BSL v1.1.1 - 39.g9f43410
AMMOS Bundle Protocol Security Library (BSL)
Loading...
Searching...
No Matches
CoseMsg.h File Reference

Header for COSE message structures [15]. More...

#include "bsl/front/BSLMemory.h"
#include "bsl/dynamic/CBOR.h"
#include "bsl/dynamic/IdValPair.h"
#include <m-array.h>
#include <m-bptree.h>
#include <m-shared-ptr.h>
+ Include dependency graph for CoseMsg.h:
+ This graph shows which files directly or indirectly include this file:

Data Structures

struct  BSLX_CoseMsg_Headers_t
 Common header storage and logic. More...
 
struct  BSLX_CoseMsg_Mac0_t
 Decoded COSE_Mac0. More...
 
struct  BSLX_CoseMsg_Encrypt0_t
 Decoded COSE_Encrypt0. More...
 
struct  BSLX_CoseMsg_Recipient_t
 Each recipient of a COSE_Mac or COSE_Encrypt. More...
 
struct  BSLX_CoseMsg_Mac_t
 Decoded COSE_Mac. More...
 
struct  BSLX_CoseMsg_Encrypt_t
 Decoded COSE_Encrypt. More...
 

Macros

#define BSLX_COSEMSG_RECIPIENTS_LIMIT   10
 Artificial limit on number of recipients supported.
 
#define BSLX_COSEMSG_AESGCM_IV_LEN   (12)
 Length of generated IV byte strings.
 

Enumerations

enum  BSLX_CoseMsg_Header_e {
  BSLX_COSEMSG_HDR_ALG = 1 , BSLX_COSEMSG_HDR_CRIT = 2 , BSLX_COSEMSG_HDR_CONTENTTYPE = 3 , BSLX_COSEMSG_HDR_KID = 4 ,
  BSLX_COSEMSG_HDR_IV = 5 , BSLX_COSEMSG_HDR_PARTIALIV = 6 , BSLX_COSEMSG_HDR_KIDCONTEXT = 10 , BSLX_COSEMSG_HDR_SALT = -20
}
 Header parameters managed by IANA. More...
 
enum  BSLX_CoseMsg_Alg_e {
  BSLX_COSEMSG_ALG_DIRECT_HKDF_SHA_512 = -11 , BSLX_COSEMSG_ALG_DIRECT_HKDF_SHA_256 = -10 , BSLX_COSEMSG_ALG_DIRECT = -6 , BSLX_COSEMSG_ALG_AES_KW_256 = -5 ,
  BSLX_COSEMSG_ALG_AES_KW_192 = -4 , BSLX_COSEMSG_ALG_AES_KW_128 = -3 , BSLX_COSEMSG_ALG_AES_GCM_128 = 1 , BSLX_COSEMSG_ALG_AES_GCM_192 = 2 ,
  BSLX_COSEMSG_ALG_AES_GCM_256 = 3 , BSLX_COSEMSG_ALG_HMAC_SHA_256_256 = 5 , BSLX_COSEMSG_ALG_HMAC_SHA_384_384 = 6 , BSLX_COSEMSG_ALG_HMAC_SHA_512_512 = 7
}
 Algorithm code points managed by IANA. More...
 
enum  BSLX_CoseMsg_KeyParam_e { BSLX_COSEMSG_KEY_PARAM_KTY = 1 , BSLX_COSEMSG_KEY_PARAM_KID = 2 , BSLX_COSEMSG_KEY_PARAM_ALG = 3 , BSLX_COSEMSG_KEY_PARAM_BASEIV = 5 }
 Key parameter code points managed by IANA. More...
 

Functions

void BSLX_CoseMsg_HdrMapTree_update (BSLX_CoseMsg_HdrMapTree_t base, const BSLX_CoseMsg_HdrMapTree_t addl)
 Update a base map with an additional map, adding items when the key is not already present.
 
int BSLX_CoseMsg_Headers_Encode_Map (QCBOREncodeContext *enc, const BSLX_CoseMsg_HdrMapTree_t *map)
 Encode a header parameter map.
 
int BSLX_CoseMsg_Headers_Decode_Map (QCBORDecodeContext *dec, BSLX_CoseMsg_HdrMapTree_t *map)
 Decode a header parameter map.
 
void BSLX_CoseMsg_Headers_Init (BSLX_CoseMsg_Headers_t *obj)
 Initialize the struct.
 
void BSLX_CoseMsg_Headers_Deinit (BSLX_CoseMsg_Headers_t *obj)
 Deinitialize the struct.
 
int BSLX_CoseMsg_Headers_Encode (QCBOREncodeContext *enc, const BSLX_CoseMsg_Headers_t *obj)
 Match BSL_CBOR_Encode_f signature.
 
