ic-rustls 0.2.4

IronCrypto as a rustls CryptoProvider
Documentation

IronCrypto as a rustls CryptoProvider.

# fn main() -> Result<(), rustls::Error> {
let roots = rustls::RootCertStore::empty();
let config = rustls::ClientConfig::builder_with_provider(ic_rustls::arc_provider())
    .with_safe_default_protocol_versions()?
    .with_root_certificates(roots)
    .with_no_client_auth();
# let _ = config;
# Ok(())
# }

Or install it once, for every rustls configuration in the process:

ic_rustls::provider()
    .install_default()
    .expect("a provider was already installed in this process");

This crate has a third-party dependency, and it is the only one that does

Every other crate in this workspace depends on nothing outside it. That is asserted on each build by scripts/no-third-party.sh, and the SBOM, CWE-1104 and T1195.001 all rest on it.

A rustls provider cannot: it exists to implement rustls's traits, so it must depend on rustls, and rustls brings rustls-pki-types, rustls-webpki, subtle, untrusted, once_cell and zeroize with it -- seven crates in total, which is what scripts/no-third-party.sh allows by name and scripts/advisories.sh holds to a version floor. Rather than weaken the check, the boundary is drawn here. This crate is excluded by name, the exclusion is one line with a reason beside it, and everything cryptographic stays on the other side: ic-core, ic-hash, ic-mac, ic-cipher, ic-drbg, ic-ec and ic-pkix are unchanged and still depend on nothing.

So the guarantee narrows honestly instead of quietly. If you need it whole, do not depend on this crate; the algorithms are reachable directly.

What is provided
AEAD AES-128-GCM, AES-256-GCM and ChaCha20-Poly1305, for TLS 1.3 and TLS 1.2
Hash SHA-256, SHA-384
MAC HMAC-SHA256, HMAC-SHA384
KDF HKDF, as rustls's HkdfUsingHmac over the above
Signatures ECDSA P-256/SHA-256 and P-384/SHA-384; Ed25519; RSA PKCS#1 v1.5 and PSS over SHA-256/384/512. All verified and produced
Key exchange X25519, ECDH P-256, ECDH P-384
Randomness SP 800-90A HMAC_DRBG, seeded from the OS
QUIC Packet and header protection for all three AEADs, RFC 9001

HKDF is rustls's own extract-and-expand over IronCrypto's HMAC, which is the right split: HKDF is a construction and HMAC is the primitive. The result is checked against RFC 5869 in the hmac module's tests, so the composition is verified and not just assumed.

What is not provided

  • RSA below 2048 bits. Refused, deliberately, when verifying and when loading a key to sign with. See crate::verify.
  • The mismatched ECDSA pairings. A P-256 key signed with SHA-384, or the reverse. See crate::verify.
  • FIPS validation. Every fips() in this crate returns false, because rustls is asking about a certificate and IronCrypto holds none.