Lise-Meitner-Allee 4

44801 Bochum

Telefon: +49 234 438702-09

Telefax: +49 234 438702-11

E-Mail: [email protected]
Internet: www.escrypt.com

ECU Protection PKI

Middleware Handbook

ESCRYPT GmbH – Embedded Security

www.escrypt.com

Version: 1.6

Date: 2014-10-17
Document History

Version Author Notes Date

0.1 MOM Document created 30-Aug-2013

0.2 JPE Added new information about smart card TLS 05-Sep-2013
authentication

0.9 JPE Release candidate Sep-2013

0.9.1 MOM Added comment regarding system variables for TLS 12-Sep-2013
communication

0.9.2 JPE Peer reviewed 16-Sep-2013

1.0 JPE - Added information about the different type of 04-Oct-2013

releases.

- Added error codes.

1.1 JPE - Added information about installation, CNTLM, and 15-Jan-2014

server availability.

1.2 JPE, MOM - Major overhaul 07-Mar-2014

1.3 MOM - Adds section "troubleshooting"; moves error codes 24-Mar-2014

to middleware specification; renamed document to
"handbook"

1.4 JPE, MOM - Update for latest middleware; removed information 20-May-2014
pertaining to proxy authentication

1.5 JPE - Updated information pertaining to the middleware 13-Oct-2014

verification tool; updated information pertaining to
the installation of the middleware

1.6 AS - Proxy Auto-Configuration 17-Oct-2014

ECU Protection PKI Middleware Handbook 3

Contents
ECU Protection PKI ...................................................................................................................................1

Middleware Handbook ...........................................................................................................................1

Document History ....................................................................................................................................2

Contents.......................................................................................................................................................3

1 Introduction .......................................................................................................................................4

2 Contents of Release Archive ........................................................................................................5

3 Prerequisites for the Middleware ..............................................................................................6

4 Installing the Middleware .............................................................................................................7

5 Using the Middleware ....................................................................................................................9

5.1 Smart Card Readers ................................................................................................................9

5.2 Proxy Auto-Config ...................................................................................................................9

5.3 Integrated Windows Authentication (IWA) ....................................................................9

5.4 Verifying the Middleware Setup ...................................................................................... 10

5.5 Error Codes.............................................................................................................................. 11

6 System Variables ........................................................................................................................... 12

6.1 Overall Configuration .......................................................................................................... 12

6.2 TLS Communication Configuration ................................................................................ 12

7 Troubleshooting............................................................................................................................ 14

8 Bibliography ................................................................................................................................... 15

█ ESCRYPT GmbH – Embedded Security

GESCHÄFTSFÜHRER: DR.-ING. JAN PELZL, DR.-ING. THOMAS WOLLINGER

HANDELSREGISTER: AMTSGERICHT BOCHUM NR. 7877 · ST. -NR. 350/5714/0765
BANKVERBINDUNG: SPARKASSE KREFELD · KONTO 12 039 · BLZ 320 500 00
ECU Protection PKI Middleware Handbook 4

1 Introduction
This document describes the process and necessary steps that need to be taken to
install and use the ECU Protection PKI middleware on a Windows 7 32/64-bit
machine. The DLL provided in the release is 32-bit.

Section 2 provides details about the content of the release package. Sections 3 and 4
describe how the middleware is installed. Section 5 contains all information needed
to use the middleware. Section 6 provides information that may be relevant during
development. Finally, Section 7 contains some frequently asked questions that may
help in troubleshooting.

█ ESCRYPT GmbH – Embedded Security

GESCHÄFTSFÜHRER: DR.-ING. JAN PELZL, DR.-ING. THOMAS WOLLINGER

HANDELSREGISTER: AMTSGERICHT BOCHUM NR. 7877 · ST. -NR. 350/5714/0765
BANKVERBINDUNG: SPARKASSE KREFELD · KONTO 12 039 · BLZ 320 500 00
ECU Protection PKI Middleware Handbook 5

2 Contents of Release Archive

There are 5 directories in the release archive base directory:

 src: contains source code written in C. These files provide an example on how
to use the PKCS #11 functions that the middleware implements.
 bin: contains the PKCS#11 middleware library (PKCS11Library.dll).
 deploy: contains the modified axis2c libraries, as well as the axis2.xml
configuration file.
 gnutls_downloaded: A placeholder for a GnuTLS download. Needs to contain
