capability.h File Reference

UDIF capability token management. More...

#include "udif.h"

Go to the source code of this file.

Data Structures
struct	udif_capability
	Capability token. More...

Macros
#define	UDIF_CAP_QUERY_EXIST   (UINT64_C(1) << 0)
	Grants permission to issue existence queries.
#define	UDIF_CAP_QUERY_OWNER_BINDING   (UINT64_C(1) << 1)
	Grants permission to query object ownership binding.
#define	UDIF_CAP_QUERY_ATTR_BUCKET   (UINT64_C(1) << 2)
	Grants permission to query predefined attribute buckets.
#define	UDIF_CAP_PROVE_MEMBERSHIP   (UINT64_C(1) << 3)
	Grants permission to request Merkle membership proofs.
#define	UDIF_CAP_FORWARD_QUERY   (UINT64_C(1) << 4)
	Grants permission to forward authorized queries.
#define	UDIF_CAP_ADMIN_ENROLL   (UINT64_C(1) << 5)
	Grants permission to enroll subordinate entities.
#define	UDIF_CAP_ADMIN_SUSPEND   (UINT64_C(1) << 6)
	Grants permission to suspend subordinate certificates.
#define	UDIF_CAP_ADMIN_RESUME   (UINT64_C(1) << 7)
	Grants permission to resume suspended subordinate certificates.
#define	UDIF_CAP_ADMIN_REVOKE   (UINT64_C(1) << 8)
	Grants permission to revoke subordinate certificates.
#define	UDIF_CAP_ADMIN_BRANCH_CREATE   (UINT64_C(1) << 9)
	Grants permission to create subordinate branches or groups.
#define	UDIF_CAP_ADMIN_BRANCH_RETIRE   (UINT64_C(1) << 10)
	Grants permission to retire or prune subordinate branches.
#define	UDIF_CAP_REGISTRY_COMMIT   (UINT64_C(1) << 11)
	Grants permission to commit registry roots.
#define	UDIF_CAP_TX_CREATE   (UINT64_C(1) << 12)
	Grants permission to originate transaction events.
#define	UDIF_CAP_TX_ACCEPT   (UINT64_C(1) << 13)
	Grants permission to accept incoming transaction transfers.
#define	UDIF_CAP_LOG_ANCHOR_SEND   (UINT64_C(1) << 14)
	Grants permission to generate and send Anchor Records upstream.
#define	UDIF_CAP_LOG_ANCHOR_VERIFY   (UINT64_C(1) << 15)
	Grants permission to verify and append child Anchor Records.
#define	UDIF_CAP_TREATY_NEGOTIATE   (UINT64_C(1) << 16)
	Grants permission to negotiate and sign Peering Treaties.
#define	UDIF_CAP_TREATY_QUERY_EXEC   (UINT64_C(1) << 17)
	Grants permission to execute treaty-scoped queries.
#define	UDIF_CAP_TREATY_QUERY_ORIGIN   (UINT64_C(1) << 18)
	Grants permission to originate treaty-scoped queries.
#define	UDIF_CAP_TELEMETRY_EXPORT   (UINT64_C(1) << 19)
	Grants permission to export telemetry counters.
#define	UDIF_CAP_ERROR_REPORT   (UINT64_C(1) << 20)
	Grants permission to issue signed error events into logs.
#define	UDIF_CAP_RESERVED_FUTURE_CORE_MASK   (UINT64_C(0x00000000FFE00000))
	Reserved capability bits for future UDIF core extensions.
#define	UDIF_CAP_RESERVED_PROFILE_MASK   (UINT64_C(0xFFFFFFFF00000000))
	Reserved capability bits for profile-specific extensions.
#define	UDIF_CAP_QUERY_MASK
	Mask of all core predicate-query capabilities.
#define	UDIF_CAP_ADMIN_MASK
	Mask of all core administrative capabilities.
#define	UDIF_CAP_TRANSACTION_MASK
	Mask of all core transaction and registry capabilities.
#define	UDIF_CAP_ANCHOR_MASK
	Mask of all core anchoring capabilities.
#define	UDIF_CAP_TREATY_MASK
	Mask of all core treaty capabilities.
#define	UDIF_CAP_AUDIT_MASK
	Mask of core audit-support capabilities.
#define	UDIF_ROOT_CAPABILITIES
	Default capability mask for a UDIF Root certificate.
#define	UDIF_BC_CAPABILITIES
	Default capability mask for a UDIF Branch Controller certificate.
