Auth

include/rid/auth.h High-level authentication data API per ASTM F3411-22a.

Provides a container struct and functions for managing multi-page authentication data.

Example usage:

    rid_message_pack_t pack;
    rid_basic_id_t basic_id;
    rid_location_t location;
    rid_self_id_t self_id;
    rid_operator_id_t operator_id;
    rid_system_t system;
    rid_auth_t auth;

    rid_message_pack_init(&pack);
    rid_basic_id_init(&basic_id);
    rid_location_init(&location);
    rid_self_id_init(&self_id);
    rid_operator_id_init(&operator_id);
    rid_system_init(&system);
    rid_auth_init(&auth);

    rid_message_pack_add_message(&pack, &basic_id);
    rid_message_pack_add_message(&pack, &location);
    rid_message_pack_add_message(&pack, &self_id);
    rid_message_pack_add_message(&pack, &operator_id);
    rid_message_pack_add_message(&pack, &system);

    /* You must set timestamp manually */
    rid_auth_set_unixtime(&auth, (uint32_t)time(NULL));

    /* Sign and add the Auth message to the Message Pack */
    rid_auth_sign(&auth, &pack, sign_ed25519, (void *)secret_key);
    rid_message_pack_set_auth(&pack, &auth);

Structures and Types

Type	Name
typedef int(*	rid_auth_sign_cb_t Callback function type for producing authentication signatures.
struct	rid_auth_t Container for multi-page authentication data.
typedef int(*	rid_auth_verify_cb_t Callback function type for verifying authentication signatures.

Functions

Type	Name
uint8_t	rid_auth_get_length (const rid_auth_t *auth) Get the total signature length in bytes.
uint8_t	rid_auth_get_page_count (const rid_auth_t *auth) Get the number of pages used.
int	rid_auth_get_signature (const rid_auth_t *auth, uint8_t *buffer, size_t buffer_size) Get the signature data.
uint32_t	rid_auth_get_timestamp (const rid_auth_t *auth) Get the timestamp.
rid_auth_type_t	rid_auth_get_type (const rid_auth_t *auth) Get the authentication type.
uint32_t	rid_auth_get_unixtime (const rid_auth_t *auth) Get the timestamp as Unix time.
int	rid_auth_init (rid_auth_t *auth) Initialize an authentication data container.
int	rid_auth_set_signature (rid_auth_t *auth, const uint8_t *signature, size_t signature_size) Set the signature data.
int	rid_auth_set_timestamp (rid_auth_t *auth, uint32_t timestamp) Set the timestamp.
int	rid_auth_set_type (rid_auth_t *auth, rid_auth_type_t type) Set the authentication type.
int	rid_auth_set_unixtime (rid_auth_t *auth, uint32_t unixtime) Set the timestamp from Unix time.
int	rid_auth_sign (rid_auth_t *auth, const void *message, rid_auth_sign_cb_t callback, void *context) Create an authentication signature with a caller supplied callback.
int	rid_auth_to_json (const rid_auth_t *auth, char *buffer, size_t buffer_size, size_t *needed_size) Format an Auth message as a JSON string.
int	rid_auth_validate (const rid_auth_t *auth) Validate an Auth container structure.
int	rid_auth_verify (const rid_auth_t *auth, const void *message, rid_auth_verify_cb_t callback, void *context) Verify an authentication signature using a caller supplied callback.

Macros

Type	Name
define	RID_AUTH_PAGE_MAX_SIGNATURE_SIZE 255 Max signature size in bytes.

Structures and Types Documentation

typedef rid_auth_sign_cb_t

Callback function type for producing authentication signatures.

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

Called by rid_auth_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.
• signature Output buffer for the signature.
• signature_size Size of the signature buffer in bytes.
• signature_length Output: actual signature length written.

Return value:

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

struct rid_auth_t

Container for multi-page authentication data.

Holds page 0 and up to 15 additional pages.

Variables:

• rid_auth_page_0_t page_0

• rid_auth_page_x_t page_x

typedef rid_auth_verify_cb_t

Callback function type for verifying authentication signatures.

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

Called by rid_auth_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 data to verify against.
• signature_length Length of the signature in bytes.

Return value:

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

Functions Documentation

function rid_auth_get_length

Get the total signature length in bytes.

uint8_t rid_auth_get_length (
    const rid_auth_t *auth
) 

Parameters:

• auth Pointer to the authentication data container.

Returns:

The total signature length in bytes, or 0 if auth is NULL.

function rid_auth_get_page_count

Get the number of pages used.

uint8_t rid_auth_get_page_count (
    const rid_auth_t *auth
) 

Parameters:

• auth Pointer to the authentication data container.

Returns:

The page count (1-16), or 0 if auth is NULL.

function rid_auth_get_signature

Get the signature data.

int rid_auth_get_signature (
    const rid_auth_t *auth,
    uint8_t *buffer,
    size_t buffer_size
) 

Retrieves signature data from page 0 and additional pages.

Parameters:

• auth Pointer to the authentication data container.
• buffer Buffer to store the signature data.
• buffer_size Size of the buffer (must be at least the signature length).

Return value:

• RID_SUCCESS on success.
• RID_ERROR_NULL_POINTER if auth or buffer is NULL.
• RID_ERROR_BUFFER_TOO_SMALL if buffer_size is less than signature length.

function rid_auth_get_timestamp

Get the timestamp.

uint32_t rid_auth_get_timestamp (
    const rid_auth_t *auth
) 

Parameters:

• auth Pointer to the authentication data container.

Returns:

Seconds since 2019-01-01 00:00:00 UTC, or 0 if auth is NULL.

function rid_auth_get_type

Get the authentication type.

rid_auth_type_t rid_auth_get_type (
    const rid_auth_t *auth
) 

Parameters:

• auth Pointer to the authentication data container.

Returns:

The authentication type, or RID_AUTH_TYPE_NONE if auth is NULL.

function rid_auth_get_unixtime

Get the timestamp as Unix time.

uint32_t rid_auth_get_unixtime (
    const rid_auth_t *auth
) 

Converts RID timestamp to Unix timestamp.

Parameters:

• auth Pointer to the authentication data container.

Returns:

Unix timestamp (seconds since 1970-01-01 00:00:00 UTC), or 0 if auth is NULL.

function rid_auth_init

Initialize an authentication data container.

int rid_auth_init (
    rid_auth_t *auth
) 

Zeros the structure and initializes page0 with protocol version and message type. Sets page_count to 1.

Parameters:

• auth Pointer to the authentication data container.

Return value:

• RID_SUCCESS on success.
• RID_ERROR_NULL_POINTER if auth is NULL.

function rid_auth_set_signature

Set the signature data.

int rid_auth_set_signature (
    rid_auth_t *auth,
    const uint8_t *signature,
    size_t signature_size
) 

Distributes signature data across page 0 and additional pages as needed. Page 0 holds up to 17 bytes, each additional page holds up to 23 bytes. You can clear the signature by passing signature_size 0.

Note:

Authentication type must be set before setting a signature.

rid_auth_set_type(auth, RID_AUTH_TYPE_MESSAGE_SET_SIGNATURE);
rid_auth_set_signature(auth, signature, signature_size);

Parameters:

• auth Pointer to the authentication data container.
• signature Pointer to the signature data. May be NULL if signature_size is 0.
• signature_size Size of the signature data (0 to 255 bytes).

Return value:

• RID_SUCCESS on success.
• RID_ERROR_NULL_POINTER if auth is NULL, or if signature is NULL and signature_size is not 0.
• RID_ERROR_BUFFER_TOO_LARGE if signature_size exceeds 255 bytes.
• RID_ERROR_NON_EMPTY_SIGNATURE if type is RID_AUTH_TYPE_NONE or RID_AUTH_TYPE_NETWORK_REMOTE_ID but signature is not empty.

function rid_auth_set_timestamp

Set the timestamp.

int rid_auth_set_timestamp (
    rid_auth_t *auth,
    uint32_t timestamp
) 

Parameters:

• auth Pointer to the authentication data container.
• timestamp Seconds since 2019-01-01 00:00:00 UTC.

Return value:

• RID_SUCCESS on success.
• RID_ERROR_NULL_POINTER if auth is NULL.

function rid_auth_set_type

Set the authentication type.

int rid_auth_set_type (
    rid_auth_t *auth,
    rid_auth_type_t type
) 

Note:

When setting RID_AUTH_TYPE_NONE or RID_AUTH_TYPE_NETWORK_REMOTE_ID you should clear the signature first.

rid_auth_set_signature(auth, NULL, 0);
rid_auth_set_type(auth, RID_AUTH_TYPE_NETWORK_REMOTE_ID);

Parameters:

• auth Pointer to the authentication data container.
• type The authentication type to set.

Return value:

• RID_SUCCESS on success.
• RID_ERROR_NULL_POINTER if auth is NULL.
• RID_ERROR_OUT_OF_RANGE if type exceeds RID_AUTH_TYPE_MAX.
• RID_ERROR_NON_EMPTY_SIGNATURE if type is RID_AUTH_TYPE_NONE or RID_AUTH_TYPE_NETWORK_REMOTE_ID but signature is not empty.

function rid_auth_set_unixtime

Set the timestamp from Unix time.

int rid_auth_set_unixtime (
    rid_auth_t *auth,
    uint32_t unixtime
) 

Converts Unix timestamp to RID timestamp (seconds since 2019-01-01).

Parameters:

• auth Pointer to the authentication data container.
• unixtime Unix timestamp (seconds since 1970-01-01 00:00:00 UTC).

Return value:

• RID_SUCCESS on success.
• RID_ERROR_NULL_POINTER if auth is NULL.
• RID_ERROR_OUT_OF_RANGE if unixtime is before RID epoch (2019-01-01).

function rid_auth_sign

Create an authentication signature with a caller supplied callback.

int rid_auth_sign (
    rid_auth_t *auth,
    const void *message,
    rid_auth_sign_cb_t callback,
    void *context
) 

Validates the auth container and the input message. Constructs the payload to be signed internally, invokes the sign callback, then stores the resulting signature in the auth container.

The caller must set the timestamp before calling this function. The auth type is set automatically to RID_AUTH_TYPE_MESSAGE_SET_SIGNATURE.

Only rid_message_pack_t is currently supported.

Parameters:

• auth Pointer to the authentication data container. The signature produced by the callback is stored here.
• message Pointer to a rid_message_pack_t whose non-AUTH messages are to be signed.
• callback Callback function used to produce the signature.
• context Opaque context passed to the callback.

Return value:

• RID_SUCCESS if signing succeeded.
• RID_ERROR_NULL_POINTER if auth, message, or callback is NULL.
• RID_ERROR_NOT_IMPLEMENTED if message is not a message pack.
• RID_ERROR_OUT_OF_RANGE if the callback produced a zero-length signature.
• Validation error codes from rid_auth_validate() orrid_message_pack_validate().
• Any non-zero value returned by the callback on signing failure.

function rid_auth_to_json

Format an Auth message as a JSON string.

int rid_auth_to_json (
    const rid_auth_t *auth,
    char *buffer,
    size_t buffer_size,
    size_t *needed_size
) 

Parameters:

• auth Pointer to the Auth container structure.
• buffer Buffer to store the JSON string or NULL.
• buffer_size Size of the buffer.
• needed_size If non-NULL receives the required buffer size.

Return value:

• RID_SUCCESS on success.
• RID_ERROR_NULL_POINTER if auth is NULL or if bothbuffer andneeded_size are NULL.
• RID_ERROR_BUFFER_TOO_SMALL if buffer is too small.

function rid_auth_validate

Validate an Auth container structure.

int rid_auth_validate (
    const rid_auth_t *auth
) 

Checks that page_0 fields contain valid values according to ASTM F3411-22a.

Parameters:

• auth Pointer to the Auth container structure to validate.

Return value:

• RID_SUCCESS if all fields are valid.
• RID_ERROR_NULL_POINTER if auth is NULL.
• RID_ERROR_INVALID_PROTOCOL_VERSION if protocol version is invalid.
• RID_ERROR_UNKNOWN_MESSAGE_TYPE if message type is not AUTH.
• RID_ERROR_INVALID_PAGE_NUMBER if page_number is invalid.
• RID_ERROR_INVALID_LAST_PAGE_INDEX if last_page_index exceeds maximum.
• RID_ERROR_NON_EMPTY_SIGNATURE if auth type is NETWORK_REMOTE_ID but signature is not empty.

function rid_auth_verify

Verify an authentication signature using a caller supplied callback.

int rid_auth_verify (
    const rid_auth_t *auth,
    const void *message,
    rid_auth_verify_cb_t callback,
    void *context
) 

Validates the auth container and the input message. Constructs the signed payload internally, extracts the signature and then invokes the verify callback with the payload and signature.

Only rid_message_pack_t is currently supported.

Only RID_AUTH_TYPE_MESSAGE_SET_SIGNATURE is currently supported.

Parameters:

• auth Pointer to the authentication data container.
• message Pointer to a rid_message_pack_t whose non-AUTH messages were signed.
• callback Callback function used to verify the signature.
• context Opaque context passed to the callback.

Return value:

• RID_SUCCESS if verification succeeded.
• RID_ERROR_NULL_POINTER if auth, message, or callback is NULL.
• RID_ERROR_NOT_IMPLEMENTED if message is not a message pack, or if auth type is not MESSAGE_SET_SIGNATURE.
• RID_ERROR_OUT_OF_RANGE if the signature length is zero.
• Validation error codes from rid_auth_validate() orrid_message_pack_validate().
• Any non-zero value returned by the callback on verification failure.

Macros Documentation

define RID_AUTH_PAGE_MAX_SIGNATURE_SIZE

Max signature size in bytes.

#define RID_AUTH_PAGE_MAX_SIGNATURE_SIZE 255