Documentation
¶
Overview ¶
Package verifier implements offline bundle verification with a four-level trust model.
Trust Levels ¶
Verification produces one of four trust levels (highest to lowest):
- verified: Checksums valid, bundle attestation verified, binary attestation verified and identity-pinned to NVIDIA CI, no external data.
- attested: Full chain verified but external data (--data) was used, capping trust because the data's own provenance is unknown.
- unverified: Checksums valid but no attestation files (--attest not used).
- unknown: Missing or invalid checksums, or attestation verification failed.
Verification Chain ¶
Verify performs a five-step offline verification:
- Read and verify checksums.txt (single read to prevent TOCTOU)
- Check for bundle attestation file
- Verify bundle attestation against trusted root, binding to checksums.txt digest and requiring a valid OIDC-issued certificate
- Check for binary attestation file
- Verify binary attestation with identity pinning to NVIDIA CI and binding to the running binary's digest
All verification is fully offline using the locally cached or embedded Sigstore trusted root. No network calls are made during verification.
Identity Pinning ¶
Binary attestation verification pins to NVIDIA's GitHub Actions OIDC issuer and a repository pattern matching NVIDIA/aicr workflows. This ensures the binary was built by NVIDIA CI. The pattern can be overridden via VerifyOptions.CertificateIdentityRegexp but must always contain the github.com/NVIDIA/aicr/ prefix.
Index ¶
Constants ¶
const ( TrustedOIDCIssuer = "https://token.actions.githubusercontent.com" TrustedRepositoryPattern = `^https://github\.com/NVIDIA/aicr/\.github/workflows/on-tag\.yaml@refs/tags/.*` )
Identity pinning constants for NVIDIA CI.
Variables ¶
This section is empty.
Functions ¶
func ValidateIdentityPattern ¶
ValidateIdentityPattern checks that a certificate identity pattern contains the required NVIDIA/aicr GitHub repository URL path. Accepts both literal and regex-escaped forms (e.g., "github.com" or "github\.com").
func VerifyBinaryAttestation ¶
func VerifyBinaryAttestation(ctx context.Context, bundlePath string, identityPattern string, artifactDigest []byte) (string, error)
VerifyBinaryAttestation verifies the binary attestation with identity pinning to the given OIDC issuer and repository pattern, binding the attestation to the given artifact digest. Returns the signer identity on success.
Types ¶
type Policy ¶
type Policy struct {
// MinTrustLevel is the minimum required trust level ("max" resolves to
// the highest achievable level for the bundle).
MinTrustLevel string
// RequireCreator requires the bundle attestation creator to match.
RequireCreator string
// VersionConstraint is a version constraint expression for the CLI version.
// Supports operators: >=, >, <=, <, ==, !=.
// A bare version (e.g. "0.8.0") is treated as ">= 0.8.0".
VersionConstraint string
}
Policy defines verification requirements to enforce after verification.
type TrustLevel ¶
type TrustLevel string
TrustLevel represents the verification trust level of a bundle.
const ( // TrustUnknown indicates missing attestation or checksum files. TrustUnknown TrustLevel = "unknown" // TrustUnverified indicates checksums are valid but no attestation files exist // (bundle was created with --attest not used). TrustUnverified TrustLevel = "unverified" // TrustAttested indicates the full chain is cryptographically verified but // external data (--data) was used, capping trust because the data's own // provenance is unknown. TrustAttested TrustLevel = "attested" // TrustVerified indicates checksums valid, bundle attestation verified, // binary attestation verified with identity pinned to NVIDIA CI, and no // external data. TrustVerified TrustLevel = "verified" )
func ParseTrustLevel ¶
func ParseTrustLevel(s string) (TrustLevel, error)
ParseTrustLevel parses a string into a TrustLevel.
func (TrustLevel) MeetsMinimum ¶
func (t TrustLevel) MeetsMinimum(minimum TrustLevel) bool
MeetsMinimum returns true if this trust level is at least the given minimum.
type VerifyOptions ¶
type VerifyOptions struct {
// CertificateIdentityRegexp overrides the default identity pinning pattern
// for binary attestation verification. Must contain "NVIDIA/aicr".
// Defaults to TrustedRepositoryPattern if empty.
CertificateIdentityRegexp string
}
VerifyOptions configures verification behavior.
type VerifyResult ¶
type VerifyResult struct {
// TrustLevel is the computed trust level for the bundle.
TrustLevel TrustLevel `json:"trustLevel"`
// ChecksumsPassed indicates whether all content files match checksums.txt.
ChecksumsPassed bool `json:"checksumsPassed"`
// ChecksumFiles is the number of files verified by checksum.
ChecksumFiles int `json:"checksumFiles"`
// BundleAttested indicates whether the bundle attestation was verified.
BundleAttested bool `json:"bundleAttested"`
// BinaryAttested indicates whether the binary attestation was verified.
BinaryAttested bool `json:"binaryAttested"`
// IdentityPinned indicates whether the binary attestation identity was pinned to NVIDIA CI.
IdentityPinned bool `json:"identityPinned"`
// BundleCreator is the OIDC identity from the bundle attestation signing certificate.
BundleCreator string `json:"bundleCreator,omitempty"`
// BinaryBuilder is the certificate subject from the binary attestation.
BinaryBuilder string `json:"binaryBuilder,omitempty"`
// ToolVersion is the aicr version extracted from the attestation predicate.
ToolVersion string `json:"toolVersion,omitempty"`
// HasExternalData indicates the bundle contains external data files (data/ directory).
HasExternalData bool `json:"hasExternalData"`
// Errors contains verification failure messages.
Errors []string `json:"errors,omitempty"`
}
VerifyResult contains the outcome of bundle verification.
func Verify ¶
func Verify(ctx context.Context, bundleDir string, opts *VerifyOptions) (*VerifyResult, error)
Verify performs full verification of a bundle directory. Returns a VerifyResult describing the trust level and verification details.
func (*VerifyResult) CheckPolicy ¶
func (r *VerifyResult) CheckPolicy(p Policy) (string, error)
CheckPolicy validates the verification result against a policy. Returns an empty string if all checks pass, or a failure description.
func (*VerifyResult) MaxAchievableTrustLevel ¶
func (r *VerifyResult) MaxAchievableTrustLevel() TrustLevel
MaxAchievableTrustLevel returns the highest trust level this bundle could achieve based on its contents. Used by --min-trust-level max to enforce that verification reached the expected level:
- verified: standard bundle with both attestations, no external data
- attested: external data present (caps trust regardless of attestation chain)
- unverified: no attestation files (--attest not used was used)
- unknown: checksums failed or missing
Source Files