KMIP CLIENT AUTHENTICATION¶

KMIP authenticates the users with the client certificate exchanged during TLS handshake. Thus, the client must generate a private RSA or EC key and a client certificate. The client certificate must be registered with the KMIP server. This is a KMIP server product-specific out-of-band process, which is not described here. The client certificate can be a self-signed certificate or a CA-signed certificate. In a production environment, use a CA-signed certificate.

The client private key identifies the client to the KMIP server, and thus must be kept secret. If the client private key gets stolen by an attacker then the attacker can identify itself at the KMIP server and thus gets access to the keys stored in the KMIP server.

USING A CLEAR CLIENT KEY¶

You can generate the client private key with OpenSSL command line tools. In this case, the private key is a clear key stored in a PEM file. For security reasons, store the client private key in a password-protected PEM file. See an example on how to create a password-protected client key and a self-signed certificate using OpenSSL commands:

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 \
-out '/path_to_client_key/client.key' -pass stdin \
-aes-256-cbc

If you want to generate an EC key instead, use -algorithm EC and -pkeyopt ec_paramgen_curve:<curve-name>. Create a self-signed certificate with the just generated client key as follows:

openssl req -x509 -key '/path_to_client_key/client.key' \
-out '/path_to_client_certificate/selfsigned_client.crt' \
-nodes -days 3650 \
-subj '/CN=www.mydom.com/O=My Company Name LTD./C=US'

When using a password-protected client key PEM file, then you are prompted for the PEM password. You are also prompted for further information for the certificate to create, unless these details are supplied via the OpenSSL config file. Refer to the man page of the openssl req command for further details.

If you want to generate a CA-signed certificate instead, omit the -x509 option. Thus, the command generates a certificate signing request instead, that you pass to the CA. With this request, you let the CA sign the certificate and issue a CA-signed certificate for you.

USING AN HSM-PROTECTED CLIENT KEY¶

A more secure way to protect the client private key is to generate and store the client key inside a PKCS#11 token. If a secure key token, such as a CCA or EP11 token, is used then the client private key is HSM protected and can not be stolen. This requires the use of a PKCS#11 OpenSSL provider (with OpenSSL 3.0.0 or later), that is, the pkcs11-provider from https://github.com/latchset/pkcs11-provider. The PKCS#11 provider must be installed and configured properly to allow access to openCryptoki. Use an OpenSSL configuration file similar to the following:

[openssl_init]
providers = provider_sect

[provider_sect]
default = default_sect
pkcs11 = pkcs11_sect

[default_sect]
activate = 1

[pkcs11_sect]
pkcs11-module-path = /path/to/libopencryptoki.so
activate = 1

Generate an RSA client key pair in a PKCS#11 token:

p11sak generate-key rsa 2048 --label '<name-of-client-key>' --slot <n>

If you want to generate an EC key instead, use:

p11sak generate-key EC <curve-name> --label '<name-of-client-key>' --slot <n>

Then export the private client key as a URI-PEM file. A URI-PEM file contains a PKCS#11 URI referencing the key in the PKCS#11 token, but no key material. By default, the PKCS#11 URI does not contain the PKCS#11 user PIN. Refer to the man page of p11sak(1) and option --uri-pem for details about how to include the PKCS#11 user PIN or a PIN source into the URI.

p11sak export-key --label '<name-of-client.key>:prv' --uri-pem \
--file '/path_to_client_key/client.key' \
--slot <n>>

With that private client key as URI-PEM file you can create a self-signed certificate using the following OpenSSL command:

openssl req -x509 -key '/path_to_client_key/client.key' \
-out '/path_to_client_certificate/selfsigned_client.crt' \
-nodes -days 3650 \
-subj '/CN=www.mydom.com/O=My Company Name LTD./C=US'

You are prompted for the PKCS#11 user PIN, unless the user PIN is contained in the PKCS#11 URI. You are also prompted for further information for the certificate to create, unless these details are supplied via the OpenSSL config file. Refer to the man page of the openssl req command for further details.

If you want to generate a CA-signed certificate instead, omit the -x509 option. Thus, the command generates a certificate signing request instead, that you pass to the CA. With this request, you let the CA sign the certificate and issue a CA-signed certificate for you.

Instead of using an URI-PEM file, you can also use the PKCS#11 URI directly. Use the p11sak list-key command with the --long option to display the PKCS#11 URI of the client private key object. Then specify this URI as-is at the -key option of the openssl req command from above:

openssl req -x509 -key 'pkcs11:....;type=private' \
-out '/path_to_client_certificate/selfsigned_client.crt' \
-nodes -days 3650 \
-subj '/CN=www.mydom.com/O=My Company Name LTD./C=US'

There is no need to export the client private key as URI-PEM file in this case.

USING THE CLIENT KEY AND CERTIFICATE WITH P11KMIP¶

