89 lines
2.8 KiB
Plaintext
89 lines
2.8 KiB
Plaintext
.. 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 reference.
|
|
|
|
|
|
==============================================================
|
|
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
|