query.h File Reference

UDIF query operations. More...

#include "udif.h"
#include "capability.h"

Go to the source code of this file.

Data Structures
struct	udif_query
	Query request. More...
struct	udif_query_response
	Query response. More...

Macros
#define	UDIF_QUERY_ID_SIZE   16U
	The query id size.
#define	UDIF_QUERY_MAX_PREDICATE_SIZE   1024U
	Maximum query predicate data size.
#define	UDIF_QUERY_MAX_PROOF_SIZE   8192U
#define	UDIF_QUERY_PREDICATE_SIZE   sizeof(size_t)
	The query predicate size.
#define	UDIF_QUERY_PROOF_SIZE   sizeof(size_t)
	The query proof size.
#define	UDIF_QUERY_TYPE_SIZE   1U
	The query type size.
#define	UDIF_QUERY_VERDICT_SIZE   1U
	The query verdict size.
#define	UDIF_QUERY_STRUCTURE_SIZE
	The query structure size.
#define	UDIF_QUERY_RESPONSE_STRUCTURE_SIZE
	The query structure size.

Typedefs
typedef UDIF_EXPORT_API enum udif_query_types	udif_query_types
typedef UDIF_EXPORT_API enum udif_query_verdicts	udif_query_verdicts
typedef UDIF_EXPORT_API struct udif_query	udif_query
typedef UDIF_EXPORT_API struct udif_query_response	udif_query_response

Enumerations
enum	udif_query_types { udif_query_exist = 1U , udif_query_owner_binding = 2U , udif_query_attr_bucket = 3U , udif_query_membership_proof = 4U }
	Query predicate types. More...
enum	udif_query_verdicts { udif_verdict_no = 0U , udif_verdict_yes = 1U , udif_verdict_deny = 2U }
	Query response verdicts. More...

Functions
UDIF_EXPORT_API void	udif_query_clear (udif_query *query)
	Clear a query.
UDIF_EXPORT_API void	udif_query_compute_digest (uint8_t *digest, const udif_query *query)
	Compute query digest.
UDIF_EXPORT_API udif_errors	udif_query_create_attr_bucket (udif_query *query, const uint8_t *queryid, const uint8_t *targetser, const uint8_t *serial, uint64_t attrmin, uint64_t attrmax, uint64_t timeanchor, const uint8_t *capability)
	Create an attribute bucket query.
UDIF_EXPORT_API udif_errors	udif_query_create_existence (udif_query *query, const uint8_t *queryid, const uint8_t *targetser, const uint8_t *serial, uint64_t timeanchor, const uint8_t *capability)
	Create an existence query.
UDIF_EXPORT_API udif_errors	udif_query_create_membership_proof (udif_query *query, const uint8_t *queryid, const uint8_t *targetser, const uint8_t *serial, uint64_t timeanchor, const uint8_t *capability)
	Create a membership proof query.
UDIF_EXPORT_API udif_errors	udif_query_create_owner_binding (udif_query *query, const uint8_t *queryid, const uint8_t *targetser, const uint8_t *serial, const uint8_t *ownerser, uint64_t time_anchor, const uint8_t *capability)
	Create an owner binding query.
UDIF_EXPORT_API udif_errors	udif_query_create_response (udif_query_response *response, const udif_query *query, uint8_t verdict, const uint8_t *proofdata, size_t prooflen, const uint8_t *respser, const uint8_t *respsigkey, uint64_t ctime, bool(*rng_generate)(uint8_t *, size_t))
	Create a query response.
UDIF_EXPORT_API udif_errors	udif_query_deserialize (udif_query *query, const uint8_t *input, size_t inplen)
	Deserialize a query.
UDIF_EXPORT_API udif_errors	udif_query_serialize (uint8_t *output, size_t *outlen, const udif_query *query)
	Serialize a query.
UDIF_EXPORT_API bool	udif_query_is_fresh (const udif_query *query, uint64_t ctime)
	Check if query is fresh.
UDIF_EXPORT_API void	udif_query_response_clear (udif_query_response *response)
	Clear a query response.
UDIF_EXPORT_API void	udif_query_response_compute_digest (uint8_t *digest, const udif_query_response *response, const uint8_t *queryid)
	Compute response digest.
UDIF_EXPORT_API udif_errors	udif_query_response_deserialize (udif_query_response *response, const uint8_t *input, size_t inplen)
	Deserialize a query response.
UDIF_EXPORT_API udif_errors	udif_query_response_serialize (uint8_t *output, size_t *outlen, const udif_query_response *response)
	Serialize a query response.
UDIF_EXPORT_API bool	udif_query_validate_authorization (const udif_query *query, const udif_capability *capability, const uint8_t *targser)
	Validate query authorization.
UDIF_EXPORT_API bool	udif_query_verify_response (const udif_query_response *response, const udif_query *query, const uint8_t *respverkey)
	Verify a query response.

Detailed Description

UDIF query operations.

