demos/linux/tls_client/tls_client_demo.rst - a71ch-crypto-support - Git at Google

 ..
     Copyright 2019,2020 NXP


 .. _tls-client-example:

 ========================================================
  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 (:numref:`tls-client-using-a71ch`) highlights the changes in case one uses an A71CH secure element.


 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:

 1. **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.

 2. **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 :numref:`credential-prep` to :numref:`startup-the-server` are
 identical for the two demo flavours.

 .. _credential-prep:

 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.

 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:

 provisionTlsClient.py
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 .. include:: scripts/doc/provisionTlsClient.rst.txt


 Server side preparation
 ========================================================

 .. note::

     The Host SW package comes bundled with the required server credentials.

 Ensure the default server credentials or those created under (:numref:`credential-prep`) are available
 on the server platform.

 .. _startup-the-server:

 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

 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.

 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

 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.


 .. _tls-client-using-a71ch:

 TLS client example using A71CH
 ========================================================

 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

 Secure Element preparation (client side)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 Specify an additional option ``--subsystem a71ch``::

     > python3 provisionTlsClient.py --key_type ecc --subsystem a71ch

 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
	..
	Copyright 2019,2020 NXP


	.. _tls-client-example:

	========================================================
	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 (:numref:`tls-client-using-a71ch`) highlights the changes in case one uses an A71CH secure element.


	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:

	1. 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.

	2. 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 :numref:`credential-prep` to :numref:`startup-the-server` are
	identical for the two demo flavours.

	.. _credential-prep:

	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.

	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:

	provisionTlsClient.py
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	.. include:: scripts/doc/provisionTlsClient.rst.txt


	Server side preparation
	========================================================

	.. note::

	The Host SW package comes bundled with the required server credentials.

	Ensure the default server credentials or those created under (:numref:`credential-prep`) are available
	on the server platform.

	.. _startup-the-server:

	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

	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.

	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

	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.


	.. _tls-client-using-a71ch:

	TLS client example using A71CH
	========================================================

	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

	Secure Element preparation (client side)
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	Specify an additional option ``--subsystem a71ch``::

	> python3 provisionTlsClient.py --key_type ecc --subsystem a71ch

	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