pkcs11_kms(5) Standards, Environments, and Macros pkcs11_kms(5)NAMEpkcs11_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 Cryp‐
tographic 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 specifi‐
cation 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 communi‐
cated 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 initial‐
ize 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 config‐
ured, 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
Manager:
$ decrypt -a aes -K mykey1 -T KMS -i output.enc -o output.txt
ATTRIBUTES
See attributes(5) for a description of the following attributes:
┌─────────────────────────────┬────────────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼────────────────────────────────────┤
│Availability │/system/library/secu‐ │
│ │rity/crypto/pkcs11_kms │
├─────────────────────────────┼────────────────────────────────────┤
│Interface Stability │Committed │
├─────────────────────────────┼────────────────────────────────────┤
│MT-Level │MT-Safe with Exceptions. See below. │
├─────────────────────────────┼────────────────────────────────────┤
│Standard │PKCS#11 v2.20 │
└─────────────────────────────┴────────────────────────────────────┘
Exceptions to MT-Safe attribute are documented in section 6.6.2 of RSA
PKCS#11 v2.20.
SEE ALSOdecrypt(1), encrypt(1), pktool(1), cryptoadm(1M), kmscfg(1M), libp‐
kcs11(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 pri‐
vate 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.
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 Man‐
ager (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 assis‐
tance in assigning key groups to agents.
SunOS 5.10 12 May 2011 pkcs11_kms(5)
