====== 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:resources: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): # pnr_uploader -R -p pnc_password request completed with status: 0 Be aware that it will delete all the previously stored secrets The ProvenCore password needs to be at least 8 characters long. Only ASCII characters are supported. ===== Ciphering the .p12 ===== ==== Creating the PKCS#12 file ===== It is advised to follow the procedure described on the [[ wiki:network_mana: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): 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. ==== 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:resources:resources#tools|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. ===== 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: ################################################# # # # 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) 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. 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 ==== 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. "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. If Windows is used to generate these files, before ciphering the ''ipsec.secrets'' file, please 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. ===== 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. ################################################# # # # 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 ==== IPsec ==== Here is a sample strongSwan ''ipsec.conf'' configuration file (use ''man ipsec.conf'' for more details): 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. # 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/'' 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 } } ===== 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): 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 ==== 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): 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 ===== Next, [[ wiki:network_mana:vpn_start|start the VPN]].