Crate rustls

展开描述

§Rustls - a modern TLS library

Rustls 是 TLS library that aims 到 provide 一个 good level of cryptographic security, requires no configuration 到 achieve that security, 并 provides no unsafe features 或过时的密码学算法

Rustls implements TLS1.2 并 TLS 1.3 用于 both clients 并 servers. ，请参见the full list of protocol features。

§Platform support

虽然 Rustls 本身是平台无关的，但默认使用 aws-lc-rs 用于 implementing TLS 中的密码学，请参见the aws-lc-rs FAQ 用于 more details of the aws-lc-rs 的平台/架构支持限制

ring 也 available via the ring ：请参见 the 受支持ring target platforms。

By providing 一个 custom instance of the crypto::CryptoProvider ：来，可替换 rustls 的所有密码学依赖 This 是 route 到 being portable 到一个 wider set of architectures 并 environments, 或 compliance requirements. ，请参见 crypto::CryptoProvider documentation 用于 more details.

Specifying default-features = false when depending on rustls will remove the implicit 对 aws-lc-rs 的依赖。

Rustls requires Rust 1.71 或 later. It has an optional dependency on zlib-rs which requires 1.75 或 later.

§Cryptography providers

Since Rustls 0.22 it has been possible 到 choose the provider of the cryptographic primitives that Rustls uses. This may be appealing if you have specific platform, compliance 或 feature requirements that ，’，默认 provider, aws-lc-rs。

Users that wish 到 customize the provider in use can do so when constructing ClientConfig 并 ServerConfig instances using the with_crypto_provider method on the respective config builder types. ，请参见 crypto::CryptoProvider documentation 用于 more details.

§Built-in providers

Rustls 附带两个内置 provider，由关联的 crate 特性控制：

aws-lc-rs - enabled by default, available with the aws_lc_rs crate feature enabled.
ring - available with the ring crate feature enabled.

，请参见 documentation 用于 crypto::CryptoProvider 用于 details on how providers are selected.

§Third-party providers

此 community has also started developing third-party providers 用于 Rustls:

boring-rustls-provider - a work-in-progress provider that uses boringssl for cryptography.
rustls-graviola - a provider that uses graviola for cryptography.
rustls-mbedtls-provider - a provider that uses mbedtls for cryptography.
rustls-openssl - a provider that uses OpenSSL for cryptography.
rustls-rustcrypto - an experimental provider that uses the crypto primitives from RustCrypto for cryptography.
rustls-symcrypt - a provider that uses Microsoft’s SymCrypt library.
rustls-wolfcrypt-provider - a work-in-progress provider that uses wolfCrypt for cryptography.

§Custom provider

We also provide 一个 simple example of writing your own provider in the custom provider example。 This example implements 一个 minimal provider using parts of the RustCrypto ecosystem.

，请参见 Making 一个 custom CryptoProvider section of the documentation 用于 more information on this topic.

§Design overview

Rustls 是 low-level library. If your goal is 到 make HTTPS connections you may prefer 到 use 一个 library built on top of Rustls like hyper 或 ureq。

§Rustls does not take care of network IO

It doesn’t make 或 accept TCP connections, 或 do DNS, 或 read 或 write files.

Our examples directory contains demos that show how 到 handle I/O using the stream::Stream helper, as well as more complex asynchronous I/O using mio。 If you’re already using Tokio 用于 an async runtime you may prefer 到 use tokio-rustls instead of interacting with rustls directly.

§Rustls provides encrypted pipes

These are the ServerConnection 并 ClientConnection types. You supply raw TLS traffic on the left (via the read_tls() 并 write_tls() methods) 并 then read/write the 明文 on the right:

         TLS                                   Plaintext
         ===                                   =========
    read_tls()      +-----------------------+      reader() as io::Read
                    |                       |
          +--------->   ClientConnection    +--------->
                    |          or           |
          <---------+   ServerConnection    <---------+
                    |                       |
    write_tls()     +-----------------------+      writer() as io::Write

§Rustls takes care of server certificate verification

You do not need to provide anything other than a set of root certificates to trust. Certificate verification cannot be turned off or disabled in the main API.

§Getting started

This is the minimum you need to do to make a TLS client connection.

First we load some root certificates. These are used to authenticate the server. 此 simplest way is to depend on the webpki_roots crate which contains the Mozilla set of root certificates.

let root_store = rustls::RootCertStore::from_iter(
    webpki_roots::TLS_SERVER_ROOTS
        .iter()
        .cloned(),
);

Next, we make a ClientConfig。 You’re likely to make one of these per process, and use it for all connections made by that process.

let config = rustls::ClientConfig::builder()
    .with_root_certificates(root_store)
    .with_no_client_auth();

Now we can make a connection. You need to provide the server’s hostname so we know what to expect to find in the server’s certificate.

let rc_config = Arc::new(config);
let example_com = "example.com".try_into().unwrap();
let mut client = rustls::ClientConnection::new(rc_config, example_com);

