Go to main content

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

Exit Print View

Updated: Wednesday, February 9, 2022
 
 

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)

OASIS PKCS#11 specification

https://www.oasis-open.org/committees/pkcs11/

History

The pkcs11_kmip provider was added to Oracle Solaris in Solaris 11.3.17.