openssl and pkcs11 engine - utimaco€¦ · ig_openssl_and_pkcs11_engine allrightsreserved...

Integraton GuideOpenSSL and PKCS11 EngineLinux

Integraton Guide: OpenSSL and PKCS11 Engine

Imprint

copyright 2016 Utimaco IS GmbHGermanusstrasse 4D-52080 AachenGermany

phone +49 (0)241 / 1696-200fax +49 (0)241 / 1696-199web http://hsm.utimaco.comemail [email protected] version 1.0.4date June 2016author M. Sc. Ariano-Tim Dondadocument no. IG_OpenSSL_and_PKCS11_Engine

all rights reserved No part of this documentation may be reproduced in any form (printing, photocopyor according to any other process) without the written approval of Utimaco IS GmbHor be processed, reproduced or distributed using electronic systems.Utimaco IS GmbH reserves the right to modify or amend the documentation at anytime without prior notice. Utimaco IS GmbH assumes no liability for typographicalerrors and damages incurred due to them.All trademarks and registered trademarks are the property of their respective owners.

http://hsm.utimaco.com

mailto:[email protected]

Contents1 Introduction 4

2 Overview 4

3 Requirements 5

4 Setup PKCS#11 Engine 6

4.1 Dynamic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

4.1.1 OpenSSL CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

4.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

5 Example 13

6 Further Information 14


1 IntroductionThe CryptoServer is a hardware security module developed by Utimaco IS GmbH, i.e. a physically pro-

tected specialized computer unit designed to perform sensitive cryptographic tasks and to securely

manage cryptographic keys and data. In a CryptoServer security system security-relevant actions can

be executed and security relevant information can be stored. It can be used as a universal, indepen-

dent security component for heterogeneous computer systems.

2 OverviewOpenSSL is a general purpose cryptography library that provides an open source implementation of

the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols.

Starting OpenSSL version 0.9.6, a new component was introduced to support alternative cryptogra-

phy implementations, most commonly for interfacing with external cryptography devices (e.g. Cryp-

toServer). This new component is generally called engine. OpenSSL does provide several kinds of

engines. For this article we provide instructions how to use the PKCS11 engine to work with the Cryp-

toServer PKCS11 interface. There are two options how to use the PKCS11 engine with the application

OpenSSL:

Dynamic This option enables OpenSSL application to load the PKCS11 engine at runtime.

Configuration This option loads the PKCS11 engine based on the configuration openssl.cnf auto-

matically when OpenSSL application is used.

https://www.openssl.org/

3 RequirementsThis article assumes that you have a CryptoServer PKCS#11 environment setup and PKCS#11 token

already initialized. Further information on how to setup a CryptoServer PKCS11 environment and to

initialize a PKCS#11 token can be found in QuickStart Guide PKCS#11 R2 Linux.

Software- and Hardware Requirements

HSMModel Utimaco CryptoServer CSe-Series/Se-Series/Se-Gen2-Series PCI

Utimaco CryptoServer CSe-Series/Se-Series/Se-Gen2-Series LAN

Utimaco CryptoServer Simulator

HSM Firmware Utimaco SecurityServer 4.0.0

Software OpenSSL 1.0.1f

libengine-pkcs11-openssl 0.1.8-3

p11tool2 from product package Utimaco SecurityServer 4.0.0

Ubuntu 14.04 LTS

To test a PKCS#11 engine successful integration with the CryptoServer generate a RSA key pair

(4096bit) for PKCS#11 token slot zero.

Console

p11tool2 slot=0 LoginUser=123456

PubKeyAttr=CKA_ID="Example",CKA_MODULUS_BITS=4096

PrvKeyAttr=CKA_ID="Example" GenerateKeyPair=RSA

This RSA key will be later used to run a typical OpenSSL cryptographic operation using the PKCS#11

engine.

https://kb.hsm.uti.local/general/quickstart-guide-pkcs11-r2-linux/


4 Setup PKCS#11 Engine

By default the PKCS#11 engine for OpenSSL is not installed. To install the PKCS#11 engine for

OpenSSL run:

Console

$ sudo apt-get install libengine-pkcs11-openssl

4.1 Dynamic

The dynamic method requires to load the PKCS#11 engine before it can be used further OpenSSL

cryptographic operations. You run OpenSSL as CLI to provide loading of the PKCS#11 engine manu-

ally.

Console

utimaco@utimaco:/$ openssl

