OpenSC Manual Pages: Section 1

Name

cardos-tool — displays information about Card OS-based security tokens or format them

Synopsis

cardos-tool [OPTIONS]

Description

The cardos-tool utility is used to display information about smart cards and similar security tokens based on Siemens Card/OS M4.

Options

--format, -f: Format the card or token.
--help, -h: Print help message on screen.
--info, -i: Display information about the card or token.
--reader arg, -r arg: Number of the reader to use. By default, the first reader with a present card is used. If arg 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.

Authors

cardos-tool was written by Andreas Jellinghaus <aj@dungeon.inka.de>.

Name

cryptoflex-tool — utility for manipulating Schlumberger Cryptoflex data structures

Synopsis

cryptoflex-tool [OPTIONS]

Description

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.

Options

--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 arg, -r arg: Number of the reader to use. By default, the first reader with a present card is used. If arg 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.

Authors

cryptoflex-tool was written by Juha Yrjölä <juha.yrjola@iki.fi>.

Name

dnie-tool — displays information about DNIe based security tokens

Synopsis

dnie-tool [OPTIONS]

Description

The dnie-tool utility is used to display additional information about DNIe, the Spanish National eID card.

Options

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

These options can be used to specify the PIN value on the command line. If the value is set to env:VARIABLE, the value of the specified environment variable is used. By default, the code is prompted on the command line if needed.

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 prefer passing the codes via an environment variable on an unsecured system.

--reader arg, -r arg

Number of the reader to use. By default, the first reader with a present card is used. If arg is an ATR, the reader with a matching card will be chosen.

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

Authors

dnie-tool was written by Juan Antonio Martinez <jonsito@terra.es>.

Name

egk-tool — displays information on the German electronic health card (elektronische Gesundheitskarte, eGK)

Synopsis

egk-tool [OPTIONS]

Description

The egk-tool utility is used to display information stored on the German elektronic health card (elektronische Gesundheitskarte, eGK).

Options

--help, -h: Print help and exit.
--version, -V: Print version and exit.
--reader arg, -r arg: Number of the reader to use. By default, the first reader with a present card is used. If arg is an ATR, the reader with a matching card will be chosen.
--verbose, -v: Causes egk-tool to be more verbose. Specify this flag several times to be more verbose.

Health Care Application (HCA)

--pd: Show 'Persönliche Versicherungsdaten' (XML).
--vd: Show 'Allgemeine Versicherungsdaten' (XML).
--gvd: Show 'Geschützte Versicherungsdaten' (XML).
--vsd-status: Show 'Versichertenstammdaten-Status'.

Authors

egk-tool was written by Frank Morgner <frankmorgner@gmail.com>.

Name

eidenv — utility for accessing visible data from electronic identity cards

Synopsis

eidenv [OPTIONS]

Description

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.

Options

--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 arg, -r arg: Number of the reader to use. By default, the first reader with a present card is used. If arg 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

Authors

eidenv utility was written by Stef Hoeben and Martin Paljak <martin@martinpaljak.net>.

Name

gids-tool — smart card utility for GIDS cards

Synopsis

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.

Options

-X, --initialize

Initialize token.

--admin-key argument

Define the administrator key

--pin pin

This option can be used to specify the PIN value on the command line. If the value is set to env:VARIABLE, the value of the specified environment variable is used. By default, the code is prompted on the command line if needed.

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 prefer passing the codes via an environment variable on an unsecured system.

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

Number of the reader to use. By default, the first reader with a present card is used. If argument 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.

Authors

gids-tool was written by Vincent Le Toux <vincent.letoux@mysmartlogon.com>.

Name

iasecc-tool — displays information about IAS/ECC card

Synopsis

iasecc-tool [OPTIONS]

Description

The iasecc-tool utility is used to display information about IAS/ECC v1.0.1 smart cards.

Options

--reader arg,: Number of the reader to use. By default, the first reader with a present card is used. If arg 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.

Authors

iasecc-tool was written by Viktor Tarasov <viktor.tarasov@gmail.com>.

Name

netkey-tool — administrative utility for Netkey E4 cards

Synopsis

netkey-tool [OPTIONS] [COMMAND]

Description

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.

Options

--help, -h: Displays a short help message.
--pin pin, -p pin: Specifies the current value of the global PIN.
--puk pin, -u pin: Specifies the current value of the global PUK.
--pin0 pin, -0 pin: Specifies the current value of the local PIN0 (aka local PIN).
--pin1 pin, -1 pin: Specifies the current value of the local PIN1 (aka local PUK).
--reader arg, -r arg: Number of the reader to use. By default, the first reader with a present card is used. If arg 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.

