Managing token keys - p11sak utility

The general invocation scheme of the command line tool is:

p11sak COMMAND [ARGS] [OPTIONS]

Figure 1. p11sak syntax - General invocation scheme

where

subcommand

generate−key: Generating keys in the openCryptoki repository
list-key: Listing keys in the repository
remove-key: Removing keys
set-key-attr: Setting attributes of keys
copy-key: Copying keys in the repository
import-key: Importing keys from a binary file or a PEM file
export-key: Exporting keys to a binary file or a PEM file
extract-pubkey: Extracting the public key from a private key
list-cert: Listing certificates in the repository
remove-cert: Removing certificates from the repository
set-cert-attr: Setting or updating attributes of certificates
copy-cert: Copying certificates in the repository
import-cert: Importing certificates from a binary file or a PEM file
export-cert: Exporting certificates to a binary file or PEM file
extract-cert-pubkey: Extracting public keys from certificates

Also, read the information in section Command help to learn how to use the tool efficiently.

Generating keys in the openCryptoki repository

Use the p11sak generate-key subcommand to generate keys in the openCryptoki token repository. The tool supports the generation of:

symmetric keys (AES, AES-XTS, 3DES, DES, generic secret) with PKCS #11 attributes
asymmetric keys (RSA, DH, DSA, EC, IBM® Kyber, IBM Dilithium) with PKCS #11 attributes.

Figure 2. p11sak syntax - Generating keys

where

des

specifies a symmetric DES key to be generated.

3des

specifies a symmetric triple DES key.

aes

specifies a symmetric AES key to be generated. You must specify a key length in bits: 128, 192, or 256.

aes-xts

specifies a symmetric AES-XTS key to be generated. You must specify a key length in bits: 128 or 256.

generic

specifies a generic secret key to be generated (CKK_GENERIC_SECRET), which you can use for example, for HMAC. You must specify a key length in bits.

sha-1-hmac, sha[224|256|384|512]-hmac, sha512/[224|256]-hmac, sha3-[224|256|384|512]-hmac

specifies a key to be generated (CKK_SHAnnn_HMAC), which you can use for example, for HMAC. You must specify a key length in bits.

rsa

specifies an asymmetric RSA key pair (private and public) to be generated. You must specify a key length in bits. The key size must be in the range 512 - 16384 and must be a multiple of 8 bits. Typical key sizes are 512, 1024, 2048, 4096, or 8192. Optionally, you can specify a public exponent (parameter <public_exponent>) for an RSA key pair generation. The default is 65537.

ec

specifies an elliptic curve key pair (private and public) to be generated. You must specify an elliptic curve for the ECC key pair. Select one supported curve as shown in the syntax diagram.

dh

specifies a Diffie-Hellman key pair (private and public) to be generated. You must specify a group name or the name of a PEM file (<dh−param−pem−file>) containing the DH-parameter for the key pair. Valid group names as shown in the syntax diagram are:


ffdhe2048|ffdhe3072|ffdhe4096|ffdhe6144|ffdhe8192
modp1536|modp2048|modp3072|modp4096|modp6144|modp8192

Optionally specify the size of the private key in bits in parameter <number_of_priv_key_bits>.

dsa

specifies a DSA key pair (private and public) to be generated. In parameter <dsa_param_pem_file> you must specify the name of a PEM file containing the DSA-parameter for the key pair.

ibm-dilithium

specifies an IBM Dilithium key pair (private and public) to be generated. You must specify a version for the IBM Dilithium key pair. Select one supported version as shown in the syntax diagram.

ibm-kyber

specifies an IBM Kyber key pair (private and public) to be generated. You must specify a version for the IBM Kyber key pair. Select one supported version as shown in the syntax diagram.

--slot|-s

specifies the slot ID of an openCryptoki token within the repository.

--pin|-p

specifies the openCryptoki token User PIN. If not specified, the user can enter the PIN on request.

--no-login|-N

Do not login to the session. This means that only public token objects (CKA_PRIVATE=FALSE) can be accessed.

--so

Login as SO (security officer). Option --pin|-p must specify the SO pin, or if the --pin|-p option is not specified, environment variable PKCS11_SO_PIN is used. If PKCS11_SO_PIN is not set, then you are prompted for the SO PIN. The security officer (SO) can only access public token objects (CKA_PRIVATE=FALSE).

--force-pin-prompt

enforces a PIN prompt regardless whether a PIN has been specified elsewhere.

--label|-L

specifies the label (name) of the generated key. This option is mandatory.

