File syn_cose.h

FileList > proto > syn_cose.h

Go to the source code of this file

Zero-Heap CBOR Object Signing and Encryption (COSE - RFC 9052 / RFC 8152). More...

• #include "syntropic/common/syn_defs.h"
• #include "syntropic/crypto/syn_aes.h"
• #include "syntropic/crypto/syn_chacha20poly1305.h"
• #include "syntropic/crypto/syn_ed25519.h"
• #include "syntropic/crypto/syn_hmac.h"
• #include "syntropic/crypto/syn_p256.h"
• #include "syntropic/crypto/syn_sha256.h"
• #include "syntropic/util/syn_cbor_read.h"
• #include "syntropic/util/syn_cbor_write.h"
• #include <stdbool.h>
• #include <stddef.h>
• #include <stdint.h>

Classes

Type	Name
struct	SYN_COSE_Encrypt0Message Parsed COSE_Encrypt0 Message descriptor.
struct	SYN_COSE_Key COSE_Key representation structure (RFC 9052 / RFC 9053).
struct	SYN_COSE_Mac0Message Parsed COSE_Mac0 Message descriptor (Tag 17).
struct	SYN_COSE_Sign1Message Parsed COSE_Sign1 Message descriptor.

Public Types

Type	Name
enum	SYN_COSE_Algorithm COSE Algorithm Identifiers.
enum	SYN_COSE_Curve COSE Elliptic Curves (crv)
enum	SYN_COSE_KeyType COSE Key Types (kty)

Public Functions

Type	Name
SYN_Status	syn_cose_encrypt0_create (SYN_COSE_Algorithm alg, const uint8_t * key, const uint8_t * iv, size_t iv_len, const uint8_t * kid, size_t kid_len, const uint8_t * plaintext, size_t plaintext_len, const uint8_t * external_aad, size_t external_aad_len, uint8_t * out_buf, size_t out_buf_size, size_t * out_len) Encrypt a payload into a COSE_Encrypt0 (Tag 16) message using ChaCha20/Poly1305.
SYN_Status	syn_cose_encrypt0_decrypt (const uint8_t * msg, size_t msg_len, const uint8_t * key, const uint8_t * external_aad, size_t external_aad_len, uint8_t * out_plaintext, size_t out_plaintext_size, size_t * out_plaintext_len, SYN_COSE_Encrypt0Message * parsed_out) Decrypt and verify a COSE_Encrypt0 message.
SYN_Status	syn_cose_key_decode (const uint8_t * buf, size_t buf_len, SYN_COSE_Key * key_out) Decode a CBOR-encoded COSE_Key map into a SYN_COSE_Key structure.
SYN_Status	syn_cose_key_encode (const SYN_COSE_Key * key, uint8_t * out_buf, size_t out_buf_size, size_t * out_len) Encode a COSE_Key structure into CBOR format.
SYN_Status	syn_cose_mac0_create (SYN_COSE_Algorithm alg, const uint8_t * key, size_t key_len, const uint8_t * kid, size_t kid_len, const uint8_t * payload, size_t payload_len, const uint8_t * external_aad, size_t external_aad_len, uint8_t * out_buf, size_t out_buf_size, size_t * out_len) Create a COSE_Mac0 (Tag 17) message using HMAC-SHA256.
SYN_Status	syn_cose_mac0_verify (const uint8_t * msg, size_t msg_len, const uint8_t * key, size_t key_len, const uint8_t * external_aad, size_t external_aad_len, SYN_COSE_Mac0Message * parsed_out) Verify a COSE_Mac0 message using HMAC-SHA256.
SYN_Status	syn_cose_sign1_create (SYN_COSE_Algorithm alg, const uint8_t * secret_key, const uint8_t * public_key, const uint8_t * kid, size_t kid_len, const uint8_t * payload, size_t payload_len, const uint8_t * external_aad, size_t external_aad_len, uint8_t * out_buf, size_t out_buf_size, size_t * out_len) Create a COSE_Sign1 (Tag 18) message signed with EdDSA (Ed25519) or ES256 (P-256).
SYN_Status	syn_cose_sign1_verify (const uint8_t * msg, size_t msg_len, const uint8_t * public_key, size_t public_key_len, const uint8_t * external_aad, size_t external_aad_len, SYN_COSE_Sign1Message * parsed_out) Parse and verify a COSE_Sign1 message using the signer's public key.

