RIOT/dist/tools/suit/suit-manifest-generator/README.md

# Manifest Generator

This repository contains a tool to generate manifests following the specification in https://tools.ietf.org/html/draft-ietf-suit-manifest-03.

# Installing

First clone this repo:

```
$ git clone https://github.com/ARMmbed/suit-manifest-generator.git
```

Next, use pip to install the repo:

```
$ cd suit-manifest-generator
$ python3 -m pip install --user --upgrade .
```

# Input File Description

The input file is organised into four high-level elements:

* `manifest-version` (a positive integer), the version of the manifest specification
* `manifest-sequence-number` (a positive integer), the anti-rollback counter of the manifest
* `components`, a list of components that are described by the manifest


Each component is a JSON map that may contain the following elements. Some elements are required for the target to be able to install the component.

Required elements:

* `install-id` (a Component ID), the identifier of the location to install the described component.
* `install-digest` (a SUIT Digest), the digest of the component after installation.
* `install-size` (a positive integer), the size of the component after installation.
* `vendor-id` (a RFC 4122 UUID), the UUID for the component vendor. This must match the UUID that the manifest processor expects for the specified `install-id`. The suit-tool expects at least one component to have a `vendor-id`
* `class-id` (a RFC 4122 UUID), the UUID for the component. This must match the UUID that the manifest processor expects for the specified `install-id`. The `suit-tool` expects at least one component with a `vendor-id` to also have a `class-id`
* `file` (a string), the path to a payload file. The `install-digest` and `install-size` will be calculated from this file.

Some elements are not required by the tool, but are necessary in order to accomplish one or more use-cases.

Optional elements:

* `bootable` (a boolean, default: `false`), when set to true, the `suit-tool` will generate commands to execute the component, either from `install-id` or from `load-id` (see below)
* `uri` (a text string), the location at which to find the payload. This element is required in order to generate the `payload-fetch` and `install` sections.
* `loadable` (a boolean, default: `false`), when set to true, the `suit-tool` loads this component in the `load` section.
* `compression-info` (a choice of string values), indicates how a payload is compressed. When specified, payload is decompressed before installation. The `install-size` must match the decompressed size of the payload and the install-digest must match the decompressed payload. N.B. The suit-tool does not perform compression. Supported values are:

    * `gzip`
    * `bzip2`
    * `deflate`
    * `lz4`
    * `lzma`

* `download-digest` (a SUIT Digest), a digest of the component after download. Only required if `compression-info` is present and `decompress-on-load` is `false`.
* `decompress-on-load` (a boolean, default: `false`), when set to true, payload is not decompressed during installation. Instead, the payload is decompressed during loading. This element has no effect if `loadable` is `false`.
* `load-digest` (a SUIT Digest), a digest of the component after loading. Only required if `decompress-on-load` is `true`.
* `install-on-download` (boolean, default: true), If true, payload is written to `install-id` during download, otherwise, payload is written to `download-id`.
* `download-id` (a component id), the location where a downloaded payload should be stored before installation--only used when `install-on-download` is `false`.

## Component ID

The `suit-tool` expects component IDs to be a JSON list of strings. The `suit-tool` converts the strings to bytes by:

1. Attempting to convert from hex
2. Attempting to convert from base64
3. Encoding the string to UTF-8

For example,

* `["00"]` will encode to `814100` (`[h'00']`)
* `["0"]` will encode to `814130` (`[h'30']`)
* `["MTIzNA=="]` will encode to `814431323334` (`[h'31323334']`)
* `["example"]` will encode to `81476578616D706C65` (`[h'6578616d706c65']`)

N.B. Be careful that certain strings can appear to be hex or base64 and will be treated as such. Any characters outside the set `[0-9a-fA-F]` ensure that the string is not treated as hex. Any characters outside the set `[0-9A-Za-z+/]` or a number of characters not divisible by 4 will ensure that the string is not treated as base64.

## SUIT Digest

The format of a digest is a JSON map:

```JSON
{
    "algorithm-id" : "sha256",
    "digest-bytes" : "base64-or-hex"
}
```

