/rust/registry/src/index.crates.io-1949cf8c6b5b557f/rustls-0.23.46/src/webpki/verify.rs

Source
use alloc::vec::Vec;
use core::fmt;

use pki_types::{
    CertificateDer, ServerName, SignatureVerificationAlgorithm, SubjectPublicKeyInfoDer, UnixTime,
};

use super::anchors::RootCertStore;
use super::pki_error;
use crate::enums::SignatureScheme;
use crate::error::{Error, PeerMisbehaved};
use crate::verify::{DigitallySignedStruct, HandshakeSignatureValid};

/// Verify that the end-entity certificate `end_entity` is a valid server cert
/// and chains to at least one of the trust anchors in the `roots` [RootCertStore].
///
/// This function is primarily useful when building a custom certificate verifier. It
/// performs **no revocation checking**. Implementers must handle this themselves,
/// along with checking that the server certificate is valid for the subject name
/// being used (see [`verify_server_name`]).
///
/// `intermediates` contains all certificates other than `end_entity` that
/// were sent as part of the server's `Certificate` message. It is in the
/// same order that the server sent them and may be empty.
#[allow(dead_code)]
pub fn verify_server_cert_signed_by_trust_anchor(
    cert: &ParsedCertificate<'_>,
    roots: &RootCertStore,
    intermediates: &[CertificateDer<'_>],
    now: UnixTime,
    supported_algs: &[&dyn SignatureVerificationAlgorithm],
) -> Result<(), Error> {
    verify_server_cert_signed_by_trust_anchor_impl(
        cert,
        roots,
        intermediates,
        None, // No revocation checking supported with this API.
        now,
        supported_algs,
    )
}

/// Verify that the `end_entity` has an alternative name matching the `server_name`.
///
/// Note: this only verifies the name and should be used in conjunction with more verification
/// like [verify_server_cert_signed_by_trust_anchor]
pub fn verify_server_name(
    cert: &ParsedCertificate<'_>,
    server_name: &ServerName<'_>,
) -> Result<(), Error> {
    cert.0
        .verify_is_valid_for_subject_name(server_name)
        .map_err(pki_error)
}

/// Describes which `webpki` signature verification algorithms are supported and
/// how they map to TLS [`SignatureScheme`]s.
#[derive(Clone, Copy)]
#[allow(unreachable_pub)]
pub struct WebPkiSupportedAlgorithms {
    /// A list of all supported signature verification algorithms.
    ///
    /// Used for verifying certificate chains.
    ///
    /// The order of this list is not significant.
    pub all: &'static [&'static dyn SignatureVerificationAlgorithm],

    /// A mapping from TLS `SignatureScheme`s to matching webpki signature verification algorithms.
    ///
    /// This is one (`SignatureScheme`) to many ([`SignatureVerificationAlgorithm`]) because
    /// (depending on the protocol version) there is not necessary a 1-to-1 mapping.
    ///
    /// For TLS1.2, all `SignatureVerificationAlgorithm`s are tried in sequence.
    ///
    /// For TLS1.3, only the first is tried.
    ///
    /// The supported schemes in this mapping is communicated to the peer and the order is significant.
    /// The first mapping is our highest preference.
    pub mapping: &'static [(
        SignatureScheme,
        &'static [&'static dyn SignatureVerificationAlgorithm],
    )],
}

impl WebPkiSupportedAlgorithms {
    /// Return all the `scheme` items in `mapping`, maintaining order.
    pub fn supported_schemes(&self) -> Vec<SignatureScheme> {
        self.mapping
            .iter()
            .map(|item| item.0)
            .collect()
    }

    /// Return the first item in `mapping` that matches `scheme`.
    fn convert_scheme(
        &self,
        scheme: SignatureScheme,
    ) -> Result<&[&'static dyn SignatureVerificationAlgorithm], Error> {
        self.mapping
            .iter()
            .filter_map(|item| if item.0 == scheme { Some(item.1) } else { None })
            .next()
            .ok_or_else(|| PeerMisbehaved::SignedHandshakeWithUnadvertisedSigScheme.into())
    }

