Manifest

include/drip/manifest.h

Structures and Types

Type	Name
typedef int(*	drip_manifest_sign_cb_t Callback function type for producing manifest signatures.
struct	drip_manifest_t
typedef int(*	drip_manifest_verify_cb_t Callback function type for verifying manifest signatures.

Functions

Type	Name
int	drip_manifest_add_evidence (drip_manifest_t *manifest, const drip_hash_t *hash)
int	drip_manifest_decode (drip_manifest_t *manifest, const uint8_t *buffer, size_t buffer_size) Decode a manifest from its wire format.
int	drip_manifest_encode (const drip_manifest_t *manifest, uint8_t *buffer, size_t buffer_size, size_t *encoded_length)
const drip_hash_t *	drip_manifest_get_current_hash (const drip_manifest_t *manifest)
const drip_det_t *	drip_manifest_get_det (const drip_manifest_t *manifest)
const drip_hash_t *	drip_manifest_get_evidence_at (const drip_manifest_t *manifest, uint8_t index)
const drip_hash_t *	drip_manifest_get_link_hash (const drip_manifest_t *manifest)
const drip_hash_t *	drip_manifest_get_previous_hash (const drip_manifest_t *manifest)
const drip_signature_t *	drip_manifest_get_signature (const drip_manifest_t *manifest)
uint32_t	drip_manifest_get_vna (const drip_manifest_t *manifest) Get the vna timestamp.
uint32_t	drip_manifest_get_vna_unixtime (const drip_manifest_t *manifest) Get the vna as a unix timestamp.
uint32_t	drip_manifest_get_vnb (const drip_manifest_t *manifest) Get the vnb timestamp.
uint32_t	drip_manifest_get_vnb_unixtime (const drip_manifest_t *manifest) Get the vnb as a unix timestamp.
int	drip_manifest_init (drip_manifest_t *manifest)
int	drip_manifest_set_det (drip_manifest_t *manifest, const drip_det_t *det)
int	drip_manifest_set_link_hash (drip_manifest_t *manifest, const drip_hash_t *hash)
int	drip_manifest_set_previous_hash (drip_manifest_t *manifest, const drip_hash_t *hash)
int	drip_manifest_set_signature (drip_manifest_t *manifest, const drip_signature_t *signature)
int	drip_manifest_set_vna (drip_manifest_t *manifest, uint32_t vna) Set the vna timestamp.
int	drip_manifest_set_vna_unixtime (drip_manifest_t *manifest, uint32_t unixtime) Set the vna from unix timestamp.
int	drip_manifest_set_vnb (drip_manifest_t *manifest, uint32_t vnb) Set the vnb timestamp.
int	drip_manifest_set_vnb_unixtime (drip_manifest_t *manifest, uint32_t unixtime) Set the vnb from unix timestamp.
int	drip_manifest_sign (drip_manifest_t *manifest, drip_manifest_sign_cb_t callback, void *context) Sign a manifest with caller supplied callback.
int	drip_manifest_to_json (const drip_manifest_t *manifest, char *buffer, size_t buffer_size, size_t *json_length) Serialize a DRIP manifest to a JSON string.
int	drip_manifest_update_current_hash (drip_manifest_t *manifest, drip_hash_cb_t callback, void *context)
int	drip_manifest_validate (const drip_manifest_t *manifest) Validate the structural state of a manifest.
int	drip_manifest_verify (drip_manifest_t *manifest, drip_manifest_verify_cb_t callback, void *context)

Macros

Type	Name
define	DRIP_EVIDENCE_SIZE 112
define	DRIP_MANIFEST_EVIDENCE_MAX 11
define	DRIP_MANIFEST_MAX_SIZE 201 /* when 11 hashes */
define	DRIP_MANIFEST_MIN_SIZE 113 /* when zero hashes */
define	DRIP_SAM_TYPE_SIZE 1
define	DRIP_TIMESTAMP_SIZE 4

Structures and Types Documentation

typedef drip_manifest_sign_cb_t

Callback function type for producing manifest signatures.

typedef int(* drip_manifest_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_manifest_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 manifest length written.

Return value:

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

struct drip_manifest_t

Variables:

• drip_hash_t current_hash

• drip_det_t det

• drip_hash_t evidence

• uint8_t evidence_count

• drip_hash_t link_hash

• drip_hash_t previous_hash

• uint8_t sam_type

• drip_signature_t signature

• uint32_t vna

• uint32_t vnb

typedef drip_manifest_verify_cb_t

Callback function type for verifying manifest signatures.

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

Called by drip_manifest_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_manifest_add_evidence

int drip_manifest_add_evidence (
    drip_manifest_t *manifest,
    const drip_hash_t *hash
) 

function drip_manifest_decode

Decode a manifest from its wire format.

int drip_manifest_decode (
    drip_manifest_t *manifest,
    const uint8_t *buffer,
    size_t buffer_size
) 

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

Parameters:

• manifest Pointer to the manifest 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 manifest orbuffer is NULL.
• DRIP_ERROR_BUFFER_TOO_SMALL if buffer_size is less than DRIP_MANIFEST_MIN_SIZE.
• DRIP_ERROR_INVALID_LENGTH if the evidence payload length is not a multiple of DRIP_HASH_SIZE.
• DRIP_ERROR_ARRAY_OVERFLOW if the evidence count would exceed DRIP_MANIFEST_EVIDENCE_MAX.
• DRIP_ERROR_INVALID_SAM_TYPE if the decoded SAM type is not DRIP_SAM_TYPE_MANIFEST.

function drip_manifest_encode

int drip_manifest_encode (
    const drip_manifest_t *manifest,
    uint8_t *buffer,
    size_t buffer_size,
    size_t *encoded_length
) 

function drip_manifest_get_current_hash

const drip_hash_t * drip_manifest_get_current_hash (
    const drip_manifest_t *manifest
) 

function drip_manifest_get_det

const drip_det_t * drip_manifest_get_det (
    const drip_manifest_t *manifest
) 

function drip_manifest_get_evidence_at

const drip_hash_t * drip_manifest_get_evidence_at (
    const drip_manifest_t *manifest,
    uint8_t index
) 

function drip_manifest_get_link_hash

const drip_hash_t * drip_manifest_get_link_hash (
    const drip_manifest_t *manifest
) 

function drip_manifest_get_previous_hash

const drip_hash_t * drip_manifest_get_previous_hash (
    const drip_manifest_t *manifest
) 

function drip_manifest_get_signature

const drip_signature_t * drip_manifest_get_signature (
    const drip_manifest_t *manifest
) 

function drip_manifest_get_vna

Get the vna timestamp.

uint32_t drip_manifest_get_vna (
    const drip_manifest_t *manifest
) 

Returned as seconds since DRIP_TIMESTAMP_EPOCH.

Parameters:

• manifest Pointer to the manifest.

Returns:

The vna timestamp or 0 if manifest is NULL.

function drip_manifest_get_vna_unixtime

Get the vna as a unix timestamp.

uint32_t drip_manifest_get_vna_unixtime (
    const drip_manifest_t *manifest
) 

Parameters:

• manifest Pointer to the manifest.

Returns:

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

function drip_manifest_get_vnb

Get the vnb timestamp.

uint32_t drip_manifest_get_vnb (
    const drip_manifest_t *manifest
) 

Returned as seconds since DRIP_TIMESTAMP_EPOCH.

Parameters:

• manifest Pointer to the manifest.

Returns:

The vnb timestamp or 0 if manifest is NULL.

function drip_manifest_get_vnb_unixtime

Get the vnb as a unix timestamp.

uint32_t drip_manifest_get_vnb_unixtime (
    const drip_manifest_t *manifest
) 

Parameters:

• manifest Pointer to the manifest.

Returns:

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

function drip_manifest_init

int drip_manifest_init (
    drip_manifest_t *manifest
) 

function drip_manifest_set_det

int drip_manifest_set_det (
    drip_manifest_t *manifest,
    const drip_det_t *det
) 

function drip_manifest_set_link_hash

int drip_manifest_set_link_hash (
    drip_manifest_t *manifest,
    const drip_hash_t *hash
) 

function drip_manifest_set_previous_hash

int drip_manifest_set_previous_hash (
    drip_manifest_t *manifest,
    const drip_hash_t *hash
) 

function drip_manifest_set_signature

int drip_manifest_set_signature (
    drip_manifest_t *manifest,
    const drip_signature_t *signature
) 

function drip_manifest_set_vna

Set the vna timestamp.

int drip_manifest_set_vna (
    drip_manifest_t *manifest,
    uint32_t vna
) 

Stored internally as seconds since DRIP_TIMESTAMP_EPOCH.

Parameters:

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

Return value:

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

function drip_manifest_set_vna_unixtime

Set the vna from unix timestamp.

int drip_manifest_set_vna_unixtime (
    drip_manifest_t *manifest,
    uint32_t unixtime
) 

Parameters:

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

Return value:

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

function drip_manifest_set_vnb

Set the vnb timestamp.

int drip_manifest_set_vnb (
    drip_manifest_t *manifest,
    uint32_t vnb
) 

Stored internally as seconds since DRIP_TIMESTAMP_EPOCH.

Parameters:

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

Return value:

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

function drip_manifest_set_vnb_unixtime

Set the vnb from unix timestamp.

int drip_manifest_set_vnb_unixtime (
    drip_manifest_t *manifest,
    uint32_t unixtime
) 

Parameters:

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

Return value:

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

function drip_manifest_sign

Sign a manifest with caller supplied callback.

int drip_manifest_sign (
    drip_manifest_t *manifest,
    drip_manifest_sign_cb_t callback,
    void *context
) 

Parameters:

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

Precondition:

You must call drip_manifest_update_current_hash() atleast once before calling this function.

Return value:

• DRIP_SUCCESS if signing succeeded.
• DRIP_ERROR_NULL_POINTER if manifest orcallback is NULL.
• DRIP_ERROR_CALLBACK_FAILED if callback returned non-zero.

function drip_manifest_to_json

Serialize a DRIP manifest to a JSON string.

int drip_manifest_to_json (
    const drip_manifest_t *manifest,
    char *buffer,
    size_t buffer_size,
    size_t *json_length
) 

On success writes a NULL terminated JSON to buffer. Whenbuffer_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 manifest 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 orbuffer is NULL.
• DRIP_ERROR_BUFFER_TOO_SMALL if buffer_size is too small.

function drip_manifest_update_current_hash

int drip_manifest_update_current_hash (
    drip_manifest_t *manifest,
    drip_hash_cb_t callback,
    void *context
) 

function drip_manifest_validate

Validate the structural state of a manifest.

int drip_manifest_validate (
    const drip_manifest_t *manifest
) 

Performs structural checks only. Does not verify the signature.

Parameters:

• manifest Pointer to the manifest to validate.

Return value:

• DRIP_SUCCESS if manifest is structurally valid.
• DRIP_ERROR_NULL_POINTER if manifest is NULL.
• DRIP_ERROR_INVALID_SAM_TYPE if sam_type is not DRIP_SAM_TYPE_MANIFEST.
• DRIP_ERROR_INVALID_TIMESTAMP if vnb >vna.
• DRIP_ERROR_ARRAY_OVERFLOW if evidence_count exceeds DRIP_MANIFEST_EVIDENCE_MAX.
• DRIP_ERROR_INVALID_DET if det failsdrip_det_validate().

function drip_manifest_verify

int drip_manifest_verify (
    drip_manifest_t *manifest,
    drip_manifest_verify_cb_t callback,
    void *context
) 

Macros Documentation

define DRIP_EVIDENCE_SIZE

#define DRIP_EVIDENCE_SIZE 112

define DRIP_MANIFEST_EVIDENCE_MAX

#define DRIP_MANIFEST_EVIDENCE_MAX 11

define DRIP_MANIFEST_MAX_SIZE

#define DRIP_MANIFEST_MAX_SIZE 201 /* when 11 hashes */

define DRIP_MANIFEST_MIN_SIZE

#define DRIP_MANIFEST_MIN_SIZE 113 /* when zero hashes */

define DRIP_SAM_TYPE_SIZE

#define DRIP_SAM_TYPE_SIZE 1

define DRIP_TIMESTAMP_SIZE

#define DRIP_TIMESTAMP_SIZE 4