Use the private client key as URI-PEM ('/path_to_client_key/client.key') or as PKCS#11 URI ('pkcs11:....;type=private') and the client certificate ('/path_to_client_certificate/selfsigned_client.crt') with the p11kmip commands described below. You can specify the client key and client certificate using options --kmip-client-key and --kmip-client-cert, or in the /etc/opencryptoki/p11kmip.conf configuration file, or via environment variables.

When using a URI-PEM file, or a password-protected PEM file as client key, then you are prompted for the PKCS#11 user PIN or the PEM password when the p11kmip tool reads the client key PEM file, unless the PEM password is specified using the --pem-password option. The prompt looks like this:

Please enter PEM password for '/path_to_client_key/client.key':

Note that the prompt message is the same when using a URI-PEM file, and it is prompting for the PKCS#11 user PIN. For a URI-PEM file, the PEM password is the PKCS#11 user PIN required to access the PKCS#11 token that contains the key the URI is referring to.

If you specify a PKCS#11 URI directly as client private key, then you are explicitely prompted for the PKCS#11 user PIN for the specified URI.

Importing target keys¶

p11kmip import-key|import|imp --targkey-label|-t TARGKEY-LABEL --wrapkey-label|-w WRAPKEY-LABEL [--unwrapkey-label|-u UNWRAPKEY-LABEL] [--send-wrapkey] [--targkey-attrs TARGKEY-ATTRS] [--targkey-id ID] [--gen-targkey] [--targkey-length LENGTH] [OPTIONS]

Use the import-key command to import a target key located on a KMIP server to a PKCS #11 token repository. Importing a key from a KMIP server requires a wrapping key present on the server with its corresponding unwrapping key present in a local PKCSCurrently RSA is supported for wrapping and unwrapping keys and AES is supported for target keys.

The --targkey-label|-t TARGKEY-LABEL option specifies the KMIP name attribute of the target key to be imported. Once imported into the PKCS #11 token repository, the CKA_LABEL attribute of the target key will be set to the same value as TARGKEY-LABEL. The --wrapkey-label|-w WRAPKEY-LABEL option specifies the KMIP name attribute of the key to be used for wrapping. This wrapping key must already be present on the KMIP server, unless the --send-wrapkey option is specified.

The imported key will be unwrapped using a corresponding unwrapping key located in the PKCS #11 token repository with a CKA_LABEL attribute value that is the same as WRAPKEY-LABEL , unless the --unwrapkey-label | -u UNWRAPKEY-LABEL option identifies a different private key instead.

When the --send-wrapkey option is specified, the --wrapkey-label|-w WRAPKEY-LABEL option will instead be used to identify a public key located in the PKCS #11 token repository, with a CKA_LABEL attribute value that is the same as specified by WRAPKEY-LABEL. This public key is sent and registered on the KMIP server with a KMIP name specified by --wrapkey-label. The public key will then be used for wrapping.

After the import operation has been completed successfully, information will be displayed about the keys involved. This includes the CKA_LABEL attribute values of the imported target key and wrapping key, the KMIP UID attributes of both keys, and a SHA-256 digest of the imported target key from both the KMIP server and the PKCS #11 token repository.

Example:
Target Key
PKCS#11 Label...TARGET_KEY_LABEL
PKCS#11 Digest..FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
KMIP UID........TARGET_KEY_UUID
KMIP Digest.....AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Wrapping Key
PKCS#11 Label...WRAPPING_KEY_LABEL
KMIP UID........WRAPPING_KEY_UUID

The --targkey-attrs TARGKEY-ATTRS option can be used to set the boolean attributes of the imported target key (see below for detailed description of the attributes). The --targkey-id ID option may be used to set the value of the CKA_ID attribute of the target key.

When the --gen-targkey option is specified, the target key will first be generated on the KMIP server. In this case, the value of the --targkey-label|-t TARGKEY-LABEL option will be used as the KMIP name attribute of the generated key. Currently, only AES symmetric keys may be generated in this way.

The --targkey-length LENGTH option may be used to specify the length of the generated with the --gen-targkey option, and is only valid when specified with that option. LENGTH must be one of 128, 192, or 256. The default is 256.

See below for a detailed description of OPTIONS. The --help|-h option will also show the arguments and options available.

Exporting target keys¶

p11kmip export-key|export|exp --targkey-label|-t TARGKEY-LABEL --wrapkey-label|-w WRAPKEY-LABEL [--retr-wrapkey] [--wrapkey-attrs WRAPKEY-ATTRS] [--wrapkey-id ID] [OPTIONS]

Use the export-key command to export a target key located in a PKCS #11 token repository to a KMIP server. Exporting a key from a PKCS #11 slot to a KMIP server requires an unwrapping key to be present on the server with a corresponding wrapping key present in the PKCS #11 slot. Currently only RSA is supported for wrapping and unwrapping keys and AES for target keys.

