pki

package module
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 31, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

README

varwof-types

Shared type definitions for AIC / Capability / PrincipalUid / DelegationAuthorization in the varwof PKI suite.

⚠️ Preview — Not for production use. APIs and features may change before official release.

License Go Reference

中文

What is varwof-types?

Core shared type definitions for the varwof PKI suite: AIC (Agent Identity Certificate), Capability, PrincipalUid (SPKI key hash), DelegationAuthorization, PrincipalAuthorization, and more. Zero external dependencies. Referenced by core, gateway-core, register, and all other modules.

Quick Start

import pki "github.com/varwof/types"

// Parse AIC from certificate
aic, err := pki.ParseAIC(cert)

// Validate AIC
err = pki.ValidateAIC(aic)

// Match capability with glob pattern
matched := pki.MatchCapability("oracle/mysql:query:users", "oracle/*:query:*")

Installation

go get github.com/varwof/types@v0.1.0

Core Types

Type Description
AIC Agent Identity Certificate extension structure
Capability Capability declaration (schemeId + capabilityId)
PrincipalUid Principal identifier (SPKI public key hash)
DelegationAuthorization Delegation authorization signature (timestamp + nonce)
PrincipalAuthorization Principal authorization policy
GatewaySessionExtension Gateway session execution constraints
MatchCapability Capability glob pattern matching
ValidateAIC AIC validation

Sub-packages

Package Description
aicjwt AIC-JWT (draft-wei-aic-jwt-00) claims model, JWS sign/verify, 11-step validation pipeline

Ecosystem

graph TB
    subgraph varwof["varwof Ecosystem"]
        core["core<br/>PKI CA"]
        gw["gateway<br/>TCP/HTTP/UDP"]
        gwcore["gateway-core<br/>Security Engine"]
        types["types<br/>Shared Types"]
        reg["register<br/>Capability Registry"]
    end
    core --> types
    gwcore --> types
    reg --> types

types is the type foundation layer of the varwof ecosystem. This project is a member of the Open Invention Network.
Homepage https://varwof.com
Community https://varwof.org
IETF Draft draft-wei-aic-identity-cert
AIC X.509 (docs) draft-wei-aic-identity-cert-00.md (also .xml / .txt / .html)
AIC-JWT (docs) draft-wei-aic-jwt-00.md (also .xml / .txt / .html)
License Apache-2.0
Member Open Invention Network

Community

Questions, feedback, and port status: AIC Discussions

Documentation

Overview

Package pki provides shared type definitions for the varwof project.

Index

Constants

View Source 
const (
	// MaxCapabilities is the maximum number of AIC.capabilities.
	MaxCapabilities = 256
	// MaxAuthorizationConstraints is the upper limit for the AIC/PA
	// authorizationConstraints count (32).
	// The spec protocol structure limit is 32 (MaxExtensionsSlots);
	// the implementation uses the stricter default recommended value of 8 to ensure certificate size and parsing safety.
	MaxAuthorizationConstraints = 32
	// MaxExtensionsSlots is the maximum capacity of AIC.extensions slots.
	MaxExtensionsSlots = 32
	// MaxGrantEntries is the maximum number of PrincipalAuthorization.grants.
	MaxGrantEntries = 256
	// MaxConstraintParams is the byte limit for a single authorizationConstraints parameters entry.
	MaxConstraintParams = 512
	// MaxCapParams is the byte limit for a single Capability parameters entry.
	MaxCapParams = 4096
	// MaxNonceLen is the fixed length of DelegationAuthorization.nonce (32 bytes).
	MaxNonceLen = 32
	// MaxRequestedLifetime is the upper limit for requestedLifetime (seconds, 86400 = 24h).
	MaxRequestedLifetime = 86400
	// MinRequestedLifetime is the recommended lower limit for requestedLifetime (seconds, 3600 = 1h).
	MinRequestedLifetime = 3600
	// MaxRecommendedCertDERSize is the recommended upper limit for AIC certificate DER size (12KB).
	// Exceeding this value is recommended to split the envelope; 16KB is the hard reject limit in production code (see varwof-core sign.go).
	MaxRecommendedCertDERSize = 12 * 1024
	// MaxHardCertDERSize is the hard reject limit for AIC certificate DER size (16KB).
	MaxHardCertDERSize = 16 * 1024
	// MaxConcurrentMin is the minimum value for the max-concurrent constraint max parameter (spec P1-A-29).
	MaxConcurrentMin = 1
	// MaxConcurrentMax is the maximum value for the max-concurrent constraint max parameter (spec P1-A-29).
	MaxConcurrentMax = 1024
	// ConstraintConcurrentKey is the capabilityId for the max-concurrent constraint.
	ConstraintConcurrentKey = "max-concurrent"
)