the GnuTLS libraries used for secure communication with the ECU Protection
PKI server.
 dummy: contains credentials that are used to “ping” the ECU Protection PKI
server in the PKCS#11 function C_GetSlotList.

Additionally, the following files related to the execution of the middleware are
included in the base directory:

 MiddlewareInstaller.bat: this batch file will set the system environment

variables (see Section 6) and will install the necessary software onto the
system.
Note: This tool only needs to be run once (for fresh installations).
 MiddlewareVerifier.exe: this executable verifies that the middleware was
installed correctly by running several checks.
 vcredist2008_x86.exe: the installer for the Visual C++ 2008 Redistributable
libraries. Automatically called by MiddlewareInstaller.bat (there is no need to
run this installer independently of the batch file).
 vcredist2012_x86.exe: the installer for Visual C++ 2012 Redistributable
libraries. Automatically called by MiddlewareInstaller.bat (there is no need to
run this installer independently of the batch file).

█ ESCRYPT GmbH – Embedded Security

GESCHÄFTSFÜHRER: DR.-ING. JAN PELZL, DR.-ING. THOMAS WOLLINGER

HANDELSREGISTER: AMTSGERICHT BOCHUM NR. 7877 · ST. -NR. 350/5714/0765
BANKVERBINDUNG: SPARKASSE KREFELD · KONTO 12 039 · BLZ 320 500 00
ECU Protection PKI Middleware Handbook 6

3 Prerequisites for the Middleware

The middleware requires GnuTLS to be successfully installed (the middleware uses
v3.2.18). GnuTLS pre-compiled for Windows can be found at the following web
address:

ftp://ftp.gnutls.org/gcrypt/gnutls/w32/

In order to communicate with the PKCS#11 interface (separate from the interface
used in the middleware), the OpenSC PKCS#11 provider library (opensc-pkcs11.dll)
must be downloaded. The installer for OpenSC can be found at the following web
address:

http://sourceforge.net/projects/opensc/files/OpenSC/opensc-0.13.0/opensc-0.13.0-
win32.msi/download

█ ESCRYPT GmbH – Embedded Security

GESCHÄFTSFÜHRER: DR.-ING. JAN PELZL, DR.-ING. THOMAS WOLLINGER

HANDELSREGISTER: AMTSGERICHT BOCHUM NR. 7877 · ST. -NR. 350/5714/0765
BANKVERBINDUNG: SPARKASSE KREFELD · KONTO 12 039 · BLZ 320 500 00
ECU Protection PKI Middleware Handbook 7

4 Installing the Middleware

The middleware can be installed through the following 3 step process:

1. Extract all contents of the release archive into a folder of your choice, keeping
the directory structure of the archive intact.

Example: Create the folder "C:\ubkpki_pkcs11provider" and extract the archive

into this folder.

2. Navigate to the folder of your choice and run the file MiddlewareInstaller.bat
from the command line. (This will define several system variables the
middleware relies on and that were not defined previously. Also, the batch file
calls the installers for the Visual C++ 2008 Redistributable libraries, and Visual
C++ 2012 Redistributable libraries.)

Note: Success of this step can be verified as described in Section 5.2.

3. From the GnuTLS ZIP archive (i.e., gnutls-3.2.18-w32.zip) downloaded during

the instructions shown in Section 3, copy the contents of the bin directory into
the bin directory within the gnutls_downloaded directory. From the download
location (see note), copy the opensc-pkcs11.dll file into the bin directory within
the gnutls_downloaded directory.

Note: The installer may place the file in system, System32, or SysWOW64.

Upon completion of this step, the bin directory will have the following
contents:

10/01/2014 11:30 AM <DIR> .

10/01/2014 11:30 AM <DIR> ..
09/21/2014 02:17 AM 481,456 certtool.exe
09/21/2014 02:17 AM 408,321 danetool.exe
09/21/2014 02:17 AM 352,302 gnutls-cli-debug.exe
09/21/2014 02:17 AM 406,931 gnutls-cli.exe
09/21/2014 02:17 AM 377,001 gnutls-serv.exe
09/21/2014 02:17 AM 526,518 libgcc_s_sjlj-1.dll
05/08/2014 11:46 PM 691,117 libgmp-10.dll

█ ESCRYPT GmbH – Embedded Security

