updated documentation

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