Go to main content

man pages section 7: Standards, Environments, Macros, Character Sets, and Miscellany

Exit Print View

Updated: Wednesday, August 8, 2018
 
 

pkcs11_kmip (7)

Name

pkcs11_kmip - RSA PKCS#11 provider for the KMIP server

Synopsis

/usr/lib/security/pkcs11_kmip.so
/usr/lib/security/64/pkcs11_kmip.so

Description

The pkcs11_kmip.so object implements the RSA Security Inc. PKCS#11 Cryptographic Token Interface (Cryptoki), v2.20 specification by using the Key Management Interoperability Protocol (KMIP) to communicate to a KMIP server. The following PKCS#11 mechanisms are supported in this provider:

CKM_AES_KEY_GEN
CKM_AES_CBC
CKM_AES_CBC_PAD

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

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

The pkcs11_kmip provider supports multiple slots. Each slot accommodates a single KMIP server group. That is, a group of KMIP servers represents a token plugged into a PKCS#11 slot.

KMIP PKCS#11 token configuration consists of two parts, the pkcs11_kmip and the libkmip specific part. The configuration storage is either file based for user private configuration or smf based (shared system wide defaults). For more information, see the smf(7) man page.

Before initializing the pkcs11_kmip provider, users are first required to configure a KMIP server group with the kmipcfg command. For more information, see the kmipcfg(8) man page.

Private KMIP client configuration

kmipcfg creates the configuration files in the respective KMIP token directory. This step provides the configuration material (including TLS credentials) to establish connection to a KMIP server. One or more server groups can be configured for a PKCS#11 client. For more information, see the kmipcfg(8) man page.

The default location of the KMIP token directory is /var/user/$USERNAME/kmip. If set, the environment variable $KMIPTOKEN_DIR overrides the default location. Each of the subdirectories under this KMIP token directory represents a server group and it keeps the configuration material as needed by a KMIP client to connect to a KMIP server.

Shared KMIP client configuration

The shared configuration of the KMIP client components is stored in the service management framework. For more information, see the smf(7) man page. Rules for accessing the configuration and its modification are determined by the security framework of SMF. For more information, see the smf_security(7) man page. KMIP client component specific authorizations and profiles are preconfigured in the RBAC framework and used in the respective service instance manifest to control the allowed operations.

The shared KMIP client configuration is represented by the "Default KMIP token" server group and token. kmipcfg is used to update configuration parameters.

Service instances and authorization profiles: The following rbac profiles are defined for the top most KMIP client service instance, svc:/system/pkcs11:kmip.

  
       +----------------------------------------------------+-------------+
       | PROFILE NAME                                       | ACCESS TYPE |
       +----------------------------------------------------+-------------+
       | PKCS11 Default KMIP Token User                     | read-only   |
       +----------------------------------------------------+-------------+
       | PKCS11 Default KMIP Token Administrator            | read-write  |
       +----------------------------------------------------+-------------+
       | PKCS11 Default KMIP Token Service Instance Control | read-write  |
       |                                                    | + instance  |
       |                                                    | management  |
       +----------------------------------------------------+-------------+

CONFIGURATION

A user's private KMIP token is initialized using the kmipcfg command. For example, to create a server group named KMIP_server:

# kmipcfg create -o server_list=kmip-server.example.com:5696\ 
            -o client_p12=kmip-server.p12 KMIP_server

After a private KMIP token is initialized and configured by the kmipcfg create command, the name of the server group can be changed by the pktool inittoken command:

# pktool inittoken slotid=3 currlabel=KMIP_server\ 
            newlabel=KMIP_newserver

For an initialized private KMIP token, the passphrase associated with the PKCS#12 bundle for the respective server group can be changed by the pktool setpin command:

# pktool setpin keystore=pkcs11 token=KMIP_server

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

The shared KMIP token is never created by the kmipcfg create command. The token is preconfigured automatically during the pkcs11_kmip package installation and only the existence of an association between user and the "Default KMIP token" specific rbac authorizations determines, whether the user can use the token.

To set the "Default KMIP token" parameters use kmipcfg set command.

# kmipcfg set -o server_list="kmip-server.example.com:5696"\ 
             -o cred_source_type=raw -o cert=/tmp/cert.pem\ 
             -o private_key=/tmp/key.pem -o ca_cert=/tmp/ca_cert.pem\ 
             "Default KMIP token"

If at least cert and private_key parameters, or p12_bundle are successfully set, the respective token is marked with "Protected authentication path" flag, and allows for PIN-less access. The C_Login() function call is still required, however, the pPin argument is set to NULL_PTR. Setting the parameters also initializes the "Default KMIP token" and no further token initialization is needed.

Return Values

The return values for each of the implemented functions are defined and listed in the RSA PKCS#11 v2.20 specification.

All unimplemented functions return CKR_FUNCTION_NOT_SUPPORTED when called.

Files

/var/user/$USERNAME/kmip

User's default KMIP token directory

$KMIPTOKEN_DIR

Alternate location for KMIP token directory

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
MT-Safe with exceptions. For more information, see section 6.6.2 of RSA PKCS#11 v2.20
Standard
PKCS#11 v2.20

See Also

pktool(1), libpkcs11(3LIB), attributes(7), cryptoadm(8), kmipcfg(8)