diff --git a/ccid/doc/Makefile.am b/ccid/doc/Makefile.am index ece80c5..0a477e2 100644 --- a/ccid/doc/Makefile.am +++ b/ccid/doc/Makefile.am @@ -16,11 +16,12 @@ do_subst = $(SED) \ -e 's,[@]abs_top_srcdir[@],$(abs_top_srcdir),g' \ -e 's,[@]top_srcdir[@],$(top_srcdir),g' -EXTRA_DIST = README.rst.in README.rst autotools.rst autotools.rst.in questions.rst questions.rst.in +EXTRA_DIST = README.rst.in README.rst autotools.rst autotools.rst.in questions.rst questions.rst.in download.rst.in download.rst doc: *.in $(do_subst) < autotools.rst.in > autotools.rst $(do_subst) < questions.rst.in > questions.rst + $(do_subst) < download.rst.in > download.rst $(do_subst) < README.rst.in > README.rst touch doc diff --git a/ccid/doc/README.rst.in b/ccid/doc/README.rst.in index ce787ae..f30711d 100644 --- a/ccid/doc/README.rst.in +++ b/ccid/doc/README.rst.in @@ -53,6 +53,9 @@ tools. .. [#f1] Note that the heavily outdated `Windows USB CCID driver `_ does not support secure PIN entry or PIN modification. @PACKAGE_NAME@ comes with a patch for libccid_ to support |PACE|, because it is not yet standardised in USB CCID. However, the traditional commands can be used without restriction. +.. include:: download.rst + + .. include:: autotools.rst Running the @PACKAGE_NAME@ has the following dependencies: diff --git a/ccid/doc/download.rst.in b/ccid/doc/download.rst.in new file mode 120000 index 0000000..30d6cb5 --- /dev/null +++ b/ccid/doc/download.rst.in @@ -0,0 +1 @@ +../../doc/download.rst.in \ No newline at end of file diff --git a/doc/conf.py b/doc/conf.py index c630040..e7269cb 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -51,7 +51,7 @@ master_doc = 'index' # General information about the project. project = u'Virtual Smart Card Architecture' -copyright = u'2009-2012 by Dominik Oepen and Frank Morgner' +copyright = u'2009-2013 by Dominik Oepen and Frank Morgner' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -74,7 +74,7 @@ release = '2012-04-11' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build', '*/questions.rst', '*/autotools.rst'] +exclude_patterns = ['_build', '*/questions.rst', '*/autotools.rst', '*/download.rst'] # The reST default role (used for this markup: `text`) to use for all documents. #default_role = None diff --git a/doc/download.rst.in b/doc/download.rst.in new file mode 100644 index 0000000..a683326 --- /dev/null +++ b/doc/download.rst.in @@ -0,0 +1,12 @@ +.. highlight:: sh + +=============================================================================== +Download +=============================================================================== + +You can find the latest release of @PACKAGE_NAME@ `here +`_. + +Alternatively, you can clone our git repository:: + + git clone git://vsmartcard.git.sourceforge.net/gitroot/vsmartcard/vsmartcard diff --git a/doc/index.rst b/doc/index.rst index f2492a3..9507768 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,3 +1,5 @@ +.. highlight:: sh + .. |vsmartcard| replace:: Virtual Smart Card Architecture Welcome to the |vsmartcard| documentation! @@ -59,9 +61,13 @@ Mobile Phone with Virtual Smartcard connected via USB :width: 320px +======== Download ======== -You can download the latest release of the |vsmartcard| `here `_. +You can download the latest release of the |vsmartcard| `here +`_. -Alternatively you can check out the source code from our `subversion repository `_. +Alternatively, you can clone our git repository:: + + git clone git://vsmartcard.git.sourceforge.net/gitroot/vsmartcard/vsmartcard diff --git a/npa/doc/Makefile.am b/npa/doc/Makefile.am index cab92b0..a68f52f 100644 --- a/npa/doc/Makefile.am +++ b/npa/doc/Makefile.am @@ -16,7 +16,7 @@ do_subst = $(SED) \ -e 's,[@]abs_top_srcdir[@],$(abs_top_srcdir),g' \ -e 's,[@]top_srcdir[@],$(top_srcdir),g' -EXTRA_DIST = README.rst.in README.rst Doxyfile.in example.c autotools.rst autotools.rst.in questions.rst questions.rst.in +EXTRA_DIST = README.rst.in README.rst Doxyfile.in example.c autotools.rst autotools.rst.in questions.rst questions.rst.in download.rst.in download.rst DOXYGEN = doxygen @@ -26,6 +26,7 @@ doc: $(top_srcdir)/src/npa/*.h *.in touch api.rst $(do_subst) < autotools.rst.in > autotools.rst $(do_subst) < questions.rst.in > questions.rst + $(do_subst) < download.rst.in > download.rst $(do_subst) < README.rst.in > README.rst touch doc diff --git a/npa/doc/README.rst b/npa/doc/README.rst index 8c2e36b..03ceab0 100644 --- a/npa/doc/README.rst +++ b/npa/doc/README.rst @@ -35,6 +35,9 @@ transparent SM usage in OpenSC. This allows nPA Smart Card Library to be fully compatible with OpenSC. +.. include:: download.rst + + .. _npa-install: .. include:: autotools.rst @@ -79,7 +82,7 @@ of OpenSC_:: cd $VSMARTCARD/npa/src/opensc autoreconf --verbose --install # adding PKG_CONFIG_PATH here lets OpenSC use OpenSSL with OpenPACE - ./configure --prefix=$PREFIX PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig + ./configure --prefix=$PREFIX PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig --enable-sm make install && cd - Now :file:`libopensc.so` should be located in ``$PREFIX/lib``. @@ -94,7 +97,7 @@ To complete this step-by-step guide, here is how to install nPA Smart Card Libra cd $VSMARTCARD/npa autoreconf --verbose --install # adding PKG_CONFIG_PATH here lets OpenSC use OpenSSL with OpenPACE - ./configure --prefix=$PREFIX PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig OPENSC_LIBS="-L$PREFIX/lib -lopensc" + ./configure --prefix=$PREFIX PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig OPENSC_LIBS="-L$PREFIX/lib -lopensc -lcrypto" make install && cd - @@ -105,9 +108,13 @@ To complete this step-by-step guide, here is how to install nPA Smart Card Libra Usage ===== +The API to libnpa is documented in :ref:`npa-api`. It includes a simple +programming example. Here we will focus on the command line interface to the +library offered by the |npa-tool|. + To pass a secret to |npa-tool| for |PACE|, command line parameters or environment variables can be used. If the smart card reader supports |PACE|, -the PIN pad is used. If none of these options is applies, npa-tool will show a +the PIN pad is used. If none of these options applies, |npa-tool| will show a password prompt. |npa-tool| can send arbitrary APDUs to the nPA in the secure channel. APDUs @@ -138,8 +145,5 @@ Alternatively you can specify libraries and flags by hand:: -I$PREFIX/include \ -L$PREFIX/lib -lnpa -lopensc -lcrypto" -The API to libnpa is documented in :ref:`npa-api`. It includes a simple -programming example. - .. include:: questions.rst diff --git a/npa/doc/README.rst.in b/npa/doc/README.rst.in index ce4bae9..eb4a024 100644 --- a/npa/doc/README.rst.in +++ b/npa/doc/README.rst.in @@ -35,6 +35,9 @@ transparent SM usage in OpenSC. This allows @PACKAGE_NAME@ to be fully compatible with OpenSC. +.. include:: download.rst + + .. _npa-install: .. include:: autotools.rst @@ -78,8 +81,8 @@ of OpenSC_:: git clone git://vsmartcard.git.sourceforge.net/gitroot/vsmartcard $VSMARTCARD cd $VSMARTCARD/npa/src/opensc autoreconf --verbose --install - # adding PKG_CONFIG_PATH here lets OpenSC use OpenSSL with OpenPACE - ./configure --prefix=$PREFIX PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig + # adding PKG_CONFIG_PATH here lets OpenSC use the patched OpenSSL + ./configure --prefix=$PREFIX PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig --enable-sm make install && cd - Now :file:`libopensc.so` should be located in ``$PREFIX/lib``. @@ -93,8 +96,7 @@ To complete this step-by-step guide, here is how to install @PACKAGE_NAME@:: cd $VSMARTCARD/npa autoreconf --verbose --install - # adding PKG_CONFIG_PATH here lets OpenSC use OpenSSL with OpenPACE - ./configure --prefix=$PREFIX PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig OPENSC_LIBS="-L$PREFIX/lib -lopensc" + ./configure --prefix=$PREFIX PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig OPENSC_LIBS="-L$PREFIX/lib -lopensc -lcrypto" make install && cd - @@ -105,9 +107,13 @@ To complete this step-by-step guide, here is how to install @PACKAGE_NAME@:: Usage ===== +The API to libnpa is documented in :ref:`npa-api`. It includes a simple +programming example. Here we will focus on the command line interface to the +library offered by the |npa-tool|. + To pass a secret to |npa-tool| for |PACE|, command line parameters or environment variables can be used. If the smart card reader supports |PACE|, -the PIN pad is used. If none of these options is applies, npa-tool will show a +the PIN pad is used. If none of these options apply, |npa-tool| will show a password prompt. |npa-tool| can send arbitrary APDUs to the nPA in the secure channel. APDUs @@ -138,8 +144,5 @@ Alternatively you can specify libraries and flags by hand:: -I$PREFIX/include \ -L$PREFIX/lib -lnpa -lopensc -lcrypto" -The API to libnpa is documented in :ref:`npa-api`. It includes a simple -programming example. - .. include:: questions.rst diff --git a/npa/doc/download.rst b/npa/doc/download.rst new file mode 100644 index 0000000..6bb6b21 --- /dev/null +++ b/npa/doc/download.rst @@ -0,0 +1,12 @@ +.. highlight:: sh + +=============================================================================== +Download +=============================================================================== + +You can find the latest release of nPA Smart Card Library `here +`_. + +Alternatively, you can clone our git repository:: + + git clone git://vsmartcard.git.sourceforge.net/gitroot/vsmartcard/vsmartcard diff --git a/npa/doc/download.rst.in b/npa/doc/download.rst.in new file mode 120000 index 0000000..30d6cb5 --- /dev/null +++ b/npa/doc/download.rst.in @@ -0,0 +1 @@ +../../doc/download.rst.in \ No newline at end of file diff --git a/npa/src/Makefile.am b/npa/src/Makefile.am index 2626aea..c2c4b67 100644 --- a/npa/src/Makefile.am +++ b/npa/src/Makefile.am @@ -37,7 +37,7 @@ npa-tool.ggo: npa-tool.ggo.in $(do_subst) < $< > $(srcdir)/$@ -npa-tool.1: +npa-tool.1: npa-tool.ggo $(HELP2MAN) \ --output=$@ \ --no-info \ diff --git a/npa/src/npa-tool.ggo.in b/npa/src/npa-tool.ggo.in index 4cbaa5d..34195a4 100644 --- a/npa/src/npa-tool.ggo.in +++ b/npa/src/npa-tool.ggo.in @@ -13,11 +13,8 @@ option "verbose" v "Use (several times) to be more verbose" multiple optional -option "env" - - "Whether to use environment variables PIN, PUK, CAN, MRZ and NEWPIN. You may want to clean your environment before enabling this." - flag off -section "Secrets for establishing the secure PACE channel to the card" +section "Password Authenticated Connection Establishment (PACE)" option "pin" p "Run PACE with (transport) eID-PIN" string @@ -38,34 +35,9 @@ option "mrz" m string argoptional optional - -section "Terminal Authentication" -option "cv-certificate" C - "Card Verifiable Certificate to create a certificate chain. Can be used multiple times (order is important)." - string - typestr="FILENAME" - optional - multiple -option "cert-desc" - - "Certificate description to use for Terminal Authentication" - string - typestr="HEX_STRING" - optional -option "chat" - - "Card holder authorization template to use (default is terminal's CHAT). Use 7F:4C:0e:06:09:04:00:7F:00:07:03:01:02:03:53:01:03 to trigger EAC on the CAT-C (Komfortleser)." - string - typestr="HEX_STRING" - optional -option "auxiliary-data" A - "Terminal's auxiliary data (default is determined by age verification and community id verification)." - string - typestr="HEX_STRING" - optional -option "private-key" P - "Terminal's private key." - string - typestr="FILENAME" - optional +option "env" - + "Whether to use environment variables PIN, PUK, CAN, MRZ and NEWPIN. You may want to clean your environment before enabling this." + flag off section "PIN management" option "new-pin" N @@ -79,7 +51,41 @@ option "unblock" U "Unblock PIN (uses PUK to activate three more retries)" flag off -section "Read and Write Data Groups" +section "Terminal Authentication (TA) and Chip Authentication (CA)" +option "cv-certificate" C + "Card Verifiable Certificate to create a certificate chain. Can be used multiple times (order is important)." + string + typestr="FILENAME" + optional + multiple +option "cert-desc" - + "Certificate description to show for Terminal Authentication" + string + typestr="HEX_STRING" + optional +option "chat" - + "Card holder authorization template to use (default is terminal's CHAT). Use 7F4C0E060904007F000703010203530103 to trigger EAC on the CAT-C (Komfortleser)." + string + typestr="HEX_STRING" + optional +option "auxiliary-data" A + "Terminal's auxiliary data (default is determined by age verification and community id verification)." + string + typestr="HEX_STRING" + optional +option "private-key" P + "Terminal's private key." + string + typestr="FILENAME" + optional +option "disable-ta-checks" - + "Disable checking the validity period of CV certifcates" + flag off +option "disable-ca-checks" - + "Disable passive authentication" + flag off + +section "Read and write data groups" option "read-dg1" - "Read DG 1 (Document Type)" flag off @@ -169,15 +175,15 @@ option "write-dg21" - typestr="HEX_STRING" optional -section "nPA operations" +section "Verification of validity, age and community ID" +option "verify-validity" - + "Verify the chip's validity" + flag off option "older-than" - "Verify age with a reference date" string typestr="YYYYMMDD" optional -option "verify-validity" - - "Verify document validity with the chips current date" - flag off option "verify-community" - "Verify community ID with a reference ID" string @@ -185,10 +191,10 @@ option "verify-community" - section "Special options, not always useful" option "break" b - "Brute force PIN, CAN or PUK" + "Brute force PIN, CAN or PUK. Use together with -p, -a or -u" flag off option "translate" t - "File with APDUs to send through the secure channel" + "File with APDUs of HEX_STRINGs to send through the secure channel" string typestr="FILENAME" default="stdin" @@ -199,12 +205,6 @@ option "tr-03110v201" - option "disable-all-checks" - "Disable all checking of fly-by-data" flag off -option "disable-ta-checks" - - "Disable checking the validity period of CV certifcates" - flag off -option "disable-ca-checks" - - "Disable passive authentication" - flag off text " Report bugs to @PACKAGE_BUGREPORT@ diff --git a/npa/src/npa.c b/npa/src/npa.c index 6aeb8f9..08ecfa8 100644 --- a/npa/src/npa.c +++ b/npa/src/npa.c @@ -236,17 +236,17 @@ IMPLEMENT_ASN1_FUNCTIONS(NPA_GEN_AUTH_CA_R) #define maxresp SC_MAX_APDU_BUFFER_SIZE - 2 -/** NPA secure messaging context */ +/** @brief NPA secure messaging context */ struct npa_sm_ctx { - /** EAC context */ + /** @brief EAC context */ EAC_CTX *ctx; - /** Certificate Description given on initialization of PACE */ + /** @brief Certificate Description given on initialization of PACE */ BUF_MEM *certificate_description; - /** picc's compressed ephemeral public key of PACE */ + /** @brief picc's compressed ephemeral public key of PACE */ BUF_MEM *id_icc; - /** PCD's compressed ephemeral public key of CA */ + /** @brief PCD's compressed ephemeral public key of CA */ BUF_MEM *eph_pub_key; - /** Auxiliary Data */ + /** @brief Auxiliary Data */ BUF_MEM *auxiliary_data; char flags; }; diff --git a/npa/src/npa/iso-sm.h b/npa/src/npa/iso-sm.h index b72c3f7..c495315 100644 --- a/npa/src/npa/iso-sm.h +++ b/npa/src/npa/iso-sm.h @@ -30,47 +30,47 @@ extern "C" { #endif -/** Padding indicator: use ISO/IEC 9797-1 padding method 2 */ +/** @brief Padding indicator: use ISO/IEC 9797-1 padding method 2 */ #define SM_ISO_PADDING 0x01 -/** Padding indicator: use no padding */ +/** @brief Padding indicator: use no padding */ #define SM_NO_PADDING 0x02 -/** Secure messaging context */ +/** @brief Secure messaging context */ struct iso_sm_ctx { - /** data of the specific crypto implementation */ + /** @brief data of the specific crypto implementation */ void *priv_data; - /** Padding-content indicator byte (ISO 7816-4 Table 30) */ + /** @brief Padding-content indicator byte (ISO 7816-4 Table 30) */ u8 padding_indicator; - /** Pad to this block length */ + /** @brief Pad to this block length */ size_t block_length; - /** Call back function for authentication of data */ + /** @brief Call back function for authentication of data */ int (*authenticate)(sc_card_t *card, const struct iso_sm_ctx *ctx, const u8 *data, size_t datalen, u8 **outdata); - /** Call back function for verifying authentication data */ + /** @brief Call back function for verifying authentication data */ int (*verify_authentication)(sc_card_t *card, const struct iso_sm_ctx *ctx, const u8 *mac, size_t maclen, const u8 *macdata, size_t macdatalen); - /** Call back function for encryption of data */ + /** @brief Call back function for encryption of data */ int (*encrypt)(sc_card_t *card, const struct iso_sm_ctx *ctx, const u8 *data, size_t datalen, u8 **enc); - /** Call back function for decryption of data */ + /** @brief Call back function for decryption of data */ int (*decrypt)(sc_card_t *card, const struct iso_sm_ctx *ctx, const u8 *enc, size_t enclen, u8 **data); - /** Call back function for actions before encoding and encryption of \a apdu */ + /** @brief Call back function for actions before encoding and encryption of \a apdu */ int (*pre_transmit)(sc_card_t *card, const struct iso_sm_ctx *ctx, sc_apdu_t *apdu); - /** Call back function for actions before decryption and decoding of \a sm_apdu */ + /** @brief Call back function for actions before decryption and decoding of \a sm_apdu */ int (*post_transmit)(sc_card_t *card, const struct iso_sm_ctx *ctx, sc_apdu_t *sm_apdu); - /** Call back function for actions after decrypting SM protected APDU */ + /** @brief Call back function for actions after decrypting SM protected APDU */ int (*finish)(sc_card_t *card, const struct iso_sm_ctx *ctx, sc_apdu_t *apdu); - /** Clears and frees private data */ + /** @brief Clears and frees private data */ void (*clear_free)(const struct iso_sm_ctx *ctx); }; @@ -107,6 +107,9 @@ int iso_sm_start(struct sc_card *card, struct iso_sm_ctx *sctx); /** * @brief Stops SM and frees allocated ressources. * + * Calls \a card->sm_ctx.ops.close() if available and \c card->sm_ctx.sm_mode + * is \c SM_MODE_TRANSMIT + * * @param[in] card * * @return \c SC_SUCCESS or error code if an error occurred diff --git a/npa/src/npa/npa.h b/npa/src/npa/npa.h index eccda80..00d736e 100644 --- a/npa/src/npa/npa.h +++ b/npa/src/npa/npa.h @@ -37,64 +37,64 @@ extern "C" { #endif -/** NPA capabilities (TR-03119): PACE */ +/** @brief NPA capabilities (TR-03119): PACE */ #define NPA_BITMAP_PACE 0x40 -/** NPA capabilities (TR-03119): EPA: eID */ +/** @brief NPA capabilities (TR-03119): EPA: eID */ #define NPA_BITMAP_EID 0x20 -/** NPA capabilities (TR-03119): EPA: eSign */ +/** @brief NPA capabilities (TR-03119): EPA: eSign */ #define NPA_BITMAP_ESIGN 0x10 -/** NPA result (TR-03119): Kein Fehler */ +/** @brief NPA result (TR-03119): Kein Fehler */ #define NPA_SUCCESS 0x00000000 -/** NPA result (TR-03119): Längen im Input sind inkonsistent */ +/** @brief NPA result (TR-03119): Längen im Input sind inkonsistent */ #define NPA_ERROR_LENGTH_INCONSISTENT 0xD0000001 -/** NPA result (TR-03119): Unerwartete Daten im Input */ +/** @brief NPA result (TR-03119): Unerwartete Daten im Input */ #define NPA_ERROR_UNEXPECTED_DATA 0xD0000002 -/** NPA result (TR-03119): Unerwartete Kombination von Daten im Input */ +/** @brief NPA result (TR-03119): Unerwartete Kombination von Daten im Input */ #define NPA_ERROR_UNEXPECTED_DATA_COMBINATION 0xD0000003 -/** NPA result (TR-03119): Die Karte unterstützt das PACE – Verfahren nicht. (Unerwartete Struktur in Antwortdaten der Karte) */ +/** @brief NPA result (TR-03119): Die Karte unterstützt das PACE – Verfahren nicht. (Unerwartete Struktur in Antwortdaten der Karte) */ #define NPA_ERROR_CARD_NOT_SUPPORTED 0xE0000001 -/** NPA result (TR-03119): Der Kartenleser unterstützt den angeforderten bzw. den ermittelten Algorithmus nicht. */ +/** @brief NPA result (TR-03119): Der Kartenleser unterstützt den angeforderten bzw. den ermittelten Algorithmus nicht. */ #define NPA_ERROR_ALGORITH_NOT_SUPPORTED 0xE0000002 -/** NPA result (TR-03119): Der Kartenleser kennt die PIN – ID nicht. */ +/** @brief NPA result (TR-03119): Der Kartenleser kennt die PIN – ID nicht. */ #define NPA_ERROR_PINID_NOT_SUPPORTED 0xE0000003 -/** NPA result (TR-03119): Negative Antwort der Karte auf Select EF_CardAccess (needs to be OR-ed with SW1|SW2) */ +/** @brief NPA result (TR-03119): Negative Antwort der Karte auf Select EF_CardAccess (needs to be OR-ed with SW1|SW2) */ #define NPA_ERROR_SELECT_EF_CARDACCESS 0xF0000000 -/** NPA result (TR-03119): Negative Antwort der Karte auf Read Binary (needs to be OR-ed with SW1|SW2) */ +/** @brief NPA result (TR-03119): Negative Antwort der Karte auf Read Binary (needs to be OR-ed with SW1|SW2) */ #define NPA_ERROR_READ_BINARY 0xF0010000 -/** NPA result (TR-03119): Negative Antwort der Karte auf MSE: Set AT (needs to be OR-ed with SW1|SW2) */ +/** @brief NPA result (TR-03119): Negative Antwort der Karte auf MSE: Set AT (needs to be OR-ed with SW1|SW2) */ #define NPA_ERROR_MSE_SET_AT 0xF0020000 -/** NPA result (TR-03119): Negative Antwort der Karte auf General Authenticate Step 1 (needs to be OR-ed with SW1|SW2) */ +/** @brief NPA result (TR-03119): Negative Antwort der Karte auf General Authenticate Step 1 (needs to be OR-ed with SW1|SW2) */ #define NPA_ERROR_GENERAL_AUTHENTICATE_1 0xF0030000 -/** NPA result (TR-03119): Negative Antwort der Karte auf General Authenticate Step 2 (needs to be OR-ed with SW1|SW2) */ +/** @brief NPA result (TR-03119): Negative Antwort der Karte auf General Authenticate Step 2 (needs to be OR-ed with SW1|SW2) */ #define NPA_ERROR_GENERAL_AUTHENTICATE_2 0xF0040000 -/** NPA result (TR-03119): Negative Antwort der Karte auf General Authenticate Step 3 (needs to be OR-ed with SW1|SW2) */ +/** @brief NPA result (TR-03119): Negative Antwort der Karte auf General Authenticate Step 3 (needs to be OR-ed with SW1|SW2) */ #define NPA_ERROR_GENERAL_AUTHENTICATE_3 0xF0050000 -/** NPA result (TR-03119): Negative Antwort der Karte auf General Authenticate Step 4 (needs to be OR-ed with SW1|SW2) */ +/** @brief NPA result (TR-03119): Negative Antwort der Karte auf General Authenticate Step 4 (needs to be OR-ed with SW1|SW2) */ #define NPA_ERROR_GENERAL_AUTHENTICATE_4 0xF0060000 -/** NPA result (TR-03119): Kommunikationsabbruch mit Karte. */ +/** @brief NPA result (TR-03119): Kommunikationsabbruch mit Karte. */ #define NPA_ERROR_COMMUNICATION 0xF0100001 -/** NPA result (TR-03119): Keine Karte im Feld. */ +/** @brief NPA result (TR-03119): Keine Karte im Feld. */ #define NPA_ERROR_NO_CARD 0xF0100002 -/** NPA result (TR-03119): Benutzerabbruch. */ +/** @brief NPA result (TR-03119): Benutzerabbruch. */ #define NPA_ERROR_ABORTED 0xF0200001 -/** NPA result (TR-03119): Benutzer – Timeout */ +/** @brief NPA result (TR-03119): Benutzer – Timeout */ #define NPA_ERROR_TIMEOUT 0xF0200002 -/** File identifier of EF.CardAccess */ +/** @brief File identifier of EF.CardAccess */ #define FID_EF_CARDACCESS 0x011C -/** Short file identifier of EF.CardAccess */ +/** @brief Short file identifier of EF.CardAccess */ #define SFID_EF_CARDACCESS 0x1C -/** File identifier of EF.CardSecurity */ +/** @brief File identifier of EF.CardSecurity */ #define FID_EF_CARDSECURITY 0x011D -/** Short file identifier of EF.CardAccess */ +/** @brief Short file identifier of EF.CardAccess */ #define SFID_EF_CARDSECURITY 0x1D -/** Maximum length of PIN */ +/** @brief Maximum length of PIN */ #define MAX_PIN_LEN 6 -/** Minimum length of PIN */ +/** @brief Minimum length of PIN */ #define MIN_PIN_LEN 6 -/** Minimum length of MRZ */ +/** @brief Minimum length of MRZ */ #define MAX_MRZ_LEN 128 /** @@ -204,7 +204,8 @@ int npa_reset_retry_counter(sc_card_t *card, */ #define npa_unblock_pin(card) \ npa_reset_retry_counter(card, PACE_PIN, 0, NULL, 0) -/** Send APDU to set a new PIN +/** + * @brief Send APDU to set a new PIN * * @param[in] card * @param[in] newp (optional) new PIN @@ -215,15 +216,15 @@ int npa_reset_retry_counter(sc_card_t *card, /** @brief Disable all sanity checks done by libnpa */ #define NPA_FLAG_DISABLE_CHECK_ALL 1 -/** Disable checking validity period of CV certificates */ +/** @brief Disable checking validity period of CV certificates */ #define NPA_FLAG_DISABLE_CHECK_TA 2 -/** Disable checking passive authentication during CA */ +/** @brief Disable checking passive authentication during CA */ #define NPA_FLAG_DISABLE_CHECK_CA 4 -/** Use \c npa_default_flags to disable checks for EAC/SM */ +/** @brief Use \c npa_default_flags to disable checks for EAC/SM */ extern char npa_default_flags; -/** ASN.1 type for authenticated auxiliary data for terminal authentication */ +/** @brief ASN.1 type for authenticated auxiliary data for terminal authentication */ typedef CVC_DISCRETIONARY_DATA_TEMPLATES ASN1_AUXILIARY_DATA; DECLARE_ASN1_FUNCTIONS(ASN1_AUXILIARY_DATA) diff --git a/npa/src/npa/scutil.h b/npa/src/npa/scutil.h index 3f5d592..40539e3 100644 --- a/npa/src/npa/scutil.h +++ b/npa/src/npa/scutil.h @@ -89,7 +89,8 @@ void _bin_log(sc_context_t *ctx, int type, const char *file, int line, */ int print_avail(int verbose); -/** Recursively read an EF by short file identifier. +/** + * @brief Recursively read an EF by short file identifier. * * @param[in] card * @param[in] sfid Short file identifier @@ -103,7 +104,8 @@ int print_avail(int verbose); int read_binary_rec(sc_card_t *card, unsigned char sfid, u8 **ef, size_t *ef_len); -/** Recursively write an EF by short file identifier. +/** + * @brief Recursively write an EF by short file identifier. * * @param[in] card * @param[in] sfid Short file identifier diff --git a/pcsc-relay/doc/Makefile.am b/pcsc-relay/doc/Makefile.am index 8d88b88..98dd4ef 100644 --- a/pcsc-relay/doc/Makefile.am +++ b/pcsc-relay/doc/Makefile.am @@ -16,11 +16,12 @@ do_subst = $(SED) \ -e 's,[@]abs_top_srcdir[@],$(abs_top_srcdir),g' \ -e 's,[@]top_srcdir[@],$(top_srcdir),g' -EXTRA_DIST = README.rst.in README.rst autotools.rst.in questions.rst.in autotools.rst questions.rst +EXTRA_DIST = README.rst.in README.rst autotools.rst.in questions.rst.in autotools.rst questions.rst download.rst.in download.rst doc: *.in $(do_subst) < autotools.rst.in > autotools.rst $(do_subst) < questions.rst.in > questions.rst + $(do_subst) < download.rst.in > download.rst $(do_subst) < README.rst.in > README.rst touch doc diff --git a/pcsc-relay/doc/README.rst b/pcsc-relay/doc/README.rst index 144b4e2..a16f080 100644 --- a/pcsc-relay/doc/README.rst +++ b/pcsc-relay/doc/README.rst @@ -41,6 +41,9 @@ emulate an ISO/IEC 14443 smart card. but it generally concerns *all* contact-less smart cards. +.. include:: download.rst + + .. include:: autotools.rst PC/SC Relay has the following dependencies: diff --git a/pcsc-relay/doc/README.rst.in b/pcsc-relay/doc/README.rst.in index 5919596..2624c50 100644 --- a/pcsc-relay/doc/README.rst.in +++ b/pcsc-relay/doc/README.rst.in @@ -41,6 +41,9 @@ emulate an ISO/IEC 14443 smart card. but it generally concerns *all* contact-less smart cards. +.. include:: download.rst + + .. include:: autotools.rst @PACKAGE_NAME@ has the following dependencies: diff --git a/pcsc-relay/doc/download.rst b/pcsc-relay/doc/download.rst new file mode 100644 index 0000000..54f3d35 --- /dev/null +++ b/pcsc-relay/doc/download.rst @@ -0,0 +1,12 @@ +.. highlight:: sh + +=============================================================================== +Download +=============================================================================== + +You can find the latest release of PC/SC Relay `here +`_. + +Alternatively, you can clone our git repository:: + + git clone git://vsmartcard.git.sourceforge.net/gitroot/vsmartcard/vsmartcard diff --git a/virtualsmartcard/doc/Makefile.am b/virtualsmartcard/doc/Makefile.am index a96b626..0df25e7 100644 --- a/virtualsmartcard/doc/Makefile.am +++ b/virtualsmartcard/doc/Makefile.am @@ -17,13 +17,14 @@ do_subst = $(SED) \ -e 's,[@]abs_top_srcdir[@],$(abs_top_srcdir),g' \ -e 's,[@]top_srcdir[@],$(top_srcdir),g' -EXTRA_DIST = README.rst.in README.rst autotools.rst.in questions.rst.in autotools.rst questions.rst +EXTRA_DIST = README.rst.in README.rst autotools.rst.in questions.rst.in autotools.rst questions.rst download.rst.in download.rst dist_noinst_SCRIPTS = generate_modules.py doc: $(top_srcdir)/src/vpicc/virtualsmartcard/*.py $(top_srcdir)/src/vpicc/virtualsmartcard/cards/*.py generate_modules.py *.in $(do_subst) < autotools.rst.in > autotools.rst $(do_subst) < questions.rst.in > questions.rst + $(do_subst) < download.rst.in > download.rst $(do_subst) < README.rst.in > README.rst ./generate_modules.py $(top_srcdir)/src/vpicc --dest-dir=api --suffix=rst --no-toc -1 -f touch doc diff --git a/virtualsmartcard/doc/README.rst b/virtualsmartcard/doc/README.rst index 5cdda9e..ff24078 100644 --- a/virtualsmartcard/doc/README.rst +++ b/virtualsmartcard/doc/README.rst @@ -13,6 +13,9 @@ .. |vpcd| replace:: :abbr:`vpcd (virtual smart card reader)` .. |EAC| replace:: :abbr:`EAC (Extended Access Control)` .. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)` +.. |TA| replace:: :abbr:`TA (Terminal Authenticatation)` +.. |CA| replace:: :abbr:`CA (Chip Authentication)` +.. |BAC| replace:: :abbr:`BAC (Basic Access Control)` .. _vicc: @@ -35,14 +38,14 @@ Virtual Smart Card emulates a smart card and makes it accessible through PC/SC. Currently the Virtual Smart Card supports the following types of smart cards: - Generic ISO-7816 smart card including secure messaging -- German electronic identity card (nPA) with |EAC| including |PACE| -- German electronic passport (ePass) with basic access control +- German electronic identity card (nPA) with complete support for |EAC| (|PACE|, |TA|, |CA|) +- German electronic passport (ePass) with complete support for |BAC| - Cryptoflex smart card (incomplete) The |vpcd| is a smart card driver for PCSC-Lite_. It allows smart card applications to access the |vpicc| through the PC/SC API. By default |vpicc| communicates with |vpcd| through a socket on localhost port -35963. But the |vpicc| does not need to run on the same machine as the |vpcd|, +``35963``. But the |vpicc| does not need to run on the same machine as the |vpcd|, they can connect over the internet for example. Although the Virtual Smart Card is a software emulator, you can use @@ -52,6 +55,9 @@ reader. The file :file:`utils.py` was taken from Henryk Plötz's cyberflex-shell_. +.. include:: download.rst + + .. include:: autotools.rst Depending on your usage of the |vpicc| you might or might not need diff --git a/virtualsmartcard/doc/README.rst.in b/virtualsmartcard/doc/README.rst.in index dd8df55..5ad3cce 100644 --- a/virtualsmartcard/doc/README.rst.in +++ b/virtualsmartcard/doc/README.rst.in @@ -13,6 +13,9 @@ .. |vpcd| replace:: :abbr:`vpcd (virtual smart card reader)` .. |EAC| replace:: :abbr:`EAC (Extended Access Control)` .. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)` +.. |TA| replace:: :abbr:`TA (Terminal Authenticatation)` +.. |CA| replace:: :abbr:`CA (Chip Authentication)` +.. |BAC| replace:: :abbr:`BAC (Basic Access Control)` .. _vicc: @@ -35,8 +38,8 @@ Currently the @PACKAGE_NAME@ supports the following types of smart cards: - Generic ISO-7816 smart card including secure messaging -- German electronic identity card (nPA) with |EAC| including |PACE| -- German electronic passport (ePass) with basic access control +- German electronic identity card (nPA) with complete support for |EAC| (|PACE|, |TA|, |CA|) +- German electronic passport (ePass) with complete support for |BAC| - Cryptoflex smart card (incomplete) The |vpcd| is a smart card driver for PCSC-Lite_. It allows @@ -52,6 +55,9 @@ reader. The file :file:`utils.py` was taken from Henryk Plötz's cyberflex-shell_. +.. include:: download.rst + + .. include:: autotools.rst Depending on your usage of the |vpicc| you might or might not need diff --git a/virtualsmartcard/doc/download.rst b/virtualsmartcard/doc/download.rst new file mode 100644 index 0000000..d6dd4d4 --- /dev/null +++ b/virtualsmartcard/doc/download.rst @@ -0,0 +1,12 @@ +.. highlight:: sh + +=============================================================================== +Download +=============================================================================== + +You can find the latest release of Virtual Smart Card `here +`_. + +Alternatively, you can clone our git repository:: + + git clone git://vsmartcard.git.sourceforge.net/gitroot/vsmartcard/vsmartcard diff --git a/virtualsmartcard/doc/download.rst.in b/virtualsmartcard/doc/download.rst.in new file mode 120000 index 0000000..30d6cb5 --- /dev/null +++ b/virtualsmartcard/doc/download.rst.in @@ -0,0 +1 @@ +../../doc/download.rst.in \ No newline at end of file diff --git a/virtualsmartcard/src/vpicc/Makefile.am b/virtualsmartcard/src/vpicc/Makefile.am index c0393be..cb351d9 100644 --- a/virtualsmartcard/src/vpicc/Makefile.am +++ b/virtualsmartcard/src/vpicc/Makefile.am @@ -35,7 +35,7 @@ $(builddir)/vicc: vicc.in Makefile $(do_subst) < $(srcdir)/vicc.in > $(builddir)/vicc chmod +x $(builddir)/vicc -$(builddir)/vicc.1: +$(builddir)/vicc.1: vicc.in $(HELP2MAN) \ --no-discard-stderr \ --output=$@ \ diff --git a/virtualsmartcard/src/vpicc/vicc.in b/virtualsmartcard/src/vpicc/vicc.in index 36c5ce3..e3f4ddd 100644 --- a/virtualsmartcard/src/vpicc/vicc.in +++ b/virtualsmartcard/src/vpicc/vicc.in @@ -37,7 +37,7 @@ parser.add_argument("-t", "--type", action="store", choices=['iso7816', 'cryptoflex', 'ePass', 'nPA', 'relay'], default='iso7816', - help="Type of smart card to emulate (default: %(default)s)") + help="type of smart card to emulate (default: %(default)s)") parser.add_argument("-f", "--file", action="store", type=argparse.FileType('r'), @@ -54,32 +54,33 @@ parser.add_argument("-P", "--port", help="port of the vpcd (default: %(default)s)") parser.add_argument('--version', action='version', version='%(prog)s @PACKAGE_VERSION@') -relay = parser.add_argument_group('options for relaying a local smart card') -relay.add_argument("-r", "--reader", +relay = parser.add_argument_group('Relaying a local smart card (`--type=relay`)') +relay.add_argument("--reader", action="store", type=int, - help="number of the reader which contains the smart card to be relayed.") + default=0, + help="number of the reader containing the card to be relayed (default: %(default)s)") -npa = parser.add_argument_group('options for nPA emulation') -npa.add_argument("-s", "--ef-cardsecurity", +npa = parser.add_argument_group('Emulation of German identity card (`--type=nPA`)') +npa.add_argument("--ef-cardaccess", action="store", type=argparse.FileType('rb'), - help="EF.CardSecurity with the signed CA public key.") -npa.add_argument("-a", "--ef-cardaccess", + help="the card's EF.CardAccess (default: use file from first generation nPA)") +npa.add_argument("--ef-cardsecurity", action="store", type=argparse.FileType('rb'), - help="EF.CardAccess with the EAC configuration.") -npa.add_argument("-k", "--ca-key", + help="the card's EF.CardSecurity (default: use file from first generation nPA)") +npa.add_argument("--cvca", action="store", type=argparse.FileType('rb'), - help="CA private key.") -npa.add_argument("-C", "--cvca", - action="store", - type=argparse.FileType('rb'), - help="CVCA certificate") -npa.add_argument("-d", "--disable-checks", + help="trust anchor for verifying certificates in TA (default: use libeac's trusted certificates)") +npa.add_argument("--disable-ta-checks", action="store_true", default=False, - help="Disables checking validity period of TA certificates") + help="disable checking the validity period of CV certifcates (default: %(default)s)") +npa.add_argument("--ca-key", + action="store", + type=argparse.FileType('rb'), + help="the chip's private key for CA (default: randomly generated, invalidates signature of EF.CardSecurity)") args = parser.parse_args() @@ -106,5 +107,5 @@ if (args.cvca): vicc = VirtualICC(args.file, args.type, args.hostname, args.port, readernum=args.reader, ef_cardaccess=ef_cardaccess_data, ef_cardsecurity=ef_cardsecurity_data, - ca_key=ca_key_data, cvca=cvca, disable_checks=args.disable_checks) + ca_key=ca_key_data, cvca=cvca, disable_checks=args.disable_ta_checks) vicc.run()