Certificate size and structure limit constants (aligned with v1.7.1 spec and patent specification).

View Source 
const (
	// SPIFFEScheme is the URI scheme for SPIFFE identities.
	SPIFFEScheme = "spiffe"
	// SPIFFEAgentPrefix is the standard path prefix for agent workloads.
	SPIFFEAgentPrefix = "/agent/"
)
View Source 
const (
	// MatchPriorityNoMatch no match.
	MatchPriorityNoMatch = 0
	// MatchPriorityGlobal global wildcard: pattern is "*", "**", or "*:*".
	MatchPriorityGlobal = 1
	// MatchPriorityScheme scheme wildcard: first segment is "*", remaining segments match exactly (e.g. *:query:SELECT).
	MatchPriorityScheme = 2
	// MatchPriorityMulti multi-segment wildcard: contains "**" segment, matches one or more cross-segment parts (e.g. database:**).
	MatchPriorityMulti = 3
	// MatchPrioritySingle single-segment wildcard: all segments are literals or "*", * matches any single segment content (excluding ':').
	MatchPrioritySingle = 4
	// MatchPriorityExact exact match: id == pattern.
	MatchPriorityExact = 5
)

MatchPriority defines the priority levels for capabilityId matching (spec P1-B-19 / P2-B-06). Higher values are more specific; the highest priority matching rule wins in decisions, deny overrides allow.

Variables

View Source 
var (
	// ── AIC OIDs ──
	OIDAIC              = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 1, 1}
	OIDAICAgentIdentity = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 1, 1, 1}
	// DelegationAuthorization is AIC tree .1.1.2 (principal signature evidence, former name UserAuth before v1.5).
	OIDAICDelegationAuthorization = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 1, 1, 2}
	// DelegationDepthControl (.1.1.4, spec v1.7.2 §3.7, FUTURE delegation depth control):
	// chainDepth = .1.1.4.1, maxDepth = .1.1.4.2. Parsed with P1-11 delegation chain implementation.
	OIDDelegationDepthControl = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 1, 1, 4}
	OIDDDCChainDepth          = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 1, 1, 4, 1}
	OIDDDCMaxDepth            = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 1, 1, 4, 2}

	// ── Signature algorithm OIDs ──
	OIDSigECDSAWithSHA256  = asn1.ObjectIdentifier{1, 2, 840, 10045, 4, 3, 2}
	OIDSigECDSAWithSHA384  = asn1.ObjectIdentifier{1, 2, 840, 10045, 4, 3, 3}
	OIDSigECDSAWithSHA512  = asn1.ObjectIdentifier{1, 2, 840, 10045, 4, 3, 4}
	OIDSigRSAWithSHA256    = asn1.ObjectIdentifier{1, 2, 840, 113549, 1, 1, 11}
	OIDSigRSAWithSHA384    = asn1.ObjectIdentifier{1, 2, 840, 113549, 1, 1, 12}
	OIDSigRSAWithSHA512    = asn1.ObjectIdentifier{1, 2, 840, 113549, 1, 1, 13}
	OIDSigRSAPSSWithSHA256 = asn1.ObjectIdentifier{1, 2, 840, 113549, 1, 1, 10}
	OIDSigEd25519          = asn1.ObjectIdentifier{1, 3, 101, 112}

	// ── PrincipalAuthorization ──
	OIDPrincipalAuthorization = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 1, 2}

	// ── RenewalToken ──
	OIDRenewalToken = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 1, 6}

	// ── 3.x Certification Extensions ──
	OIDIdentityExt      = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 1}
	OIDCertificationExt = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 3}
	OIDMarketAccessId   = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 3, 1}
	OIDTrustLevel       = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 3, 2}
	OIDCrossBorder      = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 3, 3}

	// ── 5.x GM Algorithms ──
	OIDGM        = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 5}
	OIDSM2Sig    = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 5, 1}
	OIDSM3Hash   = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 5, 2}
	OIDSM4Enc    = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 5, 3}
	OIDSM2SM3Sig = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 5, 4}

	// ── 6.x Certificate Transparency ──
	OIDCT    = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 6}
	OIDCTSCT = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 6, 1}
	OIDCTLog = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 6, 2}

	// ── Hash algorithm OIDs ──
	OIDSHA256 = asn1.ObjectIdentifier{2, 16, 840, 1, 101, 3, 4, 2, 1}
	OIDSHA384 = asn1.ObjectIdentifier{2, 16, 840, 1, 101, 3, 4, 2, 2}
	OIDSHA512 = asn1.ObjectIdentifier{2, 16, 840, 1, 101, 3, 4, 2, 3}
)
View Source 
var HashAlgoOIDs = map[string]asn1.ObjectIdentifier{
	"sha256":   OIDSHA256,
	"sha384":   OIDSHA384,
	"sha512":   OIDSHA512,
	"sha3-256": {2, 16, 840, 1, 101, 3, 4, 2, 8},
	"sha3-384": {2, 16, 840, 1, 101, 3, 4, 2, 9},
	"sha3-512": {2, 16, 840, 1, 101, 3, 4, 2, 10},
}

