Provided by: opencryptoki_3.20.0+dfsg-0ubuntu1_amd64 
NAME
p11sak - generate and list token keys in an openCryptoki token repository.
SYNOPSIS
p11sak command [ARGS] [OPTIONS]
p11sak --help|-h
DESCRIPTION
p11sak can be used to generate, list and delete the token keys in an openCryptoki token
repository. The utility provides a flexible key management tool in openCryptoki to list
and generate symmetric (DES, 3DES, AES, AES-XTS) and asymmetric (RSA, EC, IBM Dilithium,
IBM Kyber) keys. This tool is especially capable of a well defined listing of keys with
their PKCS #11 attributes.
COMMANDS
The p11sak tool can operate in three modes: when command generate-key is specified, it
operates in the mode to generate a token key in the openCryptoki token repository. If
command list-key is given, it lists the keys specified in the arguments. If command
remove-key is given, it removes the keys specified in the arguments.
generate-key
Use the generate-key|gen-key|gen command and key argument to generate a token key with the
respective [ARGS] and [OPTIONS]. The --help|-h option will show the arguments and options
available.
list-key
Use the list-key|ls-key|ls command and key argument to list token keys given the
respective [ARGS] and [OPTIONS]. The --help|-h option will show the arguments and options
available.
remove-key
Use the remove-key|rm-key|rm command and key argument to delete token keys given the
respective [ARGS] and [OPTIONS]. The --help|-h option will show the arguments and options
available.
Generating DES/3DES keys
p11sak generate-key|gen-key|gen des|3des --slot SLOTID --pin PIN --label LABEL --attr
[PMRLSEDGVWUAXNT] --help | -h
Use the generate-key command with the des|3des key argument to generate a DES or 3DES key.
The --slot SLOTID and --pin PIN options are required to set the token to SLOTID and the
token PIN. The --label option allows the user to set the LABEL attribute of the key and
--attr [PMRLSEDGVWUAXNT] can be used to set the binary attributes of the key (see below
for detailed description of the attributes).
Generating AES keys
p11sak generate-key|gen-key|gen aes 128|192|256 --slot SLOTID --pin PIN --label LABEL
--attr [PMRLSEDGVWUAXNT] --help | -h
Use the generate-key aes 128|192|256 command and key argument to generate a AES key with
128, 192 or 256 bit length, respectively. The --slot SLOTID and --pin PIN options are
required to set the token to SLOTID and the token PIN. The --label option allows the user
to set the LABEL attribute of the key and --attr [PMRLSEDGVWUAXNT] can be used to set the
binary attributes of the key (see below for detailed description of the attributes).
Generating AES-XTS keys
p11sak generate-key|gen-key|gen aes-xts 128|256 --slot SLOTID --pin PIN --label LABEL
--attr [PMRLSEDGVWUAXNT] --help | -h
Use the generate-key aes-xts 128|256 command and key argument to generate a AES-XTS key
with 128 or 256 bit length, respectively. The --slot SLOTID and --pin PIN options are
required to set the token to SLOTID and the token PIN. The --label option allows the user
to set the LABEL attribute of the key and --attr [PMRLSEDGVWUAXNT] can be used to set the
binary attributes of the key (see below for detailed description of the attributes).
Generating RSA keys
p11sak generate-key|gen-key|gen rsa 1024|2048|4096 --slot SLOTID --pin PIN --label LABEL
--exponent EXP --attr [PMRLSEDGVWUAXNT] --help | -h
Use the generate-key rsa 1024|2048|4096 command and key argument to generate a 1024, 2048
or 4096 bit RSA key, respectively. The --slot SLOTID and --pin PIN options are required to
set the token to SLOTID and the token PIN. The --label option allows the user to set the
LABEL attribute of the key and --attr [PMRLSEDGVWUAXNT] can be used to set the binary
attributes of the key (see below for detailed description of the attributes). Furthermore,
the --exponent EXP options 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 EC keys
p11sak generate-key|gen-key|gen ec CURVE --slot SLOTID --pin PIN --label LABEL --attr
[PMRLSEDGVWUAXNT] --help | -h
Use the generate-key ec CURVE command and key argument to generate an EC key, where CURVE
specifies the eliptic 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 --slot SLOTID and --pin PIN options are required to
set the token to SLOTID and the token PIN. The --label option allows the user to set the
LABEL attribute of the key and --attr [PMRLSEDGVWUAXNT] can be used to set the binary
attributes of the key (see below for detailed description of the attributes).
Generating IBM Dilithium keys
p11sak generate-key|gen-key|gen ibm-dilithium VERSION --slot SLOTID --pin PIN --label
LABEL --attr [MRLSEDGVWUAXNT] --help | -h
Use the generate-key ibm-dilithium VERSION command and key argument to generate an IBM
Dilithium key, 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
The --slot SLOTID and --pin PIN options are required to set the token to SLOTID and the
token PIN. The --label option allows the user to set the LABEL attribute of the key and
--attr [MRLSEDGVWUAXNT] can be used to set the binary attributes of the key (see below for
detailed description of the attributes).
Generating IBM Kyber keys
p11sak generate-key|gen-key|gen ibm-kyber VERSION --slot SLOTID --pin PIN --label LABEL
--attr [M R L S E D G V W U A X N T] --help | -h
Use the generate-key ibm-kyber VERSION command and key argument to generate an IBM Kyber
key, where VERSION specifies the version of the IBM Kyber keypair. The following arguments
can be used for respective keys: r2_768 | r2_1024
The --slot SLOTID and --pin PIN options are required to set the token to SLOTID and the
token PIN. The --label option allows the user to set the LABEL attribute of the key and
--attr [M R L S E D G V W U A X N T] can be used to set the binary attributes of the key
(see below for detailed description of the attributes).
Listing symmetric and asymmetric keys
p11sak list-key|ls-key|ls des|3des|aes|aes-xts|rsa|ec|ibm-dilithium|ibm-
kyber|public|private|secret|all --slot SLOTID --pin PIN --label LABEL --long | -l --help |
-h
Use the list-key | ls-key | ls command and key argument to list DES, 3DES, AES, AES-XTS,
RSA, EC, IBM Dilithium, or IBM Kyber keys, respectively. Public, private, secret, or all
keys can also be listed irrespective of key type.
Deleting symmetric and asymmetric keys
p11sak remove-key|rm-key|rm des|3des|aes|aes-xts|rsa|ec|ibm-dilithium|ibm-kyber --slot
SLOTID --pin PIN --label LABEL --force | -f --help | -h
Use the remove-key | rm-key | rm command and key argument to delete DES, 3DES, AES, AES-
XTS, RSA, EC, IBM Dilithium, or IBM Kyber keys, respectively. All specified cipher keys
will be prompted to be deleted unless a specific key with the --label LABEL argument is
selected. The user will be promted to confirm the deletion of the key. To suppress the
promt, use the --force | -f option.
ARGS
des | 3des | aes | aes-xts | rsa | ec | ibm-dilithium | ibm-kyber | public | private | secret
| all
selects the respective symmetric or asymmetric key to be generated or listed. The
public|private|secret|all argument can only be used with the list-key command to list
either public, private, secret, or all keys.
128|192|256
the aes argument has to be followed by either 128, 192 or 256 to set the respective key
bit length of the AES key.
128|256
the aes-xts argument has to be followed by either 128 or 256 to set the respective key bit
length of the AES-XTS key.
1024|2048|4096
the rsa argument has to be followed by either 1024, 2048 or 4096 to set the respective key
bit length of the RSA key.
prime256v1 | prime192 | secp224 | secp384r1 | secp521r1 | secp265k1 | brainpoolP160r1 |
brainpoolP160t1 | brainpoolP192r1 | brainpoolP192t1 | brainpoolP224r1 | brainpoolP224t1 |
brainpoolP256r1 | brainpoolP256t1 | brainpoolP320r1 | brainpoolP320t1 | brainpoolP384r1 |
brainpoolP384t1 | brainpoolP512r1 | brainpoolP512t1 | curve25519 | curve448 | ed25519 |
ed448
the ec argument has to be followed by either of these CURVE to select the EC curve used to
generate the key.
r2_6|r2_87|r3_44|r3_65|r3_875
the ibm-dilithium argument has to be followed by either of these VERSION to select the IBM
dilithium version used to generate the key.
r2_768|r2_1024
the ibm-kyber argument has to be followed by either of these VERSION to select the IBM
kyber version used to generate the key.
OPTIONS
--slot SLOTID
sets the token to SLOTID
--pin PIN
sets the token PIN to PIN
Alternatively the PKCS11_USER_PIN environment variable may be used to provide the token
PIN.
--force-pin-prompt
enforce p11sak to prompt for the token PIN (regardless if it has been specified elsewhere)
--label LABEL
sets the key label attribute to LABEL
For 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 specification.
--exponent EXP
sets the RSA exponent to EXP
--attr [P M R L S E D G V W U A X N T]
sets the binary attributes of a key.
Note: not all binary attributes are applicable to all keys and will be omitted if not
applicable.
The attributes are set to FALSE by default and switched to TRUE when the letter that is
associated with the given binary attribute is specified. The following letters are
associated with the respective CK_ATTRIBUTE:
• P - CKA_PRIVATE
• M - CKA_MODIFIABLE
• R - CKA_DERIVE
• L - CKA_LOCAL
• S - CKA_SENSITIVE
• E - CKA_ENCRYPT
• D - CKA_DECRYPT
• G - CKA_SIGN
• V - CKA_VERIFY
• W - CKA_WRAP
• U - CKA_UNWRAP
• A - CKA_ALWAYS_SENSITIVE
• X - CKA_EXTRACTABLE
• N - CKA_NEVER_EXTRACTABLE
• * - if in p11sak_defined_attrs.conf additional attributes are defined.
CKA_TOKEN and CKA_PRIVATE are set by default to TRUE. For multiple attributes, combine
the letters in a string without white space, e. g. 'MlD'. An uppercase letter means true,
while an lowercase letter equals false. From Example above: CKA_MODIFIABLE=true,
CKA_LOCAL=false, CKA_DECRYPT=true
For asymmetric keys a user can set different custom attributes for the public and the
private key. The separator is the symbol ":". The defined attributes in front of the
separator are set for the public key and the attributes defined after the separator are
set for the private key. When the separator is not in the string, the defined attribute
set is used for public and private key. To set a configuration for only the public key,
the string has to end with the separator and respectively, to use a configuration for the
private key only, the string has to start with the separator.
--long | -l
prints the list-key output in long format. If omitted, the output is in a short, tabular
format.
--force | -f
to be used with the remove-key command to suppress the promt whether the user wants to
delete the specified keys.
--help | -h
prints help for the usage of p11sak and/or the respective command.
FILES
/usr/local/etc/opencryptoki/p11sak_defined_attrs.conf
In the output config file a user can define additional attributes, which are not mentioned
in the PKCS#11 standard. A custom filepath can be set with an environment variable.
ENVIRONMENT VARIABLES
P11SAK_DEFAULT_CONF_FILE
A custom path for p11sak_defined_attrs.conf can be set with the environment variable
P11SAK_DEFAULT_CONF_FILE. If none is set p11sak will first look for the file in the user
directory, followed by the standard installation path.
PKCS11_USER_PIN
The token PIN can be specified via the environment variable PKCS11_USER_PIN. If nothing
is set and the option --pin is not specified, p11sak will prompt for the token PIN
interactively.
EXIT STATUS
p11sak returns various error codes on fail:
CKR_ARGUMENTS_BAD (0x00000007):
The p11sak_defined_attrs.conf is not found.
CKR_DATA_INVALID (0x00000020):
The p11sak_defined_attrs.conf cannot be parsed or syntax is invalid.
CKR_ATTRIBUTE_TYPE_INVALID (0x00000012):
A given attribute type cannot be set for this key.
SEE ALSO
p11sak_defined_attrs.conf(5)