query.h File Reference

UDIF query operations. More...

#include "udif.h"
#include "capability.h"
#include "registry.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_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 enum udif_query_types	udif_query_types
typedef 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 udif_query *query)
	Compute response digest.
UDIF_EXPORT_API bool	udif_query_verify_response_signature (const udif_query_response *response, const uint8_t *respverkey)
	Verify a query response signature over the embedded query 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_predicate_is_canonical (const udif_query *query)
	Validate the canonical predicate size for a query type.
UDIF_EXPORT_API udif_errors	udif_query_evaluate_registry (uint8_t *verdict, uint8_t *proof, size_t *prooflen, const udif_query *query, const udif_registry_state *registry, const udif_capability *capability, const uint8_t *subjectser, uint64_t ctime)
	Evaluate a query against a UA registry.
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_CRYPTO_HASH_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_evaluate_registry()

UDIF_EXPORT_API udif_errors udif_query_evaluate_registry	(	uint8_t *	verdict,
		uint8_t *	proof,
		size_t *	prooflen,
		const udif_query *	query,
		const udif_registry_state *	registry,
		const udif_capability *	capability,
		const uint8_t *	subjectser,
		uint64_t	ctime )

Evaluate a query against a UA registry.

Applies capability authorization and evaluates the query predicate against the supplied registry. Unauthorized queries return a DENY verdict without leaking target state. Membership-proof queries write the proof to the supplied proof buffer when authorized and true.

Parameters

verdict	The output verdict.
proof	The output proof buffer, or NULL when no proof is requested.
prooflen	The proof length, in/out, or NULL when no proof is requested.
query	[const] The query to evaluate.
registry	[const] The registry to evaluate against.
capability	[const] The caller capability token.
subjectser	[const] The caller certificate serial.
ctime	The current UTC time.

Returns

Returns udif_error_none on a completed evaluation.

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_predicate_is_canonical()

UDIF_EXPORT_API bool udif_query_predicate_is_canonical

(

const udif_query *

query

)

Validate the canonical predicate size for a query type.

Checks that the query type is one of the core UDIF predicate families and that the predicate buffer has the exact canonical size required for that family.

Parameters

query

[const] The query to validate.

Returns

Returns true if the query predicate form is canonical.

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 udif_query *	query )

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

udif_query_verify_response_signature()

UDIF_EXPORT_API bool udif_query_verify_response_signature	(	const udif_query_response *	response,
		const uint8_t *	respverkey )

Verify a query response signature over the embedded query digest.

Parameters

response	[const] The response to verify.
respverkey	[const] The responder verification key.

Returns

Returns true if the signature verifies.