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 firmware worker thread
	SUIT secure firmware updates worker thread.

	SUIT secure firmware OTA VFS transport
	SUIT firmware VFS transport.

	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...

bool	suit_get_public_key (uint8_t idx, cose_key_t *key)
	Get public key accepted by SUIT. More...

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 }

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_t *	suit_get_vendor_id (void)
	Retrieve the generated vendor ID. More...

uuid_t *	suit_get_class_id (void)
	Retrieve the generated class ID. More...

uuid_t *	suit_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 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_INSTALLED (1 << 3)
	Component is installed, but has not been verified.

#define	SUIT_COMPONENT_STATE_FINALIZED (1 << 4)
	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 257 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 264 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

typedef struct suit_storage suit_storage_ref_t

Forward declaration for storage struct.

Breaks a dependency chain

Definition at line 1 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

enum 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

enum 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

enum 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

component	Component to check a flag for
flag	Flag to check

Returns: True if the flag is set

Definition at line 311 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

component	Component to set flag for
flag	Flag to set

Definition at line 297 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_public_key()

bool suit_get_public_key	(	uint8_t	idx,
		cose_key_t *	key
	)

Get public key accepted by SUIT.

Parameters

[in]	idx	Index of the key to query
[out]	key	The public key used to verify the signature

Returns: True if a key at that index exists

◆ 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]	manifest	manifest context to store information in
[in]	buf	buffer to parse the manifest from
[in]	len	length 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] manifest manifest context to check the policy for

Returns: 0 on valid manifest policy; -1 on invalid manifest policy

Detailed Description

Modules

Data Structures

Macros

Typedefs

Enumerations

Functions

SUIT parameters

SUIT manifest status flags

SUIT component flags.

Macro Definition Documentation

◆ SUIT_CLASS_ID

◆ SUIT_MANIFEST_COMPONENT_ALL

◆ SUIT_MANIFEST_COMPONENT_NONE

◆ SUIT_VENDOR_DOMAIN

◆ SUIT_VERSION

Typedef Documentation

◆ suit_storage_ref_t

Enumeration Type Documentation

◆ anonymous enum

◆ suit_digest_t

◆ suit_digest_type_t

◆ suit_error_t

Function Documentation

◆ suit_component_check_flag()

◆ suit_component_name_to_string()

◆ suit_component_set_flag()

◆ suit_get_class_id()

◆ suit_get_device_id()

◆ suit_get_public_key()

◆ suit_get_vendor_id()

◆ suit_init_conditions()

◆ suit_parse()

◆ suit_policy_check()