    /// Return `true` if all cryptography is FIPS-approved.
    pub fn fips(&self) -> bool {
        self.all.iter().all(|alg| alg.fips())
            && self
                .mapping
                .iter()
                .all(|item| item.1.iter().all(|alg| alg.fips()))
    }
}

impl fmt::Debug for WebPkiSupportedAlgorithms {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "WebPkiSupportedAlgorithms {{ all: [ .. ], mapping: ")?;
        f.debug_list()
            .entries(self.mapping.iter().map(|item| item.0))
            .finish()?;
        write!(f, " }}")
    }
}

/// Wrapper around internal representation of a parsed certificate.
///
/// This is used in order to avoid parsing twice when specifying custom verification
pub struct ParsedCertificate<'a>(pub(crate) webpki::EndEntityCert<'a>);

impl ParsedCertificate<'_> {
    /// Get the parsed certificate's SubjectPublicKeyInfo (SPKI)
    pub fn subject_public_key_info(&self) -> SubjectPublicKeyInfoDer<'static> {
        self.0.subject_public_key_info()
    }
}

impl<'a> TryFrom<&'a CertificateDer<'a>> for ParsedCertificate<'a> {
    type Error = Error;
    fn try_from(value: &'a CertificateDer<'a>) -> Result<Self, Self::Error> {
        webpki::EndEntityCert::try_from(value)
            .map_err(pki_error)
            .map(ParsedCertificate)
    }
}

/// Verify a message signature using the `cert` public key and any supported scheme.
///
/// This function verifies the `dss` signature over `message` using the subject public key from
/// `cert`. Since TLS 1.2 doesn't provide enough information to map the `dss.scheme` into a single
/// [`SignatureVerificationAlgorithm`], this function will map to several candidates and try each in
/// succession until one succeeds or we exhaust all candidates.
///
/// See [WebPkiSupportedAlgorithms::mapping] for more information.
pub fn verify_tls12_signature(
    message: &[u8],
    cert: &CertificateDer<'_>,
    dss: &DigitallySignedStruct,
    supported_schemes: &WebPkiSupportedAlgorithms,
) -> Result<HandshakeSignatureValid, Error> {
    if dss.scheme.algorithm().is_none() {
        return Err(PeerMisbehaved::SignedHandshakeWithUnadvertisedSigScheme.into());
    }

    let possible_algs = supported_schemes.convert_scheme(dss.scheme)?;
    let cert = webpki::EndEntityCert::try_from(cert).map_err(pki_error)?;

    let mut error = None;
    for alg in possible_algs {
        match cert.verify_signature(*alg, message, dss.signature()) {
            Err(err @ webpki::Error::UnsupportedSignatureAlgorithmForPublicKeyContext(_)) => {
                error = Some(err);
                continue;
            }
            Err(e) => return Err(pki_error(e)),
            Ok(()) => return Ok(HandshakeSignatureValid::assertion()),
        }
    }

    #[allow(deprecated)] // The `unwrap_or()` should be statically unreachable
    Err(pki_error(error.unwrap_or(
        webpki::Error::UnsupportedSignatureAlgorithmForPublicKey,
    )))
}

/// Verify a message signature using the `cert` public key and the first TLS 1.3 compatible
/// supported scheme.
///
/// This function verifies the `dss` signature over `message` using the subject public key from
/// `cert`. Unlike [verify_tls12_signature], this function only tries the first matching scheme. See
/// [WebPkiSupportedAlgorithms::mapping] for more information.
pub fn verify_tls13_signature(
    msg: &[u8],
    cert: &CertificateDer<'_>,
    dss: &DigitallySignedStruct,
    supported_schemes: &WebPkiSupportedAlgorithms,
) -> Result<HandshakeSignatureValid, Error> {
    if !dss.scheme.supported_in_tls13() {
        return Err(PeerMisbehaved::SignedHandshakeWithUnadvertisedSigScheme.into());
    }

    let alg = supported_schemes.convert_scheme(dss.scheme)?[0];

    let cert = webpki::EndEntityCert::try_from(cert).map_err(pki_error)?;

    cert.verify_signature(alg, msg, dss.signature())
        .map_err(pki_error)
        .map(|_| HandshakeSignatureValid::assertion())
}