Macros

Type	Name
define	SYN_COSE_HEADER_ALG 1 Header parameter label for algorithm identifier (1).
define	SYN_COSE_HEADER_CONTENT_TYPE 3 Header parameter label for content type (3).
define	SYN_COSE_HEADER_CRIT 2 Header parameter label for criticality (2).
define	SYN_COSE_HEADER_IV 5 Header parameter label for initialization vector / nonce (5).
define	SYN_COSE_HEADER_KID 4 Header parameter label for key identifier (4).
define	SYN_COSE_HEADER_PARTIAL_IV 6 Header parameter label for partial IV (6).
define	SYN_COSE_KEY_ALG 3 Key parameter label for key algorithm identifier (3).
define	SYN_COSE_KEY_CRV (-1) Key parameter label for elliptic curve identifier (-1).
define	SYN_COSE_KEY_D (-4) Key parameter label for private key / secret exponent (-4).
define	SYN_COSE_KEY_K (-1) Key parameter label for symmetric key octet sequence (-1).
define	SYN_COSE_KEY_KID 2 Key parameter label for key identification value (2).
define	SYN_COSE_KEY_KTY 1 Key parameter label for identification of the key type (1).
define	SYN_COSE_KEY_X (-2) Key parameter label for public key x-coordinate or OKP public key (-2).
define	SYN_COSE_KEY_Y (-3) Key parameter label for public key y-coordinate (-3).
define	SYN_COSE_MAX_IV_LEN 16U Maximum IV length (16 bytes).
define	SYN_COSE_MAX_KID_LEN 32U Maximum key ID length (32 bytes).
define	SYN_COSE_MAX_PROTECTED_LEN 64U Maximum protected header byte length (64 bytes).
define	SYN_COSE_MAX_SIG_LEN 64U Maximum signature length in bytes (64 bytes for Ed25519 / P-256).
define	SYN_COSE_MAX_TAG_LEN 32U Maximum MAC tag length in bytes (32 bytes for HMAC-256/256).

Detailed Description

Implements COSE_Sign1 (Tag 18) and COSE_Encrypt0 (Tag 16) for constrained IoT nodes. Supported Cryptographic Algorithms: * EdDSA (-8): Pure C99 Ed25519 signature scheme (RFC 8032). * ES256 (-7): ECDSA over NIST P-256 curve with SHA-256 (RFC 9053). * ChaCha20/Poly1305 (24): Authenticated encryption with associated data (RFC 9053).

Public Types Documentation

enum SYN_COSE_Algorithm

COSE Algorithm Identifiers.

enum SYN_COSE_Algorithm {
    SYN_COSE_ALGO_UNKNOWN = 0,
    SYN_COSE_ALGO_A128GCM = 1,
    SYN_COSE_ALGO_A192GCM = 2,
    SYN_COSE_ALGO_A256GCM = 3,
    SYN_COSE_ALGO_HMAC_256_64 = 4,
    SYN_COSE_ALGO_HMAC_256_256 = 5,
    SYN_COSE_ALGO_AES_CCM_16_64_128 =
        10,
    SYN_COSE_ALGO_AES_CCM_16_64_256 =
        11,
    SYN_COSE_ALGO_CHACHA20_POLY1305 = 24,
    SYN_COSE_ALGO_AES_CCM_16_128_128 =
        30,
    SYN_COSE_ALGO_AES_CCM_16_128_256 =
        31,
    SYN_COSE_ALGO_ES256 = -7,
    SYN_COSE_ALGO_EDDSA = -8
};