int BSLX_CoseMsg_Headers_Decode (QCBORDecodeContext *dec, BSLX_CoseMsg_Headers_t *obj)
 Match BSL_CBOR_Decode_f signature.
 
int BSLX_CoseMsg_Headers_DerivePhdr (BSLX_CoseMsg_Headers_t *obj)
 Derive BSLX_CoseMsg_Headers_t::phdr_bstr from protected headers in BSLX_CoseMsg_Headers_t::phdr.
 
int BSLX_CoseMsg_Headers_CheckCrit (const BSLX_CoseMsg_Headers_t *obj)
 Check for the presence of crit header referencing unsupported parameters.
 
const BSL_IdValPair_t * BSLX_CoseMsg_Headers_Get (const BSLX_CoseMsg_Headers_t *obj, int64_t label, bool need_phdr)
 Get a desired header parameter.
 
void BSLX_CoseMsg_Mac0_Init (BSLX_CoseMsg_Mac0_t *obj)
 Initialize the struct.
 
void BSLX_CoseMsg_Mac0_Deinit (BSLX_CoseMsg_Mac0_t *obj)
 Deinitialize the struct.
 
int BSLX_CoseMsg_Mac0_Encode (QCBOREncodeContext *enc, const BSLX_CoseMsg_Mac0_t *obj)
 Match BSL_CBOR_Encode_f signature.
 
int BSLX_CoseMsg_Mac0_Decode (QCBORDecodeContext *dec, BSLX_CoseMsg_Mac0_t *obj)
 Match BSL_CBOR_Decode_f signature.
 
void BSLX_CoseMsg_Encrypt0_Init (BSLX_CoseMsg_Encrypt0_t *obj)
 Initialize the struct.
 
void BSLX_CoseMsg_Encrypt0_Deinit (BSLX_CoseMsg_Encrypt0_t *obj)
 Deinitialize the struct.
 
int BSLX_CoseMsg_Encrypt0_Encode (QCBOREncodeContext *enc, const BSLX_CoseMsg_Encrypt0_t *obj)
 Match BSL_CBOR_Encode_f signature.
 
int BSLX_CoseMsg_Encrypt0_Decode (QCBORDecodeContext *dec, BSLX_CoseMsg_Encrypt0_t *obj)
 Match BSL_CBOR_Decode_f signature.
 
void BSLX_CoseMsg_Recipient_Init (BSLX_CoseMsg_Recipient_t *obj)
 Initialize the struct.
 
void BSLX_CoseMsg_Recipient_Deinit (BSLX_CoseMsg_Recipient_t *obj)
 Deinitialize the struct.
 
int BSLX_CoseMsg_Recipient_Encode (QCBOREncodeContext *enc, const BSLX_CoseMsg_Recipient_t *obj)
 Match BSL_CBOR_Encode_f signature.
 
int BSLX_CoseMsg_Recipient_Decode (QCBORDecodeContext *dec, BSLX_CoseMsg_Recipient_t *obj)
 Match BSL_CBOR_Decode_f signature.
 
void BSLX_CoseMsg_RecipientList_ResizeNew (BSLX_CoseMsg_RecipientList_t obj, size_t size)
 Resize recipients array, preserving existing if possible.
 
void BSLX_CoseMsg_Mac_Init (BSLX_CoseMsg_Mac_t *obj)
 Initialize the struct.
 
void BSLX_CoseMsg_Mac_Deinit (BSLX_CoseMsg_Mac_t *obj)
 Deinitialize the struct.
 
int BSLX_CoseMsg_Mac_Encode (QCBOREncodeContext *enc, const BSLX_CoseMsg_Mac_t *obj)
 Match BSL_CBOR_Encode_f signature.
 
int BSLX_CoseMsg_Mac_Decode (QCBORDecodeContext *dec, BSLX_CoseMsg_Mac_t *obj)
 Match BSL_CBOR_Decode_f signature.
 
void BSLX_CoseMsg_Encrypt_Init (BSLX_CoseMsg_Encrypt_t *obj)
 Initialize the struct.
 
void BSLX_CoseMsg_Encrypt_Deinit (BSLX_CoseMsg_Encrypt_t *obj)
 Deinitialize the struct.
 
int BSLX_CoseMsg_Encrypt_Encode (QCBOREncodeContext *enc, const BSLX_CoseMsg_Encrypt_t *obj)
 Match BSL_CBOR_Encode_f signature.
 
int BSLX_CoseMsg_Encrypt_Decode (QCBORDecodeContext *dec, BSLX_CoseMsg_Encrypt_t *obj)
 Match BSL_CBOR_Decode_f signature.
 

Detailed Description

Header for COSE message structures [15].

Macro Definition Documentation

◆ BSLX_COSEMSG_AESGCM_IV_LEN

