crypto_dispatch/
traits.rs

1// SPDX-FileCopyrightText: Copyright © 2026 ReallyMe LLC. All rights reserved
2//
3// SPDX-License-Identifier: Apache-2.0
4
5use zeroize::Zeroizing;
6
7use crate::AlgorithmError;
8use crypto_core::{AeadAlgorithm, Algorithm, HashAlgorithm, MacAlgorithm};
9
10/// Borrowed AEAD inputs. Key and nonce lengths are validated by the
11/// selected algorithm's typed constructors at dispatch time, so a wrong
12/// length fails closed with a typed error instead of being truncated or
13/// padded.
14pub struct AeadParams<'a> {
15    /// Symmetric key bytes; length is validated by the selected algorithm.
16    pub key: &'a [u8],
17    /// Nonce bytes; length is validated by the selected algorithm.
18    pub nonce: &'a [u8],
19    /// Additional authenticated data bound to the ciphertext (may be empty).
20    pub aad: &'a [u8],
21}
22
23/// Borrowed HMAC inputs. The selected algorithm validates key and tag lengths
24/// before authenticating so callers cannot accidentally compare truncated tags.
25pub struct MacParams<'a> {
26    /// Symmetric key bytes; length is validated by the selected algorithm.
27    pub key: &'a [u8],
28}
29
30/// Adapter contract for a detached-signature algorithm.
31pub trait SignatureAlgorithm {
32    /// The algorithm selector this adapter implements.
33    const ALG: Algorithm;
34
35    /// Generate a keypair, returning `(public_key, secret_key)`; the secret
36    /// zeroizes on drop.
37    fn generate_keypair() -> Result<(Vec<u8>, Zeroizing<Vec<u8>>), AlgorithmError>;
38    /// Sign `msg` with `secret`, returning the detached signature bytes.
39    fn sign(secret: &[u8], msg: &[u8]) -> Result<Vec<u8>, AlgorithmError>;
40    /// Verify `sig` over `msg` against `public`; invalid signatures fail closed.
41    fn verify(public: &[u8], msg: &[u8], sig: &[u8]) -> Result<(), AlgorithmError>;
42}
43
44/// Adapter contract for an AEAD cipher algorithm.
45pub trait AeadCipherAlgorithm {
46    /// The AEAD algorithm selector this adapter implements.
47    const ALG: AeadAlgorithm;
48
49    /// Encrypt `plaintext` under `params`, returning `ciphertext || tag`.
50    fn encrypt(params: &AeadParams<'_>, plaintext: &[u8]) -> Result<Vec<u8>, AlgorithmError>;
51    /// Decrypt and authenticate `ciphertext || tag`; fails closed on a
52    /// tampered ciphertext or AAD. Returned plaintext zeroizes on drop.
53    fn decrypt(
54        params: &AeadParams<'_>,
55        ciphertext_with_tag: &[u8],
56    ) -> Result<Zeroizing<Vec<u8>>, AlgorithmError>;
57}
58
59/// Adapter contract for a cryptographic hash algorithm.
60pub trait HashDigestAlgorithm {
61    /// The hash algorithm selector this adapter implements.
62    const ALG: HashAlgorithm;
63
64    /// Compute the digest of `message`, returning the raw digest bytes.
65    fn digest(message: &[u8]) -> Result<Vec<u8>, AlgorithmError>;
66}
67
68/// Adapter contract for a message authentication code algorithm.
69pub trait MacAlgorithmAdapter {
70    /// The MAC algorithm selector this adapter implements.
71    const ALG: MacAlgorithm;
72
73    /// Compute a MAC tag over `message`.
74    fn authenticate(params: &MacParams<'_>, message: &[u8]) -> Result<Vec<u8>, AlgorithmError>;
75    /// Verify `tag` over `message`; failures are returned as typed errors.
76    fn verify(params: &MacParams<'_>, message: &[u8], tag: &[u8]) -> Result<(), AlgorithmError>;
77}
crypto_dispatch/traits.rs

crypto_dispatch/
traits.rs
