diff --git a/ccid/README.dox b/ccid/README.dox index fc88cfa..0fd7bb7 100644 --- a/ccid/README.dox +++ b/ccid/README.dox @@ -3,18 +3,14 @@ Welcome to ccid. The purpose of ccid is to forward a PCSC smartcard reader as a standard USB CCID reader. If the host system is in USB device mode, ccid forwards the local reader via USB to an other device. If in USB host mode, -ccid virtually plugges in a USB CCID reader to the host system. +ccid virtually plugges in a USB CCID reader to the host system. ccid has +support for Password Authenticated Connection Establishment (PACE) using +OpenPACE (http://sourceforge.net/projects/openpace/). ccid is implemented using GadgetFS. Some fragments of the source code is based on the GadgetFS example at http://www.linux-usb.org/gadget/ and on the source code of the OpenSC tools. -pace-tool has support for Password Authenticated Connection Establishment -(PACE) using OpenPACE (see http://sourceforge.net/projects/openpace/). -pace-tool can be used for PIN management or to encrypt APDUs inside a secure -messaging channel established with PACE. PACE is experimental and disabled by -default. - @section i INSTALLATION @@ -33,36 +29,38 @@ http://docs.openmoko.org/trac/ticket/2206). If you also want to switch multiple times between gadgetfs and g_ether an other patch is needed (see https://docs.openmoko.org/trac/ticket/2240). -If you only use pace-tool for testing your card, you don't need gadgetfs. - @subsection o HINTS ON OPENSC -With PACE support enabled OpenSC older than r4244 will yield something like -this error: +ccid links against libopensc, which is discouraged and hindered since +opensc>=0.12. We really need to get rid of this dependency. But since this is a +lot of work, you will have to use older versions of opensc. + +OpenSC older than r4244 will yield something like this error: [default] apdu.c:341:sc_check_apdu: Invalid Case 4 short APDU: cse=04 cla=10 ins=86 p1=00 p2=00 lc=2 le=0 resp=0x10353c0 resplen=256 data=0x1034a30 datalen=2 [default] pace.c:1110:EstablishPACEChannel: Could not get encrypted nonce from card (General Authenticate step 1 failed). -It requires the following patch: +This requires the following patch: http://www.opensc-project.org/opensc/raw-attachment/ticket/209/le0.patch The following patch makes the hex dumped output more readable: -http://www.opensc-project.org/opensc/raw-attachment/ticket/263/hex_dump_align.patch +http://www.opensc-project.org/opensc/raw-attachment/ticket/263/hex_dump_align.2.patch @section u USAGE -When testing PACE with either PIN, CAN, MRZ or PUK run pace-tool. Here you can -enter APDUs which are to be converted according to the secure messaging -parameter and to be sent to the card. Herefor insert the APDU in hex (upper or -lower case) with a colon to separate the bytes or without it. Example APDUs can -be found in the file apdus. -To pass a secret to pace-tool, the command line parameters or the environment -variables PIN/CAN/MRZ/PUK/NEWPIN can be used. If none of these options is used, -pace-tool will show a password prompt. +ccid-emulator has various command line options to customize the appearance on +the USB host. To run ccid-emulator GadgetFS must be loaded and mounted. +ccid-emulator is compatible with the unix driver libccid and the windows smart +card driver. To initialize PACE using the PC/SC API you need to patch libccid +and pcsc-lite (see directory patches). + +cats-test can be used to test the PACE capabilities of a smart card reader with +PACE support (such as ccid-emulator or any other "Standardleser" CAT-S or +"Komfortleser" CAT-C) via PC/SC. @section q QUESTIONS diff --git a/npa/README.dox b/npa/README.dox index fc88cfa..1eba790 100644 --- a/npa/README.dox +++ b/npa/README.dox @@ -1,19 +1,15 @@ /** @mainpage -Welcome to ccid. The purpose of ccid is to forward a PCSC smartcard reader -as a standard USB CCID reader. If the host system is in USB device mode, ccid -forwards the local reader via USB to an other device. If in USB host mode, -ccid virtually plugges in a USB CCID reader to the host system. +Welcome to npa. The purpose of npa is to offer an easy to use API for the new +German identity card (neuer Personalausweis, nPA). The library also implements +secure messaging, which could also be used for other cards. -ccid is implemented using GadgetFS. Some fragments of the source code is based -on the GadgetFS example at http://www.linux-usb.org/gadget/ and on the source -code of the OpenSC tools. +npa is implemented using OpenPACE (http://sourceforge.net/projects/openpace/). +Some fragments of the source code are on the source code of the OpenSC tools. -pace-tool has support for Password Authenticated Connection Establishment -(PACE) using OpenPACE (see http://sourceforge.net/projects/openpace/). -pace-tool can be used for PIN management or to encrypt APDUs inside a secure -messaging channel established with PACE. PACE is experimental and disabled by -default. +The included pace-tool has support for Password Authenticated Connection +Establishment (PACE). pace-tool can be used for PIN management or to encrypt +APDUs inside a secure messaging channel established with PACE. @section i INSTALLATION @@ -21,36 +17,24 @@ default. See file INSTALL. -@subsection g HINTS ON GADGETFS - -To create an USB Gadget in both USB host and USB client mode, you need to load -the kernel module gadgetfs. A guide focused on Debian based systems to run and -compile gadgetfs, you can find here: -http://wiki.openmoko.org/wiki/Building_Gadget_USB_Module - -On OpenMoko it is likely, that you need to patch your kernel (see -http://docs.openmoko.org/trac/ticket/2206). If you also want to switch multiple -times between gadgetfs and g_ether an other patch is needed (see -https://docs.openmoko.org/trac/ticket/2240). - -If you only use pace-tool for testing your card, you don't need gadgetfs. - - @subsection o HINTS ON OPENSC -With PACE support enabled OpenSC older than r4244 will yield something like -this error: +npa links against libopensc, which is discouraged and hindered since +opensc>=0.12. We really need to get rid of this dependency. But since this is a +lot of work, you will have to use older versions of opensc. + +OpenSC older than r4244 will yield something like this error: [default] apdu.c:341:sc_check_apdu: Invalid Case 4 short APDU: cse=04 cla=10 ins=86 p1=00 p2=00 lc=2 le=0 resp=0x10353c0 resplen=256 data=0x1034a30 datalen=2 [default] pace.c:1110:EstablishPACEChannel: Could not get encrypted nonce from card (General Authenticate step 1 failed). -It requires the following patch: +This requires the following patch: http://www.opensc-project.org/opensc/raw-attachment/ticket/209/le0.patch The following patch makes the hex dumped output more readable: -http://www.opensc-project.org/opensc/raw-attachment/ticket/263/hex_dump_align.patch +http://www.opensc-project.org/opensc/raw-attachment/ticket/263/hex_dump_align.2.patch @section u USAGE