#define	UDIF_GC_CAPABILITIES
	Default capability mask for a UDIF Group Controller certificate.
#define	UDIF_CLIENT_CAPABILITIES
	Default capability mask for a UDIF client or User Agent certificate.
#define	UDIF_CAP_CORE_DEFINED_MASK
	Mask of all UDIF v1 core-defined capability bits.
#define	UDIF_TREATY_ORIGIN_CAPABILITIES   (UDIF_CAP_FORWARD_QUERY | UDIF_CAP_TREATY_QUERY_ORIGIN)
	Optional capability overlay for originating treaty-scoped queries.
#define	UDIF_TREATY_EXEC_CAPABILITIES   (UDIF_CAP_TREATY_QUERY_EXEC)
	Optional capability overlay for executing treaty-scoped queries.
#define	UDIF_TREATY_ADMIN_CAPABILITIES   (UDIF_CAP_TREATY_NEGOTIATE)
	Optional capability overlay for treaty negotiation.
#define	UDIF_CAP_NONE   (UINT64_C(0))
	Empty capability mask.
#define	UDIF_CAP_ALL_CORE   (UDIF_CAP_CORE_DEFINED_MASK)
	Mask containing all UDIF v1 core-defined capabilities.
#define	UDIF_CAPABILITY_POLICY_SIZE   8U
#define	UDIF_CAPABILITY_ENCODED_SIZE
	The capability structure encoded size.
#define	UDIF_CAPABILITY_SIGNED_SIZE
	The capability structure signed size.
#define	UDIF_CAPABILITY_ALL   UINT64_C(0x00000000001FFFFF)
	Full capability bitmap granting all defined verb bits.

Typedefs
typedef UDIF_EXPORT_API struct udif_capability	udif_capability
typedef enum udif_capability_id	udif_capability_id
typedef enum udif_capability_verbs	udif_capability_verbs
typedef enum udif_capability_scopes	udif_capability_scopes

Enumerations
enum	udif_capability_id {   udif_capability_issue_certificate = 0x00U , udif_capability_revoke_certificate = 0x01U , udif_capability_issue_token = 0x02U , udif_capability_validate_token = 0x03U ,   udif_capability_register_issuer = 0x04U , udif_capability_rotate_keys = 0x05U , udif_capability_directory_query = 0x06U , udif_capability_audit_logging_access = 0x07U ,   udif_capability_admin = 0x08U }
	Canonical capability identifiers (bit positions map to the mask). More...
enum	udif_capability_verbs {   udif_capability_query_exist = 0U , udif_capability_query_owner_binding = 1U , udif_capability_query_attr_bucket = 2U , udif_capability_prove_membership = 3U ,   udif_capability_forward_query = 4U , udif_capability_admin_enroll = 5U , udif_capability_admin_suspend = 6U , udif_capability_admin_resume = 7U ,   udif_capability_admin_revoke = 8U , udif_capability_admin_branch_create = 9U , udif_capability_admin_branch_retire = 10U , udif_capability_registry_commit = 11U ,   udif_capability_tx_create = 12U , udif_capability_tx_accept = 13U , udif_capability_logging_anchor_send = 14U , udif_capability_logging_anchor_verify = 15U ,   udif_capability_treaty_negotiate = 16U , udif_capability_treaty_query_exec = 17U , udif_capability_treaty_query_origin = 18U , udif_capability_telemetry_export = 19U ,   udif_capability_error_report = 20U }
	Capability permission verbs (bit positions) More...
enum	udif_capability_scopes { udif_scope_local = 0U , udif_scope_intra_domain = 1U , udif_scope_treaty = 2U }
	Capability scope flags. More...

Functions
UDIF_EXPORT_API bool	udif_capability_allows_scope (const udif_capability *capability, uint32_t scope)
	Check if capability allows a scope.
UDIF_EXPORT_API bool	udif_capability_allows_verb (const udif_capability *capability, uint32_t verb)
	Check if capability allows a verb.
UDIF_EXPORT_API void	udif_capability_clear (udif_capability *capability)
	Clear a capability.
UDIF_EXPORT_API udif_errors	udif_capability_create (udif_capability *capability, uint32_t verbsbitmap, uint32_t scopebitmap, const uint8_t *issuedto, const uint8_t *issuedby, uint64_t validto, uint32_t policy, const uint8_t *issuerkey)
	Create a capability token.
UDIF_EXPORT_API udif_errors	udif_capability_compute_digest (uint8_t *digest, const udif_capability *capability)
	Compute object digest.
