Det

include/drip/det.h

Structures and Types

Type	Name
enum	drip_det_role_t DET role determined from an HID.
typedef uint8_t	drip_det_t 16-byte DRIP Entity Tag (DET).
enum	drip_hhsi_t HHIT Suite ID (HHSI) values per RFC 9374.

Functions

Type	Name
int	drip_det_decode (drip_det_t *det, const uint8_t *buffer, size_t buffer_size) Decode and validate a 16-byte buffer into a DET.
int	drip_det_encode (const drip_det_t *det, uint8_t *buffer, size_t buffer_size) Encode a DET to its 16-byte wire format.
int	drip_det_from_ipv6_string (drip_det_t *det, const char *string) Parse a canonical IPv6 address string into a DET.
const drip_hash_t *	drip_det_get_hash (const drip_det_t *det) Get the hash of a DET.
uint16_t	drip_det_get_hda (const drip_det_t *det) Get the HHIT Domain Authority (HDA) of a DET.
uint8_t	drip_det_get_hhsi (const drip_det_t *det) Get the HHIT Suite ID (HHSI) of a DET.
uint32_t	drip_det_get_hid (const drip_det_t *det) Get the Hierarchy ID (HID) of a DET.
uint16_t	drip_det_get_raa (const drip_det_t *det) Get the Registered Assigning Authority (RAA) of a DET.
int	drip_det_hid_abbreviation (const drip_det_t *det, char *buffer, size_t buffer_size) Render the default HID abbreviation of a DET.
int	drip_det_init (drip_det_t *det) Initialize a DET.
drip_det_role_t	drip_det_role (const drip_det_t *det) Get the role of a DET from its HID.
int	drip_det_set_hash (drip_det_t *det, const drip_hash_t *hash) Set the hash of a DET.
int	drip_det_set_hda (drip_det_t *det, uint16_t hda) Set the HHIT Domain Authority (HDA) of a DET.
int	drip_det_set_hhsi (drip_det_t *det, drip_hhsi_t hhsi) Set the HHIT Suite ID (HHSI) of a DET.
int	drip_det_set_hid (drip_det_t *det, uint32_t hid) Set the Hierarchy ID (HID) of a DET.
int	drip_det_set_raa (drip_det_t *det, uint16_t raa) Set the Registered Assigning Authority (RAA) of a DET.
int	drip_det_to_ipv6_string (const drip_det_t *det, char *buffer, size_t buffer_size) Render a DET as a canonical IPv6 address string.
int	drip_det_update_hash (drip_det_t *det, const drip_hi_t *hi, drip_hash_cb_t callback, void *context) Update the hash of a DET.
int	drip_det_validate (const drip_det_t *det) Validate the structural integrity of a DET.
int	drip_det_verify (const drip_det_t *det, const drip_hi_t *hi, drip_hash_cb_t callback, void *context) Verify the hash of a DET.
int	drip_det_verify_delegation (const drip_det_t *parent, const drip_det_t *child) Verify that a parent DET may delegate to a child DET.

Macros

Type	Name
define	DRIP_DET_CONTEXT_ID_SIZE 16 Length of the hash customization string in bytes.
define	DRIP_DET_HID_ABBREVIATION_SIZE 10 Buffer size in bytes for a NULL terminated HID abbreviation.
define	DRIP_DET_IPV6_PREFIX_STRING "2001:30::/28" DET IPv6 prefix string (2001:30::/28).
define	DRIP_DET_IPV6_STRING_SIZE 40 Buffer size in bytes for a NULL terminated DET IPv6 string.
define	DRIP_DET_SIZE 16 Size of a DET in bytes.

Structures and Types Documentation

enum drip_det_role_t

DET role determined from an HID.

enum drip_det_role_t {
    DRIP_DET_ROLE_UNKNOWN = 0,
    DRIP_DET_ROLE_APEX = 1,
    DRIP_DET_ROLE_RAA = 2,
    DRIP_DET_ROLE_HDA = 3
};

