SUIT manifest handling. More...

Detailed Description

SUIT manifest handling.

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

Data Structures

struct  suit_v4_component_t
 SUIT v4 component struct. More...
 
struct  suit_v4_manifest_t
 SUIT manifest struct. More...
 

Macros

#define SUIT_COSE_BUF_SIZE   (512U)
 Buffer size used for Cose.
 
#define SUIT_V4_COMPONENT_MAX   (1U)
 Maximum number of components used for SUIT v4.
 
#define SUIT_MANIFEST_VERSION   (4)
 Supported SUIT manifest version.
 
#define SUIT_VERSION   (1)
 Current SUIT serialization format version. More...
 
#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_v4_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 error codes. More...
 
enum  suit_v4_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_v4_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_v4_parse (suit_v4_manifest_t *manifest, const uint8_t *buf, size_t len)
 Parse a manifest. More...
 
int suit_v4_policy_check (suit_v4_manifest_t *manifest)
 Check a manifest policy. More...
 
int suit_cbor_map_iterate_init (nanocbor_value_t *map, nanocbor_value_t *it)
 Initialize a cbor iterator for SUIT cbor map container parsing. More...
 
int suit_cbor_map_iterate (nanocbor_value_t *it, nanocbor_value_t *key, nanocbor_value_t *value)
 Iterate over a cbor map container. More...
 
int suit_cbor_get_int32 (nanocbor_value_t *it, int32_t *out)
 Get cbor value as int32_t. More...
 
int suit_cbor_get_uint (nanocbor_value_t *it, unsigned *out)
 Get cbor value as unsigned. More...
 
int suit_cbor_get_uint32 (nanocbor_value_t *it, uint32_t *out)
 Get cbor value as unsigned long. More...
 
int suit_cbor_get_string (nanocbor_value_t *it, const uint8_t **buf, size_t *len)
 Get cbor value as string. More...
 
int suit_cbor_subparse (nanocbor_value_t *bseq, nanocbor_value_t *it)
 Parser a cbor subsequence. 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...
 
typedef int(* suit_manifest_handler_t) (suit_v4_manifest_t *manifest, int key, nanocbor_value_t *it)
 SUIT v4 manifest handlers. More...
 
suit_manifest_handler_t suit_manifest_get_manifest_handler (int key)
 Get suit manifest handler for given integer key. More...
 

Macro Definition Documentation

◆ SUIT_VERSION

#define SUIT_VERSION   (1)

Current SUIT serialization format version.

see https://tools.ietf.org/html/draft-moran-suit-manifest-04#section-8.2 for details

Definition at line 60 of file suit.h.

Typedef Documentation

◆ suit_manifest_handler_t

typedef int(* suit_manifest_handler_t) (suit_v4_manifest_t *manifest, int key, nanocbor_value_t *it)

SUIT v4 manifest handlers.

Warning
This feature is experimental!

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 suit handler prototype
Parameters
manifestSUIT v4 manifest context
itnanocbor_value_t iterator to the content the handler must handle
Returns
1 on success
negative on error

Definition at line 47 of file handlers.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 108 of file suit.h.

◆ suit_v4_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 82 of file suit.h.

◆ suit_v4_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 95 of file suit.h.

◆ suit_v4_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 manifest 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.

Definition at line 65 of file suit.h.

Function Documentation

◆ suit_cbor_get_int32()

int suit_cbor_get_int32 ( nanocbor_value_t *  it,
int32_t *  out 
)

Get cbor value as int32_t.

Parameters
[in]itcbor container iterator
[out]outaddress of the returned integer
Returns
SUIT_OK on success
SUIT_ERR_INVALID_MANIFEST if value doesn't fit in an int

◆ suit_cbor_get_string()

int suit_cbor_get_string ( nanocbor_value_t *  it,
const uint8_t **  buf,
size_t len 
)

Get cbor value as string.

Parameters
[in]itcbor container iterator
[out]bufaddress of the string buffer
[out]lenaddress of the len of the string
Returns
SUIT_OK on success
SUIT_ERR_INVALID_MANIFEST if value is not a valid string

◆ suit_cbor_get_uint()

int suit_cbor_get_uint ( nanocbor_value_t *  it,
unsigned *  out 
)

Get cbor value as unsigned.

Parameters
[in]itcbor container iterator
[out]outaddress of the returned unsigned
Returns
SUIT_OK on success
SUIT_ERR_INVALID_MANIFEST if value doesn't fit or cannot be converted to unsigned

◆ suit_cbor_get_uint32()

int suit_cbor_get_uint32 ( nanocbor_value_t *  it,
uint32_t *  out 
)

Get cbor value as unsigned long.

Parameters
[in]itcbor container iterator
[out]outaddress of the returned unsigned long
Returns
SUIT_OK on success
SUIT_ERR_INVALID_MANIFEST if value doesn't fit or cannot be converted to unsigned long

◆ suit_cbor_map_iterate()

int suit_cbor_map_iterate ( nanocbor_value_t *  it,
nanocbor_value_t *  key,
nanocbor_value_t *  value 
)

Iterate over a cbor map container.

Parameters
[in]itcbor container iterator
[out]keythe returned key
[out]valuethe returned value
Returns
0 when the iterator is already at the end of the container
the number of returned (key, value) pair, e.g. 1

◆ suit_cbor_map_iterate_init()

int suit_cbor_map_iterate_init ( nanocbor_value_t *  map,
nanocbor_value_t *  it 
)

Initialize a cbor iterator for SUIT cbor map container parsing.

Parameters
[in]mapthe cbor container
[in]itthe cbor iterator
Returns
SUIT_OK when initialization is successful
SUIT_ERR_INVALID_MANIFEST if the manifest is not a cbor container

◆ suit_cbor_subparse()

int suit_cbor_subparse ( nanocbor_value_t *  bseq,
nanocbor_value_t *  it 
)

Parser a cbor subsequence.

Parameters
[in]bseqsubsequence value
[out]itcbor iterator
Returns
0 on success
-1 if bseq is not a cbor string
CborError code on other cbor parser errors

◆ 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 flash writer
[in]offsetoffset to write to on flash
[in]bufbytes to write
[in]lenlength of bytes to write
[in]morewhether more data is comming
Returns
0 on success
<0 on error

◆ suit_manifest_get_manifest_handler()

suit_manifest_handler_t suit_manifest_get_manifest_handler ( int  key)

Get suit manifest handler for given integer key.

Parameters
[in]keyinteger key
Returns
ptr to handler function
NULL (if handler unavailable or key out of range)

◆ suit_v4_parse()

int suit_v4_parse ( suit_v4_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_v4_error_t code on error

◆ suit_v4_policy_check()

int suit_v4_policy_check ( suit_v4_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