1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
//! Error types for soliton.
/// All possible errors from soliton operations.
#[non_exhaustive]
#[derive(Debug, thiserror::Error)]
pub enum Error {
/// Input had an invalid size for the expected key/buffer type.
///
/// `expected` and `got` are safe to expose in Display because this variant
/// is only used for API-boundary size mismatches (e.g., "public key must be
/// 3200 bytes, got 100"). Parser-internal truncation errors use `InvalidData`
/// instead, to avoid leaking internal offsets (see RT-201).
#[error("invalid length: expected {expected}, got {got}")]
InvalidLength {
/// Required size.
expected: usize,
/// Actual size provided.
got: usize,
},
/// KEM decapsulation failed (X-Wing or ML-KEM internal error, or low-order
/// X25519 point in standalone DH).
#[error("decapsulation failed")]
DecapsulationFailed,
/// Signature verification failed (Ed25519, ML-DSA-65, or hybrid verify).
#[error("signature verification failed")]
VerificationFailed,
/// AEAD decryption failed (wrong key, tampered ciphertext, or wrong AAD).
#[error("AEAD decryption failed")]
AeadFailed,
/// Pre-key bundle verification failed (IK mismatch or invalid SPK signature).
#[error("pre-key bundle verification failed")]
BundleVerificationFailed,
/// Reserved — was skip cache overflow in the pre-counter-mode ratchet design.
///
/// Retained for CAPI ABI stability: `SolitonError::TooManySkipped = -6`
/// must not be reassigned. Not currently constructed by any code path.
#[error("too many skipped messages")]
TooManySkipped,
/// Duplicate or out-of-order message (already decrypted or behind recv_count).
#[error("duplicate message")]
DuplicateMessage,
/// Algorithm is disabled or unsupported.
///
/// Reserved for future use (e.g., algorithm deprecation). Not currently
/// constructed by any code path, but retained for CAPI ABI stability —
/// `SolitonError::AlgorithmDisabled = -9` must not be reassigned.
#[error("algorithm disabled")]
AlgorithmDisabled,
/// Serialized blob has unsupported version.
///
/// Payload intentionally omitted — in storage decryption, exposing the
/// version byte would let an attacker enumerate key versions in the keyring.
#[error("unsupported version")]
UnsupportedVersion,
/// Storage decompression failed.
///
/// Not currently constructed — all post-AEAD decompression failures are
/// mapped to `AeadFailed` to prevent error oracles. Retained for CAPI ABI
/// stability — `SolitonError::DecompressionFailed = -11` must not be
/// reassigned.
#[error("decompression failed")]
DecompressionFailed,
/// Storage blob has unsupported flags (reserved bits set).
///
/// Not currently constructed — reserved-flag rejections are mapped to
/// `AeadFailed` to prevent error oracles. Retained for CAPI ABI
/// stability — `SolitonError::UnsupportedFlags = -14` must not be reassigned.
#[error("unsupported storage flags")]
UnsupportedFlags,
/// Chain counter space exhausted.
///
/// Returned when a counter would exceed its maximum value: u32::MAX for
/// ratchet send/recv counters, 2^24 for call key advancement,
/// MAX_RECV_SEEN for the per-epoch duplicate detection set, or u64::MAX
/// for the streaming AEAD chunk index.
#[error("chain exhausted: counter space full")]
ChainExhausted,
/// Unsupported crypto version string in a pre-key bundle or session init.
/// The peer advertised a version this library does not implement.
#[error("unsupported crypto version")]
UnsupportedCryptoVersion,
/// Structurally invalid content: bad format markers, co-presence violations,
/// implausible field values, or semantic constraint failures.
#[error("invalid data")]
InvalidData,
/// Structurally unreachable internal invariant violated — receiving this
/// error indicates a bug in soliton.
#[error("internal error")]
Internal,
}
/// Result type alias for soliton operations.
pub type Result<T> = std::result::Result<T, Error>;