UDIF_EXPORT_API udif_errors	udif_capability_deserialize (udif_capability *capability, const uint8_t *input, size_t inplen)
	Deserialize a capability.
UDIF_EXPORT_API bool	udif_capability_grants_permission (const udif_capability *capability, uint32_t verb, uint32_t scope, uint64_t ctime)
	Check if capability grants permission.
UDIF_EXPORT_API bool	udif_capability_is_expired (const udif_capability *capability, uint64_t ctime)
	Check if capability is expired.
UDIF_EXPORT_API udif_errors	udif_capability_serialize (uint8_t *output, size_t outlen, const udif_capability *capability)
	Serialize a capability.
UDIF_EXPORT_API bool	udif_capability_verify (const udif_capability *capability, const uint8_t *issuerkey)
	Verify a capability token.

Detailed Description

UDIF capability token management.

This module implements capability-based access control for UDIF. Capabilities are unforgeable tokens that grant specific permissions to entities. They use KMAC-256 for authentication.

Capabilities define:

• Verbs: What operations are allowed
• Scopes: Where operations can be performed
• Subject: Who holds the capability
• Issuer: Who granted the capability
• Validity: When the capability expires

Macro Definition Documentation

UDIF_BC_CAPABILITIES

#define UDIF_BC_CAPABILITIES

Value:

    (UDIF_CAP_FORWARD_QUERY | \
     UDIF_CAP_ADMIN_ENROLL | \
     UDIF_CAP_ADMIN_SUSPEND | \
     UDIF_CAP_ADMIN_RESUME | \
     UDIF_CAP_ADMIN_REVOKE | \
     UDIF_CAP_ADMIN_BRANCH_CREATE | \
     UDIF_CAP_ADMIN_BRANCH_RETIRE | \
     UDIF_CAP_LOG_ANCHOR_SEND | \
     UDIF_CAP_LOG_ANCHOR_VERIFY | \
     UDIF_CAP_TELEMETRY_EXPORT | \
     UDIF_CAP_ERROR_REPORT)

Default capability mask for a UDIF Branch Controller certificate.

The Branch Controller capability mask grants authority to administer a subordinate branch or group subtree. It permits enrollment and lifecycle control of subordinate certificates, creation and retirement of subordinate branches or groups, forwarding of authorized queries, generation of upstream Anchor Records, verification of child Anchor Records, export of permitted telemetry counters, and issuance of signed operational error reports.

This mask is appropriate for a Branch Controller operating in branch-admin mode. A Branch Controller operating as a Group Controller should instead use the Group Controller capability mask.

Treaty capabilities are excluded from this default mask. They should be granted only when a valid Peering Treaty and parent policy explicitly permit cross-domain operation.

UDIF_CAP_ADMIN_BRANCH_CREATE

#define UDIF_CAP_ADMIN_BRANCH_CREATE   (UINT64_C(1) << 9)

Grants permission to create subordinate branches or groups.

Allows a Branch Controller to instantiate a subordinate Branch Controller or Group Controller. This bit should not be granted to User Agents.

UDIF_CAP_ADMIN_BRANCH_RETIRE

#define UDIF_CAP_ADMIN_BRANCH_RETIRE   (UINT64_C(1) << 10)

Grants permission to retire or prune subordinate branches.

Allows a Branch Controller to permanently retire, prune, or decommission a subordinate branch according to policy and audit requirements.

UDIF_CAP_ADMIN_ENROLL

#define UDIF_CAP_ADMIN_ENROLL   (UINT64_C(1) << 5)

Grants permission to enroll subordinate entities.

Allows the holder to enroll new User Agents, Group Controllers, or subordinate Branch Controllers, depending on the holder role and parent-issued scope.

UDIF_CAP_ADMIN_MASK

#define UDIF_CAP_ADMIN_MASK

Value:

    (UDIF_CAP_ADMIN_ENROLL | \
     UDIF_CAP_ADMIN_SUSPEND | \
     UDIF_CAP_ADMIN_RESUME | \
     UDIF_CAP_ADMIN_REVOKE | \
     UDIF_CAP_ADMIN_BRANCH_CREATE | \
     UDIF_CAP_ADMIN_BRANCH_RETIRE)

Mask of all core administrative capabilities.

UDIF_CAP_ADMIN_RESUME

#define UDIF_CAP_ADMIN_RESUME   (UINT64_C(1) << 7)

Grants permission to resume suspended subordinate certificates.

Allows the holder to restore a previously suspended User Agent, Group Controller, or Branch Controller when policy and audit conditions are met.

