Struct webpki::EndEntityCert

pub struct EndEntityCert<'a> { /* private fields */ }

An end-entity certificate.

Server certificate processing in a TLS connection consists of several steps. All of these steps are necessary:

• EndEntityCert::verify_for_usage(): Verify that the peer’s certificate is valid for the current usage scenario. For server authentication, use KeyUsage::server_auth().
• EndEntityCert::verify_is_valid_for_subject_name(): Verify that the server’s certificate is valid for the host or IP address that is being connected to.
• EndEntityCert::verify_signature(): Verify that the signature of server’s ServerKeyExchange message is valid for the server’s certificate.

Client certificate processing in a TLS connection consists of analogous steps. All of these steps are necessary:

• EndEntityCert::verify_for_usage(): Verify that the peer’s certificate is valid for the current usage scenario. For client authentication, use KeyUsage::client_auth().
• EndEntityCert::verify_signature(): Verify that the signature of client’s CertificateVerify message is valid using the public key from the client’s certificate.

Although it would be less error-prone to combine all these steps into a single function call, some significant optimizations are possible if the three steps are processed separately (in parallel). It does not matter much which order the steps are done in, but all of these steps must completed before application data is sent and before received application data is processed. The TryFrom conversion from &CertificateDer<'_> is an inexpensive operation and is deterministic, so if these tasks are done in multiple threads, it is probably best to just create multiple EndEntityCert instances for the same DER-encoded ASN.1 certificate bytes.

Implementations

impl<'a> EndEntityCert<'a>

pub fn verify_for_usage<'p>( &'p self, supported_sig_algs: &[&dyn SignatureVerificationAlgorithm], trust_anchors: &'p [TrustAnchor<'_>], intermediate_certs: &'p [CertificateDer<'p>], time: UnixTime, usage: KeyUsage, revocation: Option<RevocationOptions<'_>>, verify_path: Option<&dyn Fn(&VerifiedPath<'_>) -> Result<(), Error>>, ) -> Result<VerifiedPath<'p>, Error>

Verifies that the end-entity certificate is valid for use against the specified Extended Key Usage (EKU).

• supported_sig_algs is the list of signature algorithms that are trusted for use in certificate signatures; the end-entity certificate’s public key is not validated against this list.
• trust_anchors is the list of root CAs to trust in the built path.
• intermediate_certs is the sequence of intermediate certificates that a peer sent for the purpose of path building.
• time is the time for which the validation is effective (usually the current time).
• usage is the intended usage of the certificate, indicating what kind of usage we’re verifying the certificate for.
• crls is the list of certificate revocation lists to check the certificate against.
• verify_path is an optional verification function for path candidates.

If successful, yields a VerifiedPath type that can be used to inspect a verified chain of certificates that leads from the end_entity to one of the self.trust_anchors.

verify_path will only be called for potentially verified paths, that is, paths that have been verified up to the trust anchor. As such, verify_path() cannot be used to verify a path that doesn’t satisfy the constraints listed above; it can only be used to reject a path that does satisfy the aforementioned constraints. If verify_path returns an error, path building will continue in order to try other options.

pub fn verify_is_valid_for_subject_name( &self, server_name: &ServerName<'_>, ) -> Result<(), Error>

Verifies that the certificate is valid for the given Subject Name.

pub fn verify_signature( &self, signature_alg: &dyn SignatureVerificationAlgorithm, msg: &[u8], signature: &[u8], ) -> Result<(), Error>

Verifies the signature signature of message msg using the certificate’s public key.

signature_alg is the algorithm to use to verify the signature; the certificate’s public key is verified to be compatible with this algorithm.

For TLS 1.2, signature corresponds to TLS’s DigitallySigned.signature and signature_alg corresponds to TLS’s DigitallySigned.algorithm of TLS type SignatureAndHashAlgorithm. In TLS 1.2 a single SignatureAndHashAlgorithm may map to multiple SignatureVerificationAlgorithms. For example, a TLS 1.2 SignatureAndHashAlgorithm of (ECDSA, SHA-256) may map to any or all of {ECDSA_P256_SHA256, ECDSA_P384_SHA256}, depending on how the TLS implementation is configured.

For current TLS 1.3 drafts, signature_alg corresponds to TLS’s algorithm fields of type SignatureScheme. There is (currently) a one-to-one correspondence between TLS 1.3’s SignatureScheme and SignatureVerificationAlgorithm.

Methods from Deref<Target = Cert<'a>>

pub fn valid_dns_names(&self) -> impl Iterator<Item = &str>

Returns a list of valid DNS names provided in the subject alternative names extension

This function must not be used to implement custom DNS name verification. Checking that a certificate is valid for a given subject name should always be done with EndEntityCert::verify_is_valid_for_subject_name.

pub fn serial(&self) -> &[u8]

Raw DER encoded certificate serial number.

pub fn issuer(&self) -> &[u8]

Raw DER encoded certificate issuer.

pub fn subject(&self) -> &[u8]

Raw DER encoded certificate subject.

pub fn subject_public_key_info(&self) -> SubjectPublicKeyInfoDer<'static>

Get the RFC 5280-compliant SubjectPublicKeyInfoDer (SPKI) of this Cert.

pub fn der(&self) -> CertificateDer<'a>

Raw DER encoded representation of the certificate.

Trait Implementations

impl<'a> Deref for EndEntityCert<'a>

type Target = Cert<'a>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'a> TryFrom<&'a CertificateDer<'a>> for EndEntityCert<'a>

fn try_from(cert: &'a CertificateDer<'a>) -> Result<Self, Self::Error>

Parse the ASN.1 DER-encoded X.509 encoding of the certificate cert_der.

type Error = Error

The type returned in the event of a conversion error.