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.
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
The following command creates a key on an Oracle Key Manager:
$ pktool genkey token=KMS label=mykey1 keytype=aes keylen=256Example 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.encExample 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
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.
KMS 2.2: Administration Guide
Oracle Key Manager (OKM) Administration Guide
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.