Link

include/drip/link.h

Structures and Types

Type	Name
typedef int(*	drip_link_sign_cb_t Callback function type for producing link signatures.
struct	drip_link_t
typedef int(*	drip_link_verify_cb_t Callback function type for verifying link signatures.

Functions

Type	Name
int	drip_link_decode (drip_link_t *link, const uint8_t *buffer, size_t buffer_size)
int	drip_link_encode (const drip_link_t *link, uint8_t *buffer, size_t buffer_size, size_t *encoded_length)
int	drip_link_filter_chain (const drip_link_t *in_array, size_t in_count, const drip_det_t *ua_det, drip_link_t *out_array, size_t out_capacity, size_t *out_count) Filter an array of DRIP Links that belong to the chain of a UA.
int	drip_link_from_endorsement (drip_link_t *link, const uint8_t *buffer, size_t buffer_size) Construct a DRIP Link from a Broadcast Endorsement.
const drip_det_t *	drip_link_get_child_det (const drip_link_t *link)
const drip_hi_t *	drip_link_get_child_hi (const drip_link_t *link)
const drip_det_t *	drip_link_get_parent_det (const drip_link_t *link)
const drip_signature_t *	drip_link_get_signature (const drip_link_t *link)
uint32_t	drip_link_get_vna (const drip_link_t *link) Get the vna timestamp.
uint32_t	drip_link_get_vna_unixtime (const drip_link_t *link) Get the vna as a unix timestamp.
uint32_t	drip_link_get_vnb (const drip_link_t *link) Get the vnb timestamp.
uint32_t	drip_link_get_vnb_unixtime (const drip_link_t *link) Get the vnb as a unix timestamp.
int	drip_link_init (drip_link_t *link)
int	drip_link_set_child_det (drip_link_t *link, const drip_det_t *det)
int	drip_link_set_child_hi (drip_link_t *link, const drip_hi_t *hi)
int	drip_link_set_parent_det (drip_link_t *link, const drip_det_t *det)
int	drip_link_set_signature (drip_link_t *link, const drip_signature_t *signature)
int	drip_link_set_vna (drip_link_t *link, uint32_t vna) Set the vna timestamp.
int	drip_link_set_vna_unixtime (drip_link_t *link, uint32_t unixtime) Set the vna from unix timestamp.
int	drip_link_set_vnb (drip_link_t *link, uint32_t vnb) Set the vnb timestamp.
int	drip_link_set_vnb_unixtime (drip_link_t *link, uint32_t unixtime) Set the vnb from unix timestamp.
int	drip_link_sign (drip_link_t *link, drip_link_sign_cb_t callback, void *context) Sign a DRIP Link.
int	drip_link_to_endorsement (const drip_link_t *link, uint8_t *buffer, size_t buffer_size) Extract a Broadcast Endorsement from a DRIP Link.
int	drip_link_to_json (const drip_link_t *link, char *buffer, size_t buffer_size, size_t *json_length) Serialize a DRIP link to a JSON string.
int	drip_link_validate (const drip_link_t *link) Validate the structural state of a DRIP Link.
int	drip_link_verify (const drip_link_t *link, uint32_t unixtime, drip_link_verify_cb_t callback, void *context) Verify the signature of a DRIP Link.
int	drip_link_verify_chain (const drip_link_t *link_array, size_t link_count, const drip_det_t *root_det, const drip_hi_t *root_hi, uint32_t unixtime, drip_hash_cb_t hash_cb, drip_link_verify_cb_t verify_cb) Verify a chain of DRIP Links from a trusted root.

Macros

Type	Name
define	DRIP_LINK_CHAIN_MAX_HOPS 8
define	DRIP_LINK_ENDORSEMENT_SIZE 136
define	DRIP_LINK_SIZE 137

Structures and Types Documentation

typedef drip_link_sign_cb_t

Callback function type for producing link signatures.

typedef int(* drip_link_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_link_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_link_t

Variables:

• drip_det_t child_det

• drip_hi_t child_hi

• drip_det_t parent_det

• uint8_t sam_type

• drip_signature_t signature

• uint32_t vna

• uint32_t vnb

typedef drip_link_verify_cb_t

Callback function type for verifying link signatures.

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

Called by drip_link_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_link_decode

int drip_link_decode (
    drip_link_t *link,
    const uint8_t *buffer,
    size_t buffer_size
) 

function drip_link_encode

int drip_link_encode (
    const drip_link_t *link,
    uint8_t *buffer,
    size_t buffer_size,
    size_t *encoded_length
) 

function drip_link_filter_chain

Filter an array of DRIP Links that belong to the chain of a UA.

int drip_link_filter_chain (
    const drip_link_t *in_array,
    size_t in_count,
    const drip_det_t *ua_det,
    drip_link_t *out_array,
    size_t out_capacity,
    size_t *out_count
) 

Use this to filter and sort an array of Links before passing them to drip_link_verify_chain() function. Output hops are in root-to-UA order. A self-signed Link is the root identity and is omitted. Structurally invalid Links are skipped.

Parameters:

• in_array Input array of Links.
• in_count Number of Links in in_array.
• ua_det UA DET to filter with.
• out_array Output array for the filtered chain.
• out_capacity Output array capacity.
• out_count Receives the number of hops written to the output array.

Return value:

• DRIP_SUCCESS on success including when result is a partial chain or an empty array.
• DRIP_ERROR_NULL_POINTER if in_array, ua_det, out_array or out_count is NULL.
• DRIP_ERROR_BUFFER_TOO_SMALL if out_capacity is too small.
• DRIP_ERROR_ARRAY_OVERFLOW if hops exceed DRIP_LINK_CHAIN_MAX_HOPS.

function drip_link_from_endorsement

Construct a DRIP Link from a Broadcast Endorsement.

int drip_link_from_endorsement (
    drip_link_t *link,
    const uint8_t *buffer,
    size_t buffer_size
) 

The endorsement is a 136-byte payload without SAM type. This simple helper just adds SAM Type 0x01 (DRIP_SAM_TYPE_LINK) in front of it.

Parameters:

• link Pointer to the DRIP Link to populate.
• buffer Pointer to the endorsement bytes.
• buffer_size Size of buffer in bytes. Must be at least DRIP_LINK_ENDORSEMENT_SIZE.

Return value:

• DRIP_SUCCESS if the link was constructed.
• DRIP_ERROR_NULL_POINTER if link or buffer is NULL.
• DRIP_ERROR_BUFFER_TOO_SMALL if buffer_size is less than DRIP_LINK_ENDORSEMENT_SIZE.

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

function drip_link_get_child_det

const drip_det_t * drip_link_get_child_det (
    const drip_link_t *link
) 

function drip_link_get_child_hi

const drip_hi_t * drip_link_get_child_hi (
    const drip_link_t *link
) 

function drip_link_get_parent_det

const drip_det_t * drip_link_get_parent_det (
    const drip_link_t *link
) 

function drip_link_get_signature

const drip_signature_t * drip_link_get_signature (
    const drip_link_t *link
) 

function drip_link_get_vna

Get the vna timestamp.

uint32_t drip_link_get_vna (
    const drip_link_t *link
) 

Returned as seconds since DRIP_TIMESTAMP_EPOCH.

Parameters:

• link Pointer to the link.

Returns:

The stored vna, or 0 if link is NULL.

function drip_link_get_vna_unixtime

Get the vna as a unix timestamp.

uint32_t drip_link_get_vna_unixtime (
    const drip_link_t *link
) 

Parameters:

• link Pointer to the link.

Returns:

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

function drip_link_get_vnb

Get the vnb timestamp.

uint32_t drip_link_get_vnb (
    const drip_link_t *link
) 

Returned as seconds since DRIP_TIMESTAMP_EPOCH.

Parameters:

• link Pointer to the link.

Returns:

The stored vnb, or 0 if link is NULL.

function drip_link_get_vnb_unixtime

Get the vnb as a unix timestamp.

uint32_t drip_link_get_vnb_unixtime (
    const drip_link_t *link
) 

Parameters:

• link Pointer to the link.

Returns:

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

function drip_link_init

int drip_link_init (
    drip_link_t *link
) 

function drip_link_set_child_det

int drip_link_set_child_det (
    drip_link_t *link,
    const drip_det_t *det
) 

function drip_link_set_child_hi

int drip_link_set_child_hi (
    drip_link_t *link,
    const drip_hi_t *hi
) 

function drip_link_set_parent_det

int drip_link_set_parent_det (
    drip_link_t *link,
    const drip_det_t *det
) 

function drip_link_set_signature

int drip_link_set_signature (
    drip_link_t *link,
    const drip_signature_t *signature
) 

function drip_link_set_vna

Set the vna timestamp.

int drip_link_set_vna (
    drip_link_t *link,
    uint32_t vna
) 

Stored internally as seconds since DRIP_TIMESTAMP_EPOCH.

Parameters:

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

Return value:

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

function drip_link_set_vna_unixtime

Set the vna from unix timestamp.

int drip_link_set_vna_unixtime (
    drip_link_t *link,
    uint32_t unixtime
) 

Parameters:

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

Return value:

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

function drip_link_set_vnb

Set the vnb timestamp.

int drip_link_set_vnb (
    drip_link_t *link,
    uint32_t vnb
) 

Stored internally as seconds since DRIP_TIMESTAMP_EPOCH.

Parameters:

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

Return value:

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

function drip_link_set_vnb_unixtime

Set the vnb from unix timestamp.

int drip_link_set_vnb_unixtime (
    drip_link_t *link,
    uint32_t unixtime
) 

Parameters:

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

Return value:

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

function drip_link_sign

Sign a DRIP Link.

int drip_link_sign (
    drip_link_t *link,
    drip_link_sign_cb_t callback,
    void *context
) 

Signs the DRIP Link using the provided callback and parent private key. Pass the private key in the context.

int rc = drip_link_sign(&link, sign_ed25519, (void *)secret_key);

Parameters:

• link Pointer to the DRIP Link to sign.
• callback Callback function used to generate the signature.
• context Opaque context passed to the callback.

Return value:

• DRIP_SUCCESS if link was signed.
• DRIP_ERROR_NULL_POINTER if link or callback is NULL.
• DRIP_ERROR_CALLBACK_FAILED if callback returned an error.
• DRIP_ERROR_INVALID_LENGTH if the signature is not DRIP_SIGNATURE_SIZE.

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

function drip_link_to_endorsement

Extract a Broadcast Endorsement from a DRIP Link.

int drip_link_to_endorsement (
    const drip_link_t *link,
    uint8_t *buffer,
    size_t buffer_size
) 

The endorsement is a 136-byte payload without SAM type. This simple helper just strips the SAM type from the link.

Parameters:

• link Pointer to the DRIP Link to read.
• buffer Output buffer for the endorsement bytes.
• buffer_size Size of buffer in bytes. Must be at least DRIP_LINK_ENDORSEMENT_SIZE.

Return value:

• DRIP_SUCCESS if the endorsement was written.
• DRIP_ERROR_NULL_POINTER if link or buffer is NULL.
• DRIP_ERROR_INVALID_SAM_TYPE if sam_type is not DRIP_SAM_TYPE_LINK.
• DRIP_ERROR_BUFFER_TOO_SMALL if buffer_size is less than DRIP_LINK_ENDORSEMENT_SIZE.

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

function drip_link_to_json

Serialize a DRIP link to a JSON string.

int drip_link_to_json (
    const drip_link_t *link,
    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:

• link Pointer to the link 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 link or buffer is NULL.
• DRIP_ERROR_BUFFER_TOO_SMALL if buffer_size is too small.

function drip_link_validate

Validate the structural state of a DRIP Link.

int drip_link_validate (
    const drip_link_t *link
) 

Performs structural checks only. Does not verify the signature or DET hashes. Use drip_link_verify() ordrip_link_verify_chain() for that.

Parameters:

• link Pointer to the DRIP Link to validate.

Return value:

• DRIP_SUCCESS if link is structurally valid.
• DRIP_ERROR_NULL_POINTER if link is NULL.
• DRIP_ERROR_INVALID_SAM_TYPE if sam_type is not DRIP_SAM_TYPE_LINK.
• DRIP_ERROR_INVALID_TIMESTAMP if vnb > vna.
• DRIP_ERROR_INVALID_CHILD_DET if child_det fails validation.
• DRIP_ERROR_INVALID_PARENT_DET if parent_det fails validation.

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

function drip_link_verify

Verify the signature of a DRIP Link.

int drip_link_verify (
    const drip_link_t *link,
    uint32_t unixtime,
    drip_link_verify_cb_t callback,
    void *context
) 

Verifies the signature using the provided callback, timestamp and parent HI. Parent HI is the public key, pass it in the context.

const drip_hi_t *parent_hi = drip_link_get_child_hi(&parent_link);
uint32_t unixtime = (uint32_t)time(NULL);
int rc = drip_link_verify(&child_link, unixtime, verify_ed25519, (void *)parent_hi);

Parameters:

• link Pointer to the DRIP Link to verify.
• unixtime Unix time in seconds or 0 to ignore.
• callback Callback function used to verify the signature.
• context Opaque context passed to the callback.

Return value:

• DRIP_SUCCESS if the signature verifies.
• DRIP_ERROR_NULL_POINTER if link or callback is NULL.
• DRIP_ERROR_TIMESTAMP_NOT_YET_VALID if unixtime is before vnb.
• DRIP_ERROR_TIMESTAMP_EXPIRED if unixtime is after vna.
• DRIP_ERROR_CALLBACK_FAILED if callback returned an error.

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

function drip_link_verify_chain

Verify a chain of DRIP Links from a trusted root.

int drip_link_verify_chain (
    const drip_link_t *link_array,
    size_t link_count,
    const drip_det_t *root_det,
    const drip_hi_t *root_hi,
    uint32_t unixtime,
    drip_hash_cb_t hash_cb,
    drip_link_verify_cb_t verify_cb
) 

Parameters:

• link_array Array of DRIP Links.
• link_count Number of DRIP Links in link_array.
• root_det Trusted root DET.
• root_hi Trusted root Host Identity.
• unixtime Unix time in seconds or 0 ignore.
• hash_cb Callback used to verify each child DET hash.
• verify_cb Callback used to verify each DRIP Link signature.

Return value:

• DRIP_SUCCESS if the chain verifies.
• DRIP_ERROR_NULL_POINTER if link_array, root_det, root_hi, hash_cb, or verify_cb is NULL.
• DRIP_ERROR_TIMESTAMP_NOT_YET_VALID if unixtime is before a hop vnb.
• DRIP_ERROR_TIMESTAMP_EXPIRED if unixtime is after a hop vna.
• DRIP_ERROR_CALLBACK_FAILED if a callback returned an error.
• DRIP_ERROR_VERIFICATION_FAILED if a hop DET hash or signature does not match or the chain is broken.
• DRIP_ERROR_INVALID_APEX_DELEGATION if a hop parent is Apex and child is not an RAA.
• DRIP_ERROR_INVALID_RAA_DELEGATION if a hop parent is RAA and child is not an HDA with the same RAA.
• DRIP_ERROR_INVALID_HDA_DELEGATION if a hop parent is HDA and child is not an HDA with the same RAA and HDA.

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

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

Macros Documentation

define DRIP_LINK_CHAIN_MAX_HOPS

#define DRIP_LINK_CHAIN_MAX_HOPS 8

define DRIP_LINK_ENDORSEMENT_SIZE

#define DRIP_LINK_ENDORSEMENT_SIZE 136

define DRIP_LINK_SIZE

#define DRIP_LINK_SIZE 137