UDIF_CAP_ADMIN_REVOKE

#define UDIF_CAP_ADMIN_REVOKE   (UINT64_C(1) << 8)

Grants permission to revoke subordinate certificates.

Allows the holder to permanently revoke User Agent, Group Controller, or Branch Controller certificates within the holder's delegated authority.

UDIF_CAP_ADMIN_SUSPEND

#define UDIF_CAP_ADMIN_SUSPEND   (UINT64_C(1) << 6)

Grants permission to suspend subordinate certificates.

Allows the holder to temporarily suspend User Agents, Group Controllers, or Branch Controllers pending audit, investigation, or policy review.

UDIF_CAP_ALL_CORE

#define UDIF_CAP_ALL_CORE   (UDIF_CAP_CORE_DEFINED_MASK)

Mask containing all UDIF v1 core-defined capabilities.

This mask is intended for validation, testing, and issuer-side policy construction. It should not be assigned blindly to subordinate certificates.

UDIF_CAP_ANCHOR_MASK

#define UDIF_CAP_ANCHOR_MASK

Value:

    (UDIF_CAP_LOG_ANCHOR_SEND | \
     UDIF_CAP_LOG_ANCHOR_VERIFY)

Mask of all core anchoring capabilities.

UDIF_CAP_AUDIT_MASK

#define UDIF_CAP_AUDIT_MASK

Value:

    (UDIF_CAP_TELEMETRY_EXPORT | \
     UDIF_CAP_ERROR_REPORT)

Mask of core audit-support capabilities.

UDIF_CAP_CORE_DEFINED_MASK

#define UDIF_CAP_CORE_DEFINED_MASK

Value:

    (UDIF_CAP_QUERY_EXIST | \
     UDIF_CAP_QUERY_OWNER_BINDING | \
     UDIF_CAP_QUERY_ATTR_BUCKET | \
     UDIF_CAP_PROVE_MEMBERSHIP | \
     UDIF_CAP_FORWARD_QUERY | \
     UDIF_CAP_ADMIN_ENROLL | \
     UDIF_CAP_ADMIN_SUSPEND | \
     UDIF_CAP_ADMIN_RESUME | \
     UDIF_CAP_ADMIN_REVOKE | \
     UDIF_CAP_ADMIN_BRANCH_CREATE | \
     UDIF_CAP_ADMIN_BRANCH_RETIRE | \
     UDIF_CAP_REGISTRY_COMMIT | \
     UDIF_CAP_TX_CREATE | \
     UDIF_CAP_TX_ACCEPT | \
     UDIF_CAP_LOG_ANCHOR_SEND | \
     UDIF_CAP_LOG_ANCHOR_VERIFY | \
     UDIF_CAP_TREATY_NEGOTIATE | \
     UDIF_CAP_TREATY_QUERY_EXEC | \
     UDIF_CAP_TREATY_QUERY_ORIGIN | \
     UDIF_CAP_TELEMETRY_EXPORT | \
     UDIF_CAP_ERROR_REPORT)

Mask of all UDIF v1 core-defined capability bits.

Includes all normative UDIF v1 capability bits from bit 0 through bit 20.

UDIF_CAP_ERROR_REPORT

#define UDIF_CAP_ERROR_REPORT   (UINT64_C(1) << 20)

Grants permission to issue signed error events into logs.

Allows the holder to create signed error reports or audit events and append them to the appropriate membership, transaction, or operational log.

UDIF_CAP_FORWARD_QUERY

#define UDIF_CAP_FORWARD_QUERY   (UINT64_C(1) << 4)

Grants permission to forward authorized queries.

Allows a Group Controller or Branch Controller to forward queries upstream or across treaty peers, subject to scope, treaty, and policy restrictions.

UDIF_CAP_LOG_ANCHOR_SEND

#define UDIF_CAP_LOG_ANCHOR_SEND   (UINT64_C(1) << 14)

Grants permission to generate and send Anchor Records upstream.

Allows a Group Controller or Branch Controller to generate signed Anchor Records and submit them to its parent authority.

UDIF_CAP_LOG_ANCHOR_VERIFY

#define UDIF_CAP_LOG_ANCHOR_VERIFY   (UINT64_C(1) << 15)

Grants permission to verify and append child Anchor Records.

Allows a parent controller to verify signed Anchor Records received from subordinate controllers and append accepted anchors to its logs.

UDIF_CAP_NONE

#define UDIF_CAP_NONE   (UINT64_C(0))

Empty capability mask.

