[87db69]: doc / index.txt  Maximize  Restore  History

Download this file

265 lines (192 with data), 11.3 kB

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
.. 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)`
.. |CVCA| replace:: :abbr:`CSCA (Country Verifying Certificate Authority)`
.. |CSCA| replace:: :abbr:`CSCA (Country Signing Certificate Authority)`
###############################################################################
Welcome to OpenPACE's documentation!
###############################################################################
.. image:: https://travis-ci.org/frankmorgner/openpace.png?branch=master
:target: https://travis-ci.org/frankmorgner/openpace
.. sidebar:: Summary
Cryptographic library for EAC version 2
:Authors:
- `Frank Morgner <morgner@informatik.hu-berlin.de>`_
- `Dominik Oepen <oepen@informatik.hu-berlin.de>`_
:License:
GPL version 3
:Tested Platforms:
- Windows
- Linux (Debian, Ubuntu, SUSE, OpenMoko)
- FreeBSD
- Mac OS
- Solaris
- Android
- Javascript
OpenPACE implements Extended Access Control (EAC) version 2 as specified in
`BSI TR-03110`_. OpenPACE comprises support for the following protocols:
:Password Authenticated Connection Establishment (PACE):
Establish a secure channel with a strong key between two parties that only
share a weak secret.
:Terminal Authentication (TA):
Verify/prove the terminal's certificate (or rather certificate chain) and
secret key.
:Chip Authentication (CA):
Establish a secure channel based on the chip's static key pair proving its
authenticy.
Furthermore, OpenPACE also supports Card Verifiable Certificates (CV
Certificates) as well as easy to use wrappers for using the established secure
channels.
The handlers for looking up trust anchors during |TA| and |CA| (i.e. the |CVCA|
and the |CSCA| certificates) can be customized. By default, the appropriate
certificates will be looked up in the file system.
OpenPACE supports all variants of |PACE| (DH/ECDH, GM/IM), |TA|
(RSASSA-PKCS1-v1_5/RSASSA-PSS/ECDSA), |CA| (DH/ECDH) and all standardized
domain parameters (GFP/ECP).
OpenPACE is implemented as C-library and comes with native language wrappers
for:
- Python
- Ruby
- Javascript
- Java
- Go
.. note::
OpenPACE only implements the cryptographic protocols of the |EAC|. If you
actually want to exchange data with a smart card, you need to take care of
formatting and sending the data in the form of APDUs. If this is what
you're trying to do, you should have a look at the :command:`npa-tool` of
the `nPA Smart Card Library`_.
*******************************************************************************
Download OpenPACE
*******************************************************************************
You can find the latest release of OpenPACE on `Sourceforge
<http://sourceforge.net/projects/openpace/>`_.
Alternatively, you can clone our git repository::
git clone git://git.code.sf.net/p/openpace/git openpace
*******************************************************************************
Install OpenPACE
*******************************************************************************
OpenPACE uses the GNU Build System to compile and install. If you are
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:`openpace` to get the missing standard
auxiliary files::
autoreconf --verbose --install
To configure (:command:`configure --help` lists possible options), build and
install OpenPACE now do the following::
./configure
make
make install
OpenPACE depends on the `OpenSSL`_ library. Since |PACE| uses CMAC and the
Brainpool curves, the currently unreleased version 1.0.2 of OpenSSL is required.
Furthermore, additional object identifiers from `BSI TR-03110`_ are required.
You have two options to get them to work:
1. Let OpenPACE load the object identifiers at runtime
2. Patch OpenSSL to include the identifiers
The first option allows you to install an unchanged version of OpenSSL to your
system. However, performance will be slightly worse and there are some
limitations. For example, you won't be able to use the new NIDs as labels in a
switch statement and you need to make sure to call ``EAC_init()`` first. For
patching OpenSSL we provide :file:`oids.patch`. You can configure
OpenPACE with :option:`--enable-openssl-install`, which will
automatically download, patch, build and install OpenSSL if needed.
===============================================================================
Cross compiling OpenPACE
===============================================================================
We have added some scripts for the ease of cross compiling for Windows and
Android. Both are tested with Debian wheezy. First create a working
:file:`Makefile`::
test -x configure || autoreconf --verbose --install
./configure
Compiling for Windows
-------------------------------------------------------------------------------
Cross compilation for Windows can be done with::
make win
================ ==================== ===========================================================================================
Make Variable Default Meaning
================ ==================== ===========================================================================================
``WIN_TOOL`` ``i686-w64-mingw32`` cross compiler
``WIN_TOOL_DIR`` ``/usr/${WIN_TOOL}`` root directory of the cross compiler containing the :file:`lib` and :file:`include` folders
================ ==================== ===========================================================================================
On successfull compilation, the Windows binaries can be found in
:file:`openpace-0.9_win32`.
Compiling for Android
-------------------------------------------------------------------------------
Cross compilation for Android can be done with::
make android
============================= ============================================================================== =====================================================
Make Variable Default Meaning
============================= ============================================================================== =====================================================
``ANDROID_ARCH`` ``arm`` target Architecture
``ANDROID_TOOL`` ``${ANDROID_ARCH}-linux-androideabi`` cross compiler
``MAKE_STANDALONE_TOOLCHAIN`` ``${HOME}/.local/opt/android-ndk-r9/build/tools/make-standalone-toolchain.sh`` location of the NDK script for creating the toolchain
============================= ============================================================================== =====================================================
On successfull compilation, the Android binaries can be found in
:file:`openpace-0.9_${ANDROID_ARCH}`.
.. _javascript_api:
Compiling for Javascript
-------------------------------------------------------------------------------
Technically the process for getting OpenPACE into Javascript is similar to
cross compiling. With Emscripten_ the library is compiled into LLVM bytecode
and then translated into Javascript. Use the following command::
make emscripten
============================= ================================== ==============================================================================
Make Variable Default Meaning
============================= ================================== ==============================================================================
``EMSCRIPTEN_DIR`` ``${HOME}/.local/src/emscripten`` root directory of emscripten containing the :file:`system/include/libc` folder
============================= ================================== ==============================================================================
On successfull compilation, the compiled bitcode files can be found in
:file:`openpace-0.9_bc`. You can run our testsuite
completely in Javascript or `in your browser <../../_static/eactest.html>`_::
nodejs openpace-0.9_bc/eactest.js
# WARNING: Our tests are very time consuming and might stall your browser for a moment or two...
firefox openpace-0.9_bc/eactest.html
.. warning::
`Javascript cryptography is considered harmful`_. You may want to think
twice before using the Javascript version of OpenPACE.
*******************************************************************************
How to use OpenPACE
*******************************************************************************
OpenPACE is a native C library on top of OpenSSL. If you want to know how to
use OpenPACE from C/C++, have a look at our `API documentation
<../../_static/doxygen/modules.html>`_.
OpenPACE uses SWIG_ to offer bindings in some more programming languages. The
bindings are easily portable to lots of different languages. Currently, native
language bindings need to be explicitly turned on with ``./configure
--enable-...``
If you have chosen to install OpenPACE in a non-standard location you have to
set up the :envvar:`LD_LIBRARY_PATH` environment variable correctly. One way to
do this is::
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/libeac
If OpenPACE is compiled for Javascript, it results in a standalone Javascript
file that can be used without special requirements.
More details and a number of examples are covered here:
.. toctree::
:maxdepth: 2
usage
*******************************************************************************
Where to get help
*******************************************************************************
Do you have questions, suggestions or contributions? Feedback of any kind is
more than welcome! You can contact us through our `GitHub
<https://github.com/frankmorgner/openpace/>`_ `repositories
<https://github.com/d0/openpace/>`_ or the `project trackers
<http://sourceforge.net/projects/openpace/support>`_.
*******************************************************************************
Further Reading
*******************************************************************************
.. toctree::
:maxdepth: 3
protocols
*******************************************************************************
References
*******************************************************************************
.. target-notes::
.. _`BSI TR-03110`: https://www.bsi.bund.de/ContentBSI/Publikationen/TechnischeRichtlinien/tr03110/index_htm.html
.. _`nPA Smart Card Library`: http://vsmartcard.sourceforge.net/npa/README.html
.. _`OpenSSL`: http://openssl.org
.. _`SWIG`: http://swig.org
.. _`Emscripten`: https://github.com/kripken/emscripten
.. _`Javascript cryptography is considered harmful`: http://www.matasano.com/articles/javascript-cryptography

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:





No, thanks