<commit_before>= Implicit Provisioning with an HSM

This document describes the current support for implicit provisioning with an HSM in Aktualizr and https://github.com/advancedtelematic/meta-updater[meta-updater].

== Background

In automatic provisioning, bootstrap credentials are downloaded and installed on devices to initiate the provisioning process. In implicit provisioning with an HSM, devices shall have an HSM that is pre-loaded with the requisite provisioning credentials. These credentials shall be signed by a root CA certificate which shall be uploaded to the server. The server will thus be able to authenticate a client device by verifying that the client's certificate was signed by the uploaded root CA.

== Configuration

The following items are relevant for implicit provisioning:

// tag::summary-table[]

[options=header]
|===================
| Configuration option         | Where it will come from/what it does
| Server URL                   | Read from credentials archive
| Server Root CA cert          | Read from credentials archive
| Fleet Root CA cert           | Chain of trust for a device fleet; provided by the user. Must be uploaded by user to the server.
| Fleet Root CA private key    | Key for signing device certs in the fleet; provided by user, but used only for signing. Not stored on device.
| TLS device cert              | Pre-installed in the device HSM; must be signed by Fleet Root CA private key
| TLS device key               | Pre-installed in the device HSM
| Device ID                    | Read from Common Name field of TLS device cert
| Uptane public/private key    | Automatically generated by Aktualizr
| Uptane primary serial number | Automatically generated by Aktualizr
| Primary ECU Hardware ID      | Automatically generated by Aktualizr
|===================

// end::summary-table[]

An example `.toml` configuration file can be found at link:../config/sota_hsm_prov.toml[]. This is what is used as in input to `implicit_writer` during bitbaking with meta-updater.

== Steps

// tag::full-instructions[]

. Generate a root CA private key and self-signed certificate.
+
If you do not have your own CA certificate for signing device certificates, you can generate a self-signed certificate for testing.
+
ifdef::env-github[]
You can examine the `new_server` function in link:https://github.com/advancedtelematic/ota-community-edition/blob/master/scripts/start.sh#L127[OTA Community Edition's `start.sh`] for one way of generating the cert.
endif::[]
ifndef::env-github[]
First, create a directory structure for the keys, and grab sample configurations for the certificates from the OTA Community Edition project:
+
[source,bash]
----
export SERVER_NAME=myservername
export SERVER_DIR="./${SERVER_NAME}" DEVICES_DIR="./${SERVER_NAME}/devices" CWD="${PWD}"
mkdir -p "$DEVICES_DIR" certs
for file in client.cnf device_ca.cnf server.ext client.ext server.cnf server_ca.cnf; do
  curl -o certs/$file https://raw.githubusercontent.com/advancedtelematic/ota-community-edition/master/scripts/certs/$file
done
----
+
Then, generate the key and cert using openssl on the command line:
+
[source,bash]
----
include::https://raw.githubusercontent.com/advancedtelematic/ota-community-edition/master/scripts/start.sh[tags="genserverkeys"]
----
endif::[]
+
This will create a `./${SERVER_DIR}/devices/` directory with the `ca.crt` certificate and a `ca.key` private key. Keep the private key safe and secure.
. Upload the root CA certificate to the server. To add a root CA certificate to link:https://atsgarage.com[ATS Garage], contact link:mailto:<EMAIL>[<EMAIL>].
. Generate a device certificate and key, and sign it with the root CA you just created.
+
ifdef::env-github[]
Examine the link:https://github.com/advancedtelematic/ota-community-edition/blob/master/scripts/start.sh#L89[`new_client` function in start.sh] for one way to do that.
endif::[]
ifndef::env-github[]
Generate a UUID for the device, and make a directory for it:
+
[source,bash]
----
export DEVICE_UUID=$(uuidgen | tr "[:upper:]" "[:lower:]")
export device_id=${DEVICE_ID:-${DEVICE_UUID}} device_dir="${DEVICES_DIR}/${DEVICE_UUID}"
mkdir -p "${device_dir}"
----
+
Then, generate the device certificate and key using openssl:
+
[source,bash]
----
include::https://raw.githubusercontent.com/advancedtelematic/ota-community-edition/master/scripts/start.sh[tags="genclientkeys"]
----
endif::[]
. Add the internal root CA certificate of the device gateway the device will connect to. To get the device gateway's certificate, use openssl:
+
----
export device_gateway=https://your-gateway-url # for ATS Garage, looks something like
    # a3378fca-4e4c-4a5d-b1c2-d5c5ec35b3c2.tcpgw.prod01.advancedtelematic.com
openssl s_client -connect device_gateway:8000 -servername device_gateway -showcerts | \<commit_msg>Fix: Add missing $ in HSM device gateway registration doc<commit_after>= Implicit Provisioning with an HSM