Now you should do appropriate IO for the client object. If client.wants_read() yields true, you should call client.read_tls() when the underlying connection has data. Likewise, if client.wants_write() yields true, you should call client.write_tls() when the underlying connection is able to send data. You should continue doing this as long as the connection is valid.

此 return types of read_tls() and write_tls() only tell you if the IO worked. No parsing or processing of the TLS messages is done. After each read_tls() you should therefore call client.process_new_packets() which parses and processes the messages. Any error returned 从 process_new_packets is fatal to the connection, and will tell you why. For example, if the server’s certificate is expired process_new_packets will return Err(InvalidCertificate(Expired))。 From this point on, process_new_packets will not do any new work and will return that error continually.

You can extract newly received data by calling client.reader() (which implements the io::Read trait)。 You can send data to the peer by calling client.writer() (which implements io::Write trait)。 Note that client.writer().write() buffers data you send if the TLS connection is not yet established: this is useful for writing (say) a HTTP request, but this is buffered so avoid large amounts of data.

此 following code uses a fictional socket IO API for illustration, and does not handle errors.

use std::io;
use rustls::Connection;

client.writer().write(b"GET / HTTP/1.0\r\n\r\n").unwrap();
let mut socket = connect("example.com", 443);
loop {
  if client.wants_read() && socket.ready_for_read() {
    client.read_tls(&mut socket).unwrap();
    client.process_new_packets().unwrap();

    let mut plaintext = Vec::new();
    client.reader().read_to_end(&mut plaintext).unwrap();
    io::stdout().write(&plaintext).unwrap();
  }

  if client.wants_write() && socket.ready_for_write() {
    client.write_tls(&mut socket).unwrap();
  }

  socket.wait_for_something_to_happen();
}

§示例

You can find several client and server examples of varying complexity in the examples directory, including tlsserver-mio and tlsclient-mio - full worked examples using mio。

§Manual

此 rustls manual explains design decisions and includes how-to guidance.

§Crate features

Here’s a list of what features are exposed by the rustls crate and what they mean.

std (enabled by default): enable the high-level (buffered) Connection API and other functionality which relies on the std library.
aws_lc_rs (enabled by default): makes the rustls crate depend on the aws-lc-rs crate. Use rustls::crypto::aws_lc_rs::default_provider().install_default() to use it as the default CryptoProvider, or provide it explicitly when making a ClientConfig or ServerConfig。

Note that aws-lc-rs has additional build-time dependencies like cmake. See the documentation for details.
ring: makes the rustls crate depend on the ring crate for cryptography. Use rustls::crypto::ring::default_provider().install_default() to use it as the default CryptoProvider, or provide it explicitly when making a ClientConfig or ServerConfig。
fips: enable support for FIPS140-3-approved cryptography, via the aws-lc-rs crate. This feature enables the aws_lc_rs crate feature, which makes the rustls crate depend on aws-lc-rs。 It also changes the default for [ServerConfig::require_ems] and [ClientConfig::require_ems]。

See manual::_06_fips for more details.
prefer-post-quantum (enabled by default): for the aws-lc-rs-backed provider, prioritizes post-quantum secure key exchange by default (using X25519MLKEM768)。 This feature merely alters the order of rustls::crypto::aws_lc_rs::DEFAULT_KX_GROUPS。 See the manual for more details.
custom-provider: disables implicit use of built-in providers (aws-lc-rs or ring)。 This forces applications to manually install one, for instance, when using a custom CryptoProvider。
tls12 (enabled by default): enable support for TLS version 1.2. Note that, due to the additive nature of Cargo features and because it is enabled by default, other crates in your dependency graph could re-enable it for your application. If you want to disable TLS 1.2 for security reasons, consider explicitly enabling TLS 1.3 only in the config builder API.
logging (enabled by default): make the rustls crate depend on the log crate. rustls outputs interesting protocol-level messages at trace! and debug! level, and protocol-level errors at warn! and error! level. 此 log messages do not contain secret key data, and so are safe to archive without affecting session security.
read_buf: when building with Rust Nightly, adds support for the unstable std::io::ReadBuf and related APIs. This reduces costs 从 initializing buffers. Will do nothing on non-Nightly releases.
brotli: uses the brotli crate for RFC8879 certificate compression support.
zlib: uses the zlib-rs crate for RFC8879 certificate compression support.

重新导出§

pub use crate::ticketer::TicketRotator;
pub use crate::ticketer::TicketSwitcher;
pub use client::ClientConfig;
pub use client::ClientConnection;
pub use server::ServerConfig;
pub use server::ServerConnection;

模块§

client: Items for use in a client.
compress: Certificate compression and decompression support
crypto: Crypto provider interface.
ffdhe_groups: This module contains parameters for FFDHE named groups as defined in RFC 7919 Appendix A.
kernel: Kernel connection API.
lock: APIs abstracting over locking primitives.
manual: This is the rustls manual.
pki_types: Re-exports the contents of the rustls-pki-types crate for easy access
quic: APIs for implementing QUIC TLS
server: Items for use in a server.
sign: Message signing interfaces.
ticketer: APIs for implementing TLS tickets
time_provider: The library’s source of time.
unbuffered: Unbuffered connection API
version: All defined protocol versions appear in this module.

