pki

package module
v0.1.0 Latest Latest
Warning

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

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

README

Varwof Types

Shared type definition library providing AIC, Capability, Principal and other core types for the Varwof PKI suite.

Features

  • Zero external dependencies, pure standard library
  • AIC (Agent Identity Certificate) extension structure and validation
  • Capability definitions with glob pattern matching
  • PrincipalUid principal identifier with SPKI key hash
  • DelegationAuthorization delegation authorization
  • PrincipalAuthorization with delegation policy
  • GatewaySessionExtension for execution constraints
  • Hash algorithm support (SHA-2/SHA-3 family)
  • aicjwt subpackage: AIC-JWT (draft-wei-aic-jwt-00) claims model, JWS sign/verify, capability matching (draft Section 6.2), constraint evaluation and the 11-step validation pipeline

Installation

go get github.com/varwof/types

Usage

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:*")

// Validate an AIC-JWT (github.com/varwof/types/aicjwt)
import aicjwt "github.com/varwof/types/aicjwt"
dec, err := aicjwt.Validate(token, aicjwt.VerifyOptions{ /* ... */ })

License

Apache-2.0

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}

	// ── Gateway Session ──
	OIDGatewaySession = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 1, 5}

	// ── Capability Scheme Registry (reserved) ──
	OIDCapabilitySchemeRegistry = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 1, 3}

	// ── Vendor Extension Registry (reserved) ──
	OIDVendorExtensionRegistry = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 66257, 1, 4}

	// ── 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.1.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 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 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 GatewaySessionExtension 

type GatewaySessionExtension struct {
	Version       int                   `asn1:"default:1"`
	MaxConcurrent int                   `asn1:"optional,omitempty"`
	HardTimeout   int                   `asn1:"optional,omitempty"`
	AllowedCIDRs  []string              `asn1:"optional,omitempty"`
	MaxRetries    int                   `asn1:"optional,omitempty"`
	KeyDerivation []KeyDerivationParams `asn1:"optional,explicit,tag:0"`
}

GatewaySessionExtension corresponds to the Gateway Session extension (OID 1.3.6.1.4.1.66257.1.5). Note: This OID is historical/pre-v1.5. The v1.5+ PrincipalAuthorization uses OID .1.2. GatewaySessionExtension is kept as a runtime type (lib/gs.go) for non-AIC session scenarios.

func ParseGatewaySessionExtension 

func ParseGatewaySessionExtension(cert *x509.Certificate) (*GatewaySessionExtension, error)

ParseGatewaySessionExtension parses the Gateway Session extension from a certificate.

func (*GatewaySessionExtension) CIDRAllowed 

func (g *GatewaySessionExtension) CIDRAllowed(ip string) bool

CIDRAllowed checks if the given IP is within allowed CIDRs (empty list = unrestricted).

func (*GatewaySessionExtension) HardTimeoutLimit 

func (g *GatewaySessionExtension) HardTimeoutLimit() int

HardTimeoutLimit returns the session hard timeout in seconds.

func (*GatewaySessionExtension) MaxConcurrentLimit 

func (g *GatewaySessionExtension) MaxConcurrentLimit() int

MaxConcurrentLimit returns the max concurrent connection limit.

func (*GatewaySessionExtension) MaxRetriesLimit 

func (g *GatewaySessionExtension) MaxRetriesLimit() int

MaxRetriesLimit returns the max retries limit.

func (*GatewaySessionExtension) ValidateKeyDerivation 

func (g *GatewaySessionExtension) ValidateKeyDerivation() error

ValidateKeyDerivation validates key derivation parameter size constraints.

type KeyDerivationParams 

type KeyDerivationParams struct {
	KDFAlgorithm asn1.ObjectIdentifier `asn1:"objectidentifier"`
	KeyLength    int                   `asn1:"default:32"`
	Salt         []byte                `asn1:"octet"`
	Info         string                `asn1:"utf8,optional"`
}

KeyDerivationParams for session key derivation (v1.4).

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 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.