Skip to main content

Crate crypto_rustls

Crate crypto_rustls 

Source
Expand description

A rustls [CryptoProvider] backed by the stdx [crypto] crate.

This crate lets rustls use the pure-Rust, no_std-friendly primitives from [crypto] instead of rustls’ built-in aws-lc-rs or ring backends. Rustls is configured with default-features = false, so no C or assembly-backed cryptography is compiled in.

§Supported algorithms

  • TLS 1.3 cipher suites: TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256.
  • Key exchange: X25519MLKEM768 (post-quantum hybrid, preferred), X25519, secp256r1 and secp384r1.
  • Signature verification: ECDSA P-256/P-384, Ed25519, RSA PKCS#1 v1.5 and PSS, and ML-DSA-44/65/87 (FIPS 204).
  • Signing (for serving TLS or client certificates): ECDSA P-256/P-384, Ed25519 and ML-DSA-44/65/87. RSA private keys are not supported.
  • QUIC (RFC 9001) packet protection for all three cipher suites.

ML-DSA is supported in the “pure” mode required by RFC 9881 and the TLS 1.3 ML-DSA profile (empty FIPS 204 context). Private keys must be in the RFC 9881 seed form; keys stored only as an expanded key are rejected because the seed cannot be recovered from them. OpenSSL’s default both encoding (seed plus expanded key) is accepted.

The X25519MLKEM768 hybrid is offered first, so a post-quantum key share is sent by default in the ClientHello, while classical groups remain available for peers that do not support it. Encapsulation keys received from a peer are validated per FIPS 203 section 7.2 (modulus check); a malformed key share is rejected as PeerMisbehaved::InvalidKeyShare.

RSA PKCS#1 v1.5 certificates are accepted both with the customary NULL AlgorithmIdentifier parameters and with the parameters absent (RFC 4055 section 2.1).

§Limitations

  • TLS 1.2 is not supported. Only TLS 1.3 cipher suites are provided.
  • RSA signing is not supported. The [crypto] crate implements RSA verification only, so a TLS server (or a client using client authentication) must use an ECDSA P-256/P-384, Ed25519 or ML-DSA private key. RSA-signed certificate chains are still verified normally.
  • The curve implementations bind each curve to a single hash (P-256 with SHA-256, P-384 with SHA-384), so the uncommon cross combinations are not registered.

§Usage

Install this provider as the process default before building any rustls configuration:

ⓘ
crypto_rustls::install_default_rustls_provider();

Or pass default_provider explicitly to ClientConfig::builder_with_provider() / ServerConfig::builder_with_provider().

Functions§

default_provider
Returns this crate’s [CryptoProvider].
install_default_rustls_provider
Installs default_provider as the process-default rustls [CryptoProvider].