Wrapper

include/drip/wrapper.h

Structures and Types

Type	Name
typedef int(*	drip_wrapper_sign_cb_t Callback function type for producing wrapper signatures.
struct	drip_wrapper_t
typedef int(*	drip_wrapper_verify_cb_t Callback function type for verifying wrapper signatures.

Functions

Type	Name
int	drip_wrapper_add_evidence (drip_wrapper_t *wrapper, const uint8_t *buffer, size_t buffer_size) Add a 25-byte ASTM message to the wrapper evidence.
int	drip_wrapper_decode (drip_wrapper_t *wrapper, const uint8_t *buffer, size_t buffer_size) Decode a wrapper from its wire format.
int	drip_wrapper_encode (const drip_wrapper_t *wrapper, uint8_t *buffer, size_t buffer_size, size_t *encoded_length)
uint8_t	drip_wrapper_evidence_count (const drip_wrapper_t *wrapper) Get the evidence count.
const drip_det_t *	drip_wrapper_get_det (const drip_wrapper_t *wrapper)
const uint8_t *	drip_wrapper_get_evidence_at (const drip_wrapper_t *wrapper, uint8_t index)
const drip_signature_t *	drip_wrapper_get_signature (const drip_wrapper_t *wrapper)
uint32_t	drip_wrapper_get_vna (const drip_wrapper_t *wrapper) Get the vna timestamp.
uint32_t	drip_wrapper_get_vna_unixtime (const drip_wrapper_t *wrapper) Get the vna as a unix timestamp.
uint32_t	drip_wrapper_get_vnb (const drip_wrapper_t *wrapper) Get the vnb timestamp.
uint32_t	drip_wrapper_get_vnb_unixtime (const drip_wrapper_t *wrapper) Get the vnb as a unix timestamp.
int	drip_wrapper_init (drip_wrapper_t *wrapper)
int	drip_wrapper_set_det (drip_wrapper_t *wrapper, const drip_det_t *det)
int	drip_wrapper_set_signature (drip_wrapper_t *wrapper, const drip_signature_t *signature)
int	drip_wrapper_set_vna (drip_wrapper_t *wrapper, uint32_t vna) Set the vna timestamp.
int	drip_wrapper_set_vna_unixtime (drip_wrapper_t *wrapper, uint32_t unixtime) Set the vna from unix timestamp.
int	drip_wrapper_set_vnb (drip_wrapper_t *wrapper, uint32_t vnb) Set the vnb timestamp.
int	drip_wrapper_set_vnb_unixtime (drip_wrapper_t *wrapper, uint32_t unixtime) Set the vnb from unix timestamp.
int	drip_wrapper_sign (drip_wrapper_t *wrapper, drip_wrapper_sign_cb_t callback, void *context) Sign a wrapper with caller supplied callback.
int	drip_wrapper_to_json (const drip_wrapper_t *wrapper, char *buffer, size_t buffer_size, size_t *json_length) Serialize a DRIP wrapper to a JSON string.
int	drip_wrapper_validate (const drip_wrapper_t *wrapper) Validate the structural state of a wrapper.
int	drip_wrapper_verify (drip_wrapper_t *wrapper, drip_wrapper_verify_cb_t callback, void *context) Verify a wrapper with caller supplied callback.

Macros

Type	Name
define	DRIP_SAM_TYPE_SIZE 1
define	DRIP_TIMESTAMP_SIZE 4
define	DRIP_WRAPPER_EVIDENCE_MAX 4 /* 0..4 messages */
define	DRIP_WRAPPER_EVIDENCE_SIZE 112
define	DRIP_WRAPPER_MAX_SIZE 189 /* When four messages. */
define	DRIP_WRAPPER_MIN_SIZE 89 /* When zero messages. */
define	RID_MESSAGE_SIZE 25

Structures and Types Documentation

typedef drip_wrapper_sign_cb_t

Callback function type for producing wrapper signatures.

typedef int(* drip_wrapper_sign_cb_t) (void *context, const uint8_t *input, size_t input_length, uint8_t *buffer, size_t buffer_size, size_t *output_length);

Called by drip_wrapper_sign() to perform the actual signing of the payload.

Parameters:

• context Opaque context passed to the callback.
• input Pointer to the payload to sign.
• input_length Length of the payload in bytes.
• buffer Output buffer for the signature.
• buffer_size Size of the signature buffer in bytes.
• output_length Receives resulting signature length written.

Return value:

• 0 on success.
• Non-zero on signing failure.

struct drip_wrapper_t

Variables:

• drip_det_t det

• uint8_t evidence

• uint8_t evidence_count

• uint8_t sam_type

• drip_signature_t signature

• uint32_t vna

• uint32_t vnb

typedef drip_wrapper_verify_cb_t

Callback function type for verifying wrapper signatures.

typedef int(* drip_wrapper_verify_cb_t) (void *context, const uint8_t *input, size_t input_length, const uint8_t *signature, size_t signature_length);

Called by drip_wrapper_verify() to perform the actual verification of the signed payload.

Parameters:

• context Opaque context passed to the callback.
• input Pointer to the signed payload data.
• input_length Length of the signed payload in bytes.
• signature Pointer to the signature to verify against.
• signature_length Length of the signature in bytes.

Return value:

• 0 on success.
• Non-zero on verification failure.

Functions Documentation

function drip_wrapper_add_evidence

Add a 25-byte ASTM message to the wrapper evidence.

int drip_wrapper_add_evidence (
    drip_wrapper_t *wrapper,
    const uint8_t *buffer,
    size_t buffer_size
) 

Only ASTM Message Types 0x0 0x1 0x3 0x4 and 0x5 are allowed.

Parameters:

• wrapper Pointer to the wrapper to modify.
• buffer Pointer to a 25-byte ASTM message.
• buffer_size Size of buffer in bytes. Must be RID_MESSAGE_SIZE.

Return value:

• DRIP_SUCCESS if the message was added to the wrapper.
• DRIP_ERROR_NULL_POINTER if wrapper or buffer is NULL.
• DRIP_ERROR_INVALID_LENGTH if buffer_size is not RID_MESSAGE_SIZE.
• DRIP_ERROR_INVALID_MESSAGE_TYPE if the given ASTM message type is not allowed.
• DRIP_ERROR_ARRAY_OVERFLOW if evidence_count would exceed DRIP_WRAPPER_EVIDENCE_MAX.

See also: https://www.rfc-editor.org/rfc/rfc9575.html#section-4.3

function drip_wrapper_decode

Decode a wrapper from its wire format.

int drip_wrapper_decode (
    drip_wrapper_t *wrapper,
    const uint8_t *buffer,
    size_t buffer_size
) 

The buffer must contain only the bytes for the wrapper and nothing else.

Parameters:

• wrapper Pointer to the wrapper that receives the decoded data.
• buffer Input buffer holding the wire format bytes.
• buffer_size Size of buffer in bytes.

Return value:

• DRIP_SUCCESS on success.
• DRIP_ERROR_NULL_POINTER if wrapper or buffer is NULL.
• DRIP_ERROR_BUFFER_TOO_SMALL if buffer_size is less than DRIP_WRAPPER_MIN_SIZE.
• DRIP_ERROR_INVALID_LENGTH if the evidence payload length is not a multiple of RID_MESSAGE_SIZE.
• DRIP_ERROR_ARRAY_OVERFLOW if the evidence count would exceed DRIP_wrapper_EVIDENCE_MAX.
• DRIP_ERROR_INVALID_SAM_TYPE if the decoded SAM type is not DRIP_SAM_TYPE_WRAPPER.

function drip_wrapper_encode

int drip_wrapper_encode (
    const drip_wrapper_t *wrapper,
    uint8_t *buffer,
    size_t buffer_size,
    size_t *encoded_length
) 

function drip_wrapper_evidence_count

Get the evidence count.

uint8_t drip_wrapper_evidence_count (
    const drip_wrapper_t *wrapper
) 

Parameters:

• wrapper Pointer to the wrapper.

Returns:

The evidence count or 0 if wrapper is NULL.

function drip_wrapper_get_det

const drip_det_t * drip_wrapper_get_det (
    const drip_wrapper_t *wrapper
) 

function drip_wrapper_get_evidence_at

const uint8_t * drip_wrapper_get_evidence_at (
    const drip_wrapper_t *wrapper,
    uint8_t index
) 

function drip_wrapper_get_signature

const drip_signature_t * drip_wrapper_get_signature (
    const drip_wrapper_t *wrapper
) 

function drip_wrapper_get_vna

Get the vna timestamp.

uint32_t drip_wrapper_get_vna (
    const drip_wrapper_t *wrapper
) 

Returned as seconds since DRIP_TIMESTAMP_EPOCH.

Parameters:

• wrapper Pointer to the wrapper.

Returns:

The vna timestamp or 0 if wrapper is NULL.

function drip_wrapper_get_vna_unixtime

Get the vna as a unix timestamp.

uint32_t drip_wrapper_get_vna_unixtime (
    const drip_wrapper_t *wrapper
) 

Parameters:

• wrapper Pointer to the wrapper.

Returns:

The vna as unix timestamp or 0 if wrapper is NULL.

function drip_wrapper_get_vnb

Get the vnb timestamp.

uint32_t drip_wrapper_get_vnb (
    const drip_wrapper_t *wrapper
) 

Returned as seconds since DRIP_TIMESTAMP_EPOCH.

Parameters:

• wrapper Pointer to the wrapper.

Returns:

The vnb timestamp or 0 if wrapper is NULL.

function drip_wrapper_get_vnb_unixtime

Get the vnb as a unix timestamp.

uint32_t drip_wrapper_get_vnb_unixtime (
    const drip_wrapper_t *wrapper
) 

Parameters:

• wrapper Pointer to the wrapper.

Returns:

The vnb as unix timestamp or 0 if wrapper is NULL.

function drip_wrapper_init

int drip_wrapper_init (
    drip_wrapper_t *wrapper
) 

function drip_wrapper_set_det

int drip_wrapper_set_det (
    drip_wrapper_t *wrapper,
    const drip_det_t *det
) 

function drip_wrapper_set_signature

int drip_wrapper_set_signature (
    drip_wrapper_t *wrapper,
    const drip_signature_t *signature
) 

function drip_wrapper_set_vna

Set the vna timestamp.

int drip_wrapper_set_vna (
    drip_wrapper_t *wrapper,
    uint32_t vna
) 

Stored internally as seconds since DRIP_TIMESTAMP_EPOCH.

Parameters:

• wrapper Pointer to the wrapper to modify.
• vna Offset from DRIP_TIMESTAMP_EPOCH in seconds.

Return value:

• DRIP_SUCCESS if vna was stored.
• DRIP_ERROR_NULL_POINTER if wrapper is NULL.
• DRIP_ERROR_OUT_OF_RANGE if vna > UINT32_MAX - DRIP_TIMESTAMP_EPOCH.

function drip_wrapper_set_vna_unixtime

Set the vna from unix timestamp.

int drip_wrapper_set_vna_unixtime (
    drip_wrapper_t *wrapper,
    uint32_t unixtime
) 

Parameters:

• wrapper Pointer to the wrapper to modify.
• unixtime Unix timestamp in seconds.

Return value:

• DRIP_SUCCESS if vna was stored.
• DRIP_ERROR_NULL_POINTER if wrapper is NULL.
• DRIP_ERROR_OUT_OF_RANGE if unixtime < DRIP_TIMESTAMP_EPOCH.

function drip_wrapper_set_vnb

Set the vnb timestamp.

int drip_wrapper_set_vnb (
    drip_wrapper_t *wrapper,
    uint32_t vnb
) 

Stored internally as seconds since DRIP_TIMESTAMP_EPOCH.

Parameters:

• wrapper Pointer to the wrapper to modify.
• vnb Offset from DRIP_TIMESTAMP_EPOCH in seconds.

Return value:

• DRIP_SUCCESS if vnb was stored.
• DRIP_ERROR_NULL_POINTER if wrapper is NULL.
• DRIP_ERROR_OUT_OF_RANGE if vnb > UINT32_MAX - DRIP_TIMESTAMP_EPOCH.

function drip_wrapper_set_vnb_unixtime

Set the vnb from unix timestamp.

int drip_wrapper_set_vnb_unixtime (
    drip_wrapper_t *wrapper,
    uint32_t unixtime
) 

Parameters:

• wrapper Pointer to the wrapper to modify.
• unixtime Unix timestamp in seconds.

Return value:

• DRIP_SUCCESS if vnb was stored.
• DRIP_ERROR_NULL_POINTER if wrapper is NULL.
• DRIP_ERROR_OUT_OF_RANGE if unixtime < DRIP_TIMESTAMP_EPOCH.

function drip_wrapper_sign

Sign a wrapper with caller supplied callback.

int drip_wrapper_sign (
    drip_wrapper_t *wrapper,
    drip_wrapper_sign_cb_t callback,
    void *context
) 

Validates the wrapper with drip_wrapper_validate() before signing. The callback is not called if validation fails.

Parameters:

• wrapper Pointer to the wrapper to be signed.
• callback Callback function used to generate the signature.
• context Opaque context passed to the callback.

Return value:

• DRIP_SUCCESS if signing succeeded.
• DRIP_ERROR_NULL_POINTER if wrapper or callback is NULL.
• DRIP_ERROR_INVALID_SAM_TYPE if sam_type is not DRIP_SAM_TYPE_WRAPPER.
• DRIP_ERROR_INVALID_TIMESTAMP if vnb > vna.
• DRIP_ERROR_ARRAY_OVERFLOW if evidence_count exceeds DRIP_WRAPPER_EVIDENCE_MAX.
• DRIP_ERROR_INVALID_MESSAGE_TYPE if an evidence message type is not 0x0 0x1 0x3 0x4 or 0x5.
• DRIP_ERROR_INVALID_DET if det fails drip_det_validate().
• DRIP_ERROR_CALLBACK_FAILED if callback returned non-zero.
• DRIP_ERROR_INVALID_LENGTH if the signature is not DRIP_SIGNATURE_SIZE.

function drip_wrapper_to_json

Serialize a DRIP wrapper to a JSON string.

int drip_wrapper_to_json (
    const drip_wrapper_t *wrapper,
    char *buffer,
    size_t buffer_size,
    size_t *json_length
) 

On success writes a NULL terminated JSON to buffer. When buffer_size is too small the output is truncated and DRIP_ERROR_BUFFER_TOO_SMALL is returned. The truncated buffer is still NULL terminated.

Parameters:

• wrapper Pointer to the wrapper to serialize.
• buffer Output buffer for the JSON representation.
• buffer_size Size of buffer in bytes.
• json_length Optional. Receives receives the number of characters for the full non truncated output. Ignored if NULL.

Return value:

• DRIP_SUCCESS on success.
• DRIP_ERROR_NULL_POINTER if wrapper or buffer is NULL.
• DRIP_ERROR_BUFFER_TOO_SMALL if buffer_size is too small.

function drip_wrapper_validate

Validate the structural state of a wrapper.

int drip_wrapper_validate (
    const drip_wrapper_t *wrapper
) 

Performs structural checks only. Does not verify the signature.

Parameters:

• wrapper Pointer to the wrapper to validate.

Return value:

• DRIP_SUCCESS if wrapper is structurally valid.
• DRIP_ERROR_NULL_POINTER if wrapper is NULL.
• DRIP_ERROR_INVALID_SAM_TYPE if sam_type is not DRIP_SAM_TYPE_WRAPPER.
• DRIP_ERROR_INVALID_TIMESTAMP if vnb > vna.
• DRIP_ERROR_ARRAY_OVERFLOW if evidence_count exceeds DRIP_WRAPPER_EVIDENCE_MAX.
• DRIP_ERROR_INVALID_MESSAGE_TYPE if an evidence message type is not 0x0 0x1 0x3 0x4 or 0x5.
• DRIP_ERROR_INVALID_DET if det fails drip_det_validate().

function drip_wrapper_verify

Verify a wrapper with caller supplied callback.

int drip_wrapper_verify (
    drip_wrapper_t *wrapper,
    drip_wrapper_verify_cb_t callback,
    void *context
) 

Validates the wrapper with drip_wrapper_validate() before verifying. The callback is not called if validation fails.

Parameters:

• wrapper Pointer to the wrapper to be verified.
• callback Callback function used to verify the signature.
• context Opaque context passed to the callback.

Return value:

• DRIP_SUCCESS if verification succeeded.
• DRIP_ERROR_NULL_POINTER if wrapper or callback is NULL.
• DRIP_ERROR_INVALID_SAM_TYPE if sam_type is not DRIP_SAM_TYPE_WRAPPER.
• DRIP_ERROR_INVALID_TIMESTAMP if vnb > vna.
• DRIP_ERROR_ARRAY_OVERFLOW if evidence_count exceeds DRIP_WRAPPER_EVIDENCE_MAX.
• DRIP_ERROR_INVALID_MESSAGE_TYPE if an evidence message type is not 0x0 0x1 0x3 0x4 or 0x5.
• DRIP_ERROR_INVALID_DET if det fails drip_det_validate().
• DRIP_ERROR_CALLBACK_FAILED if callback returned non-zero.

Macros Documentation

define DRIP_SAM_TYPE_SIZE

#define DRIP_SAM_TYPE_SIZE 1

define DRIP_TIMESTAMP_SIZE

#define DRIP_TIMESTAMP_SIZE 4

define DRIP_WRAPPER_EVIDENCE_MAX

#define DRIP_WRAPPER_EVIDENCE_MAX 4 /* 0..4 messages */

define DRIP_WRAPPER_EVIDENCE_SIZE

#define DRIP_WRAPPER_EVIDENCE_SIZE 112

define DRIP_WRAPPER_MAX_SIZE

#define DRIP_WRAPPER_MAX_SIZE 189 /* When four messages. */

define DRIP_WRAPPER_MIN_SIZE

#define DRIP_WRAPPER_MIN_SIZE 89 /* When zero messages. */

define RID_MESSAGE_SIZE

#define RID_MESSAGE_SIZE 25