For asymmetric keys, set individual labels for public and private key, separated by a colon: pub_label:priv_label, for example, rsa1_public:rsa1_private. You can use the same label for public and private keys by specifying the equal sign ('=') for the private key label part, for example, rsa1:=. If only one label is specified for an asymmetric key, the label is automatically extended by :pub and :prv for the public and private keys respectively, for example, --label rsa1 is extended to rsa1:pub and rsa1:prv.

--attr|-a

This parameter is optional and can be used to set one or more of the binary key attributes by specifying one or more of the respective letters from the subsequent list. With an upper case letter, the respective attribute is set to TRUE and with a lower case letter it is set to FALSE. For multiple attributes add the respective letters without space, for example: MLD or MrS.

For asymmetric keys set individual key attributes for public and private key separated by a colon: public_attributes:private_attributes, for example, MLD:MrS.

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 be set to TRUE by the security officer (SO) only)
I: CKA_WRAP_WITH_TRUSTED
K: CKA_IBM_PROTKEY_EXTRACTABLE (IBM specific, not all tokens support this)
Z: CKA_IBM_PROTKEY_NEVER_EXTRACTABLE (IBM specific, not all tokens support this, read only)

An uppercase letter sets the corresponding attribute to CK_TRUE, a lower case letter to CK_FALSE. If an attribute is not set explicitly, its default value is used. Not all attributes may be accepted for all key types. Attribute CKA_TOKEN is always set to CK_TRUE.

--id|-i

specifies a hex string (not prefixed with 0x) of any number of bytes. For asymmetric keys the same ID is set for both, the public and the private key.

Example for generating an RSA private and public key pair:

p11sak generate-key rsa 1024 --slot 1 --pin 11111111 –label test

The resulting key pair of this command is shown in Figure 4. If you do not specify attributes using the –attr option, the resulting key will obtain the default attributes as shown. Also, if you would specify the label using --label test:= , you get just test as the key names, without prv or pub appended.

Listing keys in the repository

The tool supports the listing of:

symmetric keys (AES, AES-XTS, 3DES, DES, SHA-HMAC, generic secret) with PKCS #11 attributes,
asymmetric keys (RSA, DH, DSA, EC, IBM Kyber, IBM Dilithium),
public, private and secret keys,
all keys of any type.

With the options in the list-key subcommand, you can filter the keys that you want to list. They have the same meaning as described in section Generating keys in the openCryptoki repository, with additional options to filter for public, private and secure keys. The --long or -l parameter produces the long output format. If omitted, you obtain a short output format.

Figure 3. p11sak syntax - Listing keys

The parameters and options for the p11sak list-key subcommand are the same as for the generate-key subcommand (Figure 2). Differences in the use and meaning are described hereafter.

In addition to the p11sak generate-key subcommand, there are the following key types which you can use to filter for listing keys:

secret: lists all symmetric keys (for example, AES and DES) that are created with the CKO_SECRET attribute.
public: lists the public key part of a public/private asymmetric key pair that is created with the CKO_PUBLIC_KEY attribute.
private: lists the private key part of a public/private asymmetric key pair (for example, AES and DES) that is created with the CKO_PRIVATE_KEY attribute.
all: lists all keys no matter of which type.

--attr|-a

Attributes whose letters are not specified in parameter list_of_attribute_letters are not used to filter the keys. The format of the list of attributes is shown in Figure 2.

--sort|-S <sort_specification>

Sort the keys by label, key type, object class, and key size. Specify a <sort_specification> parameter of up to four criteria, each represented by its corresponding letter, separated by a comma:

l: label
k: key type
c: object class
s: key size

The sort order (a = ascending (default), d = descending)) can be appended to the criteria designators by a colon. Example: l:a,k:d will sort by label in ascending order and then by key type in descending order.

--label|-L

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 (\\).

--detailed-uri

includes all information into the Unified Resource Identifier (URI). This detailed URI is only printed if the option --long has been specified. If this parameter is not set, the URI will not contain information about the library (CK_INFO) and the slot (CK_SLOT_INFO).

--hsm-mkvp|-m

shows the HSM master key verification patterns (MKVPs) of the key objects. Only valid for secure key tokens, such as CCA or EP11 tokens.

Example for a listing output in short format (default):

Figure 4. Listing RSA key pairs

# p11sak list-key rsa --slot 1 --pin 11111111

