Transferring keys between a token and a KMIP server - p11kmip utility

Edit online

Use the p11kmip tool to export keys from a token instance in a PKCS #11 slot to a KMIP server. Or use this tool to import keys from a KMIP server to a token instance. These keys used for export or import are referred to as target keys. The current version of this utility supports secret AES keys (with attribute CKA_EXTRACTABLE = TRUE) as target keys. The target keys are protected by a wrapping key during the transit and are unwrapped after the transit by a corresponding unwrapping key. The current version of this utility supports RSA asymmetric private and public key pairs for wrapping the target key during the transit (public RSA key) and for unwrapping it after the transit (private RSA key).

Description

The transfer of target keys may be appropriate in a number of use cases, for example for backing up keys used for file system encryption, or for allowing other parties to access sensitive data previously encrypted by the same key.

The connection between the p11kmip tool and a KMIP server is initiated using a TLS handshake to authenticate the p11kmip tool as a KMIP client. This process requires files containing a TLS private key and a TLS client certificate to be present on the system where the p11kmip tool is being used. The TLS client certificate used by the p11kmip tool must already be imported and trusted by the KMIP server.

Because public key cryptography is utilized to secure the target keys during transmission, the receiving party must possess a public and private key pair, and the sending party must possess the public key of this pair. Therefore, as a prerequisite to use the p11kmip utility, the key pair itself must already have been generated on the appropriate host. The p11kmip utility provides a feature for transmitting the public key (wrapping key) of an existing key pair in preparation for the transfer of the secret target key.

Create the required key pair:

On the system hosting the PKCS #11 slot, you can use the p11sak utility.
On the KMIP server, you can use an equivalent tool, for example, the IBM® Guardium® Key Lifecycle Manager.

openCryptoki architecture — Figure 1. Components involved in transferring keys between a PKCS #11 token and a KMIP server

The KMIP server sends its TLS certificate at the beginning of the connection. However, the p11kmip tool does not store it permanently on the filesystem. Instead, during the connection establishment, the p11kmip tool displays the certificate together with all details like the fingerprint to the user, and the user is prompted to decide whether to trust the certificate or not to trust it.

When a secret key is being exported from a PKCS #11 slot, any attributes relating to key usage (for example, CKA_DERIVE, CKA_ENCRYPT or CKA_DECRYPT) are translated into a KMIP cryptographic usage mask with the corresponding usages enabled and disabled. When a key is being imported, the same process is performed in the opposite direction, with the KMIP cryptographic usage mask being converted into PKCS #11 key usage attributes set to the appropriate boolean values. Also, the CKA_LABEL attribute of a PKCS #11 key object is equated to the name attribute of a KMIP key. This equivalency is also used when locating a key on the KMIP server.

The p11kmip utility provides the following sub-commands:

import-key: to transfer a secret target key from a KMIP server to a token in a PKCS #11 slot (see Importing keys).
export-key: to transfer a target key from a PKCS #11 token to a KMIP server (see Exporting keys).

Options for these sub-commands may be specified through one of the following methods:

specifying command line options (see Command line options)
using environment variables (see Environment variables for the p11kmip utility)
specifying options in a configuration file (see The configuration file - p11kmip.conf).

If the same option is specified in multiple places, command line options are given the highest level of precedence, followed by environment variables, and lastly the configuration file.

