The Wirnet™ iBTS firmware comes with strongSwan and OpenVPN clients pre-installed. The credentials however need to be stored in a very specific way, described in this page.

The instructions listed on this page are applicable for the latest firmware release only. Be sure to check the instructions for older firmware releases.

The steps to make the VPN work are the following:

1. Setup a PKI (Public Key Infrastructure) to be able to produce secrets.
2. Generate secrets for the gateways to connect, in the PKCS#12 format.
3. Write the main VPN configuration file (must match the server configuration).
4. Write the ProvenCore specific configuration file.
5. Cipher the ProvenCore specific configuration file.
6. Cipher the P12 file.
7. Initialize the TrustZone.
8. Upload the ProvenCore specific ciphered configuration file to the TrustZone.
9. Upload the ciphered P12 file to the TrustZone.
10. Start the VPN client using the main VPN configuration file.

Wirnet™ iBTS embedds the TrustZone™ security feature provided by ARM microprocessors. TrustZone technology is used to run trusted boot and a trusted OS to create a Trusted Execution Environment.

The Wirnet™ iBTS trusted OS is ProvenCore, from Prove&Run.

The firmware comes with two VPN clients: strongSwan (IPSec) and OpenVPN. These clients are modified to be able to read the secrets (passwords, keys, certificates, etc.) from that hardware-backed secure storage. This means that the sensitive data is encrypted and stored in a memory that cannot be read from the userland or even the kernel. The only way the data can be extracted is through the use of the embedded VPN clients, which are compiled using a dedicated library provided by ProvenCore.

openvpn --version

All the secrets management on KerOS firmware starting with 3.1.7 version is handled by ProvenCore for OpenVPN/strongSwan.

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, 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 Wirnet™ iBTS (replace pnc_password with the password you want to use):

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

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

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

The encryption of these files is done using the pnrcipher.py (available here) tool. 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.secret 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 Wirnet™ iBTS filesystem.

Before to cipher the ipsec.secrets file, make sure to convert it in Unix format:

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-ibts.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-ibts.conf file on the gateway in /user/rootfs_rw/etc/openvpn/ folder, convert it in Unix format:

dos2unix client-openvpn-ibts.conf

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

ipsec.conf

# ipsec.conf - strongSwan IPsec configuration file
 
# basic configuration
 
config setup
 
conn vpn_conn_name
	auto=start
	leftauth=secrets
	left=your_LAN_IP
	right=your_server_hostname

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

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

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 Wirnet™ iBTS gateway in /user/rootfs_rw/etc/openvpn/ (don't forget to replace the IP address of the Wirnet™ iBTS):

scp *.enc root@192.168.0.x:/user/rootfs_rw/etc/openvpn/

Then on the Wirnet™ iBTS, 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/rootfs_rw/etc/openvpn/my_key_and_certs.p12.enc -b 10

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

uploading 4432 bytes
request completed with status: 0

To upload the Provencore config file, do:

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

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

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 Wirnet™ iBTS gateway in /user/rootfs_rw/etc/strongswan.d/ (don't forget to replace the IP address of the Wirnet™ iBTS):

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

Then on the Wirnet™ iBTS, 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/rootfs_rw/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 /user/rootfs_rw/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

The previously installed secrets can now be used by OpenVPN. The version bundled with KerOS are modified to use the Secure Storage. OpenVPN can not be used without it.

*filter
#OpenVPN ports
-A INPUT -p udp -m udp --sport 1194 -j ACCEPT
-A OUTPUT -p udp -m udp --dport 1194 -j ACCEPT
COMMIT

/etc/init.d/firewall stop

Put the OpenVPN main configuration file in /user/rootfs_rw/etc/openvpn/ and launch it with (replace with the appropriate file name):

openvpn --config /etc/openvpn/client-openvpn-ibts.conf 2>&1 | logger &

Check that OpenVPN client is well launched on your gateway:

ps | grep [o]penvpn
31342 root      4700 S    openvpn --config /etc/openvpn/client-openvpn-ibts.conf

Check with the ifconfig command that the tun interface is now active.

Once everything is working, you can add initialization scripts to enable the VPN automatically. Don't forget to enable the firewall again.

/etc/init.d/firewall stop

You can run strongSwan with the TKM daemon, first not as a daemon to check that everything works:

ipsec stop # if already running
ipsec start --nofork --daemon charon-tkm

Once everything is working, you can add initialization scripts to enable the VPN automatically. Don't forget to enable the firewall again.