| P L M B Y R E D G C V O W U S A X N T I K Z |               KEY TYPE | LABEL
|---------------------------------------------+------------------------+--------------------
| 0 1 1 1 1 - 1 - - - 1 1 1 - - - - - 0 - - - |        public RSA 1024 | "test:pub"
| 0 1 1 1 1 - - 1 1 1 - - - 1 0 0 1 0 - 0 0 - |       private RSA 1024 | "test:prv"

2 key(s) displayed

How to get a listing output in long format

Request a long output format by specifying option --long or -l with the list-key command. You optionally can provide an output configuration file called p11sak_defined_attrs.conf to specify attributes to be printed in addition to the ones defined by the PKCS #11 standard. You can use the environment variable P11SAK_DEFAULT_CONF_FILE to set the full path name for this file. If this variable is not set, the system looks for this configuration file in your user directory. If no configuration file is found there, the default output configuration file /etc/opencryptoki/p11sak_defined_attrs.conf is used.

The output configuration file lists the desired attributes in the following format:


attribute {
   name = CKA_IBM_RESTRICTABLE
   id = 0x80010001
   type = CK_BBOOL
}
attribute {
   name = CKA_IBM_ATTRBOUND
   id = 0x80010004
   type = CK_BBOOL
}
attribute {
   name = CKA_IBM_USE_AS_DATA
   id = 0x80010008
   type = CK_BBOOL
}

Example for a listing output in long format:

# p11sak list-key rsa --slot 1 --pin 11111111 --detailed-uri --long
Please enter user PIN:

Label: "test:pub"
        URI: pkcs11:library-description=openCryptoki;library-manufacturer=IBM;
             library-version=3.20;slot-id=1;slot-description=Linux;slot-manufacturer=IBM;
             manufacturer=IBM;model=ICA;token=ica;object=test:pub;type=public
        Key: public RSA 1024
        Attributes:
             CKA_TOKEN: CK_TRUE
             CKA_PRIVATE: CK_FALSE
             CKA_LOCAL: CK_TRUE
             ...
             CKA_ALLOWED_MECHANISMS: [no restriction]
             CKA_SUBJECT: [no value]
             CKA_WRAP_TEMPLATE: 0 attributes
             CKA_PUBLIC_KEY_INFO: len=162 value:
                30 81 9F 30 0D 06 09 2A 86 48 86 F7 0D 01 01 01
                ...
             CKA_MODULUS: len=128 value:
                 C6 F3 7A E4 19 09 C5 6B C3 5F 21 1E 50 3A 0D 45
                 ...
             CKA_MODULUS_BITS: 1024 (0x400)
             CKA_PUBLIC_EXPONENT: len=3 value:
                 01 00 01
             CKA_IBM_PROTKEY_EXTRACTABLE: CK_FALSE
Label: "test:prv"
    URI: pkcs11:library-description=openCryptoki;library-manufacturer=IBM;library-version=3.20;slot-id=1;slot-description=Linux;slot-manufacturer=IBM;manufacturer=IBM;model=ICA;token=ica;object=test:prv;type=private
    Key: private RSA 1024
    Attributes:
         CKA_TOKEN: CK_TRUE
         CKA_PRIVATE: CK_FALSE
         CKA_LOCAL: CK_TRUE
         ...
         CKA_ALLOWED_MECHANISMS: [no restriction] 
         CKA_SUBJECT: [no value]
         CKA_UNWRAP_TEMPLATE: 0 attributes
         CKA_PUBLIC_KEY_INFO: len=162 value:
             30 81 9F 30 0D 06 09 2A 86 48 86 F7 0D 01 01 01
             ...
         CKA_DERIVE_TEMPLATE: 0 attributes 
         CKA_MODULUS: len=128 value:
             C6 F3 7A E4 19 09 C5 6B C3 5F 21 1E 50 3A 0D 45
             ...
         CKA_PUBLIC_EXPONENT: len=3 value:
             01 00 01
         CKA_PRIVATE_EXPONENT: [no value]
         CKA_PRIME_1: len=64 value:
             ED 9D EC 54 69 F2 C6 BE F7 04 4C 70 46 3B 64 EB
             ...
         CKA_PRIME_2: len=64 value:
             D6 57 C4 CB F4 25 FE F3 E8 6C AD 12 89 29 19 0E
             ...
         CKA_EXPONENT_1: len=64 value:
             8F 42 1F 31 E5 8E 91 74 A0 C8 DE AC F2 2A EC F5
             ...
         CKA_EXPONENT_2: len=64 value:
             68 12 93 A6 67 F4 6E F7 64 FA 27 8A E1 78 48 07
             ...
         CKA_COEFFICIENT: len=64 value:
             91 00 D0 24 BD 15 7A 27 57 C8 81 A4 F2 C3 62 F5
             ...
         CKA_IBM_PROTKEY_EXTRACTABLE: CK_FALSE

