# 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
```sh
git submodule update --init
```

### Custom OpenVPN

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

### PKCS#11 plugin

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

### YubiKey plugin

```sh
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/`.

```sh
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:

```sh
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>`

```sh
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:

```sh
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.

```sh
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

```sh
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:

```sh
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:

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

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