GESCHÄFTSFÜHRER: DR.-ING. JAN PELZL, DR.-ING. THOMAS WOLLINGER

HANDELSREGISTER: AMTSGERICHT BOCHUM NR. 7877 · ST. -NR. 350/5714/0765
BANKVERBINDUNG: SPARKASSE KREFELD · KONTO 12 039 · BLZ 320 500 00
ECU Protection PKI Middleware Handbook 8

09/21/2014 02:17 AM 34,495 libgnutls-28.def

09/21/2014 02:17 AM 1,503,660 libgnutls-28.dll
09/22/2014 09:40 AM 148,551 libgnutls-28.exp
09/22/2014 09:40 AM 250,700 libgnutls-28.lib
09/21/2014 02:17 AM 218,888 libgnutls-xssl-0.dll
09/21/2014 02:17 AM 259 libgnutls-xssl-28.def
04/07/2014 10:25 PM 179,438 libgnutlsxx-28.dll
07/29/2014 09:36 PM 4,403,456 libhogweed-2-5.dll
09/22/2014 09:43 AM 5,856 libnettle-4-7.def
07/29/2014 09:36 PM 3,360,344 libnettle-4-7.dll
09/22/2014 09:46 AM 36,750 libnettle-4-7.exp
09/22/2014 09:46 AM 63,162 libnettle-4-7.lib
09/21/2014 02:11 AM 892,786 libp11-kit-0.dll
09/21/2014 02:17 AM 304,792 ocsptool.exe
12/04/2012 03:45 PM 1,721,856 opensc-pkcs11.dll
09/21/2014 02:17 AM 462,024 p11tool.exe
09/21/2014 02:17 AM 256,978 psktool.exe
09/21/2014 02:17 AM 268,893 srptool.exe

█ ESCRYPT GmbH – Embedded Security

GESCHÄFTSFÜHRER: DR.-ING. JAN PELZL, DR.-ING. THOMAS WOLLINGER

HANDELSREGISTER: AMTSGERICHT BOCHUM NR. 7877 · ST. -NR. 350/5714/0765
BANKVERBINDUNG: SPARKASSE KREFELD · KONTO 12 039 · BLZ 320 500 00
ECU Protection PKI Middleware Handbook 9

5 Using the Middleware

5.1 Smart Card Readers

In order to use the server and smart card slots of the middleware, a smart card and a
smart card reader are both necessary.

Note: The officially supported smart card readers are those in the Omnikey CardMan
3x21 series. The middleware requires the official drivers supplied by Omnikey. Other
smart card readers and drivers may work with the middleware, but this is not tested.
The PIN must be entered through the tool integrating the middleware during its call
to the PKCS#11 function C_Login.

Note: This PIN is statically stored in memory and used until any of the PKCS#11
functions C_Finalize, C_Logout, C_CloseSession, or C_CloseAllSessions are called.

5.2 Proxy Auto-Config

ESCRYPT’s PKI Middleware supports the Proxy Auto-Configuration technology. A

proxy auto-config (PAC) file defines proxy servers for given URLs. A PAC file contains
a JavaScript function “FindProxyForURL” which implements the selection of proxy
servers. For this purpose, the Windows library WinHttp has been integrated.

The WinHttp library provides a server-supported high-level interface to the HTTP/1.1

Internet protocol, but in this case, only the proxy auto-config functionality is used.

5.3 Integrated Windows Authentication (IWA)

Integrated Windows Authentication is a term that refers to different authentication

protocols, particularly the NTLM authentication protocol. A prerequisite to ensure the
support the NTLM v2 authentication is the so called Security Support Provider
Interface (SSPI) functionality. This interface provides an API used by Microsoft
Windows system to perform security related functions, e.g. authentication.

The combination of SSPI and NTLM provides a transparent authentication without the
need to authenticate manually for each connection.

█ ESCRYPT GmbH – Embedded Security

GESCHÄFTSFÜHRER: DR.-ING. JAN PELZL, DR.-ING. THOMAS WOLLINGER

HANDELSREGISTER: AMTSGERICHT BOCHUM NR. 7877 · ST. -NR. 350/5714/0765
BANKVERBINDUNG: SPARKASSE KREFELD · KONTO 12 039 · BLZ 320 500 00
ECU Protection PKI Middleware Handbook 10