---

enum SYN_COSE_Curve

COSE Elliptic Curves (crv)

enum SYN_COSE_Curve {
    SYN_COSE_CRV_RESERVED = 0,
    SYN_COSE_CRV_P256 = 1,
    SYN_COSE_CRV_ED25519 = 6
};

---

enum SYN_COSE_KeyType

COSE Key Types (kty)

enum SYN_COSE_KeyType {
    SYN_COSE_KTY_RESERVED = 0,
    SYN_COSE_KTY_OKP = 1,
    SYN_COSE_KTY_EC2 = 2,
    SYN_COSE_KTY_SYMMETRIC = 4
};

---

Public Functions Documentation

function syn_cose_encrypt0_create

Encrypt a payload into a COSE_Encrypt0 (Tag 16) message using ChaCha20/Poly1305.

SYN_Status syn_cose_encrypt0_create (
    SYN_COSE_Algorithm alg,
    const uint8_t * key,
    const uint8_t * iv,
    size_t iv_len,
    const uint8_t * kid,
    size_t kid_len,
    const uint8_t * plaintext,
    size_t plaintext_len,
    const uint8_t * external_aad,
    size_t external_aad_len,
    uint8_t * out_buf,
    size_t out_buf_size,
    size_t * out_len
) 

Parameters:

• alg Encryption algorithm (SYN_COSE_ALGO_CHACHA20_POLY1305).
• key Symmetric key (32 bytes).
• iv Nonce / IV (12 bytes for ChaCha20/Poly1305).
• iv_len IV length.
• kid Optional key identifier (NULL if unused).
• kid_len Key identifier length.
• plaintext Plaintext payload to encrypt.
• plaintext_len Plaintext length.
• external_aad Optional external associated data (NULL if unused).
• external_aad_len External AAD length.
• out_buf [out] Output buffer for encoded COSE_Encrypt0 message.
• out_buf_size Capacity of output buffer.
• out_len [out] Number of bytes written to output buffer.

Returns:

SYN_Status SYN_OK on success, error code otherwise.

---

function syn_cose_encrypt0_decrypt

Decrypt and verify a COSE_Encrypt0 message.

SYN_Status syn_cose_encrypt0_decrypt (
    const uint8_t * msg,
    size_t msg_len,
    const uint8_t * key,
    const uint8_t * external_aad,
    size_t external_aad_len,
    uint8_t * out_plaintext,
    size_t out_plaintext_size,
    size_t * out_plaintext_len,
    SYN_COSE_Encrypt0Message * parsed_out
) 

Parameters:

• msg Raw COSE_Encrypt0 CBOR encoded message.
• msg_len Message length.
• key Symmetric key (32 bytes).
• external_aad Optional external associated data (NULL if unused).
• external_aad_len External AAD length.
• out_plaintext [out] Output buffer for decrypted plaintext.
• out_plaintext_size Output buffer capacity.
• out_plaintext_len [out] Number of plaintext bytes written.
• parsed_out [out] Optional parsed message details (may be NULL).

Returns:

SYN_Status SYN_OK if decrypted and authenticated, error code otherwise.

---

function syn_cose_key_decode

Decode a CBOR-encoded COSE_Key map into a SYN_COSE_Key structure.

SYN_Status syn_cose_key_decode (
    const uint8_t * buf,
    size_t buf_len,
    SYN_COSE_Key * key_out
) 

Parameters:

• buf Input CBOR buffer.
• buf_len Length of CBOR buffer.
• key_out [out] Decoded key descriptor.

Returns:

SYN_Status SYN_OK on success, error code otherwise.

---

function syn_cose_key_encode

Encode a COSE_Key structure into CBOR format.

