Provided by: opencryptoki_3.21.0+dfsg-0ubuntu1.1_amd64 
NAME
p11sak - Manage token keys in a PKCS #11 token repository.
SYNOPSIS
p11sak command [ARGUMENTS] [OPTIONS]
p11sak --help|-h
p11sak --version|-v
DESCRIPTION
The p11sak tool can be used to manage token keys in a PKCS #11 token repository. The
utility provides a flexible key management tool to generate, list, remove, update, copy,
import, and export symmetric (DES, 3DES, generic, AES, AES-XTS) and asymmetric (RSA, DH,
DSA, EC, IBM Dilithium, IBM Kyber) keys. This tool is also capable of listing the keys
with their PKCS #11 attributes and its values (not all attributes may be displayed if a
keys is sensitive).
Note: The p11sak tool only operates on token keys (i.e. CKA_TOKEN=TRUE), but not on
session keys (CKA_TOKEN=FALSE). Token keys are stored persistently in the token's
repository, while session keys are not stored persistently, and only exist as long as the
session is alive. Thus, session keys generated or imported by the p11sak tool would not
exist anymore when the p11sak tool has exited.
COMMANDS
The p11sak tool supports various commands to generate, list, remove, update, import, and
export token keys in a PKCS #11 token repository.
Generating symmetric and asymmetric keys
p11sak generate-key|gen-key|gen KEYTYPE [ARGUMENTS] [OPTIONS]
Use the generate-key|gen-key|gen command to generate a token key of the specified KEYTYPE
with the respective ARGUMENTS and OPTIONS. Possible values for the KEYTYPE argument are:
des|3des|generic|aes|aes-xts|rsa|dh|dsa|ec|ibm-dilithium|ibm-kyber. See below for a
detailed description of the arguments and options. The --help|-h option will also show the
arguments and options available.
Generating DES/3DES keys
p11sak generate-key|gen-key|gen des|3des --slot|-s SLOTID [--pin|-p PIN]
[--force-pin-prompt] --label|-L LABEL --attr|-a ATTRS [--id|-i ID] [--help|-h]
Use the generate-key|gen-key|gen command with the des|3des KEYTYPE argument to generate a
DES or 3DES key (CKK_DES or CKK_DES3). The --label|-L LABEL option sets the CKA_LABEL
attribute of the key and the --attr|-a ATTRS option can be used to set the boolean
attributes of the key (see below for detailed description of the attributes). The --id|-i
ID option can be used to set the value of the CKA_ID attribute of the key.
Generating generic secret keys
p11sak generate-key|gen-key|gen generic KEYBITS --slot|-s SLOTID [--pin|-p PIN]
[--force-pin-prompt] --label|-L LABEL --attr|-a ATTRS [--id|-i ID] [--help|-h]
Use the generate-key|gen-key|gen generic KEYBITS command and KEYTYPE argument to generate
a generic secret key (CKK_GENERIC_SECRET) with the key size in bits as specified by the
KEYBITS argument.The --label|-L LABEL option sets the CKA_LABEL attribute of the key and
the --attr|-a ATTRS option can be used to set the boolean attributes of the key (see below
for detailed description of the attributes). The --id|-i ID option can be used to set the
value of the CKA_ID attribute of the key.
Generating AES keys
p11sak generate-key|gen-key|gen aes 128|192|256 --slot|-s SLOTID [--pin|-p PIN]
[--force-pin-prompt] --label|-L LABEL --attr|-a ATTRS [--id|-i ID] [--help|-h]
Use the generate-key|gen-key|gen aes 128|192|256 command and KEYTYPE argument to generate
a AES key (CKK_AES) with 128-, 192-, or 256-bit length, respectively. The --label|-L LABEL
option sets the CKA_LABEL attribute of the key and the --attr|-a ATTRS option can be used
to set the boolean attributes of the key (see below for detailed description of the
attributes). The --id|-i ID option can be used to set the value of the CKA_ID attribute of
the key.
Generating AES-XTS keys
p11sak generate-key|gen-key|gen aes-xts 128|256 --slot|-s SLOTID [--pin|-p PIN]
[--force-pin-prompt] --label|-L LABEL --attr|-a ATTRS [--id|-i ID] [--help|-h]
Use the generate-key|gen-key|gen aes-xts 128|256 command and KEYTYPE argument to generate
a AES-XTS key (CKK_AES_XTS) with 128- or 256-bit length, respectively. The --label|-L
LABEL option sets the CKA_LABEL attribute of the key and the --attr|-a ATTRS option can be
used to set the boolean attributes of the key (see below for detailed description of the
attributes). The --id|-i ID option can be used to set the value of the CKA_ID attribute of
the key.
Generating RSA keys
p11sak generate-key|gen-key|gen rsa 512|1024|2048|4096 [PUBL-EXP] --slot|-s SLOTID
[--pin|-p PIN] [--force-pin-prompt] --label|-L LABEL|PUB-LABEL:PRIV-LABEL --attr|-a
ATTRS|PUB-ATTRS:PRIV-ATTRS [--id|-i ID] [--help|-h]
Use the generate-key|gen-key|gen rsa 1024|2048|4096 command and KEYTYPE argument to
generate an 512-, 1024-, 2048-, or 4096-bit RSA key (CKK_RSA), respectively. The
--label|-L LABEL|PUB-LABEL:PRIV-LABEL option sets the CKA_LABEL attribute of the key and
the --attr|-a ATTRS|PUB-ATTRS:PRIV-ATTRS option can be used to set the boolean attributes
of the key (see below for detailed description of the attributes). Optionally, set
individual key attributes for public and private key separated by a colon (:). The --id|-i
ID option can be used to set the value of the CKA_ID attribute of the key. Furthermore,
the optional PUBL-EXP argument allows the user to specify the exponent used for generating
the RSA key. The default is set to 65537 according to the PKCS #11 standard.
Generating DH keys
p11sak generate-key|gen-key|gen dh GROUP|DH-PARAM-PEM-FILE [PRIV-BITS] --slot|-s SLOTID
[--pin|-p PIN] [--force-pin-prompt] --label|-L LABEL|PUB-LABEL:PRIV-LABEL --attr|-a
ATTRS|PUB-ATTRS:PRIV-ATTRS [--id|-i ID] [--help|-h]
Use the generate-key|gen-key|gen dh GROUP|DH-PARAM-PEM-FILE command and KEYTYPE argument
to generate a DH key (CKK_DH), where GROUP specifies the Diffie-Hellman FFC group name or
DH-PARAM-PEM-FILE specifies the name of a DH parameters PEM file. The following arguments
can be used for respective groups:
ffdhe2048|ffdhe3072|ffdhe4096|ffdhe6144|ffdhe8192|modp1536|modp2048|modp3072|modp4096|modp6144|modp8192
Note: Not all groups are supported by all tokens and key generation will fail when the
specified GROUP is not supported. Also, not all groups are supported by all OpenSSL
versions. If the p11sak tool is compiled against an OpenSSL version that does not support
certain groups, then those groups are not accepted for the GROUP argument.
Alternatively, specify a DH parameters PEM file as DH-PARAM-PEM-FILE argument. You can for
example generate DH parameters using the OpenSSL command line tool as follows: 'openssl
dhparam <numbits> -out <pem-file> -outform PEM'. See the OpenSSL man page for details
about this command.
The --label|-L LABEL|PUB-LABEL:PRIV-LABEL option sets the CKA_LABEL attribute of the key
and the --attr|-a ATTRS|PUB-ATTRS:PRIV-ATTRS option can be used to set the boolean
attributes of the key (see below for detailed description of the attributes). Optionally,
set individual key attributes for public and private key separated by a colon (:). The
--id|-i ID option can be used to set the value of the CKA_ID attribute of the key.
Furthermore, the optional PRIV-BITS argument allows the user to specify the size of the
private key in bits.
Generating DSA keys
p11sak generate-key|gen-key|gen dsa DSA-PARAM-PEM-FILE --slot|-s SLOTID [--pin|-p PIN]
[--force-pin-prompt] --label|-L LABEL|PUB-LABEL:PRIV-LABEL --attr|-a
ATTRS|PUB-ATTRS:PRIV-ATTRS [--id|-i ID] [--help|-h]
Use the generate-key|gen-key|gen dsa DSA-PARAM-PEM-FILE command and KEYTYPE argument to
generate a DSA key (CKK_DSA), where DSA-PARAM-PEM-FILE specifies the name of a DSA
parameters PEM file. You can for example generate DSA parameters using the OpenSSL command
line tool as follows: 'openssl dsaparam <numbits> -out <pem-file> -outform PEM'. See the
OpenSSL man page for details about this command.
The --label|-L LABEL|PUB-LABEL:PRIV-LABEL option sets the CKA_LABEL attribute of the key
and the --attr|-a ATTRS|PUB-ATTRS:PRIV-ATTRS option can be used to set the boolean
attributes of the key (see below for detailed description of the attributes). Optionally,
set individual key attributes for public and private key separated by a colon (:). The
--id|-i ID option can be used to set the value of the CKA_ID attribute of the key.
Generating EC keys
p11sak generate-key|gen-key|gen ec CURVE --slot|-s SLOTID [--pin|-p PIN]
[--force-pin-prompt] --label|-L LABEL|PUB-LABEL:PRIV-LABEL --attr|-a
ATTRS|PUB-ATTRS:PRIV-ATTRS [--id|-i ID] [--help|-h]
Use the generate-key|gen-key|gen ec CURVE command and KEYTYPE argument to generate an EC
key (CKK_EC), where CURVE specifies the elliptic curve used to create the EC key. The
following arguments can be used for respective curves:
prime256v1|prime192|secp224|secp384r1|secp521r1|secp265k1|brainpoolP160r1|brainpoolP160t1|brainpoolP192r1|brainpoolP192t1|brainpoolP224r1|brainpoolP224t1|brainpoolP256r1|brainpoolP256t1|brainpoolP320r1|brainpoolP320t1|brainpoolP384r1|brainpoolP384t1|brainpoolP512r1|brainpoolP512t1|curve25519|curve448|ed25519|ed448
Note: Not all curves will be supported by all tokens and key generation will fail when the
specified CURVE is not supported.
The --label|-L LABEL|PUB-LABEL:PRIV-LABEL option sets the CKA_LABEL attribute of the key
and the --attr|-a ATTRS|PUB-ATTRS:PRIV-ATTRS option can be used to set the boolean
attributes of the key (see below for detailed description of the attributes). Optionally,
set individual key attributes for public and private key separated by a colon (:). The
--id|-i ID option can be used to set the value of the CKA_ID attribute of the key.
Generating IBM Dilithium keys
p11sak generate-key|gen-key|gen ibm-dilithium VERSION --slot|-s SLOTID [--pin|-p PIN]
[--force-pin-prompt] --label|-L LABEL|PUB-LABEL:PRIV-LABEL --attr|-a
ATTRS|PUB-ATTRS:PRIV-ATTRS [--id|-i ID] [--help|-h]
Use the generate-key|gen-key|gen ibm-dilithium VERSION command and KEYTYPE argument to
generate an IBM Dilithium key (CKK_IBM_PQC_DILITHIUM), where VERSION specifies the version
of the IBM Dilithium keypair. The following arguments can be used for respective keys:
r2_65|r2_87|r2_44|r3_65|r3_87
Note: Not all IBM Dilithium versions will be supported by all tokens and key generation
will fail when the specified VERSION is not supported.
The --label|-L LABEL|PUB-LABEL:PRIV-LABEL option sets the CKA_LABEL attribute of the key
and the --attr|-a ATTRS can be used to set the boolean attributes of the key (see below
for detailed description of the attributes). Optionally, set individual key attributes
for public and private key separated by a colon (:). The --id|-i ID option can be used to
set the value of the CKA_ID attribute of the key.
Generating IBM Kyber keys
p11sak generate-key|gen-key|gen ibm-kyber VERSION --slot|-s SLOTID [--pin|-p PIN]
[--force-pin-prompt] --label|-L LABEL|PUB-LABEL:PRIV-LABEL --attr|-a
ATTRS|PUB-ATTRS:PRIV-ATTRS [--id|-i ID] [--help|-h]
Use the generate-key|gen-key|gen ibm-kyber VERSION command and KEYTYPE argument to
generate an IBM Kyber key (CKK_IBM_PQC_KYBER), where VERSION specifies the version of the
IBM Kyber keypair. The following arguments can be used for respective keys: r2_768|r2_1024
Note: Not all IBM Kyber versions will be supported by all tokens and key generation will
fail when the specified VERSION is not supported.
The --label|-L LABEL|PUB-LABEL:PRIV-LABEL option sets the CKA_LABEL attribute of the key
and the --attr|-a ATTRS can be used to set the boolean attributes of the key (see below
for detailed description of the attributes). Optionally, set individual key attributes
for public and private key separated by a colon (:). The --id|-i ID option can be used to
set the value of the CKA_ID attribute of the key.
Listing symmetric and asymmetric keys
p11sak list-key|ls-key|ls [KEYTYPE] --slot|-s SLOTID [--pin|-p PIN] [--force-pin-prompt]
[--label|-L LABEL] [--id|-i ID] [--attr|-a ATTRS] [--long|-l] [--detailed-uri] [--sort|-S
SORT-SPEC] [--help|-h]
Use the list-key|ls-key|ls command and the optional KEYTYPE argument to list symmetric or
asymmetric keys. Public, private, secret, or all keys can also be listed irrespective of
the key type.
Possible values for the KEYTYPE argument are:
des|3des|generic|aes|aes-xts|rsa|dh|dsa|ec|ibm-dilithium|ibm-
kyber|public|private|secret|all. If KEYTYPE is omitted, then all key types are listed.
Specify the --label|-L LABEL, the --id|-i ID, and/or the --attr|-a ATTRS options to filter
the list of keys to display. You can use wildcards (* and ?) in the LABEL specification.
To specify a wildcard character that should not be treated as a wildcard, it must be
escaped using a backslash (\* or \?). Also, a backslash character that should not be
treated as an escape character must be escaped (\\). The ID must be specified as hex
string (not prefixed with 0x) of any number of bytes.
By default, the keys are listed in a short, tabular format showing only the boolean
attributes, the key type (CKA_KEY_TYPE) and the key label (CKA_LABEL). The attributes are
denoted using the same single letters as used with the --attr|-a
ATTRS|PUB-ATTRS:PRIV-ATTRS option. When option --long|-l is specified, the keys are listed
in long format, displaying the values of all attributes defined for the key type,
including non-boolean attributes.
By default, the keys are displayed in the order as they are retrieved from the PKCS #11
implementation. To display the keys in a certain order, specify the --sort|-S SORT-SPEC
option. You can sort the keys by label, key type, object class, and/or key size. For
details, see the description of the --sort|-S SORT-SPEC option below.
Deleting symmetric and asymmetric keys
p11sak remove-key|rm-key|rm [KEYTYPE] --slot|-s SLOTID [--pin|-p PIN] [--force-pin-prompt]
[--label|-L LABEL] [--id|-i ID] [--attr|-a ATTRS] [--long|-l] [--force|-f] [--help|-h]
Use the remove-key|rm-key|rm command and the optional KEYTYPE argument to remove symmetric
or asymmetric keys. Public, private, secret, or all keys can also be selected for removal
irrespective of the key type.
Possible values for the KEYTYPE argument are:
des|3des|generic|aes|aes-xts|rsa|dh|dsa|ec|ibm-dilithium|ibm-
kyber|public|private|secret|all. If KEYTYPE is omitted, then all key types are selected
for removal.
Specify the --label|-L LABEL, the --id|-i ID, and/or the --attr|-a ATTRS options to filter
the list of keys to display. You can use wildcards (* and ?) in the LABEL specification.
To specify a wildcard character that should not be treated as a wildcard, it must be
escaped using a backslash (\* or \?). Also, a backslash character that should not be
treated as an escape character must be escaped (\\). The ID must be specified as hex
string (not prefixed with 0x) of any number of bytes.
The user will be prompted to confirm the removal of the key. To suppress the prompt, use
the --force|-f option.
Setting or updating boolean attributes of symmetric and asymmetric keys
p11sak set-key-attr|set-key|set [KEYTYPE] --slot|-s SLOTID [--pin|-p PIN]
[--force-pin-prompt] [--label|-L LABEL] [--id|-i ID] [--attr|-a ATTRS] [--force|-f]
[--new-attr|-A ATTRS] [--new-label|-l LABEL] [--new-id|-I ID] [--help|-h]
Use the set-key-attrs | set-key | set command and the optional KEYTYPE argument to set or
update boolean attributes of symmetric or asymmetric keys. Public, private, secret, or
all keys can also be selected for updating irrespective of the key type.
Possible values for the KEYTYPE argument are:
des|3des|generic|aes|aes-xts|rsa|dh|dsa|ec|ibm-dilithium|ibm-
kyber|public|private|secret|all. If KEYTYPE is omitted, then all key types are selected
for updating.
Specify the --label|-L LABEL, the --id|-i ID, and/or the --attr|-a ATTRS options to filter
the list of keys to display. You can use wildcards (* and ?) in the LABEL specification.
To specify a wildcard character that should not be treated as a wildcard, it must be
escaped using a backslash (\* or \?). Also, a backslash character that should not be
treated as an escape character must be escaped (\\). The ID must be specified as hex
string (not prefixed with 0x) of any number of bytes.
Use the --new-attr|-A ATTRS option to specify the boolean attributes of the key you want
to update (see below for detailed description of the attributes). Attributes that are not
specified are not changed. Use the --new-label|-l LABEL option to specify the new label,
or the --new-id|-I ID option to specify the new ID to set for the key. At least one of the
--new-attr|-A ATTRS, --new-label|-l LABEL, or --new-id|-I ID options must be specified.
The user will be prompted to confirm the updating of the key. To suppress the prompt, use
the --force|-f option.
Coyping symmetric and asymmetric keys
p11sak copy-key|copy|cp [KEYTYPE] --slot|-s SLOTID [--pin|-p PIN] [--force-pin-prompt]
[--label|-L LABEL] [--id|-i ID] [--attr|-a ATTRS] [--force|-f] [--new-attr|-A ATTRS]
[--new-label|-l LABEL] [--new-id|-I ID] [--help|-h]
Use the copy-key | copy | cp command and the optional KEYTYPE argument to copy symmetric
or asymmetric keys and optionally set or change boolean attributes, the label, or ID of
the copied keys. Public, private, secret, or all keys can also be copied irrespective of
the key type.
Possible values for the KEYTYPE argument are:
des|3des|generic|aes|aes-xts|rsa|dh|dsa|ec|ibm-dilithium|ibm-
kyber|public|private|secret|all. If KEYTYPE is omitted, then all key types are selected
for copying.
Specify the --label|-L LABEL, the --id|-i ID, and/or the --attr|-a ATTRS options to filter
the list of keys to display. You can use wildcards (* and ?) in the LABEL specification.
To specify a wildcard character that should not be treated as a wildcard, it must be
escaped using a backslash (\* or \?). Also, a backslash character that should not be
treated as an escape character must be escaped (\\). The ID must be specified as hex
string (not prefixed with 0x) of any number of bytes.
Use the --new-attr|-A ATTRS option to specify the boolean attributes of the copied key you
want to set or update (see below for detailed description of the attributes). Attributes
that are not specified are not changed. Use the --new-label|-l LABEL option to specify the
new label, or the --new-id|-I ID option to specify the new ID to set for the copied key.
The user will be prompted to confirm the copying of the key. To suppress the prompt, use
the --force|-f option.
Importing symmetric and asymmetric keys from a file
p11sak import-key|import|imp KEYTYPE [KIND] --slot|-s SLOTID [--pin|-p PIN]
[--force-pin-prompt] --label|-L LABEL [--id|-i ID] [--force|-f] [--attr|-a ATTRS]
--file|-F FILENAME [--pem-password|-P PASSWORD] [--force-pem-pwd-prompt] [--opaque|-o]
[--help|-h]
Use the import-key|import|imp command and KEYTYPE argument to import an symmetric or
asymmetric key from a file. When importing an asymmetric key, the KIND argument is
required and specifies to either import a private or public key.
Possible values for the KEYTYPE argument are:
des|3des|generic|aes|aes-xts|rsa|dh|dsa|ec|ibm-dilithium|ibm-
kyber|public|private|secret|all.
The --label|-L LABEL option sets the CKA_LABEL attribute of the key and the --attr|-a
ATTRS can be used to set the boolean attributes of the key (see below for detailed
description of the attributes). The --id|-i ID option can be used to set the value of the
CKA_ID attribute of the key.
The --file|-F FILENAME option specifies the file name of the file that contains the key to
be imported. For symmetric keys, this is a binary file containing the key material in
clear. For asymmetric keys, this is an OpenSSL PEM file containing a public or private
key. PEM files can optionally be password protected. Specify the PEM password with the
--pem-password|-P PASSWORD option or environment variable P11SAK_PEM_PASSWORD. If the PEM
file is password protected, but no PEM password is specified, you will be prompted for the
PEM password. Specify the --opaque|-o option to import an opaque secure key blob. Not all
tokens support this.
Exporting symmetric and asymmetric keys to a file
p11sak export-key|export|exp [KEYTYPE] --slot|-s SLOTID [--pin|-p PIN]
[--force-pin-prompt] [--label|-L LABEL] [--id|-i ID] [--attr|-a ATTRS] [--force|-f]
--file|-F FILENAME [--opaque|-o] [--spki|-S] [--help|-h]
Use the export-key|export|exp command and the optional KEYTYPE argument to export
symmetric or asymmetric keys to a file. Public, private, secret, or all keys can also be
selected for export irrespective of the key type.
Possible values for the KEYTYPE argument are:
des|3des|generic|aes|aes-xts|rsa|dh|dsa|ec|ibm-dilithium|ibm-
kyber|public|private|secret|all. If KEYTYPE is omitted, then all key types are selected
for export.
Specify the --label|-L LABEL, the --id|-i ID, and/or the --attr|-a ATTRS options to filter
the list of keys to display. You can use wildcards (* and ?) in the LABEL specification.
To specify a wildcard character that should not be treated as a wildcard, it must be
escaped using a backslash (\* or \?). Also, a backslash character that should not be
treated as an escape character must be escaped (\\). The ID must be specified as hex
string (not prefixed with 0x) of any number of bytes.
The --file|-F FILENAME option specifies the file name of the file to which the keys to be
exported are written to. For symmetric keys, this is a binary file where the key material
in clear is written to. For asymmetric keys, this is an OpenSSL PEM file where the public
or private keys are written to. If multiple asymmetric keys match the filter, the keys are
appended to the PEM file specified with the --file|-F FILENAME option. If multiple
symmetric keys or a mixture of asymmetric and symmetric keys match the filter, then you
are prompted to confirm to overwrite the previously created file, unless the [--force|-f]
option is specified.
Specify the --opaque|-o option to export the opaque secure key blobs of the key. Not all
tokens support this.
Specify the --spki|-S option to export the Subject Public Key Info (SPKI) from the
CKA_PUBLIC_KEY_INFO attribute of an asymmetric private key instead of its private key
material. This option can only be used with private keys.
Note: Not all keys can be exported, because its attribute setting may forbid to reveal the
values of certain attributes. To allow exporting of a secret (CKO_SECRET_KEY) or private
(CKO_PRIVATE_KEY) key, attribute CKA_SENSITIVE must be CK_FALSE and attribute
CKA_EXTRACTABLE must be CK_TRUE. Secret or private keys that contain an opaque secure key
blob (attribute CKA_IBM_OPAQUE) can also not be exported in clear, even if the attributes
would allow it. For such keys only the opaque secure key blob can be exported by using the
--opaque|-o option.
ARGUMENTS
KEYTYPE
Selects the respective symmetric or asymmetric key to be generated, imported or selected.
Possible values are: des|3des|generic|aes|aes-xts|rsa|dh|dsa|ec|ibm-dilithium|ibm-
kyber|public|private|secret|all. The public|private|secret|all argument can only be used
with commands that use the KEYTYPE argument as filter, such as the list-key command, the
remove-key command, the set-key-attrs command, or the export-key command.
KEYBITS
Specifies the size of the key in bits. For the aes key type, possible values are
128|192|256. For the aes-xts key type, possible values are 128|256. For the rsa key
type, possible values are 512|1024|2048|4096.
PUBL-EXP
Specifies the public exponent for an RSA key. If not specified, the default is 65537
according to the PKCS #11 standard.
PRIV-BITS
Specifies the size of the private key in bits for an DH key.
GROUP
Specifies the Diffie-Hellman FFC group name for an DH key. Possible values are
ffdhe2048|ffdhe3072|ffdhe4096|ffdhe6144|ffdhe8192|modp1536|modp2048|modp3072|modp4096|modp6144|modp8192.
Note: Not all groups are supported by all tokens and key generation will fail when the
specified GROUP is not supported. Also, not all groups are supported by all OpenSSL
versions. If the p11sak tool is compiled against an OpenSSL version that does not support
certain groups, then those groups are not accepted for the GROUP argument.
DH-PARAM-PEM-FILE
Specifies the DH parameters PEM file name. You can for example generate DH parameters
using the OpenSSL command line tool as follows: 'openssl dhparam <numbits> -out
<pem-file> -outform PEM' . See the OpenSSL man page for details about this command.
DSA-PARAM-PEM-FILE
Specifies the DSA parameters PEM file name. You can for example generate DSA parameters
using the OpenSSL command line tool as follows: 'openssl dsaparam <numbits> -out
<pem-file> -outform PEM' . See the OpenSSL man page for details about this command.
CURVE
Specifies the curve for an EC key. Possible values are:
prime256v1|prime192|secp224|secp384r1|secp521r1|secp265k1|brainpoolP160r1|brainpoolP160t1|brainpoolP192r1|brainpoolP192t1|brainpoolP224r1|brainpoolP224t1|brainpoolP256r1|brainpoolP256t1|brainpoolP320r1|brainpoolP320t1|brainpoolP384r1|brainpoolP384t1|brainpoolP512r1|brainpoolP512t1|curve25519|curve448|ed25519|ed448.
VERSION
Specifies the version for an IBM Dilithium or IBM Kyber key. For the ibm-dilithium key
type, possible values are r2_65|r2_87|r2_44|r3_65|r3_87. For the ibm-kyber key type,
possible values are r2_768|r2_1024.
KIND
Specifies the kind of the asymmetric key to import. Possible values are public|private.
OPTIONS
--slot|-s SLOT
Specifies the slot number of the token to use.
--pin|-p PIN
Specifies the 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 einvironment variable
is set, you are prompted for the PIN.
--force-pin-prompt
Enforce the p11sak tool to prompt for the token user PIN (regardless if it has
been specified elsewhere)
--label|-L LABEL|PUB-LABEL:PRIV-LABEL
Specifies the key label attribute value (CKA_LABEL).
For commands such as the list-key command, the remove-key command, the
set-key-attrs command, and the export-key command, specify the label to filter the
list of keys to operate on. You can use wildcards (* and ?) in the LABEL
specification. To specify a wildcard character that should not be treated as a
wildcard, it must be escaped using a backslash (\* or \?). Also, a backslash
character that should not be treated as an escape character must be escaped (\\).
For generation of asymmetric keys, the specified label is appended by :pub and
:prv for the public and private key objects. Optionally, a user can set different
labels for the public and private key objects by specifying them separated by a
colon (:), e.g. pub-label:priv-label. The label string in front of the colon is
used as label for the public key object, the label string after the colon is used
for the private key object. To set the public and private key label the exact
same, use pub-label:=. The equal sign (=) means to use the same label string for
the private key objects as for the public key object. In case a colon character
or a equal sign is supposed to appear within a label string, it must be escaped
using a back slash (\), e.g. abc\:xyz results in abx:xyz where the colon is not
treated as separator character. Note that the shell may interpret escape
characters as well, so better quote the LABEL|PUB-LABEL:PRIV-LABEL specification.
--id|-i ID
Specifies the key ID attribute value (CKA_ID) as hex string (not prefixed with 0x)
of any number of bytes.
For commands such as the list-key command, the remove-key command, the
set-key-attrs command, and the export-key command, specify the key ID to filter
the list of keys to operate on.
For generation of asymmetric keys, the same ID is set for both, the public and the
private key.
--attr|-a ATTRS|PUB-ATTRS:PRIV-ATTRS
For the generate-key command the and import-key commands, specify the boolean
attributes that are to be set for the new key(s). For commands such as the
list-key command, the remove-key command, the set-key-attrs command, and the
export-key command, specify the attribute values to filter the list of keys to
operate on.
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 when generating a key. The p11sak tool
always generates token keys, since session keys are not persistent, and thus would
no longer exist after the session that the p11sak tool has opened for generating
the key is closed when it exists.
When generating or importing a key with the p11sak tool, attribute CKA_SENSITIVE
defaults to TRUE for secret keys or the private key of asymmetric key pairs.
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 p11sak
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:
• P - CKA_PRIVATE
• L - CKA_LOCAL (read only)
• M - CKA_MODIFIABLE
• B - CKA_COPYABLE
• Y - CKA_DESTROYABLE
• R - CKA_DERIVE
• E - CKA_ENCRYPT
• D - CKA_DECRYPT
• G - CKA_SIGN
• C - CKA_SIGN_RECOVER
• V - CKA_VERIFY
• O - CKA_VERIFY_RECOVER
• W - CKA_WRAP
• U - CKA_UNWRAP
• S - CKA_SENSITIVE
• A - CKA_ALWAYS_SENSITIVE (read only)
• X - CKA_EXTRACTABLE
• N - CKA_NEVER_EXTRACTABLE (read only)
• T - CKA_TRUSTED (can only be set by SO user)
• I - CKA_WRAP_WITH_TRUSTED
• K - CKA_IBM_PROTKEY_EXTRACTABLE (IBM specific, not all tokens support this)
• Z - CKA_IBM_PROTKEY_NEVER_EXTRACTABLE (IBM specific, not all tokens support
this, read only)
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, 'MlD' corresponds to: CKA_MODIFIABLE=TRUE,
CKA_LOCAL=FALSE, CKA_DECRYPT=TRUE.
For generating asymmetric keys set individual key attributes for public and
private key separated by a colon (:). The attributes in front of the colon are set
for the public key and the attributes after the colon are set for the private key.
When no colon is used, the same attribute set is used for both, the public and
private keys. To set a configuration for only the public key, the string must end
with the colon and respectively, to use a configuration for the private key only,
the string must start with the colon.
--new-attr|-A ATTRS
Specifies the boolean attributes to set or update for a key with the set-key-attr
or copy-key commands. See the description of the --attr|-a option above for a list
of letters that are associated with the respective CK_ATTRIBUTE.
--new-label|-L LABEL
Specifies the new label attribute value (CKA_LABEL) to set for the key.
--new-id|-I ID
Specifies the new ID attribute value (CKA_ID) as hex string (not prefixed with 0x)
of any number of bytes to set for the key.
--long|-l
Prints the list-key output in long format, displaying the values of all attributes
defined for the key type, including non-boolean attributes. If the --long|-l
option is omitted, the output is in a short, tabular format, showing only the
boolean attributes, the key type (CKA_KEY_TYPE) and the key label (CKA_LABEL).
--detailed-uri
Displayes a detailed PKCS #11 URI.
--sort|-S SORT-SPEC
Sort the keys by label, key type, object class, and/or key size. Specify a sort
selection of up to 4 fields, each field represented by its coresponding letter,
separated by comma (,):
• l - sort by label (CKA_LABEL)
• k - sort by key type (CKA_KEY_TYPE)
• c - sort by object class (CKA_CLASS, secret key, private key, public key)
• s - sort by key size (CKA_VALUE_LEN, or derived from other key type spcifi
attribute)
The sort order can be appended to the field designator by a colon (:) and its
coressponding letter:
• a - ascending order (default)
• d - descending order
Example: l:a,k:d will sort by label in ascending order and then by key type in
descending order.
--force|-f
Suppress the prompt whether the user wants to remove, update, or export the keys
matching the specified KEYTYPE, label, and ID filter (if specified).
--file|-F FILENAME
For the import-key command, this option specifies the file name of the file that
contains the key to be imported. For symmetric keys, this is a binary file
containing the key material in clear. For asymmetric keys, this is an OpenSSL PEM
file containing a public or private key. PEM files used for importing keys can be
password protected. Specify the PEM password with the --pem-password|-P PASSWORD
option or environment variable P11SAK_PEM_PASSWORD. If the PEM file is password
protected, but no PEM password is specified, you will be prompted for the PEM
password.
For the export-key command, this option specifies the file name of the file to
which the keys to be exported are written to. For symmetric keys, this is a binary
file where the key material in clear is written to. For asymmetric keys, this is
an OpenSSL PEM file where the public or private keys are written to. If multiple
asymmetric keys match the filter, the keys are appended to the PEM file specified
with this option. If multiple symmetric keys or a mixture of asymmetric and
symmetric keys match the filter, then you are prompted to confirm to overwrite the
previously created file, unless the [--force|-f] option is specified.
--pem-password|-P PASSWORD
Specifies the password of the PEM file specified with the --file|-F FILENAME
option for the import-key command. If the PEM file is password protected, but this
option is not specified, nor environment variable P11SAK_PEM_PASSWORD is set, you
will be prompted for the PEM password.
--force-pem-pwd-prompt
Enforce the import-key command to prompt for the PEM password (regardless if it
has been specified elsewhere).
--opaque
The key material in the file specified with the --file|-F FILENAME option is an
opaque secure key blob. Not all tokens support this.
--help|-h
Prints help for the usage of the p11sak tool and/or the respective command and
then exits.
--version|-v
Prints the version of the p11sak tool and then exits.
FILES
/etc/opencryptoki/p11sak_defined_attrs.conf ~/.p11sak_defined_attrs.conf In the output config file a user can define additional attributes, which are not mentioned in the PKCS#11 standard or are not known by the p11sak tool. A custom file path can be set with environment variable P11SAK_DEFAULT_CONF_FILE. If the environment variable is not set, then .p11sak_defined_attrs.conf is first tried to be read from the current user's home directory. If this is not available, the global /etc/opencryptoki/p11sak_defined_attrs.conf config file is read. If none of these files are available, a warning message is displayed, and printing of custom attributes is not available.
ENVIRONMENT VARIABLES
P11SAK_DEFAULT_CONF_FILE
A custom path for the p11sak_defined_attrs.conf config file can be set with the
environment variable P11SAK_DEFAULT_CONF_FILE. If the environment variable is not set,
then .p11sak_defined_attrs.conf is first tried to be read from the current user's home
directory. If this is not available, the global
/etc/opencryptoki/p11sak_defined_attrs.conf config file is read. If none of these files
are available, a warning message is displayed, and printing of custom attributes is not
available.
PKCS11_USER_PIN
The 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, p11sak will
prompt for the token user PIN interactively.
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.
P11SAK_PEM_PASSWORD
PEM files used for importing keys from can be password protected. The PEM password can be
specified via the environment variable P11SAK_PEM_PASSWORD. If this environment variable
is not set, and the option --pem-password|-P PASSWORD is not specified, p11sak will prompt
for the PEM password interactively.
EXIT STATUS
The p11sak 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 p11sak tool,
or from the p11sak tool itself, like the following:
CKR_ARGUMENTS_BAD (0x00000007):
An argument, option or keyword is not valid.
CKR_DATA_INVALID (0x00000020):
The p11sak_defined_attrs.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
p11sak_defined_attrs.conf(5)