attestation

Documentation

Overview

Package attestation describes runtime identity evidence and trust levels.

Self-reported fields must never be treated as verified without an explicit trust upgrade from platform or cryptographic verification.

Index

• type Evidence
  • func (e Evidence) Verified() bool
• type Report
  • func SelfReport(service, instance, generation, moduleVersion string) Report
  • func (r Report) DigestHex() (string, error)
  • func (r Report) RequireMinTrust(min TrustLevel) bool
• type TrustLevel
  • func OverallTrustFromEvidence(ev []Evidence) TrustLevel

Types

type Evidence

type Evidence struct {
	Kind        string            `json:"kind"`
	Value       string            `json:"value"`
	Trust       TrustLevel        `json:"trust"`
	CollectedAt time.Time         `json:"collected_at"`
	Attributes  map[string]string `json:"attributes,omitempty"`
}

Evidence is one piece of attestation material with an explicit trust level.

func (Evidence) Verified

func (e Evidence) Verified() bool

Verified reports whether this evidence is above self-reported trust.

type Report

type Report struct {
	Service            string     `json:"service"`
	InstanceID         string     `json:"instance_id"`
	GenerationID       string     `json:"generation_id,omitempty"`
	ModuleVersion      string     `json:"module_version,omitempty"`
	ProtocolVersion    string     `json:"protocol_version,omitempty"`
	CollectedAt        time.Time  `json:"collected_at"`
	Evidence           []Evidence `json:"evidence"`
	OverallTrust       TrustLevel `json:"overall_trust"`
	SecurityPolicyHash string     `json:"security_policy_hash,omitempty"`
}

Report aggregates attestation evidence for a generation or process.

func SelfReport

func SelfReport(service, instance, generation, moduleVersion string) Report

SelfReport builds a self-reported attestation from local process metadata. Callers must not treat the result as platform- or crypto-verified.

func (Report) DigestHex

func (r Report) DigestHex() (string, error)

DigestHex returns a hex SHA-256 of the report's canonical JSON (excluding OverallTrust recompute).

func (Report) RequireMinTrust

func (r Report) RequireMinTrust(min TrustLevel) bool

RequireMinTrust returns false if overall trust is below min.

type TrustLevel

type TrustLevel string

TrustLevel classifies how strongly evidence was validated.

const (
	// TrustSelfReported is process-local data with no external verification.
	TrustSelfReported TrustLevel = "self-reported"
	// TrustPlatformVerified was confirmed by the hosting platform (e.g. K8s SA).
	TrustPlatformVerified TrustLevel = "platform-verified"
	// TrustCryptoVerified was checked against a signature or digest allowlist.
	TrustCryptoVerified TrustLevel = "crypto-verified"
	// TrustExternallyAttested was confirmed by an external attestation service.
	TrustExternallyAttested TrustLevel = "externally-attested"
)

func OverallTrustFromEvidence

func OverallTrustFromEvidence(ev []Evidence) TrustLevel

OverallTrustFromEvidence picks the strongest trust present, defaulting to self-reported.