# OpenSC

# OpenSC tools

## 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` `num`, `-r` `num`

  Use the given reader. The default is the first reader with a card.

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

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

`--card-driver` `name`, `-c` `name`

  Use the card driver specified by `name`. The default is to auto-detect the correct card driver.

`--format`, `-f`

  Format the card or token.

`--info`, `-i`

  Display information about the card or token.

`--reader` `number`, `-r` `number`

  Specify the reader number `number` to use. The default is reader `0`.

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

## 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 CHV`id`

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

  Reads a public key from the card, allowing the user to extract and store or use the public key

`--reader` `num`, `-r` `num`

  Forces cryptoflex-tool to use reader number `num` for operations. The default is to use reader number 0, the first reader in the system.

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

## See also

pkcs15-tool(1)

## 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-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` `number`, `-r` `number`

  Use smart card in specified reader. Default is reader 0.

`-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 consists of exacly 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 exeption 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 succesfull 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.

## See also

opensc-explorer(1)

## Authors

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

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

`--exec` `prog`, `-x` `prog`

  Execute the given program with data in environment variables.

`--help`, `-h`

  Print help message on screen.

`--raw`

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

`--pretty`

  Print values in pretty format.

`--user-info`, `-U`

  Show card holder information.

`--reader` `num`, `-r` `num`

  Use the given reader. The default is the first reader with a card.

`--verify` `pintype`

  Verify PIN (CHV1, CHV2 or CHV3).

`--pin` `string`

  The PIN text to verify. If set to env:`VARIABLE`, the value of the environment variable `VARIABLE` is used.

`--gen-key` `ID`, `-G` `ID`

  Generate key. Specify key ID (1, 2 or 3) to generate.

`--key-length` `bitlength`, `-L` `bitlength`

  Length (default 2048 bit) of the key to be generated.

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

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` `number`,

  Specify the reader number `number` to use. The default is reader `0`.

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

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

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

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

`--reader` `num`, `-r` `num`

  Use the given reader number. The default is `0`, the first reader in the system.

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

## See also

opensc-explorer(1)

## 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 interactively to perform miscellaneous operations such as exploring the contents of or sending arbitrary APDU commands to a smart card or similar security token.

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

  Use the given reader number. The default is 0, the first reader in the system.

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

## Commands

The following commands are supported at opensc-explorer's interactive prompt or in script files passed via the command line parameter `SCRIPT`.

apdu `hex-data`

  Send a custom APDU command `hex-data`.

asn1 `file-id`

  Parse and print the ASN.1 encoded content of the file specified by `file-id`.

