381 lines
18 KiB
Plaintext
381 lines
18 KiB
Plaintext
1. Introduction
|
|
===============
|
|
|
|
Nothing is impossible for the man who doesn't
|
|
have to do it himself. -- A.H. Weiler
|
|
|
|
This guide is about initialising and personalising (no distinction made) cards
|
|
with the OpenSC library and tools (mostly pkcs15-init).
|
|
|
|
Some knowlegde about smart cards is assumed. Below is a short overview of some
|
|
key words and concepts. For more info, see the opensc.html manual.
|
|
|
|
Filesystem - MF - DF - EF - FID
|
|
A smart cards has a non-volatile memory (EEPROM) in which usually a
|
|
PC-like file system is implemented. The directories are called Dedicated Files
|
|
(DF) and the files are called Elementary Files (EF). They are identified by a
|
|
a File ID (FID) on 2 bytes. For example, the root of the file system (called
|
|
Master File or MF) has FID = 3F 00 (hex).
|
|
|
|
Commands - APDUs
|
|
It is possible to send commands (APDUs) to the card to select, read, write,
|
|
create, list, delete, ... EFs and DFs (not all cards allow all commands).
|
|
|
|
Access control, PIN, PUK
|
|
The file system usually implements some sort of access control on EFs and DFs.
|
|
This is usually done by PINs or Keys: you have to provide a PIN or show
|
|
knowledge of a key before you can perform some command on some EF/DF. A PIN
|
|
is usually accompanied by a PUK (Pin Unblock Key), which can be used to reset
|
|
(or unblock) that PIN.
|
|
|
|
Cryptographic keys
|
|
On crypto cards, it is also possible to sign, decrypt, generate a key pair
|
|
(what can be done exactly depends on the card). on some cards, key and/or PINs
|
|
are files in the filesystem, on other cards, they don't exist in the
|
|
filesystem but are referenced through an ID.
|
|
|
|
Reader - PC/SC - OpenCT - CT-API
|
|
Smart card readers come with a library that can be used on a PC to send APDUs
|
|
to the card. Commonly used APIs for those libraries are PC/SC, OpenCT and
|
|
CT-API.
|
|
|
|
PKCS15
|
|
There are standards (e.g. ISO7816, parts 4-...) that specify how to select,
|
|
read, write, EFs and DFs, and how to sign, decrypt, login, ...
|
|
However, there is also a need to know which files contain what, or where the
|
|
keys, PINs, .. can be found.
|
|
For crypto cards, PCKS15 adresses this need by defining some files that contain
|
|
info on where to find keys, certificates, PINs, and other data. For example,
|
|
there is a PrKDF (Private Key Directory File) that contains the EFs or ID of
|
|
the private keys, what those keys can be used for, by which PINs they are
|
|
protected, ...
|
|
So a "PCKS15 card" is nothing but any other card on which the right set of
|
|
files has been added.
|
|
In short: PKCS15 allows you to describe where to find PINs, keys, certificates
|
|
and data on a card, plus all the info that is needed to use them.
|
|
|
|
A little PKCS15 example:
|
|
|
|
Here's the textual contents of 3 PKCS15 files: the AODF (Authentication
|
|
Object Directory File), PrKDF (Private Key Directory File) and CDF
|
|
(Certificate Directory File) that contain info on resp. the PINs, private
|
|
keys and certificates. Each of them contains 1 entry.
|
|
|
|
AODF:
|
|
Com. Flags : private, modifiable
|
|
Auth ID : 01
|
|
Flags : [0x32], local, initialized, needs-padding
|
|
Length : min_len:4, max_len:8, stored_len:8
|
|
Pad char : 0x00
|
|
Reference : 1
|
|
Encoding : ASCII-numeric
|
|
Path : 3F005015
|
|
|
|
PrKDF:
|
|
Com. Flags : private, modifiable
|
|
Com. Auth ID: 01
|
|
Usage : [0x32E], decrypt, sign, signRecover, unwrap, derive, nonRep
|
|
Access Flags: [0x1D], sensitive, alwaysSensitive, neverExtract, local
|
|
ModLength : 1024
|
|
Key ref : 0
|
|
Native : yes
|
|
Path : 3F00501530450012
|
|
ID : 45
|
|
|
|
X.509 Certificate [/C=BE/ST=...]
|
|
Com. Flags : modifiable
|
|
Authority : no
|
|
Path : 3f0050154545
|
|
ID : 45
|
|
|
|
Some things to note:
|
|
- The Auth ID (01) of the private key is the same as the one of the PIN which
|
|
means that you first have to do a login with this PIN before you can use
|
|
this key.
|
|
- The key is in an EF with ID = 0012 in the DF with ID = 3045, which on its
|
|
turn is a DF with ID = 5015, which on its turn is a DF of the MF (3F00).
|
|
- The private key and certificate share the same ID (45), which means that they
|
|
belong together.
|
|
- The cert is in the EF with as path: 3F00\5015\4545 and is no CA cert.
|
|
|
|
Use the tests/p15dump tool to see yourself what pkcs15 data is on
|
|
your card, or tools/opensc-explorer to browse through the files.
|
|
|
|
Have the PKCS15 files a fixed place so everyone can find them? No, there's
|
|
only one: the EF(DIR) in the MF and with ID 2F00. That's the starting place.
|
|
|
|
|
|
2. The OpenSC pkcs15-init library and profiles
|
|
==============================================
|
|
|
|
Reading and writing files, PIN verification, signing and decryption happen in
|
|
much the same way on all cards. Therefore, the "normal life" commands have
|
|
been implemented in OpenSC for all supported cards.
|
|
|
|
However, creating and deleting files, PINs and keys is very card specific and
|
|
has not yet been implemented for all cards. Currently, pkcs15-init is
|
|
implemented for: Cryptoflex, Cyberflex, CardOS (etoken), GPK, Miocos, Starcos
|
|
JCOP and Oberthur. (Check src/pkcs15init/pkcs15-*.c for possible updates).
|
|
Because of this, and because pkcs15-init is not necessary for "normal life"
|
|
operations, it has been put in a separate library and in a separate directory.
|
|
|
|
Profile
|
|
Because the initialisation/personalisation is so card-specific, it would be
|
|
very hard to make a tool or API that accepts all parameters for all current
|
|
and future cards. Therefore, a profile file has been made in OpenSC that
|
|
contains all the card-specific parameters. This card-specific profile is read
|
|
by card-specific code in the pkcs15-init library each time this library is
|
|
used on that card.
|
|
See the *.profile files in src/pkcs15init/. There is one general file
|
|
(pkcs15.profile) and one card-specific profile for each card.
|
|
|
|
Profile options
|
|
There are currently 3 options you can specify to modify a profile:
|
|
- default: creation/deletion/generation is controlled by the SO PIN (SO =
|
|
Security Officer, different from the regular user of the card)
|
|
- onepin: creation/deletion/generation is controlled by the user PIN and thus
|
|
by the user. As a result, only 1 user PIN is possible
|
|
- small: like default, but suitable for card with little memory
|
|
|
|
|
|
3. pkcs15-init tool
|
|
===================
|
|
|
|
This is a command-line tool that uses the pkcs15-init library. It allows you
|
|
to do all the init/perso things, e.g. add/delete keys, certificates, PINs and
|
|
data, generate keys, ... while specifying key usage, which PIN protects
|
|
which key, ...
|
|
|
|
As said before, not all cards are supported in the pkcs15-init library. In that
|
|
case, the pkcs15-init tool won't work (top 5 questions on the mailing list :-).
|
|
To find out which card you have, try "opensc-tool -n"
|
|
|
|
Below is explained how to do the operations that are supported by pkcs15-tool.
|
|
Not all options are explained (run "pkcs15-tool -h" to see them) because some
|
|
are card-specific or obsolete (or we don't know about them). Feel free to
|
|
experiment and explain them here.
|
|
|
|
So the things in this section are fairly general but not guaranteed to work
|
|
for all cards. See also the section on "card-specific issues".
|
|
|
|
The --reader or -r can be given with any command. By default the first reader
|
|
is used. Do "opensc-tool -l" to see the list of available readers.
|
|
|
|
To see the results of what you did, you can do one of the following:
|
|
pkcs15-tool --list-pins --list-public-keys -k -c -C
|
|
p15dump (in the src/tests directory)
|
|
To see/dump the content of any file, use the opensc-explorer tool.
|
|
|
|
* Create the PKCS15 files
|
|
pkcs15-init -C {-T} {-p <profile>}
|
|
--so-pin <PIN> --so-puk <PUK> | --no-so-pin | --pin <PIN> --puk <PUK>
|
|
This will create the PKCS15 DF (5015) and all the PKCS15 files (some of which
|
|
will be empty until a key, PIN, ... will be added). It must be done before you
|
|
can do any of the operations below.
|
|
- This operation usually requires a 'transport' key. pkcs15-init will ask you
|
|
for this key and propose the default one for that card. With -T, the default
|
|
key will be used without asking. NOTE: if you get a "Failed to erase card:
|
|
PIN code or key incorrect", the transport key is wrong. Find this key and
|
|
then try again, DO NOT try with the default key again!
|
|
- If you want an SO PIN and PUK, do so with the --so-pin and --so-puk options,
|
|
or specify --no-so-pin if you don't want them. If you use the onepin profile,
|
|
there is no SO PIN so you should specify --pin and --puk instead.
|
|
(So you get: pkcs15-init -CT -p pkcs15+onepin --pin <PIN> --puk <PUK>)
|
|
- To specify the profile file + option. The profile file can only be "pkcs15"
|
|
for the moment, so you can have:
|
|
pkcs15+default : the default (not needed to specify it)
|
|
pkcs15+onepin : for the onepin profile option
|
|
pkcs15+small : for the small profile option
|
|
|
|
* Erase the card's content
|
|
pkcs15-init -E {-T}
|
|
This will delete all keys, PINs, certificates, data that were listed in PKCS15
|
|
files, along with the PKCS15 files themselves.
|
|
- This operation usually requires a 'transport' key. pkcs15-init will ask you
|
|
for this key and propose the default one for that card. With -T, the default
|
|
key will be used without asking. NOTE: if you get a "Failed to erase card:
|
|
PIN code or key incorrect", the transport key is wrong. Find this key and
|
|
then try again, DO NOT try the default key again!
|
|
|
|
Note: you can combine erase/create (-E -C or -EC) to erase and then create
|
|
the card's contents, except when you change the profile option.
|
|
|
|
* Add a PIN (not possible with the onepin profile option)
|
|
pkcs15-init -P {-a <AuthID>} {--pin <PIN>} {--puk <PUK>} {-l <label>}
|
|
- You can specify the AuthID with -a, if you don't do so, a value that didn't
|
|
exist yet on the card will be used.
|
|
- Specify the PIN and PUK with --pin and --puk, if you don't do so, the tool
|
|
will prompt you for one.
|
|
- Specify the label (name) of the PIN with -l, or accept the default label.
|
|
|
|
* Generate a key pair (on card or in software on the PC)
|
|
pkcs15-init -G <keyspec> -a <AuthID> --insecure {-i <ID>} {--soft}
|
|
{-u <keyusage>}
|
|
{-l <privkeylabel>} {--public-key-label <pubkeylabel>}
|
|
This will generate a public and private key pair.
|
|
- The keyspec consist of the key type, rsa or dsa (depends on what your card
|
|
supports), and optinally a slash followed by the keysize in bits. E.g.
|
|
"rsa/1024" specifies a 1024-bit RSA key pair. Note: dsa is not fully
|
|
supported.
|
|
- Specify the AuthID of the PIN that protects this key (protect from being
|
|
used in a signature or decryption operation) with -a; or specify --insecure
|
|
if you want the private key to be used without first providing a PIN.
|
|
- Specify the ID of the key with -i, otherwise the tool will choose one.
|
|
- Specify --soft if you don't want the key pair to be generated on card.
|
|
- Specify the usage of the private key with -u; if you add a
|
|
corresponding certificate later, it should have the same key usage.
|
|
(Do "pkcs15-init -u help" for help).
|
|
- Specify the label (name) of the private key with -l, or accept the default
|
|
label.
|
|
- Specify the label (name) of the public key with --public-key-label, or
|
|
accept the default label.
|
|
- Depending on your card and profile option, you will be prompted to provide
|
|
your SO PIN and/or PIN; if you don't want to be prompted, add them to the
|
|
command line with --so-pin <SOPIN> and/or --pin <PIN>.
|
|
NOTE: see the SSL engines (below) on how to make a certificate request with
|
|
the key you generated.
|
|
|
|
* Add a private key
|
|
pkcs15-init -S <keyfile> {-f <keyformat>} -a <AuthID> --insecure
|
|
{-i <ID>} {-u <keyusage>} {--passphrase <password>}
|
|
{-l <label>}
|
|
- The keyfile should be in DER (binary) or PEM format.
|
|
- The keyformat should be PEM (default) or DER.
|
|
- Specify the AuthID of the PIN that protects the private key (from being used
|
|
in a signature or decryption operation) with -a; or specify --insecure if
|
|
you want the private key to be used without first providing a PIN
|
|
- Specify the ID of the key with -i
|
|
- Specify the usage of the private key with -u; if you add a
|
|
corresponding certificate later, it should have the same key usage.
|
|
(Do "pkcs15-init -u help" for help).
|
|
- Specify the label (name) of the with -l, or accept the default label if
|
|
you don't do so.
|
|
- Depending on your card and profile option, you will be prompted to provide
|
|
your SO PIN and/or PIN; if you don't want to be prompted, add them to the
|
|
command line with --so-pin <SOPIN> and/or --pin <PIN>.
|
|
|
|
* Add a private key + certificate(s) (in a pkcs12 file)
|
|
pkcs15-init -S <pkcs12file> -f PKCS12 -a <AuthID> {--insecure} {-i <ID>}
|
|
{-u <keyusage>} {--passphrase <password>}
|
|
{-l <privkeylabel>} {--cert-label <usercertlabel>}
|
|
This adds the private key and certificate chain to the card. If a certificate
|
|
already exists in the card, it won't be added again.
|
|
- Specify the AuthID of the PIN that protects this key (protect from being
|
|
used in a signature or decryption operation) with -a; or specify --insecure
|
|
if you want the private key to be used without first providing a PIN.
|
|
- Specify the ID of the key and the corresponding certificate with -i,
|
|
otherwise the tool with choose one; only the 'user cert' will get the same
|
|
ID as the key,
|
|
the other certificates will get 'authority' status and another ID.
|
|
- You can specify the key-usage, but it is advised not to do this so the key
|
|
usage is fetched from the certificate.
|
|
- Specify the password of the pkcs12 key file if you don't want to be prompted
|
|
for one.
|
|
- Specify the label (name) of the private key with -l, or accept the default
|
|
label if you don't do so.
|
|
- Specify the label (name) of the user certificate with --cert-label, or
|
|
accept the default label if you don't do so.
|
|
- Depending on your card and profile option, you will be prompted to provide
|
|
your SO PIN and/or PIN; if you don't want to be prompted, add them to the
|
|
command line with --so-pin <SOPIN> and/or --pin <PIN>.
|
|
|
|
* Add a certificate
|
|
pkcs15-init -W <certfile> {-f <certformat>} {-i <ID>} {--authority}
|
|
- The certfile should be in DER (binary) or PEM format
|
|
- The certformat should be PEM (default) or DER
|
|
- Specify the ID of the certificate with -i, otherwise the tool with choose
|
|
one; if the certificate corresponds to a private and/or public key, you
|
|
should specify the same ID as that key.
|
|
- Specify --authority if it is a CA certificate.
|
|
- Depending on your card and profile option, you will be prompted to provide
|
|
your SO PIN and/or PIN; if you don't want to be prompted, add them to the
|
|
command line with --so-pin <SOPIN> and/or --pin <PIN>.
|
|
|
|
* Add a public key
|
|
pkcs15-init --store-public-key <keyfile> {-f <keyformat>} {-i <ID>}
|
|
{-l <label>}
|
|
- The keyfile should be in DER (binary) or PEM format
|
|
- The keyformat should be PEM (default) or DER
|
|
- Specify the ID of the key with -i, otherwise the tool with choose one;
|
|
if the key corresponds to a private key and/or certificate, you should
|
|
specify the same ID as that private key and/or certificate.
|
|
- Specify the label (name) of the with -l, or accept the default label if
|
|
you don't do so.
|
|
- Depending on your card and profile option, you will be prompted to provide
|
|
your SO PIN and/or PIN; if you don't want to be prompted, add them to the
|
|
command line with --so-pin <SOPIN> and/or --pin <PIN>.
|
|
|
|
* Add data
|
|
pkcs15-init -W <datafile> {-i <ID>} {-l <label>}
|
|
- The datafile is stored "as is" onto the card.
|
|
- Specify the ID of the data with -i, or accept the default ID.
|
|
- Specify the label (name) of the data with -l, or accept the default label.
|
|
- Depending on your card and profile option, you will be prompted to provide
|
|
your SO PIN and/or PIN; if you don't want to be prompted, add them to the
|
|
command line with --so-pin <SOPIN> and/or --pin <PIN>.
|
|
|
|
|
|
4. Other tools
|
|
==============
|
|
|
|
* SSL-engines
|
|
|
|
These libraries can be loaded in OpenSSL so you can do a certificate request
|
|
with the openssl tool; the signature of the certificate request will then be
|
|
made using the smart card. The result can then be sent to a CA for
|
|
certification or the resulting certificate can be put on the card with pkcs15-init
|
|
or pkcs11-tool.
|
|
- Run openssl
|
|
- On the openssl command prompt, type
|
|
engine dynamic -pre SO_PATH:engine_pkcs11 -pre ID:pkcs11 -pre LIST_ADD:1 -pre LOAD
|
|
or
|
|
engine dynamic -pre SO_PATH:engine_opensc -pre ID:opensc -pre LIST_ADD:1 -pre LOAD
|
|
depending on which one of the 2 engines (pkcs11 or opensc) you want to use.
|
|
- Then type (on the openssl command prompt)
|
|
req -engine pkcs11 -new -key <ID> -keyform engine -out <cert_req>
|
|
or
|
|
req -engine opensc -new -key <ID> -keyform engine -out <cert_req>
|
|
in which ID is the slot+ID in the following format:
|
|
[slot_<slotID>][-][id_<ID>], e.g. id_45 or slot_0-id_45
|
|
|
|
* pkcs11-tool and Mozilla/Netscape
|
|
|
|
You can use the OpenSC pkcs11 library to generate a key pair in Mozilla or
|
|
Netscape, and let the browser generate a certificate request that is sent
|
|
to an on-line CA to issue and send you a certificate that is then added to the
|
|
card.
|
|
|
|
Just go to an online CA (Globalsign, Thawte, ...) and follow their guidelines.
|
|
Because such a request either costs you or at least requires you to provide a
|
|
valid mail address, it is advisable to first try you card with
|
|
"pkcs11-tool --moz-cert <cert_file_in_der_format> --login".
|
|
|
|
NOTE: This can only be done with the onepin profile option (because the browser
|
|
won't ask for an SO PIN, only for the user PIN).
|
|
|
|
|
|
5. Card-specific issues
|
|
=======================
|
|
|
|
Experience is that marvelous thing that enables you to recognize
|
|
a mistake when you make it again. -- Franklin P. Jones
|
|
|
|
Cryptoflex:
|
|
- DFs and EFs in a DF have to be deleted in reverse order of creation.
|
|
OpenSC relies on this fact for security, but also has some downsides. For
|
|
example, if you did a "pkcs15-init -C" and then added some EFs or DFs in the
|
|
MF, you won't be able to do a "pkcs15-init -E" afterwards to remove the
|
|
PKCS15 DF (5015). So you'll first have to manually remove all EFs/DFs you
|
|
created in the MF before being able remove the pkcs15 DF.
|
|
|
|
Starcos SPK 2.3:
|
|
- Due to the way Starcos SPK 2.3 manages access rights it is necessary
|
|
to manually call "pkcs15-init --finalize" after card personalization
|
|
if no SO-PIN has been specified. Once the card has been finalized it is
|
|
not possible to add new private/secret keys or PINs. If a SO-PIN is
|
|
used the card will automatically be finalized after the SO-PIN has
|
|
been stored.
|
|
- If an SO-PIN is used and if there is enough space in the key file left,
|
|
then the owner of the SO-PIN can access/use every protected item by
|
|
creating a PIN for the necessary state.
|