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}