Table of Contents
cardos-tool — displays information about Card OS-based security tokens or format them
cardos-tool [OPTIONS]
The cardos-tool utility is used to display information about smart cards and similar security tokens based on Siemens Card/OS M4.
--card-driver name,
-c nameUse the card driver specified by name.
The default is to auto-detect the correct card driver.
--format,
-f
Format the card or token.
--help,
-h
Print help message on screen.
--info,
-i
Display information about the card or token.
--reader num,
-r num
Specify the reader to use. By default, the first
reader with a present card is used. If
num is an ATR, the
reader with a matching card will be chosen.
--startkey arg,
-s arg
Specify startkey for format.
--change-startkey arg,
-S arg
Change Startkey with given APDU command.
--verbose,
-v
Causes cardos-tool to be more verbose. Specify this flag several times to enable debug output in the opensc library.
--wait,
-w
Causes cardos-tool to wait for the token to be inserted into reader.
cryptoflex-tool — utility for manipulating Schlumberger Cryptoflex data structures
cryptoflex-tool [OPTIONS]
cryptoflex-tool is used to manipulate PKCS data structures on Schlumberger Cryptoflex smart cards. Users can create, list and read PINs and keys stored on the smart card. User PIN authentication is performed for those operations that require it.
--app-df num,
-a num
Specifies the DF to operate in
--create-key-files arg,
-c arg
Creates new RSA key files for arg keys
--create-pin-files id,
-P id
Creates new PIN file for CHVid
--exponent exp,
-e exp
Specifies the RSA exponent, exp,
to use in key generation. The default value is 3.
--generate-key,
-g
Generate a new RSA key pair
--key-num num,
-k num
Specifies the key number to operate on. The default is key number 1.
--list-keys,
-l
Lists all keys stored in a public key file
--modulus-length length,
-m length
Specifies the modulus length to use
in key generation. The default value is 1024.
--prkey-file id,
-p id
Specifies the private key file id, id,
to use
--pubkey-file id,
-u id
Specifies the public key file id, id,
to use
--read-key,
-R
Reads a public key from the card, allowing the user to extract and store or use the public key
--reader num,
-r num
Specify the reader to use. By default, the first
reader with a present card is used. If
num is an ATR, the
reader with a matching card will be chosen.
--verbose,
-v
Causes cryptoflex-tool to be more verbose. Specify this flag several times to enable debug output in the opensc library.
--verify-pin,
-V
Verifies CHV1 before issuing commands
--wait,
-w
Causes cryptoflex-tool to wait for a card insertion.
dnie-tool — displays information about DNIe based security tokens
dnie-tool [OPTIONS]
The dnie-tool utility is used to display additional information about DNIe, the Spanish National eID card.
--idesp,
-i
Show the DNIe IDESP value.
--data,
-d
Show DNIe personal information. Reads and print DNIe number and User Name and SurName
--all,
-a
Displays every available information. This command is equivalent to -d -i -s
--serial,
-s
Displays DNIe Serial Number
--version,
-V
Show DNIe sw version. Displays software version for in-card DNIe OS
--pin pin,
-p pin
Specify the user pin pin to use.
If set to env:VARIABLE, the
value of the environment variable
VARIABLE is used.
The default is do not enter pin
--reader num,
-r num
Specify the reader to use. By default, the first
reader with a present card is used. If
num is an ATR, the
reader with a matching card will be chosen.
--driver driver,
-c driver
Specify the card driver driver to use.
Default is use driver from configuration file, or auto-detect if absent
--wait,
-w
Causes dnie-tool to wait for the token to be inserted into reader.
--verbose,
-v
Causes dnie-tool to be more verbose. Specify this flag several times to enable debug output in the opensc library.
egk-tool — displays information on the German electronic health card (elektronische Gesundheitskarte, eGK)
egk-tool [OPTIONS]
The egk-tool utility is used to display information stored on the German elektronic health card (elektronische Gesundheitskarte, eGK).
--help,
-hPrint help and exit.
--version,
-VPrint version and exit.
--reader arg,
-r arg
Specify the reader to use.
Use -1 as arg
to automatically detect the reader to use.
By default, the first reader with a present card is used.
--verbose,
-v
Causes egk-tool to be more verbose. Specify this flag several times to be more verbose.
eidenv — utility for accessing visible data from electronic identity cards
eidenv [OPTIONS]
The eidenv utility is used for accessing data from electronic identity cards (like national eID cards) which might not be present in PKCS#15 objects but available in custom files on the card. The data can be printed on screen or used by other programs via environment variables.
--exec prog,
-x prog
Executes the given program with data in environment variables.
--help,
-h
Print help message on screen.
--print,
-p
Prints all data fields from the card, like validity period, document number etc.
--reader num,
-r num
Specify the reader to use. By default, the first
reader with a present card is used. If
num is an ATR, the
reader with a matching card will be chosen.
--stats,
-t
Prints key usage statistics (only for Estonian ID card).
--version,
-v
Prints the version of the utility and exits.
--wait,
-w
Wait for a card to be inserted
gids-tool — smart card utility for GIDS cards
gids-tool [OPTIONS]
The gids-tool utility can be used from the command line to perform miscellaneous smart card operations on a GIDS smart card.
-X,
--initialize
Initialize token.
--admin-key argument
Define the administrator key
--pin argument
Define user PIN.
--serial-number argument
Define serial number.
-U,
--unblock
Unblock the user PIN after an administrator authentication.
-C,
--change-admin-key
Change the administrator key.
--new-admin-key argument
Define the new administrator key.
--reader argument,
-r argument
Specify the reader to use. By default, the first
reader with a present card is used. If
num is an ATR, the
reader with a matching card will be chosen.
-w,
--wait
Wait for a card to be inserted.
-v,
--verbose
Verbose operation. Use several times to enable debug output.
iasecc-tool — displays information about IAS/ECC card
iasecc-tool [OPTIONS]
The iasecc-tool utility is used to display information about IAS/ECC v1.0.1 smart cards.
--reader num,
Specify the reader to use. By default, the first
reader with a present card is used. If
num is an ATR, the
reader with a matching card will be chosen.
--list-applications,
Get list of the on-card applications.
--aid hex-aid,
Select hex-aid before processing.
--list-sdos sdo-type,
List SDOs of the given sdo-type,
present in default or selected application.
--verbose,
-v
Causes cardos-tool to be more verbose. Specify this flag several times to enable debug output in the opensc library.
--wait,
-w
Causes iasecc-tool to wait for the token to be inserted into reader.
netkey-tool — administrative utility for Netkey E4 cards
netkey-tool [OPTIONS] [COMMAND]
The netkey-tool utility can be used from the command line to perform some smart card operations with NetKey E4 cards that cannot be done easily with other OpenSC-tools, such as changing local PINs, storing certificates into empty NetKey E4 cert-files or displaying the initial PUK-value.
--help,
-h
Displays a short help message.
--pin pin-value,
-p pin-value
Specifies the current value of the global PIN.
--puk pin-value,
-u pin-value
Specifies the current value of the global PUK.
--pin0 pin-value,
-0 pin-value
Specifies the current value of the local PIN0 (aka local PIN).
--pin1 pin-value,
-1 pin-value
Specifies the current value of the local PIN1 (aka local PUK).
--reader num,
-r num
Specify the reader to use. By default, the first
reader with a present card is used. If
num is an ATR, the
reader with a matching card will be chosen.
-v
Causes netkey-tool to be more verbose. This options may be specified multiple times to increase verbosity.
With the -p, -u, -0 or the -1
one of the cards pins may be specified. You may use plain ascii-strings (i.e. 123456) or a hex-string
(i.e. 31:32:33:34:35:36). A hex-string must consist of exactly n 2-digit hexnumbers separated by n-1 colons.
Otherwise it will be interpreted as an ascii string. For example :12:34: and 1:2:3:4 are both pins of
length 7, while 12:34 and 01:02:03:04 are pins of length 2 and 4.
When used without any options or commands, netkey-tool will display information about the smart cards pins and certificates. This will not change your card in any aspect (assumed there are no bugs in netkey-tool). In particular the tries-left counters of the pins are investigated without doing actual pin-verifications.
If you specify the global PIN via the --pin option,
netkey-tool will also display the initial value of the cards
global PUK. If your global PUK was changed netkey-tool will still
display its initial value. There's no way to recover a lost global PUK once it was changed.
There's also no way to display the initial value of your global PUK without knowing the
current value of your global PIN.
For most of the commands that netkey-tool can execute, you have to specify one pin. One notable exception is the nullpin command, but this command can only be executed once in the lifetime of a NetKey E4 card.
number filename
This command will read one of your cards certificates (as specified by
number) and save this certificate into file filename
in PEM-format. Certificates on a NetKey E4 card are readable without a pin, so you don't
have to specify one.
filename number
This command will read the first PEM-encoded certificate from file
filename and store this into your smart cards certificate file
number. Some of your smart cards certificate files might be readonly, so
this will not work with all values of number. If a certificate file is
writable you must specify a pin in order to change it. If you try to use this command
without specifying a pin, netkey-tool will tell you which one is
needed.
new-pin
This changes the value of the specified pin to the given new value. You must specify either the current value of the pin or another pin to be able to do this and if you don't specify a correct one, netkey-tool will tell you which one is needed.
initial-pin
This command can be executed only if the global PIN of your card is in nullpin-state. There's no way to return back to nullpin-state once you have changed your global PIN. You don't need a pin to execute the nullpin-command. After a successful nullpin-command netkey-tool will display your cards initial PUK-value.
This unblocks the specified pin. You must specify another pin to be able to do this and if you don't specify a correct one, netkey-tool will tell you which one is needed.
npa-tool — displays information on the German eID card (neuer Personalausweis, nPA).
npa-tool [OPTIONS]
The npa-tool utility is used to display information stored on the German eID card (neuer Personalausweis, nPA), and to perform some write and verification operations.
--help,
-hPrint help and exit.
--version,
-VPrint version and exit.
--reader arg,
-r arg
Specify the reader to use.
Use -1 as arg
to automatically detect the reader to use.
By default, the first reader with a present card is used.
--verbose,
-v
Causes npa-tool to be more verbose. Specify this flag several times to be more verbose.
--pin [STRING],
-p [STRING]
Run PACE with (transport) eID-PIN.
--puk [STRING],
-u [STRING]
Run PACE with PUK.
--can [STRING],
-c [STRING]
Run PACE with Card Access Number (CAN).
--mrz [STRING],
-m [STRING]
Run PACE with Machine Readable Zone (MRZ). Enter the MRZ without newlines.
--env
Specify whether to use environment variables PIN,
PUK, CAN, MRZ,
and NEWPIN.
You may want to clean your environment before enabling this.
(default=off)
--new-pin [STRING],
-N [STRING]
Install a new PIN.
--resume,
-R
Resume eID-PIN (uses CAN to activate last retry). (default=off)
--unblock,
-U
Unblock PIN (uses PUK to activate three more retries). (default=off)
--cv-certificate FILENAME,
-C FILENAME
Specify Card Verifiable (CV) certificate to create a certificate chain. The option can be given multiple times, in which case the order is important.
--cert-desc HEX_STRINGCertificate description to show for Terminal Authentication.
--chat HEX_STRING
Specify the Card Holder Authorization Template
(CHAT) to use.
If not given, it defaults to the terminal's CHAT.
Use 7F4C0E060904007F000703010203530103
to trigger EAC on the CAT-C (Komfortleser).
--auxiliary-data HEX_STRING,
-A HEX_STRING
Specify the terminal's auxiliary data. If not given, the default is determined by verification of validity, age and community ID.
--private-key FILENAME,
-P FILENAME
Specify the terminal's private key.
--cvc-dir DIRECTORY
Specify where to look for the certificate of the
Country Verifying Certification Authority
(CVCA).
If not given, it defaults to
/home/fm/.local/etc/eac/cvc.
--x509-dir DIRECTORY
Specify where to look for the X.509 certificate.
If not given, it defaults to
/home/fm/.local/etc/eac/x509.
--disable-ta-checksDisable checking the validity period of CV certificates. (default=off)
--disable-ca-checksDisable passive authentication. (default=off)
--read-dg1Read data group 1: Document Type.
--read-dg2Read data group 2: Issuing State.
--read-dg3Read data group 3: Date of Expiry.
--read-dg4Read data group 4: Given Name(s).
--read-dg5Read data group 5: Family Name.
--read-dg6Read data group 6: Religious/Artistic Name.
--read-dg7Read data group 7: Academic Title.
--read-dg8Read data group 8: Date of Birth.
--read-dg9Read data group 9: Place of Birth.
--read-dg10Read data group 10: Nationality.
--read-dg11Read data group 11: Sex.
--read-dg12Read data group 12: Optional Data.
--read-dg13Read data group 13: Birth Name.
--read-dg14Read data group 14.
--read-dg15Read data group 15.
--read-dg16Read data group 16.
--read-dg17Read data group 17: Normal Place of Residence.
--read-dg18Read data group 18: Community ID.
--read-dg19Read data group 19: Residence Permit I.
--read-dg20Read data group 20: Residence Permit II.
--read-dg21Read data group 21: Optional Data.
--write-dg17 HEX_STRINGWrite data group 17: Normal Place of Residence.
--write-dg18 HEX_STRINGWrite data group 18: Community ID.
--write-dg19 HEX_STRINGWrite data group 19: Residence Permit I.
--write-dg20 HEX_STRINGWrite data group 20: Residence Permit II.
--write-dg21 HEX_STRINGWrite data group 21: Optional Data.
--verify-validity YYYYMMDDVerify chip's validity with a reference date.
--older-than YYYYMMDDVerify age with a reference date.
--verify-community HEX_STRINGVerify community ID with a reference ID.
--break,
-b
Brute force PIN, CAN or PUK.
Use together with options -p,
-a, or -u.
(default=off)
--translate FILENAME,
-t FILENAME
Specify the file with APDUs of HEX_STRINGs to send through the secure channel. (default=`stdin')
--tr-03110v201Force compliance to BSI TR-03110 version 2.01. (default=off)
--disable-all-checksDisable all checking of fly-by-data. (default=off)
openpgp-tool — utility for accessing visible data OpenPGP smart cards and compatible tokens
openpgp-tool [OPTIONS]
The openpgp-tool utility is used for accessing data from the OpenPGP v1.1 and v2.0 smart cards and compatible tokens like e.g. GPF CryptoStick v1.x, which might not be present in PKCS#15 objects but available in custom files on the card. The data can be printed on screen or used by other programs via environment variables.
--del-key arg
Delete key indicated by arg.
arg can be 1,
2, 3, or
all.
--do arg,
-d arg
Dump private data object (DO)
indicated by arg.
arg can be in the form
x,
10x, or
010x
to access DO 010x,
where x is 1,
2, 3, or
4.
--erase,
-E
Erase (i.e. reset) the card.
--exec prog,
-x prog
Execute the given program with data in environment variables.
--gen-key arg,
-G arg
Generate key with the ID given as arg.
arg can be one of 1,
2, or 3.
--help,
-h
Print help message on screen.
--key-length bitlength,
-L bitlength
Specify the length of the key to be generated. If not given, it defaults to 2048 bit.
--pin string
The PIN text to verify. If set to
env:VARIABLE, the value of
the environment variable
VARIABLE is used.
--pretty
Print values in pretty format.
--raw
Print values in raw format, as they are stored on the card.
--reader num,
-r num
Specify the reader to use. By default, the first
reader with a present card is used. If
num is an ATR, the
reader with a matching card will be chosen.
--user-info,
-U
Show card holder information.
--verify pintype
Verify PIN (CHV1, CHV2 or CHV3).
--version,
-V
Print the version of the utility and exit.
--verbose,
-v
Verbose operation. Use several times to enable debug output.
--wait,
-w
Wait for a card to be inserted.
opensc-explorer — generic interactive utility for accessing smart card and similar security token functions
opensc-explorer [OPTIONS] [SCRIPT]
The opensc-explorer utility can be used interactively to perform miscellaneous operations such as exploring the contents of or sending arbitrary APDU commands to a smart card or similar security token.
The following are the command-line options for opensc-explorer. There are additional interactive commands available once it is running.
--card-driver driver,
-c driver
Use the given card driver. The default is auto-detected.
--mf path,
-m path
Select the file referenced by the given path on
startup. The default is the path to the standard master file,
3F00. If path is empty (e.g. opensc-explorer
--mf ""), then no file is explicitly selected.
--reader num,
-r num
Specify the reader to use. By default, the first
reader with a present card is used. If
num is an ATR, the
reader with a matching card will be chosen.
--verbose, -v
Causes opensc-explorer to be more verbose. Specify this flag several times to enable debug output in the opensc library.
--wait, -w
Wait for a card to be inserted
The following commands are supported at opensc-explorer's
interactive prompt or in script files passed via the command line parameter
SCRIPT.
hex-data
Send a custom APDU command hex-data.
file-id
Parse and print the ASN.1 encoded content of the file specified by
file-id.
file-id | sfi:short-id ]
Print the contents of the currently selected EF or the contents
of a file specified by file-id or the short file id
short-id.
.. | file-id | aid:DF-name }
Change to another DF specified by the argument passed.
If the argument given is ..,
then move up one level in the file system hierarchy.
If it is file-id,
which must be a DF directly
beneath the current DF, then change to that DF.
If it is an application identifier given as
aid:DF-name,
then jump to the MF of the application denoted by
DF-name.
CHVpin-ref
[
[old-pin]
new-pin
]
Change a PIN, where pin-ref is the PIN reference.
Examples:
change CHV2 00:00:00:00:00:00 "foobar"
Change PIN CHV2
to the new value foobar,
giving the old value 00:00:00:00:00:00.
change CHV2 "foobar"
Set PIN CHV2
to the new value foobar.
change CHV2
Change PIN CHV2 using the card reader's pinpad.
file-id
size
Create a new EF. file-id specifies the
id number and size is the size of the new file.
level]
Set OpenSC debug level to level.
If level is omitted the current debug level will be shown.
file-id
Remove the EF or DF specified by file-id
hex-tag
[output]
Copy the internal card's 'tagged' data into the local file.
The local file is specified by output while the tag of
the card's data is specified by hex-tag.
If output is omitted, the name of the output file will be
derived from hex-tag.
hex-tag
input
Update internal card's 'tagged' data.
hex-tag is the tag of the card's data.
input is the filename of the source file or the literal data presented as
a sequence of hexadecimal values or " enclosed string.
string...
Print the strings given.
Erase the card, if the card supports it.
file-id
[output]
Copy an EF to a local file. The local file is specified
by output while the card file is specified by file-id.
If output is omitted, the name of the output file will be
derived from the full card path to file-id.
file-id]
Display attributes of a file specified by file-id.
If file-id is not supplied,
the attributes of the current file are printed.
pattern...]
List files in the current DF.
If no pattern is given, then all files are listed.
If one ore more patterns are given, only files matching
at least one pattern are listed.
start-id
[end-id]
]
Find all files in the current DF.
Files are found by selecting all file identifiers in the range from start-fid to end-fid (by default from 0000 to FFFF).
start-tag
[end-tag]
]
Find all tags of data objects in the current context.
Tags are found by using GET DATA in the range from start-tag to end-tag (by default from 0000 to FFFF).
file-id
size
Create a DF. file-id specifies the id number
and size is the size of the new file.
file-id
input
Copy a local file to the card. The local file is specified
by input while the card file is specified by file-id.
Exit the program.
count
Generate random sequence of count bytes.
file-id
Remove the EF or DF specified by file-id
CHVpin-ref
[
puk
[new-pin]
]
Unblock the PIN denoted by pin-ref
using the PUK puk, and set potentially
change its value to new-pin.
PUK and PIN values can be a sequence of hexadecimal values,
"-enclosed strings, empty (""),
or absent.
If they are absent, the values are read from the card reader's pin pad.
Examples:
unblock CHV2 00:00:00:00:00:00 "foobar"
Unblock PIN CHV2 using PUK
00:00:00:00:00:00
and set it to the new value foobar.
unblock CHV2 00:00:00:00:00:00 ""
Unblock PIN CHV2 using PUK
00:00:00:00:00:00 keeping the old value.
unblock CHV2 "" "foobar"
Set new value of PIN CHV2
to foobar.
unblock CHV2 00:00:00:00:00:00
Unblock PIN CHV2 using PUK
00:00:00:00:00:00.
The new PIN value is prompted by pinpad.
unblock CHV2 ""
Set PIN CHV2.
The new PIN value is prompted by pinpad.
unblock CHV2
Unblock PIN CHV2.
The unblock code and new PIN value are prompted by pinpad.
file-id
offs
data
Binary update of the file specified by
file-id with the literal data
data starting from offset specified
by offs.
data can be supplied as a sequencer
of the hex values or as a " enclosed string.
file-id
rec-nr
rec-offs
data
Update record specified by rec-nr of the file
specified by file-id with the literal data
data starting from offset specified by
rec-offs.
data can be supplied as a sequence of the hex values or
as a " enclosed string.
key-typekey-id
[key]
Present a PIN or key to the card, where
key-type can be one of CHV,
KEY, AUT or PRO.
key-id is a number representing the key or PIN reference.
key is the key or PIN to be verified, formatted as a
colon-separated list of hex values or a " enclosed string.
If key is omitted, the exact action depends on the
card reader's features: if the card readers supports PIN input via a pin pad,
then the PIN will be verified using the card reader's pin pad.
If the card reader does not support PIN input, then the PIN will be asked
interactively.
Examples:
verify CHV0 31:32:33:34:00:00:00:00
Verify CHV2 using the hex value
31:32:33:34:00:00:00:00
verify CHV1 "secret"
Verify CHV1
using the string value secret.
verify KEY2
Verify KEY2,
get the value from the card reader's pin pad.
open | close }
Calls the card's open or close Secure Messaging handler.
opensc-notify — monitor smart card events and send notifications
opensc-notify [OPTIONS]
The opensc-notify utility is used to monitor smart card events and send the appropriate notification.
--help,
-hPrint help and exit.
--version,
-VPrint version and exit.
Send customized notifications.
--title [STRING],
-t [STRING]
Specify the title of the notification.
--message [STRING],
-m [STRING]
Specify the main text of the notification.
Manually send standard notifications.
--notify-card-inserted,
-I
See notify_card_inserted
in opensc.conf (default=off).
--notify-card-removed,
-R
See notify_card_removed
in opensc.conf (default=off).
--notify-pin-good,
-G
See notify_pin_good
in opensc.conf (default=off).
--notify-pin-bad,
-B
See notify_pin_bad
in opensc.conf (default=off).
opensc-tool — generic smart card utility
opensc-tool [OPTIONS]
The opensc-tool utility can be used from the command line to perform miscellaneous smart card operations such as getting the card ATR or sending arbitrary APDU commands to a card.
--version,
Print the OpenSC package release version.
--atr,
-a
Print the Answer To Reset (ATR) of the card. Output is in hex byte format
--card-driver driver,
-c driver
Use the given card driver. The default is auto-detected.
--list-algorithms,
Lists algorithms supported by card
--info,
-i
Print information about OpenSC, such as version and enabled components.
--list-drivers,
-D
List all installed card drivers.
--list-files,
-f
Recursively list all files stored on card.
--list-readers,
-l
List all configured readers.
--name,
-n
Print the name of the inserted card (driver).
--get-conf-entry conf,
-G conf
Get configuration key, format: section:name:key
--set-conf-entry conf,
-S conf
Get configuration key, format: section:name:key:value
--reader num,
-r num
Specify the reader to use. By default, the first
reader with a present card is used. If
num is an ATR, the
reader with a matching card will be chosen.
--reset [type],
Resets the card in reader.
The default reset type is cold,
but warm reset is also possible.
--send-apdu apdu,
-s apdu
Sends an arbitrary APDU to the card in the format
AA:BB:CC:DD:EE:FF....
--serial
Print the card serial number (normally the ICCSN). Output is in hex byte format
--verbose,
-v
Causes opensc-tool to be more verbose. Specify this flag several times to enable debug output in the opensc library.
--wait,
-w
Wait for a card to be inserted.
piv-tool — smart card utility for HSPD-12 PIV cards
piv-tool [OPTIONS]
The piv-tool utility can be used from the command line to perform miscellaneous smart card operations on a HSPD-12 PIV smart card as defined in NIST 800-73-3. It is intended for use with test cards only. It can be used to load objects, and generate key pairs, as well as send arbitrary APDU commands to a card after having authenticated to the card using the card key provided by the card vendor.
--serial
Print the card serial number derived from the CHUID object, if any. Output is in hex byte format.
--name,
-n
Print the name of the inserted card (driver)
--admin argument,
-A argument
Authenticate to the card using a 2DES or 3DES key.
The argument of the form
{A|M}:ref:alg
is required, were A uses "EXTERNAL AUTHENTICATION"
and M uses "MUTUAL AUTHENTICATION".
ref is normally 9B,
and alg is 03 for 3DES.
The key is provided by the card vendor, and the environment variable
PIV_EXT_AUTH_KEY must point to a text file containing
the key in the format:
XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX
--genkey argument,
-G argument
Generate a key pair on the card and output the public key.
The argument of the form
ref:alg
is required, where ref is 9A,
9C, 9D or 9E and
alg is 06,
07, 11 or 14
for RSA 1024, RSA 2048, ECC 256 or ECC 384 respectively.
--object ContainerID,
-O ContainerID
Load an object onto the card.
The ContainerID is as defined in NIST 800-73-n
without leading 0x. Example: CHUID object is 3000
--cert ref,
-C ref
Load a certificate onto the card.
ref is 9A,
9C, 9D or
9E
--compresscert ref,
-Z ref
Load a certificate that has been gzipped onto the card.
ref is 9A,
9C, 9D or
9E
--out file,
-o file
Output file for any operation that produces output.
--in file,
-i file
Input file for any operation that requires an input file.
--key-slots-discovery file
Print properties of the key slots. Needs 'admin' authentication.
--send-apdu apdu,
-s apdu
Sends an arbitrary APDU to the card in the format
AA:BB:CC:DD:EE:FF....
This option may be repeated.
--reader num,
-r num
Specify the reader to use. By default, the first
reader with a present card is used. If
num is an ATR, the
reader with a matching card will be chosen.
--card-driver driver,
-c driver
Use the given card driver. The default is auto-detected.
--wait,
-w
Wait for a card to be inserted
--verbose,
-v
Causes piv-tool to be more verbose. Specify this flag several times to enable debug output in the opensc library.
pkcs11-tool — utility for managing and using PKCS #11 security tokens
pkcs11-tool [OPTIONS]
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.
--attr-from filename
Extract 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-pin,
-c
Change the user PIN on the token
--unlock-pin
Unlock User PIN (without --login
unlock in logged in session; otherwise --login-type
has to be 'context-specific').
--hash,
-h
Hash some data.
--hash-algorithm 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 id,
-d id
Specify the id of the object to operate on.
--init-pin
Initializes the user PIN. This option
differs from --change-pin in that it sets the user PIN
for the first time. Once set, the user PIN can be changed
using --change-pin.
--init-token
Initialize a token: set the token label as
well as a Security Officer PIN (the label must be specified
using --label).
--input-file filename,
-i filename
Specify the path to a file for input.
--keypairgen,
-k
Generate a new key pair (public and private pair.)
--keygen
Generate a new key.
--key-type specification
Specify the type and length of the key to create, for example rsa:1024 or EC:prime256v1.
--usage-sign
Specify 'sign' key usage flag (sets SIGN in privkey, sets VERIFY in pubkey).
--usage-decrypt
Specify 'decrypt' key usage flag (RSA only, set DECRYPT privkey, ENCRYPT in pubkey).
--usage-derive
Specify 'derive' key usage flag (EC only).
--label name,
-a name
Specify the name of the object to operate on
(or the token label when --init-token
is used).
--list-mechanisms,
-M
Display a list of mechanisms supported by the token.
--list-objects,
-O
Display a list of objects.
--list-slots,
-L
Display a list of available slots on the token.
--list-token-slots,
-T
List slots with tokens.
--login,
-l
Authenticate to the token before performing other operations. This option is not needed if a PIN is provided on the command line.
--login-type
Specify login type ('so', 'user', 'context-specific'; default:'user').
--mechanism mechanism,
-m mechanism
Use the specified mechanism
for token operations. See -M for a list
of mechanisms supported by your token. The mechanism can also be specified in
hexadecimal, e.g., 0x80001234.
--mgf function
Use 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.
--module mod
Specify a PKCS#11 module (or library) to load.
--moz-cert filename,
-z filename
Test a Mozilla-like keypair generation
and certificate request. Specify the filename
to the certificate file.
--output-file filename,
-o filename
Specify the path to a file for output.
--pin pin,
-p pin
Use 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 --login option.
--puk puk
Supply User PUK on the command line.
--new-pin pin
Supply new User PIN on the command line.
--sensitive
Set the CKA_SENSITIVE attribute (object cannot be revealed in plaintext).
--set-id id,
-e id
Set the CKA_ID of the object.
--show-info,
-I
Display general token information.
--sign,
-s
Sign some data.
--decrypt,
Decrypt some data.
--derive,
Derive a secret key using another key and some data.
--derive-pass-der,
Derive ECDHpass DER encoded pubkey for compatibility with some PKCS#11 implementations
--salt-len bytes
Specify 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).
--slot id
Specify the id of the slot to use.
--slot-description description
Specify the description of the slot to use.
--slot-index index
Specify the index of the slot to use.
--token-label label
Specify the label of token. Will be used the first slot, that has the inserted token with this label.
--so-pin pin
Use 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 --pin also
applies here.
--test,
-t
Perform some tests on the token. This
option is most useful when used with either --login
or --pin.
--test-hotplug
Test hotplug capabilities (C_GetSlotList + C_WaitForSlotEvent).
--private
Set the CKA_PRIVATE attribute (object is only viewable after a login).
--test-ec
Test EC (best used with the --login
or --pin option).
--test-fork
Test forking and calling C_Initialize() in the child.
--type type,
-y type
Specify the type of object to operate on.
Examples are cert, privkey
and pubkey.
--verbose, -v
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.
--read-object,
-r
Get object's CKA_VALUE attribute (use with
--type).
--delete-object,
-b
Delete an object.
--application-label label
Specify the application label of the data object (use with
--type data).
--application-id id
Specify the application ID of the data object (use with
--type data).
--issuer data
Specify the issuer in hexadecimal format (use with
--type cert).
--subject data
Specify the subject in hexadecimal format (use with
--type cert/privkey/pubkey).
--signature-format format
Format for ECDSA signature: 'rs' (default), 'sequence', 'openssl'.
--write-object filename,
-w filename
Write a key or certificate object to the token.
filename points to the DER-encoded certificate or key file.
--generate-random num
Get num bytes of random data.
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 --outfile 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.sig
pkcs15-crypt — perform crypto operations using PKCS#15 smart cards
pkcs15-crypt [OPTIONS]
The pkcs15-crypt utility can be used from the command line to perform cryptographic operations such as computing digital signatures or decrypting data, using keys stored on a PKCS#15 compliant smart card.
--version,
Print the OpenSC package release version.
--aid aid
Specify the AID of the on-card PKCS#15 application
to bind to. The aid must be in hexadecimal
form.
--decipher,
-c
Decrypt the contents of the file specified by
the --input option. The result of the
decryption operation is written to the file specified by the
--output option. If this option is not given,
the decrypted data is printed to standard output, displaying
non-printable characters using their hex notation xNN (see also
--raw).
--input file,
-i file
Specifies the input file to use. Defaults to stdin if not specified.
--key id,
-k id
Selects the ID of the key to use.
--output file,
-o file
Any output will be sent to the specified file. Defaults to stdout if not specified.
--pin pin,
-p pin
When the cryptographic operation requires a PIN to access the key, pkcs15-crypt will prompt the user for the PIN on the terminal. Using this option allows you to specify the PIN on the command line.
Note that on most operating systems, the command line of a process can be displayed by any user using the ps(1) command. It is therefore a security risk to specify secret information such as PINs on the command line. If you specify '-' as PIN, it will be read from STDIN.
--pkcs1
By default, pkcs15-crypt
assumes that input data has been padded to the correct length
(i.e. when computing an RSA signature using a 1024 bit key,
the input must be padded to 128 bytes to match the modulus
length). When giving the --pkcs1 option,
however, pkcs15-crypt will perform the
required padding using the algorithm outlined in the
PKCS #1 standard version 1.5.
--raw,
-R
Outputs raw 8 bit data.
--reader N,
-r N
Specify the reader to use. By default, the first
reader with a present card is used. If
num is an ATR, the
reader with a matching card will be chosen.
--md5
--sha-1
--sha-224
--sha-256
--sha-384
--sha-512
These options tell pkcs15-crypt that the input file is the result of the specified hash operation. By default, an MD5 hash is expected. Again, the data must be in binary representation.
--sign,
-s
Perform digital signature operation on
the data read from a file specified using the --input
option. By default, the contents of the file are assumed to
be the result of an MD5 hash operation.
Note that pkcs15-crypt
expects the data in binary representation, not ASCII.
The digital signature is stored, in binary representation,
in the file specified by the --output option. If
this option is not given, the signature is printed on standard
output, displaying non-printable characters using their hex notation
xNN
(see also --raw).
--signature-format,
--f
When signing with ECDSA key this option indicates to pkcs15-crypt the signature output format. Possible values are 'rs'(default) -- two concatenated integers (PKCS#11), 'sequence' or 'openssl' -- DER encoded sequence of two integers (OpenSSL).
--wait,
-w
Causes pkcs15-crypt to wait for a card insertion.
--verbose,
-v
Causes pkcs15-crypt to be more verbose. Specify this flag several times to enable debug output in the OpenSC library.
pkcs15-init — smart card personalization utility
pkcs15-init [OPTIONS]
The pkcs15-init utility can be used to create a PKCS #15 structure on a smart card, and add key or certificate objects. Details of the structure that will be created are controlled via profiles.
The profile used by default is pkcs15. Alternative
profiles can be specified via the -p switch.
pkcs15-init can be used to create a PKCS #15 structure on
your smart card, create PINs, and install keys and certificates on the card.
This process is also called personalization.
An OpenSC card can have one security officer PIN, and zero or more user PINs. PIN stands for Personal Identification Number, and is a secret code you need to present to the card before being allowed to perform certain operations, such as using one of the stored RSA keys to sign a document, or modifying the card itself.
Usually, PINs are a sequence of decimal digits, but some cards will accept arbitrary ASCII characters. Be aware however that using characters other than digits will make the card unusable with PIN pad readers, because those usually have keys for entering digits only.
The security officer (SO) PIN is special; it is used to protect meta data information on the card, such as the PKCS #15 structure itself. Setting the SO PIN is optional, because the worst that can usually happen is that someone finding your card can mess it up. To extract any of your secret keys stored on the card, an attacker will still need your user PIN, at least for the default OpenSC profiles. However, it is possible to create card profiles that will allow the security officer to override user PINs.
For each PIN, you can specify a PUK (also called unblock PIN).
The PUK can be used to overwrite or unlock a PIN if too many incorrect values
have been entered in a row.
For some cards that use the PKCS#15 emulation, the attributes of private objects
are protected and cannot be parsed without authentication (usually with User PIN).
This authentication need to be done immediately after the card binding.
In such cases --verify-pin has to be used.
This is the first step during card personalization, and will create the basic files on the card. To create the initial PKCS #15 structure, invoke the utility as
pkcs15-init --create-pkcs15
You will then be asked for the security officer PIN and PUK. Simply pressing return at the SO PIN prompt will skip installation of an SO PIN.
If the card supports it, you should erase the contents of the card with pkcs15-init --erase-card before creating the PKCS#15 structure.
Before installing any user objects such as private keys, you need at least one PIN to protect these objects. you can do this using
pkcs15-init --store-pin --id " nn
where nn is a PKCS #15 ID in hexadecimal notation. Common
values are 01, 02, etc.
Entering the command above will ask you for the user's PIN and PUK. If you do not wish to install an unblock PIN, simply press return at the PUK prompt.
To set a label for this PIN object (which can be used by applications to display
a meaningful prompt to the user), use the --label command line option.
pkcs15-init lets you generate a new key and store it on the card. You can do this using:
pkcs15-init --generate-key " keyspec " --auth-id " nn
where keyspec describes the algorithm and length of the
key to be created, such as rsa/512. This will create a 512 bit
RSA key. Currently, only RSA key generation is supported. Note that cards
usually support just a few different key lengths. Almost all cards will support
512 and 1024 bit keys, some will support 768 or 2048 as well.
nn is the ID of a user PIN installed previously,
e.g. 01.
In addition to storing the private portion of the key on the card, pkcs15-init will also store the the public portion of the key as a PKCS #15 public key object.
You can use a private key generated by other means and upload it to the card.
For instance, to upload a private key contained in a file named
okir.pem, which is in PEM format, you would use
pkcs15-init --store-private-key okir.pem --id 45 --auth-id 01
In addition to storing the private portion of the key on the card, pkcs15-init will also store the the public portion of the key as a PKCS #15 public key object.
Note that usage of --id option in the pkcs15-init
commands to generate or to import a new key is deprecated.
Better practice is to let the middleware to derive the identifier from the key material.
(SHA1(modulus) for RSA, SHA1(pub) for DSA, ...).
This allows easily set up relation between 'related' objects
(private/public keys and certificates).
In addition to the PEM key file format, pkcs15-init also supports DER encoded keys, and PKCS #12 files. The latter is the file format used by Netscape Navigator (among others) when exporting certificates to a file. A PKCS #12 file usually contains the X.509 certificate corresponding to the private key. If that is the case, pkcs15-init will store the certificate instead of the public key portion.
You can also upload individual public keys to the card using the
--store-public-key option, which takes a filename as an
argument. This file is supposed to contain the public key. If you don't
specify a key file format using the --format option,
pkcs15-init will assume PEM format. The only other
supported public key file format is DER.
Since the corresponding public keys are always uploaded automatically when generating a new key, or when uploading a private key, you will probably use this option only very rarely.
You can upload certificates to the card using the
--store-certificate option, which takes a filename as
an argument. This file is supposed to contain the PEM encoded X.509
certificate.
Most browsers nowadays use PKCS #12 format files when you ask them to export your key and certificate to a file. pkcs15-init is capable of parsing these files, and storing their contents on the card in a single operation. This works just like storing a private key, except that you need to specify the file format:
pkcs15-init --store-private-key okir.p12 --format pkcs12 --auth-id 01
This will install the private key contained in the file okir.p12,
and protect it with the PIN referenced by authentication ID 01.
It will also store any X.509 certificates contained in the file, which is
usually the user certificate that goes with the key, as well as the CA certificate.
You can use a secret key generated by other means and upload it to the card. For instance, to upload an AES-secret key generated by the system random generator you would use
pkcs15-init --store-secret-key /dev/urandom --secret-key-algorithm aes/256 --auth-id 01
By default a random ID is generated for the secret key. You may specify an ID
with the --id if needed.
--version,
Print the OpenSC package release version.
--card-profile name,
-c name
Tells pkcs15-init to load the specified card profile option. You will rarely need this option.
--create-pkcs15,
-C
This tells pkcs15-init to create a PKCS #15 structure on the card, and initialize any PINs.
--serial SERIAL
Specify the serial number of the card.
--erase-card,
-E
This will erase the card prior to creating the PKCS #15 structure, if the card supports it. If the card does not support erasing, pkcs15-init will fail.
--erase-application AID
This will erase the application with the application identifier
AID.
--generate-key keyspec,
-G keyspec
Tells the card to generate new key and store it on the card.
keyspec consists of an algorithm name
(currently, the only supported name is RSA),
optionally followed by a slash and the length of the key in bits.
It is a good idea to specify the key ID along with this command,
using the id option, otherwise an intrinsic ID
will be calculated from the key material. Look the description of
the 'pkcs15-id-style' attribute in the 'pkcs15.profile' for the details
about the algorithm used to calculate intrinsic ID.
For the multi-application cards the target PKCS#15 application can be
specified by the hexadecimal AID value of the aid option.
--options-file filename
Tells pkcs15-init to read additional options
from filename. The file is supposed to
contain one long option per line, without the leading dashes,
for instance:
pin 1234 puk 87654321
You can specify --options-file several times.
--pin,
--puk
--so-pin,
--so-puk,
These options can be used to specify PIN/PUK values
on the command line. If set to
env:VARIABLE, the value
of the environment variable
VARIABLE is used. Note
that on most operation systems, any user can
display the command line of any process on the
system using utilities such as
ps(1). Therefore, you should use
these options only on a secured system, or in an
options file specified with
--options-file.
--no-so-pin,
Do not install a SO PIN, and do not prompt for it.
--profile name,
-p name
Tells pkcs15-init to load the specified general
profile. Currently, the only application profile defined is
pkcs15, but you can write your own profiles and
specify them using this option.
The profile name can be combined with one or more profile
options, which slightly modify the profile's behavior.
For instance, the default OpenSC profile supports the
openpin option, which installs a single PIN during
card initialization. This PIN is then used both as the SO PIN as
well as the user PIN for all keys stored on the card.
Profile name and options are separated by a +
character, as in pkcs15+onepin.
--secret-key-algorithm keyspec,
keyspec describes the algorithm and length of the
key to be created or downloaded, such as aes/256.
This will create a 256 bit AES key.
--store-certificate filename,
-X filename
Tells pkcs15-init to store the certificate given
in filename on the card, creating a certificate
object with the ID specified via the --id option.
Without supplied ID an intrinsic ID will be calculated from the
certificate's public key. Look the description of the 'pkcs15-id-style'
attribute in the 'pkcs15.profile' for the details
about the algorithm used to calculate intrinsic ID.
The file is assumed to contain the PEM encoded certificate.
For the multi-application cards the target application can be specified
by the hexadecimal AID value of the aid option.
--store-pin,
-P
Store a new PIN/PUK on the card.
--store-public-key filename
Tells pkcs15-init to download the specified
public key to the card and create a public key object with the
key ID specified via the --id. By default,
the file is assumed to contain the key in PEM format. Alternative
formats can be specified using --format.
--store-private-key filename,
-S filename
Tells pkcs15-init to download the specified
private key to the card. This command will also create a public
key object containing the public key portion. By default, the
file is assumed to contain the key in PEM format. Alternative
formats can be specified using --format.
It is a good idea to specify the key ID along with this command,
using the --id option, otherwise an intrinsic ID
will be calculated from the key material. Look the description of
the 'pkcs15-id-style' attribute in the 'pkcs15.profile' for the details
about the algorithm used to calculate intrinsic ID.
For the multi-application cards the target PKCS#15 application can be
specified by the hexadecimal AID value of the aid option.
--store-secret-key filename,
Tells pkcs15-init to download the specified
secret key to the card. The file is assumed to contain the raw key.
They key type should be specified with --secret-key-algorithm
option.
You may additionally specify the key ID along with this command,
using the --id option, otherwise a random ID is generated.
For the multi-application cards the target PKCS#15 application can be
specified by the hexadecimal AID value of the aid option.
--store-data filename,
-W filename
Store a data object.
--update-certificate filename,
-U filename
Tells pkcs15-init to update the certificate
object with the ID specified via the --id option
with the certificate in filename.
The file is assumed to contain a PEM encoded certificate.
Pay extra attention when updating mail decryption certificates, as missing certificates can render e-mail messages unreadable!
--delete-objects arg,
-D arg
Tells pkcs15-init to delete the
specified object. arg
is comma-separated list containing any of
privkey, pubkey,
secrkey, cert,
chain or data.
When data is specified, an
---application-id must also be
specified, in the other cases an
--id must also be specified
When chain is specified, the
certificate chain starting with the cert with
specified ID will be deleted, until there's a CA
certificate that certifies another cert on the card
--change-attributes arg,
-A arg
Tells pkcs15-init to change the
specified attribute. arg
is either privkey,
pubkey, secrkey,
cert or data.
You also have to specify the --id
of the object.
For now, you can only change the --label, e.g:
pkcs15-init -A cert --id 45 -a 1 --label Jim
--use-default-transport-keys,
-T
Tells pkcs15-init to not ask for the transport keys and use default keys, as known by the card driver.
--sanity-check,
-T
Tells pkcs15-init to perform a card specific sanity check and possibly update procedure.
--reader num,
-r num
Specify the reader to use. By default, the first
reader with a present card is used. If
num is an ATR, the
reader with a matching card will be chosen.
--verbose,
-v
Causes pkcs15-init to be more verbose. Specify this flag several times to enable debug output in the OpenSC library.
--wait,
-w
Causes pkcs15-init to wait for a card insertion.
--use-pinpad
Do not prompt the user; if no PINs supplied, pinpad will be used.
--puk-id ID
Specify ID of PUK to use/create
--puk-label LABEL
Specify label of PUK
--public-key-label LABEL
Specify public key label (use with --generate-key)
--cert-label LABEL
Specify user cert label (use with --store-private-key)
--application-name arg
Specify application name of data object (use with --store-data-object)
--aid AID
Specify AID of the on-card PKCS#15 application to be binded to (in hexadecimal form)
--output-file filename
-o filename,
Output public portion of generated key to file
--passphrase PASSPHRASE
Specify passphrase for unlocking secret key
--authority
Mark certificate as a CA certificate
--key-usage arg
-u arg,
Specifies the X.509 key usage.
arg is comma-separated
list containing any of
digitalSignature,
nonRepudiation,
keyEncipherment,
dataEncipherment,
keyAgreement,
keyCertSign,
cRLSign. Abbreviated names are
allowed if unique (e.g.
dataEnc).
The alias sign is equivalent to
digitalSignature,keyCertSign,cRLSign
The alias decrypt is equivalent to
keyEncipherment,dataEncipherment
--finalize
-F,
Finish initialization phase of the smart card
--update-last-update
Update 'lastUpdate' attribute of tokenInfo
--ignore-ca-certificates
When storing PKCS#12 ignore CA certificates
--update-existing
Store or update existing certificate
--extractable
Private key stored as an extractable key
--insecure
Insecure mode: do not require a PIN for private key
--md-container-guid GUID
For a new key specify GUID for a MD container
--help
-h,
Display help message
pkcs15-tool — utility for manipulating PKCS #15 data structures on smart cards and similar security tokens
pkcs15-tool [OPTIONS]
The pkcs15-tool utility is used to manipulate the PKCS #15 data structures on smart cards and similar 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.
--version,
Print the OpenSC package release version.
--aid aid
Specify in a hexadecimal form the AID of the on-card PKCS#15 application to bind to.
--auth-id pin,
-a pin
Specifies the auth id of the PIN to use for the operation. This is useful with the --change-pin operation.
--change-pin
Changes a PIN or PUK stored on the token. User authentication is required for this operation.
--dump,
-D
List all card objects.
--list-info
List card objects.
--list-applications
List the on-card PKCS#15 applications.
--list-certificates,
-c
List all certificates stored on the token.
--list-data-objects,
-C
List all data objects stored on the token.
For some cards the PKCS#15 attributes of the private data objects are
protected for reading and need the authentication with the User PIN.
In such a case the --verify-pin option has to be used.
--list-keys,
-k
List all private keys stored on the token. General
information about each private key is listed (eg. key name, id and
algorithm). Actual private key values are not displayed.
For some cards the PKCS#15 attributes of the private keys are protected for reading
and need the authentication with the User PIN.
In such a case the --verify-pin option has to be used.
--list-secret-keys
List all secret (symmetric) keys stored on the token. General
information about each secret key is listed (eg. key name, id and
algorithm). Actual secret key values are not displayed.
For some cards the PKCS#15 attributes of the private keys are protected for reading
and need the authentication with the User PIN.
In such a case the --verify-pin option has to be used.
--list-pins
List all PINs stored on the token. General information about each PIN is listed (eg. PIN name). Actual PIN values are not shown.
--list-public-keys
List all public keys stored on the token, including key name, id, algorithm and length information.
--short
-s
Output lists in compact format.
--no-cache
Disables token data caching.
--clear-cache
Removes the user's cache directory. On Windows, this option additionally removes the system's caching directory (requires administrator privileges).
--clear-cache
Removes the user's cache directory. On Windows, this option additionally removes the system's caching directory (requires administrator privileges).
--output filename,
-o filename
Specifies where key output should be written.
If filename already exists, it will be overwritten.
If this option is not given, keys will be printed to standard output.
--raw
Changes how --read-data-object prints the content
to standard output. By default, when --raw is not given, it will
print the content in hex notation. If --raw is set, it will print
the binary data directly. This does not affect the output that is written to the
file specified by the --output option. Data written to a file will
always be in raw binary.
--read-certificate cert,
-r cert
Reads the certificate with the given id.
--read-data-object cert,
-R data
Reads data object with OID, applicationName or label.
The content is printed to standard output in hex notation, unless
the --raw option is given.
If an output file is given with the --output option,
the content is additionally written to the file.
Output to the file is always written in raw binary mode, the
--raw only affects standard output behavior.
--read-public-key id
Reads the public key with id id,
allowing the user to extract and store or use the public key.
--read-ssh-key id
Reads the public key with id id,
writing the output in format suitable for
$HOME/.ssh/authorized_keys.
The key label, if any will be shown in the 'Comment' field.
--rfc4716
When used in conjunction with option --read-ssh-key the
output format of the public key follows rfc4716.
The default output format is a single line (openssh).
--test-update,
-T,
Test if the card needs a security update
--update,
-U,
Update the card with a security update
--reader num
Specify the reader to use. By default, the first
reader with a present card is used. If
num is an ATR, the
reader with a matching card will be chosen.
--unblock-pin,
-u
Unblocks a PIN stored on the token. Knowledge of the Pin Unblock Key (PUK) is required for this operation.
--verbose,
-v
Causes pkcs15-tool to be more verbose. Specify this flag several times to enable debug output in the OpenSC library.
--pin PIN
Specify PIN
--puk PUK
Specify Unblock PIN
--new-pin PIN
Specify New PIN (when changing or unblocking)
--verify-pin
Verify PIN after card binding and before issuing any command (without 'auth-id' the first non-SO, non-Unblock PIN will be verified)
--test-session-pin
Equivalent to --verify-pin
with additional session PIN generation
--wait,
-w
Causes pkcs15-tool to wait for a card insertion.
--use-pinpad
Do not prompt the user; if no PINs supplied, pinpad will be used.
sc-hsm-tool — smart card utility for SmartCard-HSM
sc-hsm-tool [OPTIONS]
The sc-hsm-tool utility can be used from the command line to perform extended maintenance tasks not available via PKCS#11 or other tools in the OpenSC package. It can be used to query the status of a SmartCard-HSM, initialize a device, generate and import Device Key Encryption Key (DKEK) shares and to wrap and unwrap keys.
--initialize,
-X
Initialize token, removing all existing keys, certificates and files.
Use --so-pin to define SO-PIN for first initialization or to verify in subsequent
initializations.
Use --pin to define the initial user pin value.
Use --pin-retry to define the maximum number of wrong user PIN presentations.
Use with --dkek-shares to enable key wrap / unwrap.
Use with --label to define a token label
--create-dkek-share filename,
-C filename
Create a DKEK share encrypted under a password and save it to the file given as parameter.
Use --password to provide a password for encryption rather than prompting for one.
Use --pwd-shares-threshold and --pwd-shares-total to randomly generate a password and split is using a (t, n) threshold scheme.
--import-dkek-share filename,
-I filename
Prompt for user password, read and decrypt DKEK share and import into SmartCard-HSM.
Use --password to provide a password for decryption rather than prompting for one.
Use --pwd-shares-total to specify the number of shares that should be entered to reconstruct the password.
--wrap-key filename,
-W filename
Wrap the key referenced in --key-reference and save with it together with the key description
and certificate to the given file.
Use --pin to provide the user PIN on the command line.
--unwrap-key filename,
-U filename
Read wrapped key, description and certificate from file and import into SmartCard-HSM
under the key reference given in --key-reference.
Determine the key reference using the output of pkcs15-tool -D.
Use --pin to provide a user PIN on the command line.
Use --force to remove any key, key description or certificate in the way.
--dkek-shares number-of-shares,
-s number-of-shares
Define the number of DKEK shares to use for recreating the DKEK.
This is an optional parameter. Using --initialize without
--dkek-shares will disable the DKEK completely.
Using --dkek-shares with 0 shares requests the SmartCard-HSM to
generate a random DKEK. Keys wrapped with this DKEK can only be unwrapped in the
same SmartCard-HSM.
After using --initialize with one or more DKEK shares, the
SmartCard-HSM will remain in the initialized state until all DKEK shares have
been imported. During this phase no new keys can be generated or imported.
--so-pin value
Define SO-PIN for initialization. If set to
env:VARIABLE, the value of
the environment variable
VARIABLE is used.
--pin value
Define user PIN for initialization, wrap or
unwrap operation. If set to
env:VARIABLE, the value of
the environment variable
VARIABLE is used.
--pin-retry value
Define number of PIN retries for user PIN during initialization. Default is 3.
--password value
Define password for DKEK share encryption. If set to
env:VARIABLE, the value of
the environment variable
VARIABLE is used.
--pwd-shares-threshold value
Define threshold for number of password shares required for reconstruction.
--pwd-shares-total value
Define number of password shares.
--force
Force removal of existing key, description and certificate.
--label label,
-l label
Define the token label to be used in --initialize.
--reader num,
-r num
Specify the reader to use. By default, the first
reader with a present card is used. If
num is an ATR, the
reader with a matching card will be chosen.
--wait,
-w
Wait for a card to be inserted
--verbose,
-v
Causes sc-hsm-tool to be more verbose. Specify this flag several times to enable debug output in the opensc library.
Create a DKEK share:
sc-hsm-tool --create-dkek-share dkek-share-1.pbe
Create a DKEK share with random password split up using a (3, 5) threshold scheme:
sc-hsm-tool --create-dkek-share dkek-share-1.pbe --pwd-shares-threshold 3 --pwd-shares-total 5
Initialize SmartCard-HSM to use a single DKEK share:
sc-hsm-tool --initialize --so-pin 3537363231383830 --pin 648219 --dkek-shares 1 --label mytoken
Import DKEK share:
sc-hsm-tool --import-dkek-share dkek-share-1.pbe
Import DKEK share using a password split up using a (3, 5) threshold scheme for encryption:
sc-hsm-tool --import-dkek-share dkek-share-1.pbe --pwd-shares-total 3
Wrap referenced key, description and certificate:
sc-hsm-tool --wrap-key wrap-key.bin --key-reference 1 --pin 648219
Unwrap key into same or in different SmartCard-HSM with the same DKEK:
sc-hsm-tool --unwrap-key wrap-key.bin --key-reference 10 --pin 648219 --force
westcos-tool — utility for manipulating data structures on westcos smart cards
westcos-tool [OPTIONS]
The westcos-tool utility is used to manipulate the westcos data structures on 2 Ko smart cards / tokens. Users can create PINs, keys and certificates stored on the card / token. User PIN authentication is performed for those operations that require it.
--change-pin,
-n
Changes a PIN stored on the card. User authentication is required for this operation.
--certificate file,
-t file
Write certificate file file
in PEM format to the card.
User authentication is required for this operation.
--finalize,
-f
Finalize the card. Once finalized the default key is invalidated, so PIN and PUK cannot be changed anymore without user authentication.
Warning, un-finalized cards are insecure because the PIN can be changed without user authentication (knowledge of default key is enough).
--generate-key,
-g
Generate a private key on the card. The card must not have
been finalized and a PIN must be installed (i.e. the file for the PIN must
have been created, see option -i).
By default the key length is 1536 bits. User authentication is required for
this operation.
--help,
-h
Print help message on screen.
--install-pin,
-i
Install PIN file in on the card.
You must provide a PIN value with -x.
--key-length length,
-l length
Change the length of private key.
Use with -g.
--overwrite-key,
-o
Overwrite the key if there is already a key on the card.
--pin-value value,
-x value
Set value of PIN. If set to
env:VARIABLE, the value of
the environment variable
VARIABLE is used.
--puk-value value,
-y value
set value of PUK (or value of new PIN for change PIN
command see -n). If set to
env:VARIABLE, the value of
the environment variable
VARIABLE is used.
--read-file filename,
-j filename
Read the file filename from the card.
The file is written on disk with name filename.
User authentication is required for this operation.
--reader num,
-r num
Specify the reader to use. By default, the first
reader with a present card is used. If
num is an ATR, the
reader with a matching card will be chosen.
--unblock-pin,
-u
Unblocks a PIN stored on the card. Knowledge of the PIN Unblock Key (PUK) is required for this operation.
--verbose
-v
Causes westcos-tool to be more verbose. Specify this flag several times to enable debug output in the OpenSC library.
--wait,
-w
Wait for a card to be inserted.
--write-file filename,
-k filename
Put the file with name filename
from disk to card.
On the card the file is written in filename.
User authentication is required for this operation.