/// Verify a message signature using a raw public key and the first TLS 1.3 compatible
/// supported scheme.
pub fn verify_tls13_signature_with_raw_key(
    msg: &[u8],
    spki: &SubjectPublicKeyInfoDer<'_>,
    dss: &DigitallySignedStruct,
    supported_schemes: &WebPkiSupportedAlgorithms,
) -> Result<HandshakeSignatureValid, Error> {
    if !dss.scheme.supported_in_tls13() {
        return Err(PeerMisbehaved::SignedHandshakeWithUnadvertisedSigScheme.into());
    }

    let raw_key = webpki::RawPublicKeyEntity::try_from(spki).map_err(pki_error)?;
    let alg = supported_schemes.convert_scheme(dss.scheme)?[0];

    raw_key
        .verify_signature(alg, msg, dss.signature())
        .map_err(pki_error)
        .map(|_| HandshakeSignatureValid::assertion())
}

/// Verify that the end-entity certificate `end_entity` is a valid server cert
/// and chains to at least one of the trust anchors in the `roots` [RootCertStore].
///
/// `intermediates` contains all certificates other than `end_entity` that
/// were sent as part of the server's `Certificate` message. It is in the
/// same order that the server sent them and may be empty.
///
/// `revocation` controls how revocation checking is performed, if at all.
///
/// This function exists to be used by [`verify_server_cert_signed_by_trust_anchor`],
/// and differs only in providing a `Option<webpki::RevocationOptions>` argument. We
/// can't include this argument in `verify_server_cert_signed_by_trust_anchor` because
/// it will leak the webpki types into Rustls' public API.
pub(crate) fn verify_server_cert_signed_by_trust_anchor_impl(
    cert: &ParsedCertificate<'_>,
    roots: &RootCertStore,
    intermediates: &[CertificateDer<'_>],
    revocation: Option<webpki::RevocationOptions<'_>>,
    now: UnixTime,
    supported_algs: &[&dyn SignatureVerificationAlgorithm],
) -> Result<(), Error> {
    let result = cert.0.verify_for_usage(
        supported_algs,
        &roots.roots,
        intermediates,
        now,
        webpki::KeyUsage::server_auth(),
        revocation,
        None,
    );
    match result {
        Ok(_) => Ok(()),
        Err(e) => Err(pki_error(e)),
    }
}

#[cfg(test)]
mod tests {
    use std::format;

    use super::*;

    #[test]
    fn certificate_debug() {
        assert_eq!(
            "CertificateDer(0x6162)",
            format!("{:?}", CertificateDer::from(b"ab".to_vec()))
        );
    }

    #[cfg(feature = "ring")]
    #[test]
    fn webpki_supported_algorithms_is_debug() {
        assert_eq!(
            "WebPkiSupportedAlgorithms { all: [ .. ], mapping: [ECDSA_NISTP384_SHA384, ECDSA_NISTP256_SHA256, ED25519, RSA_PSS_SHA512, RSA_PSS_SHA384, RSA_PSS_SHA256, RSA_PKCS1_SHA512, RSA_PKCS1_SHA384, RSA_PKCS1_SHA256] }",
            format!(
                "{:?}",
                crate::crypto::ring::default_provider().signature_verification_algorithms
            )
        );
    }
}

Coverage Report

Created: 2026-10-28 06:40

Line	Count	Source
1		use alloc::vec::Vec;
2		use core::fmt;
3
4		use pki_types::{
5		CertificateDer, ServerName, SignatureVerificationAlgorithm, SubjectPublicKeyInfoDer, UnixTime,
6		};
7
8		use super::anchors::RootCertStore;
9		use super::pki_error;
10		use crate::enums::SignatureScheme;
11		use crate::error::{Error, PeerMisbehaved};
12		use crate::verify::{DigitallySignedStruct, HandshakeSignatureValid};
13
14		/// Verify that the end-entity certificate `end_entity` is a valid server cert
15		/// and chains to at least one of the trust anchors in the `roots` [RootCertStore].
16		///
17		/// This function is primarily useful when building a custom certificate verifier. It
18		/// performs no revocation checking. Implementers must handle this themselves,
19		/// along with checking that the server certificate is valid for the subject name
20		/// being used (see [`verify_server_name`]).
21		///
22		/// `intermediates` contains all certificates other than `end_entity` that
23		/// were sent as part of the server's `Certificate` message. It is in the
24		/// same order that the server sent them and may be empty.
25		#[allow(dead_code)]
26	0	pub fn verify_server_cert_signed_by_trust_anchor(
27	0	cert: &ParsedCertificate<'_>,
28	0	roots: &RootCertStore,
29	0	intermediates: &[CertificateDer<'_>],
30	0	now: UnixTime,
31	0	supported_algs: &[&dyn SignatureVerificationAlgorithm],
32	0	) -> Result<(), Error> {
33	0	verify_server_cert_signed_by_trust_anchor_impl(
34	0	cert,
35	0	roots,
36	0	intermediates,
37	0	None, // No revocation checking supported with this API.
38	0	now,
39	0	supported_algs,
40		)
41	0	}
42
43		/// Verify that the `end_entity` has an alternative name matching the `server_name`.
44		///
45		/// Note: this only verifies the name and should be used in conjunction with more verification
46		/// like [verify_server_cert_signed_by_trust_anchor]
47	0	pub fn verify_server_name(
48	0	cert: &ParsedCertificate<'_>,
49	0	server_name: &ServerName<'_>,
50	0	) -> Result<(), Error> {
51	0	cert.0
52	0	.verify_is_valid_for_subject_name(server_name)
53	0	.map_err(pki_error)
54	0	}
55
56		/// Describes which `webpki` signature verification algorithms are supported and
57		/// how they map to TLS [`SignatureScheme`]s.
58		#[derive(Clone, Copy)]
59		#[allow(unreachable_pub)]
60		pub struct WebPkiSupportedAlgorithms {
61		/// A list of all supported signature verification algorithms.
62		///
63		/// Used for verifying certificate chains.
64		///
65		/// The order of this list is not significant.
66		pub all: &'static [&'static dyn SignatureVerificationAlgorithm],
67
68		/// A mapping from TLS `SignatureScheme`s to matching webpki signature verification algorithms.
69		///
70		/// This is one (`SignatureScheme`) to many ([`SignatureVerificationAlgorithm`]) because
71		/// (depending on the protocol version) there is not necessary a 1-to-1 mapping.
72		///
73		/// For TLS1.2, all `SignatureVerificationAlgorithm`s are tried in sequence.
74		///
75		/// For TLS1.3, only the first is tried.
76		///
77		/// The supported schemes in this mapping is communicated to the peer and the order is significant.
78		/// The first mapping is our highest preference.
79		pub mapping: &'static [(
80		SignatureScheme,
81		&'static [&'static dyn SignatureVerificationAlgorithm],
82		)],
83		}
84
85		impl WebPkiSupportedAlgorithms {
86		/// Return all the `scheme` items in `mapping`, maintaining order.
87	0	pub fn supported_schemes(&self) -> Vec<SignatureScheme> {
88	0	self.mapping
89	0	.iter()
90	0	.map(\|item\| item.0)
91	0	.collect()
92	0	}
93
94		/// Return the first item in `mapping` that matches `scheme`.
95	0	fn convert_scheme(
96	0	&self,
97	0	scheme: SignatureScheme,
98	0	) -> Result<&[&'static dyn SignatureVerificationAlgorithm], Error> {
99	0	self.mapping
100	0	.iter()
101	0	.filter_map(\|item\| if item.0 == scheme { Some(item.1) } else { None })
102	0	.next()
103	0	.ok_or_else(\|\| PeerMisbehaved::SignedHandshakeWithUnadvertisedSigScheme.into())
104	0	}
105
106		/// Return `true` if all cryptography is FIPS-approved.
107	0	pub fn fips(&self) -> bool {
108	0	self.all.iter().all(\|alg\| alg.fips())
109	0	&& self
110	0	.mapping
111	0	.iter()
112	0	.all(\|item\| item.1.iter().all(\|alg\| alg.fips()))
113	0	}
114		}
115
116		impl fmt::Debug for WebPkiSupportedAlgorithms {
117	0	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
118	0	write!(f, "WebPkiSupportedAlgorithms {{ all: [ .. ], mapping: ")?;
119	0	f.debug_list()
120	0	.entries(self.mapping.iter().map(\|item\| item.0))
121	0	.finish()?;
122	0	write!(f, " }}")
123	0	}
124		}
125
126		/// Wrapper around internal representation of a parsed certificate.
127		///
128		/// This is used in order to avoid parsing twice when specifying custom verification
129		pub struct ParsedCertificate<'a>(pub(crate) webpki::EndEntityCert<'a>);
130
131		impl ParsedCertificate<'_> {
132		/// Get the parsed certificate's SubjectPublicKeyInfo (SPKI)
133	0	pub fn subject_public_key_info(&self) -> SubjectPublicKeyInfoDer<'static> {
134	0	self.0.subject_public_key_info()
135	0	}
136		}
137
138		impl<'a> TryFrom<&'a CertificateDer<'a>> for ParsedCertificate<'a> {
139		type Error = Error;
140	0	fn try_from(value: &'a CertificateDer<'a>) -> Result<Self, Self::Error> {
141	0	webpki::EndEntityCert::try_from(value)
142	0	.map_err(pki_error)
143	0	.map(ParsedCertificate)
144	0	}
145		}
146
147		/// Verify a message signature using the `cert` public key and any supported scheme.
148		///
149		/// This function verifies the `dss` signature over `message` using the subject public key from
150		/// `cert`. Since TLS 1.2 doesn't provide enough information to map the `dss.scheme` into a single
151		/// [`SignatureVerificationAlgorithm`], this function will map to several candidates and try each in
152		/// succession until one succeeds or we exhaust all candidates.
153		///
154		/// See [WebPkiSupportedAlgorithms::mapping] for more information.
155	0	pub fn verify_tls12_signature(
156	0	message: &[u8],
157	0	cert: &CertificateDer<'_>,
158	0	dss: &DigitallySignedStruct,
159	0	supported_schemes: &WebPkiSupportedAlgorithms,
160	0	) -> Result<HandshakeSignatureValid, Error> {
161	0	if dss.scheme.algorithm().is_none() {
162	0	return Err(PeerMisbehaved::SignedHandshakeWithUnadvertisedSigScheme.into());
163	0	}
164
165	0	let possible_algs = supported_schemes.convert_scheme(dss.scheme)?;
166	0	let cert = webpki::EndEntityCert::try_from(cert).map_err(pki_error)?;
167
168	0	let mut error = None;
169	0	for alg in possible_algs {
170	0	match cert.verify_signature(*alg, message, dss.signature()) {
171	0	Err(err @ webpki::Error::UnsupportedSignatureAlgorithmForPublicKeyContext(_)) => {
172	0	error = Some(err);
173	0	continue;
174		}
175	0	Err(e) => return Err(pki_error(e)),
176	0	Ok(()) => return Ok(HandshakeSignatureValid::assertion()),
177		}
178		}
179
180		#[allow(deprecated)] // The `unwrap_or()` should be statically unreachable
181	0	Err(pki_error(error.unwrap_or(
182	0	webpki::Error::UnsupportedSignatureAlgorithmForPublicKey,
183	0	)))
184	0	}
185
186		/// Verify a message signature using the `cert` public key and the first TLS 1.3 compatible
187		/// supported scheme.
188		///
189		/// This function verifies the `dss` signature over `message` using the subject public key from
190		/// `cert`. Unlike [verify_tls12_signature], this function only tries the first matching scheme. See
191		/// [WebPkiSupportedAlgorithms::mapping] for more information.
192	0	pub fn verify_tls13_signature(
193	0	msg: &[u8],
194	0	cert: &CertificateDer<'_>,
195	0	dss: &DigitallySignedStruct,
196	0	supported_schemes: &WebPkiSupportedAlgorithms,
197	0	) -> Result<HandshakeSignatureValid, Error> {
198	0	if !dss.scheme.supported_in_tls13() {
199	0	return Err(PeerMisbehaved::SignedHandshakeWithUnadvertisedSigScheme.into());
200	0	}
201
202	0	let alg = supported_schemes.convert_scheme(dss.scheme)?[0];
203
204	0	let cert = webpki::EndEntityCert::try_from(cert).map_err(pki_error)?;
205
206	0	cert.verify_signature(alg, msg, dss.signature())
207	0	.map_err(pki_error)
208	0	.map(\|_\| HandshakeSignatureValid::assertion())
209	0	}
210
211		/// Verify a message signature using a raw public key and the first TLS 1.3 compatible
212		/// supported scheme.
213	0	pub fn verify_tls13_signature_with_raw_key(
214	0	msg: &[u8],
215	0	spki: &SubjectPublicKeyInfoDer<'_>,
216	0	dss: &DigitallySignedStruct,
217	0	supported_schemes: &WebPkiSupportedAlgorithms,
218	0	) -> Result<HandshakeSignatureValid, Error> {
219	0	if !dss.scheme.supported_in_tls13() {
220	0	return Err(PeerMisbehaved::SignedHandshakeWithUnadvertisedSigScheme.into());
221	0	}
222
223	0	let raw_key = webpki::RawPublicKeyEntity::try_from(spki).map_err(pki_error)?;
224	0	let alg = supported_schemes.convert_scheme(dss.scheme)?[0];
225
226	0	raw_key
227	0	.verify_signature(alg, msg, dss.signature())
228	0	.map_err(pki_error)
229	0	.map(\|_\| HandshakeSignatureValid::assertion())
230	0	}
231
232		/// Verify that the end-entity certificate `end_entity` is a valid server cert
233		/// and chains to at least one of the trust anchors in the `roots` [RootCertStore].
234		///
235		/// `intermediates` contains all certificates other than `end_entity` that
236		/// were sent as part of the server's `Certificate` message. It is in the
237		/// same order that the server sent them and may be empty.
238		///
239		/// `revocation` controls how revocation checking is performed, if at all.
240		///
241		/// This function exists to be used by [`verify_server_cert_signed_by_trust_anchor`],
242		/// and differs only in providing a `Option<webpki::RevocationOptions>` argument. We
243		/// can't include this argument in `verify_server_cert_signed_by_trust_anchor` because
244		/// it will leak the webpki types into Rustls' public API.
245	0	pub(crate) fn verify_server_cert_signed_by_trust_anchor_impl(
246	0	cert: &ParsedCertificate<'_>,
247	0	roots: &RootCertStore,
248	0	intermediates: &[CertificateDer<'_>],
249	0	revocation: Option<webpki::RevocationOptions<'_>>,
250	0	now: UnixTime,
251	0	supported_algs: &[&dyn SignatureVerificationAlgorithm],
252	0	) -> Result<(), Error> {
253	0	let result = cert.0.verify_for_usage(
254	0	supported_algs,
255	0	&roots.roots,
256	0	intermediates,
257	0	now,
258	0	webpki::KeyUsage::server_auth(),
259	0	revocation,
260	0	None,
261		);
262	0	match result {
263	0	Ok(_) => Ok(()),
264	0	Err(e) => Err(pki_error(e)),
265		}
266	0	}
267
268		#[cfg(test)]
269		mod tests {
270		use std::format;
271
272		use super::*;
273
274		#[test]
275		fn certificate_debug() {
276		assert_eq!(
277		"CertificateDer(0x6162)",
278		format!("{:?}", CertificateDer::from(b"ab".to_vec()))
279		);
280		}
281
282		#[cfg(feature = "ring")]
283		#[test]
284		fn webpki_supported_algorithms_is_debug() {
285		assert_eq!(
286		"WebPkiSupportedAlgorithms { all: [ .. ], mapping: [ECDSA_NISTP384_SHA384, ECDSA_NISTP256_SHA256, ED25519, RSA_PSS_SHA512, RSA_PSS_SHA384, RSA_PSS_SHA256, RSA_PKCS1_SHA512, RSA_PKCS1_SHA384, RSA_PKCS1_SHA256] }",
287		format!(
288		"{:?}",
289		crate::crypto::ring::default_provider().signature_verification_algorithms
290		)
291		);
292		}
293		}