2 key(s) displayed

Examples for listing the master key verification patterns for an EP11 token in short and long format:

# p11sak ls --slot 4 --hsm-mkvp
| MASTER KEY VERIFICATION PATTERN  | MK TYPE  |               KEY TYPE | LABEL
|----------------------------------+----------+------------------------+--------------------
| 8B991263E3A8F4E4BE0D5EC8F0A4DF9E | EP11-WK  |                AES 256 | "aes256"
| 8B991263E3A8F4E4BE0D5EC8F0A4DF9E | EP11-WK  |        public RSA 2048 | "rsa2048:pub"
| 8B991263E3A8F4E4BE0D5EC8F0A4DF9E | EP11-WK  |       private RSA 2048 | "rsa2048:prv"


# p11sak ls --slot 4 --hsm-mkvp --long 
Label: "aes256"
    URI: pkcs11:manufacturer=IBM;model=EP11;serial=93AADFK711976872;token=ep11;object=aes256;type=secret-key
    Key: AES 256
    MKVP: 8B991263E3A8F4E4BE0D5EC8F0A4DF9E (EP11-WK)
    Attributes:
        CKA_TOKEN: CK_TRUE
        CKA_PRIVATE: CK_FALSE
        CKA_LOCAL: CK_FALSE
       …

Examples for listing the master key verification patterns for a CCA token in short and long format:

# p11sak ls --slot 2 --hsm-mkvp
| MASTER KEY VERIFICATION PATTERN  | MK TYPE  |               KEY TYPE | LABEL
|----------------------------------+----------+------------------------+--------------------
| -                                | -        |              public EC | "EC-key:pub"
| 5F2F27AAA2D59B4A                 | CCA APKA |             private EC | "EC-key:prv"
| E9A49A58CD039BED                 | CCA AES  |                AES 256 | "aes256"


# p11sak ls --slot 2 --hsm-mkvp --long
Label: "aes256"
    URI: pkcs11:manufacturer=IBM;model=CCA;token=cca;object=aes256;type=secret-key
    Key: AES 256
    MKVP: E9A49A58CD039BED (CCA AES)
    Attributes:
        CKA_TOKEN: CK_TRUE
        CKA_PRIVATE: CK_FALSE
        CKA_LOCAL: CK_TRUE
        …

Removing keys

Use the p11sak remove-key subcommand to delete keys from the openCryptoki token repository.

Figure 5. p11sak syntax - Removing keys

The parameters and options for the p11sak remove-key subcommand that are not listed here, are the same as for the generate-key subcommand. Differences in the use and meaning are described hereafter.

With the parameters you can select the key or the keys that you want to delete:

Use the <key_type> parameter to select the type or types of keys to be deleted. Possible values for the <key_type> argument are the following (as explained in Figure 2 and Listing keys in the repository):

des|3des|generic|aes|aes−xts|rsa|dh|dsa|ec|ibm−dilithium|ibm-kyber|public|private|secret|all

If <key_type> is omitted, then all key types are selected for deleting.

--slot|-s: specifies the slot ID of an openCryptoki token within the repository from which you want to delete the matching keys.
--id|-i: specifies a hex string (not prefixed with 0x) of any number of bytes. For asymmetric keys the same ID is set for both, the public and the private key.
--attr|-a: Attributes whose letters are not specified in this list are not used to filter the keys.

You are prompted to confirm the deletion of the selected key or keys. To suppress the confirmation, use the --force|-f option.

Setting attributes of keys

Use the p11sak set-key-attr subcommand and the optional key_type 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.

Figure 6. p11sak syntax - Setting attributes of keys

Most of the options are the same as used for and explained in Figure 2 .

Use the <key_type> parameter to select the type or types of keys to be updated. Possible values for the <key_type> parameter are the following (as explained in Figure 2 and Listing keys in the repository):

des|3des|generic|aes|aes−xts|rsa|dh|dsa|ec|ibm−dilithium|ibm-kyber|public|private|secret|all

If <key_type> is omitted, then all key types are selected for updating.

Specify the −−label|−L <key_name>, the −−id|−i <id_hex_string>, or the −−attr|−a <list_of_attribute_letters> options to filter the keys to be updated. The <id_hex_string> must be specified as hex string (not prefixed with 0x) of any number of bytes. You can use wildcards (* and ?) in the <key_name> specification.