结构体§

CipherSuiteCommon: Common state for cipher suites (both for TLS 1.2 and TLS 1.3)
CommonState: Connection state common to both client and server connections.
ConfigBuilder: A builder for ServerConfig or ClientConfig values.
ConnectionCommon: Interface shared by client and server connections.
DigitallySignedStruct: This type combines a SignatureScheme and a signature payload produced with that scheme.
DistinguishedName: A DistinguishedName is a Vec<u8> wrapped in internal types.
ExtractedSecrets: Secrets for transmitting/receiving data over a TLS session.
IoState: Values of this structure are returned from Connection::process_new_packets and tell the caller the current I/O state of the TLS connection.
KeyLogFile: KeyLog implementation that opens a file whose name is given by the SSLKEYLOGFILE environment variable, and writes keys into it.
NoKeyLog: KeyLog that does exactly nothing.
OtherError: Any other error that cannot be expressed by a more specific Error variant.
Reader: A structure that implements std::io::Read for reading plaintext.
RootCertStore: A container for root certificates able to provide a root-of-trust for connection authentication.
Stream: This type implements io::Read and io::Write, encapsulating a Connection C and an underlying transport T, such as a socket.
StreamOwned: This type implements io::Read and io::Write, encapsulating and owning a Connection C and an underlying transport T, such as a socket.
SupportedProtocolVersion: A TLS protocol version supported by rustls.
Tls13CipherSuite: A TLS 1.3 cipher suite supported by rustls.
WantsVerifier: Config builder state where the caller must supply a verifier.
WantsVersions: Config builder state where the caller must supply TLS protocol versions.
Writer: A structure that implements std::io::Write for writing plaintext.

枚举§

AlertDescription: The AlertDescription TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. The Unknown item is used when processing unrecognised ordinals.
CertRevocationListError: The ways in which a certificate revocation list (CRL) can be invalid.
CertificateCompressionAlgorithm: The “TLS Certificate Compression Algorithm IDs” TLS protocol enum. Values in this enum are taken from RFC8879.
CertificateError: The ways in which certificate validators can express errors.
CipherSuite: The CipherSuite TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. The Unknown item is used when processing unrecognised ordinals.
Connection: A client or server connection.
ConnectionTrafficSecrets: Secrets used to encrypt/decrypt data in a TLS session.
ContentType: The ContentType TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. The Unknown item is used when processing unrecognised ordinals.
EncryptedClientHelloError: An error that occurred while handling Encrypted Client Hello (ECH).
Error: rustls reports protocol errors using this type.
ExtendedKeyPurpose: Extended Key Usage (EKU) purpose values.
HandshakeKind: Describes which sort of handshake happened.
HandshakeType: The HandshakeType TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. The Unknown item is used when processing unrecognised ordinals.
InconsistentKeys: Specific failure cases from keys_match or a crate::crypto::signer::SigningKey that cannot produce a corresponding public key.
InvalidMessage: A corrupt TLS message payload that resulted in an error.
NamedGroup: The NamedGroup TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. The Unknown item is used when processing unrecognised ordinals.
PeerIncompatible: The set of cases where we failed to make a connection because a peer doesn’t support a TLS version/feature we require.
PeerMisbehaved: The set of cases where we failed to make a connection because we thought the peer was misbehaving.
ProtocolVersion: The ProtocolVersion TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. The Unknown item is used when processing unrecognised ordinals.
Side: Side of the connection.
SignatureAlgorithm: The SignatureAlgorithm TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. The Unknown item is used when processing unrecognised ordinals.
SignatureScheme: The SignatureScheme TLS protocol enum. Values in this enum are taken from the various RFCs covering TLS, and are listed by IANA. The Unknown item is used when processing unrecognised ordinals.
SupportedCipherSuite: A cipher suite supported by rustls.

废除项§

ALL_VERSIONS: A list of all the protocol versions supported by rustls.
DEFAULT_VERSIONS: The version configuration that an application should use by default.

Trait§

ConfigSide: Helper trait to abstract ConfigBuilder over building a ClientConfig or ServerConfig.
KeyLog: This trait represents the ability to do something useful with key material, such as logging it to a file for debugging.
SideData: Data specific to the peer’s side (client or server).

Crate rustls

Crate rustls 复制项目路径

§Rustls - a modern TLS library

§Platform support

§Cryptography providers

§Built-in providers

§Third-party providers

§Custom provider

§Design overview

§Rustls does not take care of network IO

§Rustls provides encrypted pipes

§Rustls takes care of server certificate verification

§Getting started

§示例

§Manual

§Crate features

重新导出§

模块§

结构体§

枚举§

废除项§

Trait§

Crate rustls