HashAlgoOIDs maps hash algorithm name strings to OIDs.

View Source 
var HashOutputLen = map[string]int{
	"sha256":   32,
	"sha384":   48,
	"sha512":   64,
	"sha3-256": 32,
	"sha3-384": 48,
	"sha3-512": 64,
}

HashOutputLen returns the output byte length for each hash algorithm OID (spec P1-A-12). Supports SHA-2/SHA-3 (stdlib implementation); BLAKE2/BLAKE3 only register known OID-to-length mappings per zero external dependency policy (consistent with keyHash OCTET STRING SIZE(1..64) semantics); actual computation requires the corresponding dependencies on the gateway/core side.

View Source 
var Version = "0.2.0"

Version is the package version, set via -ldflags -X github.com/varwof/types.Version=x.y.z.

Functions

func AddSPIFFESANToCert 

func AddSPIFFESANToCert(cert *x509.Certificate, spiffeID string) error

AddSPIFFESANToCert adds a SPIFFE URI to a certificate's SAN URIs. Does not add if the SPIFFE ID already exists.

func BuildSPIFFEID 

func BuildSPIFFEID(trustDomain, agentName string) string

BuildSPIFFEID constructs a SPIFFE ID from trust domain and agent name. Returns "spiffe://{trustDomain}/agent/{agentName}".

func DefaultHashAlgo 

func DefaultHashAlgo() asn1.ObjectIdentifier

DefaultHashAlgo returns the default SHA-256 OID.

func ExtractSPIFFEIDFromCert 

func ExtractSPIFFEIDFromCert(cert *x509.Certificate) string

ExtractSPIFFEIDFromCert extracts the SPIFFE ID from a certificate's SAN URIs. Returns empty string if no SPIFFE URI is found.

func HashOIDName 

func HashOIDName(oid asn1.ObjectIdentifier) string

HashOIDName returns the canonical name of a hash algorithm OID; returns empty string if unknown.

func IsSPIFFEAgentID 

func IsSPIFFEAgentID(agentId string) bool

IsSPIFFEAgentID returns true if the agentId is in SPIFFE format.

func KeyHashFromCertSPKI 

func KeyHashFromCertSPKI(algo asn1.ObjectIdentifier, cert *x509.Certificate) ([]byte, error)

KeyHashFromCertSPKI computes keyHash from a certificate's public key using the algorithm OID.

func KeyHashFromSPKI 

func KeyHashFromSPKI(algo asn1.ObjectIdentifier, spkiDER []byte) ([]byte, error)

KeyHashFromSPKI computes the SPKI DER digest (keyHash) of a public key using the specified hash algorithm OID. Supports stdlib-implemented SHA-2/SHA-3 family; other algorithms return explicit errors (to prevent silent degradation).

func MatchCapability 

func MatchCapability(id, pattern string) bool

MatchCapability checks if id matches pattern, supporting `*`/`?`/`**` glob syntax.

func MatchCapabilityPriority 

func MatchCapabilityPriority(id, pattern string) int

MatchCapabilityPriority determines whether id matches pattern and returns the matched priority level.

Semantics (per spec):

  • capabilityId is segmented by ':'
  • '*' matches any single segment content (excluding ':')
  • '**' matches one or more cross-segment parts
  • Priority: exact(5) > single-segment-wildcard(4) > multi-segment-wildcard(3) > scheme-wildcard(2) > global-wildcard(1)

Returns MatchPriorityNoMatch(0) if no match.

func MatchCapabilityPriorityString 

func MatchCapabilityPriorityString(p int) string

