SUIT secure firmware OTA upgrade infrastructure

SUIT manifest handling. More...

Detailed Description

SUIT manifest handling.

Warning
This feature is experimental!
Note
The current implementation of this specification is based on the IETF-SUIT-v9 draft. The module is still experimental and will change to match future draft specifications
See also
https://tools.ietf.org/html/draft-ietf-suit-manifest-09

Handler functions for SUIT manifests

Author
Koen Zandberg koen@.nosp@m.berg.nosp@m.zand..nosp@m.net
Kaspar Schleiser kaspa.nosp@m.r@sc.nosp@m.hleis.nosp@m.er.d.nosp@m.e

Modules

 SUIT firmware CoAP transport
 SUIT secure firmware updates over CoAP.
 
 SUIT secure firmware OTA mock transport
 SUIT firmware mock transport.
 
 SUIT secure firmware OTA upgrade storage
 infrastructure
 

Data Structures

struct  suit_param_ref_t
 SUIT parameter reference. More...
 
struct  suit_component_t
 SUIT component struct as decoded from the manifest. More...
 
struct  suit_manifest_t
 SUIT manifest struct. More...
 

Macros

#define SUIT_COSE_BUF_SIZE   (180U)
 Buffer size used for Cose.
 
#define CONFIG_SUIT_COMPONENT_MAX   (1U)
 Maximum number of components supported in a SUIT manifest.
 
#define CONFIG_SUIT_COMPONENT_MAX_NAME_LEN   (32U)
 Maximum name of component, includes separator.
 
#define SUIT_VERSION   (1)
 Current SUIT serialization format version. More...
 
#define SUIT_MANIFEST_COMPONENT_ALL   (UINT8_MAX)
 Component index representing all components. More...
 
#define SUIT_MANIFEST_COMPONENT_NONE   (SUIT_MANIFEST_COMPONENT_ALL - 1)
 Component index representing no components. More...
 

Typedefs

typedef struct suit_storage suit_storage_ref_t
 Forward declaration for storage struct. More...
 

Enumerations

enum  suit_error_t {
  SUIT_OK = 0, SUIT_ERR_INVALID_MANIFEST = -1, SUIT_ERR_UNSUPPORTED = -2, SUIT_ERR_NOT_SUPPORTED = -3,
  SUIT_ERR_COND = -4, SUIT_ERR_SEQUENCE_NUMBER = -5, SUIT_ERR_SIGNATURE = -6, SUIT_ERR_DIGEST_MISMATCH = -7,
  SUIT_ERR_POLICY_FORBIDDEN = -8, SUIT_ERR_NO_MEM = -9, SUIT_ERR_STORAGE = -50, SUIT_ERR_STORAGE_EXCEEDED = -51,
  SUIT_ERR_STORAGE_UNAVAILABLE = -52
}
 SUIT error codes. More...
 
enum  suit_digest_t { SUIT_DIGEST_NONE = 0, SUIT_DIGEST_SHA256 = 1, SUIT_DIGEST_SHA384 = 2, SUIT_DIGEST_SHA512 = 3 }
 SUIT payload digest algorithms. More...
 
enum  suit_digest_type_t { SUIT_DIGEST_TYPE_RAW = 1, SUIT_DIGEST_TYPE_INSTALLED = 2, SUIT_DIGEST_TYPE_CIPHERTEXT = 3, SUIT_DIGEST_TYPE_PREIMAGE = 4 }
 SUIT payload digest types. More...
 
enum  { SUIT_COMPONENT_IDENTIFIER = 1, SUIT_COMPONENT_SIZE = 2, SUIT_COMPONENT_DIGEST = 3 }
 SUIT component types. More...
 

Functions

int suit_parse (suit_manifest_t *manifest, const uint8_t *buf, size_t len)
 Parse a manifest. More...
 
int suit_policy_check (suit_manifest_t *manifest)
 Check a manifest policy. More...
 
static void suit_component_set_flag (suit_component_t *component, uint16_t flag)
 Set a component flag. More...
 
static bool suit_component_check_flag (suit_component_t *component, uint16_t flag)
 Check a component flag. More...
 
int suit_component_name_to_string (const suit_manifest_t *manifest, const suit_component_t *component, char separator, char *buf, size_t buf_len)
 Convert a component name to a string. More...
 
int suit_storage_helper (void *arg, size_t offset, uint8_t *buf, size_t len, int more)
 Helper function for writing bytes on flash a specified offset. More...
 
enum  { SUIT_COND_VENDOR_ID = 1, SUIT_COND_CLASS_ID = 2, SUIT_COND_DEV_ID = 3, SUIT_COND_BEST_BEFORE = 4 }
 SUIT conditionals.
 
void suit_init_conditions (void)
 Initialize boot-time conditions for SUIT manifests. More...
 
uuid_tsuit_get_vendor_id (void)
 Retrieve the generated vendor ID. More...
 