#define BSLX_COSEMSG_AESGCM_IV_LEN   (12)

Length of generated IV byte strings.

From https://www.rfc-editor.org/rfc/rfc9053.html#section-4.1 "This document fixes the size of the nonce at 96 bits."

◆ BSLX_COSEMSG_RECIPIENTS_LIMIT

#define BSLX_COSEMSG_RECIPIENTS_LIMIT   10

Artificial limit on number of recipients supported.

Enumeration Type Documentation

◆ BSLX_CoseMsg_Alg_e

Algorithm code points managed by IANA.

https://www.iana.org/assignments/cose/cose.xhtml#algorithms

Enumerator
BSLX_COSEMSG_ALG_DIRECT_HKDF_SHA_512 

direct+HKDF-SHA-512

BSLX_COSEMSG_ALG_DIRECT_HKDF_SHA_256 

direct+HKDF-SHA-256

BSLX_COSEMSG_ALG_DIRECT 

direct

BSLX_COSEMSG_ALG_AES_KW_256 

A256KW.

BSLX_COSEMSG_ALG_AES_KW_192 

A256KW.

BSLX_COSEMSG_ALG_AES_KW_128 

A256KW.

BSLX_COSEMSG_ALG_AES_GCM_128 

A128GCM.

BSLX_COSEMSG_ALG_AES_GCM_192 

A192GCM.

BSLX_COSEMSG_ALG_AES_GCM_256 

A256GCM.

BSLX_COSEMSG_ALG_HMAC_SHA_256_256 

HMAC 256/256.

BSLX_COSEMSG_ALG_HMAC_SHA_384_384 

HMAC 384/384.

BSLX_COSEMSG_ALG_HMAC_SHA_512_512 

HMAC 512/512.

◆ BSLX_CoseMsg_Header_e

Header parameters managed by IANA.

https://www.iana.org/assignments/cose/cose.xhtml#header-parameters

Enumerator
BSLX_COSEMSG_HDR_ALG 

Algorithm code point with value type int64.

BSLX_COSEMSG_HDR_CRIT 

Critical parameters with value type raw (array of int)

BSLX_COSEMSG_HDR_CONTENTTYPE 

Content Type not used by BPSec.

BSLX_COSEMSG_HDR_KID 

Key ID with value type bytes.

BSLX_COSEMSG_HDR_IV 

IV with value type bytes.

BSLX_COSEMSG_HDR_PARTIALIV 

Partial IV with value type bytes.

BSLX_COSEMSG_HDR_KIDCONTEXT 

Key ID context with value type bytes.

BSLX_COSEMSG_HDR_SALT 

Salt for KDF with value type bytes.

◆ BSLX_CoseMsg_KeyParam_e

Key parameter code points managed by IANA.

https://www.iana.org/assignments/cose/cose.xhtml#key-common-parameters

Enumerator
BSLX_COSEMSG_KEY_PARAM_KTY 

Key type value as int64_t.

BSLX_COSEMSG_KEY_PARAM_KID 

Key ID value as bytes.

BSLX_COSEMSG_KEY_PARAM_ALG 

Algorithm value as int64_t.

BSLX_COSEMSG_KEY_PARAM_BASEIV 

Base IV value as bytes.

Function Documentation

◆ BSLX_CoseMsg_Encrypt0_Decode()

◆ BSLX_CoseMsg_Encrypt0_Deinit()

◆ BSLX_CoseMsg_Encrypt0_Encode()

int BSLX_CoseMsg_Encrypt0_Encode ( QCBOREncodeContext *  enc,
const BSLX_CoseMsg_Encrypt0_t obj 
)

◆ BSLX_CoseMsg_Encrypt0_Init()

◆ BSLX_CoseMsg_Encrypt_Decode()

◆ BSLX_CoseMsg_Encrypt_Deinit()

◆ BSLX_CoseMsg_Encrypt_Encode()

◆ BSLX_CoseMsg_Encrypt_Init()

◆ BSLX_CoseMsg_HdrMapTree_update()

void BSLX_CoseMsg_HdrMapTree_update ( BSLX_CoseMsg_HdrMapTree_t  base,
const BSLX_CoseMsg_HdrMapTree_t  addl 
)

Update a base map with an additional map, adding items when the key is not already present.

Referenced by BSLX_CoseSc_VerifyHeaders().

◆ BSLX_CoseMsg_Headers_CheckCrit()

int BSLX_CoseMsg_Headers_CheckCrit ( const BSLX_CoseMsg_Headers_t obj)

Check for the presence of crit header referencing unsupported parameters.

Parameters
[in]objThe headers to search.
Returns
BSL_SUCCESS if successful.