MatchCapabilityPriorityString returns a human-readable name for the priority level (debugging/audit).

func ParseHashAlgo 

func ParseHashAlgo(s string) (asn1.ObjectIdentifier, error)

ParseHashAlgo parses a hash algorithm string to an OID. Returns nil if empty.

func ParseSPIFFEAgentName 

func ParseSPIFFEAgentName(agentId string) string

ParseSPIFFEAgentName extracts the agent name from a SPIFFE agentId. "spiffe://varwof.com/agent/scheduler-a" → "scheduler-a" Returns the original id if it's not in SPIFFE format.

func ParseSPIFFEDomain 

func ParseSPIFFEDomain(agentId string) string

ParseSPIFFEDomain extracts the trust domain from a SPIFFE agentId. "spiffe://varwof.com/agent/scheduler-a" → "varwof.com" Returns empty string if not in SPIFFE format.

func RegisterPlugin added in v0.2.0 

func RegisterPlugin(p CapabilityPlugin) error

RegisterPlugin registers a plugin in the global registry.

func ResetPlugins added in v0.2.0 

func ResetPlugins()

ResetPlugins clears the global registry (testing only).

func SupportedHashAlgos 

func SupportedHashAlgos() []string

SupportedHashAlgos returns the names of computationally implemented algorithms (SHA-2/SHA-3 family).

func ValidateAIC 

func ValidateAIC(aic *AIC) error

ValidateAIC validates AIC field constraints per v1.7.1 spec (03-validation.md).

func ValidateMaxConcurrentParam 

func ValidateMaxConcurrentParam(raw []byte) error

ValidateMaxConcurrentParam validates max-concurrent constraint parameters ({"max": N}, N in 1..1024, spec P1-A-29). Missing/empty parameters return nil (not configured).

func ValidatePrincipalAuthorization 

func ValidatePrincipalAuthorization(pa *PrincipalAuthorization) error

ValidatePrincipalAuthorization validates PrincipalAuthorization field constraints (v1.7.1). Validates: grants count <= 256, per-Capability length constraints, authorizationConstraints count <= 8 with schemeId in the constraint whitelist, DelegationPolicy value boundaries.

func ValidatePrincipalUidKeyHash 

func ValidatePrincipalUidKeyHash(pu PrincipalUid) error

ValidatePrincipalUidKeyHash validates the keyHash length against the declared hashAlgo. Per v1.7.1 the spec supports hash algorithms with output length <= 64 bytes (keyHash OCTET STRING SIZE(1..64)). SHA-2/SHA-3 family implemented by stdlib + SM3 built-in pure Go implementation (C1) with length validation; BLAKE2/BLAKE3 and other algorithms requiring external dependencies return explicit errors (never silently fallback to SHA-256).

func ValidateSPIFFEID 

func ValidateSPIFFEID(id, trustDomain string) error

ValidateSPIFFEID checks that id matches the expected format: "spiffe://{trustDomain}/agent/{name}" where name is non-empty.

Types

type AIC 

type AIC struct {
	Version                  int                     `asn1:"default:1"`
	AgentId                  string                  `asn1:"utf8"`
	PrincipalUid             PrincipalUid            `asn1:""`
	Capabilities             []Capability            `asn1:"sequence"`
	DelegationMode           DelegationMode          `asn1:"default:0"`
	AuthorizationConstraints []Capability            `asn1:"optional,omitempty,contextspecific,explicit,tag:0"`
	DelegationAuthorization  DelegationAuthorization `asn1:"optional,omitempty"`
	Extensions               []ExtField              `asn1:"optional,omitempty,contextspecific,explicit,tag:1"`
}

AIC is the X.509v3 extension ASN.1 structure (v1.7.1 spec §AIC). delegationAuthorization is REQUIRED per spec; emptiness is enforced at parse/validate/sign time. Go encoding/asn1 cannot marshal a mandatory empty DelegationAuthorization (nil signature OID), so the tag keeps `optional,omitempty` on the wire while the semantics remain required.

func ParseAIC 

func ParseAIC(cert *x509.Certificate) (*AIC, error)

ParseAIC parses the AIC extension from a certificate. Per v1.7.1 spec delegationAuthorization is REQUIRED; a present AIC extension without a non-empty DelegationAuthorization is rejected.

func (*AIC) CheckPermission 

func (a *AIC) CheckPermission(required string) bool

