5.4.2. OpenSSL Engine: TLS Client example for iMX/Rpi3¶
DocRevision : 0.94
Date : 2020-01-14
This section explains how to set-up a TLS link using the SE050 OpenSSL Engine on the client side. A note at the bottom of this page (Section 5.4.2.7) highlights the changes in case one uses an A71CH secure element.
5.4.2.1. Summary¶
The TLS demo demonstrates setting up a mutually authenticated and encrypted link between a client and a server system. The keypair used to identify the client is stored in the Secure Element. The keypair used to identify the server is simply available as a pem file.
The public keys associated with the respective key pairs are contained in respectively a client and a server certificate.
The CA is a self-signed certificate. The same CA is used to sign client and server certificate.
One can choose the keymaterial (CA, Client and Server) to be either RSA (4096 CA - 2048 client/server) or EC (prime256v1).
The TLS demo comes in two flavours:
Flavour-A: The standard OpenSSL tools s_server and s_client are used to set-up and demonstrate the TLS link. The certificates used are simply stored on the file system of the host. The client uses the keypair stored inside the SE050.
Flavour-B: A TLS client program - included in source code (tlsSe050Client.cpp) - retrieves the client certificate from the SE050 and uses the keypair stored inside the SE050. It establishes a TLS connection with the server process s_server.
Steps in Section 5.4.2.2 to Section 5.4.2.5 are identical for the two demo flavours.
5.4.2.2. Credential preparation (execute once) [Optional]¶
> cd demos/linux/tls_client
> ./scripts/createTlsCredentials_Optional.sh <ECC|RSA>
Note
The Host SW package comes bundled with the required credentials. The createTlsCredentials_Optional.sh script will re-create equivalent credentials (but with new/different keypairs)
The script creates all demo required client and server credentials on the client platform. One must transfer the server credentials to the server platform.
5.4.2.3. Secure Element preparation (client side)¶
For the purpose of the demo one MUST inject the TLS client key pair and certificate into the Secure Element and create a reference pem file referring to the provisioned key pair:
> cd demos/linux/tls_client/scripts
> python3 provisionTlsClient.py --key_type <ecc|rsa>
Further details on using these scripts can be found in the following:
5.4.2.3.1. provisionTlsClient.py¶
- usage: provisionTlsClient.py [-h] –key_type KEY_TYPE
[–connection_data CONNECTION_DATA] [–connection_type CONNECTION_TYPE] [–subsystem SUBSYSTEM]
Provision attached secure element with ECC/RSA keys
- Preconditions:
Secure element attached
Virtual environment should be activated (not for iMX platform. Refer ssscli installation steps: Plug & Trust MW, Section 8.3 Steps needed before running ssscli tool)
- Postconditions:
Key pair injected on id referred by KEYPAIR_INDEX_CLIENT_PRIVATE variable
Ref pem created
Client certificate injected on id referred by CERTIFICATE_INDEX variable.
- optional arguments:
- -h, --help
show this help message and exit
- required arguments:
- --key_type KEY_TYPE
Supported key types =>
ecc
,rsa
- optional arguments:
- --connection_data CONNECTION_DATA
Parameter to connect to SE => eg.
COM3
,127.0.0.1:8050
,none
. Default:none
- --connection_type CONNECTION_TYPE
Supported connection types =>
t1oi2c
,sci2c
,vcom
,jrcpv1
,jrcpv2
,pcsc
. Default:t1oi2c
- --subsystem SUBSYSTEM
Supported subsystem =>
se050
,a71ch
. Default:se050
Example invocation:
python provisionTlsClient.py --key_type ecc
python provisionTlsClient.py --key_type ecc --connection_data 169.254.0.1:8050
python provisionTlsClient.py --key_type rsa --connection_data 127.0.0.1:8050 --connection_type jrcpv2
python provisionTlsClient.py --key_type rsa --connection_data COM3
python provisionTlsClient.py --key_type ecc --subsystem a71ch
5.4.2.4. Server side preparation¶
Note
The Host SW package comes bundled with the required server credentials.
Ensure the default server credentials or those created under (Section 5.4.2.2) are available on the server platform.
5.4.2.5. Start up the server¶
Note
The server can run e.g. on a PC. The server must be reacheable over the TCP/IP network for the Client. Choose either a server using EC based credentials or a server using RSA based credentials.
Execute the following command on the server platform to use the EC based server credentials, make a note on the IP address of the server:
> cd demos/linux/tls_client/scripts
> ./tlsServer.sh <ECDHE|ECDHE_SHA256|max>
Execute the following command on the server platform to use the RSA based server credentials, make a note on the IP address of the server:
> cd demos/linux/tls_client/scripts
> ./tlsServer.sh RSA
5.4.2.6. Establish a TLS link from the client to the server¶
The client process establishing the TLS connection comes in two flavours: either s_client or a program provided in source code (tlsSe050Client.cpp). Invoke either example through a bash shell script.
5.4.2.6.1. Using s_client¶
Invoke the script using the IP address of the server as the first argument and ECDHE or ECDHE_SHA256 as the second argument (ECDHE corresponding to ECDH ephemeral) when connecting to a server using EC based credentials:
> ./tlsSeClient.sh <server-IP-address> <ECDHE|ECDHE_256>
Invoke the script using the IP address of the server as the first argument and RSA as the second argument when connecting to a server using RSA based credentials:
> ./tlsSeClient.sh <server-IP-address> RSA
In case OpenSSL 1.1.1 is available on both Client (i.MX or Raspberry Pi) and Server side, it’s possible to request the usage of the TLS1.3 protocol (by default TLS1.2 is used). This is achieved by setting the environment variable REQ_TLS to tls1_3:
> REQ_TLS=tls1_3 ./tlsSeClient.sh <server-IP-address> ECDHE
5.4.2.6.2. Using tlsSe050Client.cpp¶
First compile the client program. Ensure all required SE050 specific libraries and header files have been installed on the linux system. By default this example links to static libraries:
> cd demos/linux/tls_client/build
> cmake ../.
> cmake --build .
Invoke the script using the IP address of the server as argument:
> ./tlsExtendedSeClient.sh <server-IP-address> <EC|RSA>
Note
The environment variable REQ_TLS is not applicable to this example. In case OpenSSL 1.1.1 is available on the client, the actual TLS protocol version used will be negotiated to the highest version supported by both client and server. Otherwise TLS1.2 will be used.
5.4.2.7. TLS client example using A71CH¶
5.4.2.7.1. Introduction¶
The TLS client example can also be used in combination with an A71CH secure element (in EC mode only). The following steps are different:
- secure element preparation
- client program invocation
5.4.2.7.2. Secure Element preparation (client side)¶
Specify an additional option --subsystem a71ch
:
> python3 provisionTlsClient.py --key_type ecc --subsystem a71ch
5.4.2.7.3. Invocation of client program¶
Set the environment variable REQ_SE
to a71ch
when invoking the client program:
> REQ_SE=a71ch ./tlsSeClient.sh 192.168.1.190 ECDHE
> ... or ...
> REQ_SE=a71ch ./tlsExtendedSeClient.sh 192.168.1.190 EC