1 unstable release
0.1.0 | Apr 23, 2024 |
---|
#1813 in Cryptography
64 downloads per month
74KB
1K
SLoC
SymCrypt Provider for Rustls
This crate provides integration for using SymCrypt
cryptographic functionalities with the rustls
crate, by implementing the required traits specified by rustls
.
Platform Support
- Windows AMD64: Full support.
- Azure Linux: Full support.
- Ubuntu: Partial support. While tested, full compatibility and optimal performance on all Ubuntu environments cannot be guaranteed.
Limitations
- QUIC Protocol: Not supported.
- Integration Efforts: Ongoing integration with rustls-cng and rustls-platform-verifier.
Supported Ciphers
Supported cipher suites are listed below, ordered by preference. IE: The default configuration prioritizes TLS13_AES_256_GCM_SHA384
over TLS13_AES_128_GCM_SHA256
.
TLS 1.3
TLS13_AES_256_GCM_SHA384
TLS13_AES_128_GCM_SHA256
TLS13_CHACHA20_POLY1305_SHA256 // Enabled with the `chacha` feature
Note: TLS13_CHACHA20_POLY1305_SHA256
is disabled by default. Enable the chacha
feature in your Cargo.toml
to use this cipher suite.
TLS 1.2
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 // Enabled with the `chacha` feature
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 // Enabled with the `chacha` feature
Note: TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
and TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
are disabled by default. Enable the chacha
feature in your Cargo.toml
to use this cipher suite.
Supported Key Exchanges
Key exchanges are listed below, ordered by preference. IE: SECP384R1
is preferred over SECP256R1
.
SECP384R1
SECP256R1
X25519 // Enabled with the `x25519` feature
Note: X25519
is disabled by default. To enable, add x25519
feature in your Cargo.toml
.
Dependencies
This crate depends on the symcrypt crate and requires you have the necessary symcrypt
binaries for your architecture.
Refer to the rust-symcrypt Quick Start Guide to download the required binaries.
Usage
Add rustls-symcrypt
to your Cargo.toml
:
Note: If you wish to enable x25519
or chacha
you may add it as a feature at this time.
[dependencies]
# Disabling aws-lc as it slows down build times and is not needed.
rustls = { version = "0.23.0", features = ["ring", "tls12", "std"], default-features = false }
rustls_symcrypt = "0.1.0"
# To enable the chacha feature:
# rustls_symcrypt = {version = "0.1.0", features = ["chacha"]}
Default Configuration
Use default_symcrypt_provider()
for a ClientConfig
that utilizes the default cipher suites and key exchange groups listed above:
use rustls::{ClientConfig, RootCertStore};
use rustls_symcrypt::default_symcrypt_provider;
use std::sync::Arc;
use webpki_roots;
fn main() {
let mut root_store = RootCertStore {
roots: webpki_roots::TLS_SERVER_ROOTS.iter().cloned().collect(),
};
let mut config =
ClientConfig::builder_with_provider(Arc::new(default_symcrypt_provider()))
.with_safe_default_protocol_versions()
.unwrap()
.with_root_certificates(root_store)
.with_no_client_auth();
// Rest of the connection setup
}
Custom Configuration
To modify or change the order of negotiated cipher suites for ClientConfig
, use custom_symcrypt_provider()
.
use rustls::{ClientConfig, RootCertStore};
use rustls_symcrypt::{custom_symcrypt_provider, TLS13_AES_128_GCM_SHA256, SECP256R1};
use std::sync::Arc;
use webpki_roots;
fn main() {
let mut root_store = RootCertStore {
roots: webpki_roots::TLS_SERVER_ROOTS.iter().cloned().collect(),
};
// Set custom config of cipher suites that have been imported from rustls_symcrypt.
let cipher_suites = vec![TLS13_AES_128_GCM_SHA256];
let kx_group = vec![SECP256R1];
let mut config =
ClientConfig::builder_with_provider(Arc::new(custom_symcrypt_provider(
Some(cipher_suites), Some(kx_group))))
.with_safe_default_protocol_versions()
.unwrap()
.with_root_certificates(root_store)
.with_no_client_auth();
// Rest of the connection setup
}
Dependencies
~17–28MB
~542K SLoC