CheckPermission checks if agent has the specified capability (full ID, glob match). The capability is matched by its FullID (scheme:capabilityId) so a requested permission like "varwof/demo-mysql-v1:SELECT:*" matches an AIC declaration of {SchemeId:"varwof/demo-mysql-v1", CapabilityId:"SELECT:*"}.

func (*AIC) HasProtocol 

func (a *AIC) HasProtocol(schemeId string) bool

HasProtocol checks if agent has the specified schemeId capability.

func (*AIC) IntersectPermissions 

func (a *AIC) IntersectPermissions(pa *PrincipalAuthorization) []string

IntersectPermissions returns the CapabilityId intersection between AIC capabilities and PrincipalAuthorization grants.

func (*AIC) IntersectPermissionsStr 

func (a *AIC) IntersectPermissionsStr(upPerms []string) []string

IntersectPermissionsStr returns AIC capabilities (full IDs) that match any pattern in upPerms (glob). Matching is on FullID so a PA grant of {SchemeId:"varwof/demo-mysql-v1", CapabilityId:"SELECT:*"} covers an AIC declaration of {SchemeId:"varwof/demo-mysql-v1", CapabilityId:"SELECT:/api/tables"}.

func (*AIC) IntersectPermissionsStrAny 

func (a *AIC) IntersectPermissionsStrAny(upPerms string) []string

IntersectPermissionsStrAny parses a comma/space-delimited string and returns intersection.

func (*AIC) Principal 

func (a *AIC) Principal() string

Principal returns the human principal represented by the agent.

type AlgorithmIdentifier 

type AlgorithmIdentifier struct {
	Algorithm  asn1.ObjectIdentifier
	Parameters asn1.RawValue `asn1:"optional"`
}

AlgorithmIdentifier is ASN.1 algorithm identifier.

func SigAlgoToOID 

func SigAlgoToOID(algo x509.SignatureAlgorithm) AlgorithmIdentifier

SigAlgoToOID maps x509.SignatureAlgorithm to AlgorithmIdentifier.

type Capability 

type Capability struct {
	SchemeId     string `json:"scheme_id" asn1:"utf8"`
	CapabilityId string `json:"capability_id" asn1:"utf8"`
	Parameters   []byte `json:"parameters,omitempty" asn1:"optional,omitempty,contextspecific,explicit,tag:0"`
}

Capability is a protocolized capability container.

Encoding convention (v1.8, unified PA grant / AIC capability convention):

  • SchemeId : capability scheme identifier (e.g. "ca", "cert", "varwof/demo-mysql-v1", "varwof-gateway-v1")
  • CapabilityId : pure action identifier, **without scheme prefix** (e.g. "list", "issue", "SELECT:*")
  • Full permission identifier = SchemeId + ":" + CapabilityId (e.g. "ca:list", "varwof/demo-mysql-v1:SELECT:*"), uniformly generated by FullID(); all matching/intersection/authorization decisions must use the full identifier; consumers must not concatenate themselves or match authorization policies using bare CapabilityId.

func (Capability) FullID 

func (c Capability) FullID() string

FullID returns the full capability identifier (scheme:capabilityId). When SchemeId is empty, it degrades to CapabilityId (for capabilities without a scheme). This is the single authoritative concatenation point across the entire system; gateway/core/type layers must uniformly reuse this method. Modules must not duplicate the concatenation logic.

type CapabilityPlugin added in v0.2.0 

type CapabilityPlugin interface {
	Scheme() string
	Execute(cap *Capability, ctx *PluginContext) (*PluginResult, error)
}

CapabilityPlugin is the interface for all capability plugins.

func FindPlugin added in v0.2.0 

func FindPlugin(schemeID string) (CapabilityPlugin, error)

FindPlugin looks up a registered plugin by schemeID.

type CapabilityRule 

type CapabilityRule struct {
	// Pattern matching pattern (supports five-level wildcard syntax).
	Pattern string
	// Deny when true indicates a deny rule; false indicates an allow rule.
	Deny bool
}

CapabilityRule is a matching rule with an action, used for "deny overrides allow" decisions.

type CapabilityRuleMatch 

type CapabilityRuleMatch struct {
	// Matched indicates whether a matching rule exists.
	Matched bool
	// Deny indicates whether the rule is a deny rule (deny overrides allow).
	Deny bool
	// Priority is the highest priority level matched (MatchPriority*).
	Priority int
	// Pattern is the matched rule pattern.
	Pattern string
}

CapabilityRuleMatch is the result of a rule match.

func MatchCapabilityRules 

func MatchCapabilityRules(id string, rules []CapabilityRule) CapabilityRuleMatch