OpenSSL> engine -t dynamic -pre SO_PATH:/usr/lib/engines/engine_pkcs11.so

-pre ID:pkcs11 -pre\ LIST_ADD:1 -pre LOAD -pre

MODULE_PATH:/usr/lib/libcs_pkcs11_R2.so

(dynamic) Dynamic engine loading support

[Success]: SO_PATH:/usr/lib/engines/engine_pkcs11.so

[Success]: ID:pkcs11

[Success]: LIST_ADD:1

[Success]: LOAD

[Success]: MODULE_PATH:/usr/lib/libcs_pkcs11_R2.so

Loaded: (pkcs11) pkcs11 engine

[ available ]

OpenSSL>

4.1.1 OpenSSL CLI

To check whether it’s now possible to access the RSA key we have previously generated for our

PKCS#11 token on slot zero, create a self signed certificate file as shown next.

Console

utimaco@utimaco:/$ openssl

OpenSSL> engine -t dynamic -pre\ SO_PATH:/usr/lib/engines/engine_pkcs11.so

-pre ID:pkcs11 -pre\ LIST_ADD:1 -pre LOAD -pre

MODULE_PATH:/usr/lib/libcs_pkcs11_R2.so

(dynamic) Dynamic engine loading support

[Success]: SO_PATH:/usr/lib/engines/engine_pkcs11.so

[Success]: ID:pkcs11

[Success]: LIST_ADD:1

[Success]: LOAD

[Success]: MODULE_PATH:/usr/lib/libcs_pkcs11_R2.so

Loaded: (pkcs11) pkcs11 engine

[ available ]

OpenSSL> req -engine pkcs11 -new -key id_4578616D706C65 -keyform engine\

-out certificate.pem -text -x509 -subj\ "/C=DE/ST=NRW/L=Aachen/O=Utimaco

IS GmbH/OU=SystemEngineering\ HSM/CN=Max Mustermann"

engine "pkcs11" set.

PKCS11 token PIN: ******

Show the content of the certificate.pem file and double check if all information given previously are

correct.

Console

utimaco@utimaco:/$ openssl x509 -text -noout -in certificate.pem

Certificate:

Data:

Version: 3 (0x2)

Serial Number: 17299328040199222677 (0xf0138f3261077595)


Signature Algorithm: sha256WithRSAEncryption

Issuer: C=DE, ST=NRW, L=Aachen, O=Utimaco IS GmbH,

OU=SystemEngineering HSM, CN=Max Mustermann

Validity

Not Before: Mar 12 14:10:51 2015 GMT

Not After : Apr 11 14:10:51 2015 GMT

Subject: C=DE, ST=NRW, L=Aachen, O=Utimaco IS GmbH,

OU=SystemEngineering HSM, CN=Max Mustermann

Subject Public Key Info:

Public Key Algorithm: rsaEncryption

Public-Key: (4096 bit)

Modulus:

00:82:00:aa:84:eb:cd:7d:0d:7c:ce:e0:e2:a5:65:

cc:ca:69:e5:76:ee:ed:86:70:52:5c:10:88:c4:75:

3e:d3:93:47:69:17:c0:18:02:53:f3:c2:a1:48:28:

a5:47:b3:7f:cb:e8:ae:0e:0d:ab:2c:33:83:8f:56:

ef:a7:3d:0d:ce:70:10:17:14:62:f6:46:8c:41:86:

39:18:d6:e1:53:69:20:36:18:ab:c1:a5:43:16:f6:

98:82:d8:cc:da:f2:0a:3d:1a:e6:3b:e6:1c:5a:57:

75:2e:9f:4a:1d:f0:69:7d:6e:09:ab:b2:da:a4:96:

d7:0f:04:9f:94:fd:ae:0e:86:c5:16:76:24:f3:c3:

e9:ab:fe:d0:03:42:ad:73:45:2f:46:c6:a2:c3:44:

71:d4:20:94:a1:c9:24:e3:94:a8:39:cf:83:65:77:

d3:ba:2b:9e:ff:ea:a8:3b:b2:cb:a4:41:f0:8f:4d:

de:55:0a:00:77:36:11:10:e7:4b:95:56:a3:7e:bf:

9a:c2:1c:7c:51:73:94:c6:19:ad:81:ac:11:62:96:

d0:64:ba:d9:03:6a:56:9a:f6:0a:0a:cd:38:13:f9:

fc:01:60:1f:50:83:c8:01:37:39:6e:14:d6:18:b2:

