<commit_before><commit_msg>Rough draft of new HSM provisioning doc.<commit_after># Implicit Provisioning with an HSM

This document describes the current support for implicit provisioning with an HSM in Aktualizr and 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:

[options=header]
|===================
| Configuration option         | Where it will come from/what it does
| Server URL                   | Written into `sota.toml` during bitbake via `implicit_writer`.
| Server Root CA cert          | Location of cert written into `sota.toml` during bitbake via `implicit_writer`. See `tls_cacert_path` option in `sota.toml`.
| 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
|===================

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

## Steps

1. Generate a root CA private key and self-signed certificate.
1. Upload the root CA certificate to the server.
1. In meta-updater, set `SOTA_CLIENT_PROV = "aktualizr-hsm-test-prov"`. Currently, you will also need to set `SOTA_PACKED_CREDENTIALS` to a provisioning credentials zip file.
1. Build a standard image using bitbake.
1. Boot the image.
1. Sign the client device certificate with the root private key and install it in the HSM on the client device.
1. The server shall provide its own internal root CA certificate to client device. Currently, `implicit_writer` is used to read the server's root CA from the `SOTA_PACKED_CREDENTIALS` and install it on the device during bitbake.
1. The server shall authenticate the client device by verifying that the client's certificate was signed by the your root CA private key. (The server uses the root CA certificate that it was given in step 2 to do so.)
1. The client device authenticates the server by verifying that the server's certificate was signed by the server's internal root CA private key. (The client device uses the server's internal root CA certificate that it was given in step 7 to do so.)

## Simulated implicit provisioning with `cert_provider`

Implicit provisioning can be simulated with `cert_provider` without need for the user to create a root CA. `cert_provider` uses the existing autoprovisioning mechanisms to pre-install a certificate and key on the device.

1. In meta-updater, set `SOTA_CLIENT_PROV = "aktualizr-hsm-test-prov"`. Currently, you will also need to set `SOTA_PACKED_CREDENTIALS` to provisioning credentials zip file.
1. Build a standard image using bitbake.
1. Boot the image.
1. Optionally, verify that Aktualizr is not provisioning and that the device is not visible in the Garage.
1. Load credentials onto the device, for example with `cert_provider` from the Aktualizr repo: `cert_provider -c credentials.zip -t <device> -d /var/sota`
1. Verify that Aktualizr provisions correctly with the server using the expected Device ID.
{'fraction_non_alphanumeric': 0.056158110388045315, 'fraction_numerical': 0.0040973728609303445, 'mean_word_length': 4.0795593635250915, 'pattern_counts': {'":': 0, '<': 4, '<?xml version=': 0, '>': 4, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 1, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3712956', 'n_tokens_mistral': 1089, 'n_tokens_neox': 1049, 'n_words': 593}