MatchCapabilityRules makes priority-based decisions within a rule set: picks the highest priority matching rule; at the same priority, deny overrides allow. When no rule matches, returns Matched=false (caller handles per default policy, typically deny).

type DelegationAuthTBS 

type DelegationAuthTBS struct {
	Version                  int            `asn1:"default:1"`
	AgentId                  string         `asn1:"utf8"`
	PrincipalUid             PrincipalUid   `asn1:""`
	Reason                   Reason         `asn1:""`
	Capabilities             []Capability   `asn1:"sequence"`
	DelegationMode           DelegationMode `asn1:"default:0"`
	AuthorizationConstraints []Capability   `asn1:"optional,omitempty,contextspecific,explicit,tag:0"`
	RequestedLifetime        int            `asn1:"default:0"`
	Timestamp                time.Time      `asn1:"generalized"`
	Nonce                    []byte         `asn1:"octet"`
}

DelegationAuthTBS is the to-be-signed data for DelegationAuthorization signature (v1.7.1). Field order: version → agentId → principalUid → reason → capabilities → delegationMode → authorizationConstraints → requestedLifetime → timestamp → nonce.

type DelegationAuthorization 

type DelegationAuthorization struct {
	Reason             Reason              `asn1:""`
	RequestedLifetime  int                 `asn1:"default:0"`
	Timestamp          time.Time           `asn1:"generalized"`
	Nonce              []byte              `asn1:"octet"`
	SignatureAlgorithm AlgorithmIdentifier `asn1:""`
	SignatureValue     []byte              `asn1:"octet"`
}

DelegationAuthorization is user authorization cryptographic evidence (v1.7.1 spec §3). Field order: reason → requestedLifetime → timestamp → nonce → signatureAlgorithm → signatureValue.

func (DelegationAuthorization) IsPresent 

func (d DelegationAuthorization) IsPresent() bool

IsPresent checks if DelegationAuthorization is actually set (non-zero).

type DelegationMode 

type DelegationMode int

DelegationMode defines agent delegation mode. 

const (
	DelegationAuthorized     DelegationMode = 0
	DelegationRepresentative DelegationMode = 1
)

type DelegationPolicy 

type DelegationPolicy struct {
	Version         int `asn1:"default:1"`
	MaxAgents       int `asn1:"default:1"`
	AllowedMode     int `asn1:"enum,default:0"`                    // 0=authorizedOnly, 1=representativeAllowed
	MaxSessionHours int `asn1:"optional,omitempty,explicit,tag:0"` // 0=absent
}

DelegationPolicy controls delegation behavior (v1.7.1, dev-docs/aic/01-asn1.md): 

SEQUENCE {
    version             INTEGER DEFAULT 1,
    maxAgents           INTEGER DEFAULT 1,
    allowedMode         DelegationModeEnum DEFAULT authorizedOnly,
    maxSessionHours     [0] EXPLICIT INTEGER OPTIONAL
}

type ExtField 

type ExtField struct {
	ExtnID    asn1.ObjectIdentifier `asn1:"objectidentifier"`
	Critical  bool                  `asn1:"default:false"`
	ExtnValue []byte                `asn1:"octet"`
}

ExtField is a single extension field inside AIC extensions slot.

type ExternalPolicyRef 

type ExternalPolicyRef struct {
	RefType   string `asn1:"utf8"`
	RefUrl    string `asn1:"utf8"`
	RefDigest []byte `asn1:"optional,omitempty"`
}

ExternalPolicyRef references an external policy system.

type HTTPFacts added in v0.2.0 

type HTTPFacts struct {
	Method  string
	Path    string
	Query   map[string][]string
	Headers map[string]string
}

HTTPFacts carries per-request HTTP facts for capability plugins.

type PermissionDef 

type PermissionDef struct {
	PermId      string `asn1:"utf8"`
	Level       int    `asn1:"enum,default:0"`
	Constraints []byte `asn1:"optional,omitempty"`
}

PermissionDef for backward compatibility.

type PermissionLevel 

type PermissionLevel int

PermissionLevel for backward compatibility. 

const (
	PermissionAuto             PermissionLevel = 0
	PermissionRequiresApproval PermissionLevel = 1
)

type PluginContext added in v0.2.0 

