pkcs11_kms

- RSA PKCS#11 provider for the Oracle Key Manager

Synopsis

/usr/lib/security/pkcs11_kms.so

/usr/lib/security/64/pkcs11_kms.so

Description

The pkcs11_kms.so object implements the RSA Security Inc. PKCS#11 Cryptographic Token Interface (Cryptoki), v2.20, specification using the Oracle Key Manager (OKM) KMS agent protocol to talk to an Oracle Key Manager appliance (KMA). This provider implements the PKCS#11 specification and communicates to a remote OKM using the (private) KMS client protocol.

The following PKCS#11 mechanisms are supported in this provider: CKM_AES_KEY_GEN, CKM_AES_CBC_PAD, and CKM_AES_CBC.

The following PKCS#11 interfaces are supported by this provider:

C_Initialize
C_Finalize
C_GetInfo
C_GetAttributeValue
C_SetAttributeValue
C_GetFunctionList
C_GetSlotList
C_GetSlotInfo
C_GetTokenInfo
C_GetMechanismList
C_GetMechanismInfo
C_InitToken
C_SetPIN
C_Login
C_Logout
C_FindObjectsInit/C_FindObjects/C_FindObjectsFinal
C_GenerateKey
C_EncryptInit/C_Encrypt/C_EncryptFinal
C_DecryptInit/C_Decrypt/C_DecryptFinal
C_DestroyObject
C_OpenSession
C_CloseSession
C_CloseAllSessions
C_GetSessionInfo
C_CreateObject
C_CopyObject
C_GetObjectSize
C_EncryptUpdate
C_DecryptUpdate

All other functions return CKR_FUNCTION_NOT_SUPPORTED when called.

Prerequisites

The pkcs11_kms provider can only be used on a system that has access to an OKM. The OKM administrator must configure a an agent ID for each user (or application) that is accessing the OKM. This is done through the OKM utilities that are part of the OKM administrative tools and are not bundled in Oracle Solaris.

Once the OKM administrator has configured the KMA for use and communicated the parameters to the client, that is, an Oracle Solaris user or application, the Oracle Solaris PKCS#11 KMS provider can be initialized for use.

Initializing the KMS provider is done through the use of the kmscfg(1M) utility. At a minimum, kmscfg requires the user to enter the name of a profile, the OKM Agent ID, the initial password used to secure the profile, and the IP address of the KMA in order to initialize the local provider configuration files for further use. See the kmscfg(1M) manual page for details.

Once kmscfg has been run and the local token namespace has been configured, the user can then initialize the token for use. Initializing the token is done using the pktool(1) command as follows:

$ pktool inittoken currlabel=KMS

The user has to supply the default SO (security officer) PIN before being able to initialize the KMS provider for use. The default SO PIN is whatever was used by the OKM administrator when initially setting up the OKM Agent. The user initializing the token must know this passphrase in order to initialize the provider.

Once the provider is initialized, the user PIN can be changed from the default values. Again, pktool(1) is used to change the PIN value.

Use the following command to change the local PIN:

$ pktool setpin token=KMS

The PIN provided for the pktool setpin operation or by calling C_Login() and C_SetPIN() functions can be any string of characters with a length between 1 and 256 and no embedded nulls.

Accessing the Token

After a user initializes their token, they can begin using it with pktool(1), decrypt(1), encrypt(1), or by writing PKCS11 applications and specifying the KMS token.

Examples

Example 1 Creating a Key on an Oracle Key Manager

The following command creates a key on an Oracle Key Manager:

$ pktool genkey token=KMS label=mykey1 keytype=aes keylen=256

Example 2 Encrypting a File Using a Key from an Oracle Key Manager

The following command encrypts a file using a key from an Oracle Key Manager:

$ encrypt -a aes -K mykey1 -T KMS -i input.txt -o output.enc

Example 3 Decrypting a File Using a Key From an Oracle Key Manager

The following command decrypts a file using a key from an Oracle Key Manger:

$ decrypt -a aes -K mykey1 -T KMS -i output.enc -o output.txt

Attributes

See attributes(5) for a description of the following attributes:

Exceptions to MT-Safe attribute are documented in section 6.6.2 of RSA PKCS#11 v2.20.

See Also

decrypt(1), encrypt(1), pktool(1), cryptoadm(1M), kmscfg(1M), libpkcs11(3LIB), attributes(5)

KMS 2.2: Administration Guide

Oracle Key Manager (OKM) Administration Guide

Notes

pkcs11_kms.so uses a private directory for holding configuration files and other data needed to initialize the connection to a KMA. The private directory is local to the host on which it was first created. By default, the KMS token directory space is in /var/user/$USERNAME/kms. The default KMS directory can be overridden by setting the KMSTOKEN_DIR environment variable prior to using the kmscfg(1M), decrypt(1), encrypt(1), and pktool(1) commands.

PKCS#11 clients require that Oracle Key Manager Software Version 2.4 be installed.

If PKCS#11 clients use the same Agent ID from multiple systems, that agent should be created without the One Time Passphrase flag set. This option is not be available in OKM clusters with some members running versions of the OKM software prior to 2.4. Refer to theOracle Key Manager (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 fail with a CKR_PIN_INCORRECT error. Refer to theOracle Key Manager (OKM) Administration Guide for assistance in assigning key groups to agents.