Differences

This shows you the differences between two versions of the page.

--- wiki:secure_network [2018/04/18 11:58]
bdu [Initializing the TrustZone] fixed typo
+++ — (current)
@@ Line 1: / Line 1: @@
-====== VPN clients ======
-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 [[wiki:secure_network_legacy|for older firmware releases]].
-<note warning>
-The pre-installed OpenVPN and strongSwan clients have been modified to work with the secure storage only. You cannot use them without this feature.
-</note>
-===== Overview =====
-The steps to make the VPN work are the following:
-  - Setup a PKI (Public Key Infrastructure) to be able to produce secrets.
-  - Generate secrets for the gateways to connect, in the PKCS#12 format.
-  - Write the main VPN configuration file (must match the server configuration).
-  - Write the ProvenCore specific configuration file.
-  - Cipher the ProvenCore specific configuration file.
-  - Cipher the P12 file.
-  - Initialize the TrustZone.
-  - Upload the ProvenCore specific ciphered configuration file to the TrustZone.
-  - Upload the ciphered P12 file to the TrustZone.
-  - Start the VPN client using the main VPN configuration file.
-<note tip>All the ''pnr_uploader'' command return with a status. If the status is different from ''0'', this is a failure. Stop and ensure you followed all the steps before you continue.</note>
-===== General information =====
-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//.
-<note warning>
-Please ensure the server version matches the client version.
-For example, if the embedded client version is OpenVPN 2.3.14, please ensure the server uses a compatible version (if possible, the same).
-You can check the version with:
-<code bash>openvpn --version</code>
-</note>
-All the secrets management on KerOS firmware starting with 3.1.7 version is handled by //ProvenCore// for OpenVPN/strongSwan.
-<note info>
-The //TrustZone// in the Wirnet™ iBTS is composed of five blocks, each having its dedicated purpose:
-  * Block 0: ''ipsec.secrets'' config file
-  * Block 1: Root CA (not used by Kerlink software)
-  * Block 2: OpenVPN config file
-  * Block 10: Client certificate (OpenVPN)
-  * Block 20: Client certificate (IPsec)
-</note>
-===== 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, 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.0.jpg?1000|}}
-==== 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 Wirnet™ iBTS (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 ====
-<note tip>
-Your P12 file should contain your 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.
-</note>
-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'' ([[wiki:resources#other_tools|available here]]) tool. It requires the ''python3-crypto'' package on your Linux box, which can be installed with:
-<code>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>./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.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.
-<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 Wirnet™ iBTS filesystem.
-Before to cipher the ''ipsec.secrets'' file, make sure to convert it in Unix format:
-<code>
-dos2unix ipsec.secrets
-</code>
-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-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
-</code>
-Before to upload the ''client-openvpn-ibts.conf'' file on the gateway in ''/user/rootfs_rw/etc/openvpn/'' folder, convert it in Unix format:
-<code>
-dos2unix client-openvpn-ibts.conf
-</code>
-=== IPsec ===
-Here is a sample strongSwan ''ipsec.conf'' configuration file (use ''man ipsec.conf'' for more details):
-<code file 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
-</code>
-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/''
-<code>
-charon-tkm
-{
-  # Force reload of config on provencore side
-  # provencore {
-  #   reload = 1
-  # }
-  # Map strongswan algorithm identifiers to TKM identifiers.
-  dh_mapping
-  {
-    # modp2048
-= 14
-    # modp3072
-= 15
-    # modp4096
-= 16
-    # modp6144
-= 17
-    # modp8192
-= 18
-    # ecp256
-= 19
-    # ecp384
-= 20
-    # ecp521
-= 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 Wirnet™ iBTS gateway in ''/user/rootfs_rw/etc/openvpn/'' (don't forget to replace the IP address of the Wirnet™ iBTS):
-<code bash>
-scp *.enc root@192.168.0.x:/user/rootfs_rw/etc/openvpn/
-</code>
-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:
-<code bash>
-pnr_uploader -u -f /user/rootfs_rw/etc/openvpn/my_key_and_certs.p12.enc -b 10
-</code>
-Sample output (on debug probe only, not printed over SSH):
-<code>
-uploading 4432 bytes
-request completed with status: 0
-</code>
-To upload the Provencore config file, do:
-<code bash>
-pnr_uploader -u -f /user/rootfs_rw/etc/openvpn/provencore-openvpn.conf.enc -b 2
-</code>
-Sample output (on debug probe only, not printed over SSH):
-<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 Wirnet™ iBTS gateway in ''/user/rootfs_rw/etc/strongswan.d/'' (don't forget to replace the IP address of the Wirnet™ iBTS):
-<code bash>
-scp *.enc root@192.168.0.x:/user/rootfs_rw/etc/strongswan.d/
-</code>
-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:
-<code bash>
-pnr_uploader -u -f /user/rootfs_rw/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 /user/rootfs_rw/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>
-===== Running the application / using a secret =====
-The previously installed secrets can now be used by OpenVPN. The version bundled with KerOS are modified to use the Secure Storage. <fc #ff0000>OpenVPN can not be used without it.</fc>
-==== Launching OpenVPN ====
-<note tip>
-Set the appropriate [[wiki:firewall|Firewall]] rules to accept OpenVPN traffic:
-<code>
-*filter
-#OpenVPN ports
--A INPUT -p udp -m udp --sport 1194 -j ACCEPT
--A OUTPUT -p udp -m udp --dport 1194 -j ACCEPT
-COMMIT
-</code>
-Or disable the firewall (only during test phase!) with:
-<code bash>/etc/init.d/firewall stop</code>
-</note>
-Put the OpenVPN main configuration file in ''/user/rootfs_rw/etc/openvpn/'' and launch it with (replace with the appropriate file name):
-<code bash>openvpn --config /etc/openvpn/client-openvpn-ibts.conf 2>&1 | logger &</code>
-Check that OpenVPN client is well launched on your gateway:
-<code bash>
-ps | grep [o]penvpn
-root      4700 S    openvpn --config /etc/openvpn/client-openvpn-ibts.conf</code>
-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.
-==== Launching strongSwan ====
-<note tip>
-Set the appropriate [[wiki:firewall|Firewall]] rules, or disable the firewall (only during test phase!) with:
-<code bash>/etc/init.d/firewall stop</code>
-</note>
-You can run strongSwan with the TKM daemon, first not as a daemon to check that everything works:
-<code bash>
-ipsec stop # if already running
-ipsec start --nofork --daemon charon-tkm
-</code>
-Once everything is working, you can add initialization scripts to enable the VPN automatically. Don't forget to enable the firewall again.

Wirnet™ i-series

User Tools

Site Tools

Differences

Page Tools