Table of Contents
Table of Contents
eidenv — utility for accessing visible data from electronic identity cards
eidenv
[OPTIONS
]
The eidenv utility is used for accessing data from electronic identity cards (like national eID cards) which might not be present in PKCS#15 objects but available in custom files on the card. The data can be printed on screen or used by other programs via environment variables.
--exec
prog
,
-x
prog
Executes the given program with data in environment variables.
--help
,
-h
Print help message on screen.
--print
,
-p
Prints all data fields from the card, like validity period, document number etc.
--reader
num
,
-r
num
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
cardos-tool — displays information about Card OS-based security tokens or format them
cardos-tool
[OPTIONS
]
The cardos-tool utility is used to display information about smart cards and similar security tokens based on Siemens Card/OS M4.
--card-driver
name
,
-c
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.
cryptoflex-tool — utility for manipulating Schlumberger Cryptoflex data structures
cryptoflex-tool
[OPTIONS
]
cryptoflex-tool is used to manipulate PKCS data structures on Schlumberger Cryptoflex smart cards. Users can create, list and read PINs and keys stored on the smart card. User PIN authentication is performed for those operations that require it.
--app-df
num
,
-a
num
Specifies the DF to operate in
--create-key-files
arg
,
-c
arg
Creates new RSA key files for arg
keys
--create-pin-files
id
,
-P
id
Creates new PIN file for CHVid
--exponent
exp
,
-e
exp
Specifies the RSA exponent, exp
,
to use in key generation. The default value is 3.
--generate-key
,
-g
Generate a new RSA key pair
--key-num
num
,
-k
num
Specifies the key number to operate on. The default is key number 1.
--list-keys
,
-l
Lists all keys stored in a public key file
--modulus-length
length
,
-m
length
Specifies the modulus length
to use
in key generation. The default value is 1024.
--prkey-file
id
,
-p
id
Specifies the private key file id, id
,
to use
--pubkey-file
id
,
-u
id
Specifies the public key file id, id
,
to use
--read-key
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
netkey-tool — administrative utility for Netkey E4 cards
netkey-tool
[OPTIONS
] [COMMAND
]
The netkey-tool utility can be used from the command line to perform some smart card operations with NetKey E4 cards that cannot be done easily with other OpenSC-tools, such as changing local PINs, storing certificates into empty NetKey E4 cert-files or displaying the initial PUK-value.
--help
,
-h
Displays a short help message.
--pin
pin-value
,
-p
pin-value
Specifies the current value of the global PIN.
--puk
pin-value
,
-u
pin-value
Specifies the current value of the global PUK.
--pin0
pin-value
,
-0
pin-value
Specifies the current value of the local PIN0 (aka local PIN).
--pin1
pin-value
,
-1
pin-value
Specifies the current value of the local PIN1 (aka local PUK).
--reader
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.
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.
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.
number
filename
This command will read one of your cards certificates (as specified by
number
) and save this certificate into file filename
in PEM-format. Certificates on a NetKey E4 card are readable without a pin, so you don't
have to specify one.
filename
number
This command will read the first PEM-encoded certificate from file
filename
and store this into your smart cards certificate file
number
. Some of your smart cards certificate files might be readonly, so
this will not work with all values of number
. If a certificate file is
writable you must specify a pin in order to change it. If you try to use this command
without specifying a pin, netkey-tool will tell you which one is
needed.
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.
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.
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.
openpgp-tool — utility for accessing visible data OpenPGP smart cards and compatible tokens
openpgp-tool
[OPTIONS
]
The openpgp-tool utility is used for accessing data from the OpenPGP v1.1 and v2.0 smart cards and compatible tokens like e.g. GPF CryptoStick v1.x, which might not be present in PKCS#15 objects but available in custom files on the card. The data can be printed on screen or used by other programs via environment variables.
--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.
iasecc-tool — displays information about IAS/ECC card
iasecc-tool
[OPTIONS
]
The iasecc-tool utility is used to display information about IAS/ECC v1.0.1 smart cards.
--reader
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.
opensc-tool — generic smart card utility
opensc-tool
[OPTIONS
]
The opensc-tool utility can be used from the command line to perform miscellaneous smart card operations such as getting the card ATR or sending arbitrary APDU commands to a card.
--version
,
Print the OpenSC package release version.
--atr
,
-a
Print the Answer To Reset (ATR) of the card. Output is in hex byte format
--card-driver
driver
,
-c
driver
Use the given card driver. The default is auto-detected.
--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.
opensc-explorer — generic interactive utility for accessing smart card and similar security token functions
opensc-explorer
[OPTIONS
] [SCRIPT
]
The opensc-explorer utility can be used interactively to perform miscellaneous operations such as exploring the contents of or sending arbitrary APDU commands to a smart card or similar security token.
The following are the command-line options for opensc-explorer. There are additional interactive commands available once it is running.
--card-driver
driver
,
-c
driver
Use the given card driver. The default is auto-detected.
--mf
path
,
-m
path
Select the file referenced by the given path on
startup. The default is the path to the standard master file,
3F00. If path
is empty (e.g. opensc-explorer
--mf ""), then no file is explicitly selected.
--reader
num
,
-r
num
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
The following commands are supported at opensc-explorer's
interactive prompt or in script files passed via the command line parameter
SCRIPT
.
hex-data
Send a custom APDU command hex-data
.
file-id
Parse and print the ASN.1 encoded content of the file specified by
file-id
.
file-id
| sfi:short-id
]
Print the contents of the currently selected EF or the contents
of a file specified by file-id
or the short file id
short-id
.
file-id
| aid:DF-name
}
Change to another DF specified by the argument passed.
If the argument given is ..
, then move up one level in the
file system hierarchy.
If it is file-id
, which must be a DF directly
beneath the current DF, then change to that DF.
If it is an application identifier given as
aid:
DF-name
,
then jump to the MF of the application denoted by
DF-name
.
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.
file-id
size
Create a new EF. file-id
specifies the
id number and size
is the size of the new file.
level
]
Set OpenSC debug level to level
.
If level
is omitted the current debug level will be shown.
file-id
Remove the EF or DF specified by file-id
hex-tag
[output
]
Copy the internal card's 'tagged' data into the local file.
The local file is specified by output
while the tag of
the card's data is specified by hex-tag
.
If output
is omitted, the name of the output file will be
derived from hex-tag
.
hex-tag
input
Update internal card's 'tagged' data.
hex-tag
is the tag of the card's data.
input
is the filename of the source file or the literal data presented as
a sequence of hexadecimal values or "
enclosed string.
string
...
Print the string
s given.
Erase the card, if the card supports it.
file-id
[output
]
Copy an EF to a local file. The local file is specified
by output
while the card file is specified by file-id
.
If output
is omitted, the name of the output file will be
derived from the full card path to file-id
.
file-id
]
Display attributes of a file specified by file-id
.
If file-id
is not supplied,
the attributes of the current file are printed.
pattern
...]
List files in the current DF.
If no pattern
is given, then all files are listed.
If one ore more pattern
s are given, only files matching
at least one pattern
are listed.
start-id
[end-id
]]
Find all files in the current DF.
Files are found by selecting all file identifiers in the range from start-fid
to end-fid
(by default from 0000 to FFFF).
start-tag
[end-tag
]]
Find all tags of data objects in the current context.
Tags are found by using GET DATA in the range from start-tag
to end-tag
(by default from 0000 to FFFF).
file-id
size
Create a DF. file-id
specifies the id number
and size
is the size of the new file.
file-id
input
Copy a local file to the card. The local file is specified
by input
while the card file is specified by file-id
.
Exit the program.
count
Generate random sequence of count
bytes.
file-id
Remove the EF or DF specified by file-id
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.
file-id
offs
data
Binary update of the file specified by
file-id
with the literal data
data
starting from offset specified
by offs
.
data
can be supplied as a sequencer
of the hex values or as a "
enclosed string.
file-id
rec-nr
rec-offs
data
Update record specified by rec-nr
of the file
specified by file-id
with the literal data
data
starting from offset specified by
rec-offs
.
data
can be supplied as a sequence of the hex values or
as a "
enclosed string.
key-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.
[open]
|[close]
Calls the card's open
or close
Secure Messaging handler.
piv-tool — smart card utility for HSPD-12 PIV cards
piv-tool
[OPTIONS
]
The piv-tool utility can be used from the command line to perform miscellaneous smart card operations on a HSPD-12 PIV smart card as defined in NIST 800-73-3. It is 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.
--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.
pkcs11-tool — utility for managing and using PKCS #11 security tokens
pkcs11-tool
[OPTIONS
]
The pkcs11-tool utility is used to manage the data objects on smart cards and similar PKCS #11 security tokens. Users can list and read PINs, keys and certificates stored on the token. User PIN authentication is performed for those operations that require it.
--attr-from
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
--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.
--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.)
--key-type
<replacement>specification</replacement>
Specify the type and length of the key to create, for example rsa:1024 or EC:prime256v1.
--usage-sign
Specify 'sign' key usage flag (sets SIGN in privkey, sets VERIFY in pubkey).
--usage-decrypt
Specify 'decrypt' key usage flag (RSA only, set DECRYPT privkey, ENCRYPT in pubkey).
--usage-derive
Specify 'derive' key usage flag (EC only).
--label
name
,
-a
name
Specify the name of the object to operate on
(or the token label when --init-token
is used).
--list-mechanisms
,
-M
Display a list of mechanisms supported by the token.
--list-objects
,
-O
Display a list of objects.
--list-slots
,
-L
Display a list of available slots on the token.
--list-token-slots
,
-T
List slots with tokens.
--login
,
-l
Authenticate to the token before performing other operations. This option is not needed if a PIN is provided on the command line.
--login-type
Specify login type ('so', 'user', 'context-specific'; default:'user').
--mechanism
mechanism
,
-m
mechanism
Use the specified mechanism
for token operations. See -M
for a list
of mechanisms supported by your token.
--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.
--puk
puk
Supply User PUK on the command line.
--new-pin
pin
Supply new User PIN on the command line.
--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.
--slot
id
Specify the id of the slot to use.
--slot-description
description
Specify the description of the slot to use.
--slot-index
index
Specify the index of the slot to use.
--token-label
label
Specify the label of token. Will be used the first slot, that has the inserted token with this label.
--so-pin
pin
Use the given pin
as the
Security Officer PIN for some token operations (token
initialization, user PIN initialization, etc). If set to
env:VARIABLE
, the value of the
environment variable VARIABLE
is
used. The same warning as --pin
also
applies here.
--test
,
-t
Perform some tests on the token. This
option is most useful when used with either --login
or --pin
.
--test-hotplug
Test hotplug capabilities (C_GetSlotList + C_WaitForSlotEvent).
--private
Set the CKA_PRIVATE attribute (object is only viewable after a login).
--test-ec
Test EC (best used with the --login
or --pin
option).
--test-fork
Test forking and calling C_Initialize() in the child.
--type
type
,
-y
type
Specify the type of object to operate on.
Examples are cert
, privkey
and pubkey
.
--verbose
, -v
Cause pkcs11-tool to be more verbose.
NB! This does not affect
OpenSC debugging level! To set OpenSC PKCS#11 module into debug
mode, set the OPENSC_DEBUG
environment variable to a
non-zero number.
--read-object
,
-r
Get object's CKA_VALUE attribute (use with
--type
).
--delete-object
,
-b
Delete an object.
--application-label
label
Specify the application label of the data object (use with
--type
data).
--application-id
id
Specify the application ID of the data object (use with
--type
data).
--issuer
data
Specify the issuer in hexadecimal format (use with
--type
cert).
--subject
data
Specify the subject in hexadecimal format (use with
--type
cert/privkey/pubkey).
--signature-format
format
Format for ECDSA signature: 'rs' (default), 'sequence', 'openssl'.
--write-object
id
,
-w
path
Write a key or certificate object to the token.
path
points to the DER-encoded certificate or key file.
pkcs15-crypt — perform crypto operations using PKCS#15 smart cards
pkcs15-crypt
[OPTIONS
]
The pkcs15-crypt utility can be used from the command line to perform cryptographic operations such as computing digital signatures or decrypting data, using keys stored on a PKCS#15 compliant smart card.
--version
,
Print the OpenSC package release version.
--aid
aid
Specify the AID of the on-card PKCS#15 application
to bind to. The aid
must be in hexadecimal
form.
--decipher
,
-c
Decrypt the contents of the file specified by
the --input
option. The result of the
decryption operation is written to the file specified by the
--output
option. If this option is not given,
the decrypted data is printed to standard output, displaying
non-printable characters using their hex notation xNN (see also
--raw
).
--input
file
,
-i
file
Specifies the input file to use. Defaults to stdin if not specified.
--key
id
,
-k
id
Selects the ID of the key to use.
--output
file
,
-o
file
Any output will be sent to the specified file. Defaults to stdout if not specified.
--pin
pin
,
-p
pin
When the cryptographic operation requires a PIN to access the key, pkcs15-crypt will prompt the user for the PIN on the terminal. Using this option allows you to specify the PIN on the command line.
Note that on most operating systems, the command line of a process can be displayed by any user using the ps(1) command. It is therefore a security risk to specify secret information such as PINs on the command line. If you specify '-' as PIN, it will be read from STDIN.
--pkcs1
By default, pkcs15-crypt
assumes that input data has been padded to the correct length
(i.e. when computing an RSA signature using a 1024 bit key,
the input must be padded to 128 bytes to match the modulus
length). When giving the --pkcs1
option,
however, pkcs15-crypt will perform the
required padding using the algorithm outlined in the
PKCS #1 standard version 1.5.
--raw
,
-R
Outputs raw 8 bit data.
--reader
N
,
-r
N
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.
pkcs15-tool — utility for manipulating PKCS #15 data structures on smart cards and similar security tokens
pkcs15-tool
[OPTIONS
]
The pkcs15-tool utility is used to manipulate the PKCS #15 data structures on smart cards and similar security tokens. Users can list and read PINs, keys and certificates stored on the token. User PIN authentication is performed for those operations that require it.
--version
,
Print the OpenSC package release version.
--aid
aid
Specify in a hexadecimal form the AID of the on-card PKCS#15 application to bind to.
--auth-id
pin
,
-a
pin
Specifies the auth id of the PIN to use for the operation. This is useful with the --change-pin operation.
--change-pin
Changes a PIN or PUK stored on the token. User authentication is required for this operation.
--dump
,
-D
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)
pkcs15-init — smart card personalization utility
pkcs15-init
[OPTIONS
]
The pkcs15-init utility can be used to create a PKCS #15 structure on a smart card, and add key or certificate objects. Details of the structure that will be created are controlled via profiles.
The profile used by default is pkcs15. Alternative
profiles can be specified via the -p
switch.
pkcs15-init can be used to create a PKCS #15 structure on
your smart card, create PINs, and install keys and certificates on the card.
This process is also called personalization
.
An OpenSC card can have one security officer PIN, and zero or more user PINs. PIN stands for Personal Identification Number, and is a secret code you need to present to the card before being allowed to perform certain operations, such as using one of the stored RSA keys to sign a document, or modifying the card itself.
Usually, PINs are a sequence of decimal digits, but some cards will accept arbitrary ASCII characters. Be aware however that using characters other than digits will make the card unusable with PIN pad readers, because those usually have keys for entering digits only.
The security officer (SO) PIN is special; it is used to protect meta data information on the card, such as the PKCS #15 structure itself. Setting the SO PIN is optional, because the worst that can usually happen is that someone finding your card can mess it up. To extract any of your secret keys stored on the card, an attacker will still need your user PIN, at least for the default OpenSC profiles. However, it is possible to create card profiles that will allow the security officer to override user PINs.
For each PIN, you can specify a PUK (also called unblock PIN
).
The PUK can be used to overwrite or unlock a PIN if too many incorrect values
have been entered in a row.
For some cards that use the PKCS#15 emulation, the attributes of private objects
are protected and cannot be parsed without authentication (usually with User PIN).
This authentication need to be done immediately after the card binding.
In such cases --verify-pin
has to be used.
This is the first step during card personalization, and will create the basic files on the card. To create the initial PKCS #15 structure, invoke the utility as
pkcs15-init --create-pkcs15
You will then be asked for the security officer PIN and PUK. Simply pressing return at the SO PIN prompt will skip installation of an SO PIN.
If the card supports it, you should erase the contents of the card with pkcs15-init --erase-card before creating the PKCS#15 structure.
Before installing any user objects such as private keys, you need at least one PIN to protect these objects. you can do this using
pkcs15-init --store-pin --id " nn
where nn
is a PKCS #15 ID in hexadecimal notation. Common
values are 01, 02, etc.
Entering the command above will ask you for the user's PIN and PUK. If you do not wish to install an unblock PIN, simply press return at the PUK prompt.
To set a label for this PIN object (which can be used by applications to display
a meaningful prompt to the user), use the --label
command line option.
pkcs15-init lets you generate a new key and store it on the card. You can do this using:
pkcs15-init --generate-key " keyspec " --auth-id " nn
where keyspec
describes the algorithm and length of the
key to be created, such as rsa/512
. This will create a 512 bit
RSA key. Currently, only RSA key generation is supported. Note that cards
usually support just a few different key lengths. Almost all cards will support
512 and 1024 bit keys, some will support 768 or 2048 as well.
nn
is the ID of a user PIN installed previously,
e.g. 01
.
In addition to storing the private portion of the key on the card, pkcs15-init will also store the the public portion of the key as a PKCS #15 public key object.
You can use a private key generated by other means and upload it to the card.
For instance, to upload a private key contained in a file named
okir.pem
, which is in PEM format, you would use
pkcs15-init --store-private-key okir.pem --id 45 --auth-id 01
In addition to storing the private portion of the key on the card, pkcs15-init will also store the the public portion of the key as a PKCS #15 public key object.
Note that usage of --id
option in the pkcs15-init
commands to generate or to import a new key is deprecated.
Better practice is to let the middleware to derive the identifier from the key material.
(SHA1(modulus) for RSA, SHA1(pub) for DSA, ...).
This allows easily set up relation between 'related' objects
(private/public keys and certificates).
In addition to the PEM key file format, pkcs15-init also supports DER encoded keys, and PKCS #12 files. The latter is the file format used by Netscape Navigator (among others) when exporting certificates to a file. A PKCS #12 file usually contains the X.509 certificate corresponding to the private key. If that is the case, pkcs15-init will store the certificate instead of the public key portion.
You can also upload individual public keys to the card using the
--store-public-key
option, which takes a filename as an
argument. This file is supposed to contain the public key. If you don't
specify a key file format using the --format
option,
pkcs15-init will assume PEM format. The only other
supported public key file format is DER.
Since the corresponding public keys are always uploaded automatically when generating a new key, or when uploading a private key, you will probably use this option only very rarely.
You can upload certificates to the card using the
--store-certificate
option, which takes a filename as
an argument. This file is supposed to contain the PEM encoded X.509
certificate.
Most browsers nowadays use PKCS #12 format files when you ask them to export your key and certificate to a file. pkcs15-init is capable of parsing these files, and storing their contents on the card in a single operation. This works just like storing a private key, except that you need to specify the file format:
pkcs15-init --store-private-key okir.p12 --format pkcs12 --auth-id 01
This will install the private key contained in the file okir.p12
,
and protect it with the PIN referenced by authentication ID 01
.
It will also store any X.509 certificates contained in the file, which is
usually the user certificate that goes with the key, as well as the CA certificate.
--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.
--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.
westcos-tool — utility for manipulating data structures on westcos smart cards
westcos-tool
[OPTIONS
]
The westcos-tool utility is used to manipulate the westcos data structures on 2 Ko smart cards / tokens. Users can create PINs, keys and certificates stored on the card / token. User PIN authentication is performed for those operations that require it.
--change-pin
,
-n
Changes a PIN stored on the card. User authentication is required for this operation.
--certificate
file
,
-t
file
Write certificate file file
in PEM format to the card.
User authentication is required for this operation.
--finalize
,
-f
Finalize the card. Once finalized the default key is invalidated, so PIN and PUK cannot be changed anymore without user authentication.
Warning, un-finalized 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.
Table of Contents
pkcs15-profile — format of profile for pkcs15-init
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@