Represents the UDIF default-deny state. A certificate or capability token with this mask grants no operational rights.

UDIF_CAP_PROVE_MEMBERSHIP

#define UDIF_CAP_PROVE_MEMBERSHIP   (UINT64_C(1) << 3)

Grants permission to request Merkle membership proofs.

Allows the holder to request membership or registry proofs for Objects, registries, or committed records where such proofs are authorized by policy.

UDIF_CAP_QUERY_ATTR_BUCKET

#define UDIF_CAP_QUERY_ATTR_BUCKET   (UINT64_C(1) << 2)

Grants permission to query predefined attribute buckets.

Allows the holder to evaluate approved attribute-bucket predicates, such as active, suspended, destroyed, or other profile-defined bucket states, without exposing raw attribute values.

UDIF_CAP_QUERY_EXIST

#define UDIF_CAP_QUERY_EXIST   (UINT64_C(1) << 0)

Grants permission to issue existence queries.

Allows the holder to query whether a User Agent or Object exists within the authorized local, domain, or treaty scope. Responses are limited to minimal disclosure yes/no semantics.

UDIF_CAP_QUERY_MASK

#define UDIF_CAP_QUERY_MASK

Value:

    (UDIF_CAP_QUERY_EXIST | \
     UDIF_CAP_QUERY_OWNER_BINDING | \
     UDIF_CAP_QUERY_ATTR_BUCKET | \
     UDIF_CAP_PROVE_MEMBERSHIP)

Mask of all core predicate-query capabilities.

UDIF_CAP_QUERY_OWNER_BINDING

#define UDIF_CAP_QUERY_OWNER_BINDING   (UINT64_C(1) << 1)

Grants permission to query object ownership binding.

Allows the holder to query whether a specified Object is currently bound to, or owned by, a specified User Agent within the authorized scope.

UDIF_CAP_REGISTRY_COMMIT

#define UDIF_CAP_REGISTRY_COMMIT   (UINT64_C(1) << 11)

Grants permission to commit registry roots.

Allows User Agents to commit their own registry roots, or Group Controllers to commit group registry state, depending on role and delegated scope.

UDIF_CAP_RESERVED_FUTURE_CORE_MASK

#define UDIF_CAP_RESERVED_FUTURE_CORE_MASK   (UINT64_C(0x00000000FFE00000))

Reserved capability bits for future UDIF core extensions.

Bits 21 through 31 are reserved for future UDIF core capability assignments. These bits must be zero in UDIF v1 certificates and capability tokens unless a later core revision explicitly defines them.

UDIF_CAP_RESERVED_PROFILE_MASK

#define UDIF_CAP_RESERVED_PROFILE_MASK   (UINT64_C(0xFFFFFFFF00000000))

Reserved capability bits for profile-specific extensions.

Bits 32 through 63 are reserved for profile-specific, jurisdictional, audit, privacy, or zero-knowledge extension profiles. Core implementations must not assign conflicting meanings to these bits.

UDIF_CAP_TELEMETRY_EXPORT

#define UDIF_CAP_TELEMETRY_EXPORT   (UINT64_C(1) << 19)

Grants permission to export telemetry counters.

Allows the holder to export authorized telemetry counters in Anchor Records. Telemetry export must not disclose raw identifiers, attributes, or private transaction contents.

UDIF_CAP_TRANSACTION_MASK

#define UDIF_CAP_TRANSACTION_MASK

Value:

    (UDIF_CAP_REGISTRY_COMMIT | \
     UDIF_CAP_TX_CREATE | \
     UDIF_CAP_TX_ACCEPT)

Mask of all core transaction and registry capabilities.

UDIF_CAP_TREATY_MASK

#define UDIF_CAP_TREATY_MASK

Value:

    (UDIF_CAP_TREATY_NEGOTIATE | \
     UDIF_CAP_TREATY_QUERY_EXEC | \
     UDIF_CAP_TREATY_QUERY_ORIGIN)

Mask of all core treaty capabilities.

UDIF_CAP_TREATY_NEGOTIATE

#define UDIF_CAP_TREATY_NEGOTIATE   (UINT64_C(1) << 16)

Grants permission to negotiate and sign Peering Treaties.

Allows an authorized Branch Controller or Group Controller to negotiate, approve, and sign treaty records with a peer domain controller.

UDIF_CAP_TREATY_QUERY_EXEC

#define UDIF_CAP_TREATY_QUERY_EXEC   (UINT64_C(1) << 17)

Grants permission to execute treaty-scoped queries.

