kmscfg - configure the PKCS#11 KMS provider
kmscfg
kmscfg -p[rofile] Profile_Name
kmscfg -a[gent] Agent_ID
kmscfg -i[paddr] Agent_Address
kmscfg -t[imeout] Transaction_Timeout
kmscfg -f[ailover] Failover_Limit
kmscfg -d[iscovery] Discovery_Freq
The kmscfg command is used to initialize the PKCS#11 KMS provider (pkcs11_kms) for use with the Solaris Cryptographic Framework. In order for the KMS provider to communicate with the Oracle Key Manager (OKM), it must have some configuration information available. This configuration data contains information such as the name of the profile to be used, the name of the OKM Agent, the IP address of an OKM appliance (KMA) and some other parameters (see SYNOPSIS).
By default, kmscfg stores the configuration information in /var/user/$USERNAME/kms. This directory will be created if it is not already present. If the configuration is already detected, the user will be given the option to override the existing data. The default location can be overridden by using the KMSTOKEN_DIR environment variable, which must be set prior to invoking kmscfg.
Prior to running kmscfg, the OKM administrator must have performed the required initialization and configuration steps on the appliance itself to setup the individual Profiles and Agents that PKCS11 KMS consumers will use. The instructions for configuring these profiles are available in the Oracle Key Manager Administration Guide on the Oracle website (https://docs.oracle.com/).
Once the administrator has configured the KMA, the necessary identification information (profile name, agent ID, IP address) must be provided to be able to run kmscfg and initialize the provider on the Oracle Solaris client.
The options listed below are supported. Note that, if the profile, agent id, or KMA address are not specified on the command line, kmscfg prompts you to provide these items.
The user agent ID as configured on the OKM to be used for the KMS token being configured. It is not unusual for the Profile and Agent ID to be the same, for example, MyAgent.
Frequency in seconds with which the client will try to discover the availability of other KMAs in an OKM cluster. If not specified, Discovery_Freq defaults to 600 seconds (10 minutes).
The number of times communications to the KMA can fail before the client gives up. If not specified, Failover_Limit defaults to 3.
Address of the KMA. This can be an IPv4 address (xxx.xxx.xxx.xxx) or an IPv6 address. A fully qualified host name can also be used, as long as that name can be resolved by the name service configured on the client. If an OKM cluster is being used, the address of any member of the cluster can be specified.
A name for the profile to be used for the KMS token being configured. Typically, the profile name and the Agent ID will be the same, though they are not required to be.
Timeout period for individual KMS commands, in seconds. If not specified, this value defaults to 10.
KMS connection timeout is calculated as one fourth of the value of Transaction_Timeout for values greater than or equal to 8, lower values default to 1 second.
After completing the requested operation, kmscfg exits with one of the following status values.
Successful termination.
Failure. The requested operation could not be completed.
Default KMS token configuration directory.
Alternate KMS token configuration directory.
See attributes(7) for descriptions of the following attributes:
|
pktool(1), attributes(7), pkcs11_kms(7)
Oracle Key Manager Administration Guide (https://docs.oracle.com/)
PKCS#11 clients require Oracle Key Manager Software Version 2.4 be installed on the OKM.
If PKCS#11 clients will use the same Agent ID from multiple systems, that agent should be created without the “One Time Passphrase” flag set. This option will not be available in OKM clusters with some members running versions of the OKM software prior to 2.4. Please refer to the OKM Administration Guide for assistance in creating Agents.
OKM Agents must have a Default Key Group assigned prior to being used to create keys with a PKCS#11 client. If a Default Key Group is not assigned to the Agent, operations will fail with a CKR_PIN_INCORRECT error. Please refer to the OKM Administration Guide for assistance in assigning key groups to agents.