.. highlight:: c

.. _npa-api:

********************************
Programming with the nPA Library
********************************

The nPA library includes a generic implementation for Secure Messaging (SM),
which might also be used in conjunction with other cards. It is implemented to
be close to ISO 7816 focusing only on encoding rather than implementing
everything that is needed to get a secure channel. All cryptographic work is
done by call back functions, which should be appropriatly set for the specific
card.

Using the German identity card (neuer Personalausweis, nPA) requires user
authentication via entry of the PIN. Transmitting the PIN in plaintext is
risky, since it would be transmitted over the air and could be snooped. That's
why the PACE keyagreement is used to verify the PIN and establish an SM channel
to the nPA. :npa:`perform_pace` does exactly that and if everything went fine,
it initializes the card for use of the SM channel. Now `sc_transmit_apdu` or
any other OpenSC command can be used to securely transmit arbitrary APDUs to
the card. Next in the Extended Access Control (EAC) are the Terminal
Authentication (:npa:`perform_terminal_authentication`) and Chip Authentication
(:npa:`perform_chip_authentication`). When the EAC was successfull, the card
will be initialized for the new SM channel. Again, libopensc can directly be
used to read identity attributes, for example.

.. note::
    Please consider the following overview to the API as incomplete. The
    `Doxygen documentation <../_static/doxygen-npa/modules.html>`_ should be
    used as programmer's.


==============================================================
Interface to German identity card (neuer Personalausweis, nPA)
==============================================================

.. seealso::
    `Doxygen documentation of the nPA module
    <../_static/doxygen-npa/group__npa.html>`__.

---------
Functions
---------
.. doxygenfunction:: perform_pace
.. doxygenfunction:: perform_terminal_authentication
.. doxygenfunction:: perform_chip_authentication
.. doxygenfunction:: npa_reset_retry_counter

-------
Defines
-------
.. doxygendefine:: npa_change_pin
.. doxygendefine:: npa_unblock_pin


=======
Example
=======

In order to compile and execute this example you need to correctly :ref:`set up
your environment <npa-usage>`.

.. literalinclude:: example.c
    :lines: 20-


======================================
Generic ISO 7816 Secure Messaging (SM)
======================================

.. seealso::
    `Doxygen documentation of the SM module
    <../_static/doxygen-npa/group__sm.html>`__.

-----
Types
-----
.. doxygenstruct:: iso_sm_ctx

---------
Functions
---------
.. doxygenfunction:: iso_sm_ctx_create
.. doxygenfunction:: iso_sm_ctx_clear_free
.. doxygenfunction:: iso_sm_start
.. doxygenfunction:: sm_stop