P11KMIP(1)

NAME
p11kmip - Transfer cryptographic keys between PKCS #11 and KMIP.

SYNOPSIS
p11kmip command [OPTIONS]

p11kmip --help|-h
p11kmip --version|-v

DESCRIPTION
The p11kmip tool can be used to transfer target keys between a PKCS #11 key repository and a KMIP server. Target keys may be imported or exported, and are wrapped using public-key cryptography during transit. Keys used for wrapping may also be sent and received. Only AES keys are supported as target keys, and only RSA is supported for key wrapping.

  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.

COMMANDS
The p11kmip tool supports commands to import and export keys between a PKCS #11 token repository and KMIP server.

  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 PKCS Currently 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.

OPTIONS

--wrapkey-attrs-a WRAPKEY-ATTRS|--targkey-attrs-a TARGKEY-ATTRS
    For the export-key command, specify the PKCS #11 boolean attributes that are to be set for the retrieved wrapping key. For the import-key , specify the PKCS #11 boolean attributes that are to be set for the imported target key.

    Note: Not all boolean attributes are applicable to all key types and/or commands and will be silently ignored if not applicable.

    The respective attributes are set to TRUE when the corresponding letter is specified in uppercase, or FALSE when the corresponding letter is specified in lowercase. Attributes (except CKA_TOKEN and CKA_SENSITIVE, see below) that are not specified get the default value as defined by the PKCS #11 standard or the used PKCS #11 token implementation when generating keys, or are not updated when setting the attributes of an existing key.

    Attribute CKA_TOKEN is always set to TRUE for imported symmetric keys, and is set to TRUE by default for public keys. This is because session keys are not persistent, and thus would no longer exist after the session that the p11kmip tool has opened is closed when it exists. For public keys only, this can be overridden by specifying the respective uppercase or lowercase letter for the CKA_TOKEN attribute in the attribute string, as desired.

    When importing or recieving a key with the p11kmip tool, attribute CKA_SENSITIVE defaults to TRUE for symmetric keys. However, this can be overridden by specifying the respective uppercase or lowercase letter for the CKA_SENSITIVE attribute in the attribute string, as desired.

    Note: The default setting for the CKA_SENSITIVE attribute is defined by the p11kmip tool, and might be different from the default setting that would be chosen by the used PKCS #11 implementation.

    The following letters are associated with the respective CK_ATTRIBUTE:

    •   H - CKA_TOKEN

    •   P - CKA_PRIVATE

    •   M - CKA_MODIFIABLE

    •   B - CKA_COPYABLE

    •   Y - CKA_DESTROYABLE

    •   S - CKA_SENSITIVE

    •   X - CKA_EXTRACTABLE

    •   K - CKA_IBM_PROTKEY_EXTRACTABLE (IBM specific, not all tokens support this)

    For multiple attributes, specify a set of these letters without any blanks in between, e. g. 'MlD'. An uppercase letter means TRUE, while a lowercase letter means FALSE. From Example above, 'MbS' corresponds to: CKA_MODIFIABLE=TRUE, CKA_COPYABLE=FALSE, CKA_SENSITIVE=TRUE.

--slot|-s SLOT
    Specifies the slot number of the PKCS #11 token to use.

    Alternatively, the slot number may be specified using the PKCS11_SLOT_ID environment variable or the p11kmip.conf configuration file. See p11kmip.conf(5) for more details about using the configuration file. When one or more of these are set, the option takes highest priority, the environment variable second highest, and the configuration file least priority. When none are set, an error occurs.

--pin|-p PIN
    Specifies the PKCS #11 token user PIN to login with.

    Alternatively, the PKCS11_USER_PIN environment variable may be used to provide the token user PIN. If neither this option is specified nor the environment variable is set, the user is prompted for the PIN.

--force-pin-prompt
    Force the p11kmip tool to prompt for the token user PIN (regardless of if it has been specified elsewhere)

--kmip-host HOSTNAME
    The hostname of the KMIP server with which to connect.

    Alternatively, the hostname may be specified using the KMIP_HOSTNAME environment variable or the p11kmip.conf configuration file. See p11kmip.conf(5) for more details about using the configuration file. When one or more of these are set, the option takes highest priority, the environment variable second highest, and the configuration file least priority. When none are set, an error occurs.

--kmip-client-cert CERT-PATH
    A path to the TLS client certificate to use for the KMIP connection.

    Alternatively, the client certificate path may be specified using the KMIP_CLIENT_CERT environment variable, or the p11kmip.conf configuration file. See p11kmip.conf(5) for more details about using the configuration file. When one or more of these are set, the option takes highest priority, the environment variable second highest, and the configuration file least priority. When none are set, an error occurs.

--kmip-client-key KEY-PATH
    A path to the TLS client private key to use for the KMIP connection.

    Alternatively, the client private key path may be specified using the KMIP_CLIENT_KEY environment variable or the p11kmip.conf configuration file. See p11kmip.conf(5) for more more details about using the configuration file. When one or more of these are set, the option takes highest priority, the environment variable second highest, and the configuration file least priority. When none are set, an error occurs.

--pem-password PEM-PASSWORD
    The password to use for the TLS client key PEM file, if it is password-protected.

    Alternatively, the PEM password may be specified using the KMIP_PEM_PASSWORD environment variable. When both are set, the option takes higher priority. When neither are set, the user is prompted for the password.

--force-pem-password-prompt
    Force the p11kmip tool to prompt for the TLS client key PEM password (regardless of if it has been specified elsewhere).

--tls-verify-hostname
    Enforce verification of the KMIP server hostname.

--tls-no-verify-certificate
    Skip verification of the KMIP server TLS certificate.

--tls-trust-server-cert
    Perform verification of the KMIP server TLS certificate, but do not prompt the user for trust of this server.

--debug|-d
    Increase debug information.

--quiet|-q
    Suppress messages.

--short|-r
    Print shortened results. Example: SECRET_KEY_LABEL:FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF SECRET_KEY_UUID:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

--help|-h
    Prints help for the usage of the p11kmip tool and/or the respective command and then exits.

--version|-v
    Prints the version of the p11kmip tool and then exits.

FILES

  /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.

ENVIRONMENT VARIABLES

  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.

EXIT STATUS
The p11kmip tool returns error codes as defined by the PKCS #11 standard, i.e. the CKR_nnn errors. On success, CKR_OK (which is zero) is returned.

The PKCS #11 error codes may originate from a PKCS #11 function called by the p11kmip tool, or from the p11kmip tool itself, like the following:

  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.

SEE ALSO
p11kmip.conf(5)
p11sak(1)
openssl-genpkey(1)
openssl-req(1)