Capability management — acquire, release, derive, and validate capability tokens for the DGP kernel's authorization model. More...

import std;
import lib.error;
import zxfoundation.memory.objects.core;
import zxfoundation.dgp.portal.types;
import zxfoundation.dgp.gate.types;
import zxfoundation.dgp.domain.types;
import zxfoundation.scoms.kobject.base;
import zxfoundation.base.types;
import zxfoundation.dgp.cap.types;

Include dependency graph for core.cxxm:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
using	zxfoundation::dgp::cap::lookup_fn = auto ()(u16 obj_id) noexcept -> scoms::kobject::bobject
	Callback signature for looking up a kobject by object ID.

Functions
auto	zxfoundation::dgp::cap::cap_acquire (cap_token source, cap_rights rights, u32 owner_domain) noexcept -> std::expected< cap_token, lib::kernel_error >
	Acquire a private capability derived from an owned capability.
auto	zxfoundation::dgp::cap::cap_duplicate (cap_token source, cap_rights rights, u32 owner_domain) noexcept -> std::expected< cap_token, lib::kernel_error >
	Duplicate a capability for a new owner from kernel policy code.
auto	zxfoundation::dgp::cap::cap_duplicate_for (cap_token source, cap_rights rights, u32 source_domain, u32 owner_domain) noexcept -> std::expected< cap_token, lib::kernel_error >
	Duplicate a capability after checking its current owner.
auto	zxfoundation::dgp::cap::cap_issue (cap_type type, u16 obj_id, cap_rights rights, u32 owner_domain) noexcept -> std::expected< cap_token, lib::kernel_error >
	Issue a capability from nucleus-owned object authority.
auto	zxfoundation::dgp::cap::cap_release (cap_token token) noexcept -> std::expected< void, lib::kernel_error >
	Release a previously acquired capability.
auto	zxfoundation::dgp::cap::cap_resolve (cap_token token, cap_rights needed) noexcept -> std::expected< scoms::kobject::bobject *, lib::kernel_error >
	Resolve a validated capability to its SCOMS object.
auto	zxfoundation::dgp::cap::cap_revoke (cap_token token) noexcept -> std::expected< void, lib::kernel_error >
	Revoke a capability token administratively.
auto	zxfoundation::dgp::cap::cap_revoke_for_domain (u32 domain_id) noexcept -> std::expected< u32, lib::kernel_error >
	Revoke every capability owned by or targeting a domain.
auto	zxfoundation::dgp::cap::cap_revoke_target (scoms::kobject::bobject &target) noexcept -> std::expected< u32, lib::kernel_error >
	Revoke all slots referring to a SCOMS object.
template<typename T>
auto	zxfoundation::dgp::cap::cap_validate (cap_token token, cap_rights needed) noexcept -> std::expected< T *, lib::kernel_error >
	Validate a capability token and return the underlying object.
template<>
auto	zxfoundation::dgp::cap::cap_validate< zxfoundation::dgp::domain::domain > (cap_token token, cap_rights needed) noexcept -> std::expected< zxfoundation::dgp::domain::domain *, lib::kernel_error >
template<>
auto	zxfoundation::dgp::cap::cap_validate< zxfoundation::dgp::gate::gate_desc > (cap_token token, cap_rights needed) noexcept -> std::expected< zxfoundation::dgp::gate::gate_desc *, lib::kernel_error >
template<>
auto	zxfoundation::dgp::cap::cap_validate< zxfoundation::dgp::portal::portal_desc > (cap_token token, cap_rights needed) noexcept -> std::expected< zxfoundation::dgp::portal::portal_desc *, lib::kernel_error >
template<>
auto	zxfoundation::dgp::cap::cap_validate< zxfoundation::memory::objects::memory_object > (cap_token token, cap_rights needed) noexcept -> std::expected< zxfoundation::memory::objects::memory_object *, lib::kernel_error >
auto	zxfoundation::dgp::cap::cap_validate_generic (cap_token token, cap_rights needed) noexcept -> std::expected< void, lib::kernel_error >
	Validate a capability token without a concrete type parameter.
auto	zxfoundation::dgp::cap::cap_validate_generic_for (cap_token token, cap_rights needed, u32 owner_domain) noexcept -> std::expected< void, lib::kernel_error >
	Validate a capability against its owning domain.
auto	zxfoundation::dgp::cap::register_lookup (cap_type type, lookup_fn fn) noexcept -> std::expected< void, lib::kernel_error >
	Register a lookup callback for a resource type.

Detailed Description

Capability management — acquire, release, derive, and validate capability tokens for the DGP kernel's authorization model.

SPDX-License-Identifier: Apache-2.0

Typedef Documentation

◆ lookup_fn

using zxfoundation::dgp::cap::lookup_fn = auto (*)(u16 obj_id) noexcept -> scoms::kobject::bobject*

export

Callback signature for looking up a kobject by object ID.

Parameters

[in] obj_id Object ID (u16 from capability token).

Returns: Pointer to the kobject, or nullptr if not found.

Function Documentation

◆ cap_acquire()

auto zxfoundation::dgp::cap::cap_acquire	(	cap_token	source,
		cap_rights	rights,
		u32	owner_domain )->std::expected< cap_token, lib::kernel_error >

