Plugins implementing TLS Crypt V2 for OpenVPN

Description

This repository contains multiple plugins each implementing the TLS Crypt V2 mechanism in a HSM or Hardware Token. To use any of the plugins, it is required to use a custom OpenVPN version to add a plugin hook for performing TLS Crypt V2 operations.

Dependencies

Runtime:

• PKCS11: openssl, a PKCS#11 library
• YubiKey: openssl, yubico-c, yubikey
• JavaCard: pcsclite
• OpenVPN: See openvpn_patched/INSTALL

Build:

• PKCS11: cmake
• YubiKey: cmake, json-c
• JavaCard: cmake, ant
• OpenVPN: See openvpn_patched/INSTALL

Usage

Add the plugin to your server config and add arguments depending on the plugin. Order of arguments matters!

• SoftHSM: Path to SoftHSM2 Library (e.g. /usr/lib/pkcs11/libsofthsm2.so) and User Pin
• YubiKey: Slot number to use on the YubiKey (e.g. 1 or 2) and access code for the YubiKey (if unknown / not set: 0)
• Smartcard: No arguments required

Build

First download all git submodules with

git submodule update --init

Custom OpenVPN

cd openvpn_patched
autoreconf -i -v -f
./configure
make

PKCS#11 plugin

cd PKCS11KeyWrappingLibrary
mkdir build && cd build
cmake ..
cmake --build . --target PKCS11KeyWrappingLibrary

YubiKey plugin

cd YubikeyKeyDerivationLibrary
mkdir build && cd build
cmake ..
cmake --build . --target YubikeyKeyManagementLib

JavaCard plugin

Build JavaCard Applet. Requires setting JAVA_HOME environmental variable to path of Java 8. Java 8 path is something like /usr/lib/jvm/java-8-openjdk/.

cd SmartcardKeyWrapping/Applet/
export JAVA_HOME=<java-8-path>
# Build Applet
ant build
# Install Applet onto card, requires a smart card to be inserted into the computer
ant install 
# If test desired
ant test

Build JavaCard plugin with:

cd SmartcardKeyWrapping/Library/
mkdir build && cd build
cmake ..
cmake --build . --target SmartcardKeyWrappingLibrary

The project also contains a utility for importing an existing server key file onto the JavaCard. The app requires OpenSSL. Usage with ./ImportKeyFile <path_to_server_key_file>

cmake --build . --target ImportKeyFile

Test

Key Generation

PKCS#11

A sample config using SoftHSM is provided. To test it first build OpenVPN and the PKCS#11 Plugin. Testing requires installing SoftHSM2 and setting up a new token, with softhsm2-util --init-token --slot 0 --label <name> --pin <user-pin> --so-pin <so-pin>. The user-pin should be set to 1234. First generate server and client key:

cd TestEnvironment/Server_openvpn/
./openvpn --genkey tls-crypt-v2-server --plugin ./plugins/libPKCS11KeyWrappingLibrary.so "/usr/lib/pkcs11/libsofthsm2.so" <user-pin>
./openvpn --genkey tls-crypt-v2-client ../Client_openvpn/secrets/softhsm_client.key --plugin ./plugins/libPKCS11KeyWrappingLibrary.so "/usr/lib/pkcs11/libsofthsm2.so" <user-pin>

YubiKey

Testing changes the config of the YubiKey. Beware of data loss! Slot can either be 1,2 or 3. With 3 both slots are used for increased security.

cd TestEnvironment/Server_openvpn/
# Generate Server Key; <slot> sets the slot which should be configured, usually 2. Removes whatever is stored in the slot. <acc_code> is usually 0
./openvpn --genkey tls-crypt-v2-server --plugin ./plugins/libYubikeyKeyManagementLib.so <slot> <acc_code>
# Generate Client Key
./openvpn --genkey tls-crypt-v2-client ../Client_openvpn/secrets/yubikey_client.key --plugin ./plugins/libYubikeyKeyManagementLib.so <slot> <acc_code>

JavaCard

cd TestEnvironment/Server_openvpn/
# Generate Server Key
./openvpn --genkey tls-crypt-v2-server --plugin ./plugins/libSmartcardKeyWrappingLibrary.so
# Generate Client Key
./openvpn --genkey tls-crypt-v2-client ../Client_openvpn/secrets/smartcard_client.key --plugin ./plugins/libSmartcardKeyWrappingLibrary.so

Runtime Test

Run server from TestEnvironment/Server_openvpn/ with:

sudo ./openvpn --config configs/<plugin-server-conf>

Options for plugin-server-conf are yubikey_server.conf, softhsm_server.conf, smartcard_server.conf Then run client from TestEnvironment/Client_openvpn/ with:

sudo ./openvpn --config configs/<plugin-client-conf>

Options for plugin-client-conf are yubikey_client.conf, softhsm_client.conf, smartcard_client.conf