Struct ClientCertificate 

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

Available on crate feature mtls only.

A client certificate the HOST has already verified, decomposed into the facts RFC 8705 matches on.

Read the module docs on the trust boundary before constructing one. Nothing in this type is a secret and nothing here is redacted in Debug: a certificate is a public document, and what authenticates the client is possession of the private key, which the TLS handshake proved to the HOST and which this crate never sees.

Everything borrows, so building one allocates nothing but the thumbprint’s hash, and passing it into the token endpoint costs one pointer.

Implementations

impl<'a> ClientCertificate<'a>

pub fn from_der(der: &[u8]) -> Self

From the DER encoding of the VERIFIED certificate: this crate cannot check the chain and takes the bytes as an established fact, so read this module’s trust boundary section before choosing where they come from. Bytes off an unstripped X-Client-Cert header authenticate nobody.

The thumbprint (RFC 8705 section 3.1) is computed here, once, so no caller has to decide which bytes to hash or which base64 alphabet to use.

The subject DN and the SAN entries default to absent; add whichever the deployment registers clients by. A certificate with no facts attached can still be BOUND to a token (section 3), which is why they are optional rather than required: section 4 makes certificate binding available to a client that does not authenticate with mutual TLS at all.

pub fn from_thumbprint(thumbprint: CertificateThumbprint) -> Self

From a thumbprint the host computed itself, for a deployment whose TLS terminator forwards a fingerprint rather than the certificate (nginx’s $ssl_client_fingerprint, an ALB’s header). The host is then responsible for the encoding, which is why ClientCertificate::from_der is the constructor to prefer where the DER is available.

pub fn with_subject_dn(self, dn: &'a str) -> Self

The subject distinguished name, in the RFC 4514 string representation.

The comparison this crate performs is EXACT STRING EQUALITY against the registered value (see ExpectedSubject::SubjectDn), so the host must produce the same spelling its registrations use. RFC 8705 section 2.1 allows a server to implement a more sophisticated DN comparison; this crate deliberately does not, because a partial DN parser that gets attribute ordering, escaping or case folding subtly wrong is a way to make two different subjects compare equal, and that is an authentication bypass rather than an inconvenience.

pub fn with_san_dns(self, entries: &'a [&'a str]) -> Self

The dNSName subjectAltName entries.

pub fn with_san_uri(self, entries: &'a [&'a str]) -> Self

The uniformResourceIdentifier subjectAltName entries.

pub fn with_san_ip(self, entries: &'a [&'a str]) -> Self

The iPAddress subjectAltName entries, in their textual form.

pub fn with_san_email(self, entries: &'a [&'a str]) -> Self

The rfc822Name subjectAltName entries.

pub fn thumbprint(&self) -> &CertificateThumbprint

This certificate’s RFC 8705 section 3.1 thumbprint, which is what a token gets bound to.

Trait Implementations

impl<'a> Clone for ClientCertificate<'a>

fn clone(&self) -> ClientCertificate<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for ClientCertificate<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Eq for ClientCertificate<'a>

impl<'a> PartialEq for ClientCertificate<'a>

fn eq(&self, other: &ClientCertificate<'a>) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<'a> StructuralPartialEq for ClientCertificate<'a>