nodiscardexportnoexcept

Acquire a private capability derived from an owned capability.

Parameters

[in]	source	Capability owned by `owner_domain`.
[in]	rights	Rights to retain from `source`.
[in]	owner_domain	Domain receiving the new capability.

Returns: cap_token on success, kernel_error on failure.

◆ cap_duplicate()

auto zxfoundation::dgp::cap::cap_duplicate	(	cap_token	source,
		cap_rights	rights,
		u32	owner_domain )->std::expected< cap_token, lib::kernel_error >

nodiscardexportnoexcept

Duplicate a capability for a new owner from kernel policy code.

Parameters

[in]	source	Existing capability.
[in]	rights	Rights to retain.
[in]	owner_domain	Domain receiving the capability.

◆ cap_issue()

auto zxfoundation::dgp::cap::cap_issue	(	cap_type	type,
		u16	obj_id,
		cap_rights	rights,
		u32	owner_domain )->std::expected< cap_token, lib::kernel_error >

nodiscardexportnoexcept

Issue a capability from nucleus-owned object authority.

Parameters

[in]	type	Resource type.
[in]	obj_id	SCOMS object ID.
[in]	rights	Rights granted to the recipient.
[in]	owner_domain	Domain receiving the capability.

◆ cap_release()

auto zxfoundation::dgp::cap::cap_release ( cap_token token ) ->std::expected< void, lib::kernel_error >

nodiscardexportnoexcept

Release a previously acquired capability.

Parameters

[in] token The capability token to release.

Returns: Success, or kernel_error if the token is invalid.

Note: Decrements the underlying object's reference count.

◆ cap_resolve()

auto zxfoundation::dgp::cap::cap_resolve	(	cap_token	token,
		cap_rights	needed )->std::expected< scoms::kobject::bobject *, lib::kernel_error >

nodiscardexportnoexcept

Resolve a validated capability to its SCOMS object.

Parameters

[in]	token	Capability supplied by a caller.
[in]	needed	Rights required by the operation.

Returns: Referenced SCOMS object, or an authorization error.

◆ cap_revoke()

auto zxfoundation::dgp::cap::cap_revoke ( cap_token token ) ->std::expected< void, lib::kernel_error >

nodiscardexportnoexcept

Revoke a capability token administratively.

Parameters

[in] token Capability token marking the object to revoke.

Returns: Success, or kernel_error if the token is null or the object vanished before we could bump its generation.

◆ cap_revoke_for_domain()

auto zxfoundation::dgp::cap::cap_revoke_for_domain ( u32 domain_id ) ->std::expected< u32, lib::kernel_error >

nodiscardexportnoexcept

Revoke every capability owned by or targeting a domain.

Parameters

[in] domain_id Domain entering teardown.

Returns: Number of revoked capability slots, or an error.

◆ cap_revoke_target()

auto zxfoundation::dgp::cap::cap_revoke_target ( scoms::kobject::bobject & target ) ->std::expected< u32, lib::kernel_error >

nodiscardexportnoexcept

Revoke all slots referring to a SCOMS object.

Parameters

[in] target Object being destroyed.

Returns: Number of revoked slots, or an error.

◆ cap_validate()

template<typename T>

auto zxfoundation::dgp::cap::cap_validate	(	cap_token	token,
		cap_rights	needed )->std::expected< T *, lib::kernel_error >

nodiscardexportnoexcept

Validate a capability token and return the underlying object.

Template Parameters

T	Expected kobject type (domain, gate_desc, etc.).

Parameters

[in]	token	The capability token to validate.
[in]	needed	Rights required for the intended operation.

Returns: Pointer to the validated object, or kernel_error.

◆ cap_validate_generic()

auto zxfoundation::dgp::cap::cap_validate_generic	(	cap_token	token,
		cap_rights	needed )->std::expected< void, lib::kernel_error >

nodiscardexportnoexcept

Validate a capability token without a concrete type parameter.

Note: Unlike cap_validate<T>, this does not return the object pointer — it only returns success/failure.

◆ cap_validate_generic_for()

auto zxfoundation::dgp::cap::cap_validate_generic_for	(	cap_token	token,
		cap_rights	needed,
		u32	owner_domain )->std::expected< void, lib::kernel_error >

nodiscardexportnoexcept

Validate a capability against its owning domain.

Parameters

[in]	token	Capability supplied by the caller.
[in]	needed	Rights required by the operation.
[in]	owner_domain	Domain making the call.

◆ register_lookup()

auto zxfoundation::dgp::cap::register_lookup	(	cap_type	type,
		lookup_fn	fn )->std::expected< void, lib::kernel_error >

nodiscardexportnoexcept

Register a lookup callback for a resource type.

Parameters

[in]	type	The resource type to associate with the callback.
[in]	fn	The callback.

Returns: Success, or kernel_error if the type is out of range.

ZXFoundation™ 26h2

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ lookup_fn

Function Documentation

◆ cap_acquire()

◆ cap_duplicate()

◆ cap_issue()

◆ cap_release()

◆ cap_resolve()

◆ cap_revoke()

◆ cap_revoke_for_domain()

◆ cap_revoke_target()

◆ cap_validate()

◆ cap_validate_generic()

◆ cap_validate_generic_for()

◆ register_lookup()