kmscfg

- configure the PKCS#11 KMS provider

Synopsis

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

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 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 overriden 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 (http://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.

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 600 seconds (10 minutes).

-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 configured. Typically, the profile name and the Agent ID will be the same, though they are not required to be.

-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/user/$USERNAME/kms

Default KMS token configuration directory.

${KMSTOKEN_DIR}

Alternate KMS token configuration directory.

Attributes

See attributes(5) for descriptions of the following attributes:

See Also

pktool(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 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.