Lib.rs

› 加密学 | 网络编程
#rustls #tls #client-server #tls-client #tls-server #provider #ring

无需std clia-rustls-mod

Rustls是用Rust编写的现代TLS库。这是使用ring的clia-mod。

所有者 Cris Liao.

1个不稳定版本

0.23.4 2024年3月28日

#1389 in 加密学

Apache-2.0 OR ISC OR MIT

1MB
26K SLoC

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

状态

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

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

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

Build Status Coverage Status (codecov.io) Documentation Chat

变更日志

每个版本中更改的详细列表可以在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.61 或更高版本。

加密提供者

从 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 开发第三方提供者

自定义提供者

我们还提供了一个简单的示例，说明如何在 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/end.fullchain --key test-ca/rsa/end.rsa -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/ca.cert -p 8443 localhost
hello world
^C

许可证

Rustls 在以下三个许可证下分发

  • Apache License version 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] 报告任何不当行为，或者如果您对行为准则有任何评论或疑问。

依赖关系

~6–27MB
~640K SLoC