Det

include/drip/det.h

Structures and Types

Type Name
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_init (drip_det_t *det)
Initialize a DET.
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.

Macros

Type Name
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

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. Values 0 (RESERVED) and 16 (skipped) must not be used.

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.
  • DRIP_ERROR_INVALID_RAA if the decoded RAA is in an IANA Reserved range (0..3 or 4000..8191).
  • DRIP_ERROR_INVALID_HHSI if the decoded HHSI is 0 or 16.

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.
  • DRIP_ERROR_INVALID_RAA if the parsed RAA is in an IANA Reserved range (0..3 or 4000..8191).
  • DRIP_ERROR_INVALID_HHSI if the HHSI is 0 (RESERVED) or 16 (skipped)

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_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_set_hash

Set the hash of a DET.

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

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
)

Values greater than 0x3FFF (14 bits) 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
)

Values 0 (RESERVED) and 16 are invalid per RFC 9374 ยง3.2.

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.
  • DRIP_ERROR_INVALID_HHSI if hhsi is 0 (RESERVED) or 16.

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
)

Values greater than 0x0FFFFFFF (28 bits) 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
)

Values greater than 0x3FFF (14 bits) 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 (Prefix|HID|HHSI) concatenated with the Host Identity using the caller supplied callback and stores the result.

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 non-zero.

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, the RAA against the IANA reserved ranges (0..3 and 4000..8191) and the HHIT Suite ID (HHSI). Does not verify the ORCHID hash, use drip_det_verify() for that.

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.
  • DRIP_ERROR_INVALID_RAA if RAA is in an IANA reserved range (0..3 or 4000..8191).
  • DRIP_ERROR_INVALID_HHSI if HHSI is 0 (RESERVED) or 16.

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 (Prefix|HID|HHSI) concatenated with the Host Identity 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_VERIFICATION_FAILED if the hash does not match.

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

Macros Documentation

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