The `algorithm-id` must be one of:

* `sha224`
* `sha256`
* `sha384`
* `sha512`

The `digest-bytes` is a string of either hex- or base64-encoded bytes. The same decoding rules as those in Component ID are applied.

## Example Input File

```JSON
{
    "components" : [
        {
            "download-id" : ["01"],
            "install-id" : ["00"],
            "install-digest": {
                "algorithm-id": "sha256",
                "digest-bytes": "00112233445566778899aabbccddeeff0123456789abcdeffedcba9876543210"
            },
            "install-size" : 34768,
            "uri": "http://example.com/file.bin",
            "vendor-id" : "fa6b4a53-d5ad-5fdf-be9d-e663e4d41ffe",
            "class-id" : "1492af14-2569-5e48-bf42-9b2d51f2ab45",
            "bootable" : true,
            "install-on-download" : false,
            "loadable" : true,
            "decompress-on-load" : true,
            "load-id" : ["02"],
            "compression-info" : "gzip",
            "load-digest" : {
                "algorithm-id": "sha256",
                "digest-bytes": "0011223344556677889901234567899876543210aabbccddeeffabcdeffedcba"
            },
        },
        {
            "install-id" : ["03", "01"],
            "install-digest": {
                "algorithm-id": "sha256",
                "digest-bytes": "0123456789abcdeffedcba987654321000112233445566778899aabbccddeeff"
            },
            "install-size" : 76834,
            "uri": "http://example.com/file2.bin"
        }
    ],
    "manifest-version": 1,
    "manifest-sequence-number": 7
}
```

# Invoking the suit-tool

The `suit-tool` supports three sub-commands:

* `create` generates a new manifest.
* `sign` signs a manifest.
* `parse` parses an existing manifest into cbor-debug or a json representation.
* `keygen` Create a signing key. Not for production use.
* `pubkey` Get the public key for a supplied private key in uECC-compatible C definition.

The `suit-tool` has a configurable log level, specified with `-l`:

* `suit-tool -l debug` verbose output
* `suit-tool -l info` normal output
* `suit-tool -l warning` suppress informational messages
* `suit-tool -l exception` suppress warning and informational messages

## Create

To create a manifest, invoke the `suit-tool` with:

```sh
suit-tool create -i IFILE -o OFILE
```

The format of `IFILE` is as described above. `OFILE` defaults to a CBOR-encoded SUIT manifest.

`-f` specifies the output format:

* `suit`: CBOR-encoded SUIT manifest
* `suit-debug`: CBOR-debug SUIT manifest
* `json`: JSON-representation of a SUIT manifest

The `suit-tool` can generate a manifest with severable fields. To enable this mode, add the `-s` flag.

To add a component to the manifest from the command-line, use the following syntax:

```
-c 'FIELD1=VALUE1,FIELD2=VALUE2'
```

The supported fields are:

* `file` the path fo a file to use as a payload file.
* `inst` the `install-id`.
* `uri` the URI where the file will be found.

## Sign

To sign an existing manifest, invoke the `suit-tool` with:

```sh
suit-tool sign -m MANIFEST -k PRIVKEY -o OFILE
```

`PRIVKEY` must be a secp256r1 ECC private key in PEM format.

If the COSE Signature needs to indicate the key ID, add a key id with:

```
-i KEYID
```

## Parse

To parse an existing manifest, invoke the `suit-tool` with:

```sh
suit-tool parse -m MANIFEST
```

If a json-representation is needed, add the '-j' flag.

## Keygen

Create an asymmetric keypair for non-production use. Production systems should use closely guarded keys, such as keys stored in an HSM.

```sh
 suit-tool keygen [-t TYPE] -o KEYFILE
 ```

`suit-tool keygen` defaults to creating SECP256r1 keys. To create another type of key, use `-t`followed by one of:

* `secp256r1`
* `secp384r1`
* `secp521r1`
* `ed25519`

## UECC public key

Derive a public key in the format used by micro ECC. The input is a PEM private key.

```sh
suit-tool pubkey -k FILE
```

The tool will then print the public key in micro ECC format.