Chapter 5

How it works...

We configured OpenVPN to make use of a PKCS#11 provider:

pkcs11-providers /usr/lib64/libeTPkcs11.so

Then we enabled the management interface. This allows us to retrieve (public) information from the hardware token via the management interface. Note that if the certificate on the hardware token is marked private, then this recipe would fail. See the recipe Private method for getting a PKCS#11 certificate later in this chapter for details.

While this example may not have much practical use, it does show how OpenVPN can be controlled using the management interface. It is expected that both the management interface and the PKCS#11 interface will become more important in future versions

of OpenVPN.

See also

The next recipe, Selecting a PKCS#11 certificate using the management interface, explains how to use the management interface to select and use a PKCS#11 certificate in OpenVPN.

Selecting a PKCS#11 certificate using the management interface

This recipe will demonstrate how the management interface can be used to select a certificate and a corresponding private key from a hardware token. This recipe is a continuation of the previous recipe. Although no particular network layout is required, we have to set up a working VPN connection before we can fully use the management interface.

Getting ready

We use the following network layout:

139

Two-factor Authentication with PKCS#11

Keep the hardware token from the first recipe at hand. For this recipe, the server computer was running CentOS 5 Linux and OpenVPN 2.1.1. The client was running Fedora 12 Linux and OpenVPN 2.1.1. Keep the server configuration file basic-udp-server.conf from the Chapter 2 recipe Server-side routing at hand.

How to do it...

1.Start the server using the configuration file basic-udp-server.conf:

[root@server]# openvpn --config basic-udp-server.conf

2.Next, create the client configuration file:

client proto udp

remote openvpnserver.example.com port 1194

dev tun nobind

ca /etc/openvpn/cookbook/ca.crt tls-auth /etc/openvpn/cookbook/ta.key 1

ns-cert-type server

pkcs11-providers /usr/lib64/libeTPkcs11.so pkcs11-id-management

management 127.0.0.1 23000 stdin management-query-passwords management-hold management-signal management-forget-disconnect

Save it as example5-5-client.conf.

3.Start the client:

[root@client]# openvpn --config example5-5-client.conf

… OpenVPN 2.1.1 x86_64-redhat-linux-gnu [SSL] [LZO2] [EPOLL] [PKCS11] built on Jan 5 2010

Enter Management Password: [choose a password]

After the management password is entered, the OpenVPN client stops and waits for a connection on the management interface.

140

Chapter 5

4.Next, we use telnet to connect to the management interface:

[client]$ telnet 127.0.0.1 23000

Connected to 127.0.0.1. Escape character is '^]'.

ENTER PASSWORD: [enter the management password] SUCCESS: password is correct

>INFO:OpenVPN Management Interface Version 1 -- type 'help' for more info

>HOLD:Waiting for hold release

5.The OpenVPN client is now waiting for the hold release command before continuing:

hold release

SUCCESS: hold release succeeded

6.Next, the OpenVPN client is asking for the serialized PKCS#11 ID to use:

>NEED-STR:Need 'pkcs11-id-request' string MSG:Please specify PKCS#11 id to use

needstr pkcs11-id-request 'Aladdin\x20Ltd\x2E/eToken/001a01a9/Cookbook/20100703'

SUCCESS: 'pkcs11-id-request' needstr-string entered, but not yet verified

And finally, the OpenVPN client is asking for the password of the hardware token:

>PASSWORD:Need 'Cookbook token' password

password 'Cookbook token' [hardware token password]

SUCCESS: 'Cookbook token' password entered, but not yet verified

After this, the VPN connection is established.

How it works...

We configured OpenVPN to make use of a PKCS#11 provider and to use the management interface to manage the PKCS#11 identities:

pkcs11-providers /usr/lib64/libeTPkcs11.so pkcs11-id-management

141

Two-factor Authentication with PKCS#11

We also configured OpenVPN to set up a management interface on port 23000 on localhost and to use this interface to query for passwords (management-query-passwords), to

start and stop the client (management-hold), to send a signal to the client when the user disconnects from the management interface (management-signal), and to forget all cached passwords when the user disconnects (management-forget-disconnect):

management 127.0.0.1 23000 stdin management-query-passwords management-hold management-signal management-forget-disconnect

When the OpenVPN client starts, it waits for a user to connect on the management interface before continuing. After the user logs in on the client interface and types hold release, OpenVPN next queries for the pkcs11-id to use, which the user needs to supply using the needstr command. If the right pkcs11-id is entered, the user is requested to type the password for the hardware token on which the pkcs11-id is found. For this, the password command is used.

This example shows that OpenVPN can be controlled using the management interface. The management interface and the PKCS#11 interface will become more important in future versions of OpenVPN.

There's more...

The design philosophy behind the management interface is that the third-party managers can be written that control the OpenVPN client. Current manager applications (for example, the OpenVPN GUI application on Windows) parse the output of the OpenVPN client and supply responses using the system standard input and output mechanisms. This does not allow for much interactive control, which led to the development of the management interface. Most of the GUI tools on Linux, such as the OpenVPN plugin for the Gnome Network Manager, already make use of the management interface. The Windows OpenVPN GUI is being rewritten and it will also make use of the management interface.

Generating a key on the hardware token

