pkcs11-tool1OpenSCOpenSC Toolsopenscpkcs11-toolutility for managing and using PKCS #11 security tokenspkcs11-toolOPTIONSDescription
The pkcs11-tool utility is used to manage the
data objects on smart cards and similar PKCS #11 security tokens.
Users can list and read PINs, keys and certificates stored on the
token. User PIN authentication is performed for those operations
that require it.
OptionsfilenameExtract information from filename
(DER-encoded certificate file) and create the corresponding
attributes when writing an object to the token. Example: the
certificate subject name is used to create the CKA_SUBJECT
attribute.
,
Change the user PIN on the tokenUnlock User PIN (without
unlock in logged in session; otherwise
has to be 'context-specific').
,
Hash some data.mechanism
Specify hash algorithm used with RSA-PKCS-PSS signature or RSA-OAEP decryption.
Allowed values are "SHA-1", "SHA256", "SHA384", "SHA512", and some tokens may
also allow "SHA224". Default is "SHA-1".
Note that the input to RSA-PKCS-PSS has to be of the size equal to
the specified hash algorithm. E.g., for SHA256 the signature input must
be exactly 32 bytes long (for mechanisms SHA256-RSA-PKCS-PSS there is no
such restriction). For RSA-OAEP, the plaintext input size mLen must be
at most keyLen - 2 - 2*hashLen. For example, for RSA 3072-bit key and
SHA384, the longest plaintext to encrypt with RSA-OAEP is (with all
sizes in bytes): 384 - 2 - 2*48 = 286, aka 286 bytes.
id,
idSpecify the id of the object to operate on.Initializes the user PIN. This option
differs from in that it sets the user PIN
for the first time. Once set, the user PIN can be changed
using .Initialize a token: set the token label as
well as a Security Officer PIN (the label must be specified
using ).filename,
filenameSpecify the path to a file for input.
,
Generate a new key pair (public and private pair.)Generate a new key.specificationSpecify the type and length of the key to create, for example rsa:1024 or EC:prime256v1.Specify 'sign' key usage flag (sets SIGN in privkey, sets VERIFY in pubkey).Specify 'decrypt' key usage flag (RSA only, set DECRYPT privkey, ENCRYPT in pubkey).Specify 'derive' key usage flag (EC only).name,
nameSpecify the name of the object to operate on
(or the token label when
is used).
,
Display a list of mechanisms supported by the token.
,
Display a list of objects.
,
Display a list of available slots on the token.
,
List slots with tokens.
,
Authenticate to the token before performing
other operations. This option is not needed if a PIN is
provided on the command line.Specify login type ('so', 'user', 'context-specific';
default:'user').mechanism,
mechanismUse the specified mechanism
for token operations. See for a list
of mechanisms supported by your token. The mechanism can also be specified in
hexadecimal, e.g., 0x80001234.functionUse the specified Message Generation
Function (MGF) function
for RSA-PKCS-PSS signatures or RSA-OAEP decryptions. Supported arguments are MGF1-SHA1
to MGF1-SHA512 if supported by the driver.
The default is based on the hash selection.
modSpecify a PKCS#11 module (or library) to
load.filename,
filenameTest a Mozilla-like keypair generation
and certificate request. Specify the filename
to the certificate file.filename,
filenameSpecify the path to a file for output.pin,
pinUse the given pin for
token operations. If set to
env:VARIABLE, the value of the
environment variable VARIABLE is
used. WARNING: Be careful using this option
as other users may be able to read the command line from
the system or if it is embedded in a script. If set to
env:VARIABLE, the value of the
environment variable VARIABLE is
used.This option will also set
the option.pukSupply User PUK on the command line.pinSupply new User PIN on the command line.Set the CKA_SENSITIVE attribute (object cannot be revealed in plaintext).id,
idSet the CKA_ID of the object.
,
Display general token information.
,
Sign some data.
,
Decrypt some data.
,
Derive a secret key using another key and some data.
,
Derive ECDHpass DER encoded pubkey for compatibility with some PKCS#11 implementationsbytesSpecify how many bytes of salt should
be used in RSA-PSS signatures. Accepts two special values:
"-1" means salt length equals to digest length,
"-2" means use maximum permissible length.
Default is digest length (-1).idSpecify the id of the slot to use.descriptionSpecify the description of the slot to use.indexSpecify the index of the slot to use.labelSpecify the label of token.
Will be used the first slot, that has the inserted token with this
label.pinUse the given pin as the
Security Officer PIN for some token operations (token
initialization, user PIN initialization, etc). If set to
env:VARIABLE, the value of the
environment variable VARIABLE is
used. The same warning as also
applies here.
,
Perform some tests on the token. This
option is most useful when used with either
or .Test hotplug capabilities (C_GetSlotList +
C_WaitForSlotEvent).Set the CKA_PRIVATE attribute (object is only
viewable after a login).Test EC (best used with the
or option).Test forking and calling C_Initialize() in the
child.type,
typeSpecify the type of object to operate on.
Examples are cert, privkey
and pubkey.
,
Cause pkcs11-tool to be
more verbose.NB! This does not affect
OpenSC debugging level! To set OpenSC PKCS#11 module into debug
mode, set the OPENSC_DEBUG environment variable to a
non-zero number.
,
Verify signature of some data.
,
Get object's CKA_VALUE attribute (use with
).
,
Delete an object.labelSpecify the application label of the data object (use with
data).idSpecify the application ID of the data object (use with
data).dataSpecify the issuer in hexadecimal format (use with
cert).dataSpecify the subject in hexadecimal format (use with
cert/privkey/pubkey).filenameThe path to the signature file for signature verificationformatFormat for ECDSA signature: 'rs' (default),
'sequence', 'openssl'.filename,
filenameWrite a key or certificate object to the token.
filename points to the DER-encoded certificate or key file.
numGet num bytes of random data.
Examples
To list all certificates on the smart card:
pkcs11-tool --list-objects --type cert
To read the certificate with ID KEY_ID
in DER format from smart card:
pkcs11-tool --read-object --id KEY_ID --type cert --output-file cert.der
To convert the certificate in DER format to PEM format, use OpenSSL
tools:
openssl x509 -inform DER -in cert.der -outform PEM > cert.pem
To sign some data stored in file data
using the private key with ID ID and
using the RSA-PKCS mechanism:
pkcs11-tool --sign --id ID --mechanism RSA-PKCS --input-file data --output-file data.sigAuthorspkcs11-tool was written by
Olaf Kirch okir@suse.de.