structured_cms/
provider.rs

1//! Selected-provider identities and distinct raw versus finalized-prehash inputs.
2//!
3//! Digest execution is the shared [`structured_asn1::digest::Digest`]
4//! contract; ASN.1 digest identifiers resolve through
5//! [`structured_pkix::algorithm::digest`].
6
7use crate::Octets;
8use core::cmp::Ordering;
9use structured_asn1::digest::Resolution;
10use structured_asn1::memory::Work;
11use structured_asn1::{Encoding, Reader, Span};
12use structured_pkix::AlgorithmIdentifier;
13use structured_pkix::algorithm::digest::{self as asn_digest, Algorithm, AsnDigest};
14use structured_pkix::path::WorkingKey;
15mod session;
16pub use session::ProviderSession;
17
18pub(crate) fn require_instance<P>(_: &P, field: &'static str, at: u64) -> crate::Result<()> {
19    // Distinct ZST objects may have the same address. Their adapters must use
20    // the explicit nonzero ProviderSession owner, not an invented object ID.
21    // This constant condition is removed for ordinary monomorphized adapters.
22    if core::mem::size_of::<P>() == 0 {
23        return Err(crate::Error::schema(
24            crate::ErrorCode::ProviderMismatch,
25            field,
26            at,
27        ));
28    }
29    Ok(())
30}
31
32/// Digest algorithms supplied by ESS schema without an encoded identifier.
33/// These select identity, not a product policy permission or an engine fallback.
34#[derive(Debug, Clone, Copy, PartialEq, Eq)]
35pub enum ImpliedDigest {
36    /// `ESSCertID` Hash is SHA-1 (RFC2634 §5.4.1).
37    EssSha1,
38    /// Omitted `ESSCertIDv2` hashAlgorithm is SHA-256 with absent parameters
39    /// (RFC5035 §4, corrected certHash description in verified erratum2364).
40    EssV2Sha256,
41}
42
43/// Original written algorithm or a normative schema-supplied identity.
44///
45/// Implied inputs have no encoded `AlgorithmIdentifier` and no parameter TLV.
46/// A written unsupported/malformed identifier must never become an implied
47/// default. The enclosing field/span locate the implied identity with real
48/// document provenance, without synthesizing bytes or a new Parser.
49#[derive(Debug, Clone, Copy)]
50pub enum DigestAlgorithm<'a> {
51    /// The complete original identifier, encoding and parameter provenance.
52    Written(AlgorithmIdentifier<'a>),
53    /// A schema default/mandatory identity without an original identifier TLV.
54    Implied {
55        /// Identity selected by the ESS schema, with no implicit NULL fallback.
56        algorithm: ImpliedDigest,
57        /// Original enclosing ESS field.
58        field: &'static str,
59        /// Original enclosing ESS identifier span.
60        span: Span,
61    },
62}
63
64impl ImpliedDigest {
65    /// The algorithm the ESS schema selects.
66    #[must_use]
67    pub const fn algorithm(self) -> Algorithm {
68        match self {
69            Self::EssSha1 => Algorithm::Sha1,
70            Self::EssV2Sha256 => Algorithm::Sha256,
71        }
72    }
73}
74
75/// Resolves a written identifier through the shared ASN.1 resolver, under the
76/// encoding of the document it came from, or an implied ESS algorithm
77/// directly, then asks the provider for its identity.
78pub(crate) fn resolve_digest<'a, P: AsnDigest<'a>>(
79    provider: &P,
80    algorithm: DigestAlgorithm<'_>,
81    parent: &Reader<'_>,
82) -> crate::Result<Resolution<P::Identity>> {
83    match algorithm {
84        DigestAlgorithm::Written(identifier) => {
85            asn_digest::resolve(provider, &identifier, &parent.execution())
86                .map_err(crate::Error::pkix)
87        }
88        DigestAlgorithm::Implied { algorithm, .. } => {
89            Ok(asn_digest::supported(provider, algorithm.algorithm()))
90        }
91    }
92}
93
94/// A cryptographic signature answer after complete input processing.
95#[derive(Debug, Clone, Copy, PartialEq, Eq)]
96pub enum SignatureAnswer {
97    /// Signature arithmetic accepted the exact selected input and key.
98    Valid,
99    /// Signature arithmetic rejected that input/key, independently of resources.
100    Invalid,
101}
102
103/// Fully resolved signature input contract; raw never silently becomes prehash.
104#[derive(Debug)]
105pub enum SignatureMode<T> {
106    /// Original logical message octets, as required by `PureEdDSA` (RFC8419 §3).
107    Raw(T),
108    /// One finalized digest with a typed, fully resolved identity.
109    Prehashed(T),
110}
111
112/// A finalized output and its complete algorithm identity, without a cloneable state.
113#[derive(Debug)]
114pub struct Finalized<'p, P, I, O> {
115    provider: &'p P,
116    identity: I,
117    output: O,
118}
119
120/// A finalized prehash with independent short identity/output borrows.
121///
122/// Only common processing constructs this view from a completed state bound
123/// to the same resolved identity/provider. Byte width alone never establishes
124/// that provenance. There is no public arbitrary digest-plus-OID constructor.
125#[derive(Debug)]
126pub struct Prehash<'i, 'o, P, I> {
127    provider: &'i P,
128    identity: &'i I,
129    bytes: &'o [u8],
130}
131
132/// A finished digest: the provider's own output and identity, and the
133/// instance that produced them. Only common processing constructs it, from a
134/// state it completed; there is no constructor from arbitrary bytes.
135#[derive(Debug)]
136pub struct Finished<'v, P, I, O> {
137    provider: &'v P,
138    identity: &'v I,
139    output: &'v O,
140}
141
142// Only shared references: copying needs no bound on the referenced types.
143impl<P, I, O> Clone for Finished<'_, P, I, O> {
144    fn clone(&self) -> Self {
145        *self
146    }
147}
148impl<P, I, O> Copy for Finished<'_, P, I, O> {}
149
150impl<'v, P, I, O: AsRef<[u8]>> Finished<'v, P, I, O> {
151    pub(crate) fn new(provider: &'v P, identity: &'v I, output: &'v O) -> Self {
152        Self {
153            provider,
154            identity,
155            output,
156        }
157    }
158    /// Whether the supplied instance actually completed this output.
159    #[must_use]
160    pub fn from_provider(&self, provider: &P) -> bool {
161        core::ptr::eq(self.provider, provider)
162    }
163    /// Full selected-provider algorithm identity.
164    #[must_use]
165    pub fn identity(&self) -> &'v I {
166        self.identity
167    }
168    /// The provider's own finished output.
169    #[must_use]
170    pub fn output(&self) -> &'v O {
171        self.output
172    }
173}
174
175impl<'i, 'o, P, I> Prehash<'i, 'o, P, I> {
176    pub(crate) fn new(provider: &'i P, identity: &'i I, bytes: &'o [u8]) -> Self {
177        Self {
178            provider,
179            identity,
180            bytes,
181        }
182    }
183    /// Whether the supplied instance actually completed this finalized input.
184    #[must_use]
185    pub fn from_provider(&self, provider: &P) -> bool {
186        core::ptr::eq(self.provider, provider)
187    }
188    /// Full selected-provider algorithm identity, including parameters/defaults.
189    #[must_use]
190    pub fn identity(&self) -> &'i I {
191        self.identity
192    }
193
194    /// Original finalized output bytes; accessing them performs no new hashing.
195    #[must_use]
196    pub fn as_bytes(&self) -> &'o [u8] {
197        self.bytes
198    }
199}
200
201impl<'p, P, I, O: AsRef<[u8]>> Finalized<'p, P, I, O> {
202    /// Resolved identity, including parameters and output-length semantics.
203    #[must_use]
204    pub fn identity(&self) -> &I {
205        &self.identity
206    }
207    /// Borrowed final output; providers must implement this as constant-time access.
208    #[must_use]
209    pub fn as_bytes(&self) -> &[u8] {
210        self.output.as_ref()
211    }
212
213    /// Borrows a typed prehash without cloning identity, state or output.
214    #[must_use]
215    pub fn prehash(&self) -> Prehash<'_, '_, P, I> {
216        Prehash::new(self.provider, &self.identity, self.output.as_ref())
217    }
218
219    /// Borrows the provider's own output for its comparison, with provenance.
220    #[must_use]
221    pub fn finished(&self) -> Finished<'_, P, I, O> {
222        Finished {
223            provider: self.provider,
224            identity: &self.identity,
225            output: &self.output,
226        }
227    }
228
229    pub(crate) fn new(provider: &'p P, identity: I, output: O) -> Self {
230        Self {
231            provider,
232            identity,
233            output,
234        }
235    }
236}
237
238/// Signature operations that stay bound to the same selected provider and key.
239///
240/// Digest execution and identities come from the provider's
241/// [`structured_asn1::digest::Digest`] and [`AsnDigest`] implementations; CMS
242/// payload message-digest, ESS certificate hashes and TSP imprints all run
243/// through them with their distinct original covered inputs.
244///
245/// The effective key retains its original SPKI and inherited parameters.
246/// Resolution validates key/algorithm compatibility before raw initialization
247/// or payload I/O. A contiguous-only backend may explicitly buffer with full
248/// admission in its adapter, or report unsupported; it cannot downgrade raw.
249///
250/// Common processing borrows a stable nonzero-sized selection owner. Ordinary
251/// adapters containing engine/context references already satisfy this. Wrap a
252/// zero-sized stateless adapter in [`ProviderSession`] before using common
253/// processing; otherwise it returns a processing `ProviderMismatch` before
254/// dispatch. Distinct ZST addresses cannot supply instance provenance.
255pub trait SignatureProvider<'a>: AsnDigest<'a> + Sized {
256    /// Fully resolved signature identity, including algorithm-specific defaults.
257    type SignatureIdentity;
258    /// Raw verification state, initialized with original signature/key first.
259    type RawState;
260
261    /// Chooses raw versus prehashed only after complete algorithm/key resolution.
262    fn resolve_signature(
263        &'a self,
264        identifier: AlgorithmIdentifier<'a>,
265        digest: &Self::Identity,
266        key: WorkingKey<'a>,
267        encoding: Encoding,
268        parent: &Reader<'a>,
269    ) -> core::result::Result<Resolution<SignatureMode<Self::SignatureIdentity>>, Self::Error>;
270    /// Semantic signature/default comparison for protected versus outer identifiers.
271    fn compare_signature<W: Work>(
272        &self,
273        left: &Self::SignatureIdentity,
274        right: &Self::SignatureIdentity,
275        execution: &W,
276    ) -> core::result::Result<Ordering, Self::Error>;
277    /// Starts the raw challenge with the original signature and effective key.
278    fn start_raw<W: Work>(
279        &'a self,
280        identity: &Self::SignatureIdentity,
281        key: WorkingKey<'a>,
282        signature: &'a Octets<'a>,
283        execution: &W,
284    ) -> core::result::Result<Self::RawState, Self::Error>;
285    /// Admits and processes original raw message chunks, never digest bytes.
286    fn update_raw<W: Work>(
287        &self,
288        state: &mut Self::RawState,
289        bytes: &[u8],
290        execution: &W,
291    ) -> core::result::Result<(), Self::Error>;
292    /// Completes a raw signature only after successful complete source EOF.
293    fn finish_raw<W: Work>(
294        &self,
295        state: Self::RawState,
296        execution: &W,
297    ) -> core::result::Result<SignatureAnswer, Self::Error>;
298    /// Verifies one borrowed finalized digest with its full identity; no rehash.
299    fn verify_prehashed<W: Work>(
300        &'a self,
301        identity: &Self::SignatureIdentity,
302        key: WorkingKey<'a>,
303        signature: &Octets<'a>,
304        digest: Prehash<'_, '_, Self, Self::Identity>,
305        execution: &W,
306    ) -> core::result::Result<SignatureAnswer, Self::Error>;
307}
structured_cms/provider.rs

structured_cms/
provider.rs