PIN format

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.

Commands

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.

cert 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.
cert 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.
change { pin | puk | pin0 | pin1 } 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.
nullpin 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.
unblock { pin | pin0 | pin1 }: 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.

Authors

netkey-tool was written by Peter Koch <pk_opensc@web.de>.

Name

npa-tool — displays information on the German eID card (neuer Personalausweis, nPA).

Synopsis

npa-tool [OPTIONS]

Description

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.

Options

--help, -h: Print help and exit.
--version, -V: Print version and exit.
--reader arg, -r arg: Number of the reader to use. By default, the first reader with a present card is used. If arg is an ATR, the reader with a matching card will be chosen.
--verbose, -v: Causes npa-tool to be more verbose. Specify this flag several times to be more verbose.

Password Authenticated Connection Establishment (PACE)

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

PIN management

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

Terminal Authentication (TA) and Chip Authentication (CA)

--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_STRING: Certificate 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-checks: Disable checking the validity period of CV certificates. (default=off)
--disable-ca-checks: Disable passive authentication. (default=off)

Read and write data groups

--read-dg1: Read data group 1: Document Type.
--read-dg2: Read data group 2: Issuing State.
--read-dg3: Read data group 3: Date of Expiry.
--read-dg4: Read data group 4: Given Name(s).
--read-dg5: Read data group 5: Family Name.
--read-dg6: Read data group 6: Religious/Artistic Name.
--read-dg7: Read data group 7: Academic Title.
--read-dg8: Read data group 8: Date of Birth.
--read-dg9: Read data group 9: Place of Birth.
--read-dg10: Read data group 10: Nationality.
--read-dg11: Read data group 11: Sex.
--read-dg12: Read data group 12: Optional Data.
--read-dg13: Read data group 13: Birth Name.
--read-dg14: Read data group 14.
--read-dg15: Read data group 15.
--read-dg16: Read data group 16.
--read-dg17: Read data group 17: Normal Place of Residence.
--read-dg18: Read data group 18: Community ID.
--read-dg19: Read data group 19: Residence Permit I.
--read-dg20: Read data group 20: Residence Permit II.
--read-dg21: Read data group 21: Optional Data.
--write-dg17 HEX_STRING: Write data group 17: Normal Place of Residence.
--write-dg18 HEX_STRING: Write data group 18: Community ID.
--write-dg19 HEX_STRING: Write data group 19: Residence Permit I.
--write-dg20 HEX_STRING: Write data group 20: Residence Permit II.
--write-dg21 HEX_STRING: Write data group 21: Optional Data.

Verification of validity, age and community ID

--verify-validity YYYYMMDD: Verify chip's validity with a reference date.
--older-than YYYYMMDD: Verify age with a reference date.
--verify-community HEX_STRING: Verify community ID with a reference ID.

Special options, not always useful

--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-03110v201: Force compliance to BSI TR-03110 version 2.01. (default=off)
--disable-all-checks: Disable all checking of fly-by-data. (default=off)

Authors

npa-tool was written by Frank Morgner <frankmorgner@gmail.com>.

Name

openpgp-tool — utility for accessing visible data OpenPGP smart cards and compatible tokens

Synopsis

openpgp-tool [OPTIONS]

Description

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.

Options

--card-info, -C

Show card information.

--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-info, -K

Show information of keys on the card.

--key-type keytype, -t keytype

Specify the type of the key to be generated. Supported values for keytype are rsa for RSA with 2048 bits, rsaLENGTH for RSA with a bit length of LENGTH. If not given, it defaults to rsa2048.

--pin pin

This option can be used to specify the PIN value on the command line. If the value is set to env:VARIABLE, the value of the specified environment variable is used. By default, the code is prompted on the command line if needed.

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 prefer passing the codes via an environment variable on an unsecured system.

--pretty

Print values in pretty format.

--raw

Print values in raw format, as they are stored on the card.

--reader arg, -r arg

Number of the reader to use. By default, the first reader with a present card is used. If arg 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.

Authors

openpgp-tool utility was written by Peter Marschall <peter@adpm.de>.

Name

opensc-asn1 — parse ASN.1 data

Synopsis

opensc-asn1 [OPTIONS] [FILES]

Description