Allows the holder to process incoming treaty queries within the predicate families and bounds explicitly allowed by a valid Peering Treaty.

UDIF_CAP_TREATY_QUERY_ORIGIN

#define UDIF_CAP_TREATY_QUERY_ORIGIN   (UINT64_C(1) << 18)

Grants permission to originate treaty-scoped queries.

Allows the holder to originate cross-domain treaty queries to a peer domain, subject to a valid treaty, predicate scope, and policy epoch.

UDIF_CAP_TX_ACCEPT

#define UDIF_CAP_TX_ACCEPT   (UINT64_C(1) << 13)

Grants permission to accept incoming transaction transfers.

Allows the holder to co-sign and accept incoming object transfers or other transaction events requiring counterparty acceptance.

UDIF_CAP_TX_CREATE

#define UDIF_CAP_TX_CREATE   (UINT64_C(1) << 12)

Grants permission to originate transaction events.

Allows the holder to originate transaction events, including object creation, object update, or object transfer initiation, subject to role and ownership checks.

UDIF_CAPABILITY_ALL

#define UDIF_CAPABILITY_ALL   UINT64_C(0x00000000001FFFFF)

Full capability bitmap granting all defined verb bits.

Used when generating root or first-level subordinate certificates that require unrestricted operational capabilities within the domain. Covers all 21 defined verbs (bits 0-20).

UDIF_CAPABILITY_ENCODED_SIZE

#define UDIF_CAPABILITY_ENCODED_SIZE

Value:

    (UDIF_CRYPTO_HASH_SIZE + \
    UDIF_CRYPTO_MAC_SIZE + \
    UDIF_SERIAL_NUMBER_SIZE + \
    UDIF_SERIAL_NUMBER_SIZE + \
    UDIF_CAPABILITY_BITMAP_SIZE + \
    UDIF_VALID_TIME_SIZE + \
    UDIF_CAPABILITY_BITMAP_SIZE + \
    UDIF_CAPABILITY_POLICY_SIZE)

The capability structure encoded size.

UDIF_CAPABILITY_SIGNED_SIZE

#define UDIF_CAPABILITY_SIGNED_SIZE

Value:

    (UDIF_SERIAL_NUMBER_SIZE + \
    UDIF_SERIAL_NUMBER_SIZE + \
    UDIF_CAPABILITY_BITMAP_SIZE + \
    UDIF_VALID_TIME_SIZE + \
    UDIF_CAPABILITY_BITMAP_SIZE + \
    UDIF_CAPABILITY_POLICY_SIZE)

The capability structure signed size.

UDIF_CLIENT_CAPABILITIES

#define UDIF_CLIENT_CAPABILITIES

Value:

    (UDIF_CAP_QUERY_EXIST | \
     UDIF_CAP_QUERY_OWNER_BINDING | \
     UDIF_CAP_QUERY_ATTR_BUCKET | \
     UDIF_CAP_PROVE_MEMBERSHIP | \
     UDIF_CAP_REGISTRY_COMMIT | \
     UDIF_CAP_TX_CREATE | \
     UDIF_CAP_TX_ACCEPT | \
     UDIF_CAP_ERROR_REPORT)

Default capability mask for a UDIF client or User Agent certificate.

The client capability mask grants only end-entity rights. It permits minimal predicate queries, membership-proof requests where authorized, registry-root commitment for the client's own registry, transaction creation, transaction acceptance, and signed error reporting.

A client must not receive administrative, branch-management, anchor-verifier, treaty-negotiation, or query-forwarding capabilities. User Agents are leaf entities in the UDIF hierarchy and cannot administer other certificates or interact laterally outside their Group Controller.

Note

In a stricter deployment profile, UDIF_CAP_PROVE_MEMBERSHIP may be removed from this default and issued only through a separate GC-signed capability token.

UDIF_GC_CAPABILITIES

#define UDIF_GC_CAPABILITIES

Value:

    (UDIF_CAP_FORWARD_QUERY | \
     UDIF_CAP_ADMIN_ENROLL | \
     UDIF_CAP_ADMIN_SUSPEND | \
     UDIF_CAP_ADMIN_RESUME | \
     UDIF_CAP_ADMIN_REVOKE | \
     UDIF_CAP_REGISTRY_COMMIT | \
     UDIF_CAP_LOG_ANCHOR_SEND | \
     UDIF_CAP_TELEMETRY_EXPORT | \
     UDIF_CAP_ERROR_REPORT)

Default capability mask for a UDIF Group Controller certificate.