HID cannot distinguish HDA from UA so both map to DRIP_DET_ROLE_HDA.

See also: https://www.rfc-editor.org/rfc/rfc9886.html#section-3

typedef drip_det_t

16-byte DRIP Entity Tag (DET).

typedef uint8_t drip_det_t[16];

See also: https://www.rfc-editor.org/rfc/rfc9374.html#section-3

enum drip_hhsi_t

HHIT Suite ID (HHSI) values per RFC 9374.

enum drip_hhsi_t {
    DRIP_HHSI_RESERVED = 0,
    DRIP_HHSI_RSA_DSA_SHA256 = 1,
    DRIP_HHSI_ECDSA_SHA384 = 2,
    DRIP_HHSI_ECDSA_LOW_SHA1 = 3,
    DRIP_HHSI_EDDSA_CSHAKE128 = 5,
    DRIP_HHSI_HDA_PRIVATE_USE_1 = 254,
    DRIP_HHSI_HDA_PRIVATE_USE_2 = 255
};

Identifies the hash and signature algorithms used by a DET.

See also: https://www.rfc-editor.org/rfc/rfc9374.html#section-3.2

Functions Documentation

function drip_det_decode

Decode and validate a 16-byte buffer into a DET.

int drip_det_decode (
    drip_det_t *det,
    const uint8_t *buffer,
    size_t buffer_size
) 

You could also just use memcpy() but using this future proofs your code in case the internal representation ever changes.

Parameters:

• det Pointer to the DET that receives the decoded bytes.
• buffer Input buffer holding the wire format bytes.
• buffer_size Size of buffer in bytes. Must be at least DRIP_DET_SIZE.

Return value:

• DRIP_SUCCESS on success.
• DRIP_ERROR_NULL_POINTER if det or buffer is NULL.
• DRIP_ERROR_BUFFER_TOO_SMALL if buffer_size is less than DRIP_DET_SIZE.
• DRIP_ERROR_INVALID_IPV6_PREFIX if the decoded prefix is not 2001:30::/28.

See also: drip_det_validate

function drip_det_encode

Encode a DET to its 16-byte wire format.

int drip_det_encode (
    const drip_det_t *det,
    uint8_t *buffer,
    size_t buffer_size
) 

You could also just use memcpy() but using this future proofs your code in case the internal representation ever changes.

Parameters:

• det Pointer to the DET to encode.
• buffer Output buffer for the wire format bytes.
• buffer_size Size of buffer in bytes. Must be at least DRIP_DET_SIZE.

Return value:

• DRIP_SUCCESS on success.
• DRIP_ERROR_NULL_POINTER if det or buffer is NULL.
• DRIP_ERROR_BUFFER_TOO_SMALL if buffer_size is less than DRIP_DET_SIZE.

function drip_det_from_ipv6_string

Parse a canonical IPv6 address string into a DET.

int drip_det_from_ipv6_string (
    drip_det_t *det,
    const char *string
) 

Parameters:

• det Pointer to the DET that receives the parsed bytes.
• string NULL terminated ipv6 string.

Return value:

• DRIP_SUCCESS if the string parsed and is a structurally valid DET.
• DRIP_ERROR_NULL_POINTER if det or string is NULL.
• DRIP_ERROR_INVALID_IPV6_STRING if string is not a valid ipv6 address.
• DRIP_ERROR_INVALID_IPV6_PREFIX if the prefix is outside 2001:30::/28.

function drip_det_get_hash

Get the hash of a DET.

const drip_hash_t * drip_det_get_hash (
    const drip_det_t *det
) 

Parameters:

• det Pointer to the DET.

Returns:

Pointer to the stored hash or NULL if det is NULL.

function drip_det_get_hda

Get the HHIT Domain Authority (HDA) of a DET.

uint16_t drip_det_get_hda (
    const drip_det_t *det
) 

Parameters:

• det Pointer to the DET.

Returns:

The stored HDA or 0 if det is NULL.

See also: https://www.rfc-editor.org/rfc/rfc9374.html#section-3.3.2

function drip_det_get_hhsi

Get the HHIT Suite ID (HHSI) of a DET.

uint8_t drip_det_get_hhsi (
    const drip_det_t *det
) 

Parameters:

• det Pointer to the DET.

Returns:

The stored HHSI or 0 if det is NULL.

See also: https://www.rfc-editor.org/rfc/rfc9374.html#section-3.2

function drip_det_get_hid

Get the Hierarchy ID (HID) of a DET.

uint32_t drip_det_get_hid (
    const drip_det_t *det
) 

Parameters:

• det Pointer to the DET.

Returns:

The stored HID or 0 if det is NULL.

See also: https://www.rfc-editor.org/rfc/rfc9374.html#section-3.3

function drip_det_get_raa

Get the Registered Assigning Authority (RAA) of a DET.

uint16_t drip_det_get_raa (
    const drip_det_t *det
) 

Parameters:

• det Pointer to the DET.

Returns:

The stored RAA or 0 if det is NULL.

See also: https://www.rfc-editor.org/rfc/rfc9374.html#section-3.3.1

function drip_det_hid_abbreviation

Render the default HID abbreviation of a DET.

int drip_det_hid_abbreviation (
    const drip_det_t *det,
    char *buffer,
    size_t buffer_size
) 

RFC 9886 default is a four character hexadecimal RAA and HDA with a space between them.

Parameters:

• det Pointer to the DET to render.
• buffer Output buffer for the NULL terminated abbreviation.
• buffer_size Size of the output buffer.

Return value:

• DRIP_SUCCESS if the abbreviation was rendered.
• DRIP_ERROR_NULL_POINTER if det or buffer is NULL.
• DRIP_ERROR_BUFFER_TOO_SMALL if buffer_size is too small to hold the rendered abbreviation.

See also: https://www.rfc-editor.org/rfc/rfc9886.html#section-5.1.2

function drip_det_init

Initialize a DET.

int drip_det_init (
    drip_det_t *det
) 

Zeroes the DET and sets the IPv6 prefix to 2001:30::/28.

Parameters:

• det Pointer to the DET to initialize.

Return value:

• DRIP_SUCCESS if the DET was initialized.
• DRIP_ERROR_NULL_POINTER if det is NULL.

See also: https://www.rfc-editor.org/rfc/rfc9374.html#section-3.1

function drip_det_role

Get the role of a DET from its HID.

drip_det_role_t drip_det_role (
    const drip_det_t *det
) 

Apex is an RAA 0-3 with a reserved HDA (0, 4096, 8192 or 12288). Any other reserved HDA is an RAA. Any other HID is either HDA or UA.

Parameters:

• det Pointer to the DET.

Returns:

The determined role or DRIP_DET_ROLE_UNKNOWN if det is NULL.

See also: https://www.rfc-editor.org/rfc/rfc9886.html#section-3

function drip_det_set_hash

Set the hash of a DET.

int drip_det_set_hash (
    drip_det_t *det,
    const drip_hash_t *hash
) 

Use this only if hash comes from an external source. Normally you should use drip_det_update_hash() instead.

Parameters:

• det Pointer to the DET to modify.
• hash Pointer to the hash to store.

Return value:

• DRIP_SUCCESS if the hash was stored.
• DRIP_ERROR_NULL_POINTER if det or hash is NULL.

function drip_det_set_hda

Set the HHIT Domain Authority (HDA) of a DET.

int drip_det_set_hda (
    drip_det_t *det,
    uint16_t hda
) 

This is a 14 bit value. Values greater than 0x3FFF are out of range.

Parameters:

• det Pointer to the DET to modify.
• hda HHIT Domain Authority to store.

Return value:

• DRIP_SUCCESS if the HDA was stored.
• DRIP_ERROR_NULL_POINTER if det is NULL.
• DRIP_ERROR_OUT_OF_RANGE if hda > 0x3FFF.

See also: https://www.rfc-editor.org/rfc/rfc9374.html#section-3.3.2

function drip_det_set_hhsi

Set the HHIT Suite ID (HHSI) of a DET.

int drip_det_set_hhsi (
    drip_det_t *det,
    drip_hhsi_t hhsi
) 

Parameters:

• det Pointer to the DET to modify.
• hhsi HHIT Suite ID to store.

Return value:

• DRIP_SUCCESS if the HHSI was stored.
• DRIP_ERROR_NULL_POINTER if det is NULL.

See also: https://www.rfc-editor.org/rfc/rfc9374.html#section-3.2

function drip_det_set_hid

Set the Hierarchy ID (HID) of a DET.

int drip_det_set_hid (
    drip_det_t *det,
    uint32_t hid
) 

This is a 28 bit value. Values greater than 0x0FFFFFFF are out of range.

Parameters:

• det Pointer to the DET to modify.
• hid Hierarchy ID to store.

Return value:

• DRIP_SUCCESS if the HID was stored.
• DRIP_ERROR_NULL_POINTER if det is NULL.
• DRIP_ERROR_OUT_OF_RANGE if hid > 0x0FFFFFFF.

See also: https://www.rfc-editor.org/rfc/rfc9374.html#section-3.3

function drip_det_set_raa

Set the Registered Assigning Authority (RAA) of a DET.

int drip_det_set_raa (
    drip_det_t *det,
    uint16_t raa
) 

This is a 14 bit value. Values greater than 0x3FFF are out of range.

Parameters:

• det Pointer to the DET to modify.
• raa Registered Assigning Authority to store.

Return value:

• DRIP_SUCCESS if the RAA was stored.
• DRIP_ERROR_NULL_POINTER if det is NULL.
• DRIP_ERROR_OUT_OF_RANGE if raa > 0x3FFF.

See also: https://www.rfc-editor.org/rfc/rfc9374.html#section-3.3.1

function drip_det_to_ipv6_string

Render a DET as a canonical IPv6 address string.

int drip_det_to_ipv6_string (
    const drip_det_t *det,
    char *buffer,
    size_t buffer_size
) 

Parameters:

• det Pointer to the DET to render.
• buffer Output buffer for the NULL terminated ipv6 string.
• buffer_size Size of the output buffer.

Return value:

• DRIP_SUCCESS if the DET was rendered.
• DRIP_ERROR_NULL_POINTER if det or buffer is NULL.
• DRIP_ERROR_BUFFER_TOO_SMALL if buffer_size is too small to hold the rendered ipv6 string.

function drip_det_update_hash

Update the hash of a DET.

int drip_det_update_hash (
    drip_det_t *det,
    const drip_hi_t *hi,
    drip_hash_cb_t callback,
    void *context
) 

Hashes the first 8 bytes of the DET concatenated with the Host Identity (HI) using the caller supplied callback.

Parameters:

• det Pointer to the DET to modify.
• hi Pointer to the Host Identity.
• callback Callback function used to generate the hash.
• context Opaque context passed to the callback.

Precondition:

You must call drip_det_set_hid() anddrip_det_set_hhsi() before calling this function.

Return value:

• DRIP_SUCCESS if the hash was stored.
• DRIP_ERROR_NULL_POINTER if det or hi or callback is NULL.
• DRIP_ERROR_CALLBACK_FAILED if callback returned an error.
• DRIP_ERROR_INVALID_LENGTH if resulting hash size does not match DRIP_HASH_SIZE.

See also: https://www.rfc-editor.org/rfc/rfc9374.html#section-3.5.2

function drip_det_validate

Validate the structural integrity of a DET.

int drip_det_validate (
    const drip_det_t *det
) 

Checks the IPv6 prefix. Does not verify the ORCHID hash, use drip_det_verify() for that. Reserved values are considered valid.

