[pkg-opensc-commit] [engine-pkcs11] 139/152: updated documentation

Eric Dorland eric at moszumanska.debian.org
Mon Oct 19 03:11:26 UTC 2015 

This is an automated email from the git hooks/post-receive script.

eric pushed a commit to branch master
in repository engine-pkcs11.

commit be98266f86d657f80069d41dc56409e144c0838d
Author: Nikos Mavrogiannopoulos <nmav at gnutls.org>
Date:   Sat Sep 26 10:34:32 2015 +0200

    updated documentation
---
 NEWS      |  2 +-
 README.md | 94 ++++++++++++++++++++++++++++++++++-----------------------------
 2 files changed, 52 insertions(+), 44 deletions(-)

diff --git a/NEWS b/NEWS
index d3ce207..bff7fa9 100644
--- a/NEWS
+++ b/NEWS
@@ -4,7 +4,7 @@ New in 0.2.0; unreleased; Nikos Mavrogiannopoulos
 * Added support for ECDSA when compiled with libp11 0.3.0
   (Douglas E. Engert)
 * Updated engine name to match other openssl engines
-* Added support for PKCS #11 URLs -RFC7512 when loading keys
+* Added support for PKCS #11 URLs -RFC7512- when loading keys
   or certificates (David Woodhouse)
 * Added support for id_<ID> legacy object identifier (Petr Písař)
 * When no module is set default to p11-kit-proxy.so, allowing
diff --git a/README.md b/README.md
index 874a19b..f4ef470 100644
--- a/README.md
+++ b/README.md
@@ -2,17 +2,29 @@
 
 [![Build Status](https://travis-ci.org/OpenSC/engine_pkcs11.png)](https://travis-ci.org/OpenSC/engine_pkcs11)
 
-# Submitting pull requests
 
-For adding new features or extending functionality in addition to the code,
-please submit a test program which verifies the correctness of operation.
-See tests/ for the existing test suite.
+# engine_pkcs11: an OpenSSL engine for PKCS#11 modules
 
-# About engine_pkcs11: an OpenSSL engine for PKCS#11 modules
+engine_pkcs11 is an engine plug-in for the OpenSSL library allowing to
+access PKCS #11 modules in a semi-transparent way.
 
-engine_pkcs11 is a plug-in for the OpenSSL
+## PKCS#11
 
-## OpenSSL
+The PKCS#11 API is an abstract API to access operations on cryptographic objects
+such as private keys, without requiring access to the objects themselves. That
+is, it provides a logical separation of the keys from the operations. The
+PKCS #11 API is mainly used to access objects in smart cards and Hardware or Software
+Security Modules (HSMs). That is because in these modules the cryptographic keys
+are isolated in hardware or software and are not made available to the applications
+using them.
+
+PKCS#11 API is an OASIS standard and it is supported by various hardware and software
+vendors. Usually, hardware vendors provide a PKCS#11 module to access their devices.
+A prominent example is the OpenSC PKCS #11 module which provides access to a variety
+of smart cards. Other libraries like NSS or GnuTLS already take advantage of PKCS #11
+to access cryptographic objects.
+
+## OpenSSL engines
 
 OpenSSL implements various cipher, digest, and signing features and it can
 consume and produce keys. However plenty of people think that these features
@@ -21,46 +33,21 @@ hardware security modules. Therefore OpenSSL has an abstraction layer called
 engine which can delegate some of these features to different piece of
 software or hardware.
 
-OpenSSL comes with a few engines for some hardware or software security
-modules, like for IBM RSA module or Windows CryptoAPI. (See OpenSSL sources
-and ``openssl engine -t`` command output). The engines can be built statically
-into the OpenSSL library or they can be built as separate plug-in. Third party
-engines has to be always built as plug-ins.
-
-## OpenSSL plug-ins
-
-One of these plug-ins is the engine_pkcs11. The engine_pkcs11 is an OpenSSL
-engine which provides a gateway between PKCS#11 modules and the OpenSSL engine
-API. One has to register the engine into the OpenSSL and one has to provide
-path to a PKCS#11 module which should be gatewayed to. (This can be done in the
-OpenSSL configuration file.)
-
-## PKCS#11
-
-PKCS#11 module is again a plug-in which implements PKCS#11 API and the purpose
-of the API is to provide some cryptograpic features like key storage, key
-generation, signing, digesting, encyphering, etc. The PKCS#11 API is something
-like the OpenSSL engine API.
-
-PKCS#11 API is a standard and it's supported by various hardware and software
-vendors. Usually, hardware vendor provides a propriatary PKCS#11 module for
-his cryptographic device and a cryptogrographic library, like NSS or GnuTLS,
-can use it to access the hardware.
-
-## OpenSC
+engine_pkcs11 tries to fit the PKCS #11 API within the engine API of OpenSSL.
+That is, it provides a gateway between PKCS#11 modules and the OpenSSL engine API.
+One has to register the engine into the OpenSSL and one has to provide
+path to a PKCS#11 module which should be gatewayed to. This can be done by editing
+the OpenSSL configuration file (not recommended), by engine specific controls,
+or by using the p11-kit proxy module.
 
-Now comes OpenSC which aims to replace the proprietary PKCS#11 modules by
-accessing the hardware directly (or indirectly via other software like
-pscs-lite). Thefore OpenSC provides an PKCS#11 module called opensc-pkcs11
-which encapsulted OpenSC into PKCS#11 API which allows to plug the OpenSC into
-into any software supporting PKCS#11.
+The p11-kit proxy module provides access to any configured PKCS #11 module
+in the system. See [the p11-kit web pages](http://p11-glue.freedesktop.org/p11-kit.html)
+for more information.
 
-Unfortunatelly, OpenSSL does not support PKSC#11 (yet). OpenSSL has the engine
-API only (like Windows have CryproAPI). Therefore the engine_pkcs11 exists
-which encapsulated PKCS#11 into the OpenSSL engine API.
 
-## OpenSSL Configuration
+# PKCS #11 module configuration
 
+## OpenSSL configuration file
 To configure OpenSSL to know about the engine and to use OpenSC PKCS#11 module
 by the engine_pkcs11, you add something like this into your global OpenSSL
 configuration file (``/etc/ssl/openssl.cnf`` probably):
@@ -80,4 +67,25 @@ The dynamic_path value is the engine_pkcs11 plug-in, the MODULE_PATH value is
 the OpenSC PKCS#11 plug-in. The engine_id value is an arbitrary identifier for
 OpenSSL applications to select the engine by the identifier.
 
+## Engine controls
+
+A specific module can be specified using the following call.
+
+```
+ENGINE_ctrl_cmd(engine, "MODULE_PATH",
+		0, "/path/to/pkcs11module.so", NULL, 1);
+
+## p11-kit
+
+No action is required to load modules enabled in p11-kit. In that case objects must
+be referred to, using the PKCS #11 URL.
+
+
+# Developer information
+
+## Submitting pull requests
+
+For adding new features or extending functionality in addition to the code,
+please submit a test program which verifies the correctness of operation.
+See tests/ for the existing test suite.
 

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-opensc/engine-pkcs11.git

More information about the pkg-opensc-commit mailing list