TLS on-device key generation

Browse source code on GitHub

Overview

This sample shows how a device gets a client certificate for a private key that never leaves the device. It uses the TLS credentials on-device key generation API.

The sample does the following:

  1. Generates an ECDSA P-256 key for the security tag CONFIG_NET_SAMPLE_SEC_TAG, if the security tag has no key yet. The key is persistent, so a restart uses the same key.

  2. Prints the public key and a Certificate Signing Request (CSR) in PEM format.

  3. Waits until the device certificate and the CA certificate are added for the same security tag with the TLS credentials shell.

  4. Connects to a TLS server that requires a client certificate, sends a message and prints the response.

A certificate authority (CA) signs the CSR. In this sample, the CA and the server run on the host with OpenSSL.

Requirements

Building and Running

Build the sample:

west build -b native_sim samples/net/sockets/tls_keygen

Create the CA and the server certificate on the host. The common name of the server certificate must match CONFIG_NET_SAMPLE_SERVER_HOSTNAME:

openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
        -keyout ca.key -out ca.pem -subj "/CN=Test CA" -days 30
openssl req -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
        -keyout server.key -out server.csr -subj "/CN=localhost"
openssl x509 -req -in server.csr -CA ca.pem -CAkey ca.key -out server.pem -days 30

Run the sample. The shell is on the standard input and output:

./build/zephyr/zephyr.exe -uart_stdinout

The sample prints the CSR:

<inf> tls_keygen_sample: Generating a key for sec tag 42
-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----
-----BEGIN CERTIFICATE REQUEST-----
...
-----END CERTIFICATE REQUEST-----
<inf> tls_keygen_sample: Waiting for the certificates. Add them in the shell:
<inf> tls_keygen_sample:   cred add 42 CLIENT_CERT DEFAULT BIN <base64 DER>
<inf> tls_keygen_sample:   cred add 42 CA_CERT DEFAULT BIN <base64 DER>

Copy the CSR, including the BEGIN and END lines, to device.csr on the host, and sign it with the CA:

openssl x509 -req -in device.csr -CA ca.pem -CAkey ca.key -out device.pem -days 30

Start the TLS server on the host. -Verify 1 requires a client certificate, and -rev sends back each received line in reverse order:

openssl s_server -accept 4433 -cert server.pem -key server.key -CAfile ca.pem -Verify 1 -rev

Print the device certificate and the CA certificate as Base64-encoded DER:

openssl x509 -in device.pem -outform der | openssl base64 -A
openssl x509 -in ca.pem -outform der | openssl base64 -A

Add them in the shell of the sample:

uart:~$ cred add 42 CLIENT_CERT DEFAULT BIN <device certificate>
uart:~$ cred add 42 CA_CERT DEFAULT BIN <CA certificate>

The shell reports the device certificate as type SERVER_CERT. This is expected: CLIENT_CERT and SERVER_CERT are the same credential type, TLS_CREDENTIAL_PUBLIC_CERTIFICATE.

The sample then connects to the server:

<inf> tls_keygen_sample: Connecting to 127.0.0.1:4433
<inf> tls_keygen_sample: TLS handshake done
<inf> tls_keygen_sample: Received: ryhpeZ morf olleH
<inf> tls_keygen_sample: Done

The server prints Peer certificate: CN = zephyr-device and Verification: OK.

The key and the certificates are kept in flash.bin in the current directory, so the next run connects without new certificates. To start again with a new key, delete flash.bin.

See also

TLS credentials management
TLS credentials on-device key generation
Socket options for TLS