Parameters:

• det Pointer to the DET to validate.

Return value:

• DRIP_SUCCESS if det is structurally valid.
• DRIP_ERROR_NULL_POINTER if det is NULL.
• DRIP_ERROR_INVALID_IPV6_PREFIX if bytes 0-3 do not match the 2001:30::/28 prefix.

See also: https://www.rfc-editor.org/rfc/rfc9374.html#section-3.1

See also: https://www.rfc-editor.org/rfc/rfc9374.html#section-3.2

See also: https://www.iana.org/assignments/drip/drip.xhtml#drip-raa

See also: https://www.rfc-editor.org/rfc/rfc9886.html

function drip_det_verify

Verify the hash of a DET.

int drip_det_verify (
    const drip_det_t *det,
    const drip_hi_t *hi,
    drip_hash_cb_t callback,
    void *context
) 

Hashes the first 8 bytes of the DET concatenated with the Host Identity (HI) using the caller supplied callback and compares the result to the stored hash.

Parameters:

• det Pointer to the DET to verify.
• hi Pointer to the Host Identity.
• callback Callback function used to generate the hash.
• context Opaque context passed to the callback.

Return value:

• DRIP_SUCCESS if the hash matches.
• DRIP_ERROR_NULL_POINTER if det or hi or callback is NULL.
• DRIP_ERROR_CALLBACK_FAILED if callback returned non-zero.
• DRIP_ERROR_INVALID_LENGTH if resulting hash size does not match DRIP_HASH_SIZE.
• DRIP_ERROR_VERIFICATION_FAILED if the hash does not match.

See also: https://www.rfc-editor.org/rfc/rfc9374.html#section-3.5.2

function drip_det_verify_delegation

Verify that a parent DET may delegate to a child DET.

int drip_det_verify_delegation (
    const drip_det_t *parent,
    const drip_det_t *child
) 

Uses Hierarchy ID (HID) only. HID is divided into Registered Assigning Authority (RAA) and HHIT Domain Authority (HDA). Does not verify hashes or signatures.

Apex may only delegate to an RAA. RAA may only delegate to an HDA with the same RAA. HDA may only delegate to an HDA with the same RAA and HDA. UA is considered to be an HDA.

Parameters:

• parent Pointer to the parent DET.
• child Pointer to the child DET.

Return value:

• DRIP_SUCCESS if the delegation is valid.
• DRIP_ERROR_NULL_POINTER if parent or child is NULL.
• DRIP_ERROR_INVALID_APEX_DELEGATION if parent is Apex and child is not an RAA.
• DRIP_ERROR_INVALID_RAA_DELEGATION if parent is RAA and child is not an HDA with the same RAA.
• DRIP_ERROR_INVALID_HDA_DELEGATION if parent is HDA and child is not an HDA with the same RAA and HDA.

See also: https://www.rfc-editor.org/rfc/rfc9374.html#section-3.3

See also: https://www.rfc-editor.org/rfc/rfc9886.html#section-3

Macros Documentation

define DRIP_DET_CONTEXT_ID_SIZE

Length of the hash customization string in bytes.

#define DRIP_DET_CONTEXT_ID_SIZE 16

define DRIP_DET_HID_ABBREVIATION_SIZE

Buffer size in bytes for a NULL terminated HID abbreviation.

#define DRIP_DET_HID_ABBREVIATION_SIZE 10

define DRIP_DET_IPV6_PREFIX_STRING

DET IPv6 prefix string (2001:30::/28).

#define DRIP_DET_IPV6_PREFIX_STRING "2001:30::/28"

define DRIP_DET_IPV6_STRING_SIZE

Buffer size in bytes for a NULL terminated DET IPv6 string.

#define DRIP_DET_IPV6_STRING_SIZE 40

define DRIP_DET_SIZE

Size of a DET in bytes.

#define DRIP_DET_SIZE 16