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.

PKCS#15

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, PKCS15 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 "PCKS#5 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 PKCS#15 example

Here's the textual contents of 3 PKCS#15 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 pkcs15-tool --dump tool to see yourself what pkcs15 data is on your card, or opensc-explorer to browse through the files.

Have the PKCS#15 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 a fixnDiscussion.html0000644000000000000000000000702310671167315020034 0ustar rootroot DesignDiscussion - OpenSC - Trac

Design issues

Every change that is not a small fix or minor enhancement requires some kind of design. In order to discuss design decisions as much as possible and leave some kind of track about decisions made and design in place other than source code and comments and maybe even documentation, this sector of the wiki could be used. As always - feel free to comment (but please leave your name after your comment).

Pinpad functionality

(Martin) Current state of secure pin entry methods in OpenSC is somewhat limited and hairy. Checks and features and functionality spans several component borders (application, library, card driver, reader, pkcs15 layer, etc). The target is to provide smooth pinpad support.

In theory different layers affect the total pinpad-oriented functioning:

Reader capabilities - actual reader capabilities detected and enabled by the reader (ctapi, pcsc, openct)
Reader driver and how-if-what verify methods it implements (though the name verify is not correct if we talk about full pin operations)
Card driver and if it implements the new pin command interface or if it is possible at all for the given card (maybe it uses some other method, maybe it uses non-numeric passwords)
pkcs15 layer - what it thinks about underlying hardware capacities and if/how it makes use of it
pkcs11 layer - exports PROTECTED_AUTHENTICATION_PATH to indicate 'secure authentication (aka pinpad)' and itself feeds data to pkcs15 layer.
applications - how they interpret various parameters (like slot capabilities, pkcs11 features, etc), how/if they react or should react on empty pins etc.
Library internal UI functionality - instead of asking for a pin who should notify the user to insert the pin to the pinpad and how?

All these should be put to work for a common goal in a nice way.

Requirements

Slot flags must correctly state the capabilities of the slot and all functionality must strictly check this flag.
A card driver should have a possibility to disable pinpad enabled functionality even if the slot tells it can do it - for reasons like character passwords
It should be possible to disable pinpad functionality on reader(driver)/global layer as a configuration option - this will result the slot capabilities to be hidden
It should be possible to disable pinpad functionality on a higher level - as a global option. This could result in different
pkcs11 flag about secure authentication flag can be affected by any of the previous config options.
One reader should support different verification methods (you can talk class2 via pcsc and you can talk ctbcs)

Things to keep in mind

Backwards compatibility
User interaction.

Decisions

Implement pinpad functionality in a proper way (err, small decisions should be outlined now)

... to be continued ...

./usr/share/doc/opensc/copyright0000644000000000000000000000121511505776665015634 0ustar rootrootThis package was debianized by Eric Dorland on Mon, 22 Dec 2003 23:23:29 -0500. It was downloaded from http://www.opensc.org/ Upstream Authors: OpenSC developers Juha Yrjölä Antti Tapaninen Timo Teräs Olaf Kirch Copyright (C) 2001, 2002 Juha Yrj, Timo Teras, Antti Tapaninen, Olaf Kirch You are free to distribute this software under the terms of the GNU Lesser General Public License. On Debian systems, the complete text of the GNU Lesser General Public License can be found in the file `/usr/share/common-licenses/LGPL'. ./usr/share/doc/opensc/StarKey.html0000644000000000000000000000544010671167315016142 0ustar rootroot StarKey - OpenSC - Trac

StarSign® USB Token

The user-friendly combination of chip card and card reader

StarSign USB Token belongs to a new generation of manipulation-proof IT security products, designed for costeffective use in PKI systems. It combines the security features of a chip card with the advantages of USB devices. StarSign USB Token contributes to the improved efficiency of IT applications, reduces costs, and offers optimum flexibility. The token is small, light, and so conveniently sized that it fits on a key chain. It requires no additional reader since it connects directly to the PC via USB interface. In many environments, such as Wireless LAN, it can be used for authentication as an alternative or supplement to the conventional combination of chip card and reader.

An intelligent solution that ensures high-level security

Two-factor authentication ensures that the user can only access the system with the combination of StarSign USB Token and PIN. Unless both match, the user is not authorized to access the corresponding applications and data. StarSign USB Token offers recognized and certified security. Sensitive information is securely saved on the token. All actions, e.g. encryption or digital signatures, are executed on the token itself. This ensures that private keys cannot be read or copied from the token. Compared to software-based solutions, this provides a considerably higher level of security.

Flash memory for saving further data

On request the StarSign USB Token is available with additional flash memory. It does not only securely store the user’s data such as personal profiles and X.509 digital certificates, but also offers the user a memory capacity of up to 1 GB. This can be used for saving further data and applications.

See more on: http://www.gi-de.com/portal/page?_pageid=42,104630&_dad=portal&_schema=PORTAL

./usr/share/doc/opensc/Pkcs15Init.html0000644000000000000000000005541210671167315016456 0ustar rootroot Pkcs15Init - OpenSC - Trac