cat [`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`.

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 `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 CHV`pin-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.

create `file-id` `size`

  Create a new EF. `file-id` specifies the id number and `size` is the size of the new file.

debug [`level`]

  Set OpenSC debug level to `level`.

  If `level` is omitted the current debug level will be shown.

delete `file-id`

  Remove the EF or DF specified by `file-id`

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

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

echo `string` ...

  Print the `string`s 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`.

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

ls [`pattern` ...]

  List files in the current DF. If no `pattern` is given, then all files are listed. If one ore more `pattern`s 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` (by default from 0000 to 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 `start-tag` to `end-tag` (by default from 0000 to FFFF).

mkdir `file-id` `size`

  Create a DF. `file-id` specifies the id number and `size` is the size of the new file.

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`

  Generate random sequence of `count` bytes.

rm `file-id`

  Remove the EF or DF specified by `file-id`

unblock CHV`pin-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.

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 sequencer of the hex values or as a `"` enclosed string.

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 the hex values or as a `"` enclosed string.

verify `key-type` `key-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.

sm `[open]`|`[close]`

  Calls the card's `open` or `close` Secure Messaging handler.

## See also

opensc-tool(1)

## 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 intened 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`, `-s` `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`

  Use the given reader number. The default is `0`, the first reader in the system.

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

## See also

opensc-tool(1)

## 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` `path`

  Extract information from `path` (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

`--hash`, `-h`

  Hash some data.

`--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` `path`, `-i` `path`

  Specify the path to a file for input.

`--keypairgen`, `-k`

  Generate a new key pair (public and private pair.)

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

`--mechanism` `mechanism`, `-m` `mechanism`

  Use the specified `mechanism` for token operations. See `-M` for a list of mechanisms supported by your token.

`--module` `mod`

  Specify a PKCS#11 module (or library) to load.

`--moz-cert` `path`, `-z` `path`

  Test a Mozilla-like keypair generation and certificate request. Specify the `path` to the certificate file.

`--output-file` `path`, `-o` `path`

  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.

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

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

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

`--write-object` `id`, `-w` `path`

  Write a key or certificate object to the token. `path` points to the DER-encoded certificate or key file.

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

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

  Selects the `N`-th smart card reader configured by the system. If unspecified, pkcs15-crypt will use the first reader found.

`--sha-1`

  This option tells pkcs15-crypt that the input file is the result of an SHA1 hash operation, rather than an MD5 hash. 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 `x` `NN` (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 concatanated integers (PKCS#11), 'sequence' or 'openssl' -- DER encoded sequence of two integeres (OpenSSL).

`--verbose`, `-v`

  Causes pkcs15-crypt to be more verbose. Specify this flag several times to enable debug output in the OpenSC library.

## See also

pkcs15-init(1), pkcs15-tool(1)

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

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

  Dump card objects.

`--learn-card`, `-L`

  Cache PKCS #15 token data to the local filesystem. Subsequent operations are performed on the cached data where possible. If the cache becomes out-of-sync with the token state (eg. new key is generated and stored on the token), the cache should be updated or operations may show stale results.

`--list-applications`

  List the on-card PKCS#15 applications

`--list-certificates`, `-c`

  Lists all certificates stored on the token.

`--list-data-objects`, `-C`

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

  Lists 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-pins`

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

  Lists all public keys stored on the token, including key name, id, algorithm and length information.

`--no-cache`

  Disables token data caching.

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

`--reader` `num`

  Forces pkcs15-tool to use reader number `num` for operations. The default is to use reader number 0, the first reader in the system.

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

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

## See also

pkcs15-init(1), pkcs15-crypt(1)

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

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

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

## Options

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

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

`--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' attribut 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		frank
      	puk		zappa

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

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

`--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 intrisic ID will be calculated from the certificate's public key. Look the description of the 'pkcs15-id-style' attribut 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-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' attribut 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.

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

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

`--verbose`, `-v`

  Causes pkcs15-init to be more verbose. Specify this flag several times to enable debug output in the OpenSC library.

## See also

pkcs15-profile(5)

## 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 are insecure because 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 (ie. the file for ithe PIN must havei 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` `path`, `-j` `path`

  Read the file `path` from the card. The file is written on disk with name `path`. User authentication is required for this operation.

`--reader` `num`, `-r` `num`

  Use the given reader. The default is the first reader with a card.

`--unblock-pin`, `-u`

  Unblocks a PIN stored on the card. Knowledge of the PIN Unblock Key (PUK) is required for this operation.

`-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` `path`, `-k` `path`

  Put the file with name `path` from disk to card. On the card the file is written in `path`. User authentication is required for this operation.

## Authors

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

# OpenSC file formats

## Name

pkcs15-profile — format of profile for pkcs15-init

## Description

The pkcs15-init utility for PKCS #15 smart card personalization is controlled via profiles. When starting, it will read two such profiles at the moment, a generic application profile, and a card specific profile. The generic profile must be specified on the command line, while the card-specific file is selected based on the type of card detected.

The generic application profile defines general information about the card layout, such as the path of the application DF, various PKCS #15 files within that directory, and the access conditions on these files. It also defines general information about PIN, key and certificate objects. Currently, there is only one such generic profile, pkcs15.profile.

The card specific profile contains additional information required during card intialization, such as location of PIN files, key references etc. Profiles currently reside in @pkgdatadir@

## Syntax

This section should contain information about the profile syntax. Will add this soonishly.

## See also

pkcs15-init(1), pkcs15-crypt(1)