The --targkey-label|-t TARGKEY-LABEL option specifies the CKA_LABEL attribute value of the target key to be exported. Once exported to the KMIP server, the KMIP name attribute of the target key will be set to the same value as TARGKEY-LABEL. The --wrapkey-label|-w WRAPKEY-LABEL option species the CKA_LABEL attribute value of key to be used for wrapping the exported key. The wrapping key must already be present in PKCS #11 token repository, unless the --retr-wrapkey option is specified.

The exported key will be unwrapped corresponding unwrapping key located on the KMIP server with a KMIP name attribute that is the same as WRAPKEY-LABEL

When the --retr-wrapkey option is specified, the --wrapkey-label|-w WRAPKEY-LABEL option will instead be used to identify a wrapping key located on the KMIP server with a KMIP name attribute that is the same as WRAPKEY-LABEL. This wrapping key will be retrieved from the KMIP server and imported into the PKCS #11 token repository, with a CKA_LABEL attribute value of WRAPKEY-LABEL , and used to wrap the exported key. When the wrapping key is being retrieved from the KMIP server, the --wrapkey-attrs WRAPKEY-ATTRS option can be used to set the boolean attributes of the retrieved wrapping key (see below for detailed description of the attributes). The --wrapkey-id ID option may be used to set the value of the CKA_ID attribute of the public key.

After the export operation has been completed successfully, information will be displayed about the keys involved. This includes the CKA_LABEL attribute values of the exported target key and public key, the KMIP UID attributes of both keys, and a SHA-256 digest of the exported target key from both the KMIP server and the PKCS #11 token repository.

Example:
Target Key
PKCS#11 Label...TARGET_KEY_LABEL
PKCS#11 Digest..FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
KMIP UID........TARGET_KEY_UUID
KMIP Digest.....AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Wrapping Key
PKCS#11 Label...WRAPPING_KEY_LABEL
KMIP UID........WRAPPING_KEY_UUID

See below for a detailed description of OPTIONS. The --help|-h option will also show the arguments and options available.

/etc/opencryptoki/p11kmip.conf¶

This configuration file can be used to specify persistent settings to be used by the p11kmip for connections to KMIP servers and interactions with PKCS #11 token repositories. A custom file path can be set with environment variable P11KMIP_DEFAULT_CONF_FILE. If the environment variable is not set, then the global /etc/opencryptoki/p11kmip.conf config file is read. If this file is unavailable, an error message is displayed.

P11KMIP_DEFAULT_CONF_FILE¶

A custom path for the p11kmip.conf config file can be set with the environment variable P11KMIP_DEFAULT_CONF_FILE. If the environment variable is not set, then the global /etc/opencryptoki/p11kmip.conf config file is read. If this file is unavailable, an error message is displayed.

PKCS11_USER_PIN¶

The PKCS #11 token user PIN can be specified via the environment variable PKCS11_USER_PIN. If this environment variable is not set, and the option --pin|-p PIN is not specified, p11kmip will prompt for the token user PIN interactively.

PKCS11_SLOT_ID¶

The PKCS #11 token slot number can be specified via the environment variable PKCS11_SLOT_ID. If this environment variable is not set, and the option --pin|-p PIN is not specified, the value will be read from the p11kmip.conf configuration file.

PKCSLIB¶

An alternative PKCS #11 library name can be specified with the PKCSLIB environment variable. If this environment variable is not set, then the default PKCS #11 library libopencryptoki.so is used.

KMIP_HOSTNAME¶

The hostname of the KMIP server with which to connect can be specified using the KMIP_HOSTNAME environment variable. If this environment variable is not set, and the option --kmip-host OSTNAME is not specified, the value will be read from the p11kmip.conf configuration file.

KMIP_CLIENT_CERT¶

The path to the TLS client certificate to use for the KMIP connection can be specified using the KMIP_CLIENT_CERT environment variable. If this environment variable is not set, and the option --kmip-client-cert ERT-PATH

KMIP_CLIENT_KEY¶

The path to the TLS client key to use for the KMIP connection can be specified using the KMIP_CLIENT_KEY environment variable. If this environment variable is not set, and the option --kmip-client-key KEY-PATH

KMIP_PEM_PASSWORD¶

The PEM file used for the TLS client key may be password protected. The PEM password can be specified via the environment variable KMIP_PEM_PASSWORD. If this environment variable is not set, and the option --pem-password EM-PASSWORD is not specified, p11kmip will prompt for the PEM password interactively.

CKR_ARGUMENTS_BAD (0x00000007):¶

An argument, option or keyword is not valid.

CKR_DATA_INVALID (0x00000020):¶

The p11kmip.conf cannot be parsed or its syntax is invalid.

CKR_MECHANISM_INVALID (0x00000070):¶

The token does not support the key generation mechanism for the specified key type.

CKR_KEY_SIZE_RANGE (0x00000062):¶

The token does not support the key size for the specified key type.

CKR_HOST_MEMORY (0x00000002):¶

Allocating memory has failed.

CKR_FUNCTION_FAILED (0x00000006):¶

A subfunction or library call has failed.