Ensure that on both sides (host of the PKCS #11 slot and KMIP server) compatible wrapping and unwrapping functions are available.

If all command options are adequately specified regarding the described hierarchy, then the conversion of key objects from the PKCS #11 format into the KMIP format and the other way round is performed transparently to the user.

If no key objects are found for transferring or wrapping or unwrapping, or if more than one object is found, the processing fails.

The configuration file - p11kmip.conf

A configuration file called p11kmip.conf is required and a default file is installed either in the default location /etc/opencryptoki/ or in the directory defined by the OCK_CONFDIR environment variable. It contains settings for the communication between both ends of the transfer.

The p11kmip.conf file is divided into two sections, the kmip section and the pkcs11 section, where the pkcs11 section contains the PKCS #11 slot ID as the only parameter and pkcs11 section contains parameters for configuring the connection and the wrapping process.

Parameters of the p11kmip.conf configuration file - kmip section

In order to interact with a KMIP server, the hostname of the server and the KMIP client certificate and key must be provided. When a connection is made, the server certificate is validated and the user is prompted to trust the certificate. The hostname of the server is not verified by default.

KMIP authenticates the users with the client certificate exchanged during TLS handshake. Thus, 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.

host: This parameter must be specified in the format hostname[:port] when using plain TLS, where hostname may be an IPv4 address, IPv6 address, or a symbolical hostname, and port may optionally be used to specify a non-standard port number. If port is not specified, 5696 is used as the default. When using HTTPS, the host parameter must be specified in the format https://hostname[:port].
tls_client_cert: This parameter must specify the path to a PEM format file containing the client certificate used for TLS authentication to the KMIP server.
wrap_key_format: This parameter specifies the format used to transmit the wrapping key, and must be one of "PKCS1", "PKCS8", or "TransparentPublicKey".
wrap_key_algorithm: This parameter specifies the algorithm used for key wrapping. Currently only "RSA" is supported.
wrap_key_size: This parameter specifies the length of the key used for wrapping. This value must match the length of the actual wrapping and unwrapping key which are provided when the tool is invoked.
wrap_padding_method: This parameter specifies padding method used during the key wrap. Currently padding methods "PKCS1.5" and "OAEP" are supported.
wrap_hashing_algorithm: This parameter specifies the hashing algorithm used by the padding method. Only the "OAEP" padding method requires a hashing algorithm for its mask generation function (MGF) to be specified. For the "OAEP" padding method, only the "SHA-1" and "SHA-256" hashing algorithms are supported. For all other padding methods this field is ignored, and may be absent.

Example:

/etc/opencryptoki/p11kmip.conf (-rw-r----- root pkcs11)
kmip {  
  host = "0.0.0.0:5696"
  tls_client_cert = "/tmp/certs/client_certificate_jack_smith.pem"    
  tls_client_key = "/tmp/certs/client_key_jack_smith.pem"
  wrap_key_format = "PKCS1"    
  wrap_key_algorithm = "RSA"
  wrap_key_size = 2048
  wrap_padding_method = "PKCS1.5"
  wrap_hashing_algorithm = "SHA-1"
}
pkcs11 {
  slot = 0
}

The parameters host, tls_client_key, tls_client_cert and slot are required unless they are specified otherwise by an environment variable or a command line option. All other parameters are set to default values if they are not specified in the p11kmip.conf configuration file. The sequence of the parameters in the configuration file can be arbitrary. A user of the p11kmip utility only needs read access to a p11kmip.conf file they wish to use.

See an example how to create the client key and certificate using an OpenSSL command. This example uses a self-signed certificate, but for your production environment you should use a CA-signed certificate.


openssl req -x509 -newkey rsa:4096 
            -keyout '/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'

Environment variables for the p11kmip utility

Certain options may be specified using environment variables:

PKCS11_USER_PIN: The User PIN for the chosen slot. See also Table 1.
PKCS11_SLOT_ID: The ID of the chosen slot where the token is plugged in.
KMIP_HOSTNAME: The hostname for the KMIP server.
KMIP_CLIENT_CERT: A path to the PEM file containing the KMIP TLS client certificate to be used for the connection to the KMIP server.
KMIP_CLIENT_KEY: A path to the PEM file containing the KMIP TLS client private key to be used for the connection to the KMIP server.
KMIP_PEM_PASSWORD: The password to be used for the KMIP client key PEM file of the KMIP TLS client, if the PEM file is password-protected.
OCK_CONFDIR: The path to a directory containing the p11kmip.conf file, if different from the default.
P11KMIP_CONF_FILE: The path to a file to be used as the configuration file, if different from the default. Takes precedence over OCK_CONFDIR.

Command line options

You can specify the following types of options together with the p11kmip command:

Common command options

--debug | -d

Increase debug information.

--quiet | -q

Suppress messages.

--short | -r

Print shortened results.

--version | -v

Display the p11kmip tool version.

--help| -h

Display help information and also show the available arguments and options.
PKCS #11-related options

--slot | -s

The number of the PKCS #11 slot (token) to use.

--pin | -p

The User PIN of the desired PKCS #11 slot.

--force-pin-prompt

Force User PIN prompt.
PKCS #11-related options syntax
In order to interact with a PKCS #11 slot, the slot number and the User PIN for the slot must be provided. If the PIN is not provided, the user is prompted for it.
KMIP-related options

--kmip-host

The hostname of the KMIP server.

--kmip-client-cert

Path to the PEM file containing the TLS client certificate for the KMIP server.

--kmip-client-key

Path to the PEM file containing the TLS client key from the KMIP server.

--pem-password

The password for the KMIP client key PEM file, if required.

--force-pem-password-prompt

Force a prompt for the client key PEM file password.

--tls-verify-hostname

Enforce verification of the KMIP server hostname.

--tls-no-verify-server-cert

Skip verification of the TLS certificate for the KMIP server.

--tls-trust-server-cert

Perform verification of the TLS certificate for the KMIP server, but do not prompt the user for trust of this server.
KMIP-related options syntax
In order to interact with a KMIP server, the hostname of the server and the KMIP client certificate and private key must be provided. When a connection is made, the server certificate is validated and the user is prompted to trust the certificate. The hostname of the server is not verified by default.

Using the p11kmip utility

The general invocation scheme of the p11kmip command line tool is:

p11kmip COMMAND [OPTIONS]

Figure 2. p11kmip syntax - General invocation scheme

where sub-command is one of:

import-key | import | imp: Used to import a target key from a KMIP server into a token in a PKCS #11 slot.
export-key | export | exp: Used to export a target key from a token in a PKCS #11 slot to a KMIP server.

and where options is one of:

Common command options
PKCS #11-related options
KMIP-related options

All options are described in Command line options.

Importing keys

Use the p11kmip import-key sub-command to import a secret target key from a KMIP server. This action requires a public key to be present on the server with its corresponding private key present in a local PKCS #11 slot.

Figure 3. p11kmip syntax - Importing keys

where:

--wrapkey-label | -w

specifies the label of the RSA public key located on the KMIP server to be used for wrapping the key to be imported. The size of the wrapping key specified by the wrapkey-label option must correspond to the wrap_key_size parameter in the configuration file.

--targkey-label | -t

specifies the KMIP name of the target key to be imported from the KMIP server. Once imported into the PKCS #11 token repository, the CKA_LABEL attribute of the secret key is set to the same value.

--targkey-attrs

is an optional list of the boolean attributes to be set for the secret key after it has been imported: P M B Y S X K. Specify a set of these letters without any blanks in between.

The boolean attributes that you can specify with this option have the following meanings:

P - CKA_PRIVATE
M - CKA_MODIFIABLE
B - CKA_COPYABLE
Y - CKA_DESTROYABLE
S - CKA_SENSITIVE
X - CKA_EXTRACTABLE
I - CKA_WRAP_WITH_TRUSTED
K - CKA_IBM_PROTKEY_EXTRACTABLE

An uppercase letter sets the corresponding attribute to CK_TRUE, a lower case letter to CK_FALSE. If an attribute is not set explicitly, its value is not changed. Not all attributes may be allowed to be changed for all key types, or to all values.

--targkey-id

is the value to be set for the CKA_ID attribute of the imported secret key (optional).

--unwrapkey-label | -u

specifies the label of the private key in the PKCS #11 slot to be used for unwrapping the target key, if different from the label of the key used for wrapping (optional).

--send-wrapkey

registers a public key from the PKCS #11 slot with the KMIP server and uses it for wrapping. In this case, the label specified by the wrapkey-label option is used to select the local public key to be sent, and the public key is registered with a name attribute value of the label on the KMIP server.

--gen-targkey

specifies that the secret key to be imported is first created on the KMIP server. Currently only AES keys are supported.

--targkey-length

is the length in bits of the target key being generated. Must be one of 128, 192, or 256. Only valid with option gen-targkey. Defaults to 256.

The imported key is unwrapped using a 2048-bit RSA private key located in the PKCS #11 token repository with a CKA_LABEL attribute value that is the same as the key specified by the wrapkey-label option, unless the unwrapkey-label option identifies a different private key instead.

When the --send-wrapkey option is specified, the --wrapkey-label option is instead 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. This public key is then used for wrapping.

Examples for importing an AES key:

p11kmip import-key --pin $PKCS11_USER_PIN 
                   --targkey-label REMOTE-TARGET-KEY --targkey-id "012345678" 
                   --targkey-attrs "sX" --wrapkey-label REMOTE-PUBLIC-KEY 
                   --unwrapkey-label LOCAL-PRVATE-KEY

p11kmip import-key --send-wrapkey --gen-targkey --pin $PKCS11_USER_PIN 
                   --targkey-label REMOTE-TARGET-KEY
                   --wrapkey-label LOCAL-PUBLIC-KEY

Exporting keys

Use the p11kmip export-key sub-command to export a target key from a token in a PKCS #11 slot to a KMIP server.

Figure 4. p11kmip syntax - Exporting keys

where:

--wrapkey-label | -w

is the label of the public key to use for key wrapping. Must exist on the KMIP server. Must also exist in the PKCS #11 repository with the same label, unless specified with option --retr-wrapkey.

--targkey-label | -t:

is the label of the secret key to be exported to the KMIP server. Must exist in the PKCS #11 repository. This label is the same as the name attribute of the exported key.

--retr-wrapkey

specifies that the public key to be used for wrapping is first retrieved from the KMIP server and stored in the PKCS #11 repository. The new key is stored using the same label as specified in the wrapkey-label option.

--wrapkey-attrs

is a list of boolean attributes to be set for the public key after it has been imported. Only compatible with the --retr-wrapkey.

The boolean attributes that you can specify with this option have the following meanings:

P - CKA_PRIVATE
M - CKA_MODIFIABLE
B - CKA_COPYABLE
Y - CKA_DESTROYABLE
S - CKA_SENSITIVE
X - CKA_EXTRACTABLE
I - CKA_WRAP_WITH_TRUSTED
K - CKA_IBM_PROTKEY_EXTRACTABLE
H - CKA_TOKEN. This attribute is included so that you can chose to make the imported wrapping key a session object rather than a token object. This is only valid for public keys.

Specify a set of these letters without any blanks in between. Restrictions on attribute values may apply.

--wrapkey-id

is the value to be set for the CKA_ID attribute of the imported wrapping key. Only compatible with the --retr-wrapkey option.

Examples for exporting an AES key

p11kmip export-key --retr-wrapkey --pin $PKCS11_USER_PIN 
                   --targkey-label LOCAL-TARGET-KEY
                   --wrapkey-label REMOTE-PUBLIC-KEY 
                   --wrapkey-id "012345678" --wrapkey-attrs "H" 


p11kmip export-key --retr-wrapkey --pin $PKCS11_USER_PIN 
                   --targkey-label LOCAL-TARGET-KEY
                   --wrapkey-label LOCAL-PUBLIC-KEY

Output format of the transfer results

When no additional flags are specified to manipulate the output format, both the import-key and export-key commands print results in the following format to standard out:

Secret Key
PKCS#11 Label...SECRET_KEY_LABEL
PKCS#11 Digest..FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
KMIP UID........SECRET_KEY_UUID
KMIP Digest.....AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Public Key
PKCS#11 Label...PUBLIC_KEY_LABEL
KMIP UID........PUBLIC_KEY_UUID

Each field is populated with its corresponding value. For example, when importing a key, the PKCS#11 Label field contains the label of the imported secret key after the command has completed, and the KMIP UID field is equal to the UID of the secret key object on the KMIP server.

The PKCS#11 Digest and KMIP Digest fields contain hexadecimal representations of the digests of both keys for comparison.

Under the Public Key section, the PKCS#11 Label field contains the label of the public key used to wrap the secret key in transit, while the KMIP UID field contains the UID of the corresponding key object on the KMIP server. If the –send-wrapkey option was specified, this would be the UID of a newly created key.

Alternatively, a user may specify the -r or –short flag to make the results more brief as shown:

SECRET_KEY_LABEL:FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
SECRET_KEY_UUID:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

Here the first line contains the PKCS #11 label of the secret key used in the operation, followed by a colon (:) as delimiter, then followed by its digest. The second line contains the KMIP UID of the secret key, then the colon (:) as delimiter, followed by its digest.

You can suppress any output using the -q or --quiet option.