diff --git a/doc/Makefile.am b/doc/Makefile.am index ebcc1ee2..302fa381 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,6 +1,6 @@ # Process this file with automake to create Makefile.in -SUBDIRS = . old +SUBDIRS = . MAINTAINERCLEANFILES = Makefile.in $(HTML) ChangeLog @@ -14,7 +14,6 @@ XML = $(shell ls $(srcdir)/tools/*.xml $(srcdir)/api/*.xml $(srcdir)/api/*/*.xml index.html: sh $(srcdir)/export-wiki.sh $(srcdir) sh $(srcdir)/generate-man.sh $(srcdir) - sh $(srcdir)/old/generate.sh $(srcdir)/old ChangeLog: sh $(srcdir)/changelog.sh $(srcdir) diff --git a/doc/old/Makefile.am b/doc/old/Makefile.am deleted file mode 100644 index fae45a8d..00000000 --- a/doc/old/Makefile.am +++ /dev/null @@ -1,11 +0,0 @@ -# Process this file with automake to create Makefile.in - -XSLTPROC = @XSLTPROC@ -SOURCE = opensc.xml opensc.xsl opensc-es.xml opensc.css opensc.xsl -GENERATE = opensc.html opensc-es.html -NILS = init_perso_guide.html init_perso_guide.txt - -MAINTAINERCLEANFILES = Makefile.in $(GENERATE) - -EXTRA_DIST = pkcs-15v1_1.asn $(NILS) $(SOURCE) $(GENERATE) doxygen.conf generate.sh - diff --git a/doc/old/doxygen.conf b/doc/old/doxygen.conf deleted file mode 100644 index b6931725..00000000 --- a/doc/old/doxygen.conf +++ /dev/null @@ -1,7 +0,0 @@ -INPUT = ../src/libopensc -FILE_PATTERNS = *.h -PROJECT_NAME = OpenSC -PROJECT_NUMBER = 0.10.0 -HIDE_UNDOC_MEMBERS = YES -SORT_MEMBER_DOCS = NO -OPTIMIZE_OUTPUT_FOR_C = YES diff --git a/doc/old/generate.sh b/doc/old/generate.sh deleted file mode 100644 index 66979d6c..00000000 --- a/doc/old/generate.sh +++ /dev/null @@ -1,22 +0,0 @@ -#!/bin/bash - -set -e - -SRCDIR=. - -if test -n "$1" -then - SRCDIR="$1" -fi - -test -f "$SRCDIR"/`basename $0` - -if ! test -w "$SRCDIR" -then - exit 0 -fi - - xsltproc -o "$SRCDIR"/opensc.html "$SRCDIR"/opensc.xsl "$SRCDIR/"opensc.xml - tidy -im -utf8 -xml "$SRCDIR"/opensc.html || true - xsltproc -o "$SRCDIR"/opensc-es.html "$SRCDIR"/opensc.xsl "$SRCDIR"/opensc-es.xml - tidy -im -utf8 -xml "$SRCDIR"/opensc-es.html || true diff --git a/doc/old/init_perso_guide.html b/doc/old/init_perso_guide.html deleted file mode 100644 index 75363466..00000000 --- a/doc/old/init_perso_guide.html +++ /dev/null @@ -1,466 +0,0 @@ - - - init_perso_guide - - -

OpenSC card init and perso guide

-

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 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, key(pair) -generation (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:
- -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/pkcs15-init/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/pkcs15-init/. 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:
- -

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

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

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

* 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 on the card, it won't be added again.
- -

* Add a certificate

-      -pkcs15-init -W <certfile> {-f <certformat>} {-i <ID>} -{--authority}
- -

* Add a public key

-      pkcs15-init ---store-public-key <keyfile> {-f <keyformat>} {-i -<ID>} {-l <label>}
- -

* Add data

-      pkcs15-init --W <datafile> {-i <ID>} {-l <label>}
- -

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 on the certificate request -will -then be made with the smart card. The result can then be sent to a CA -for certification, the resulting certificate can be put on the card -with -pkcs15-init or pkcs11-tool.
- - -

* pkcs11-tool and Mozilla/Netscape

-You can use the OpenSC pkcs11 library to generate a keypair 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:
- -Starcos SPK 2.3:
- -
- diff --git a/doc/old/init_perso_guide.txt b/doc/old/init_perso_guide.txt deleted file mode 100644 index 72a66283..00000000 --- a/doc/old/init_perso_guide.txt +++ /dev/null @@ -1,380 +0,0 @@ -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 } - --so-pin --so-puk | --no-so-pin | --pin --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 --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 } {--pin } {--puk } {-l