p11sak - Man Page

Manage token keys in a PKCS #11 token repository.

Synopsis

p11sak command [Arguments] [Options]

p11sak --help|-h p11sak --version|-v

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

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

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

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

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

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

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

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.

Generating EC keys

Note: Not all curves will be supported by all tokens and key generation will fail when the specified Curve is not supported.

Generating IBM Dilithium keys

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

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.

Listing symmetric and asymmetric keys

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.

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

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.

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

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.

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

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.

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

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

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.

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

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.

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

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

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

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

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

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

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

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

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

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

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.

Synopsis

Description

Commands

Generating symmetric and asymmetric keys

Generating DES/3DES keys

Generating generic secret keys

Generating AES keys

Generating AES-XTS keys

Generating RSA keys

Generating DH keys

Generating DSA keys

Generating EC keys

Generating IBM Dilithium keys

Generating IBM Kyber keys

Listing symmetric and asymmetric keys

Deleting symmetric and asymmetric keys

Setting or updating attributes of symmetric and asymmetric keys

Coyping symmetric and asymmetric keys

Importing symmetric and asymmetric keys from a file

Exporting symmetric and asymmetric keys to a file

Extracting the public key of private key objects

Listing certificates

Deleting certificates

Setting or updating attributes of certificates

Coyping certificates

Importing x.509 certificates from a file

Exporting certificates to a file

Extracting the public key of certificates

Arguments

Keytype

Certtype

Keybits

Publ-Exp

Priv-Bits

Group

Dh-Param-Pem-File

Dsa-Param-Pem-File

Curve

Version

Kind

Options

Files

/etc/opencryptoki/p11sak_defined_attrs.conf

~/.p11sak_defined_attrs.conf

Environment Variables

P11sak_default_conf_file

Pkcs11_user_pin

Pkcs11_so_pin

Pkcslib

P11sak_pem_password

Exit Status

CKR_ARGUMENTS_BAD (0x00000007)

CKR_DATA_INVALID (0x00000020)

CKR_MECHANISM_INVALID (0x00000070)

CKR_KEY_SIZE_RANGE (0x00000062)

CKR_HOST_MEMORY (0x00000002)

CKR_FUNCTION_FAILED (0x00000006)

See Also

Referenced By