structured_pkix/ocsp/
evidence.rs

1//! Compose signature/issuer scope with requested target, extension and time facts.
2
3use super::{
4    ExtensionProcessing, Lookup, NonceBinding, RequestNonce, ScopedResponse, SingleResponse,
5    UpdateWindow,
6};
7use crate::algorithm::digest::AsnDigest;
8use crate::error::{CallbackResult, Result};
9use crate::temporal::{LeapTable, Reading};
10use crate::{Certificate, Error};
11use structured_asn1::memory::{Memory, MemoryError, Work};
12use structured_asn1::{Oid, Span};
13
14/// Actual caller request facts, never inferred from the received response.
15pub struct Request<'p, 'a> {
16    /// Certificate identified by the actual request and authenticated issuer path.
17    pub target: &'p Certificate<'a>,
18    /// Actual sent nonce, not a newly generated replacement.
19    pub nonce: Option<RequestNonce<'p>>,
20    /// Optional expected exact signer certificate chosen by the caller. Absent
21    /// binding is reported explicitly rather than counted as a match.
22    pub intended_signer: Option<&'p Certificate<'a>>,
23}
24
25/// Current temporal/resource facts; maximum age and clock-skew policy stay outside.
26pub struct Evaluation<'p, E: Work = Memory> {
27    /// Actual caller-supplied current label, retaining subnanosecond precision.
28    pub now: Reading,
29    /// Caller-authenticated UTC correction evidence and explicit coverage.
30    pub utc: &'p LeapTable<'p>,
31    /// Current operation's shared work and storage domain.
32    pub execution: &'p E,
33}
34
35/// Whether this evidence is bound to the caller's exact intended signer input.
36#[derive(Debug, Clone, Copy, PartialEq, Eq)]
37pub enum RecipientBinding {
38    /// Caller did not supply an exact signer; no such claim is made.
39    NotSpecified,
40    /// Authenticated actual signer matches the supplied exact certificate.
41    Matches,
42}
43
44/// Composed original evidence, still not final application acceptance. Read its
45/// authority source for pending delegate revocation, and apply nonce, maximum
46/// age, recipient and time-uncertainty policy before interpreting status.
47#[derive(Debug, Clone, Copy)]
48pub struct Evidence<'r, 'a> {
49    source: ScopedResponse<'r, 'a>,
50    assertion: &'r SingleResponse<'a>,
51    window: UpdateWindow,
52    nonce: NonceBinding,
53    recipient: RecipientBinding,
54    revocation_time: Option<crate::time::Relation>,
55}
56
57impl<'r, 'a> Evidence<'r, 'a> {
58    /// Signature and explicit issuer-scope provenance.
59    #[must_use]
60    pub fn source(self) -> ScopedResponse<'r, 'a> {
61        self.source
62    }
63    /// Selected original assertion, with every uninterpreted noncritical value.
64    #[must_use]
65    pub fn assertion(self) -> &'r SingleResponse<'a> {
66        self.assertion
67    }
68    /// Update-window relation, not a maximum-age decision.
69    #[must_use]
70    pub fn window(self) -> UpdateWindow {
71        self.window
72    }
73    /// Actual request/response nonce relation.
74    #[must_use]
75    pub fn nonce(self) -> NonceBinding {
76        self.nonce
77    }
78    /// Exact intended signer binding, when requested.
79    #[must_use]
80    pub fn recipient(self) -> RecipientBinding {
81        self.recipient
82    }
83
84    /// UTC-qualified recorded revocation time when this assertion is revoked.
85    #[must_use]
86    pub fn revocation_time(self) -> Option<crate::time::Relation> {
87        self.revocation_time
88    }
89}
90
91/// Target processing outcome, without turning missing/unsupported into Good.
92#[derive(Debug, Clone, Copy)]
93#[expect(
94    clippy::large_enum_variant,
95    reason = "retain source/key/time facts by value rather than allocate a box per target merely to discriminate the result"
96)]
97pub enum TargetEvidence<'r, 'a> {
98    /// Identity and supported extension semantics completed; policy facts remain.
99    Evidence(Evidence<'r, 'a>),
100    /// Actual signer differs from the caller's intended exact signer.
101    UnexpectedSigner,
102    /// Identity lookup did not yield one usable assertion.
103    Lookup(Lookup<'r, 'a>),
104    /// Response-wide or selected-assertion critical demand cannot be processed.
105    UnsupportedCritical {
106        /// Original unsupported demand identifier.
107        kind: Oid<'a>,
108        /// Original location.
109        span: Span,
110    },
111}
112
113/// Complete target processing together with the original requested certificate.
114/// Target and response lifetimes are independent; no temporary request,
115/// evaluation context, provider or execution wrapper is retained.
116#[derive(Debug)]
117pub struct TargetReading<'target, 'request, 'response, 'source> {
118    target: &'target Certificate<'request>,
119    evaluated_at: Reading,
120    outcome: TargetEvidence<'response, 'source>,
121}
122
123impl<'target, 'request, 'response, 'source> TargetReading<'target, 'request, 'response, 'source> {
124    /// Original actual target, not another certificate with a matching hint.
125    #[must_use]
126    pub fn target(&self) -> &'target Certificate<'request> {
127        self.target
128    }
129    /// Exact label used by the same update-window/revocation-time processing.
130    #[must_use]
131    pub fn evaluated_at(&self) -> Reading {
132        self.evaluated_at
133    }
134    /// Original complete result, including lookup and critical-demand failures.
135    #[must_use]
136    pub fn outcome(&self) -> &TargetEvidence<'response, 'source> {
137        &self.outcome
138    }
139    /// Bind established mechanism facts to the target used by this invocation.
140    /// Status, temporal uncertainty, nonce and delegated-responder requirements
141    /// remain exactly as reported; this does not mean the status is Good.
142    #[must_use]
143    pub fn evidence(&self) -> Option<BoundEvidence<'target, 'request, 'response, 'source>> {
144        match self.outcome {
145            TargetEvidence::Evidence(evidence) => Some(BoundEvidence {
146                target: self.target,
147                evaluated_at: self.evaluated_at,
148                evidence,
149            }),
150            _ => None,
151        }
152    }
153    /// Move the original outcome when the caller does not retain target binding.
154    #[must_use]
155    pub fn into_outcome(self) -> TargetEvidence<'response, 'source> {
156        self.outcome
157    }
158}
159
160/// Privately bound target and facts from the same completed common evaluation.
161/// This association cannot be created from an unrelated certificate and result.
162#[derive(Debug, Clone, Copy)]
163pub struct BoundEvidence<'target, 'request, 'response, 'source> {
164    target: &'target Certificate<'request>,
165    evaluated_at: Reading,
166    evidence: Evidence<'response, 'source>,
167}
168
169impl<'target, 'request, 'response, 'source> BoundEvidence<'target, 'request, 'response, 'source> {
170    /// Original requested certificate whose identity the common kernel matched.
171    #[must_use]
172    pub fn target(self) -> &'target Certificate<'request> {
173        self.target
174    }
175    /// Original evaluation label; the caller cannot relabel status in time.
176    #[must_use]
177    pub fn evaluated_at(self) -> Reading {
178        self.evaluated_at
179    }
180    /// Same original mechanism facts, without repeating identity hashes.
181    #[must_use]
182    pub fn evidence(self) -> Evidence<'response, 'source> {
183        self.evidence
184    }
185}
186
187fn exact_signer<E: Work>(
188    left: &Certificate<'_>,
189    right: &Certificate<'_>,
190    execution: &E,
191    at: u64,
192) -> Result<bool> {
193    let left = left.as_bytes();
194    let right = right.as_bytes();
195    let work = u64::try_from(left.len().max(right.len()))
196        .ok()
197        .and_then(|n| n.checked_mul(2))
198        .and_then(|n| n.checked_add(1))
199        .ok_or_else(|| Error::resource(MemoryError::WorkExceeded, "ocspResponse.recipient", at))?;
200    execution
201        .charge_work(work)
202        .map_err(|reason| Error::resource(reason, "ocspResponse.recipient", at))?;
203    Ok(left == right)
204}
205
206impl<'r, 'a> ScopedResponse<'r, 'a> {
207    /// Run the same complete target-processing kernel once while retaining its
208    /// original requested certificate. No hashing, parsing or allocation is
209    /// repeated to recover provenance later. Failures retain their original
210    /// result/cause; no positive target binding is returned for a lookup failure.
211    pub fn evaluate_with_target<'target, 'request, 'd, D: AsnDigest<'d> + ?Sized, E: Work>(
212        self,
213        request: &Request<'target, 'request>,
214        time: &Evaluation<'_, E>,
215        digest: &'d D,
216    ) -> CallbackResult<TargetReading<'target, 'request, 'r, 'a>, D::Error> {
217        let outcome = self.evaluate(request, time, digest)?;
218        Ok(TargetReading {
219            target: request.target,
220            evaluated_at: time.now,
221            outcome,
222        })
223    }
224
225    /// Evaluate the actual request against this issuer-scoped signed response.
226    /// RFC6960 §3.2 requires identity, signer, authorization and temporal checks;
227    /// this operation composes mechanism facts without choosing caller policy.
228    /// <https://www.rfc-editor.org/rfc/rfc6960#section-3.2>
229    pub fn evaluate<'d, D: AsnDigest<'d> + ?Sized, E: Work>(
230        self,
231        request: &Request<'_, '_>,
232        time: &Evaluation<'_, E>,
233        digest: &'d D,
234    ) -> CallbackResult<TargetEvidence<'r, 'a>, D::Error> {
235        let execution = time.execution;
236        let response = self.signed().response();
237        let recipient = match request.intended_signer {
238            None => RecipientBinding::NotSpecified,
239            Some(expected) => {
240                if !exact_signer(
241                    self.signed().signer(),
242                    expected,
243                    execution,
244                    response.span().start,
245                )? {
246                    return Ok(TargetEvidence::UnexpectedSigner);
247                }
248                RecipientBinding::Matches
249            }
250        };
251        let processed = response.process_extensions(execution)?;
252        if let ExtensionProcessing::Unsupported { kind, span } = processed.processing {
253            return Ok(TargetEvidence::UnsupportedCritical { kind, span });
254        }
255        let assertion = match self.find(request.target, digest, execution)? {
256            Lookup::Found(assertion) => assertion,
257            outcome => return Ok(TargetEvidence::Lookup(outcome)),
258        };
259        if let ExtensionProcessing::Unsupported { kind, span } =
260            assertion.check_extensions(execution)?
261        {
262            return Ok(TargetEvidence::UnsupportedCritical { kind, span });
263        }
264        let nonce = super::nonce::bind(
265            request.nonce,
266            processed.nonce,
267            execution,
268            response.span().start,
269        )?;
270        let window = assertion.update_window(time.now, time.utc, execution)?;
271        let revocation_time = assertion.revocation_relation(time.now, time.utc, execution)?;
272        Ok(TargetEvidence::Evidence(Evidence {
273            source: self,
274            assertion,
275            nonce,
276            window,
277            recipient,
278            revocation_time,
279        }))
280    }
281}
282
283#[cfg(test)]
284mod tests;
structured_pkix/ocsp/evidence.rs

structured_pkix/ocsp/
evidence.rs
