From 862d457e94dc735dd67c5d57ab8e95bab9a1724a Mon Sep 17 00:00:00 2001 From: frankmorgner Date: Wed, 26 Oct 2011 09:11:51 +0000 Subject: [PATCH] - surrendered to the incompletenes of breathe. now including only documentation of important stuff by hand. - added example code using npa-tool.c git-svn-id: https://vsmartcard.svn.sourceforge.net/svnroot/vsmartcard@569 96b47cad-a561-4643-ad3b-153ac7d7599c --- doc/npaapi.rst | 56 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 54 insertions(+), 2 deletions(-) diff --git a/doc/npaapi.rst b/doc/npaapi.rst index fc7723d..f6e3015 100644 --- a/doc/npaapi.rst +++ b/doc/npaapi.rst @@ -30,12 +30,64 @@ reference since it is more detailed. Secure Messaging (SM) ===================== -.. doxygenfile:: sm.h +The complete documentation can be found `here +<_static/doxygen-npa/group__sm.html>`_. + +.. doxygenstruct:: sm_ctx +.. doxygenfunction:: sm_transmit_apdu +.. doxygenfunction:: sm_ctx_clear_free ============================================================== Interface to German identity card (neuer Personalausweis, nPA) ============================================================== -.. doxygenfile:: npa.h +The complete documentation can be found `here +<_static/doxygen-npa/group__npa.html>`_. + +.. doxygenstruct:: establish_pace_channel_input +.. doxygenstruct:: establish_pace_channel_output +.. doxygenfunction:: EstablishPACEChannel +.. doxygenfunction:: npa_reset_retry_counter +.. doxygendefine:: npa_change_pin +.. doxygendefine:: npa_unblock_pin + +======= +Example +======= + +The following example are fragments of the npa-tool, which uses libnpa to acces +the nPA with and without SM enabled. First set up the environment: + + .. literalinclude:: ../npa/src/npa-tool.c + :lines: 49-74,198-212 + +Connect to a reader and the nPA: + + .. literalinclude:: ../npa/src/npa-tool.c + :lines: 331-341 + +Now we try to change the PIN. Therefor we need to establish a SM channel with +PACE. You could set your PIN with `pin = "123456"` or just leave it out to be +asked for it. The same applies to the new PIN `newpin`. + + .. literalinclude:: ../npa/src/npa-tool.c + :lines: 484-501 + +Imagine you want to transmit additional APDUs in the established SM channel. +Declare the APDU to something like:: + + const unsigned char buf[] = {0x00, 0xA4, 0x00, 0x0C, 0x02, 0x3F, 0x00}; + size_t apdulen = sizeof buf;` + sc_apdu_t apdu; + +Now parse and transmit the APDU with SM: + + .. literalinclude:: ../npa/src/npa-tool.c + :lines: 171-173,175-183,185 + +Free up memory and wipe it if necessary (e.g. for keys stored in :npa:`sm_ctx`) + + .. literalinclude:: ../npa/src/npa-tool.c + :lines: 563- .. @author Frank Morgner