Newer
Older
This repository contains a tool to generate manifests following the specification in https://tools.ietf.org/html/draft-ietf-suit-manifest-03.
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 .
```
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
# 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`
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
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:
## 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.