pkcs11_kms

- RSA PKCS#11 provider for the Key Management Server

Synopsis

/usr/lib/security/pkcs11_kms.so

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

Description

The pkcs11_kms.so object implements the RSA PKCS#11 v2.20 specification using the Key Management Server (KMS) client protocols to talk to a KMS secure key storage appliance. This provider implements the PKCS#11 specification and communicates to a remote KMS 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

All other functions return CKR_FUNCTION_NOT_SUPPORTED when called.

Prerequisites

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

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

Initializing the KMS is done through the use of the kmscfg(1M) utility. At a minimum, the kmscfg requires the user to enter the name of the KMS profile, the name of the KMS Agent, the initial password used to secure the profile, and the IP address of the KMS 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 KMS administrator when initially setting up the KMS profile. 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 in the KMS

The following command creates a key in the KMS:

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

Example 2 Encrypting a File Using a Key from the KMS

The following command encrypts a file using a key from the KMS:

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

Example 3 Decrypting a File Using a Key From the KMS

The following command decrypts a file using a key from the KMS:

$ 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.5.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

Notes

pkcs11_kms.so uses a private directory for holding configuration files and other data needed to initialize the connection to the KMS. The private directory is local to the host on which it was first created. By default, the KMS token directory space is in /var/kms/$USERNAME. 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.