Setting up the VPN client

The ProvenCore manages secrets. The secrets are stored on the TrustZone in different blocks, which are designated by an integer index. Uploading secrets to a block is protected by a password (the ProvenCore password) that has to be provisioned beforehand.

To upload a secret to a block, one must first cipher it with the pnrcipher.py tool (available here), using the ProvenCore password. The application using the ProvenCore software (VPN client) is set to use each block for a different purpose, and a ciphered configuration file is needed in some specific block. The secret keys (in P12 archive form) are stored in some other blocks, told by the configuration files.

The files are processed as:

VPN client started → Main configuration file is read → Encrypted configuration file is read → Secrets are read → VPN starts

1. VPN client started: modified VPN client with ProvenCore software
2. Main configuration file: clear-text configuration file with default, non-sensitive configuration data
3. Encrypted configuration file: encrypted and stored in the TrustZone. Contains the P12 password
4. Secrets: encrypted P12 archive stored in the TrustZone
5. VPN starts: the VPN client has all the required information to initiate the VPN connection

Hereunder is an overview of the VPN configuration:

It is necessary to setup the TrustZone password before using it.

To initialize the TrustZone with a password, use the pnr_uploader tool on the gateway (replace pnc_password with the password you want to use):

# pnr_uploader -R -p pnc_password
request completed with status: 0

It is advised to follow the procedure described on the PKI management page. Otherwise, here are some basic instructions.

The P12 file should contain the host certificate and key, and the certificates up to the root of trust.

So the first step is usually to have:

• A certificate authority certificate file (named ca.crt in the example below).
• A client certificate for the gateway (named gatewayhostname.crt in the example below).
• The client certificate key for the gateway (named gatewayhostname.key in the example below).

