Blame README.md

Packit 6b81fa
# Build state
Packit 6b81fa
Packit 6b81fa
[![Linux Build Status](https://travis-ci.org/OpenSC/libp11.png)](https://travis-ci.org/OpenSC/libp11)
Packit 6b81fa
[![Windows Build status](https://ci.appveyor.com/api/projects/status/kmbu8nex5ogecoiq?svg=true)](https://ci.appveyor.com/project/LudovicRousseau/libp11)
Packit 6b81fa
[![Coverity Scan Status](https://scan.coverity.com/projects/15472/badge.svg)](https://scan.coverity.com/projects/opensc-libp11)
Packit 6b81fa
[![Code Quality: Cpp](https://img.shields.io/lgtm/grade/cpp/g/OpenSC/libp11.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/OpenSC/libp11/context:cpp)
Packit 6b81fa
[![Total Alerts](https://img.shields.io/lgtm/alerts/g/OpenSC/libp11.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/OpenSC/libp11/alerts)
Packit 6b81fa
Packit 6b81fa
Packit 6b81fa
# Overview
Packit 6b81fa
Packit 6b81fa
This code repository produces two libraries:
Packit 6b81fa
* libp11 provides a higher-level (compared to the PKCS#11 library)
Packit 6b81fa
interface to access PKCS#11 objects.  It is designed to integrate with
Packit 6b81fa
applications that use OpenSSL.
Packit 6b81fa
* pkcs11 engine plugin for the OpenSSL library allows accessing
Packit 6b81fa
PKCS#11 modules in a semi-transparent way.
Packit 6b81fa
Packit 6b81fa
The wiki page for this project is at https://github.com/OpenSC/libp11/wiki
Packit 6b81fa
and includes a bug tracker and source browser.
Packit 6b81fa
Packit 6b81fa
## PKCS#11
Packit 6b81fa
Packit 6b81fa
The PKCS#11 API is an abstract API to perform operations on cryptographic objects
Packit 6b81fa
such as private keys, without requiring access to the objects themselves. That
Packit 6b81fa
is, it provides a logical separation of the keys from the operations. The
Packit 6b81fa
PKCS #11 API is mainly used to access objects in smart cards and Hardware or Software
Packit 6b81fa
Security Modules (HSMs). That is because in these modules the cryptographic keys
Packit 6b81fa
are isolated in hardware or software and are not made available to the applications
Packit 6b81fa
using them.
Packit 6b81fa
Packit 6b81fa
PKCS#11 API is an OASIS standard and it is supported by various hardware and software
Packit 6b81fa
vendors. Usually, hardware vendors provide a PKCS#11 module to access their devices.
Packit 6b81fa
A prominent example is the OpenSC PKCS #11 module which provides access to a variety
Packit 6b81fa
of smart cards. Other libraries like NSS or GnuTLS already take advantage of PKCS #11
Packit 6b81fa
to access cryptographic objects.
Packit 6b81fa
Packit 6b81fa
## OpenSSL engines
Packit 6b81fa
Packit 6b81fa
OpenSSL implements various cipher, digest, and signing features and it can
Packit 6b81fa
consume and produce keys. However plenty of people think that these features
Packit 6b81fa
should be implemented in separate hardware, like USB tokens, smart cards or
Packit 6b81fa
hardware security modules. Therefore OpenSSL has an abstraction layer called
Packit 6b81fa
"engine" which can delegate some of these features to different piece of
Packit 6b81fa
software or hardware.
Packit 6b81fa
Packit 6b81fa
engine_pkcs11 tries to fit the PKCS#11 API within the engine API of OpenSSL.
Packit 6b81fa
That is, it provides a gateway between PKCS#11 modules and the OpenSSL engine API.
Packit 6b81fa
One has to register the engine with OpenSSL and one has to provide the
Packit 6b81fa
path to the PKCS#11 module which should be gatewayed to. This can be done by editing
Packit 6b81fa
the OpenSSL configuration file, by engine specific controls,
Packit 6b81fa
or by using the p11-kit proxy module.
Packit 6b81fa
Packit 6b81fa
The p11-kit proxy module provides access to any configured PKCS #11 module
Packit 6b81fa
in the system. See [the p11-kit web pages](http://p11-glue.freedesktop.org/p11-kit.html)
Packit 6b81fa
for more information.
Packit 6b81fa
Packit 6b81fa
Packit 6b81fa
# PKCS #11 module configuration
Packit 6b81fa
Packit 6b81fa
## Copying the engine shared object to the proper location
Packit 6b81fa
Packit 6b81fa
OpenSSL has a location where engine shared objects can be placed
Packit 6b81fa
and they will be automatically loaded when requested. It is recommended
Packit 6b81fa
to copy the engine_pkcs11 to that location as "libpkcs11.so" to ease usage.
Packit 6b81fa
This is handle by 'make install' of engine_pkcs11.
Packit 6b81fa
Packit 6b81fa
Packit 6b81fa
## Using the engine from the command line
Packit 6b81fa
Packit 6b81fa
In systems with p11-kit-proxy engine_pkcs11 has access to all the configured
Packit 6b81fa
PKCS #11 modules and requires no further OpenSSL configuration.
Packit 6b81fa
In systems without p11-kit-proxy you need to configure OpenSSL to know about
Packit 6b81fa
the engine and to use OpenSC PKCS#11 module by the engine_pkcs11. For that you
Packit 6b81fa
add something like the following into your global OpenSSL configuration file
Packit 6b81fa
(often in ``/etc/ssl/openssl.cnf``).  This line must be placed at the top,
Packit 6b81fa
before any sections are defined:
Packit 6b81fa
Packit 6b81fa
```
Packit 6b81fa
openssl_conf = openssl_init
Packit 6b81fa
```
Packit 6b81fa
Packit 6b81fa
This should be added to the bottom of the file:
Packit 6b81fa
Packit 6b81fa
```
Packit 6b81fa
[openssl_init]
Packit 6b81fa
engines=engine_section
Packit 6b81fa
Packit 6b81fa
[engine_section]
Packit 6b81fa
pkcs11 = pkcs11_section
Packit 6b81fa
Packit 6b81fa
[pkcs11_section]
Packit 6b81fa
engine_id = pkcs11
Packit 6b81fa
dynamic_path = /usr/lib/ssl/engines/libpkcs11.so
Packit 6b81fa
MODULE_PATH = opensc-pkcs11.so
Packit 6b81fa
init = 0
Packit 6b81fa
```
Packit 6b81fa
Packit 6b81fa
The dynamic_path value is the engine_pkcs11 plug-in, the MODULE_PATH value is
Packit 6b81fa
the OpenSC PKCS#11 plug-in. The engine_id value is an arbitrary identifier for
Packit 6b81fa
OpenSSL applications to select the engine by the identifier. In systems
Packit 6b81fa
with p11-kit-proxy installed and configured, you do not need to modify the
Packit 6b81fa
OpenSSL configuration file; the configuration of p11-kit will be used.
Packit 6b81fa
Packit 6b81fa
If you do not update the OpenSSL configuration file you will need to
Packit 6b81fa
specify the engine configuration explicitly. The following line loads
Packit 6b81fa
engine_pkcs11 with the PKCS#11 module opensc-pkcs11.so:
Packit 6b81fa
Packit 6b81fa
```
Packit 6b81fa
OpenSSL> engine -t dynamic -pre SO_PATH:/usr/lib/engines/engine_pkcs11.so
Packit 6b81fa
         -pre ID:pkcs11 -pre LIST_ADD:1 -pre LOAD 
Packit 6b81fa
         -pre MODULE_PATH:opensc-pkcs11.so
Packit 6b81fa
```
Packit 6b81fa
Packit 6b81fa
Packit 6b81fa
## Testing the engine operation
Packit 6b81fa
Packit 6b81fa
To verify that the engine is properly operating you can use the following example.
Packit 6b81fa
Packit 6b81fa
```
Packit 6b81fa
$ openssl engine pkcs11 -t
Packit 6b81fa
(pkcs11) pkcs11 engine
Packit 6b81fa
     [ available ]
Packit 6b81fa
```
Packit 6b81fa
Packit 6b81fa
## Using p11tool and OpenSSL from the command line
Packit 6b81fa
Packit 6b81fa
This section demonstrates how to use the command line to create a self signed
Packit 6b81fa
certificate for "Andreas Jellinghaus". The key of the certificate will be generated
Packit 6b81fa
in the token and will not exportable.
Packit 6b81fa
Packit 6b81fa
For the examples that follow, we need to generate a private key in the token and
Packit 6b81fa
obtain its private key URL. The following commands utilize p11tool for that.
Packit 6b81fa
Packit 6b81fa
```
Packit 6b81fa
$ p11tool --provider /usr/lib/opensc-pkcs11.so --login --generate-rsa --bits 1024 --label test-key
Packit 6b81fa
$ p11tool --provider /usr/lib/opensc-pkcs11.so --list-privkeys --login
Packit 6b81fa
```
Packit 6b81fa
Packit 6b81fa
Note the PKCS #11 URL shown above and use it in the commands below.
Packit 6b81fa
Packit 6b81fa
To generate a certificate with its key in the PKCS #11 module, the following commands commands
Packit 6b81fa
can be used. The first command creates a self signed Certificate for "Andreas Jellinghaus". The
Packit 6b81fa
signing is done using the key specified by the URL. The second command creates a self-signed 
Packit 6b81fa
certificate for the request, the private key used to sign the certificate is the same private key
Packit 6b81fa
used to create the request. Note that in a PKCS #11 URL you can specify the PIN using the 
Packit 6b81fa
"pin-value" attribute.
Packit 6b81fa
Packit 6b81fa
```
Packit 6b81fa
$ openssl
Packit 6b81fa
OpenSSL> req -engine pkcs11 -new -key "pkcs11:object=test-key;type=private;pin-value=XXXX" \
Packit 6b81fa
         -keyform engine -out req.pem -text -x509 -subj "/CN=Andreas Jellinghaus"
Packit 6b81fa
OpenSSL> x509 -engine pkcs11 -signkey "pkcs11:object=test-key;type=private;pin-value=XXXX" \
Packit 6b81fa
         -keyform engine -in req.pem -out cert.pem
Packit 6b81fa
```
Packit 6b81fa
Packit 6b81fa
Packit 6b81fa
## Engine controls
Packit 6b81fa
Packit 6b81fa
The supported engine controls are the following.
Packit 6b81fa
Packit 6b81fa
* **SO_PATH**: Specifies the path to the 'pkcs11-engine' shared library 
Packit 6b81fa
* **MODULE_PATH**: Specifies the path to the pkcs11 module shared library 
Packit 6b81fa
* **PIN**: Specifies the pin code 
Packit 6b81fa
* **VERBOSE**: Print additional details 
Packit 6b81fa
* **QUIET**: Do not print additional details 
Packit 6b81fa
* **LOAD_CERT_CTRL**: Load a certificate from token
Packit 6b81fa
* **SET_USER_INTERFACE**: Set the global user interface
Packit 6b81fa
* **SET_CALLBACK_DATA**: Set the global user interface extra data
Packit 6b81fa
* **FORCE_LOGIN**: Force login to the PKCS#11 module
Packit 6b81fa
Packit 6b81fa
An example code snippet setting specific module is shown below.
Packit 6b81fa
Packit 6b81fa
```
Packit 6b81fa
ENGINE_ctrl_cmd(engine, "MODULE_PATH",
Packit 6b81fa
		0, "/path/to/pkcs11module.so", NULL, 1);
Packit 6b81fa
```
Packit 6b81fa
Packit 6b81fa
In systems with p11-kit, if this engine control is not called engine_pkcs11
Packit 6b81fa
defaults to loading the p11-kit proxy module.
Packit 6b81fa
Packit 6b81fa
Packit 6b81fa
# Developer information
Packit 6b81fa
Packit 6b81fa
## Thread safety in libp11
Packit 6b81fa
Packit 6b81fa
Thread-safety requires dynamic callbacks to be registered by the calling
Packit 6b81fa
application with the following OpenSSL functions:
Packit 6b81fa
* CRYPTO_set_dynlock_create_callback
Packit 6b81fa
* CRYPTO_set_dynlock_destroy_callback
Packit 6b81fa
* CRYPTO_set_dynlock_lock_callback
Packit 6b81fa
Packit 6b81fa
## Submitting pull requests
Packit 6b81fa
Packit 6b81fa
For adding new features or extending functionality in addition to the code,
Packit 6b81fa
please also submit a test program which verifies the correctness of operation.
Packit 6b81fa
See tests/ for the existing test suite.