SYN_Status syn_cose_key_encode (
    const SYN_COSE_Key * key,
    uint8_t * out_buf,
    size_t out_buf_size,
    size_t * out_len
) 

Parameters:

• key Pointer to populated COSE_Key descriptor.
• out_buf [out] Output buffer for encoded CBOR map.
• out_buf_size Capacity of output buffer.
• out_len [out] Number of bytes written.

Returns:

SYN_Status SYN_OK on success, error code otherwise.

---

function syn_cose_mac0_create

Create a COSE_Mac0 (Tag 17) message using HMAC-SHA256.

SYN_Status syn_cose_mac0_create (
    SYN_COSE_Algorithm alg,
    const uint8_t * key,
    size_t key_len,
    const uint8_t * kid,
    size_t kid_len,
    const uint8_t * payload,
    size_t payload_len,
    const uint8_t * external_aad,
    size_t external_aad_len,
    uint8_t * out_buf,
    size_t out_buf_size,
    size_t * out_len
) 

Parameters:

• alg MAC algorithm (SYN_COSE_ALGO_HMAC_256_256 or SYN_COSE_ALGO_HMAC_256_64).
• key MAC key.
• key_len Key length in bytes.
• kid Optional key identifier (NULL if unused).
• kid_len Key identifier length.
• payload Message payload to authenticate.
• payload_len Payload length.
• external_aad Optional external associated data (NULL if unused).
• external_aad_len External AAD length.
• out_buf [out] Output buffer for encoded COSE_Mac0 message.
• out_buf_size Capacity of output buffer.
• out_len [out] Number of bytes written to output buffer.

Returns:

SYN_Status SYN_OK on success, error code otherwise.

---

function syn_cose_mac0_verify

Verify a COSE_Mac0 message using HMAC-SHA256.

SYN_Status syn_cose_mac0_verify (
    const uint8_t * msg,
    size_t msg_len,
    const uint8_t * key,
    size_t key_len,
    const uint8_t * external_aad,
    size_t external_aad_len,
    SYN_COSE_Mac0Message * parsed_out
) 

Parameters:

• msg Raw COSE_Mac0 CBOR encoded message.
• msg_len Message length.
• key MAC key.
• key_len Key length in bytes.
• external_aad Optional external associated data (NULL if unused).
• external_aad_len External AAD length.
• parsed_out [out] Optional parsed message details (may be NULL).

Returns:

SYN_Status SYN_OK if authentication tag is valid, error code otherwise.

---

function syn_cose_sign1_create

Create a COSE_Sign1 (Tag 18) message signed with EdDSA (Ed25519) or ES256 (P-256).

SYN_Status syn_cose_sign1_create (
    SYN_COSE_Algorithm alg,
    const uint8_t * secret_key,
    const uint8_t * public_key,
    const uint8_t * kid,
    size_t kid_len,
    const uint8_t * payload,
    size_t payload_len,
    const uint8_t * external_aad,
    size_t external_aad_len,
    uint8_t * out_buf,
    size_t out_buf_size,
    size_t * out_len
) 

Parameters:

• alg Signature algorithm (SYN_COSE_ALGO_EDDSA or SYN_COSE_ALGO_ES256).
• secret_key Secret key (32 bytes for Ed25519 / P-256 scalar).
• public_key Public key (32 bytes for Ed25519, 64/65 bytes for P-256).
• kid Optional key identifier (NULL if unused).
• kid_len Key identifier length.
• payload Message payload to sign.
• payload_len Payload length.
• external_aad Optional external associated data (NULL if unused).
• external_aad_len External AAD length.
• out_buf [out] Output buffer for encoded COSE_Sign1 message.
• out_buf_size Capacity of output buffer.
• out_len [out] Number of bytes written to output buffer.

Returns:

SYN_Status SYN_OK on success, error code otherwise.

---

function syn_cose_sign1_verify

Parse and verify a COSE_Sign1 message using the signer's public key.