This document describes the current support for implicit provisioning with an HSM in Aktualizr and https://github.com/advancedtelematic/meta-updater[meta-updater].

== Background

In automatic provisioning, bootstrap credentials are downloaded and installed on devices to initiate the provisioning process. In implicit provisioning with an HSM, devices shall have an HSM that is pre-loaded with the requisite provisioning credentials. These credentials shall be signed by a root CA certificate which shall be uploaded to the server. The server will thus be able to authenticate a client device by verifying that the client's certificate was signed by the uploaded root CA.

== Configuration

The following items are relevant for implicit provisioning:

// tag::summary-table[]

[options=header]
|===================
| Configuration option         | Where it will come from/what it does
| Server URL                   | Read from credentials archive
| Server Root CA cert          | Read from credentials archive
| Fleet Root CA cert           | Chain of trust for a device fleet; provided by the user. Must be uploaded by user to the server.
| Fleet Root CA private key    | Key for signing device certs in the fleet; provided by user, but used only for signing. Not stored on device.
| TLS device cert              | Pre-installed in the device HSM; must be signed by Fleet Root CA private key
| TLS device key               | Pre-installed in the device HSM
| Device ID                    | Read from Common Name field of TLS device cert
| Uptane public/private key    | Automatically generated by Aktualizr
| Uptane primary serial number | Automatically generated by Aktualizr
| Primary ECU Hardware ID      | Automatically generated by Aktualizr
|===================

// end::summary-table[]

An example `.toml` configuration file can be found at link:../config/sota_hsm_prov.toml[]. This is what is used as in input to `implicit_writer` during bitbaking with meta-updater.

== Steps

// tag::full-instructions[]

. Generate a root CA private key and self-signed certificate.
+
If you do not have your own CA certificate for signing device certificates, you can generate a self-signed certificate for testing.
+
ifdef::env-github[]
You can examine the `new_server` function in link:https://github.com/advancedtelematic/ota-community-edition/blob/master/scripts/start.sh#L127[OTA Community Edition's `start.sh`] for one way of generating the cert.
endif::[]
ifndef::env-github[]
First, create a directory structure for the keys, and grab sample configurations for the certificates from the OTA Community Edition project:
+
[source,bash]
----
export SERVER_NAME=myservername
export SERVER_DIR="./${SERVER_NAME}" DEVICES_DIR="./${SERVER_NAME}/devices" CWD="${PWD}"
mkdir -p "$DEVICES_DIR" certs
for file in client.cnf device_ca.cnf server.ext client.ext server.cnf server_ca.cnf; do
  curl -o certs/$file https://raw.githubusercontent.com/advancedtelematic/ota-community-edition/master/scripts/certs/$file
done
----
+
Then, generate the key and cert using openssl on the command line:
+
[source,bash]
----
include::https://raw.githubusercontent.com/advancedtelematic/ota-community-edition/master/scripts/start.sh[tags="genserverkeys"]
----
endif::[]
+
This will create a `./${SERVER_DIR}/devices/` directory with the `ca.crt` certificate and a `ca.key` private key. Keep the private key safe and secure.
. Upload the root CA certificate to the server. To add a root CA certificate to link:https://atsgarage.com[ATS Garage], contact link:mailto:<EMAIL>[<EMAIL>].
. Generate a device certificate and key, and sign it with the root CA you just created.
+
ifdef::env-github[]
Examine the link:https://github.com/advancedtelematic/ota-community-edition/blob/master/scripts/start.sh#L89[`new_client` function in start.sh] for one way to do that.
endif::[]
ifndef::env-github[]
Generate a UUID for the device, and make a directory for it:
+
[source,bash]
----
export DEVICE_UUID=$(uuidgen | tr "[:upper:]" "[:lower:]")
export device_id=${DEVICE_ID:-${DEVICE_UUID}} device_dir="${DEVICES_DIR}/${DEVICE_UUID}"
mkdir -p "${device_dir}"
----
+
Then, generate the device certificate and key using openssl:
+
[source,bash]
----
include::https://raw.githubusercontent.com/advancedtelematic/ota-community-edition/master/scripts/start.sh[tags="genclientkeys"]
----
endif::[]
. Add the internal root CA certificate of the device gateway the device will connect to. To get the device gateway's certificate, use openssl:
+
----
export device_gateway=https://your-gateway-url # for ATS Garage, looks something like
    # a3378fca-4e4c-4a5d-b1c2-d5c5ec35b3c2.tcpgw.prod01.advancedtelematic.com
openssl s_client -connect $device_gateway:8000 -servername $device_gateway -showcerts | \
{'fraction_non_alphanumeric': 0.10354785478547855, 'fraction_numerical': 0.005569306930693069, 'mean_word_length': 4.333883388338834, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 16, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7557886', 'n_tokens_mistral': 2801, 'n_tokens_neox': 2680, 'n_words': 1062}