type PluginContext struct {
	Context  context.Context
	AIC      *AIC
	UserPerm *UserPermission
	Target   string
	ClientCN string
	Roles    []string
	AgentId  string

	// Optional HTTP request facts, populated by HTTP-facing gateways
	// so that capability plugins can evaluate request conditions
	// (method/path/query/headers). Zero values mean "not provided".
	Method  string
	Path    string
	Query   map[string][]string
	Headers map[string]string
}

PluginContext is the context during plugin execution.

type PluginDecision added in v0.2.0 

type PluginDecision int

PluginDecision represents the decision result after plugin execution. 

const (
	PluginAllow PluginDecision = iota
	PluginDeny
	PluginBypass
)

PluginAllow/Deny/Bypass are plugin decision constants.

type PluginRegistry added in v0.2.0 

type PluginRegistry struct {
	// contains filtered or unexported fields
}

PluginRegistry manages plugin registration and lookup.

func NewPluginRegistry added in v0.2.0 

func NewPluginRegistry() *PluginRegistry

NewPluginRegistry creates a new empty registry.

func (*PluginRegistry) Execute added in v0.2.0 

func (r *PluginRegistry) Execute(schemeID string, cap *Capability, ctx *PluginContext) (*PluginResult, error)

Execute is a convenience wrapper for Find + Execute.

func (*PluginRegistry) Find added in v0.2.0 

func (r *PluginRegistry) Find(schemeID string) (CapabilityPlugin, error)

Find looks up a registered plugin by schemeID.

func (*PluginRegistry) Keys added in v0.2.0 

func (r *PluginRegistry) Keys() []string

Keys returns the scheme list of all registered plugins.

func (*PluginRegistry) Len added in v0.2.0 

func (r *PluginRegistry) Len() int

Len returns the number of registered plugins.

func (*PluginRegistry) Register added in v0.2.0 

func (r *PluginRegistry) Register(p CapabilityPlugin) error

Register registers a plugin to this instance.

func (*PluginRegistry) Reset added in v0.2.0 

func (r *PluginRegistry) Reset()

Reset clears the registry.

type PluginResult added in v0.2.0 

type PluginResult struct {
	Decision PluginDecision
	Reason   string
	Metadata map[string]string
}

PluginResult is the return result after plugin execution.

func ExecutePlugin added in v0.2.0 

func ExecutePlugin(schemeID string, cap *Capability, ctx *PluginContext) (*PluginResult, error)

ExecutePlugin is a convenience wrapper for findPlugin + Execute.

type PrincipalAuthorization 

type PrincipalAuthorization struct {
	Version                  int              `asn1:"default:1"`
	Grants                   []Capability     `asn1:"optional,omitempty"`
	AuthorizationConstraints []Capability     `asn1:"optional,omitempty,contextspecific,explicit,tag:0"`
	DelegationPolicy         DelegationPolicy `asn1:"optional,explicit,tag:1"`
	Extensions               []ExtField       `asn1:"optional,omitempty,contextspecific,explicit,tag:2"`
}

PrincipalAuthorization is the v1.7.1 user authorization structure. ASN.1 (dev-docs/aic/01-asn1.md §PrincipalAuthorization): 

SEQUENCE {
    version                     INTEGER DEFAULT 1,
    grants                      SEQUENCE OF Capability,
    authorizationConstraints    [0] EXPLICIT SEQUENCE SIZE(0..8) OF Capability OPTIONAL,
    delegationPolicy            [1] EXPLICIT DelegationPolicy OPTIONAL,
    extensions                  [2] EXPLICIT Extensions OPTIONAL
}

The pre-v1.5 `roles` field was removed by the v1.5 spec.

func ParseUserPermissionExtension 

func ParseUserPermissionExtension(cert *x509.Certificate) (*PrincipalAuthorization, error)

ParseUserPermissionExtension parses the PrincipalAuthorization extension from a certificate.

func (*PrincipalAuthorization) AllowsRepresentative 

func (pa *PrincipalAuthorization) AllowsRepresentative() bool

AllowsRepresentative checks if representative delegation mode is allowed.

func (*PrincipalAuthorization) GrantIds 

func (pa *PrincipalAuthorization) GrantIds() []string

GrantIds returns all grants as full capability IDs (scheme:capabilityId), via Capability.FullID(). Matching/authorization decisions uniformly use the full identifier, aligned with the "ca:list" format in authorization policy grants.

func (*PrincipalAuthorization) HasRole 

func (pa *PrincipalAuthorization) HasRole(role string) bool

HasRole reports whether the authorization has the specified role.

The v1.5 spec removed the roles field; role membership is now carried in the certificate OU. HasRole is kept for backward compatibility and always returns false.