The opensc-asn1 utility is used to parse ASN.1 data.

Options

--help, -h: Print help and exit.
--version, -V: Print version and exit.

Authors

opensc-asn1 was written by Frank Morgner <frankmorgner@gmail.com>.

Name

opensc-explorer — generic interactive utility for accessing smart card and similar security token functions

Synopsis

opensc-explorer [OPTIONS] [SCRIPT]

Description

The opensc-explorer utility can be used to perform miscellaneous operations such as exploring the contents of or sending arbitrary APDU commands to a smart card or similar security token.

If a SCRIPT is given, opensc-explorer runs in non-interactive mode, reading the commands from SCRIPT, one command per line. If no script is given, opensc-explorer runs in interactive mode, reading commands from standard input.

Options

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 to auto-detect the correct card driver. The literal value ? lists all available card drivers and terminates opensc-explorer.
--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 arg, -r arg: Number of the reader to use. By default, the first reader with a present card is used. If arg is an ATR, the reader with a matching card will be chosen.
--verbose, -v: Cause 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.

Commands

opensc-explorer supports commands with arguments at its interactive prompt or in script files passed via the command line parameter SCRIPT.

Similar to a command shell like e.g. bash, each input line is split into white-space separated words. Of these words, the first one is used as the command, while the remaining ones are treated as arguments to that command.

The following commands are supported:

# ...

Treat line as a comment. Ignore anything until the end of the line introduced by #.

apdu data...

Send a custom APDU command to the card. data is a series of sequences of hexadecimal values and strings enclosed in double quotes ("...").

asn1 file-id [rec-no] [offs]

Parse and print the ASN.1 encoded content of the working EF specified by file-id. If the optional parameter rec-no is given and the file is a record-oriented EF, parse and print only the record indicated by this parameter. If the optional parameter offs is given, start parsing and printing the file or record at the offset indicated by the value given. If this parameter is not given, the default offset is 0.

cat [ file-id | sfi:short-id ] [rec-no]

Print the contents of the working EF specified by file-id or the short file id short-id. If the optional second parameter rec-no is given, only print the record indicated by this parameter. If no argument is given, print the the contents of the currently selected EF.

