aster_forge_crypto/
lib.rs

1//! Shared cryptographic helpers for Aster services.
2//!
3//! The crate exposes password hashing, digest utilities, and a versioned authenticated secret
4//! envelope shared by Aster products. It keeps the error surface narrow so services can map
5//! cryptographic failures into their own API or domain errors without depending on
6//! implementation-specific error types.
7#![cfg_attr(
8    not(test),
9    deny(
10        clippy::unwrap_used,
11        clippy::unreachable,
12        clippy::expect_used,
13        clippy::panic,
14        clippy::unimplemented,
15        clippy::todo
16    )
17)]
18
19pub mod hash;
20pub mod secret_envelope;
21
22pub use hash::{
23    PasswordHashPolicy, PasswordHashVerification, PasswordHashVerificationLimits,
24    PasswordHashWorkFactor, bytes_to_hex, hash_password, hash_password_with_policy,
25    hmac_sha256_hex, new_sha256, sha256_digest_to_hex, sha256_hex, verify_password,
26    verify_password_with_policy,
27};
28pub use secret_envelope::{decrypt_secret, encrypt_secret};
29
30/// Result type returned by `aster_forge_crypto` helpers.
31pub type Result<T> = std::result::Result<T, CryptoError>;
32
33/// Errors produced by cryptographic helper functions.
34#[derive(Debug, thiserror::Error)]
35pub enum CryptoError {
36    /// Password hashing, parsing, or verification failed.
37    #[error("password hash error: {0}")]
38    PasswordHash(String),
39
40    /// A password-hash policy is internally inconsistent or unsupported.
41    #[error("password hash policy error: {0}")]
42    PasswordHashPolicy(String),
43
44    /// A stored password hash exceeds the configured verification resource budget.
45    #[error("password hash parameter {parameter}={actual} exceeds verification limit {maximum}")]
46    PasswordHashVerificationLimit {
47        /// PHC parameter or derived value that exceeded the limit.
48        parameter: &'static str,
49        /// Value read from the stored password hash.
50        actual: u64,
51        /// Maximum value accepted by the verification policy.
52        maximum: u64,
53    },
54
55    /// Keyed message authentication initialization failed.
56    #[error("message authentication error: {0}")]
57    MessageAuthentication(String),
58
59    /// The caller supplied an invalid product-owned secret-envelope context or policy value.
60    #[error("invalid secret envelope policy")]
61    InvalidSecretEnvelopePolicy,
62
63    /// The stored secret envelope is malformed.
64    #[error("invalid secret envelope")]
65    InvalidSecretEnvelope,
66
67    /// The stored secret envelope uses an unsupported version.
68    #[error("unsupported secret envelope version")]
69    UnsupportedSecretEnvelopeVersion,
70
71    /// The encryption key could not be derived for the supplied context.
72    #[error("secret envelope key derivation failed")]
73    SecretEnvelopeKeyDerivation,
74
75    /// Authenticated encryption failed.
76    #[error("secret envelope encryption failed")]
77    SecretEnvelopeEncryption,
78
79    /// Authentication or decryption failed.
80    #[error("secret envelope authentication failed")]
81    SecretEnvelopeAuthentication,
82}
83
84impl CryptoError {
85    /// Creates a password-hash error from any displayable error value.
86    pub fn password_hash(error: impl std::fmt::Display) -> Self {
87        Self::PasswordHash(error.to_string())
88    }
89
90    /// Creates a password-hash policy error.
91    pub fn password_hash_policy(error: impl std::fmt::Display) -> Self {
92        Self::PasswordHashPolicy(error.to_string())
93    }
94
95    /// Creates a keyed message-authentication error.
96    pub fn message_authentication(error: impl std::fmt::Display) -> Self {
97        Self::MessageAuthentication(error.to_string())
98    }
99}
aster_forge_crypto/lib.rs

aster_forge_crypto/
lib.rs
