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-v3 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-03

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.
 

Data Structures

struct  suit_component_t
 SUIT component struct. More...
 
struct  suit_manifest_t
 SUIT manifest struct. More...
 

Macros

#define SUIT_COSE_BUF_SIZE   (180U)
 Buffer size used for Cose.
 
#define SUIT_COMPONENT_MAX   (1U)
 Maximum number of components supported in a SUIT manifest.
 
#define SUIT_VERSION   (1)
 Current SUIT serialization format version. More...
 
#define SUIT_STATE_COSE_AUTHENTICATED   (1 << 1)
 COSE signature OK.
 
#define SUIT_STATE_FULLY_AUTHENTICATED   (1 << 2)
 COSE payload matches SUIT manifest digest.
 
#define SUIT_MANIFEST_HAVE_COMPONENTS   (0x1)
 Bit flags used to determine if SUIT manifest contains components.
 
#define SUIT_MANIFEST_HAVE_IMAGE   (0x2)
 Bit flags used to determine if SUIT manifest contains an image.
 

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

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_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 productDevice 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 63 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 122 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 96 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 109 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.

Definition at line 78 of file suit.h.

Function Documentation

◆ suit_flashwrite_helper()

int suit_flashwrite_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

◆ 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