SYN_Status syn_cose_sign1_verify (
    const uint8_t * msg,
    size_t msg_len,
    const uint8_t * public_key,
    size_t public_key_len,
    const uint8_t * external_aad,
    size_t external_aad_len,
    SYN_COSE_Sign1Message * parsed_out
) 

Parameters:

• msg Raw COSE_Sign1 CBOR encoded message.
• msg_len Message length.
• public_key Public key of the signer.
• public_key_len Public key length (32 for Ed25519, 64/65 for P-256).
• external_aad Optional external associated data (NULL if unused).
• external_aad_len External AAD length.
• parsed_out [out] Optional parsed message details (may be NULL).

Returns:

SYN_Status SYN_OK if verified and valid, error code otherwise.

---

Macro Definition Documentation

define SYN_COSE_HEADER_ALG

Header parameter label for algorithm identifier (1).

#define SYN_COSE_HEADER_ALG `1`

---

define SYN_COSE_HEADER_CONTENT_TYPE

Header parameter label for content type (3).

#define SYN_COSE_HEADER_CONTENT_TYPE `3`

---

define SYN_COSE_HEADER_CRIT

Header parameter label for criticality (2).

#define SYN_COSE_HEADER_CRIT `2`

---

define SYN_COSE_HEADER_IV

Header parameter label for initialization vector / nonce (5).

#define SYN_COSE_HEADER_IV `5`

---

define SYN_COSE_HEADER_KID

Header parameter label for key identifier (4).

#define SYN_COSE_HEADER_KID `4`

---

define SYN_COSE_HEADER_PARTIAL_IV

Header parameter label for partial IV (6).

#define SYN_COSE_HEADER_PARTIAL_IV `6`

---

define SYN_COSE_KEY_ALG

Key parameter label for key algorithm identifier (3).

#define SYN_COSE_KEY_ALG `3`

---

define SYN_COSE_KEY_CRV

Key parameter label for elliptic curve identifier (-1).

#define SYN_COSE_KEY_CRV `(-1)`

---

define SYN_COSE_KEY_D

Key parameter label for private key / secret exponent (-4).

#define SYN_COSE_KEY_D `(-4)`

---

define SYN_COSE_KEY_K

Key parameter label for symmetric key octet sequence (-1).

#define SYN_COSE_KEY_K `(-1)`

---

define SYN_COSE_KEY_KID

Key parameter label for key identification value (2).

#define SYN_COSE_KEY_KID `2`

---

define SYN_COSE_KEY_KTY

Key parameter label for identification of the key type (1).

#define SYN_COSE_KEY_KTY `1`

---

define SYN_COSE_KEY_X

Key parameter label for public key x-coordinate or OKP public key (-2).

#define SYN_COSE_KEY_X `(-2)`

---

define SYN_COSE_KEY_Y

Key parameter label for public key y-coordinate (-3).

#define SYN_COSE_KEY_Y `(-3)`

---

define SYN_COSE_MAX_IV_LEN

Maximum IV length (16 bytes).

#define SYN_COSE_MAX_IV_LEN `16U`

---

define SYN_COSE_MAX_KID_LEN

Maximum key ID length (32 bytes).

#define SYN_COSE_MAX_KID_LEN `32U`

---

define SYN_COSE_MAX_PROTECTED_LEN

Maximum protected header byte length (64 bytes).

#define SYN_COSE_MAX_PROTECTED_LEN `64U`

---

define SYN_COSE_MAX_SIG_LEN

Maximum signature length in bytes (64 bytes for Ed25519 / P-256).

#define SYN_COSE_MAX_SIG_LEN `64U`

---

define SYN_COSE_MAX_TAG_LEN

Maximum MAC tag length in bytes (32 bytes for HMAC-256/256).

#define SYN_COSE_MAX_TAG_LEN `32U`

---

---

The documentation for this class was generated from the following file src/syntropic/proto/syn_cose.h