attestation_verify/lib.rs
1//! Verify GitHub Artifact Attestations (Sigstore bundles) offline, at
2//! runtime, in Rust, with a minimal and auditable dependency footprint.
3//!
4//! See `DESIGN.md` in the repository root for the full design.
5//!
6//! # Status: functional, narrow scope
7//!
8//! This crate implements a complete offline verification chain — DSSE
9//! signature, Rekor v1 transparency-log inclusion (SET + Merkle proof +
10//! checkpoint), X.509/Fulcio chain validation, embedded SCT verification,
11//! and GitHub identity-policy matching — for one bundle shape:
12//! `actions/attest-build-provenance`-style bundles carrying a
13//! `https://slsa.dev/provenance/v1` predicate, verified against the
14//! embedded Sigstore public-good trust root or a caller-supplied one.
15//! [`Verifier::verify_digest`] / [`Verifier::verify_bytes`] report success
16//! only once every step of that chain has verified; the caller supplies an
17//! identity policy and an exact checkpoint-origin policy (DESIGN.md "Core
18//! decisions" item 2).
19//!
20//! Out of scope for now (typed [`UnsupportedError`], never silently
21//! accepted): GitHub's own TSA-timestamped release-attestation flavor
22//! (`initiator: github`, no tlog entries), Rekor v2 (Ed25519,
23//! tiles/sharded logs), and any predicate type other than SLSA provenance
24//! v1. This crate has not been independently audited; see `README.md` for
25//! the exact verified scope and `DESIGN.md` for the full design and
26//! roadmap.
27//!
28//! # Layout
29//!
30//! - [`Subject`]: the artifact digest being verified.
31//! - [`Bundle`] / [`BundleSet`]: parsed Sigstore bundles, and the two
32//! container shapes GitHub serves them in.
33//! - [`Statement`]: the in-toto statement inside a bundle's DSSE payload.
34//! - [`TrustStore`]: a parsed trusted-root document.
35//! - [`GithubPolicy`]: the identity policy a [`Verifier`] enforces.
36//! - [`CheckpointOriginPolicy`]: exact signed checkpoint origins bound to
37//! trusted log-key SPKI digests.
38//! - [`Verifier`]: the verification entry point;
39//! [`Verifier::verify_digest`] / [`Verifier::verify_bytes`] return a
40//! [`verifier::VerificationReport`] on success.
41
42#![forbid(unsafe_code)]
43
44pub mod bundle;
45pub mod error;
46pub mod policy;
47pub mod statement;
48pub mod trust;
49pub mod verifier;
50
51mod dsse;
52mod fulcio;
53mod limits;
54mod parse_util;
55mod policy_match;
56mod rekor;
57mod sct;
58mod strict_json;
59mod subject;
60mod time;
61mod x509;
62
63#[cfg(feature = "fuzzing")]
64#[doc(hidden)]
65pub mod fuzzing;
66
67pub use bundle::{
68 AttestationEntry, BUNDLE_MEDIA_TYPE, Bundle, BundleSet, Certificate, Checkpoint, DsseEnvelope,
69 DsseSignature, InclusionPromise, InclusionProof, Rfc3161Timestamp, TimestampVerificationData,
70 TlogEntry, VerificationMaterial,
71};
72pub use error::{
73 CertificateError, ContentBindingError, Error, ParseError, PolicyError, ResourceLimitError,
74 TimestampError, TransparencyError, TrustError, UnsupportedError,
75};
76pub use policy::{
77 CheckpointOriginBinding, CheckpointOriginPolicy, CheckpointOriginPolicyBuilder, CommitSha,
78 GithubPolicy, GithubPolicyBuilder, RefPolicy, RepositoryIdentity, SignerPolicy, SourcePolicy,
79 WorkflowPath, WorkflowRevisionPolicy,
80};
81pub use statement::{STATEMENT_TYPE, Statement, StatementSubject};
82pub use subject::Subject;
83pub use trust::{
84 CaSubject, CertificateAuthority, CtLog, PublicKey, TRUSTED_ROOT_MEDIA_TYPE, TransparencyLog,
85 TrustStore, ValidityPeriod,
86};
87pub use verifier::{
88 TrustSnapshotInfo, VerificationReport, VerifiedCertificateIdentity, VerifiedSignedStatement,
89 VerifiedSubject, VerifiedTransparency, Verifier, VerifierBuilder,
90};