search

ARMmbed / suit-manifest-generator

Apache License 2.0
18 stars 9 forks source link

readme

Migration: THIS REPO IS ARCHIVED

The suit-tool is being developed at: https://gitlab.arm.com/research/ietf-suit/suit-tool

The suit-parser is being developed at: https://gitlab.arm.com/research/ietf-suit/suit-parser

The core CBOR parser, used by suit-parser, is being developed at: https://gitlab.arm.com/research/ietf-suit/pull-cbor

Manifest Generator

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

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:

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:

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

Optional elements:

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,

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:

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

The algorithm-id must be one of:

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

{
    "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:

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

Create

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

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:

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:

Sign

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

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:

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.

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

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

UECC public key

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

suit-tool pubkey -k FILE

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