The Group Controller capability mask grants authority to administer User Agents within a group. It permits enrollment, suspension, resumption, and revocation of User Agent certificates, forwarding of authorized queries, registry-root commitment on behalf of the managed group, generation of upstream Anchor Records, export of permitted telemetry counters, and issuance of signed operational error reports.

The mask intentionally excludes branch creation and branch retirement because a Group Controller directly manages User Agents and must not create subordinate administrative branches.

Transaction origination and acceptance are excluded by default because those capabilities belong to User Agents as object owners. The Group Controller validates, logs, and anchors transaction evidence, but it does not own objects and should not receive object-owner transaction rights unless a specific implementation profile defines a separate service-actor role.

UDIF_ROOT_CAPABILITIES

#define UDIF_ROOT_CAPABILITIES

Value:

    (UDIF_CAP_ADMIN_ENROLL | \
     UDIF_CAP_ADMIN_SUSPEND | \
     UDIF_CAP_ADMIN_RESUME | \
     UDIF_CAP_ADMIN_REVOKE | \
     UDIF_CAP_ADMIN_BRANCH_CREATE | \
     UDIF_CAP_ADMIN_BRANCH_RETIRE | \
     UDIF_CAP_LOG_ANCHOR_VERIFY)

Default capability mask for a UDIF Root certificate.

The Root capability mask grants only domain-anchor and top-level issuance authority. It permits the Root to issue, suspend, resume, revoke, create, and retire subordinate branch authorities, and to verify Anchor Records submitted by immediate children.

The Root mask intentionally excludes User Agent, object ownership, registry mutation, transaction origination, and treaty-query capabilities. The Root is the trust anchor and policy origin for the domain; operational authority is delegated to Branch Controllers and Group Controllers through signed subordinate certificates.

Warning

This mask is an issuer-side maximum for Root operation. It must not be copied blindly into subordinate certificates.

UDIF_TREATY_ADMIN_CAPABILITIES

#define UDIF_TREATY_ADMIN_CAPABILITIES   (UDIF_CAP_TREATY_NEGOTIATE)

Optional capability overlay for treaty negotiation.

Grants the ability to negotiate and sign Peering Treaties. This capability should normally be restricted to authorized Branch Controllers or specially designated Group Controllers.

UDIF_TREATY_EXEC_CAPABILITIES

#define UDIF_TREATY_EXEC_CAPABILITIES   (UDIF_CAP_TREATY_QUERY_EXEC)

Optional capability overlay for executing treaty-scoped queries.

Grants the ability to process treaty queries received from a peer domain. This mask must be constrained by the Peering Treaty, local policy, and the certificate's role.

UDIF_TREATY_ORIGIN_CAPABILITIES

#define UDIF_TREATY_ORIGIN_CAPABILITIES   (UDIF_CAP_FORWARD_QUERY | UDIF_CAP_TREATY_QUERY_ORIGIN)

Optional capability overlay for originating treaty-scoped queries.

Grants the ability to originate treaty queries and forward them to a peer domain. This mask must be applied only when an active Peering Treaty and parent policy explicitly authorize the predicate family and peer scope.

Enumeration Type Documentation

udif_capability_id

enum udif_capability_id

Canonical capability identifiers (bit positions map to the mask).

NO_DOCUMENT

Enumerator
udif_capability_issue_certificate	Issue subordinate certificates
udif_capability_revoke_certificate	Revoke certificates
udif_capability_issue_token	Issue capability/attestation tokens
udif_capability_validate_token	Validate tokens and claims
udif_capability_register_issuer	Register issuer domain codes
udif_capability_rotate_keys	Rotate root/issuer keys
udif_capability_directory_query	Query directory / discovery
udif_capability_audit_logging_access	Access audit logs
udif_capability_admin	Administrative override

udif_capability_scopes

enum udif_capability_scopes

Capability scope flags.

Enumerator
udif_scope_local	Local only
udif_scope_intra_domain	Intra-domain
udif_scope_treaty	Cross-domain treaty

udif_capability_verbs

enum udif_capability_verbs

Capability permission verbs (bit positions)