5.4 Verifying the Middleware Setup

The correct setup of the middleware can be verified at any time after installation by
running the file MiddlewareVerifier.exe. The executable can be called as follows from
the command line:

MiddlewareVerifier.exe

Note: It is necessary to call the executable from a new command line after installing the
middleware. Otherwise the required addition of system variables during the installation
does not take effect. Also, every incorrect PIN attempt is counted in terms of the
maximum consecutive incorrect attempts for your smartcard.

Note: The PIN is entered during program execution where the characters entered are
shown as *’s.

The tool looks at the various aspects of running the middleware (e.g. system
environment variables were properly set, the smart card reader and smart card are
available, etc.) and generates an output log file.

The file name is log_YYYY_MM_DD_hh_mm_ss.dat where “YYYY” is the year, “MM” is

the month, “DD” is the day, “hh” is the hour, “mm” is the minute, and “ss” is the
second. This file can be found in the same directory in which the
MiddlewareVerifier.exe tool resides. The information can be helpful in determining
the cause of a particular issue during the installation process (e.g. not properly
installing the correct driver for the smart card reader at hand).The verification tool will
try to send a static “findKeys” SOAP message to the PKI server. If the verification tool
is able to get to the point of execution where it receives a response from upstream,
then this information will be displayed on the console. Here is an example of a
successful response is the following:

<soap:Envelope_xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/
"><soap:Body><ns2:findKeysResponse_xmlns:ns2="http://service.ubkpki.
escrypt.com/"><return>6</return><return>25</return><return>47</retur
n><return>48</return><return>58</return><return>59</return><return>6
9</return><return>70</return><return>80</return><return>81</return><
return>99</return><return>100</return><return>522</return><return>52
3</return></ns2:findKeysResponse></soap:Body></soap:Envelope>
█ ESCRYPT GmbH – Embedded Security

GESCHÄFTSFÜHRER: DR.-ING. JAN PELZL, DR.-ING. THOMAS WOLLINGER

HANDELSREGISTER: AMTSGERICHT BOCHUM NR. 7877 · ST. -NR. 350/5714/0765
BANKVERBINDUNG: SPARKASSE KREFELD · KONTO 12 039 · BLZ 320 500 00
ECU Protection PKI Middleware Handbook 11

Below is an example of a “successful” response (in the sense that the server
responded). However, there are no key handles being returned (no return tags), which
may signify that the user ID corresponding to the smart card does not have the
proper access rights for any key. Contact an admin of the PKI if that is not correct.

<soap:Envelope_xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/
"><soap:Body><ns2:findKeysResponse_xmlns:ns2="http://service.ubkpki.
escrypt.com/"/></soap:Body></soap:Envelope>

Note: Other responses from the PKI server are possible.

5.5 Error Codes

While trying to communicate with the ECU Protection PKI server, several errors can
occur that are signified by LibCURL (or cURL) error codes.

