[pkg-opensc-commit] [engine-pkcs11] 04/43: README: added example usage with p11-kit

[Eric Dorland]

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

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

commit 9463db1cb93c48efc7d6094ef789bee5f545c611
Author: Nikos Mavrogiannopoulos <nmav at gnutls.org>
Date:   Sun Nov 8 09:17:40 2015 +0100

    README: added example usage with p11-kit
---
 README.md | 65 +++++++++++++++++++++++----------------------------------------
 1 file changed, 24 insertions(+), 41 deletions(-)

diff --git a/README.md b/README.md
index f784bb7..3ec393a 100644
--- a/README.md
+++ b/README.md
@@ -55,10 +55,12 @@ to copy engine_pkcs11 at that location as libpkcs11.so to ease usage.
 This is handle by 'make install' of engine_pkcs11.
 
 
-## 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):
+## Using in systems without p11-kit
+
+In systems without p11-kit-proxy you need to configure OpenSSL to know about
+the engine and to use OpenSC PKCS#11 module by the engine_pkcs11. For that you
+add something like the following into your global OpenSSL configuration file
+(often in ``/etc/ssl/openssl.cnf``).
 
 ```
 [engine_section]
@@ -73,7 +75,12 @@ init = 0
 
 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.
+OpenSSL applications to select the engine by the identifier. In systems
+with p11-kit-proxy installed and configured, you do not need to modify the
+OpenSSL configuration file; the configuration of p11-kit will be used.
+
+
+## Testing the engine operation
 
 To verify that the engine is properly operating you can use the following example.
 
@@ -91,6 +98,7 @@ in the token and will not exportable.
 
 For the examples that follow, we need to generate a private key in the token and
 obtain its private key URL. The following commands utilize p11tool for that.
+
 ```
 $ p11tool --provider /usr/lib/opensc-pkcs11.so --login --generate-rsa --bits 1024 --label test-key
 $ p11tool --provider /usr/lib/opensc-pkcs11.so --list-privkeys --login
@@ -99,55 +107,30 @@ $ p11tool --provider /usr/lib/opensc-pkcs11.so --list-privkeys --login
 Note the PKCS #11 URL shown above and use it in the commands below.
 
 To generate a certificate with its key in the PKCS #11 module, the following commands commands
-can be used. This example loads engine_pkcs11 with the PKCS#11 module opensc-pkcs11.so. The
-second command creates a self signed Certificate for "Andreas Jellinghaus". The signing is done
-using the key specified by the URL. The third command creates a self-signed certificate for the
-request, the private key used to sign the certificate is the same private key used to create the
-request. Note that in a PKCS #11 URL you can specify the PIN using the "pin-value" attribute.
+can be used. The first command creates a self signed Certificate for "Andreas Jellinghaus". The
+signing is done using the key specified by the URL. The second command creates a self-signed 
+certificate for the request, the private key used to sign the certificate is the same private key
+used to create the request. Note that in a PKCS #11 URL you can specify the PIN using the 
+"pin-value" attribute.
 
 ```
 $ openssl
-OpenSSL> engine -t dynamic -pre SO_PATH:/usr/lib/engines/libpkcs11.so \
-         -pre ID:pkcs11 -pre LIST_ADD:1 -pre LOAD \
-         -pre MODULE_PATH:/usr/lib/opensc-pkcs11.so
 OpenSSL> req -engine pkcs11 -new -key "pkcs11:object=test-key;type=private;pin-value=XXXX" \
          -keyform engine -out req.pem -text -x509 -subj "/CN=Andreas Jellinghaus"
 OpenSSL> x509 -engine pkcs11 -signkey "pkcs11:object=test-key;type=private;pin-value=XXXX" \
          -keyform engine -in req.pem -out cert.pem
 ```
 
-
-You can also create/edit an openssl config file, so you don't need to type in or paste the above commands
-all the time. Here is an example for OpenSSL 0.9.8:
+For the above commands to operate in systems without p11-kit you will need to provide the
+engine configuration explicitly. The following line loads engine_pkcs11 with the PKCS#11
+module opensc-pkcs11.so. 
 
 ```
-openssl_conf            = openssl_def
-
-[openssl_def]
-engines = engine_section
-
-[engine_section]
-pkcs11 = pkcs11_section
-
-[pkcs11_section]
-engine_id = pkcs11
-dynamic_path = /usr/lib/engines/engine_pkcs11.so
-MODULE_PATH = /usr/lib/opensc-pkcs11.so
-init = 0
-
-[req]
-distinguished_name = req_distinguished_name
-
-[req_distinguished_name]
+OpenSSL> engine -t dynamic -pre SO_PATH:/usr/lib/engines/libpkcs11.so \
+         -pre ID:pkcs11 -pre LIST_ADD:1 -pre LOAD \
+         -pre MODULE_PATH:/usr/lib/opensc-pkcs11.so
 ```
 
-With such a config file you can directly call openssl to use that engine:
-
-```
-openssl req -config openssl.conf -engine pkcs11 -new -key "pkcs11:object=test-key" \
-        -keyform engine -out req.pem -text -x509 \
-        -subj "/CN=Andreas Jellinghaus"
-```
 
 ## Engine controls
 

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