Newer
Older
# Plugins implementing TLS Crypt V2 for OpenVPN
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.
* 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
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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
## 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.
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
```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`