Wirnet™ i-series

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Setting up the VPN client ======

===== Introduction =====

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 ([[wiki:common_resources#tools|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//

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

Hereunder is an overview of the VPN configuration:

{{:images:vpn_architecture_1.1.png|}}

===== Initializing the TrustZone =====

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):
<code># pnr_uploader -R -p pnc_password
request completed with status: 0</code>

<note warning>Be aware that it will delete all the previously stored secrets</note>
<note important>The ProvenCore password needs to be at least 8 characters long. Only ASCII characters are supported.</note>

===== Ciphering the .p12 =====

==== Creating the PKCS#12 file =====

It is advised to follow the procedure described on the [[ wiki:vpn_pki|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):
<code bash>
openssl pkcs12 -export -out gatewayhostname.p12 -inkey gatewayhostname.key -in gatewayhostname.crt -certfile ca.crt
</code>
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.

==== Ciphering the PKCS#12 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 ([[wiki:common_resources#tools|available here]]). It requires the ''python3-crypto'' package on your Linux box, which can be installed with:

<code bash>sudo apt-get install python3-crypto</code>

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:

<code bash>./pnrcipher.py -f key_certs.p12 -p pnc_password</code>

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.
===== ProvenCore configuration =====

==== OpenVPN ====

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

<code file 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
</code>

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)

<note info>
The P12 archive password is **NOT** the password used in steps 2 and 3 of this guide. Both passwords can be the same, but it is not mandatory.

The P12 password is stored in clear text in this configuration file. Therefore, before sending it to the gateway, it will be ciphered in the next step, so it is securely stored. It will not be readable from the Wirnet iBTS filesystem.
</note>

Before to cipher the ''provencore-openvpn.conf'' file, make sure to convert it in Unix format:
<code>
dos2unix provencore-openvpn.conf
</code>

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

<code>./pnrcipher.py -f provencore-openvpn.conf -p pnc_password</code>

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

==== IPsec ====

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. 

<code file ipsec.secrets>
"CN=myboard" : P12 /trustzone/securestorage/block20 "p12_password"
</code>

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.

<note tip>
If Windows is used to generate these files, before ciphering the ''ipsec.secrets'' file, please make sure to convert it in Unix format:
<code bash>
dos2unix ipsec.secrets
</code>
</note>


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

<code bash>
./pnrcipher.py -f ipsec.secrets -p pnc_password
</code>

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

===== VPN client configuration =====

==== OpenVPN ====

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.

<code file 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
</code>

Before to upload the ''client-openvpn.conf'' file on the gateway, convert it in Unix format:
<code>
dos2unix client-openvpn.conf
</code>

==== IPsec ====

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

<note warning>The only supported cipher suite for use with ProvenCore security module is ''aes128-sha256-ecp256'' for IKE and ''aes256-sha256-ecp256'' for ESP. Please contact Kerlink if you need a different one.</note>

<code file /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"
</code>

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

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

<code file /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
  }
}
</code>

===== Uploading ciphered secrets to the TrustZone =====

==== OpenVPN ====

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):

<code bash>
scp *.enc root@192.168.0.x:/user/
</code>

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

To upload the p12 file, do:
<code bash>
pnr_uploader -u -f /user/my_key_and_certs.p12.enc -b 10
</code>
Sample output:
<code>
uploading 4432 bytes
request completed with status: 0
</code>

To upload the Provencore config file, do:
<code bash>
pnr_uploader -u -f /user/provencore-openvpn.conf.enc -b 2
</code>
Sample output:
<code>
uploading 816 bytes
request completed with status: 0
</code>

==== IPsec ====

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):

<code bash>
scp *.enc root@192.168.0.x:/etc/strongswan.d/
</code>

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

To upload the p12 file, do:
<code bash>
pnr_uploader -u -f /etc/strongswan.d/key_certs.p12.enc -b 20
</code>
Sample output (on debug probe only, not printed over SSH):
<code>
uploading 4272 bytes
request completed with status: 0
</code>

To upload the Provencore config file, do:
<code bash>
pnr_uploader -u -f /etc/strongswan.d/ipsec.secrets.enc --secrets
</code>
Sample output (on debug probe only, not printed over SSH):
<code>
uploading 144 bytes
request completed with status: 0
</code>

===== Next =====

Next, [[ wiki:vpn_start|start the VPN]].
Wirnet™ i-series

User Tools

Site Tools

Page Tools