This module implements predicate-based queries with minimal disclosure. Queries allow entities to request information about objects and their ownership without revealing unnecessary details.

Query Types:

• Existence: Does object X exist?
• Owner Binding: Is object X owned by entity Y?
• Attribute Bucket: Does object X have attribute in range [A, B]?
• Membership Proof: Prove object X is in registry

Query Response Verdicts:

• No: The predicate is false
• Yes: The predicate is true (with optional proof)
• Deny: The query is not authorized

All queries require capability tokens for authorization.

Macro Definition Documentation

UDIF_QUERY_MAX_PREDICATE_SIZE

#define UDIF_QUERY_MAX_PREDICATE_SIZE   1024U

Maximum query predicate data size.

Maximum query proof size.

UDIF_QUERY_RESPONSE_STRUCTURE_SIZE

#define UDIF_QUERY_RESPONSE_STRUCTURE_SIZE

Value:

    (UDIF_SIGNED_HASH_SIZE + \
    UDIF_QUERY_ID_SIZE + \
    UDIF_SERIAL_NUMBER_SIZE + \
    UDIF_QUERY_VERDICT_SIZE + \
    UDIF_VALID_TIME_SIZE + \
    UDIF_QUERY_PROOF_SIZE)

The query structure size.

UDIF_QUERY_STRUCTURE_SIZE

#define UDIF_QUERY_STRUCTURE_SIZE

Value:

    (UDIF_CRYPTO_HASH_SIZE + \
    UDIF_QUERY_ID_SIZE + \
    UDIF_SERIAL_NUMBER_SIZE + \
    UDIF_VALID_TIME_SIZE + \
    UDIF_QUERY_PREDICATE_SIZE + \
    UDIF_QUERY_TYPE_SIZE)

The query structure size.

Enumeration Type Documentation

udif_query_types

enum udif_query_types

Query predicate types.

Enumerator
udif_query_exist	Existence query
udif_query_owner_binding	Owner binding query
udif_query_attr_bucket	Attribute bucket query
udif_query_membership_proof	Membership proof query

udif_query_verdicts

enum udif_query_verdicts

Query response verdicts.

Enumerator
udif_verdict_no	Negative response
udif_verdict_yes	Positive response
udif_verdict_deny	Access denied

Function Documentation

udif_query_clear()

UDIF_EXPORT_API void udif_query_clear

(

udif_query *

query

)

Clear a query.

Zeros out a query structure.

Parameters

query

The query to clear

udif_query_compute_digest()

UDIF_EXPORT_API void udif_query_compute_digest	(	uint8_t *	digest,
		const udif_query *	query )

Compute query digest.

Calculates the canonical digest of a query for signing.

Parameters

digest	The output digest (32 bytes)
query	[const] The query

udif_query_create_attr_bucket()

UDIF_EXPORT_API udif_errors udif_query_create_attr_bucket	(	udif_query *	query,
		const uint8_t *	queryid,
		const uint8_t *	targetser,
		const uint8_t *	serial,
		uint64_t	attrmin,
		uint64_t	attrmax,
		uint64_t	timeanchor,
		const uint8_t *	capability )

Create an attribute bucket query.

Asks whether an object's attribute falls within a range.

Parameters

query	The output query structure
queryid	[const] The query identifier (32 bytes)
targetser	[const] The target entity serial (16 bytes)
serial	[const] The object serial (32 bytes)
attrmin	The minimum attribute value
attrmax	The maximum attribute value
timeanchor	The time anchor (0 = current)
capability	[const] The capability reference (32 bytes)

Returns

Returns udif_error_none on success

udif_query_create_existence()

UDIF_EXPORT_API udif_errors udif_query_create_existence	(	udif_query *	query,
		const uint8_t *	queryid,
		const uint8_t *	targetser,
		const uint8_t *	serial,
		uint64_t	timeanchor,
		const uint8_t *	capability )

Create an existence query.

Asks whether an object exists in the system.

Parameters

query	The output query structure
queryid	[const] The query identifier (32 bytes)
targetser	[const] The target entity serial (16 bytes)
serial	[const] The object serial to query (32 bytes)
timeanchor	The time anchor for temporal queries (0 = current)
capability	[const] The capability reference (32 bytes)

Returns

Returns udif_error_none on success

udif_query_create_membership_proof()

UDIF_EXPORT_API udif_errors udif_query_create_membership_proof	(	udif_query *	query,
		const uint8_t *	queryid,
		const uint8_t *	targetser,
		const uint8_t *	serial,
		uint64_t	timeanchor,
		const uint8_t *	capability )

Create a membership proof query.

Requests a Merkle proof that an object is in the registry.

Parameters

query	The output query structure
queryid	[const] The query identifier (32 bytes)
targetser	[const] The target entity serial (16 bytes)
serial	[const] The object serial (32 bytes)
timeanchor	The time anchor (0 = current)
capability	[const] The capability reference (32 bytes)

Returns

