结构体 CryptoProvider 

pub struct CryptoProvider {
    pub cipher_suites: Vec<SupportedCipherSuite>,
    pub kx_groups: Vec<&'static dyn SupportedKxGroup>,
    pub signature_verification_algorithms: WebPkiSupportedAlgorithms,
    pub secure_random: &'static dyn SecureRandom,
    pub key_provider: &'static dyn KeyProvider,
}

Controls core cryptography 用于 rustls.

此 crate 提供两个内置选项，分别为： CryptoProvider structures:

• [crypto::aws_lc_rs::default_provider]: (behind the aws_lc_rs crate feature, which is enabled by default). This provider uses the aws-lc-rs crate. The fips crate feature makes this option use FIPS140-3-approved cryptography.
• crypto::ring::default_provider: (behind the ring crate feature, which is optional). This provider uses the ring crate.

此结构体提供默认值。其中的所有内容都可在 运行时根据需要替换字段值来覆盖。

Using the per-process default CryptoProvider

There 是 concept of an implicit 默认提供者, configured at run-time once in 一个 given process.

It is 用 用于 functions like ClientConfig::builder() 并 ServerConfig::builder()。

此 intention is that an application can specify the CryptoProvider they wish 到 use once, 并 have that apply 到 the variety of places where their application does TLS (which may be wrapped inside other libraries)。 They should do this by calling CryptoProvider::install_default() early on.

为实现此目标：

• libraries should use ClientConfig::builder()/ServerConfig::builder() or otherwise rely on the CryptoProvider::get_default() provider.
• applications should call CryptoProvider::install_default() early in their fn main(). If applications uses a custom provider based on the one built-in, they can activate the custom-provider feature to ensure its usage.

Using a specific CryptoProvider

Supply the provider when constructing your ClientConfig 或 ServerConfig:

• ClientConfig::builder_with_provider()
• ServerConfig::builder_with_provider()

When creating 并 configuring 一个 webpki-backed client 或 server certificate verifier, 一个 choice of provider 也 needed 到 start the configuration process:

• client::WebPkiServerVerifier::builder_with_provider()
• server::WebPkiClientVerifier::builder_with_provider()

If you install 一个 custom provider 并 want 到 avoid any accidental use of 一个 built-in provider, the feature custom-provider can be activated 到 ensure your custom provider is 用 everywhere 并 not 一个 built-in one. This will disable any implicit use of 一个 built-in provider.

Making a custom CryptoProvider

Your goal ， 到 populate an instance of this CryptoProvider struct.

Which elements are required?

There is no requirement that the individual elements (SupportedCipherSuite, SupportedKxGroup, SigningKey, etc.) come 从 the same crate. It is allowed 并 expected that uninteresting elements would be delegated back 到 one of 默认 providers (statically) 或 一个 parent provider (dynamically)。

For example, if we want 到 make 一个 provider that just overrides key loading in the config builder API (with ConfigBuilder::with_single_cert, etc.), it might look like this:

use rustls::crypto::aws_lc_rs;

pub fn provider() -> rustls::crypto::CryptoProvider {
  rustls::crypto::CryptoProvider{
    key_provider: &HsmKeyLoader,
    ..aws_lc_rs::default_provider()
  }
}

#[derive(Debug)]
struct HsmKeyLoader;

impl rustls::crypto::KeyProvider for HsmKeyLoader {
    fn load_private_key(&self, key_der: pki_types::PrivateKeyDer<'static>) -> Result<Arc<dyn rustls::sign::SigningKey>, rustls::Error> {
         fictious_hsm_api::load_private_key(key_der)
    }
}

References to the individual elements

此 elements are documented separately:

• Random - see crypto::SecureRandom::fill().
• Cipher suites - see SupportedCipherSuite, [Tls12CipherSuite], and Tls13CipherSuite.
• Key exchange groups - see crypto::SupportedKxGroup.
• Signature verification algorithms - see crypto::WebPkiSupportedAlgorithms.
• Authentication key loading - see crypto::KeyProvider::load_private_key() and sign::SigningKey.

Example code

See custom provider-example/ for a full client and server example that uses cryptography 从 the RustCrypto and dalek-cryptography projects.

$ cargo run --example client | head -3
Current ciphersuite: TLS13_CHACHA20_POLY1305_SHA256
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 19899

FIPS-approved cryptography

此 fips crate feature enables use of the aws-lc-rs crate in FIPS mode.

You can verify the configuration at runtime by checking ServerConfig::fips()/ClientConfig::fips() return true。

字段

cipher_suites: Vec<SupportedCipherSuite>

List of supported ciphersuites, in preference order – the first element 是 highest priority.

此 SupportedCipherSuite type carries both configuration 并 implementation.

A valid CryptoProvider must ensure that all cipher suites are accompanied by at least one matching key exchange group in CryptoProvider::kx_groups。

kx_groups: Vec<&'static dyn SupportedKxGroup>

List of supported key exchange groups, in preference order – the first element 是 highest priority.

此 first element in this list 是 default key share 算法, 并 in TLS 1.3 一个 key share 用于 it is sent in the client hello.

此 SupportedKxGroup type carries both configuration 并 implementation.

signature_verification_algorithms: WebPkiSupportedAlgorithms

List of signature verification algorithms 用于 use with webpki.

These are 用 用于 both certificate chain verification 并 handshake signature verification.

This is called by ConfigBuilder::with_root_certificates(), server::WebPkiClientVerifier::builder_with_provider() 并 client::WebPkiServerVerifier::builder_with_provider()。

secure_random: &'static dyn SecureRandom

加密安全的随机数源。

key_provider: &'static dyn KeyProvider

Provider 用于 loading private SigningKeys 从 PrivateKeyDer。

实现

impl CryptoProvider

pub fn install_default(self) -> Result<(), Arc<Self>>

Sets this CryptoProvider as 默认 用于 this process.

This can be called successfully at most once in any process execution.

Call this early in your process 到 configure which provider is 用 用于 the provider. 此 configuration should happen before any use of ClientConfig::builder() 或 ServerConfig::builder()。

pub fn get_default() -> Option<&'static Arc<Self>>

Returns 默认 CryptoProvider 用于 this process.

This ， None if no default has been set yet.

pub fn fips(&self) -> bool

Returns true if this CryptoProvider is operating in FIPS mode.

This covers only the cryptographic parts of FIPS approval. There are also TLS protocol-level recommendations made by NIST. You should prefer 到 call ClientConfig::fips() 或 ServerConfig::fips() which take these into account.

Trait 实现

impl Clone for CryptoProvider

fn clone(&self) -> CryptoProvider

返回值的副本。 更多信息

fn clone_from(&mut self, source: &Self)

Performs copy-assignment 从 source. 更多信息

impl Debug for CryptoProvider

fn fmt(&self, f: &mut Formatter<'_>) -> Result

使用给定的格式化器格式化此值。 更多信息