Use the --new-attr|-A <list_of_attribute_letters> option to specify the boolean attributes of the key you want to update. Keys can be filtered by all attributes, setting is possible for all except L | A | N | Z. An uppercase letter sets the corresponding attribute to CK_TRUE, a lower case letter to CK_FALSE. If an attribute is not set explicitly, its value is not changed. Not all attributes may be allowed to be changed for all key types, or to all values.

The boolean attributes to set for the filtered key or keys:


P | M | B | Y | R | E | D | G | C | V | O | W | U | S | X | T | I | K
p | m | b | y | r | e | d | g | c | v | o | w | u | s | x | t | i | k

Use the −−new−label|−l <key_name> option to specify the new label, or use the −−new−id|−I <id_hex_string> option to specify the new ID to be set for the key.

At least one of the --new-attr|-A <list_of_attribute_letters>, −−new−label|−l <key_name>, or −−new−id|−I <id_hex_string> options must be specified.

You are prompted to confirm the updating of the key or keys. To suppress the prompt, use the −−force|−f option.

Copying keys in the repository

Use the p11sak copy-key subcommand to copy symmetric or asymmetric keys. You can change attributes, the label, or the ID of the copied key or keys.

Figure 7. p11sak syntax - Copying keys in the repository

The parameters are the same as for Setting attributes of keys.

Use the <key_type> parameter to select the type or types of keys to be copied. Possible values for the <key_type> argument are the following (as explained in Figure 2 and Listing keys in the repository):

des|3des|generic|aes|aes−xts|rsa|dh|dsa|ec|ibm−dilithium|ibm-kyber|public|private|secret|all

If <key_type> is omitted, then all key types are selected for copying.

Besides filtering the keys to be copied by the key types, use the −−attr|−a <list_of_attribute_letters> options to additionally filter the keys with matching key types by their attributes.

Use the --new-attr|-A <list_of_attribute_letters> option to specify the boolean attributes to be set for the copied key(s). Attributes that are not specified are not set. Restrictions on attribute values may apply.

Keys can be filtered by all attributes, setting is possible for all except L | A | N | Z. An uppercase letter sets the corresponding attribute to CK_TRUE, a lower case letter to CK_FALSE. If an attribute is not set explicitly, its value is not changed. Not all attributes may be allowed to be changed for all key types, or changed to all values.

The boolean attributes to set for the key or keys to be copied:


P | M | B | Y | R | E | D | G | C | V | O | W | U | S | X | T | I | K
p | m | b | y | r | e | d | g | c | v | o | w | u | s | x | t | i | k

Use the −−new−label|−l <key_name> option to specify the new label to be stet for the copied key or keys (optional).

Use the −−new−id|−I <id_hex_string> option to specify the new ID to be set for the copied key or keys (optional).

Importing keys from a binary file or a PEM file

Use the p11sak import-key subcommand together with the <key_type> argument to import symmetric or asymmetric keys from a file.

Figure 8. p11sak syntax - Importing keys from a binary file or a PEM file

The options and parameters that are specific to the import−key subcommand have the following meaning:

<key_type>

Possible values for the <key_type> argument are:

des|3des|generic|aes|aes−xts|rsa|dh|dsa|ec|ibm−dilithium|ibm-kyber|public|private|secret|all

<kind>

When importing an asymmetric key, the <kind> argument is required and specifies to either import a private or public key.

--pem-password|-P <password>

PEM files can optionally be password protected. Specify the PEM password with this option or environment variable P11SAK_PEM_PASSWORD. If the PEM file is password protected, but no PEM password is specified, you are prompted for the PEM password.

--oqsprovider-pem

The key material in the PEM file specified with the -F/--file 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. This is an experimental feature, it may change in an incompatible way in the future!

--opaque|-o

Specify this option to import the opaque secure key blobs of the key. Not all tokens support this.

Other options have a similar purpose as in previously described options. The −−label|−L <key_name> option sets the CKA_LABEL attribute of the key and the option −−attr|−a <list_of_attribute_letters> can be used to set the boolean attributes of the key as described in Generating keys in the openCryptoki repository. Use the −−id|−i <id_hex_string> option to set the value of the CKA_ID attribute of the key.

Exporting keys to a binary file or a PEM file

Use the p11sak export-key|export|exp subcommand and the optional <key_type> parameter to export symmetric and asymmetric keys to a file. Public, private, secret, or all keys can also be selected for export, irrespective of the key type.