Returns udif_error_none on success

udif_query_create_owner_binding()

UDIF_EXPORT_API udif_errors udif_query_create_owner_binding	(	udif_query *	query,
		const uint8_t *	queryid,
		const uint8_t *	targetser,
		const uint8_t *	serial,
		const uint8_t *	ownerser,
		uint64_t	time_anchor,
		const uint8_t *	capability )

Create an owner binding query.

Asks whether an object is owned by a specific entity.

Parameters

query	The output query structure
queryid	[const] The query identifier (32 bytes)
targetser	[const] The target entity serial (16 bytes)
serial	[const] The object serial (32 bytes)
ownerser	[const] The claimed owner serial (16 bytes)
timeanchor	The time anchor (0 = current)
capability	[const] The capability reference (32 bytes)

Returns

Returns udif_error_none on success

udif_query_create_response()

UDIF_EXPORT_API udif_errors udif_query_create_response	(	udif_query_response *	response,
		const udif_query *	query,
		uint8_t	verdict,
		const uint8_t *	proofdata,
		size_t	prooflen,
		const uint8_t *	respser,
		const uint8_t *	respsigkey,
		uint64_t	ctime,
		bool(*	rng_generate )(uint8_t *, size_t) )

Create a query response.

Generates a response to a query.

Parameters

response	The output response structure
query	[const] The original query
verdict	The verdict (no, yes, deny)
proofdata	[const] The proof data (can be NULL)
prooflen	The proof data length
respser	[const] The responder's serial (16 bytes)
respsigkey	[const] The responder's private key
ctime	The current time (UTC seconds)
rng_generate	Random number generator function

Returns

Returns udif_error_none on success

udif_query_deserialize()

UDIF_EXPORT_API udif_errors udif_query_deserialize	(	udif_query *	query,
		const uint8_t *	input,
		size_t	inplen )

Deserialize a query.

Decodes a query from canonical format.

Parameters

query	The output query structure
input	[const] The input buffer
inplen	The input buffer length

Returns

Returns udif_error_none on success

udif_query_is_fresh()

UDIF_EXPORT_API bool udif_query_is_fresh	(	const udif_query *	query,
		uint64_t	ctime )

Check if query is fresh.

Verifies that a query is within the time window.

Parameters

query	[const] The query
ctime	The current time (UTC seconds)

Returns

Returns true if fresh

udif_query_response_clear()

UDIF_EXPORT_API void udif_query_response_clear

(

udif_query_response *

response

)

Clear a query response.

Zeros out and frees a query response structure.

Parameters

response

The response to clear

udif_query_response_compute_digest()

UDIF_EXPORT_API void udif_query_response_compute_digest	(	uint8_t *	digest,
		const udif_query_response *	response,
		const uint8_t *	queryid )

Compute response digest.

Calculates the canonical digest of a response for signing.

Parameters

digest	The output digest (32 bytes)
response	[const] The response
queryid	[const] The query identifier (32 bytes)

udif_query_response_deserialize()

UDIF_EXPORT_API udif_errors udif_query_response_deserialize	(	udif_query_response *	response,
		const uint8_t *	input,
		size_t	inplen )

Deserialize a query response.

Decodes a response from canonical format.

Parameters

response	The output response structure
input	[const] The input buffer
inplen	The input buffer length

Returns

Returns udif_error_none on success

udif_query_response_serialize()

UDIF_EXPORT_API udif_errors udif_query_response_serialize	(	uint8_t *	output,
		size_t *	outlen,
		const udif_query_response *	response )

Serialize a query response.

Encodes a response to canonical format.

Parameters

output	The output buffer
outlen	Pointer to output length (in: buffer size, out: bytes written)
response	[const] The response to serialize

Returns

Returns udif_error_none on success

udif_query_serialize()

UDIF_EXPORT_API udif_errors udif_query_serialize	(	uint8_t *	output,
		size_t *	outlen,
		const udif_query *	query )

Serialize a query.

Encodes a query to canonical format.

Parameters

output	The output buffer
outlen	Pointer to output length (in: buffer size, out: bytes written)
query	[const] The query to serialize

Returns

Returns udif_error_none on success

udif_query_validate_authorization()

UDIF_EXPORT_API bool udif_query_validate_authorization	(	const udif_query *	query,
		const udif_capability *	capability,
		const uint8_t *	targser )

Validate query authorization.

Checks that the query has appropriate capability authorization.

Parameters

query	[const] The query
capability	[const] The capability token
target_serial	[const] The target entity serial (16 bytes)

Returns

Returns true if authorized

udif_query_verify_response()

UDIF_EXPORT_API bool udif_query_verify_response	(	const udif_query_response *	response,
		const udif_query *	query,
		const uint8_t *	respverkey )

Verify a query response.

Verifies the signature on a query response.

Parameters

response	[const] The response to verify
query	[const] The original query
respverkey	[const] The responder's public key

Returns

Returns true if valid