Rustls 是一个用 Rust 编写的现代 TLS 库。

状态

Rustls 被许多组织和项目在生产中使用。我们旨在保持合理的 API 表面积稳定性，但随着我们对新功能或性能改进进行更改，API 可能会演变。

我们有一个路线图，其中包含我们的未来计划。我们还有 基准测试，以防止性能下降，并让您评估 rustls 在目标硬件上的性能。

如果您想帮忙，请参阅 CONTRIBUTING.md。

变更日志

每个版本中变更的详细列表可以在 https://github.com/rustls/rustls/releases 找到。

文档

https://docs.rs/rustls/

方法

Rustls 是一个 TLS 库，旨在提供良好的加密安全级别，无需配置即可实现该安全级别，并默认不提供不安全功能或过时的加密。

Rustls 为客户端和服务器实现了 TLS1.2 和 TLS1.3。有关协议功能的完整列表，请参阅 此处。

平台支持

虽然 Rustls 本身是平台无关的，但默认情况下，它使用 aws-lc-rs 来实现 TLS 中的加密。有关 aws-lc-rs 在平台/架构支持方面的限制的更多详细信息，请参阅 aws-lc-rs 常见问题解答。

ring 也可通过 ring crate 功能使用：请参阅 支持的 ring 目标平台。

通过提供自定义的 crypto::CryptoProvider 结构体实例，您可以替换 rustls 的所有加密依赖。这是实现跨更广泛的架构和环境或符合性要求的一种方式。有关更多详细信息，请参阅 crypto::CryptoProvider 文档。

当依赖 rustls 时，指定 default-features = false 将会移除对 aws-lc-rs 的依赖。

Rustls 需要 Rust 1.63 或更高版本。它有一个可选依赖 zlib-rs，需要 1.75 或更高版本。

加密提供者

从 Rustls 0.22 版本开始，可以选择 Rustls 使用的加密原语提供者。如果您有特定的平台、符合性或功能要求，而这些要求默认提供者（aws-lc-rs）无法满足，这可能很有吸引力。

希望自定义所使用提供者的用户可以在构造 ClientConfig 和 ServerConfig 实例时，使用相应配置构建器类型上的 with_crypto_provider 方法进行操作。有关更多详细信息，请参阅 crypto::CryptoProvider 文档。

内置提供者

Rustls 随带两个内置提供者，这些提供者通过关联功能标志进行控制。

• aws-lc-rs - 默认启用，当启用 aws_lc_rs 功能标志时可用。
• ring - 当启用 ring 功能标志时可用。

有关提供者选择详情，请参阅 crypto::CryptoProvider 文档。

第三方提供者

社区也已经开始为 Rustls 开发第三方提供者。

• rustls-mbedtls-provider - 使用 mbedtls 进行加密的提供者。
• boring-rustls-provider - 使用 boringssl 进行加密的仍在开发中的提供者。
• rustls-rustcrypto - 使用 RustCrypto 中的加密原语进行加密的实验性提供者。
• rustls-post-quantum：向默认的 aws-lc-rs 提供者添加支持后量子密钥交换的实验性提供者。

自定义提供者

我们还在 custom-provider 示例中提供了一个编写您自己的提供者的简单示例。此示例使用 RustCrypto 生态系统的部分实现了一个最小化提供者。

有关此主题的更多信息，请参阅文档中的 制作自定义 CryptoProvider 部分。

示例代码

我们的示例目录包含演示如何使用stream::Stream辅助器处理I/O，以及使用mio进行更复杂的异步I/O。如果您已经在使用Tokio作为异步运行时，您可能更愿意使用tokio-rustls而不是直接与rustls交互。

基于mio的示例是最完整的，下面将进行讨论。对于新接触Rustls的用户，在深入研究更复杂的MIO示例之前，可能更喜欢查看简单的客户端/服务器示例。

客户端示例程序

MIO客户端示例程序命名为tlsclient-mio。界面看起来像

Connects to the TLS server at hostname:PORT.  The default PORT
is 443.  By default, this reads a request from stdin (to EOF)
before making the connection.  --http replaces this with a
basic HTTP GET request for /.

If --cafile is not supplied, a built-in set of CA certificates
are used from the webpki-roots crate.

Usage:
  tlsclient-mio [options] [--suite SUITE ...] [--proto PROTO ...] [--protover PROTOVER ...] <hostname>
  tlsclient-mio (--version | -v)
  tlsclient-mio (--help | -h)