Figure 9. p11sak syntax -Exporting keys to a binary file or a PEM file

Possible values for the <key_type> argument are:

des|3des|generic|aes|aes−xts|rsa|dh|dsa|ec|ibm−dilithium|ibm-kyber|public|private|secret|all

If <key_type> is omitted, then all key types are selected for export.

Specify one or more of the −−label|−L <key_name>, the −−id|−i <id_hex_string>, or the −−attr|−a <list_of_attribute_letters> options to filter the list of keys for which to change the attributes. You can use wildcards (* and ?) in the <key_name> specification. The −−id|-i option must be specified as hex string (not prefixed with 0x) of any number of bytes.

The −−file|−F <file_name> 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 <file_name> 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.

Option --oqsprovider-pem has the same meaning as for Importing keys from a binary file or a PEM file.

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.

Extracting the public key from a private key

Use the p11sak extract-pubkey subcommand to extract the public key from a private key. Use the label, the ID and existing attributes to filter the private key from which you want to extract the public key.

Figure 10. p11sak syntax - Extracting the public key from a private key

where the following arguments and options have a specific use or meaning for this subcommand:

<key_type>

Optional. The type of the private key from which you want to extract the public key. If no key type is specified, all private key types are selected. Possible values for the <key_type> parameter are:

rsa|dh|dsa|ec|ibm−dilithium|ibm-kyber|private|all

--attr|-a

Optional. Filter the key by its boolean attribute values:

P | L | M | B | Y | R | E | D | G | C | V | O | W | U | S | A | X | N | T | I | K | Z

Specify a set of these letters without any blanks in between. The meaning for each of the attribute letters is explained in Generating keys in the openCryptoki repository. Attributes that are not specified are not used to filter the keys.

--new-attr|-A

Optional. The boolean attributes to set for the extracted public key:


P | M | B | Y | R | E | D | G | C | V | O | W | U | S | X | T | I | K
p | m | b | y | r | e | d | g | c | v | o | w | u | s | x | t | i | k

Specify a set of these letters without any blanks in between. The meaning for each of the attribute letters is explained in Generating keys in the openCryptoki repository. Restrictions on attribute values may apply.

Note: Keys can be filtered by all attributes, setting is possible for all except

L |
A | N | Z

.

An uppercase letter sets the corresponding attribute to CK_TRUE, a lower case letter to CK_FALSE. If an attribute is not set explicitly, its value is not changed. Not all attributes may be allowed to be changed for all key types, or to all values.

--new-label|-l

The new label to set for the extracted public key (optional). If no new label is specified, the new label is derived from the private key label by appending _pubkey.

--new-id|-I

Optional. The new ID to be set for the extracted public key.

Listing certificates in the repository

Use the p11sak list-cert subcommand to show existing certificates that match the specified parameters. As for keys, there is a short and a long output. Matching certificates can be sorted by label and common name.

Figure 11. p11sak syntax - Listing certificates

where the following arguments and options have a specific use or meaning for this subcommand:

<cert_type>

The type of the certificate to be listed. If no certificate type is specified, certificate type x509 is used.

--attr|-a

Filter the certificate by its boolean attribute values: P M B Y T (optional). Specify a set of these letters without any blanks in between. Attributes that are not specified are not used to filter the certificates. For the meaning of these attributes, see Generating keys in the openCryptoki repository.

--sort|-S <sort_specification>

Sort the certificates by label or subject common name (CN), or both. Specify a sort specification of up to two fields, each represented by its corresponding letter, separated by comma:

l: label
n: subject common name

The sort order (default: a = ascending, d = descending) can be appended to the criteria designators by a colon. Example: l:a,n:d sorts by label in ascending order and then by common name in descending order.

All other options are explained in Figure 2 or in Listing keys in the repository.

Example of a short output

# p11sak list-cert x509 --slot 4 --pin 11111111

| P M B Y T | CERT TYPE | SUBJECT-CN             | LABEL
|-----------+-----------+------------------------+-------------------------
| 1 1 1 1 - | X.509     | /C=DE/ST=BB/L=BB/O=... | mycert2
| 0 1 1 1 - | X.509     | system1                | mycert1
| 0 1 1 1 - | X.509     | user1                  | dsacert1

To obtain a long output, specify a command similar to the following:

# p11sak list-cert x509 --slot 4 --pin 11111111 --long

Removing certificates from the repository

Use the p11sak remove-cert subcommand to delete certificates in the repository.

Figure 12. p11sak syntax - Removing certificates