86:fa:31:3c:7c:13:1a:ec:94:eb:76:38:1f:83:31:

0d:be:ec:02:fb:48:81:a5:ba:0c:13:ac:ae:e8:60:

23:da:62:23:0e:19:bf:59:12:6b:6b:30:7f:6a:6b:

d3:13:23:2c:ca:53:29:dc:eb:3b:aa:84:c2:e6:7e:

0a:ba:71:be:74:41:14:54:4e:5b:86:96:04:17:5d:

09:39:c1:10:72:35:82:95:a5:7c:18:f0:eb:de:8f:

01:0c:04:05:ab:b2:e9:bc:f1:30:0b:fa:6e:45:12:

74:93:d4:a0:a3:b4:d7:00:e6:00:61:67:1b:0a:68:

01:04:49:0c:1c:d4:33:6a:86:3a:57:ea:ed:e7:35:

a4:42:91:ab:db:9e:8b:55:33:d4:e2:01:77:31:4f:

bf:c7:8a:f5:18:48:88:1f:fa:81:92:8c:97:ea:de:

e4:1a:73:36:87:2a:17:48:4b:b6:b3:a0:ee:4b:c0:

d8:17:1a:e5:dd:78:47:52:e7:4c:df:3c:a3:c7:60:

28:25:17:c0:ff:0e:8d:ed:63:62:c8:59:8b:2a:66:

b7:11:7f:39:1f:1e:a3:b9:9d:01:0c:08:00:ed:96:

e9:5b:79:a4:bf:cf:90:63:e6:0b:52:f1:19:5e:9b:

49:5f:4e:96:1c:de:b2:19:98:e3:41:d4:88:4d:c8:

39:6b:b2:c8:d8:0f:09:4b:11:fc:aa:58:97:0f:7c:

3a:48:cd

Exponent: 65537 (0x10001)

X509v3 extensions:

X509v3 Subject Key Identifier:

5D:A8:D4:E0:EF:23:8B:AB:7F:89:0C:90:1F:8A:06:F6:5F:FE:AA:F2

X509v3 Authority Key Identifier:

keyid:5D:A8:D4:E0:EF:23:8B:AB:7F:89:0C:90:1F:8A:06:F6:5F:FE:AA:F2

X509v3 Basic Constraints:

CA:TRUE

Signature Algorithm: sha256WithRSAEncryption

19:12:1e:93:28:d1:35:5c:e1:2d:d8:23:e2:43:dd:5c:11:2d:

50:bc:28:71:3c:63:ae:ac:24:4c:99:71:eb:fb:73:b9:96:4d:

cc:55:9d:e0:e0:2a:e0:2a:f0:67:0a:5f:76:31:d0:53:da:f9:

16:44:14:b7:f7:cb:78:c9:e5:2a:f0:9e:90:21:5c:83:e7:de:


4c:e4:67:ee:13:49:16:9f:33:54:62:82:09:76:48:da:8f:1e:

32:5c:6e:22:c8:92:4f:26:c6:de:8b:f4:5d:4d:c8:bb:e6:40:

c3:ea:dc:b5:2e:97:fb:32:04:ec:44:ff:52:61:68:5d:57:4f:

3c:bf:49:ce:15:3d:33:a2:f4:54:a7:91:f8:dc:2a:1a:72:69:

60:66:f8:3c:bc:bf:4d:95:12:96:c3:45:78:f6:7d:f4:c2:33:

63:ba:08:76:ae:f2:18:91:2b:ea:bc:01:59:d6:83:3a:7e:9a:

91:7a:3b:a6:1c:48:81:fd:dc:c4:20:88:e0:c2:48:5f:22:65:

57:a7:d3:ae:ea:e0:7b:01:75:6b:3c:c5:2b:21:ab:b2:2a:c1:

74:15:d0:61:99:8b:41:e4:d5:b0:1f:03:b3:ee:8f:3e:b3:fd:

0d:30:ca:80:ca:4e:f3:a3:fd:99:16:21:8f:7b:1a:74:a8:f3:

22:c6:96:15:ae:2a:8e:ad:76:1a:e8:1e:c9:6d:f0:3a:34:a9:

3e:ab:9c:72:d3:b0:35:e3:2a:7b:52:1d:d5:b2:26:f5:96:37:

1e:c0:1e:50:9d:3c:75:e5:55:16:67:2e:f3:a4:96:15:fc:ec:

dc:3f:a2:36:f6:9a:e5:00:34:ea:c4:88:03:e2:3c:de:1d:08:

f3:86:ae:76:83:20:91:8c:ac:49:89:63:e5:8d:09:12:27:e4:

42:db:cc:77:5b:c8:64:74:33:e6:bb:fe:ee:25:32:05:93:77:

84:86:36:75:b4:fa:73:43:36:67:9e:75:43:b5:5c:6c:6a:ec:

f0:ee:b6:53:a4:e7:28:01:73:39:ba:34:9c:89:a9:ea:c6:36:

83:40:0d:2f:11:e8:21:84:1f:ce:05:37:5b:c5:ad:d8:22:09:

52:42:02:16:66:fc:0d:c7:5d:c8:63:73:5d:ec:ff:70:e6:21:

3a:90:37:39:15:16:e8:e8:b8:9e:0e:ad:55:6f:3d:69:c0:e1:

40:64:d3:09:5a:a7:f9:d8:67:b8:e2:ea:93:6e:6f:fa:80:cf:

8b:b6:da:7c:17:f2:ce:17:a1:7a:7f:50:73:c9:5e:d5:a3:e9:

ee:ac:d2:7a:6e:4f:1d:f2:d7:2e:b9:e7:05:10:1b:8a:85:ca:

2e:2e:6e:34:12:39:d6:01

4.2 Configuration

Loading the PKCS#11 engine manually each time you need to run a certain openssl command is not

handy. By adding some engine information to (openssl.cnf) configuration file, OpenSSL automatically

loads thePKCS#11 engine. After adding engine information (openssl.cnf) you canuse the enginewith

the engine parameter referring to the id given in the (openssl.cnf). For our example we used a short

(/etc/ssl/openssl.cnf) file.

/etc/ssl/openssl.cnf

#

# OpenSSL example configuration file.

# This is mostly being used for generation of certificate requests.

#

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/libcs_pkcs11_R2.so

PIN = "123456"

init = 0

[req]

distinguished_name = req_distinguished_name

[req_distinguished_name]


To check whether it’s now possible to access the RSA key using OpenSSL with the configuration file

setup, run the next example.

Console

utimaco@utimaco:/$ openssl req -engine pkcs11 -new -key\ id_4578616D706C65

-keyform engine -out certificate.pem -text -x509\ -subj

"/C=DE/ST=NRW/L=Aachen/O=Utimaco IS GmbH/OU=SystemEngineering\ HSM/CN=Max

Mustermann"

Using OpenSSL like this is much easier and can be used in shell scripts compared to load PKCS#11

engine manually each time you run a certain OpenSSL command.

5 Example

OpenSSL & PKCS#11

You cannot do everything with OpenSSL and the PKCS#11 engine. OpenSSL’s

PKCS#11 support is poor.

For example, you cannot create an RSA key inside the HSM with genrsa/genpkey. You have to use

p11tool2 for it like this:

Console

p11tool2 LoginUser=PIN PubKeyAttr=CKA_ID=mykey,CKA_MODULUS_BITS=4096\

PrvKeyAttr=CKA_ID=mykey GenerateKeyPair=RSA

Now you can use this key in certain operations. But it won’t work to sign data with a private key

provided as a file since PKCS#11 expacts the private key inside the token (HSM). For the created key,

do it as follows:

Console

openssl rsautl -engine pkcs11 -keyform engine -inkey id_6D796B6579\ -sign

-in datatosign.txt -out signature.dat

Key Identification

”6D796B6579” is the hex value of the String ”mykey” (again, that’s the way OpenSSL

expects it).

To verify the signature, use:

Console

openssl rsautl -engine pkcs11 -keyform engine -inkey id_6D796B6579\ -verify

-in signature.dat

You can also replace ”sign” by ”encrypt” and ”verify” by ”decrypt” in the commands above.


6 Further InformationThis document forms a part of the information and support which is provided by the Utimaco IS

GmbH. Additional documentation can be found on the product CD in the documentation directory.

All CryptoServer product documentation is also available at the Utimaco IS GmbH website:



Contact

Utimaco IS GmbHGermanusstraße 4D - 52080 AachenGermany

phone +49 241 1696 - 200fax +49 241 1696 - 199

web https://hsm.utimaco.comemail [email protected]

https://hsm.utimaco.com

mailto:[email protected]

openssl and pkcs11 engine - utimaco€¦ · ig_openssl_and_pkcs11_engine allrightsreserved...

Documents