Options:
    -p, --port PORT     Connect to PORT [default: 443].
    --http              Send a basic HTTP GET request for /.
    --cafile CAFILE     Read root certificates from CAFILE.
    --auth-key KEY      Read client authentication key from KEY.
    --auth-certs CERTS  Read client authentication certificates from CERTS.
                        CERTS must match up with KEY.
    --protover VERSION  Disable default TLS version list, and use
                        VERSION instead.  May be used multiple times.
    --suite SUITE       Disable default cipher suite list, and use
                        SUITE instead.  May be used multiple times.
    --proto PROTOCOL    Send ALPN extension containing PROTOCOL.
                        May be used multiple times to offer several protocols.
    --no-tickets        Disable session ticket support.
    --no-sni            Disable server name indication support.
    --insecure          Disable certificate verification.
    --verbose           Emit log output.
    --max-frag-size M   Limit outgoing messages to M bytes.
    --version, -v       Show tool version.
    --help, -h          Show this screen.

一些示例运行

$ cargo run --bin tlsclient-mio -- --http mozilla-modern.badssl.com
HTTP/1.1 200 OK
Server: nginx/1.6.2 (Ubuntu)
Date: Wed, 01 Jun 2016 18:44:00 GMT
Content-Type: text/html
Content-Length: 644
(...)

或

$ cargo run --bin tlsclient-mio -- --http expired.badssl.com
TLS error: InvalidCertificate(Expired)
Connection closed

服务器示例程序

MIO服务器示例程序命名为tlsserver-mio。界面看起来像

Runs a TLS server on :PORT.  The default PORT is 443.

`echo' mode means the server echoes received data on each connection.

`http' mode means the server blindly sends a HTTP response on each
connection.

`forward' means the server forwards plaintext to a connection made to
localhost:fport.

`--certs' names the full certificate chain, `--key' provides the
RSA private key.

Usage:
  tlsserver-mio --certs CERTFILE --key KEYFILE [--suite SUITE ...] [--proto PROTO ...] [--protover PROTOVER ...] [options] echo
  tlsserver-mio --certs CERTFILE --key KEYFILE [--suite SUITE ...] [--proto PROTO ...] [--protover PROTOVER ...] [options] http
  tlsserver-mio --certs CERTFILE --key KEYFILE [--suite SUITE ...] [--proto PROTO ...] [--protover PROTOVER ...] [options] forward <fport>
  tlsserver-mio (--version | -v)
  tlsserver-mio (--help | -h)

Options:
    -p, --port PORT     Listen on PORT [default: 443].
    --certs CERTFILE    Read server certificates from CERTFILE.
                        This should contain PEM-format certificates
                        in the right order (the first certificate should
                        certify KEYFILE, the last should be a root CA).
    --key KEYFILE       Read private key from KEYFILE.  This should be a RSA
                        private key or PKCS8-encoded private key, in PEM format.
    --ocsp OCSPFILE     Read DER-encoded OCSP response from OCSPFILE and staple
                        to certificate.  Optional.
    --auth CERTFILE     Enable client authentication, and accept certificates
                        signed by those roots provided in CERTFILE.
    --crl CRLFILE ...   Perform client certificate revocation checking using the DER-encoded
                        CRLFILE. May be used multiple times.
    --require-auth      Send a fatal alert if the client does not complete client
                        authentication.
    --resumption        Support session resumption.
    --tickets           Support tickets.
    --protover VERSION  Disable default TLS version list, and use
                        VERSION instead.  May be used multiple times.
    --suite SUITE       Disable default cipher suite list, and use
                        SUITE instead.  May be used multiple times.
    --proto PROTOCOL    Negotiate PROTOCOL using ALPN.
                        May be used multiple times.
    --verbose           Emit log output.
    --version, -v       Show tool version.
    --help, -h          Show this screen.

这里是一个示例运行；我们启动了一个TLS回声服务器，然后用openssl和tlsclient-mio连接到它

$ cargo run --bin tlsserver-mio -- --certs test-ca/rsa-2048/end.fullchain --key test-ca/rsa-2048/end.key -p 8443 echo &
$ echo hello world | openssl s_client -ign_eof -quiet -connect localhost:8443
depth=2 CN = ponytown RSA CA
verify error:num=19:self signed certificate in certificate chain
hello world
^C
$ echo hello world | cargo run --bin tlsclient-mio -- --cafile test-ca/rsa-2048/ca.cert -p 8443 localhost
hello world
^C

许可证

Rustls根据以下三个许可证分发

• Apache License版本2.0。
• MIT许可证。
• ISC许可证。

这些分别包含为LICENSE-APACHE、LICENSE-MIT和LICENSE-ISC。您可以根据自己的选择在这三种许可证的条款下使用此软件。

项目成员

• Joe Birr-Pixton (@ctz，项目创始人 - 由Prossimo全职资助)
• Dirkjan Ochtman (@djc，共同维护者)
• Daniel McCarney (@cpu，共同维护者 - 由Prossimo全职资助)
• Josh Aas (@bdaehlie，项目管理)

行为准则

本项目采用Rust行为准则。请通过[email protected]发送电子邮件报告任何不当行为，或者如果您对行为准则有任何评论或问题。