cd { .. | 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 a 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.

change CHVpin-ref [ [old-pin] new-pin ]

Change the PIN specified by pin-ref from the value given by old-pin and change its value to new-pin.

old-pin and new-pin can be sequences of hexadecimal values, strings enclosed in double quotes ("..."), empty (""), or absent. If absent, the values are read from the card reader's pin pad.

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.

create file-id size

Create a new EF. file-id specifies the numeric id, and size the size of the EF to create.

debug [level]

Set OpenSC debug level to level.

If level is omitted, show the current debug level.

delete file-id

Remove the EF or DF specified by file-id.

do_get hex-tag [output]

Copy the contents of the card's data object (DO) specified by hex-tag to the local host computer's file named output.

If output is not given, the contents of hex-tag will be displayed as hex-dump.

do_put hex-tag data

Change the contents of the card's data object (DO) specified by hex-tag to data.

data is either a sequence of hexadecimal values or a string enclosed in double quotes ("...").

echo string...

Print the strings given.

erase

Erase the card, if the card supports it.

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

get_record file-id rec-no [output]

Copy a record of a record-oriented EF to a local file. The local file is specified by output while the card file and the record are specified by file-id and rec-no,

If output is omitted, the name of the output file will be derived from the full card path to file-id. and the rec-no.

help [pattern]

Display the list of available commands, their options and parameters together with a short help text. If pattern is given, the commands shown are limited to those matching pattern.

info [file-id]

Display attributes of a file specified by file-id. If file-id is not supplied, the attributes of the current file are displayed.

ls [pattern...]

List files in the current DF. If no pattern is given, then all files are listed. If one or more patterns are given, only files matching at least one pattern are listed.

find [ 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.

If not given, the default value for start-fid is 0000, while the default for end-fid is FFFF.

find_tags [ 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 from start-tag to end-tag.

If not given, the default value for start-tag is 0000, while the default for end-tag is FFFF.

mkdir file-id size

Create a DF. file-id specifies the numeric id, and size the size of the DF to create.

pin_info key-typekey-id

Get information on a PIN or key from 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.

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

quit

Exit the program.

random count [output-file]

Generate count bytes of random data. If output-file is given, write the data to the host computer's file denoted by it, otherwise show the data as hex dump.

rm file-id

Remove the EF or DF specified by file-id.

unblock CHVpin-ref [ puk [new-pin] ]

Unblock the PIN denoted by pin-ref using the PUK puk, and potentially change its value to new-pin.

puk and new-pin can be sequences of hexadecimal values, strings enclosed in double quotes ("..."), empty (""), or absent. If 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.

update_binary 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 sequence of hexadecimal values or as a string enclosed in double quotes ("...").

update_record 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 hexadecimal values or as a string enclosed in double quotes ("...").

verify 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 sequence of hexadecimal values or a string enclosed in double quotes ("...").

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

sm { open | close }

Call the card's open or close Secure Messaging handler.

Authors

opensc-explorer was written by Juha Yrjölä <juha.yrjola@iki.fi>.

Name

opensc-notify — monitor smart card events and send notifications

Synopsis

opensc-notify [OPTIONS]

Description

The opensc-notify utility is used to monitor smart card events and send the appropriate notification.

Options

--help, -h: Print help and exit.
--version, -V: Print version and exit.

Mode: customized

Send customized notifications.

--title [STRING], -t [STRING]: Specify the title of the notification.
--message [STRING], -m [STRING]: Specify the main text of the notification.

Mode: standard

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

Authors

opensc-notify was written by Frank Morgner <frankmorgner@gmail.com>.

Name

opensc-tool — generic smart card utility

Synopsis

opensc-tool [OPTIONS]

Description

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.

Options

--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 to auto-detect the correct card driver. The literal value ? lists all available card drivers.
--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: Set configuration key, format: section:name:key:value
--reader arg, -r arg: Number of the reader to use. By default, the first reader with a present card is used. If arg 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.

Authors

opensc-tool was written by Juha Yrjölä <juha.yrjola@iki.fi>.

Name

piv-tool — smart card utility for HSPD-12 PIV cards

Synopsis

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.

Options

--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 arg, -r arg

Number of the reader to use. By default, the first reader with a present card is used. If arg is an ATR, the reader with a matching card will be chosen.

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

Authors

piv-tool was written by Douglas E. Engert <deengert@gmail.com>.

Name

pkcs11-tool — utility for managing and using PKCS #11 security tokens

Synopsis

pkcs11-tool [OPTIONS]

Description

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.

Options

--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 (bytes if symmetric) of the key to create, for example RSA:1024, EC:prime256v1, GOSTR3410-2012-256:B, DES:8, DES3:24, AES:16 or GENERIC:64.

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

--usage-wrap

Specify 'wrap' key usage flag.

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

--list-interfaces

List interfaces of PKCS #11 3.0 library.

--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 key pair 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).

--extractable

Set the CKA_EXTRACTABLE attribute (object can be extracted)

--undestroyable

Set the CKA_DESTROYABLE attribute to false (object cannot be destroyed)

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

--object-index index

Specify the index of the object to use.

--use-locking

Tell pkcs11 module it should use OS thread locking.

--test-threads options

Test a pkcs11 module's thread implication. (See source code).

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

--always-auth

Set the CKA_ALWAYS_AUTHENTICATE attribute to a private key object. If set, the user has to supply the PIN for each use (sign or decrypt) with the key.

--allowed-mechanisms mechanisms

Sets the CKA_ALLOWED_MECHANISMS attribute to a key objects when importing an object or generating a keys. The argument accepts comma-separated list of algorithmsm, that can be used with the given key.

--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. Valid value are cert, privkey, pubkey, secrkey and data.

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

--verify,

Verify signature of some data.

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

The path to the signature file for signature verification

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

--allow-sw

Allow using software mechanisms that do not have the CKF_HW flag set. May be required when using software tokens and emulators.

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

Authors

pkcs11-tool was written by Olaf Kirch <okir@suse.de>.

Name

pkcs15-crypt — perform crypto operations using PKCS#15 smart cards

Synopsis

pkcs15-crypt [OPTIONS]

Description

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.

Options

--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 arg, -r arg

Number of the reader to use. By default, the first reader with a present card is used. If arg 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.

Authors

pkcs15-crypt was written by Juha Yrjölä <juha.yrjola@iki.fi>.

Name

pkcs15-init — smart card personalization utility

Synopsis

pkcs15-init [OPTIONS]

Description

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.

PIN Usage

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.

Modes of operation

Initialization

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.

User PIN Installation

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.

Key generation

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 the parameters of the key to be created. For example, rsa:2048 generates a RSA key with 2048-bit modulus. If you are generating an EC key, the curve designation must be specified, for example ec:prime256v1. For symmetric key, the length of key is specified in bytes, for example AES:32 or DES3:24.

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 public portion of the key as a PKCS #15 public key object.

Private Key Upload

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 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, ...). 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.

Public Key Upload

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.

Certificate Upload

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.

Uploading PKCS #12 bags

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.

Secret Key Upload

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.

Options

--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, optionally followed by a colon ":", slash "/" or hyphen "-" and the parameters of the key to be created. 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.

--pin pin, --puk puk, --so-pin sopin, --so-puk sopuk

These options can be used to specify the PIN/PUK values on the command line. If the value is set to env:VARIABLE, the value of the specified environment variable is used. By default, the code is prompted on the command line if needed.

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 prefer passing the codes via an environment variable on an unsecured system.

--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 arg, -r arg

Number of the reader to use. By default, the first reader with a present card is used. If arg 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

--user-consent arg

Specify user-consent. arg is an integer value. If > 0, the value specifies how many times the object can be accessed before a new authentication is required. If zero, the object does not require re-authentication.

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

Authors

pkcs15-init was written by Olaf Kirch <okir@suse.de>.

Name

pkcs15-tool — utility for manipulating PKCS #15 data structures on smart cards and similar security tokens

Synopsis

pkcs15-tool [OPTIONS]

Description

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.

Options

--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 id, -a id

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

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 arg

Number of the reader to use. By default, the first reader with a present card is used. If arg 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, --new-pin newpin --puk puk

These options can be used to specify the PIN/PUK values on the command line. If the value is set to env:VARIABLE, the value of the specified environment variable is used. By default, the code is prompted on the command line if needed.

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 prefer passing the codes via an environment variable on an unsecured system.

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

Authors

pkcs15-tool was written by Juha Yrjölä <juha.yrjola@iki.fi>.

Name

sc-hsm-tool — smart card utility for SmartCard-HSM

Synopsis

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.

Options

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

--pin pin, --so-pin sopin,

These options can be used to specify the PIN values on the command line. If the value is set to env:VARIABLE, the value of the specified environment variable is used. By default, the code is prompted on the command line if needed.

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 prefer passing the codes via an environment variable on an unsecured system.

--pin-retry value

Define number of PIN retries for user PIN during initialization. Default is 3.

--bio-server1 value

The hexadecimal AID of of the biometric server for template 1. Switches on the use of the user PIN as session PIN.

--bio-server2 value

The hexadecimal AID of of the biometric server for template 2. Switches on the use of the user PIN as session PIN.

--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 arg, -r arg

Number of the reader to use. By default, the first reader with a present card is used. If arg 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.

Examples

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

Authors

sc-hsm-tool was written by Andreas Schwier <andreas.schwier@cardcontact.de>.

Name

westcos-tool — utility for manipulating data structures on westcos smart cards

Synopsis

westcos-tool [OPTIONS]

Description

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.

Options

--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 pin, -x pin --puk-value puk, -y puk

These options can be used to specify the PIN/PUK values on the command line. If the value is set to env:VARIABLE, the value of the specified environment variable is used. By default, the code is prompted on the command line if needed.

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 prefer passing the codes via an environment variable on an unsecured system.

--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 arg, -r arg

Number of the reader to use. By default, the first reader with a present card is used. If arg 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.

Authors

westcos-tool was written by Francois Leblanc <francois.leblanc@cev-sa.com>.

OpenSC Manual Pages: Section 1

Name

Synopsis

Description

Options

Authors

Name

Synopsis

Description

Options

See also

Authors

Name

Synopsis

Description

Options

Authors

Name

Synopsis

Description

Options

Health Care Application (HCA)

Authors

Name

Synopsis

Description

Options

Authors

Name

Synopsis

Options

See also

Authors

Name

Synopsis

Description

Options

Authors

Name

Synopsis

Description

Options

PIN format

Commands

See also

Authors

Name

Synopsis

Description

Options

Password Authenticated Connection Establishment (PACE)

PIN management

Terminal Authentication (TA) and Chip Authentication (CA)

Read and write data groups

Verification of validity, age and community ID

Special options, not always useful

Authors

Name

Synopsis

Description

Options

Authors

Name

Synopsis

Description

Options

Authors

Name

Synopsis

Description

Options

Commands

See also

Authors

Name

Synopsis

Description

Options

Mode: customized

Mode: standard