kmscfg(1M) System Administration Commands kmscfg(1M)NAMEkmscfg - configure the PKCS#11 KMS provider
SYNOPSISkmscfg
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
DESCRIPTION
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 configura‐
tion 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/kms/$USERNAME/. 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 overriden by using the KMSTOKEN_DIR environment vari‐
able, 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
(http://docs.oracle.com).
Once the administrator has configured the KMA, the necessary identifi‐
cation information (profile name, agent ID, IP address) must be pro‐
vided to be able to run kmscfg and initialize the provider on the Ora‐
cle Solaris client.
OPTIONS
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.
-a Agent_ID
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.
-d Discovery_Freq
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 10.
-f Failover_Limit
The number of times communications to the KMA can fail before the
client gives up. If not specified, Failover_Limit defaults to 3.
-i Agent_Addr
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.
-p Profile_Name
A name for the profile to be used for the KMS token being config‐
ured. The profile name and the Agent ID must be the same.
-t Transaction_Timeout
Timeout period for individual KMS commands, in seconds. If not
specified, this value defaults to 10.
EXIT STATUS
After completing the requested operation, kmscfg exits with one of the
following status values.
0
Successful termination.
1
Failure. The requested operation could not be completed.
FILES
/var/kms/$USERNAME
Default KMS token configuration directory.
${KMSTOKEN_DIR}
Alternate KMS token configuration directory.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │/system/library/secu‐ │
│ │rity/crypto/pkcs11_kms │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Volatile │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOpktool(1), attributes(5), pkcs11_kms(5)
Oracle Key Manager Administration Guide (http://docs.oracle.com)
NOTES
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 mem‐
bers 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.
SunOS 5.10 3 May 2011 kmscfg(1M)
