# KeyStore structure: support for multiple public keys

## What is wolfBoot KeyStore

KeyStore is the mechanism used by wolfBoot to store all the public keys used for
authenticating the signature of current firmware and updates.

wolfBoot's key generation tool can be used to generate one or more keys. By default,
when running `make` for the first time, a single key `wolfboot_signing_private_key.der`
is created, and added to the keystore module. This key should be used to sign any firmware
running on the target, as well as firmware update binaries.

Additionally, the `keygen` tool creates additional files with different representations
of the keystore
 - A .c file (src/keystore.c) which can be used to deploy public keys as part
   of the bootloader itself, by linking the keystore in `wolfboot.elf`
 - A .bin file (keystore.bin) which contains the keystore that can be hosted
   on a custom memory support. In order to access the keystore, a small driver is
   required (see section "Interface API" below).

## Default usage (built-in keystore)

By default, the keystore object in `src/keystore.c` is accessed by wolfboot by including
its symbols in the build.
Once generated, this file contains an array of structures describing each public
key that will be available to wolfBoot on the target system. Additionally, there are a few
functions that connect to the wolfBoot keystore API to access the details and the
content of the public key slots.

The public key is described by the following structure:

```
 struct keystore_slot {
     uint32_t slot_id;
     uint32_t key_type;
     uint32_t part_id_mask;
     uint32_t pubkey_size;
     uint8_t  pubkey[KEYSTORE_PUBKEY_SIZE];
 };

```

- `slot_id` is the incremental identifier for the key slot, starting from 0.

- `key_type` describes the algorithm of the key, e.g. `AUTH_KEY_ECC256` or `AUTH_KEY_RSA3072`

- `mask` describes the permissions for the key. It's a bitmap of the partition ids for which this key can be used for verification

- `pubkey_size` the size of the public key buffer

- `pubkey` the actual buffer containing the public key in its raw format

When booting, wolfBoot will automatically select the public key associated to the signed firmware image, check that it matches the permission mask for the partition id where the verification is running and then attempts to authenticate the signature of the image using the selected public key slot.

### Creating multiple keys

`keygen` accepts multiple filenames for private keys.

Two arguments:

 - `-g priv.der` generate new keypair, store the private key in priv.der, add the public key to the keystore
 - `-i pub.der` import an existing public key and add it to the keystore

Example of creation of a keystore with two ED25519 keys:

`./tools/keytools/keygen --ed25519 -g first.der -g second.der`

will create the following files:

 - `first.der` first private key
 - `second.der` second private key
 - `src/keystore.c` C keystore containing both public keys associated with `first.der`
     and `second.der`.

The `keystore.c` generated should look similar to this:

```
#define NUM_PUBKEYS 2
const struct keystore_slot PubKeys[NUM_PUBKEYS] = {

     /* Key associated to private key 'first.der' */
    {
        .slot_id = 0,
        .key_type = AUTH_KEY_ED25519,
        .part_id_mask = KEY_VERIFY_ALL,
        .pubkey_size = KEYSTORE_PUBKEY_SIZE_ED25519,
        .pubkey = {
            0x21, 0x7B, 0x8E, 0x64, 0x4A, 0xB7, 0xF2, 0x2F,
            0x22, 0x5E, 0x9A, 0xC9, 0x86, 0xDF, 0x42, 0x14,
            0xA0, 0x40, 0x2C, 0x52, 0x32, 0x2C, 0xF8, 0x9C,
            0x6E, 0xB8, 0xC8, 0x74, 0xFA, 0xA5, 0x24, 0x84
        },
    },

     /* Key associated to private key 'second.der' */
    {
        .slot_id = 1,
        .key_type = AUTH_KEY_ED25519,
        .part_id_mask = KEY_VERIFY_ALL,
        .pubkey_size = KEYSTORE_PUBKEY_SIZE_ED25519,
        .pubkey = {
            0x41, 0xC8, 0xB6, 0x6C, 0xB5, 0x4C, 0x8E, 0xA4,
            0xA7, 0x15, 0x40, 0x99, 0x8E, 0x6F, 0xD9, 0xCF,
            0x00, 0xD0, 0x86, 0xB0, 0x0F, 0xF4, 0xA8, 0xAB,
            0xA3, 0x35, 0x40, 0x26, 0xAB, 0xA0, 0x2A, 0xD5
        },
    },


};

```

