huskarl_core/crypto/
mod.rs

1//! Cryptographic interfaces and definitions.
2//!
3//! Many `OAuth2` grants and auxiliary interfaces require cryptographic
4//! operations to ensure properties such as integrity, authentication,
5//! confidentiality, and non-repudiation.
6//!
7//! This module holds the signing ([`signer`]), verification ([`verifier`]), and
8//! encryption ([`cipher`]) traits, plus the shared key-matching types
9//! ([`KeyMatchStrength`]). Concrete implementations live in platform crates.
10//!
11//! Each base trait comes with a family of composable wrappers (multi-key,
12//! refreshable, scheduled-refresh, retrying) that decorate it without changing
13//! its interface. See [composing crypto
14//! strategies](crate::_docs::explanation::crypto_strategies) for how they stack.
15
16pub mod cipher;
17pub(crate) mod refreshable;
18pub mod signer;
19pub mod verifier;
20
21/// States how well a particular key matched the selection criteria from a JOSE header.
22///
23/// Used by both JWS verifiers and JWE ciphers to express the strength of a key match,
24/// allowing multi-key types to prefer exact matches over algorithm-only matches.
25#[non_exhaustive]
26#[derive(Debug, PartialEq, Eq, Clone, Copy)]
27pub enum KeyMatchStrength {
28    /// Both the algorithm and the key ID match exactly.
29    ByKeyId,
30    /// The algorithm matches but the key ID was not used for matching — either
31    /// the header has no `kid`, or this key has no `kid` registered.
32    ByAlgorithm,
33}
34
35/// The shared `kid` half of the key-matching rules, applied after the
36/// algorithm has already been found compatible: both sides present and equal
37/// is a `ByKeyId` match, both present and different is a mismatch, and a
38/// `kid` missing on either side falls back to `ByAlgorithm`.
39pub(crate) fn kid_match_strength(
40    requested: Option<&str>,
41    registered: Option<&str>,
42) -> Option<KeyMatchStrength> {
43    match (requested, registered) {
44        (Some(requested), Some(registered)) => {
45            (requested == registered).then_some(KeyMatchStrength::ByKeyId)
46        }
47        _ => Some(KeyMatchStrength::ByAlgorithm),
48    }
49}
huskarl_core/crypto/mod.rs

huskarl_core/crypto/
mod.rs
