p11kmip - Man Page
Transfer cryptographic keys between PKCS #11 and KMIP.
Synopsis
p11kmip command [Options]
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 recieved. Only AES keys are supported as target keys, and only RSA is supported for key wrapping.
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 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.
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 EY-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.