Crate rustls_pki_types

Expand description

This crate provides types for representing X.509 certificates, keys and other types as commonly used in the rustls ecosystem. It is intended to be used by crates that need to work with such X.509 types, such as rustls, rustls-webpki, rustls-pemfile, and others.

Some of these crates used to define their own trivial wrappers around DER-encoded bytes. However, in order to avoid inconvenient dependency edges, these were all disconnected. By using a common low-level crate of types with long-term stable API, we hope to avoid the downsides of unnecessary dependency edges while providing good interoperability between crates.

§DER and PEM

Many of the types defined in this crate represent DER-encoded data. DER is a binary encoding of the ASN.1 format commonly used in web PKI specifications. It is a binary encoding, so it is relatively compact when stored in memory. However, as a binary format, it is not very easy to work with for humans and in contexts where binary data is inconvenient. For this reason, many tools and protocols use a ASCII-based encoding of DER, called PEM. In addition to the base64-encoded DER, PEM objects are delimited by header and footer lines which indicate the type of object contained in the PEM blob.

Types here can be created from:

DER using (for example) PrivatePkcs8KeyDer::from().
PEM using (for example) pem::PemObject::from_pem_slice().

The pem::PemObject trait contains the full selection of ways to construct these types from PEM encodings. That includes ways to open and read from a file, from a slice, or from an std::io stream.

There is also a lower-level API that allows a given PEM file to be fully consumed in one pass, even if it contains different data types: see the implementation of the pem::PemObject trait on the (pem::SectionKind, Vec<u8>) tuple.

§Creating new certificates and keys

This crate does not provide any functionality for creating new certificates or keys. However, the rcgen crate can be used to create new certificates and keys.

§Cloning private keys

This crate intentionally does not implement Clone on private key types in order to minimize the exposure of private key data in memory.

If you want to extend the lifetime of a PrivateKeyDer<'_>, consider PrivateKeyDer::clone_key(). Alternatively since these types are immutable, consider wrapping the PrivateKeyDer<'_> in a Rc or an Arc.

§Target `wasm32-unknown-unknown` with the `web` feature

std::time::SystemTime is unavailable in wasm32-unknown-unknown targets, so calls to UnixTime::now(), otherwise enabled by the std feature, require building instead with the web feature. It gets time by calling Date.now() in the browser.

Re-exports§

pub use alg_id::AlgorithmIdentifier;

Modules§

alg_id: The PKIX AlgorithmIdentifier type, and common values.
pem: Low-level PEM decoding APIs.

Structs§

AddrParseError: Failure to parse an IP address
CertificateDer: A DER-encoded X.509 certificate; as specified in RFC 5280
CertificateRevocationListDer: A Certificate Revocation List; as specified in RFC 5280
CertificateSigningRequestDer: A Certificate Signing Request; as specified in RFC 2986
Der: DER-encoded data, either owned or borrowed
DnsName: A type which encapsulates a string (borrowed or owned) that is a syntactically valid DNS name.
EchConfigListBytes: A TLS-encoded Encrypted Client Hello (ECH) configuration list (ECHConfigList); as specified in draft-ietf-tls-esni-18 §4
InvalidDnsNameError: The provided input could not be parsed because it is not a syntactically-valid DNS Name.
InvalidSignature: A detail-less error when a signature is not valid.
Ipv4Addr: no_std implementation of std::net::Ipv4Addr.
Ipv6Addr: no_std implementation of std::net::Ipv6Addr.
PrivatePkcs1KeyDer: A DER-encoded plaintext RSA private key; as specified in PKCS#1/RFC 3447
PrivatePkcs8KeyDer: A DER-encoded plaintext private key; as specified in PKCS#8/RFC 5958
PrivateSec1KeyDer: A Sec1-encoded plaintext private key; as specified in RFC 5915
SubjectPublicKeyInfoDer: A DER-encoded SubjectPublicKeyInfo (SPKI), as specified in RFC 5280.
TrustAnchor: A trust anchor (a.k.a. root CA)
UnixTime: A timestamp, tracking the number of non-leap seconds since the Unix epoch.

Enums§

IpAddr: no_std implementation of std::net::IpAddr.
PrivateKeyDer: A DER-encoded X.509 private key, in one of several formats
ServerName: Encodes ways a client can know the expected name of the server.

Traits§

SignatureVerificationAlgorithm: An abstract signature verification algorithm.

Type Aliases§

SubjectPublicKeyInfoDeprecated: A DER-encoded SubjectPublicKeyInfo (SPKI), as specified in RFC 5280.

Crate rustls_pki_typesCopy item path