References BSL_CBOR_Decode(), BSL_ERR_DECODING, BSL_IdValPair_GetAsRaw(), BSL_LOG_ERR, BSL_SUCCESS, BSLX_COSEMSG_HDR_CRIT, BSLX_CoseMsg_Headers_CheckCrit_Decode(), and BSLX_CoseMsg_Headers_Get().

Referenced by BSLX_CoseSc_VerifyHeaders().

◆ BSLX_CoseMsg_Headers_Decode()

◆ BSLX_CoseMsg_Headers_Decode_Map()

int BSLX_CoseMsg_Headers_Decode_Map ( QCBORDecodeContext *  dec,
BSLX_CoseMsg_HdrMapTree_t map 
)

Decode a header parameter map.

Matches BSL_CBOR_Encode_f signature.

References BSL_ERR_DECODING, BSL_IdValPair_Decode(), and BSL_SUCCESS.

Referenced by BSLX_CoseMsg_Headers_Decode(), and BSLX_CoseSc_GetAndValidateAddlHeaders().

◆ BSLX_CoseMsg_Headers_Deinit()

◆ BSLX_CoseMsg_Headers_DerivePhdr()

int BSLX_CoseMsg_Headers_DerivePhdr ( BSLX_CoseMsg_Headers_t obj)

Derive BSLX_CoseMsg_Headers_t::phdr_bstr from protected headers in BSLX_CoseMsg_Headers_t::phdr.

This is needed before cryptographic calculation and encoding.

Parameters
[in,out]objThe headers to encode and store into.
Returns
BSL_SUCCESS if successful.

References BSL_CBOR_Encode_Twopass(), BSL_Data_Resize(), BSL_SUCCESS, BSLX_CoseMsg_Headers_Encode_Map(), BSLX_CoseMsg_Headers_t::phdr, and BSLX_CoseMsg_Headers_t::phdr_bstr.

Referenced by BSLX_CoseSc_SourceHeaders().

◆ BSLX_CoseMsg_Headers_Encode()

◆ BSLX_CoseMsg_Headers_Encode_Map()

int BSLX_CoseMsg_Headers_Encode_Map ( QCBOREncodeContext *  enc,
const BSLX_CoseMsg_HdrMapTree_t map 
)

Encode a header parameter map.

Matches BSL_CBOR_Encode_f signature.

References BSL_IdValPair_Encode(), and BSL_SUCCESS.

Referenced by BSLX_CoseMsg_Headers_DerivePhdr(), and BSLX_CoseMsg_Headers_Encode().

◆ BSLX_CoseMsg_Headers_Get()

const BSL_IdValPair_t * BSLX_CoseMsg_Headers_Get ( const BSLX_CoseMsg_Headers_t obj,
int64_t  label,
bool  need_phdr 
)

Get a desired header parameter.

Parameters
[in]objThe headers to search.
labelThe label to search for.
need_phdrIf true the parameter needs to be in the protected map when it is present. This does not imply that it needs to be present.
Returns
Non-null pointer when found, or NULL if not found.

References BSL_LOG_ERR, BSLX_CoseMsg_Headers_t::phdr, and BSLX_CoseMsg_Headers_t::uhdr.

Referenced by BSLX_CoseMsg_Headers_CheckCrit(), BSLX_CoseSc_ExtractIV(), BSLX_CoseSc_GetAndValidateKey(), BSLX_CoseSc_GetAndValidateTarget(), and BSLX_CoseSc_HkdfContentKey().

◆ BSLX_CoseMsg_Headers_Init()

◆ BSLX_CoseMsg_Mac0_Decode()

◆ BSLX_CoseMsg_Mac0_Deinit()

◆ BSLX_CoseMsg_Mac0_Encode()

int BSLX_CoseMsg_Mac0_Encode ( QCBOREncodeContext *  enc,
const BSLX_CoseMsg_Mac0_t obj 
)

◆ BSLX_CoseMsg_Mac0_Init()

◆ BSLX_CoseMsg_Mac_Decode()

◆ BSLX_CoseMsg_Mac_Deinit()

◆ BSLX_CoseMsg_Mac_Encode()

◆ BSLX_CoseMsg_Mac_Init()

◆ BSLX_CoseMsg_Recipient_Decode()

◆ BSLX_CoseMsg_Recipient_Deinit()

◆ BSLX_CoseMsg_Recipient_Encode()

◆ BSLX_CoseMsg_Recipient_Init()

◆ BSLX_CoseMsg_RecipientList_ResizeNew()

void BSLX_CoseMsg_RecipientList_ResizeNew ( BSLX_CoseMsg_RecipientList_t  obj,
size_t  size 
)

Resize recipients array, preserving existing if possible.

References ASSERT_ARG_NONNULL.

Referenced by BSLX_CoseMsg_RecipientList_Decode(), BSLX_CoseSc_Encrypt_Source(), and BSLX_CoseSc_Mac_Source().