Here is the list of PKCS#11 functions that communicate with the ECU Protection PKI
server (note that for C_GetSlotList, an error does not translate into a PKCS#11 error):

 C_GetSlotList
 C_FindObjects
 C_SignFinal
 C_GetAttributeValue
 C_DeriveKey
 C_Decrypt

Here is a list of codes that that may show up during the execution of the middleware:

 0: HTTP status code greater than 400 (consult server logs).

 7: Failed to connect() to host or proxy.
 35(a): A problem occurred somewhere in the SSL/TLS handshake.
 35(b): Smart card driver is not properly installed.
 51: The remote server's SSL certificate is not OK.
 56: Failure with receiving network data.
 60: Peer certificate cannot be authenticated with known CA certificates.

█ ESCRYPT GmbH – Embedded Security

GESCHÄFTSFÜHRER: DR.-ING. JAN PELZL, DR.-ING. THOMAS WOLLINGER

HANDELSREGISTER: AMTSGERICHT BOCHUM NR. 7877 · ST. -NR. 350/5714/0765
BANKVERBINDUNG: SPARKASSE KREFELD · KONTO 12 039 · BLZ 320 500 00
ECU Protection PKI Middleware Handbook 12

6 System Variables
The batch file MiddlewareInstaller.bat will add or modify the following system
variables. Under normal circumstances, no manual configuration is necessary.
However, it may become necessary to update paths if, for instance, files are moved or
changed by the user.

6.1 Overall Configuration

The following system variables are used for the overall configuration of the
middleware:

 PATH or Path: the path needs to be appended to contain the following

directories: (deploy\lib) and (gnutls_downloaded\bin). Note that these DLLs
must not be copied into the bin directory where MiddlewareDemonstrator.exe
resides, as this will cause the execution of the middleware to fail. Also note
that the entry for axis2c must be listed before the entry for GnuTLS.
Example value:
(additional paths);C:\middleware\deploy\lib;C:\middleware\gnutls_downloaded
\bin
 AXIS2C_HOME: location at which the middleware expects to find the axis2c
configuration file (AXIS2C_HOME\axis2.xml) and the directory of axis2c
libraries (AXIS2C_HOME\lib).
Example value: C:\middleware\deploy\

6.2 TLS Communication Configuration

The following system variables are necessary for TLS communication:

Note: The tags with the parameters SERVER_CERT, KEY_FILE and SSL_PASSPHRASE all
must remain commented out in axis2.xml.

 PROVIDER_DLL: DLL that is needed for services with the smart card. If this
variable is not specified, the middleware assumes that the DLL is located in
“C:\”.
Example value: C:\middleware\gnutls_downloaded\bin\opensc-pkcs11.dll

█ ESCRYPT GmbH – Embedded Security

GESCHÄFTSFÜHRER: DR.-ING. JAN PELZL, DR.-ING. THOMAS WOLLINGER

HANDELSREGISTER: AMTSGERICHT BOCHUM NR. 7877 · ST. -NR. 350/5714/0765
BANKVERBINDUNG: SPARKASSE KREFELD · KONTO 12 039 · BLZ 320 500 00
ECU Protection PKI Middleware Handbook 13

 CURL_CA_BUNDLE: Used for handshaking with the ECU Protection PKI server
(this is its certificate). The handshaking is used to determine whether the server
is running and reachable. As an object on the smartcard, this file is also used
for normal handshaking as well.
Example value: C:\middleware\dummy\curl-ca-bundle.crt
 DUMMY_CERT: Used for handshaking with the with the ECU Protection PKI
server. This is a fake certificate. The handshaking is used to determine whether
the server is running and reachable.
Example value: C:\middleware\dummy\cert.cer
 DUMMY_KEY: Used for handshaking with the with the ECU Protection PKI
server. This is a fake certificate. The handshaking is used to determine whether
the server is running and reachable.
Example value: C:\middleware\dummy\private.key

█ ESCRYPT GmbH – Embedded Security

GESCHÄFTSFÜHRER: DR.-ING. JAN PELZL, DR.-ING. THOMAS WOLLINGER

HANDELSREGISTER: AMTSGERICHT BOCHUM NR. 7877 · ST. -NR. 350/5714/0765
BANKVERBINDUNG: SPARKASSE KREFELD · KONTO 12 039 · BLZ 320 500 00
ECU Protection PKI Middleware Handbook 14

7 Troubleshooting
The middleware does not work.

Please run the middleware verifier that should come with your middleware distribution.
It will check the correct setup of the dependencies of the middleware. If some of those
checks fail, the verifier provides additional information in its log files that may help in
isolating the problem.

I have installed a new version of the middleware and now it does not work
anymore.

Please try completely uninstalling the previous version of the middleware as there may
be a conflict due to outdated files.

█ ESCRYPT GmbH – Embedded Security

GESCHÄFTSFÜHRER: DR.-ING. JAN PELZL, DR.-ING. THOMAS WOLLINGER

HANDELSREGISTER: AMTSGERICHT BOCHUM NR. 7877 · ST. -NR. 350/5714/0765
BANKVERBINDUNG: SPARKASSE KREFELD · KONTO 12 039 · BLZ 320 500 00
ECU Protection PKI Middleware Handbook 15

8 Bibliography
ESCRYPT GmbH. (2013). ECU Protection PKI for UBK Middleware Specifications.

█ ESCRYPT GmbH – Embedded Security

GESCHÄFTSFÜHRER: DR.-ING. JAN PELZL, DR.-ING. THOMAS WOLLINGER

HANDELSREGISTER: AMTSGERICHT BOCHUM NR. 7877 · ST. -NR. 350/5714/0765
BANKVERBINDUNG: SPARKASSE KREFELD · KONTO 12 039 · BLZ 320 500 00