Provided by: opencryptoki_3.25.0+dfsg-0ubuntu1_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 and certificates 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 their
values (not all attributes may be displayed if a keys is sensitive). It also supports the import, export,
copy, and listing of certificates. Public keys inside certificates and private keys can be extracted and
added to the token repository as new public key objects.
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 and certificates 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]
[--no-login|-N] [--so] --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]
[--no-login|-N] [--so] --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]
[--no-login|-N] [--so] --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]
[--no-login|-N] [--so] --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] [--no-login|-N] [--so] --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] [--no-login|-N] [--so] --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] [--no-login|-N] [--so] --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]
[--no-login|-N] [--so] --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] [--no-login|-N] [--so] --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|r3_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]
[--no-login|-N] [--so] --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] [--no-login|-N]
[--so] [--label|-L LABEL] [--id|-i ID] [--attr|-a ATTRS] [--long|-l] [--detailed-uri] [--hsm-mkvp|-m]
[--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. When option --hsm-mkvp|-m is specified, the HSM master key
verification patterns (MKVPs) of the keys are displayed. This is only possible for secure key tokens,
such as the CCA and EP11 tokens.
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]
[--no-login|-N] [--so] [--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 remove. 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 attributes of symmetric and asymmetric keys
p11sak set-key-attr|set-key|set [KEYTYPE] --slot|-s SLOTID [--pin|-p PIN] [--force-pin-prompt]
[--no-login|-N] [--so] [--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 set or update. 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] [--no-login|-N]
[--so] [--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 copy. 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]
[--no-login|-N] [--so] --label|-L LABEL [--id|-i ID] [--force|-f] [--attr|-a ATTRS] --file|-F FILENAME
[--pem-password|-P PASSWORD] [--force-pem-pwd-prompt] [--opaque|-o] [--oqsprovider-pem] [--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.
Specify the --oqsprovider-pem option when the key material in the PEM file is in the oqsprovider format.
This option is only valid for the ibm-dilithium keytype. PEM files in oqsprovider format are only
supported when the oqsprovider from https://github.com/open-quantum-safe/oqs-provider has been configured
with OpenSSL 3.0 or later. This is an experimental feature, it may change in an incompatible way in the
future!
Exporting symmetric and asymmetric keys to a file
p11sak export-key|export|exp [KEYTYPE] --slot|-s SLOTID [--pin|-p PIN] [--force-pin-prompt]
[--no-login|-N] [--so] [--label|-L LABEL] [--id|-i ID] [--attr|-a ATTRS] [--force|-f] --file|-F FILENAME
[--opaque|-o] [--spki|-S] [--uri-pem|-u] [--uri-pin-value] [--uri-pin-source FILENAME]
[--oqsprovider-pem] [--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 export. 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.
Specify the --oqsprovider-pem option when the key material is to be exported in oqsprovider format into
the PEM file. This option is only valid for the ibm-dilithium keytype. PEM files in oqsprovider format
are only supported when the oqsprovider from https://github.com/open-quantum-safe/oqs-provider has been
configured with OpenSSL 3.0 or later. This is an experimental feature, it may change in an incompatible
way in the future!
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.
Specify the --uri-pem|-u option to export the PKCS#11 URI of the key in PEM form instead of the key
material. Such an URI-PEM file can then be used with the pkcs11-provider from
https://github.com/latchset/pkcs11-provider. By default, the PKCS#11 URI does not contain the PKCS#11
user pin. Specify option --uri-pin-value to include the PKCS#11 user pin in the URI using the pin-value
query attribute. This reveals the PKCS#11 user pin in clear, use with care! Alternatively, specify
option --uri-pin-source FILENAME to include the pin-source query attribute in the URI, referencing the
file name specified with this option. The PKCS#11 user pin value is written into that file as part of the
export operation. This reveals the PKCS#11 user pin in clear, use with care! Adjust the file permissions
of the specified pin-source file so that it can only be read by the desired user(s). By default the file
permissions are set so that only the owner user can read and write that file, but no one else (i.e.
0600).
Extracting the public key of private key objects
p11sak extract-pubkey|extr-pubkey|expub [KEYTYPE] --slot|-s SLOTID [--pin|-p PIN] [--force-pin-prompt]
[--no-login|-N] [--so] [--label|-L LABEL] [--id|-i ID] [--attr|-a ATTRS] [--new-attr|-A ATTRS]
[--new-label|-l LABEL] [--new-id|-I ID] [--force|-f] [--help|-h]
Use the extract-pubkey|extr-pubkey|expub command and the optional KEYTYPE argument to extract the public
key from private key objects and save it as new token object.
Possible values for the KEYTYPE argument are: rsa|dh|dsa|ec|ibm-dilithium|ibm-kyber|private|all. If
KEYTYPE is omitted, then all private 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 private
keys of which the public keys are to be extracted. 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 public key object you want to
set (see below for detailed description of the attributes). Use the --new-label|-l LABEL option to
specify the new label. If no new label is specified, the label of the public key object is derived from
the private key label by appending _pubkey.
Use the --new-id|-I ID option to set an ID for the extracted public key object.
The user will be prompted to confirm the extraction of the public key from the private key objects. To
suppress the prompt, use the --force|-f option.
Listing certificates
p11sak list-cert|ls-cert|lsc [CERTTYPE] --slot|-s SLOTID [--pin|-p PIN] [--force-pin-prompt]
[--no-login|-N] [--so] [--label|-L LABEL] [--id|-i ID] [--attr|-a ATTRS] [--long|-l] [--detailed-uri]
[--sort|-S SORT-SPEC] [--help|-h]
Use the list-cert|ls-cert|lsc command and the optional CERTTYPE argument to list certificates.
Possible values for the CERTTYPE argument are: x509. If CERTTYPE is omitted, then x509 certificates are
listed by default, because no other certificate types are supported.
Specify the --label|-L LABEL, the --id|-i ID, and/or the --attr|-a ATTRS options to filter the list of
certificates 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 certificates are listed in a short, tabular format showing only the boolean attributes,
the certificate type (CKA_CERTIFICATE_TYPE) and the certificate label (CKA_LABEL). The attributes are
denoted using the same single letters as used with the --attr|-a ATTRS option. When option --long|-l is
specified, the certificates are listed in long format, displaying the values of all attributes defined
for the certificate type, including non-boolean attributes.
By default, the certificates are displayed in the order as they are retrieved from the PKCS #11
implementation. To display the certificates in a certain order, specify the --sort|-S SORT-SPEC option.
You can sort the certificates by label and/or subject common name (CN). For details, see the description
of the --sort|-S SORT-SPEC option below.
Deleting certificates
p11sak remove-cert|rm-cert|rmc [CERTTYPE] --slot|-s SLOTID [--pin|-p PIN] [--force-pin-prompt]
[--no-login|-N] [--so] [--label|-L LABEL] [--id|-i ID] [--attr|-a ATTRS] [--force|-f] [--help|-h]
Use the remove-cert|rm-cert|rmc command and the optional CERTTYPE argument to remove certificates from
the repository.
Possible values for the CERTTYPE argument are: x509. If CERTTYPE is omitted, then x509 is used by
default, because no other certificate types are supported.
Specify the --label|-L LABEL, the --id|-i ID, and/or the --attr|-a ATTRS options to filter the list of
certificates to remove. 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 certificate. To suppress the prompt, use the
--force|-f option.
Setting or updating attributes of certificates
p11sak set-cert-attr|set-cert|setc [CERTTYPE] --slot|-s SLOTID [--pin|-p PIN] [--force-pin-prompt]
[--no-login|-N] [--so] [--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-cert-attrs | set-cert | sect command and the optional CERTTYPE argument to set or update
boolean attributes of certificates.
Possible values for the CERTTYPE argument are: x509. If CERTTYPE is omitted, x509 is used by default,
because no other certificate types are supported.
Specify the --label|-L LABEL, the --id|-i ID, and/or the --attr|-a ATTRS options to filter the list of
certificates to set or update. 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 certificate 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 certificate. 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 certificate. To suppress the prompt, use the
--force|-f option.
Coyping certificates
p11sak copy-cert|copyc|cpc [CERTTYPE] --slot|-s SLOTID [--pin|-p PIN] [--force-pin-prompt]
[--no-login|-N] [--so] [--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-cert | copyc | cpc command and the optional CERTTYPE argument to copy certificates and
optionally set or change boolean attributes, the label, or ID of the copied certificates.
Possible values for the CERTTYPE argument are: x509. If CERTTYPE is omitted, then x509 is used by
default, because no other certificate type is supported.
Specify the --label|-L LABEL, the --id|-i ID, and/or the --attr|-a ATTRS options to filter the list of
certificates to copy. 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 certificates 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 certificate.
The user will be prompted to confirm the copying of the certificate. To suppress the prompt, use the
--force|-f option.
Importing x.509 certificates from a file
p11sak import-cert|importc|impc CERTTYPE --slot|-s SLOTID [--pin|-p PIN] [--force-pin-prompt]
[--no-login|-N] [--so] --label|-L LABEL [--id|-i ID] [--attr|-a ATTRS] --file|-F FILENAME [--ca-cert|-C]
[--help|-h]
Use the import-cert|importc|impc command and CERTTYPE argument to import an x.509 certificate from a
file.
Possible values for the CERTTYPE argument are: x509. If CERTTYPE is omitted, then x509 is used by
default, because no other certificate type is supported.
The --label|-L LABEL option sets the CKA_LABEL attribute of the certificate and the --attr|-a ATTRS can
be used to set the boolean attributes of the certificate (see below for detailed description of the
attributes. Applicable attributes for certificates are P M B Y T). The --id|-i ID option can be used to
set the value of the CKA_ID attribute of the certificate.
The --file|-F FILENAME option specifies the file name of the file that contains the certificate to be
imported. Supported input formats are PEM and binary (DER-encoded). The format is automatically detected.
The --ca-cert|-C option flags the certificate as a Certificate Authority (CA) certificate. If the
certificate has the BasicConstraints CA flag on, it is also flagged as Certificate Authority (CA)
certificate.
Exporting certificates to a file
p11sak export-cert|exportc|expc [CERTTYPE] --slot|-s SLOTID [--pin|-p PIN] [--force-pin-prompt]
[--no-login|-N] [--so] [--label|-L LABEL] [--id|-i ID] [--attr|-a ATTRS] [--force|-f] --file|-F FILENAME
[--der|-D] [--uri-pem|-u] [--uri-pin-value] [--uri-pin-source FILENAME] [--help|-h]
Use the export-cert|exportc|expc command and the optional CERTTYPE argument to export x.509 public key
certificates to a file.
Possible values for the CERTTYPE argument are: x509. If CERTTYPE is omitted, then x509 is used by
default, because no other certificate types are supported.
Specify the --label|-L LABEL, the --id|-i ID, and/or the --attr|-a ATTRS options to filter the list of
certificates to export. 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 certificates to be
exported are written to. This can be an OpenSSL PEM file or binary (DER-encoded) file. If it's a PEM
file, multiple certificates can be exported to the same file. If it's a binary file, each subsequent
export will overwrite the previous data in the output file. You are prompted to confirm to overwrite the
previously created file, unless the [--force|-f] option is specified.
Specify the --der|-D option to export the certificate(s) in binary (DER-encoded) form. Default is PEM
format.
Specify the --uri-pem|-u option to export the PKCS#11 URI of the certificate in PEM form instead of the
certificate material. Such an URI-PEM file can then be used with the pkcs11-provider from
https://github.com/latchset/pkcs11-provider. By default, the PKCS#11 URI does not contain the PKCS#11
user pin. Specify option --uri-pin-value to include the PKCS#11 user pin in the URI using the pin-value
query attribute. This reveals the PKCS#11 user pin in clear, use with care! Alternatively, specify
option --uri-pin-source FILENAME to include the pin-source query attribute in the URI, referencing the
file name specified with this option. The PKCS#11 user pin value is written into that file as part of the
export operation. This reveals the PKCS#11 user pin in clear, use with care! Adjust the file permissions
of the specified pin-source file so that it can only be read by the desired user(s). By default the file
permissions are set so that only the owner user can read and write that file, but no one else (i.e.
0600).
Extracting the public key of certificates
p11sak extract-cert-pubkey|extrc-pubkey|excpub [CERTTYPE] --slot|-s SLOTID [--pin|-p PIN]
[--force-pin-prompt] [--no-login|-N] [--so] [--label|-L LABEL] [--id|-i ID] [--attr|-a ATTRS]
[--new-attr|-A ATTRS] [--new-label|-l LABEL] [--new-id|-I ID] [--force|-f] [--help|-h]
Use the extract-cert-pubkey|extrc-pubkey|excpub command and the optional CERTTYPE argument to extract the
public key from certificates and save it as new token object.
Possible values for the CERTTYPE argument are: x509. If CERTTYPE is omitted, then x509 is used by
default, because no other certificate types are supported.
Specify the --label|-L LABEL, the --id|-i ID, and/or the --attr|-a ATTRS options to filter the
certificates of which the public keys are to be extracted. 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 public key object you want to
set (see below for detailed description of the attributes). Use the --new-label|-l LABEL option to
specify the new label. If no new label is specified, the label of the public key object is derived from
the certificate label by appending _pubkey.
Use the --new-id|-I ID option to set an ID for the extracted public key object.
The user will be prompted to confirm the extraction of the public key from the certificate. To suppress
the prompt, use the --force|-f 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.
CERTTYPE
Selects the type of certificate to be imported, exported, listed, copied, updated, removed, or selected
for public key extraction. Possible values are: x509. If no certificate type is specified, certificate
type x509 is used, because currently no other certificate types are supported.
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|r3_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 environment 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)
--no-login|-N
Do not login the session. This means that only public token objects (CKA_PRIVATE=FALSE) can be
accessed.
--so Login as SO (security officer). Option --pin|-p PIN must specify the SO pin, or if the --pin|-p
PIN option is not specified, environment variable PKCS11_SO_PIN is used. If PKCS11_SO_PIN is not
set, then you will be prompted for the SO PIN. SO can only access public token objects
(CKA_PRIVATE=FALSE), but SO can set attribute CKA_TRUSTED to TRUE for secret key objects, public
key objects, and certificate objects.
--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 to TRUE by SO user)
• I - CKA_WRAP_WITH_TRUSTED
• H - CKA_ALWAYS_AUTHENTICATE (for keys of class CKO_PRIVATE_KEY only, can only be set to TRUE if
CKA_PRIVATE is also TRUE)
• 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.
--hsm-mkvp|-m
Shows the HSM master key verification patterns (MKVPs) of the key objects. This option is only
valid for secure key tokens, such as the CCA and EP11 tokens.
--sort|-S SORT-SPEC
Sort the keys by label, key type, object class, and/or key size. Sort certificates by label
and/or subject common name (CN). Specify a sort selection of up to 4 fields, each field
represented by its corresponding letter, separated by comma (,):
• l - sort by label (keys and certificates) (CKA_LABEL)
• k - sort by key type (keys only) (CKA_KEY_TYPE)
• c - sort by object class (keys only) (CKA_CLASS, secret key, private key, public key)
• s - sort by key size (keys only) (CKA_VALUE_LEN, or derived from other key type specific
attribute)
• n - sort by common name (certificates only)
The sort order can be appended to the field designator by a colon (:) and its corresponding
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.
--oqsprovider-pem
The key material in the PEM file specified with the --file|-F FILENAME option is in the
oqsprovider format. This option is only valid for the ibm-dilithium keytype. PEM files in
oqsprovider format are only supported when the oqsprovider from https://github.com/open-quantum-
safe/oqs-provider has been configured with OpenSSL 3.0 or later.
Note: This is an experimental feature, it may change in an incompatible way in the future!
--der|-D
The certificate is written to the file in binary (DER-encoded) form. Default is PEM format. Note
that only one certificate can be written into a given file in DER-encoded form, while multiple
certificates can be written into the same file in PEM format.
--uri-pem|-u
Export the key's or certificate’s PKCS#11 URI in PEM form instead of the key or certificate
material. Such an URI-PEM file can then be used with the pkcs11-provider from
https://github.com/latchset/pkcs11-provider.
--uri-pin-value
When exporting the key's or certificate's PKCS#11 URI in PEM form, include the PKCS#11 user pin
value in the URI using the pin-value query attribute. This reveals the PKCS#11 user pin in clear,
use with care! This option can only be used together with the --uri-pem|-u option, and when
options --no-login|-N and --so are not specified.
--uri-pin-source FILENAME
When exporting the key's or certificate's PKCS#11 URI in PEM form, include the pin-source query
attribute in the URI, referencing the file name specified with this option. The PKCS#11 user pin
value is written into that file as part of the export operation. This reveals the PKCS#11 user
pin in clear, use with care! Adjust the file permissions of the specified file so that it can
only be read by the desired user(s). This option can only be used together with the --uri-pem|-u
option, and when options --no-login|-N and --so are not specified.
--ca-cert|-C
Flag the certificate as a Certificate Authority (CA) certificate. If the certificate has the
BasicConstraints CA flag on, it is also flagged as Certificate Authority (CA) certificate.
--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.
PKCS11_SO_PIN
When option --so is specified, the token SO PIN can be specified via the environment variable
PKCS11_SO_PIN. If this environment variable is not set, and the option --pin|-p PIN is not specified,
p11sak will prompt for the token SO 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)
3.25.0 May 2020 P11SAK(1)