VivoKey/vsmartcard
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

working on documentation

Browse Source
This commit is contained in:
Frank Morgner
2013-05-13 08:15:05 +02:00
parent ae8c086606
commit 54579ae7d7
25 changed files with 305 additions and 246 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
npa/doc/README.txt
View File

@@ -1,17 +1,20 @@
.. highlight:: sh
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
.. |TA| replace:: :abbr:`TA (Terminal Authenticatation)`
.. |CA| replace:: :abbr:`CA (Chip Authentication)`
.. |EAC| replace:: :abbr:`EAC (Extended Access Control)`
.. |CSCA| replace:: :abbr:`CSCA (Country Signing Certificate Authority)`
.. |npa-tool| replace:: :command:`npa-tool`
.. _libnpa:
.. _npa:
######################
################################################################################
nPA Smart Card Library
######################
################################################################################
:Author:
Frank Morgner <morgner@informatik.hu-berlin.de>
`Frank Morgner <morgner@informatik.hu-berlin.de>`_
:License:
GPL version 3
:Tested Platforms:
@@ -40,17 +43,17 @@ compatible with OpenSC.
The nPA Smart Card Library has the following dependencies:
- OpenSSL_
- OpenPACE_
- OpenSC_
- OpenSSL_
====================================
Installation of OpenPACE and OpenSSL
====================================
The nPA Smart Card Library links against OpenSSL_, which must be patched for OpenPACE_.
Here is an example of how to get the standard installation of OpenPACE_ (with
The nPA Smart Card Library links against OpenSSL, which must be patched for OpenPACE.
Here is an example of how to get the standard installation of OpenPACE (with
the required binaries for OpenSSL)::
PREFIX=/tmp/install
@@ -69,7 +72,7 @@ The file :file:`libcrypto.pc` should be located in ``$INSTALL/lib/pkgconfig``.
Installation of OpenSC
======================
The nPA Smart Card Library need the OpenSC components to be installed (especially
The nPA Smart Card Library needs the OpenSC components to be installed (especially
:file:`libopensc.so`). Here is an example of how to get a suitable installation
of OpenSC::
@@ -84,9 +87,9 @@ of OpenSC::
Now :file:`libopensc.so` should be located in ``$PREFIX/lib``.
==========================================
================================================================================
Installation of the nPA Smart Card Library
==========================================
================================================================================
To complete this step-by-step guide, here is how to install nPA Smart Card Library::
@@ -105,17 +108,24 @@ 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|.
library offered by the |npa-tool|. It can perform |EAC| (i.e. |PACE|, |TA|,
|CA|) and read data groups from the identity card.
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 apply, |npa-tool| will show a
its 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
are entered interactively or through a file. APDUs are formatted in hex (upper
or lower case) with an optional colon to separate the bytes. Example APDUs can
be found in :file:`apdus`.
The certificates certificate chain for |TA| should be passed in the correct
order (finishing with the terminal certificate) so that the card can verify it.
|CA| is always done when the terminal's signature has been verified
successfully. The appropriate |CSCA| certificate will automatically be looked
up by OpenPACE.
|npa-tool| can send arbitrary APDUs to the nPA in the secure channel (after
|PACE| or |EAC|). APDUs are entered interactively or through a file. APDUs
are formatted in hex (upper or lower case) with an optional colon to separate
the bytes. Example APDUs can be found in :file:`apdus`.
.. program-output:: npa-tool --help
@@ -150,6 +160,6 @@ Notes and References
.. target-notes::
.. _OpenPACE: http://openpace.sourceforge.net
.. _OpenSC: https://github.com/OpenSC/OpenSC
.. _OpenSSL: http://www.openssl.org
.. _OpenPACE: http://openpace.sourceforge.net

64
npa/doc/README.txt.in
View File

@@ -1,17 +1,20 @@
.. highlight:: sh
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
.. |TA| replace:: :abbr:`TA (Terminal Authenticatation)`
.. |CA| replace:: :abbr:`CA (Chip Authentication)`
.. |EAC| replace:: :abbr:`EAC (Extended Access Control)`
.. |CSCA| replace:: :abbr:`CSCA (Country Signing Certificate Authority)`
.. |npa-tool| replace:: :command:`npa-tool`
.. _libnpa:
.. _npa:
######################
nPA Smart Card Library
######################
################################################################################
@PACKAGE_NAME@
################################################################################
:Author:
Frank Morgner <morgner@informatik.hu-berlin.de>
`Frank Morgner <morgner@informatik.hu-berlin.de>`_
:License:
GPL version 3
:Tested Platforms:
@@ -20,14 +23,14 @@ nPA Smart Card Library
:Potential Platforms:
Unix-like operating systems (Mac OS, Solaris, BSD, ...)
The nPA Smart Card Library offers an easy to use API for the new German identity card
The @PACKAGE_NAME@ offers an easy to use API for the new German identity card
(neuer Personalausweis, nPA). The library also implements secure messaging,
which could also be used for other cards. The included |npa-tool| can
be used for PIN management or to send APDUs inside a secure channel.
The nPA Smart Card Library is implemented using OpenPACE_ and OpenSC_. nPA Smart Card Library
The @PACKAGE_NAME@ is implemented using OpenPACE_ and OpenSC_. @PACKAGE_NAME@
implements and initializes Secure Messaging wrappers of OpenSC to allow a
transparent SM usage in OpenSC. This allows nPA Smart Card Library to be fully
transparent SM usage in OpenSC. This allows @PACKAGE_NAME@ to be fully
compatible with OpenSC.
@@ -38,19 +41,19 @@ compatible with OpenSC.
.. include:: autotools.txt
The nPA Smart Card Library has the following dependencies:
The @PACKAGE_NAME@ has the following dependencies:
- OpenSSL_
- OpenPACE_
- OpenSC_
- OpenSSL_
====================================
Installation of OpenPACE and OpenSSL
====================================
The nPA Smart Card Library links against OpenSSL_, which must be patched for OpenPACE_.
Here is an example of how to get the standard installation of OpenPACE_ (with
The @PACKAGE_NAME@ links against OpenSSL, which must be patched for OpenPACE.
Here is an example of how to get the standard installation of OpenPACE (with
the required binaries for OpenSSL)::
PREFIX=/tmp/install
@@ -69,7 +72,7 @@ The file :file:`libcrypto.pc` should be located in ``$INSTALL/lib/pkgconfig``.
Installation of OpenSC
======================
The nPA Smart Card Library need the OpenSC components to be installed (especially
The @PACKAGE_NAME@ needs the OpenSC components to be installed (especially
:file:`libopensc.so`). Here is an example of how to get a suitable installation
of OpenSC::
@@ -84,11 +87,11 @@ of OpenSC::
Now :file:`libopensc.so` should be located in ``$PREFIX/lib``.
==========================================
Installation of the nPA Smart Card Library
==========================================
================================================================================
Installation of the @PACKAGE_NAME@
================================================================================
To complete this step-by-step guide, here is how to install nPA Smart Card Library::
To complete this step-by-step guide, here is how to install @PACKAGE_NAME@::
cd $VSMARTCARD/npa
autoreconf --verbose --install
@@ -105,17 +108,24 @@ 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|.
library offered by the |npa-tool|. It can perform |EAC| (i.e. |PACE|, |TA|,
|CA|) and read data groups from the identity card.
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 apply, |npa-tool| will show a
its 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
are entered interactively or through a file. APDUs are formatted in hex (upper
or lower case) with an optional colon to separate the bytes. Example APDUs can
be found in :file:`apdus`.
The certificates certificate chain for |TA| should be passed in the correct
order (finishing with the terminal certificate) so that the card can verify it.
|CA| is always done when the terminal's signature has been verified
successfully. The appropriate |CSCA| certificate will automatically be looked
up by OpenPACE.
|npa-tool| can send arbitrary APDUs to the nPA in the secure channel (after
|PACE| or |EAC|). APDUs are entered interactively or through a file. APDUs
are formatted in hex (upper or lower case) with an optional colon to separate
the bytes. Example APDUs can be found in :file:`apdus`.
.. program-output:: npa-tool --help
@@ -124,8 +134,8 @@ Linking against libnpa
----------------------
Following the section Installation_ above, you have installed OpenSSL,
OpenPACE, OpenSC and the nPA Smart Card Library to `$PREFIX` which points to
:file:`/tmp/install`. To compile a program using nPA Smart Card Library you also need
OpenPACE, OpenSC and the @PACKAGE_NAME@ to `$PREFIX` which points to
:file:`/tmp/install`. To compile a program using @PACKAGE_NAME@ you also need
the OpenSC header files, which are located in
:file:`$VSMARTCARD/npa/src/opensc` Here is how to compile an external program
with these libraries::
@@ -150,6 +160,6 @@ Notes and References
.. target-notes::
.. _OpenPACE: http://openpace.sourceforge.net
.. _OpenSC: https://github.com/OpenSC/OpenSC
.. _OpenSSL: http://www.openssl.org
.. _OpenPACE: http://openpace.sourceforge.net

17
npa/doc/api.txt
View File

@@ -26,17 +26,19 @@ Authentication (:npa:`perform_terminal_authentication`) and Chip Authentication
will be initialized for the new SM channel. Again, libopensc can directly be
used to read identity attributes, for example.
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 since it is more detailed.
.. 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)
==============================================================
The complete documentation can be found `here
<../_static/doxygen-npa/group__npa.html>`__.
.. seealso::
`Doxygen documentation of the nPA module
<../_static/doxygen-npa/group__npa.html>`__.
---------
Functions
@@ -68,8 +70,9 @@ your environment <npa-usage>`.
Generic ISO 7816 Secure Messaging (SM)
======================================
The complete documentation can be found `here
<../_static/doxygen-npa/group__sm.html>`__.
.. seealso::
`Doxygen documentation of the SM module
<../_static/doxygen-npa/group__sm.html>`__.
-----
Types

8
npa/doc/autotools.txt
View File

@@ -5,10 +5,10 @@ Installation
************
The nPA Smart Card Library uses the GNU Build System to compile and install. If you are
unfamiliar with it, please have a look at :file:`INSTALL`. If you have a look
around and can not find it, you are probably working bleeding edge in the
repository. Run the following command in :file:`npa` to
get the missing standard auxiliary files::
unfamiliar with it, please have a look at :file:`INSTALL`. If you can not find
it, you are probably working bleeding edge in the repository. Run the
following command in :file:`npa` to get the missing standard
auxiliary files::
autoreconf --verbose --install

2
npa/doc/download.txt
View File

@@ -4,7 +4,7 @@
Download
********
You can find the latest release of nPA Smart Card Library `here
You can find the latest release of nPA Smart Card Library on `Sourceforge
<http://sourceforge.net/projects/vsmartcard/files>`_.
Alternatively, you can clone our git repository::