crypto_core/error/
taxonomy.rs

1// SPDX-FileCopyrightText: Copyright © 2026 ReallyMe LLC. All rights reserved
2//
3// SPDX-License-Identifier: Apache-2.0
4
5use thiserror::Error;
6
7use super::{
8    AeadBackend, AeadFailureKind, ConstantTimeFailureKind, HkdfFailureKind, HkdfHash, KdfAlgorithm,
9    KdfFailureKind, KdfProfile, KemFailureKind, KeyAgreementFailureKind, KeyWrapAlgorithm,
10    KeyWrapFailureKind, KeyWrapOperation, MacFailureKind, MacHash, RngFailureKind, RngOutputKind,
11    SignatureBackend, SignatureFailureKind, SignatureOperation,
12};
13
14/// Typed error taxonomy for all crypto operations in the workspace.
15#[derive(Debug, Error, Clone, PartialEq, Eq)]
16#[non_exhaustive]
17pub enum CryptoError {
18    /// Supplied key material was malformed or otherwise invalid.
19    #[error("invalid key material")]
20    InvalidKey,
21
22    /// An AEAD key did not have the length the cipher requires.
23    #[error("invalid AEAD key length: expected {expected} bytes, got {actual} bytes")]
24    InvalidAeadKeyLength {
25        /// Key length in bytes the cipher requires.
26        expected: usize,
27        /// Key length in bytes that was supplied.
28        actual: usize,
29    },
30
31    /// An AEAD nonce did not have the length the cipher requires.
32    #[error("invalid AEAD nonce length: expected {expected} bytes, got {actual} bytes")]
33    InvalidAeadNonceLength {
34        /// Nonce length in bytes the cipher requires.
35        expected: usize,
36        /// Nonce length in bytes that was supplied.
37        actual: usize,
38    },
39
40    /// A ciphertext was shorter than the minimum (tag) length.
41    #[error("invalid ciphertext length: minimum {minimum} bytes, got {actual} bytes")]
42    InvalidCiphertextLength {
43        /// Minimum ciphertext length in bytes (the authentication tag length).
44        minimum: usize,
45        /// Ciphertext length in bytes that was supplied.
46        actual: usize,
47    },
48
49    /// AEAD encryption failed in the given backend for the given reason.
50    #[error("AEAD encryption failed in {backend} backend: {kind}")]
51    AeadEncrypt {
52        /// Backend lane in which the failure occurred.
53        backend: AeadBackend,
54        /// Specific encryption failure cause.
55        kind: AeadFailureKind,
56    },
57
58    /// AEAD decryption failed in the given backend for the given reason.
59    #[error("AEAD decryption failed in {backend} backend: {kind}")]
60    AeadDecrypt {
61        /// Backend lane in which the failure occurred.
62        backend: AeadBackend,
63        /// Specific decryption failure cause (includes authentication failure).
64        kind: AeadFailureKind,
65    },
66
67    /// A signature operation failed in the given backend for the given reason.
68    #[error("signature failed in {backend} backend during {operation}: {kind}")]
69    Signature {
70        /// Backend lane in which the failure occurred.
71        backend: SignatureBackend,
72        /// Operation (sign, verify, keygen, encode) that failed.
73        operation: SignatureOperation,
74        /// Specific signature failure cause.
75        kind: SignatureFailureKind,
76    },
77
78    /// A key agreement operation failed for the given reason.
79    #[error("key agreement failed: {kind}")]
80    KeyAgreementFailure {
81        /// Specific key-agreement failure cause.
82        kind: KeyAgreementFailureKind,
83    },
84
85    /// A KEM (key encapsulation) operation failed for the given reason.
86    #[error("KEM operation failed: {kind}")]
87    KemFailure {
88        /// Specific KEM failure cause.
89        kind: KemFailureKind,
90    },
91
92    /// A key-wrap operation failed for the given algorithm and reason.
93    #[error("key wrap failed for {algorithm} during {operation}: {kind}")]
94    KeyWrap {
95        /// Key-wrap algorithm that failed.
96        algorithm: KeyWrapAlgorithm,
97        /// Operation (wrap or unwrap) that failed.
98        operation: KeyWrapOperation,
99        /// Specific key-wrap failure cause.
100        kind: KeyWrapFailureKind,
101    },
102
103    /// A password-based KDF operation failed for the given algorithm/profile.
104    #[error("KDF failed for {algorithm}/{profile}: {kind}")]
105    Kdf {
106        /// KDF algorithm that failed.
107        algorithm: KdfAlgorithm,
108        /// Cost profile in effect at the time of failure.
109        profile: KdfProfile,
110        /// Specific KDF failure cause.
111        kind: KdfFailureKind,
112    },
113
114    /// An HKDF operation failed for the given hash and reason.
115    #[error("HKDF failed for {hash}: {kind}")]
116    Hkdf {
117        /// Hash suite underlying the HKDF operation.
118        hash: HkdfHash,
119        /// Specific HKDF failure cause.
120        kind: HkdfFailureKind,
121    },
122
123    /// An HMAC operation failed for the given hash and reason.
124    #[error("HMAC failed for {hash}: {kind}")]
125    Mac {
126        /// Hash suite underlying the HMAC operation.
127        hash: MacHash,
128        /// Specific HMAC failure cause.
129        kind: MacFailureKind,
130    },
131
132    /// Secure random generation failed for the given output purpose.
133    #[error("secure random generation failed for {output}: {kind}")]
134    Rng {
135        /// Purpose the requested random bytes were being generated for.
136        output: RngOutputKind,
137        /// Specific RNG failure cause.
138        kind: RngFailureKind,
139    },
140
141    /// A constant-time comparison did not match, with the two input lengths.
142    #[error("constant-time comparison failed: {kind}")]
143    ConstantTimeComparison {
144        /// Specific comparison failure cause.
145        kind: ConstantTimeFailureKind,
146        /// Length in bytes of the left-hand input.
147        left_len: usize,
148        /// Length in bytes of the right-hand input.
149        right_len: usize,
150    },
151
152    /// The requested operation is not supported.
153    #[error("unsupported operation")]
154    Unsupported,
155}
crypto_core/error/taxonomy.rs

crypto_core/error/
taxonomy.rs
