Skip to main content

attestation_verify/
error.rs

1//! Mechanical error taxonomy.
2//!
3//! Every error states what check failed, never what an attacker may have
4//! intended. Each top-level variant wraps its own `#[non_exhaustive]` enum so
5//! new failure modes can be added without a semver break. See DESIGN.md,
6//! "Core decisions" item 8.
7
8use thiserror::Error;
9
10/// Top-level error type for this crate.
11///
12/// Each variant corresponds to one stage of parsing or (eventually)
13/// verification. The taxonomy is intentionally mechanical: it says what
14/// check failed, not what an attacker may have intended (no `Tampered`
15/// variant, no inferred staleness).
16#[derive(Debug, Error)]
17#[non_exhaustive]
18pub enum Error {
19    /// A parser rejected malformed or non-conforming input.
20    #[error("parse error: {0}")]
21    Parse(#[from] ParseError),
22
23    /// The input uses a format, media type, or version this crate does not
24    /// (yet) support.
25    #[error("unsupported: {0}")]
26    Unsupported(#[from] UnsupportedError),
27
28    /// A trust-root or trust-material check failed.
29    #[error("trust error: {0}")]
30    Trust(#[from] TrustError),
31
32    /// An X.509 certificate failed validation.
33    #[error("certificate error: {0}")]
34    Certificate(#[from] CertificateError),
35
36    /// A transparency-log (Rekor) check failed.
37    #[error("transparency error: {0}")]
38    Transparency(#[from] TransparencyError),
39
40    /// An RFC 3161 timestamp check failed.
41    #[error("timestamp error: {0}")]
42    Timestamp(#[from] TimestampError),
43
44    /// The subject digest did not bind to the signed statement.
45    #[error("content binding error: {0}")]
46    ContentBinding(#[from] ContentBindingError),
47
48    /// The caller's identity policy was not satisfied.
49    #[error("policy error: {0}")]
50    Policy(#[from] PolicyError),
51
52    /// An input exceeded a hard-coded resource limit.
53    #[error("resource limit exceeded: {0}")]
54    ResourceLimit(#[from] ResourceLimitError),
55}
56
57/// Failures while parsing a bundle, statement, or trusted-root document.
58#[derive(Debug, Error)]
59#[non_exhaustive]
60pub enum ParseError {
61    /// The input was not well-formed JSON, or did not match the expected
62    /// shape once parsed.
63    #[error("invalid JSON: {0}")]
64    Json(String),
65
66    /// A field that must be strict base64 (standard alphabet, padded) was
67    /// not valid base64.
68    #[error("invalid base64 in field `{field}`: {reason}")]
69    Base64 {
70        /// Name of the field that failed to decode.
71        field: &'static str,
72        /// Human-readable reason the decode failed.
73        reason: String,
74    },
75
76    /// A field that must be strict hex was not valid hex, or had the wrong
77    /// length.
78    #[error("invalid hex in field `{field}`: {reason}")]
79    Hex {
80        /// Name of the field that failed to decode.
81        field: &'static str,
82        /// Human-readable reason the decode failed.
83        reason: String,
84    },
85
86    /// A digest string was the wrong length, wrong case set, or contained
87    /// non-hex characters.
88    #[error("malformed digest: {0}")]
89    MalformedDigest(String),
90
91    /// An integer field that protojson encodes as a JSON string (`int64`,
92    /// `uint64`) was not a valid decimal integer.
93    #[error("field `{field}` is not a valid integer: {value}")]
94    NotAnInteger {
95        /// Name of the field that failed to parse.
96        field: &'static str,
97        /// The raw string value that failed to parse as an integer.
98        value: String,
99    },
100
101    /// The DSSE envelope did not carry exactly one signature.
102    #[error("dsse envelope has {count} signatures, expected exactly 1")]
103    DsseSignatureCount {
104        /// Number of signatures actually present.
105        count: usize,
106    },
107
108    /// A required field was absent.
109    #[error("missing required field `{0}`")]
110    MissingField(&'static str),
111
112    /// A container format (JSONL, API response) had no usable entries.
113    #[error("empty container: {0}")]
114    EmptyContainer(&'static str),
115
116    /// An in-toto statement subject had an empty or otherwise unusable
117    /// digest map.
118    #[error("statement subject has no usable digest: {0}")]
119    MalformedSubject(String),
120
121    /// A field that must be an RFC 3339 timestamp did not parse as one.
122    #[error("invalid RFC 3339 timestamp in field `{field}`: {reason}")]
123    Rfc3339 {
124        /// Name of the field that failed to parse.
125        field: &'static str,
126        /// Human-readable reason the timestamp was rejected.
127        reason: String,
128    },
129
130    /// A Rekor checkpoint (signed note) envelope did not match the
131    /// expected line structure: `<origin>\n<treeSize>\n<rootHash>\n`,
132    /// optional extension lines, a blank line, then one or more `— <name>
133    /// <base64>` signature lines.
134    #[error("malformed checkpoint envelope: {0}")]
135    Checkpoint(String),
136}
137
138/// The input is well-formed but uses a format, version, or shape this crate
139/// does not implement.
140#[derive(Debug, Error)]
141#[non_exhaustive]
142pub enum UnsupportedError {
143    /// `mediaType` did not match any media type this crate understands.
144    #[error("unsupported media type: {found}")]
145    MediaType {
146        /// The media-type string found in the input.
147        found: String,
148    },
149
150    /// A container (e.g. the GitHub attestations API response) had entries
151    /// but none carried an inline bundle.
152    #[error("no inline bundles in response (bundles must be fetched out of band)")]
153    BundlesNotInline,
154
155    /// A Rekor transparency-log entry used an unsupported `kind`/`version`
156    /// pair.
157    #[error("unsupported tlog entry kind/version: {kind}/{version}")]
158    TlogEntryKindVersion {
159        /// The `kind` field found in the entry.
160        kind: String,
161        /// The `version` field found in the entry.
162        version: String,
163    },
164
165    /// A DSSE envelope's `payloadType` was not the in-toto media type
166    /// (`application/vnd.in-toto+json`). The payload type is covered by
167    /// the PAE signature, so requiring it is what makes a signature over
168    /// some other application's payload type unusable here: without the
169    /// check, an envelope a policy-trusted identity signed under a
170    /// different protocol could be replayed as an in-toto attestation.
171    #[error("unsupported dsse payload type: {found}")]
172    DssePayloadType {
173        /// The `payloadType` string found in the envelope.
174        found: String,
175    },
176
177    /// An in-toto statement's `_type` field did not match a statement
178    /// version this crate understands.
179    #[error("unsupported in-toto statement type: {found}")]
180    StatementType {
181        /// The `_type` string found in the input.
182        found: String,
183    },
184
185    /// A signed statement's `predicateType` was not on this crate's
186    /// supported allow-list. v0.1 verifies exactly one predicate type
187    /// (`https://slsa.dev/provenance/v1`); GitHub's own release predicate
188    /// (`https://in-toto.io/attestation/release/v0.2`) and any other
189    /// predicate type are rejected here rather than verified and silently
190    /// misinterpreted.
191    #[error("unsupported predicate type: {found}")]
192    PredicateType {
193        /// The `predicateType` string found in the statement.
194        found: String,
195    },
196
197    /// A bundle carried more than one transparency-log entry. This crate's
198    /// verification chain checks exactly one; selecting among several
199    /// candidate entries is unimplemented (no real-world fixture has been
200    /// observed with more than one).
201    #[error("bundle has {count} tlog entries, expected exactly 1")]
202    MultipleTlogEntries {
203        /// The actual number of tlog entries found.
204        count: usize,
205    },
206}
207
208/// Trust-root or trust-material failures.
209#[derive(Debug, Error)]
210#[non_exhaustive]
211pub enum TrustError {
212    /// No key in the trust store matched the identifier the bundle
213    /// referenced.
214    #[error("unknown trust-store key id")]
215    UnknownKeyId,
216
217    /// A key existed but was not valid at the required authenticated time.
218    #[error("no trusted key valid at the required time")]
219    NoTrustedKeyValidAt,
220}
221
222/// X.509 certificate validation failures.
223#[derive(Debug, Error)]
224#[non_exhaustive]
225pub enum CertificateError {
226    /// The certificate could not be parsed as DER.
227    #[error("certificate is not valid DER: {0}")]
228    InvalidDer(String),
229
230    /// A `SubjectPublicKeyInfo` (from a leaf certificate or a trust-store
231    /// key) used a key algorithm/curve this crate does not implement.
232    /// Only P-256 and P-384 ECDSA are supported.
233    #[error("unsupported public key algorithm")]
234    UnsupportedKeyAlgorithm,
235
236    /// A certificate's declared signature algorithm was not ECDSA with
237    /// SHA-256 (P-256) or ECDSA with SHA-384 (P-384) -- the only
238    /// algorithms DESIGN.md's "X.509 / Fulcio validation profile" allows.
239    #[error("unsupported certificate signature algorithm")]
240    UnsupportedSignatureAlgorithm,
241
242    /// No certificate authority in the trust store produced a valid chain
243    /// from the leaf to a self-signed root. Bundle-supplied roots are
244    /// never trusted, so this is also the error for a leaf whose issuer
245    /// matches no trust-store entry at all.
246    #[error("no trusted certificate authority validated this certificate chain")]
247    UntrustedCertificate,
248
249    /// A certificate's signature did not cryptographically verify against
250    /// its issuer's public key.
251    #[error("certificate signature did not verify")]
252    SignatureInvalid,
253
254    /// A certificate's `issuer` did not DER-match its issuer certificate's
255    /// `subject`.
256    #[error("certificate issuer does not match issuing certificate's subject")]
257    IssuerNameMismatch,
258
259    /// The authenticated time fell outside a certificate's
260    /// `[notBefore, notAfter]` validity window.
261    #[error("authenticated time is outside the certificate's validity window")]
262    OutsideCertificateValidity,
263
264    /// The authenticated time fell outside the trust-store certificate
265    /// authority entry's `validFor` window.
266    #[error("authenticated time is outside the trusted certificate authority's validFor window")]
267    OutsideCaValidity,
268
269    /// A certificate's `basicConstraints` did not match what its role in
270    /// the chain requires: a certificate authority must be `CA:TRUE`, and
271    /// the leaf must have `basicConstraints` absent or `CA:FALSE`.
272    #[error("certificate basicConstraints does not match its role in the chain")]
273    InvalidBasicConstraints,
274
275    /// A certificate authority's `pathLenConstraint` was violated by the
276    /// number of certificate authorities subordinate to it in the chain.
277    #[error("certificate authority pathLenConstraint exceeded")]
278    PathLengthExceeded,
279
280    /// A certificate's `keyUsage` extension was absent, or lacked the bit
281    /// its role in the chain requires (`digitalSignature` on the leaf,
282    /// `keyCertSign` on each certificate authority).
283    #[error("certificate keyUsage is missing or lacks the required bit")]
284    MissingKeyUsage,
285
286    /// The leaf certificate's `extKeyUsage` extension was absent, or did
287    /// not contain `codeSigning` (1.3.6.1.5.5.7.3.3).
288    #[error("leaf certificate extKeyUsage does not contain codeSigning")]
289    MissingCodeSigningEku,
290
291    /// The leaf certificate carried a critical extension this crate does
292    /// not recognize. RFC 5280 SS4.2 requires rejecting certificates with
293    /// critical extensions a validator does not understand.
294    #[error("leaf certificate has an unrecognized critical extension")]
295    UnknownCriticalExtension,
296
297    /// An extension this crate models by OID appeared more than once on a
298    /// certificate.
299    #[error("certificate has a duplicate extension")]
300    DuplicateExtension,
301
302    /// The leaf certificate carried no embedded SCT (Signed Certificate
303    /// Timestamp) list extension, or the list was empty.
304    #[error("leaf certificate has no embedded SCT")]
305    SctMissing,
306
307    /// No embedded SCT verified against any trusted CT log key.
308    #[error("no embedded SCT verified against a trusted CT log key")]
309    SctInvalid,
310
311    /// An SCT's `logId` did not match any CT log in the trust store.
312    #[error("SCT logId does not match any trusted CT log")]
313    UnknownCtLog,
314
315    /// An SCT's `timestamp` fell outside its matched CT log key's
316    /// `validFor` window.
317    #[error("SCT timestamp is outside the trusted CT log key's validFor window")]
318    SctOutsideKeyValidity,
319}
320
321/// Transparency-log (Rekor) verification failures.
322#[derive(Debug, Error)]
323#[non_exhaustive]
324pub enum TransparencyError {
325    /// The Merkle inclusion proof did not verify against the checkpoint,
326    /// or the proof's `logIndex`/`treeSize`/hash count were inconsistent
327    /// (including over- or under-length hash lists).
328    #[error("inclusion proof did not verify")]
329    InclusionProofInvalid,
330
331    /// The bundle carried no transparency-log entries to verify.
332    #[error("bundle has no transparency-log entries")]
333    NoTlogEntries,
334
335    /// No key in the trust store's transparency logs had a SHA-256 digest
336    /// of its `SubjectPublicKeyInfo` matching the entry's `logId.keyId`.
337    #[error("no trusted log key matches this entry's logId")]
338    UnknownLogKey,
339
340    /// The tlog entry carried no inclusion promise (SET). A SET is
341    /// required: an inclusion proof alone does not authenticate
342    /// `integratedTime` (DESIGN.md "Time-evidence model").
343    #[error("tlog entry has no inclusion promise (SET)")]
344    SetMissing,
345
346    /// The inclusion promise (SET) did not verify against the selected
347    /// trusted log key.
348    #[error("inclusion promise (SET) did not verify")]
349    SetInvalid,
350
351    /// The tlog entry carried no Merkle inclusion proof.
352    #[error("tlog entry has no inclusion proof")]
353    InclusionProofMissing,
354
355    /// The checkpoint's tree size did not match the inclusion proof's
356    /// tree size.
357    #[error("checkpoint treeSize does not match the inclusion proof's treeSize")]
358    CheckpointTreeSizeMismatch,
359
360    /// The checkpoint's root hash did not match the inclusion proof's
361    /// root hash.
362    #[error("checkpoint rootHash does not match the inclusion proof's rootHash")]
363    CheckpointRootHashMismatch,
364
365    /// No signature line in the checkpoint verified against the selected
366    /// trusted log key.
367    #[error("no checkpoint signature verified with the trusted log key")]
368    CheckpointSignatureInvalid,
369
370    /// The checkpoint signature authenticated successfully, but its opaque
371    /// origin was not allowed for the selected trusted log-key identity.
372    ///
373    /// This intentionally carries no origin or key material so an attacker
374    /// cannot use verification errors as an oracle for policy contents.
375    #[error("checkpoint origin is not allowed for the trusted log key")]
376    CheckpointOriginMismatch,
377}
378
379/// RFC 3161 timestamp verification failures.
380#[derive(Debug, Error)]
381#[non_exhaustive]
382pub enum TimestampError {
383    /// The RFC 3161 timestamp token did not parse or verify.
384    #[error("rfc3161 timestamp invalid")]
385    Invalid,
386
387    /// The authenticated `integratedTime` fell outside the selected
388    /// trusted log key's `validFor` window.
389    #[error("integratedTime is outside the trusted log key's validity window")]
390    IntegratedTimeOutsideLogKeyValidity,
391
392    /// The authenticated `integratedTime` fell outside the leaf
393    /// certificate's `[notBefore, notAfter]` validity window.
394    #[error("integratedTime is outside the leaf certificate's validity window")]
395    IntegratedTimeOutsideCertificateValidity,
396}
397
398/// The signed content did not bind to the requested subject.
399#[derive(Debug, Error)]
400#[non_exhaustive]
401pub enum ContentBindingError {
402    /// The requested subject digest was not present among the statement's
403    /// subjects.
404    #[error("subject digest not found in statement")]
405    SubjectNotFound,
406
407    /// A DSSE envelope's signature did not verify against the leaf
408    /// certificate's public key over the PAE-encoded payload.
409    #[error("dsse envelope signature did not verify")]
410    DsseSignatureInvalid,
411
412    /// The Rekor entry's own `kind`/`apiVersion` (inside the
413    /// canonicalized body) did not match the bundle's `kindVersion`
414    /// metadata for the same tlog entry.
415    #[error("tlog entry kindVersion does not match the canonicalized body's kind/apiVersion")]
416    TlogEntryKindVersionMismatch,
417
418    /// The Rekor entry's recorded signature did not match the bundle's
419    /// DSSE signature.
420    #[error("tlog entry signature does not match the bundle's DSSE signature")]
421    TlogEntrySignatureMismatch,
422
423    /// The Rekor entry's recorded verifier certificate did not match the
424    /// bundle's leaf certificate.
425    #[error("tlog entry verifier certificate does not match the bundle's leaf certificate")]
426    TlogEntryCertificateMismatch,
427
428    /// The Rekor entry's recorded payload hash did not match the SHA-256
429    /// of the bundle's decoded DSSE payload.
430    #[error("tlog entry payloadHash does not match the bundle's DSSE payload")]
431    TlogEntryPayloadHashMismatch,
432
433    /// The Rekor entry's recorded envelope hash did not match this
434    /// crate's recomputation of it from the bundle's DSSE envelope.
435    #[error("tlog entry envelopeHash does not match the bundle's DSSE envelope")]
436    TlogEntryEnvelopeHashMismatch,
437}
438
439/// The caller-supplied identity policy was not satisfied.
440///
441/// Matching (`crate::policy_match`) never infers what a mismatch might
442/// mean; every variant below names exactly which comparison failed, and
443/// (where applicable) carries the `expected` policy value alongside the
444/// `found` authenticated certificate value (DESIGN.md "Core decisions"
445/// item 8).
446#[derive(Debug, Error)]
447#[non_exhaustive]
448pub enum PolicyError {
449    /// A policy builder was given an empty or malformed value.
450    #[error("invalid policy configuration: {0}")]
451    InvalidConfiguration(String),
452
453    /// A Fulcio identity claim needed to evaluate the policy was absent
454    /// from the certificate (its extension was not present).
455    #[error("certificate is missing the `{claim}` identity claim required to evaluate policy")]
456    MissingIdentityClaim {
457        /// The name of the missing claim (e.g. `"source_repository_uri"`).
458        claim: &'static str,
459    },
460
461    /// A Fulcio identity claim was present but not in the shape this crate
462    /// requires to evaluate policy (e.g. the source repository URI or the
463    /// SAN URI did not match the expected `https://github.com/...` shape).
464    #[error("certificate's `{claim}` identity claim is malformed: {reason}")]
465    MalformedIdentityClaim {
466        /// The name of the malformed claim.
467        claim: &'static str,
468        /// Human-readable reason the claim was rejected.
469        reason: String,
470    },
471
472    /// The certificate's authenticated OIDC issuer did not match the
473    /// pinned GitHub Actions issuer.
474    #[error("issuer mismatch: expected {expected}, found {found}")]
475    IssuerMismatch {
476        /// The pinned issuer this crate requires.
477        expected: String,
478        /// The issuer found in the certificate.
479        found: String,
480    },
481
482    /// The certificate's authenticated source repository (`owner/name`)
483    /// did not match the policy's required source repository.
484    #[error("source repository mismatch: expected {expected}, found {found}")]
485    SourceRepositoryMismatch {
486        /// The `owner/name` the policy requires.
487        expected: String,
488        /// The `owner/name` found in the certificate.
489        found: String,
490    },
491
492    /// The certificate's authenticated source repository owner id did not
493    /// match the policy's pinned owner id.
494    #[error("source repository owner id mismatch: expected {expected}, found {found}")]
495    SourceOwnerIdMismatch {
496        /// The decimal owner id the policy requires.
497        expected: String,
498        /// The decimal owner id found in the certificate.
499        found: String,
500    },
501
502    /// The certificate's authenticated source repository id did not match
503    /// the policy's pinned repository id.
504    #[error("source repository id mismatch: expected {expected}, found {found}")]
505    SourceRepositoryIdMismatch {
506        /// The decimal repository id the policy requires.
507        expected: String,
508        /// The decimal repository id found in the certificate.
509        found: String,
510    },
511
512    /// The certificate's authenticated source ref did not satisfy the
513    /// policy's ref requirement (`Exact` or `Glob`).
514    #[error("source ref mismatch: expected {expected}, found {found}")]
515    SourceRefMismatch {
516        /// The policy's required ref or ref-glob pattern.
517        expected: String,
518        /// The ref found in the certificate.
519        found: String,
520    },
521
522    /// The certificate's authenticated source commit did not match the
523    /// policy's required commit.
524    #[error("source commit mismatch: expected {expected}, found {found}")]
525    SourceCommitMismatch {
526        /// The commit sha (lowercase hex) the policy requires.
527        expected: String,
528        /// The commit sha found in the certificate.
529        found: String,
530    },
531
532    /// The certificate's authenticated signer-workflow repository
533    /// (`owner/name`) did not match the policy's required repository.
534    #[error("signer repository mismatch: expected {expected}, found {found}")]
535    SignerRepositoryMismatch {
536        /// The `owner/name` the policy requires.
537        expected: String,
538        /// The `owner/name` found in the certificate's SAN.
539        found: String,
540    },
541
542    /// The certificate's authenticated signer-workflow path did not match
543    /// the policy's required path.
544    #[error("signer workflow path mismatch: expected {expected}, found {found}")]
545    SignerWorkflowPathMismatch {
546        /// The workflow path the policy requires.
547        expected: String,
548        /// The workflow path found in the certificate's SAN.
549        found: String,
550    },
551
552    /// The certificate's authenticated signer-workflow revision did not
553    /// satisfy the policy's revision requirement (`Ref` or `Sha`).
554    #[error("signer workflow revision mismatch: expected {expected}, found {found}")]
555    SignerRevisionMismatch {
556        /// The ref or commit sha the policy requires.
557        expected: String,
558        /// The ref or digest found in the certificate.
559        found: String,
560    },
561}
562
563/// A hard resource limit (size, count, or depth) was exceeded. These limits
564/// exist to keep parsing cost bounded and independent of attacker-controlled
565/// input shape.
566#[derive(Debug, Error)]
567#[non_exhaustive]
568pub enum ResourceLimitError {
569    /// The raw input exceeded the maximum accepted byte length.
570    #[error("input of {actual} bytes exceeds the {limit}-byte limit")]
571    InputTooLarge {
572        /// The actual input length in bytes.
573        actual: usize,
574        /// The maximum accepted length in bytes.
575        limit: usize,
576    },
577
578    /// A JSON document parsed to more `serde_json::Value` nodes than the
579    /// limit. Carries no actual count: parsing stops at the limit rather
580    /// than walking the rest of the input to total it up.
581    #[error("JSON document exceeds the limit of {limit} value nodes")]
582    TooManyJsonNodes {
583        /// The maximum accepted number of value nodes.
584        limit: usize,
585    },
586
587    /// A bundle carried more transparency-log entries than the limit.
588    #[error("{actual} tlog entries exceeds the limit of {limit}")]
589    TooManyTlogEntries {
590        /// The actual number of entries found.
591        actual: usize,
592        /// The maximum accepted number of entries.
593        limit: usize,
594    },
595
596    /// An in-toto statement carried more subjects than the limit.
597    #[error("{actual} statement subjects exceeds the limit of {limit}")]
598    TooManySubjects {
599        /// The actual number of subjects found.
600        actual: usize,
601        /// The maximum accepted number of subjects.
602        limit: usize,
603    },
604
605    /// A `BundleSet` container carried more bundles than the limit.
606    #[error("{actual} bundles exceeds the limit of {limit} per BundleSet")]
607    TooManyBundles {
608        /// The actual number of bundles found.
609        actual: usize,
610        /// The maximum accepted number of bundles.
611        limit: usize,
612    },
613
614    /// A certificate chain carried more certificates than the limit.
615    #[error("{actual} certificates exceeds the limit of {limit} per chain")]
616    TooManyCertificates {
617        /// The actual number of certificates found.
618        actual: usize,
619        /// The maximum accepted number of certificates.
620        limit: usize,
621    },
622
623    /// A checkpoint carried more signature lines than the limit.
624    #[error("{actual} checkpoint signature lines exceeds the limit of {limit}")]
625    TooManyCheckpointSignatures {
626        /// The actual number of signature lines found.
627        actual: usize,
628        /// The maximum accepted number of signature lines.
629        limit: usize,
630    },
631}