The arguments and options have the same meaning as described in Figure 2 or Listing certificates in the repository.

Setting or updating attributes of certificates

Use the p11sak set-cert-attr subcommand to set or update boolean attributes of certificates. Optionally, a new label, a new ID, and new attributes can be specified for the token object.

Figure 13. p11sak syntax - Setting or updating attributes of certificates

where the following argument is specific for this subcommand:

<cert_type>: The type of the certificate. Must be set to x509.

The other arguments and options have the same meaning as described in Setting attributes of keys or Listing certificates in the repository.

Copying certificates in the repository

Use the p11sak copy-cert subcommand to copy certificates in the repository.

Figure 14. p11sak syntax - Copying certificates in the repository

The following arguments and options have a specific use or meaning for this subcommand:

<cert_type>: The type of the certificate to be listed. If no certificate type is specified, certificate type x509 is used.
--attr|-a: Filter the certificate by its boolean attribute values: P M B Y T (optional). Specify a set of these letters without any blanks in between. Attributes that are not specified are not used to filter the certificates. For the meaning of these attributes, see Generating keys in the openCryptoki repository.

All other options and parameters are the same as for Generating keys in the openCryptoki repository or for Setting attributes of keys.

Importing certificates from a binary file or a PEM file

Use the p11sak import-cert subcommand to import x.509 public certificates into the openCryptoki token repository. Importing is supported in two formats: Base64 (PEM) form and binary (DER-encoded) form. The format is detected from the given input and does not need to be specified as input parameter.

Figure 15. p11sak syntax - Importing certificates from a binary file or a PEM file

where the following arguments and options are specific for this subcommand:

<cert_type>: The type of the certificate. Must be set to x509.
--attr|-a: The boolean attributes to set for the certificate: P M B Y (optional). Specify a set of these letters without any blanks in between. For the meaning of these attributes, see Generating keys in the openCryptoki repository.
--file|-F: The 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.
--ca-cert|-C: The certificate is a Certificate Authority (CA) certificate.

Exporting certificates to a binary file or PEM file

Use the p11sak export-cert subcommand to export certificates. Exporting of public key certificates is supported in two formats: Base64 (PEM) and binary (DER encoding). The default is PEM. Exporting multiple certificates into the same output file is only possible in PEM format.

Figure 16. p11sak syntax -Export certificates to a binary file or a PEM file

where the following arguments and parameters are specific for this subcommand:

<cert_type>: The type of the certificate. Must be set to x509.
--attr|-a: Filter the certificate by its boolean attribute values: P M B Y T (optional). Specify a set of these letters without any blanks in between. Attributes that are not specified are not used to filter the certificates. For the meaning of these attributes, see Generating keys in the openCryptoki repository.
--der|-D: The certificate is written to the file in binary (DER-encoded) form. Default is Base64 (PEM).

The other options and parameters are the same as for Exporting keys to a binary file or a PEM file.

Extracting public keys from certificates

Use the p11sak extract-cert-pubkey subcommand to extract the public key of a given certificate into a new token object. Supported public key types are RSA, EC, and DSA. If no new label is specified as input parameter, the labels for extracted public keys are derived from the certificate labels by appending _pubkey.

Figure 17. p11sak syntax - Extract the public keys from certificates

where the following argument is specific for this subcommand:

<cert_type>: The type of the certificate. Must be set to x509.

The other parameters are the same as for Extracting the public key from a private key.

Command help

Request general help with the following command:

# p11sak -h

to receive the following information:

Usage: p11sak COMMAND [ARGS] [OPTIONS]

COMMANDS:
    generate-key                   Generate a key.
    list-key                       List keys in the repository.
    remove-key                     Delete keys in the repository.
    set-key-attr                   Set attributes of keys in the repository.
    copy-key                       Copy keys in the repository.
    import-key                     Import a key from a binary file or PEM file.
    export-key                     Export keys to a binary file or PEM file.
    extract-pubkey                 Extract the public key from private keys in
                                   the repository.
    list-cert                      List certificates in the repository.
    remove-cert                    Delete certificates in the repository.
    set-cert-attr                  Set attributes of certificates in the
                                   repository.
    copy-cert                      Copy certificates in the repository.
    import-cert                    Import a certificate from a binary file or
                                   PEM file.
    export-cert                    Export certificates to a binary file or PEM
                                   file.
    extract-cert-pubkey            Extract the public key from certificates in
                                   the repository.


COMMON OPTIONS
    -h, --help                     Print this help, then exit.
    -v, --version                  Print version information, then exit.