In this recipe, we will generate a private key on the hardware token itself, after which we generate a certificate to match this private key. For security-sensitive purposes, this is one of the safest ways to generate a certificates/private-key pair, as the private key cannot be copied off the hardware token. It also means that if the hardware token fails or is stolen then the private key and corresponding certificate are lost.

142

Chapter 5

Getting ready

Keep the hardware token from the previous recipe at hand. In this recipe the computer used was running Fedora 12 Linux, pcsc-lite 1.5.2, opensc-0.11.12, engine_pkcs11 0.1.4 and PKI Client 5.00, but the commands used should work with other PKCS#11 libraries as well. The engine_pkcs11 library is the "engine" interface between the openssl command and a PKCS#11 driver. This package can be found on the OpenSC project website for Linux, Windows, and Mac OS X.

How to do it...

The easy-rsa scripts that are supplied with OpenVPN 2.1 support PKCS#11 management, but it requires some modification to the vars and openssl.cnf files.

1.First we modify the vars file:

export EASY_RSA=/etc/openvpn/cookbook export OPENSSL="openssl"

export KEY_CONFIG=`$EASY_RSA/whichopensslcnf $EASY_RSA` export KEY_DIR="$EASY_RSA/keys"

export PKCS11TOOL="pkcs11-tool"

export PKCS11_MODULE_PATH="/usr/lib64/libeTPkcs11.so" export PKCS11_PIN="[hardware token PIN]"

export KEY_SIZE=1024 export CA_EXPIRE=3650 export KEY_EXPIRE=1000 export KEY_COUNTRY="NL" export KEY_PROVINCE= export KEY_CITY=

export KEY_ORG="Cookbook"

export KEY_EMAIL="openvpn-ca@cookbook.example.com"

Adjust the settings (KEY_ORG, KEY_EMAIL) to reflect your organization.

2.After this we source the vars file:

$ . ./vars

3.Next we modify the openssl.cnf file that is supplied with the easy-rsa scripts. Uncomment the line 'pkcs11 = pkcs11_section' line and adjust the line 'dynamic_path' to reflect the location of the 'engine_pkcs11.so' file on your system. This library acts as the "glue" between the 'openssl' command and a PKCS#11 driver. The output below shows the location of the 'engine_pkcs11.so' file on 64-bit Fedora 12 Linux:

pkcs11 = pkcs11_section

dynamic_path = /usr/lib64/openssl/engines/engine_pkcs11.so`

143

Two-factor Authentication with PKCS#11

On Windows this file is part of the OpenSC 'SCB' package and is named

'engine_pkcs11.dll'.

4.After this we start the 'build-key' script with extra command-line parameters: $ ./build-key --pkcs11 /usr/lib64/libeTPkcs11.so \

0 20100705 "Onboard" client5

The output of the command is quite long and is therefore cut into parts. First a private key is generated on the token:

User PIN: Generating key pair on PKCS#11 token...

Then the certificate creation process is started using a pkcs11 engine. This is very similar to the certificate generation process from the first recipe of Chapter 2,

Client-server IP-only Networks, hence it is abbreviated:

engine "pkcs11" set.

[…]

The Subject's Distinguished Name is as follows countryName :PRINTABLE:'NL' organizationName :PRINTABLE:'Cookbook' commonName :PRINTABLE:'client5'

emailAddress :IA5STRING:'openvpn-ca@cookbook.example.com' Certificate is to be certified until Mar 30 18:16:33 2013 GMT (1000 days)

Sign the certificate? [y/n]:y

1 out of 1 certificate requests certified, commit? [y/n]y Write out database with 1 new entries

Data Base Updated

And finally the certificate that was generated is copied back to the hardware token:

Generated certificate:

Certificate Object, type = X.509 cert label: Onboard

ID: 20100705

The certificate and private key pair are now ready for use with OpenVPN.

144

Chapter 5

5.We can retrieve the serialized ID using:

$ openvpn --show-pkcs11-ids /usr/lib64/libeTPkcs11.so

Certificate

DN: /C=NL/O=Cookbook/CN=client5/… Serial: 09

Serialized id: Aladdin\x20Ltd\x2E/eToken/001a01a9/Cookbook/20100705

How it works...

The following command specifies that a PKCS#11 module should be used to generate the private key for the certificate:

$ ./build-key --pkcs11 /usr/lib64/libeTPkcs11.so \ 0 20100705 "Onboard" client5

The parameters to the --pkcs11 command-line options are (in order):

Library: The location of the PKCS#11 library to use.

Slot: The slot number of the hardware token. This is usually '0' unless multiple hardware tokens are plugged in at the same time.

ID: The ID of the private key and certificate on the token. This is the same ID that shows up at the end of the serialized id output in the recipe "Getting a hardware token ID" earlier in this chapter.

Label: The label of the private key and certificate on the token. This label is not really used by OpenVPN but it is useful to track different certificate/private key pairs on a token.

The last parameter client5 is the name of the client certificate to generate, similar to the

"normal" command:

$ ./build-key client5

With these parameters the build-key command first generates a private key on the token (and corresponding public key, but this is not used by OpenVPN). After that the normal certificate generation process is started using an openssl PKCS#11 engine. The engine_pkcs11.so library is used for this. When the certificate is signed by the Certificate Authority (CA) the certificate is converted to DER format and copied back to the hardware token. The certificate is now ready to be used by OpenVPN.

145