type PrincipalUid 

type PrincipalUid struct {
	Version    int                 `asn1:"default:1"`
	Realm      string              `asn1:"utf8"`
	Identifier string              `asn1:"utf8"`
	KeyHash    []byte              `asn1:"octet"`
	HashAlgo   AlgorithmIdentifier `asn1:"optional,omitempty,explicit,tag:0"`
}

PrincipalUid is the structured ASN.1 principal identity (spec §PrincipalUid). hashAlgo is [0] EXPLICIT AlgorithmIdentifier OPTIONAL; omitted defaults to SHA-256.

func MakePrincipalUidFromCert 

func MakePrincipalUidFromCert(realm, identifier string, cert *x509.Certificate) PrincipalUid

MakePrincipalUidFromCert constructs a PrincipalUid from a certificate (KeyHash = SPKI SHA-256). Returns a PrincipalUid with empty KeyHash when certificate or key encoding fails (preserves old signature compatibility).

func MakePrincipalUidFromCertWithAlgo 

func MakePrincipalUidFromCertWithAlgo(realm, identifier string, cert *x509.Certificate, algo asn1.ObjectIdentifier) (PrincipalUid, error)

MakePrincipalUidFromCertWithAlgo constructs a PrincipalUid from a certificate, computing SPKI keyHash using the specified hash algorithm OID. When algo is nil/empty, defaults to SHA-256; unsupported algorithms (BLAKE2/BLAKE3) return an error (no silent degradation). SM3 is provided by pki-types built-in pure Go implementation (C1).

func ParsePrincipalUid 

func ParsePrincipalUid(s string) (PrincipalUid, error)

ParsePrincipalUid parses a PrincipalUid from communication format string.

func (PrincipalUid) HashAlgoOID 

func (pu PrincipalUid) HashAlgoOID() asn1.ObjectIdentifier

HashAlgoOID returns the effective hash algorithm OID (nil/empty defaults to SHA-256).

func (PrincipalUid) String 

func (pu PrincipalUid) String() string

String returns the communication format {realm}:{identifier}:{keyFingerprint}.

type Reason 

type Reason struct {
	ReasonCode  string `asn1:"utf8"`
	Description string `asn1:"utf8"`
}

Reason is the delegation authorization reason (v1.7.1, dev-docs/aic/01-asn1.md §Reason). Both fields are REQUIRED (MUST be non-empty); reason is a statement for audit/display only and does not participate in permission decisions.

type ResourceScope 

type ResourceScope struct {
	OrgUnit   string `asn1:"utf8,optional,omitempty"`
	Namespace string `asn1:"utf8,optional,omitempty"`
	Tag       string `asn1:"utf8,optional,omitempty"`
}

ResourceScope for backward compatibility.

type RoleDef 

type RoleDef struct {
	RoleId      string          `asn1:"utf8"`
	Permissions []PermissionDef `asn1:"sequence"`
}

RoleDef for backward compatibility.

type UserPermission 

type UserPermission struct {
	Version         int                     `asn1:"default:1"`
	Roles           []RoleDef               `asn1:"sequence"`
	Scope           ResourceScope           `asn1:"optional,explicit,tag:0"`
	CriticalOps     []asn1.ObjectIdentifier `asn1:"optional,tag:1"`
	AgentDelegation DelegationPolicy        `asn1:"optional,explicit,tag:2"`
	ExternalRef     ExternalPolicyRef       `asn1:"optional,explicit,tag:3"`
	AgentSerialList []*big.Int              `asn1:"optional,omitempty,tag:4"`
}

UserPermission is the v1.4 legacy type for backward compatibility.

func (*UserPermission) AllowsImpersonation 

func (u *UserPermission) AllowsImpersonation() bool

AllowsImpersonation for backward compatibility.

func (*UserPermission) PermIds 

func (u *UserPermission) PermIds() []string

PermIds for backward compatibility.

Source Files

View all Source files

Directories

Path Synopsis
Package aicjson is a reference implementation and conformance test target for draft-wei-aic-jwt-00 (AIC-JWT: JSON Web Token Profile for AI Agent Identity Certificates).
 Package aicjson is a reference implementation and conformance test target for draft-wei-aic-jwt-00 (AIC-JWT: JSON Web Token Profile for AI Agent Identity Certificates).
cmd
aic command
Command aic is a small CLI for the Varwof AIC protocol core.
 Command aic is a small CLI for the Varwof AIC protocol core.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.