For more information use 'p11sak COMMAND --help'.

Request help for a subcommand:


# p11sak copy-key -h
# p11sak export-key -h
# p11sak extract-pubkey -h
# p11sak generate-key -h  (see Figure 18 and Figure 19)
# p11sak import-key -h
# p11sak list-key -h
# p11sak remove-key -h
# p11sak set-key-attr -h

# p11sak copy-cert -h
# p11sak export-cert -h
# p11sak extract-cert-pubkey -h
# p11sak import-cert -h
# p11sak list-cert -h
# p11sak remove-cert -h
# p11sak set-cert-attr -h

For the generate-key subcommand, you receive the following information:

Figure 18. Request help for generate-key

# p11sak generate-key -h

Usage: p11sak generate-key [ARGS] [OPTIONS]

ARGS:
    KEYTYPE                        The type of the key. One of the following:
        des
        3des
        generic KEYBITS

            KEYBITS                Size of the generic key in bits.
            ...
        rsa KEYBITS [PUBL-EXP]

            KEYBITS                Size of the RSA key in bits:
                512
                ...
            PUBL-EXP               The public exponent for RSA (optional).

        dh GROUP [PRIV-BITS]

            GROUP                  The Diffie-Hellman FFC group name or the
                                   name of a DH parameters PEM file:
                ffdhe2048
                ...
                modp1536
                ...
                DH-PARAM-PEM-FILE
            PRIV-BITS              Size of the DH private key in bits
                                   (optional).

        dsa DSA-PARAM-PEM-FILE     The name of a DSA parameters PEM file.

        ec CURVE

            CURVE                  The curve name. One of the following:
                prime256v1
                ...        
                ed448

        ibm-dilithium VERSION

            VERSION                The version of the IBM Dilithium key pair:
                r2_65
                ...
        ibm-kyber VERSION

            VERSION                The version of the IBM Kyber key pair:
                r2_768
                ...

OPTIONS:
    -s, --slot SLOT                The PKCS#11 slot ID.
    -p, --pin USER-PIN             The PKCS#11 user pin. If this option is not
                                   specified, ...
        --force-pin-prompt         Enforce user PIN prompt, even if environment
                                   variable PKCS11_USER_PIN is set, ...
    -L, --label LABEL              The label of the key to be generated. 
                                   ...
    -a, --attr ATTRS               The boolean attributes to set for the key:
                                   P L M B Y R E D G C V O W U S A X N T I   ...
    -i, --id ID                    The ID of the key to be generated.   ...
    -h, --help                     Print this help, then exit.
    -v, --version                  Print version information, then exit.

ATTRIBUTES:
    'P':   CKA_PRIVATE
    'M':   CKA_MODIFIABLE
    ...

    An uppercase letter sets the corresponding attribute to CK_TRUE, a lower case letter to CK_FALSE.
    If an attribute is not set explicitly, its default value is used.   ...

For the generate-key subcommand, you can request help for a selected key type, for example, for an AES key:

Figure 19. Request help for generating AES keys

# p11sak generate-key aes -h

Usage: p11sak generate-key [ARGS] [OPTIONS]

ARGS:
    KEYTYPE                        The type of the key. One of the following:
        aes KEYBITS

            KEYBITS                Size of the AES key in bits:
                128
                192
                256

OPTIONS:
    -s, --slot SLOT                The PKCS#11 slot ID.
    -p, --pin USER-PIN             The PKCS#11 user pin. If this option is not
                                   specified, ...
        --force-pin-prompt         Enforce user PIN prompt, even if environment
                                   variable PKCS11_USER_PIN is set, ...
    -L, --label LABEL              The label of the key to be generated. For
                                   asymmetric keys set individual labels for
                                   public and private key, ...
    -a, --attr ATTRS               The boolean attributes to set for the key:
                                   P L M B Y R E D G C V O W U S A X N T I
                                   (optional). ...
    -i, --id ID                    The ID of the key to be generated. ...
    -h, --help                     Print this help, then exit.
    -v, --version                  Print version information, then exit.

ATTRIBUTES:
    'P':   CKA_PRIVATE
    'M':   CKA_MODIFIABLE
    'B':   CKA_COPYABLE
 ...

    An uppercase letter sets the corresponding attribute to CK_TRUE, a lower
    case letter to CK_FALSE.
    If an attribute is not set explicitly, its default value is used.
    Not all attributes may be accepted for all key types.
    Attribute CKA_TOKEN is always set to CK_TRUE.