Server Cryptographic Material#

NOTE: this document is work in progress!

This document contains a list of all cryptographic material. We’ll explain what they are used for, where they are and how they can be (re)generated.

The purpose of this document is, next to providing an overview, make it easier to create these secrets “offline” and for example deploy them using Ansible or Puppet without depending on secrets generated on the server(s).

Single Server Installation#

On a single node system there are three locations where you can find cryptographic material:

• /etc/vpn-user-portal/keys
• /var/lib/vpn-user-portal/keys
• /etc/vpn-server-node/keys

We’ll walk over those locations in turn.

The following keys are stored under /etc/vpn-user-portal/keys:

The following keys are stored under /var/lib/vpn-user-portal:

The following keys are stored under /etc/vpn-server-node/keys:

Key Details#

CA#

The CA is used for OpenVPN server and client configuration files. The CA is generated using the vpn-ca tool. This tool is installed as part of the VPN server installation. It will generate a EdDSA (Curve25519) CA. The actual command that is used to create the CA:

$ CA_KEY_TYPE=EdDSA vpn-ca -init-ca -not-after $(date -d "+10 years" +%FT%T%:z) -name "VPN CA"

You can inspect the CA certificate using e.g. openssl:

$ sudo cat /etc/vpn-user-portal/keys/ca/ca.crt | openssl x509 -noout -text

Source

OAuth Secret Key#

The OAuth key is used for protecting the OAuth API as used by the eduVPN and Let’s Connect! VPN applications.

They key format is documented here.

You can easily generate a new key using the PHP command line:

$ php -r 'echo sprintf("k7.sec.%s.%s\n", sodium_bin2base64(random_bytes(12), SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING), sodium_bin2base64(sodium_crypto_sign_secretkey(sodium_crypto_sign_keypair()), SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING));'

VPN Node Key#

The VPN Node Key is used to communicate between “Node” and “Portal”. This is not really meaningful on “Single Server” deployments, but becomes important in Multi Node deployments.

The key is 32 bytes hex encoded. You can easily generate a new key using the PHP command line:

$ php -r 'echo sodium_bin2hex(random_bytes(32))."\n";'

The file /etc/vpn-user-portal/keys/node.0.key and /etc/vpn-server-node/keys/node.key have the exact same content on a default installation.

OpenVPN TLS Crypt Key#

The OpenVPN TLS Crypt Key is used to not directly expose OpenVPN’s TLS mechanism to the Internet. The TLS Crypt Key is a shared secret among the server and all clients. Its effectiveness depends on this shared key not being public.

Every VPN Profile has its own TLS Crypt Key. The name of the file contains the profileId, e.g. tls-crypt-default.key is for the profile default.

You can generate one of these using OpenVPN’s binary:

$ /usr/sbin/openvpn --genkey tls-crypt

See openvpn(8) for more information on --genkey and --tls-crypt.

WireGuard Keys#

The WireGuard secret key can be generated using the wg tool, part of the wireguard-tools package:

$ wg genkey

As documented by wg(8), you can generate a new secret (and public) key in one go:

$ wg genkey | tee private.key | wg pubkey > public.key

Admin API#

See Admin API on how to configure and use the API.

The key is 32 bytes hex encoded. You can easily generate a new key using the PHP command line:

$ php -r 'echo sodium_bin2hex(random_bytes(32))."\n";'

Guest Access#

See Guest Access on important details regarding “Guest Access”. This will most likely not be relevant for you!

$ php -r 'echo sodium_bin2base64(random_bytes(32), SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING)."\n";'

Multi System Installation#

On multi system installations not all cryptographic material is stored on the same system any longer. For example /etc/vpn-server-node/keys is only available on the node(s) and /etc/vpn-user-portal/keys and /var/lib/vpn-user-portal/keys only on the portal. For more information on how to set this up see High Availability (HA) and Multi Node.

In addition, we’ll have some extra files to facilitate the TLS communication between portal(s) and node(s).

VPN Daemon (Portal)#

The following keys are stored under /etc/vpn-user-portal/keys:

They are used to communicate with the vpn-daemon process running on the node(s). We provide instructions on how to generate them here using the vpn-ca tool.

VPN Daemon (Node)#

The following keys are stored under /etc/ssl/vpn-daemon (on Debian / Ubuntu) or /etc/vpn-daemon on Fedora / EL.

We provide instructions on how to generate them here using the vpn-ca tool.

Node Keys#

Every node has its own node key stored in /etc/vpn-server-node/keys/node.key. On the portal the node number is encoded in the file name in order to keep the node keys apart.

The node number MUST be configured on the node in /etc/vpn-server-node/config.php and match the index of the node key on the portal, e.g. if nodeNumber is 3, the file /etc/vpn-user-portal/keys/node.3.key on the portal contains that key.

Node keys can be generated as documented under the “Single Server” section.

WireGuard Key#

Every node has its own WireGuard key in /etc/vpn-server-node/keys/wireguard.key. Contrary to OpenVPN, for WireGuard the key is per node, NOT per profile. The public component of it will be registered in the portal when vpn-maint-apply-changes is ran.

You could already put the public key under /var/lib/vpn-user-portal/keys/wireguard.N.public.key on the portal. Where N is the node number.