basil_cose/
traits.rs

1// SPDX-FileCopyrightText: 2026 OpenBasil Contributors
2//
3// SPDX-License-Identifier: Apache-2.0
4
5//! The `Signer` / `Verifier` / `Recipient` traits.
6//!
7//! Native `async fn` in traits (AFIT), consumed through generics: no
8//! `async_trait` proc-macro dependency and no `dyn` in the public API. Local
9//! implementations (this crate's [`keys`](crate::keys)) complete
10//! synchronously; broker-backed implementations (which live in the basil
11//! client crate, not here) await an RPC.
12
13use alloc::vec::Vec;
14
15use zeroize::Zeroizing;
16
17use crate::alg::SignatureAlgorithm;
18use crate::claims::ProtectedHeaders;
19use crate::error::{OpenError, SignError, VerifyError};
20use crate::kdf::KdfParties;
21use crate::types::{ExternalAad, KeyId, Signature};
22
23/// Produces the signature over `Sig_structure` bytes.
24///
25/// The broker backs this with sign-in-place (Ed25519 transit accepts the
26/// full arbitrary-length structure); clients use local keys.
27pub trait Signer {
28    /// The signing key id; becomes the outer `kid`.
29    fn key_id(&self) -> &KeyId;
30
31    /// The signature algorithm this signer produces.
32    fn algorithm(&self) -> SignatureAlgorithm;
33
34    /// Sign the exact `Sig_structure` bytes.
35    async fn sign(&self, sig_structure: &[u8]) -> Result<Signature, SignError>;
36}
37
38/// Resolves a `kid` and verifies a signature.
39///
40/// Implementors enforce their own key/alg pinning (a broker checks the wire
41/// alg against its catalog record inside its impl; a client checks against
42/// its pinned broker key). Async because kid resolution may be remote (for
43/// example resolving an unfamiliar peer kid over an RPC); local pinned-key
44/// impls complete synchronously.
45pub trait Verifier {
46    /// Verify `signature` over the exact `Sig_structure` bytes, produced by
47    /// the key `key_id` under `algorithm`.
48    ///
49    /// `protected_headers` carries the decoded critical protected headers (for
50    /// example signer-certificate JWTs under `-70006`) so an implementor whose
51    /// trust decision depends on them can resolve `key_id` from the message;
52    /// implementors that pin keys out of band ignore it.
53    async fn verify(
54        &self,
55        key_id: &KeyId,
56        algorithm: SignatureAlgorithm,
57        protected_headers: &ProtectedHeaders,
58        sig_structure: &[u8],
59        signature: &Signature,
60    ) -> Result<(), VerifyError>;
61}
62
63/// Everything an opener needs, already strictly validated by the decode
64/// entry points, plus the raw encrypt bytes so a remote (broker-backed)
65/// recipient can forward them verbatim without re-encoding.
66///
67/// The `Enc_structure` AAD embeds the exact serialized protected-header
68/// bytes, so any re-encoding of `cose_encrypt` on the way to the key would
69/// break the AEAD tag.
70#[derive(Debug, Clone)]
71pub struct OpenRequest<'a> {
72    /// Exact tagged `COSE_Encrypt` bytes, verbatim.
73    pub cose_encrypt: &'a [u8],
74    /// Encryption-layer external AAD.
75    pub external_aad: &'a ExternalAad,
76    /// Pin the KDF party identities, or `None` to accept the message values.
77    pub expected_parties: Option<&'a KdfParties>,
78}
79
80/// Opens one `COSE_Encrypt` addressed to `key_id()`: ECDH-ES decapsulation +
81/// HKDF-256 (`COSE_KDF_Context`) + content AEAD, returning zeroizing
82/// plaintext.
83///
84/// A broker-backed impl forwards `OpenRequest::cose_encrypt` verbatim to the
85/// broker unseal RPC; the local impl holds a `Zeroizing` X25519 private. A
86/// successful open proves confidentiality, never sender identity. Sender
87/// identity comes only from the outer `COSE_Sign1`.
88pub trait Recipient {
89    /// The recipient (static X25519) key id.
90    fn key_id(&self) -> &KeyId;
91
92    /// Open the message, returning the plaintext in a zeroizing buffer.
93    async fn open(&self, request: &OpenRequest<'_>) -> Result<Zeroizing<Vec<u8>>, OpenError>;
94}
basil_cose/traits.rs

basil_cose/
traits.rs