uuid_tsuit_get_class_id (void)
 Retrieve the generated class ID. More...
 
uuid_tsuit_get_device_id (void)
 Retrieve the generated device ID. More...
 
#define SUIT_VENDOR_DOMAIN   "riot-os.org"
 SUIT conditions. More...
 
#define SUIT_CLASS_ID   RIOT_BOARD
 The SUIT class ID source. More...
 

SUIT manifest status flags

These flags apply to the full manifest.

#define SUIT_STATE_HAVE_COMPONENTS   (1 << 0)
 Bit flags used to determine if SUIT manifest contains components.
 
#define SUIT_STATE_COSE_AUTHENTICATED   (1 << 1)
 COSE signature OK.
 
#define SUIT_STATE_FULLY_AUTHENTICATED   (1 << 2)
 COSE payload matches SUIT manifest digest.
 

SUIT parameters

enum  suit_parameter_t {
  SUIT_PARAMETER_VENDOR_IDENTIFIER = 1, SUIT_PARAMETER_CLASS_IDENTIFIER = 2, SUIT_PARAMETER_IMAGE_DIGEST = 3, SUIT_PARAMETER_USE_BEFORE = 4,
  SUIT_PARAMETER_COMPONENT_OFFSET = 5, SUIT_PARAMETER_STRICT_ORDER = 12, SUIT_PARAMETER_SOFT_FAILURE = 13, SUIT_PARAMETER_IMAGE_SIZE = 14,
  SUIT_PARAMETER_ENCRYPTION_INFO = 18, SUIT_PARAMETER_COMPRESSION_INFO = 19, SUIT_PARAMETER_UNPACK_INFO = 20, SUIT_PARAMETER_URI = 21,
  SUIT_PARAMETER_SOURCE_COMPONENT = 22, SUIT_PARAMETER_RUN_ARGS = 23, SUIT_PARAMETER_DEVICE_IDENTIFIER = 24, SUIT_PARAMETER_MINIMUM_BATTERY = 26,
  SUIT_PARAMETER_UPDATE_PRIORITY = 27, SUIT_PARAMETER_VERSION = 28, SUIT_PARAMETER_WAIT_INFO = 29, SUIT_PARAMETER_URI_LIST = 30
}
 

SUIT component flags.

These state flags apply to individual components inside a manifest.

#define SUIT_COMPONENT_STATE_FETCHED   (1 << 0)
 Component is fetched.
 
#define SUIT_COMPONENT_STATE_FETCH_FAILED   (1 << 1)
 Component fetched but failed.
 
#define SUIT_COMPONENT_STATE_VERIFIED   (1 << 2)
 Component is verified.
 
#define SUIT_COMPONENT_STATE_FINALIZED   (1 << 3)
 Component successfully installed.
 

Macro Definition Documentation

◆ SUIT_CLASS_ID

#define SUIT_CLASS_ID   RIOT_BOARD

The SUIT class ID source.

By default the RIOT_VERSION define is used for this

Definition at line 49 of file conditions.h.

◆ SUIT_MANIFEST_COMPONENT_ALL

#define SUIT_MANIFEST_COMPONENT_ALL   (UINT8_MAX)

Component index representing all components.

Used when suit-directive-set-component-index = True

Definition at line 255 of file suit.h.

◆ SUIT_MANIFEST_COMPONENT_NONE

#define SUIT_MANIFEST_COMPONENT_NONE   (SUIT_MANIFEST_COMPONENT_ALL - 1)

Component index representing no components.

Used when suit-directive-set-component-index = False

Definition at line 262 of file suit.h.

◆ SUIT_VENDOR_DOMAIN

#define SUIT_VENDOR_DOMAIN   "riot-os.org"

SUIT conditions.

SUIT conditions API

Author
Koen Zandberg koen@.nosp@m.berg.nosp@m.zand..nosp@m.net
Kaspar Schleiser kaspa.nosp@m.r@sc.nosp@m.hleis.nosp@m.er.d.nosp@m.e

The SUIT vendor ID source

The basis of the UUID must be the vendor domain, please change this when using this module in a product Device vendor domain

Definition at line 40 of file conditions.h.

◆ SUIT_VERSION

#define SUIT_VERSION   (1)

Current SUIT serialization format version.

see https://tools.ietf.org/html/draft-ietf-suit-manifest-03#section-7 for details

Definition at line 71 of file suit.h.

Typedef Documentation

◆ suit_storage_ref_t

Forward declaration for storage struct.

Breaks a dependency chain

Definition at line 207 of file suit.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

SUIT component types.

Unofficial list from suit-manifest-generator

Enumerator
SUIT_COMPONENT_IDENTIFIER 

Identifier component.

SUIT_COMPONENT_SIZE 

Size component.

SUIT_COMPONENT_DIGEST 

Digest component.

Definition at line 147 of file suit.h.

◆ suit_digest_t

SUIT payload digest algorithms.