Given these (reminder, it's only an example):

openssl pkcs12 -export -out gatewayhostname.p12 -inkey gatewayhostname.key -in gatewayhostname.crt -certfile ca.crt

This generates a P12 file on which you can set an optional password. This password, if set, has to be stored in the provencore configuration file.

Before transferring the secrets to the gateway, prepare them for upload using a Linux machine. Ubuntu 16.04 is recommended.

The encryption of these files is done using the pnrcipher.py tool (available here). It requires the python3-crypto package on your Linux box, which can be installed with:

sudo apt-get install python3-crypto

To create a ciphered PKCS#12 archive, the ProvenCore password created at the previous step must be used. Be sure to replace pnc_password in the command below:

./pnrcipher.py -f key_certs.p12 -p pnc_password

This will cipher key_certs.p12 into key_certs.p12.enc using the desired pnc_password password (please replace with the chosen password). Save the .enc file, it will be used in the next steps.

The OpenVPN ProvenCore configuration file must follow the openvpn(8) options format (see man 8 openvpn). The required ProvenCore-specific settings are the following:

provencore-openvpn.conf

#################################################
#                                               #
# Config file for ProvenCore for OpenVPN        #
#                                               #
# Comments are prefixed with '#' or ';'         #
#                                               #
#################################################
 
# Mandatory Parameters
tls-version-min 1.1
tls-version-max 1.2
pkcs12 [[INLINE]] /trustzone/securestorage/block10 "p12_password"
 
# Optional Parameters
#verify-x509-name Test-Server
#key [[INLINE]] /trustzone/securestorage/block43 "test"
#cert [[INLINE]] /trustzone/securestorage/block44
#ca [[INLINE]] /trustzone/securestorage/block45
#extra-certs [[INLINE]] /trustzone/securestorage/block46

Explanations:

• [INLINE] blocks are used to instruct the VPN client to read data from the TrustZone
• the block used for the OpenVPN keys is 10, so the virtual path to the block10 has been set
• the P12 archive password has to be set (replace p12_password with the actual password of your P12 archive, if applicable)

Before to cipher the provencore-openvpn.conf file, make sure to convert it in Unix format:

dos2unix provencore-openvpn.conf

To cipher this configuration with the password provisioned earlier (be sure to replace pnc_password with the password used at the previous steps):

./pnrcipher.py -f provencore-openvpn.conf -p pnc_password

⇒ It will create a file provencore-openvpn.conf.enc. Save this file for use in the next steps.

IPsec requires a configuration file named ipsec.secrets to work with provencore.

The configuration file must follow the ipsec.secrets(5) (see man 5 ipsec.secrets) syntax for strongSwan, and reference the P12 file as /trustzone/securestorage/block20 (the block 20 is where the IPsec keys are stored). It must also specify the P12 archive password here, and set the appropriate selector.

ipsec.secrets

"CN=myboard" : P12 /trustzone/securestorage/block20 "p12_password"

The P12 password is stored in clear text in this configuration file. Therefore, before sending it to the gateway, it will be ciphered, so it is securely stored. It will not be readable from the gateway filesystem.

dos2unix ipsec.secrets

To cipher it with the password provisioned earlier (be sure to replace pnc_password with the ProvenCore password):

./pnrcipher.py -f ipsec.secrets -p pnc_password

⇒ It will create a file ipsec.secrets.enc. Save this file for use in the next steps.

In a standard configuration file, the parameters required to connect to the OpenVPN Server, e.g.:

• line 33, OpenVPN server IP and port
• line 110 to 113, select the cryptographic cipher depending on the OpenVPN server.

client-openvpn.conf

#################################################
#                                               #
# Client-side OpenVPN 2.X config file for       #
# connecting to multi-client server.            #
#                                               #
# Comments are preceded with '#' or ';'         #
#                                               #
#################################################
 
# Specify that we are a client and that we
# will be pulling certain config file directives
# from the server.
client
 
# Use the same setting as you are using on
# the server.
# On most systems, the VPN will not function
# unless you partially or fully disable
# the firewall for the TUN/TAP interface.
;dev tap
dev tun
 
 
# Are we connecting to a TCP or
# UDP server?  Use the same setting as
# on the server.
;proto tcp
proto udp
 
# The hostname/IP and port of the server.
# You can have multiple remote entries
# to load balance between the servers.
remote OPENVPN_SERVER_IP OPENVPN_SERVER_PORT
 
# Choose a random host from the remote
# list for load-balancing.  Otherwise
# try hosts in the order specified.
;remote-random
 
# Keep trying indefinitely to resolve the
# host name of the OpenVPN server.  Very useful
# on machines which are not permanently connected
# to the internet such as laptops.
resolv-retry infinite
 
# Most clients don't need to bind to
# a specific local port number.
nobind
 
# Downgrade privileges after initialization (non-Windows only)
user nobody
group nogroup
 
# Try to preserve some state across restarts.
persist-key
persist-tun
persist-local-ip
persist-remote-ip
 
# If you are connecting through an
# HTTP proxy to reach the actual OpenVPN
# server, put the proxy server/IP and
# port number here.  See the man page
# if your proxy server requires
# authentication.
;http-proxy-retry # retry on connection failures
;http-proxy [proxy server] [proxy port #]
 
# Announce to TCP sessions running over the
# tunnel that they should limit their send packet
#sizes such that after OpenVPN has encapsulated them,
# the resulting UDP packet size that OpenVPN sends
# to its peer will not exceed max bytes.
mssfix 1200
 
# Wireless networks often produce a lot
# of duplicate packets.  Set this flag
# to silence duplicate packet warnings.
;mute-replay-warnings
 
# SSL/TLS parms.
# See the server config file for more
# description.  It's best to use
# a separate .crt/.key file pair
# for each client.  A single ca
# file can be used for all clients.
pkcs12 [[INLINE]]
 
# Verify server certificate by checking that the
# certicate has the correct key usage set.
# This is an important precaution to protect against
# a potential attack discussed here:
#  http://openvpn.net/howto.html#mitm
#
# To use this feature, you will need to generate
# your server certificates with the keyUsage set to
#   digitalSignature, keyEncipherment
# and the extendedKeyUsage to
#   serverAuth
# EasyRSA can do this for you.
remote-cert-tls server
 
# If a tls-auth key is used on the server
# then every client must also have the key.
;tls-auth ta.key 1
 
# Select a cryptographic cipher.
# This config item must be copied to
# the client config file as well.
;cipher BF-CBC        # Blowfish (default)
;cipher AES-128-CBC   # AES
;cipher DES-EDE3-CBC  # Triple-DES
cipher AES-256-CBC
 
# Enable compression on the VPN link.
# Don't enable this unless it is also
# enabled in the server config file.
comp-lzo
 
# Set log file verbosity.
verb 3
 
# Silence repeating messages
;mute 20
 
# The keepalive directive causes ping-like
# messages to be sent back and forth over
# the link so that each side knows when
# the other side has gone down.
# Ping every 10 seconds, assume that remote
# peer is down if no ping received during
# a 120 second time period.
keepalive 60 600
 
# 0 -- Strictly no calling of external programs.
# 1 -- (Default) Only call built-in executables such as  ifconfig,
# ip, route, or netsh.
# 2  --  Allow  calling  of  built-in executables and user-defined
# scripts.
# 3 -- Allow passwords to be passed to scripts  via  environmental
# variables (potentially unsafe).
script-security 2
 
# up   Executed after TCP/UDP socket bind and TUN/TAP open.
# down Executed after TCP/UDP and TUN/TAP close.
;up /etc/openvpn/update-resolv-conf
;down /etc/openvpn/update-resolv-conf

Before to upload the client-openvpn.conf file on the gateway, convert it in Unix format:

dos2unix client-openvpn.conf

Here is a sample strongSwan ipsec.conf configuration file (use man ipsec.conf for more details):

/etc/ipsec.conf

# ipsec.conf - strongSwan IPsec configuration file
 
# basic configuration
 
config setup
 
# Add connections here.
conn %default
        keyexchange=ikev2
        ike=aes128-sha256-ecp256!
        esp=aes256-sha256-ecp256!
 
conn vpn_conn_name
	auto=start
	left=%any
        leftid="C=FR, O=Kerlink, CN=klk-lpbs-060434"
        leftsubnet=your_network_subnet
	right=your_server_hostname
        rightsubnet=your_server_subnet
        rightid="C=FR, O=Kerlink, CN=vpn.hostname.tld"

Put your ipsec.conf configuration file in /etc/ipsec.conf.

Additionally, a file named tkm.conf needs to be added to /etc/strongswan.d/

/etc/strongswan.d/tkm.conf

charon-tkm
{
  # Force reload of config on provencore side
  # provencore {
  #   reload = 1
  # }
 
  # Map strongswan algorithm identifiers to TKM identifiers.
  dh_mapping
  {
    # modp2048
    14 = 14
    # modp3072
    15 = 15
    # modp4096
    16 = 16
    # modp6144
    17 = 17
    # modp8192
    18 = 18
    # ecp256
    19 = 19
    # ecp384
    20 = 20
    # ecp521
    21 = 21
  }
}

Two ciphered files have been created (key_certs.p12.enc and provencore-openvpn.conf.enc).

To upload the ciphered *.enc files on the board's TrustZone, first copy them on the gateway (don't forget to replace the IP address of the gateway):

scp *.enc root@192.168.0.x:/user/

Then on the gateway, use the pnr_uploader tool with the -u option and the appropriate block number.

To upload the p12 file, do:

pnr_uploader -u -f /user/my_key_and_certs.p12.enc -b 10

Sample output:

uploading 4432 bytes
request completed with status: 0

To upload the Provencore config file, do:

pnr_uploader -u -f /user/provencore-openvpn.conf.enc -b 2

Sample output:

uploading 816 bytes
request completed with status: 0

Two ciphered files have been created (key_certs.p12.enc and ipsec.secrets.enc).

To upload the ciphered .enc files on the board's TrustZone, first copy them on the gateway in /etc/strongswan.d/ (don't forget to replace the IP address of the gateway):

scp *.enc root@192.168.0.x:/etc/strongswan.d/

Then on the gateway, use the pnr_uploader tool with the -u option and the appropriate block number.

To upload the p12 file, do:

pnr_uploader -u -f /etc/strongswan.d/key_certs.p12.enc -b 20

Sample output (on debug probe only, not printed over SSH):

uploading 4272 bytes
request completed with status: 0

To upload the Provencore config file, do:

pnr_uploader -u -f /etc/strongswan.d/ipsec.secrets.enc --secrets

Sample output (on debug probe only, not printed over SSH):

uploading 144 bytes
request completed with status: 0

Next, start the VPN.