Provided by: opencryptoki_3.25.0+dfsg-0ubuntu1_amd64 
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 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.
SEE ALSO
p11kmip.conf(5)
3.25.0 August 2023 P11KMIP(1)