<commit_before># Implicit Provisioning

This document describes the current support for implicit provisioning 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, devices are to be pre-loaded with the requisite provisioning credentials.

## Configuration

The following items are relevant for implicit provisioning:

[options=header]
|===================
| Configuration option | Where it will come from
| Server URL | Written into `sota.toml` during bitbake via `implicit_writer`
| Root CA cert | Installed to `/usr/lib/sota/root.crt` during bitbake via `implicit_writer`
| TLS key/cert | Pre-installed or manually installed, e.g. with `cert_provider`
| Device ID | Read from Common Name field of TLS 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_implicit_prov.toml`. This is what is used as in input to `implicit_writer` during bitbaking with meta-updater.

## Steps

1. In meta-updater, set `SOTA_CLIENT_PROV = "aktualizr-implicit-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.<commit_msg>Better description of proper implicit provisioning.<commit_after># Implicit Provisioning

This document describes the current support for implicit provisioning 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, devices shall be pre-loaded with the requisite provisioning credentials 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
| Server URL | Written into `sota.toml` during bitbake via `implicit_writer`
| Root CA cert | Provided by the user; installed to `/usr/lib/sota/root.crt` during bitbake via `implicit_writer`; must also be uploaded by user to the server
| Root CA key | Provided by user; used only for signing
| TLS key/cert | Pre-installed or manually installed; must be signed by Root CA key
| Device ID | Read from Common Name field of TLS 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_implicit_prov.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-implicit-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 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-implicit-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.06582278481012659, 'fraction_numerical': 0.004159132007233273, 'mean_word_length': 4.8965884861407245, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, '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': '5262932', 'n_tokens_mistral': 1487, 'n_tokens_neox': 1434, 'n_words': 754}