Enumerator
udif_capability_query_exist	Query existence
udif_capability_query_owner_binding	Query owner binding
udif_capability_query_attr_bucket	Query attribute bucket
udif_capability_prove_membership	Prove membership
udif_capability_forward_query	Forward query
udif_capability_admin_enroll	Enroll entity
udif_capability_admin_suspend	Suspend entity
udif_capability_admin_resume	Resume entity
udif_capability_admin_revoke	Revoke entity
udif_capability_admin_branch_create	Create branch
udif_capability_admin_branch_retire	Retire branch
udif_capability_registry_commit	Commit registry
udif_capability_tx_create	Create transaction
udif_capability_tx_accept	Accept transaction
udif_capability_logging_anchor_send	Send anchor
udif_capability_logging_anchor_verify	Verify anchor
udif_capability_treaty_negotiate	Negotiate treaty
udif_capability_treaty_query_exec	Execute treaty query
udif_capability_treaty_query_origin	Originate treaty query
udif_capability_telemetry_export	Export telemetry
udif_capability_error_report	Report error

Function Documentation

udif_capability_allows_scope()

UDIF_EXPORT_API bool udif_capability_allows_scope	(	const udif_capability *	capability,
		uint32_t	scope )

Check if capability allows a scope.

Tests if a specific operation scope is granted.

Parameters

capability	[const] The capability
scope	The scope to check

Returns

Returns true if allowed

udif_capability_allows_verb()

UDIF_EXPORT_API bool udif_capability_allows_verb	(	const udif_capability *	capability,
		uint32_t	verb )

Check if capability allows a verb.

Tests if a specific operation verb is granted.

Parameters

capability	[const] The capability
verb	The verb to check (bit position)

Returns

Returns true if allowed

udif_capability_clear()

UDIF_EXPORT_API void udif_capability_clear

(

udif_capability *

capability

)

Clear a capability.

Zeros out a capability structure.

Parameters

capability

The capability to clear

udif_capability_compute_digest()

UDIF_EXPORT_API udif_errors udif_capability_compute_digest	(	uint8_t *	digest,
		const udif_capability *	capability )

Compute object digest.

Computes the canonical digest for an object, does not include the signature and hash.

Parameters

digest	The output digest (32 bytes)
capability	The output capability structure

Returns

Returns udif_error_none on success

udif_capability_create()

UDIF_EXPORT_API udif_errors udif_capability_create	(	udif_capability *	capability,
		uint32_t	verbsbitmap,
		uint32_t	scopebitmap,
		const uint8_t *	issuedto,
		const uint8_t *	issuedby,
		uint64_t	validto,
		uint32_t	policy,
		const uint8_t *	issuerkey )

Create a capability token.

Creates a new capability token authenticated with KMAC-256.

Parameters

capability	The output capability structure
verbsbitmap	The allowed operation verbs
scopebitmap	The allowed operation scopes
issuedto	[const] The recipient serial (16 bytes)
issuedby	[const] The issuer serial (16 bytes)
validto	The expiration time (UTC seconds)
policy	The policy version number
issuerkey	[const] The issuer's MAC key

Returns

Returns udif_error_none on success

udif_capability_deserialize()

UDIF_EXPORT_API udif_errors udif_capability_deserialize	(	udif_capability *	capability,
		const uint8_t *	input,
		size_t	inplen )

Deserialize a capability.

Decodes a capability from canonical TLV format.

Parameters

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

Returns

Returns udif_error_none on success

udif_capability_grants_permission()

UDIF_EXPORT_API bool udif_capability_grants_permission	(	const udif_capability *	capability,
		uint32_t	verb,
		uint32_t	scope,
		uint64_t	ctime )

Check if capability grants permission.

Comprehensive check: verb, scope, and expiration.

Parameters

capability	[const] The capability
verb	The required verb
scope	The required scope
ctime	The current time

Returns

Returns true if permission granted

udif_capability_is_expired()

UDIF_EXPORT_API bool udif_capability_is_expired	(	const udif_capability *	capability,
		uint64_t	ctime )

Check if capability is expired.

Tests if a capability has expired.

Parameters

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

Returns

Returns true if expired

udif_capability_serialize()

UDIF_EXPORT_API udif_errors udif_capability_serialize	(	uint8_t *	output,
		size_t	outlen,
		const udif_capability *	capability )

Serialize a capability.

Encodes a capability to canonical TLV format.

Parameters

output	The output buffer
outlen	The output buffer LENGTH
capability	[const] The capability to serialize

Returns

Returns udif_error_none on success

udif_capability_verify()

UDIF_EXPORT_API bool udif_capability_verify	(	const udif_capability *	capability,
		const uint8_t *	issuerkey )

Verify a capability token.

Verifies the KMAC authentication tag on a capability.

Parameters

capability	[const] The capability to verify
issuerkey	[const] The issuer's MAC key

Returns

Returns true if valid