Unofficial list from suit-manifest-generator

Enumerator
SUIT_DIGEST_NONE 

No digest algo supplied.

SUIT_DIGEST_SHA256 

SHA256.

SUIT_DIGEST_SHA384 

SHA384.

SUIT_DIGEST_SHA512 

SHA512.

Definition at line 121 of file suit.h.

◆ suit_digest_type_t

SUIT payload digest types.

Unofficial list from suit-manifest-generator

Enumerator
SUIT_DIGEST_TYPE_RAW 

Raw payload digest.

SUIT_DIGEST_TYPE_INSTALLED 

Installed firmware digest.

SUIT_DIGEST_TYPE_CIPHERTEXT 

Ciphertext digest.

SUIT_DIGEST_TYPE_PREIMAGE 

Pre-image digest.

Definition at line 134 of file suit.h.

◆ suit_error_t

SUIT error codes.

Enumerator
SUIT_OK 

Manifest parsed and validated.

SUIT_ERR_INVALID_MANIFEST 

Unexpected CBOR structure detected.

SUIT_ERR_UNSUPPORTED 

Unsupported SUIT feature detected.

SUIT_ERR_NOT_SUPPORTED 

Unsupported features detected.

SUIT_ERR_COND 

Conditionals evaluate to false.

SUIT_ERR_SEQUENCE_NUMBER 

Sequence number less or equal to current sequence number.

SUIT_ERR_SIGNATURE 

Unable to verify signature.

SUIT_ERR_DIGEST_MISMATCH 

Digest mismatch with COSE and SUIT.

SUIT_ERR_POLICY_FORBIDDEN 

Denied because of policy mismatch.

SUIT_ERR_NO_MEM 

Out of memory condition.

SUIT_ERR_STORAGE 

Backend returned an error.

SUIT_ERR_STORAGE_EXCEEDED 

Backend out of space.

SUIT_ERR_STORAGE_UNAVAILABLE 

Backend location not available.

Definition at line 98 of file suit.h.

Function Documentation

◆ suit_component_check_flag()

static bool suit_component_check_flag ( suit_component_t component,
uint16_t  flag 
)
inlinestatic

Check a component flag.

Parameters
componentComponent to check a flag for
flagFlag to check
Returns
True if the flag is set

Definition at line 309 of file suit.h.

◆ suit_component_name_to_string()

int suit_component_name_to_string ( const suit_manifest_t manifest,
const suit_component_t component,
char  separator,
char *  buf,
size_t  buf_len 
)

Convert a component name to a string.

Each component part is prefixed with separator

Returns
SUIT_OK if successful
negative error code on error

◆ suit_component_set_flag()

static void suit_component_set_flag ( suit_component_t component,
uint16_t  flag 
)
inlinestatic

Set a component flag.

Parameters
componentComponent to set flag for
flagFlag to set

Definition at line 295 of file suit.h.

◆ suit_get_class_id()

uuid_t* suit_get_class_id ( void  )

Retrieve the generated class ID.

Returns
The class ID as UUID

◆ suit_get_device_id()

uuid_t* suit_get_device_id ( void  )

Retrieve the generated device ID.

Returns
The device ID as UUID

◆ suit_get_vendor_id()

uuid_t* suit_get_vendor_id ( void  )

Retrieve the generated vendor ID.

Returns
The vendor ID as UUID

◆ suit_init_conditions()

void suit_init_conditions ( void  )

Initialize boot-time conditions for SUIT manifests.

This initializes the device-based conditions for validating manifest preconditions

Vendor url as UUID: UUID5(DNS_PREFIX, SUIT_VENDOR_DOMAIN) Device class UUID: UUID5(vendor, SUIT_CLASS_ID) Device specific UUID: UUID5(vendor, Device ID)

◆ suit_parse()

int suit_parse ( suit_manifest_t manifest,
const uint8_t *  buf,
size_t  len 
)

Parse a manifest.

Note
The buffer is still required after parsing, please don't reuse the buffer while the manifest is used
Parameters
[in]manifestmanifest context to store information in
[in]bufbuffer to parse the manifest from
[in]lenlength of the manifest data in the buffer
Returns
SUIT_OK on parseable manifest
negative suit_error_t code on error

◆ suit_policy_check()

int suit_policy_check ( suit_manifest_t manifest)

Check a manifest policy.

Parameters
[in]manifestmanifest context to check the policy for
Returns
0 on valid manifest policy
-1 on invalid manifest policy

◆ suit_storage_helper()

int suit_storage_helper ( void *  arg,
size_t  offset,
uint8_t *  buf,
size_t  len,
int  more 
)

Helper function for writing bytes on flash a specified offset.

Parameters
[in]argptr to the SUIT manifest
[in]offsetoffset to write to on flash
[in]bufbytes to write
[in]lenlength of bytes to write
[in]morewhether more data is coming
Returns
0 on success
<0 on error