structured_pkix/ocsp/
authentication.rs

1//! Actual signer binding and response signature authentication.
2
3use super::{BasicResponse, Digest, DigestAlgorithm, ResponderId};
4use crate::path::{Verified, Verify, WorkingKey};
5use crate::{Certificate, Error};
6use core::fmt;
7use structured_asn1::memory::{Memory, MemoryError};
8
9/// Failure to execute authentication, retaining the originating capability.
10#[derive(Debug)]
11pub enum SignatureError<V, D> {
12    /// Located shared processing/resource failure.
13    Processing(Error),
14    /// Signature provider failure, including its resource or policy error.
15    Verification(V),
16    /// Digest provider failure, including its resource or policy error.
17    Digest(D),
18}
19
20impl<V, D> From<Error> for SignatureError<V, D> {
21    fn from(error: Error) -> Self {
22        Self::Processing(error)
23    }
24}
25
26impl<V: fmt::Display, D: fmt::Display> fmt::Display for SignatureError<V, D> {
27    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
28        match self {
29            Self::Processing(error) => error.fmt(formatter),
30            Self::Verification(error) => write!(formatter, "signature verifier: {error}"),
31            Self::Digest(error) => write!(formatter, "digest provider: {error}"),
32        }
33    }
34}
35
36#[cfg(feature = "std")]
37impl<V: std::error::Error + 'static, D: std::error::Error + 'static> std::error::Error
38    for SignatureError<V, D>
39{
40    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
41        match self {
42            Self::Processing(error) => Some(error),
43            Self::Verification(error) => Some(error),
44            Self::Digest(error) => Some(error),
45        }
46    }
47}
48
49/// Completed negative binding/signature result, not an execution failure.
50#[derive(Debug, Clone, Copy, PartialEq, Eq)]
51pub enum SignatureFailure {
52    /// Effective key does not belong to the supplied signer's original SPKI.
53    KeyBinding,
54    /// `ResponderID` does not identify the actual supplied signer.
55    ResponderIdentity,
56    /// Provider resolved protocol-imposed SHA-1 with a contradicting width.
57    DigestWidth,
58    /// The completed signature verification rejected the signature.
59    Signature,
60}
61
62/// Original response authenticated by its actual signer. This proves neither
63/// signer authorization for a target issuer nor freshness or request binding.
64#[derive(Debug, Clone, Copy)]
65pub struct SignedResponse<'r, 'a> {
66    response: &'r BasicResponse<'a>,
67    signer: &'r Certificate<'a>,
68    key: WorkingKey<'a>,
69}
70
71impl<'r, 'a> SignedResponse<'r, 'a> {
72    /// Original signed response, retaining every assertion and extension.
73    #[must_use]
74    pub fn response(self) -> &'r BasicResponse<'a> {
75        self.response
76    }
77    /// Actual certificate whose subject/key matched `ResponderID`.
78    #[must_use]
79    pub fn signer(self) -> &'r Certificate<'a> {
80        self.signer
81    }
82    /// Effective key bound to that certificate's original SPKI.
83    #[must_use]
84    pub fn key(self) -> WorkingKey<'a> {
85        self.key
86    }
87}
88
89/// Signature authentication outcome with unsupported capabilities separate.
90#[derive(Debug)]
91pub enum SignatureAuthentication<'r, 'a> {
92    /// Signer identity and signature established; authorization remains separate.
93    Signed(SignedResponse<'r, 'a>),
94    /// Completed semantic rejection.
95    Rejected(SignatureFailure),
96    /// Protocol-imposed SHA-1 cannot be supplied by this provider/policy.
97    UnsupportedDigest,
98    /// Signature algorithm/effective key is unsupported by this verifier.
99    UnsupportedSignature,
100}
101
102impl<'a> BasicResponse<'a> {
103    /// Authenticate exact `ResponseData` with the actual signer's bound key.
104    /// Included certificates are candidates only. RFC6960 §§4.2.2.2–4.2.2.3
105    /// require authorization and status validity beyond this signature fact.
106    /// <https://www.rfc-editor.org/rfc/rfc6960#section-4.2.2.2>
107    pub fn authenticate_signature<'r, V: Verify, D: Digest>(
108        &'r self,
109        signer: &'r Certificate<'a>,
110        key: WorkingKey<'a>,
111        verifier: &V,
112        digest: &D,
113        execution: &Memory,
114    ) -> core::result::Result<SignatureAuthentication<'r, 'a>, SignatureError<V::Error, D::Error>>
115    {
116        const FIELD: &str = "ocspResponse.signature";
117        let charge = |work| {
118            execution
119                .charge_work(work)
120                .map_err(|reason| Error::resource(reason, FIELD, self.span.start))
121        };
122        let encoded = key.key().as_bytes();
123        let actual = signer.tbs().public_key().as_bytes();
124        let work = u64::try_from(encoded.len().max(actual.len()))
125            .ok()
126            .and_then(|n| n.checked_mul(2))
127            .and_then(|n| n.checked_add(1))
128            .ok_or_else(|| Error::resource(MemoryError::WorkExceeded, FIELD, self.span.start))?;
129        charge(work)?;
130        if encoded != actual {
131            return Ok(SignatureAuthentication::Rejected(
132                SignatureFailure::KeyBinding,
133            ));
134        }
135        let matches = match &self.responder {
136            ResponderId::Name(name) => name.matches(signer.tbs().subject(), execution)?,
137            ResponderId::KeyHash(expected) => {
138                charge(1)?;
139                let Some(resolved) = digest
140                    .resolve(DigestAlgorithm::Sha1, execution)
141                    .map_err(SignatureError::Digest)?
142                else {
143                    return Ok(SignatureAuthentication::UnsupportedDigest);
144                };
145                // RFC6960 §4.2.2.2 imposes SHA-1 and exactly 20 bytes here.
146                // Never hash malformed width or substitute a signature hash.
147                if resolved.width.get() != 20 || expected.len() != 20 {
148                    return Ok(SignatureAuthentication::Rejected(
149                        SignatureFailure::DigestWidth,
150                    ));
151                }
152                digest
153                    .matches(
154                        resolved.handle,
155                        key.key().key().as_bytes(),
156                        expected,
157                        execution,
158                    )
159                    .map_err(SignatureError::Digest)?
160            }
161        };
162        if !matches {
163            return Ok(SignatureAuthentication::Rejected(
164                SignatureFailure::ResponderIdentity,
165            ));
166        }
167        charge(1)?;
168        match verifier
169            .verify(&self.algorithm, key, self.signed, self.signature, execution)
170            .map_err(SignatureError::Verification)?
171        {
172            Verified::Yes => Ok(SignatureAuthentication::Signed(SignedResponse {
173                response: self,
174                signer,
175                key,
176            })),
177            Verified::No => Ok(SignatureAuthentication::Rejected(
178                SignatureFailure::Signature,
179            )),
180            Verified::Unsupported => Ok(SignatureAuthentication::UnsupportedSignature),
181        }
182    }
183}
184
185#[cfg(test)]
186mod tests {
187    use super::*;
188    use crate::fixtures::{CertificateParts, bits, context, extension, octets, seq, tlv};
189    use core::{cell::Cell, num::NonZeroUsize};
190    use structured_asn1::{BitString, Parser};
191
192    struct Provider<'a> {
193        key: &'a [u8],
194        signed: &'a [u8],
195        hashes: Cell<usize>,
196        signatures: Cell<usize>,
197        width: usize,
198        digest_answer: Option<bool>,
199        signature_answer: Verified,
200        failure: bool,
201    }
202    impl Digest for Provider<'_> {
203        type Handle = ();
204        type Error = &'static str;
205        fn resolve(
206            &self,
207            algorithm: DigestAlgorithm<'_>,
208            _: &Memory,
209        ) -> Result<Option<super::super::ResolvedDigest<()>>, Self::Error> {
210            assert!(matches!(algorithm, DigestAlgorithm::Sha1));
211            if self.failure {
212                return Err("digest refusal");
213            }
214            Ok(self.digest_answer.map(|_| super::super::ResolvedDigest {
215                handle: (),
216                width: NonZeroUsize::new(self.width).unwrap(),
217            }))
218        }
219        fn matches(
220            &self,
221            (): (),
222            input: &[u8],
223            expected: &[u8],
224            _: &Memory,
225        ) -> Result<bool, Self::Error> {
226            self.hashes.set(self.hashes.get() + 1);
227            assert_eq!(input.as_ptr(), self.key.as_ptr());
228            assert_eq!(input, self.key);
229            assert_eq!(expected, &[0x33; 20]);
230            Ok(self.digest_answer.unwrap())
231        }
232    }
233    impl Verify for Provider<'_> {
234        type Error = &'static str;
235        fn verify(
236            &self,
237            _: &crate::AlgorithmIdentifier<'_>,
238            _: WorkingKey<'_>,
239            signed: &[u8],
240            _: BitString<'_>,
241            _: &Memory,
242        ) -> Result<Verified, Self::Error> {
243            self.signatures.set(self.signatures.get() + 1);
244            assert_eq!(signed.as_ptr(), self.signed.as_ptr());
245            assert_eq!(signed, self.signed);
246            Ok(self.signature_answer)
247        }
248    }
249
250    #[test]
251    fn issuer_binding_enforces_object_signing_key_usage() {
252        // RFC5280 4.2.1.3: certificate/CRL signing bits cannot authorize an
253        // OCSP object signature; either object-signing bit is sufficient.
254        for (usage, permitted) in [
255            (None, true),
256            (Some([7, 0x80]), true),
257            (Some([6, 0x40]), true),
258            (Some([1, 0x06]), false),
259            (Some([5, 0x20]), false),
260        ] {
261            let certificate_bytes = CertificateParts {
262                extensions: usage
263                    .map(|value| seq(&[extension(crate::oid::KEY_USAGE, true, &tlv(3, &value))])),
264                ..CertificateParts::default()
265            }
266            .build();
267            let execution = crate::fixtures::memory();
268            let parser = Parser::der(execution.clone());
269            let issuer = Certificate::read(&parser, &certificate_bytes, 100).unwrap();
270            let algorithm = issuer.signature_algorithm().as_bytes();
271            let timestamp = tlv(24, b"20261012120000Z");
272            let id = seq(&[
273                algorithm.to_vec(),
274                octets(&[0x11; 20]),
275                octets(&[0x22; 20]),
276                tlv(2, &[1]),
277            ]);
278            let single = seq(&[id, tlv(0x80, &[]), timestamp.clone()]);
279            let data = seq(&[
280                context(2, &[octets(&[0x33; 20])]),
281                timestamp,
282                seq(&[single]),
283            ]);
284            let bytes = seq(&[data, algorithm.to_vec(), bits(&[0xab])]);
285            let mut reader = parser.read(&bytes, 700).unwrap();
286            let root = reader.next_element().unwrap().unwrap();
287            let response = super::super::read_basic(&reader, &root).unwrap();
288            let key = WorkingKey::standing(issuer.tbs().public_key());
289            let provider = Provider {
290                key: issuer.tbs().public_key().key().as_bytes(),
291                signed: response.signed_bytes(),
292                hashes: Cell::new(0),
293                signatures: Cell::new(0),
294                width: 20,
295                digest_answer: Some(true),
296                signature_answer: Verified::Yes,
297                failure: false,
298            };
299            let SignatureAuthentication::Signed(signed) = response
300                .authenticate_signature(&issuer, key, &provider, &provider, &execution)
301                .unwrap()
302            else {
303                panic!("signature fixture rejected");
304            };
305            let result = signed.bind_issuer(&issuer, key, &execution).unwrap();
306            assert_eq!(
307                matches!(result, super::super::AuthorityBinding::Bound(_)),
308                permitted
309            );
310            if !permitted {
311                assert!(matches!(
312                    result,
313                    super::super::AuthorityBinding::Rejected(
314                        super::super::AuthorityFailure::KeyUsage
315                    )
316                ));
317            }
318            assert_eq!(provider.signatures.get(), 1);
319        }
320    }
321
322    #[test]
323    fn actual_signer_precedes_hash_and_original_response_data_verification() {
324        // This observes dispatch/provenance only, not cryptographic correctness.
325        // Wrong SPKI, responder identity or SHA1 width must stop before verify.
326        let certificate_bytes = CertificateParts::default().build();
327        let execution = crate::fixtures::memory();
328        let parser = Parser::der(execution.clone());
329        let signer = Certificate::read(&parser, &certificate_bytes, 100).unwrap();
330        let algorithm = signer.signature_algorithm().as_bytes();
331        let timestamp = tlv(24, b"20261012120000Z");
332        let id = seq(&[
333            algorithm.to_vec(),
334            octets(&[0x11; 20]),
335            octets(&[0x22; 20]),
336            tlv(2, &[1]),
337        ]);
338        let single = seq(&[id, tlv(0x80, &[]), timestamp.clone()]);
339        let data = seq(&[
340            context(2, &[octets(&[0x33; 20])]),
341            timestamp,
342            seq(&[single]),
343        ]);
344        let bytes = seq(&[data, algorithm.to_vec(), bits(&[0xab])]);
345        let mut reader = parser.read(&bytes, 700).unwrap();
346        let element = reader.next_element().unwrap().unwrap();
347        let response = super::super::read_basic(&reader, &element).unwrap();
348        let key = WorkingKey::standing(signer.tbs().public_key());
349        let mut provider = Provider {
350            key: signer.tbs().public_key().key().as_bytes(),
351            signed: response.signed_bytes(),
352            hashes: Cell::new(0),
353            signatures: Cell::new(0),
354            width: 20,
355            digest_answer: Some(true),
356            signature_answer: Verified::Yes,
357            failure: false,
358        };
359        let retained = execution.used();
360        let SignatureAuthentication::Signed(proof) = response
361            .authenticate_signature(&signer, key, &provider, &provider, &execution)
362            .unwrap()
363        else {
364            panic!("signature not authenticated");
365        };
366        assert!(core::ptr::eq(proof.response(), &raw const response));
367        assert!(core::ptr::eq(proof.signer(), &raw const signer));
368        assert_eq!(provider.signatures.get(), 1);
369        assert_eq!(execution.used(), retained);
370        provider.signatures.set(0);
371        provider.width = 19;
372        assert!(matches!(
373            response
374                .authenticate_signature(&signer, key, &provider, &provider, &execution)
375                .unwrap(),
376            SignatureAuthentication::Rejected(SignatureFailure::DigestWidth)
377        ));
378        assert_eq!(provider.signatures.get(), 0);
379        provider.width = 20;
380        provider.digest_answer = Some(false);
381        assert!(matches!(
382            response
383                .authenticate_signature(&signer, key, &provider, &provider, &execution)
384                .unwrap(),
385            SignatureAuthentication::Rejected(SignatureFailure::ResponderIdentity)
386        ));
387        assert_eq!(provider.signatures.get(), 0);
388        provider.digest_answer = None;
389        assert!(matches!(
390            response
391                .authenticate_signature(&signer, key, &provider, &provider, &execution)
392                .unwrap(),
393            SignatureAuthentication::UnsupportedDigest
394        ));
395        provider.failure = true;
396        assert!(matches!(
397            response.authenticate_signature(&signer, key, &provider, &provider, &execution),
398            Err(SignatureError::Digest("digest refusal"))
399        ));
400        let unfunded = Memory::new(alloc::sync::Arc::new(
401            structured_asn1::memory::MemoryAccount::new(0, 0),
402        ));
403        assert!(
404            matches!(response.authenticate_signature(&signer, key, &provider, &provider, &unfunded), Err(SignatureError::Processing(error)) if error.is_resource() && error.offset() == 700)
405        );
406    }
407}
structured_pkix/ocsp/authentication.rs

structured_pkix/ocsp/
authentication.rs