### Permissions

By default, when a new keystore is created, the permissions mask is set
to `KEY_VERIFY_ALL`, which means that the key can be used to verify a firmware
targeting any partition id.

The `part_id_mask` value is a bitmask, where each bit represent a different partition.
The bit '0' is reserved for wolfBoot self-update, while typically the main firmware partition
is associated to id 1, so it requires a key with the bit '1' set. In other words, signing a
partition with `--id 3` would require turning on bit '3' in the mask, i.e. adding (1U << 3) to it.

To restrict the permissions for single keys, it would be sufficient to change the value
of each key `part_id_mask`. This is done via the `--id` command line option for keygen.
Each generated or imported key can be associated with a number of partition by passing the
partition IDs in a comma-separated list, e.g.:

```
keygen --ecc256 -g generic.key --id 1,2,3 -g restricted.key
```

Generates two keypairs, `generic.key` and `restricted.key`. The former assumes the
default mask `KEY_VERIFY_ALL`, which makes it possible to use it to authenticate any
of the system components. The latter instead, will carry a mask with only the bits
'1', '2', and '3' set (mask = b00001110 =0x000e), allowing the usage only with the assigned
partition IDs.


### Importing public keys

The "-i" option is used to import existing public keys into the keyvault. The usage is identical to the '-g' option, except that
the file provided must exist and contain a valid public key of the given algorithm and key size.

### Generating and importing keys of different types

By default, wolfBoot hardcodes the type of key used for all the signature verification operations into the keystore format.

Alternatively, wolfBoot can be compiled with the option `WOLFBOOT_UNIVERSAL_KEYSTORE=1`, which disables the check at compile
time and allows adding keys of different types to the keystore. For example, if we want to create two keypairs with different ECC curves,
and additionally store a pre-existing RSA2048 public key file `rsa-pub.der`, we could run the following:

`keygen --ecc256 -g a.key  --ecc384 -g b.key --rsa2048 -i rsa-pub.der`

The command above generates a keystore with three public keys that are accessible by the bootloader at runtime.

Please note that by default wolfBoot does not include any public key algorithm implementations besides the one
selected via the option `SIGN=`, so usually this feature is reserved to specific use cases where other policies or components
in the chain-of-trust require to store different key types for different purposes.


## Using KeyStore with external Key Vaults

It is possible to use an external NVM, a Key Vault or any generic support to
access the KeyStore. In this case, wolfBoot should not link the generated keystore.c directly,
but rather rely on an external interface, that exports the same API which
would be implemented by `keystore.c`.

The API consists of a few functions described below.

### Interface API

#### Number of keys in the keystore
`int keystore_num_pubkeys(void)`

Returns the number of slots in the keystore. At least one slot
should be populated if you want to authenticate your firmware today.
The interface assumes that the slots are numbered sequentially, from zero to
`keystore_num_pubkeys() - 1`. Accessing those slots through this API should always
 return a valid public key.

#### Size of the public key in a slot
`int keystore_get_size(int id)`

Returns the size of the public key stored in the slot `id`.
In case of error, return a negative value.

#### Actual public key buffer (mapped/copied in memory)

`uint8_t *keystore_get_buffer(int id)`

Returns a pointer to an accessible area in memory, containing the buffer with the
public key associated to the slot `id`.

#### Permissions mask

`uint32_t keystore_get_mask(int id)`

Returns the permissions mask, as a 32-bit word, for the public key stored in the slot `id`.
