updated documentation

2013-02-09 23:44:14 +01:00
parent acabe8be62
commit e1da1dc081
28 changed files with 243 additions and 147 deletions
--- 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

--- 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 <http://msdn.microsoft.com/en-us/windows/hardware/gg487509>`_ 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:
--- a/ccid/doc/download.rst.in
+++ b/ccid/doc/download.rst.in
@@ -0,0 +1 @@
+../../doc/download.rst.in
--- 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
--- a/doc/download.rst.in
+++ b/doc/download.rst.in
@@ -0,0 +1,12 @@
+.. highlight:: sh
+
+===============================================================================
+Download
+===============================================================================
+
+You can find the latest release of @PACKAGE_NAME@ `here
+<http://sourceforge.net/projects/vsmartcard/files>`_.
+
+Alternatively, you can clone our git repository::
+
+    git clone git://vsmartcard.git.sourceforge.net/gitroot/vsmartcard/vsmartcard
--- 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 <https://sourceforge.net/projects/vsmartcard/files/vsmartcard_2011-05-20.tar.gz/download>`_.
+You can download the latest release of the |vsmartcard| `here
+<http://sourceforge.net/projects/vsmartcard/files>`_.

-Alternatively you can check out the source code from our `subversion repository <https://sourceforge.net/projects/vsmartcard/develop>`_. 
+Alternatively, you can clone our git repository::
+
+    git clone git://vsmartcard.git.sourceforge.net/gitroot/vsmartcard/vsmartcard
--- 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

--- 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
--- 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
--- a/npa/doc/download.rst
+++ b/npa/doc/download.rst
@@ -0,0 +1,12 @@
+.. highlight:: sh
+
+===============================================================================
+Download
+===============================================================================
+
+You can find the latest release of nPA Smart Card Library `here
+<http://sourceforge.net/projects/vsmartcard/files>`_.
+
+Alternatively, you can clone our git repository::
+
+    git clone git://vsmartcard.git.sourceforge.net/gitroot/vsmartcard/vsmartcard
--- a/npa/doc/download.rst.in
+++ b/npa/doc/download.rst.in
@@ -0,0 +1 @@
+../../doc/download.rst.in
--- 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 \
--- 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@
--- 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;
 };
--- 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
--- 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)

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

--- 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:
--- 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:
--- a/pcsc-relay/doc/download.rst
+++ b/pcsc-relay/doc/download.rst
@@ -0,0 +1,12 @@
+.. highlight:: sh
+
+===============================================================================
+Download
+===============================================================================
+
+You can find the latest release of PC/SC Relay `here
+<http://sourceforge.net/projects/vsmartcard/files>`_.
+
+Alternatively, you can clone our git repository::
+
+    git clone git://vsmartcard.git.sourceforge.net/gitroot/vsmartcard/vsmartcard
--- 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
--- 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
--- 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
--- a/virtualsmartcard/doc/download.rst
+++ b/virtualsmartcard/doc/download.rst
@@ -0,0 +1,12 @@
+.. highlight:: sh
+
+===============================================================================
+Download
+===============================================================================
+
+You can find the latest release of Virtual Smart Card `here
+<http://sourceforge.net/projects/vsmartcard/files>`_.
+
+Alternatively, you can clone our git repository::
+
+    git clone git://vsmartcard.git.sourceforge.net/gitroot/vsmartcard/vsmartcard
--- a/virtualsmartcard/doc/download.rst.in
+++ b/virtualsmartcard/doc/download.rst.in
@@ -0,0 +1 @@
+../../doc/download.rst.in
--- 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=$@ \
--- 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()