rust/rustls
rust
/
rustls
mirror of https://github.com/ctz/rustls
1
0
Fork 0
Code Issues Releases Wiki Activity

doc: update docs for SigningKey 

Explain why the implementors section for SigningKey is empty, where
SigningKey comes from, and what it is consumed by.

Update the functions that document encodings for loading private keys so
they are more specific and concrete.
This commit is contained in:
Jacob Hoffman-Andrews 2023-11-21 13:27:46 -08:00 committed by Daniel McCarney
parent 1db4506dcf
commit 96d1691b35
3 changed files with 49 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
rustls/src/client/builder.rs
View File

@ -112,9 +112,9 @@ impl ConfigBuilder<ClientConfig, WantsClientCert> {
/// in client authentication.
///
/// `cert_chain` is a vector of DER-encoded certificates.
/// `key_der` is a DER-encoded private key -- the precise set of supported key
/// types and parameters is defined by the selected [`CryptoProvider`]'s `load_private_key()`
/// method.
/// `key_der` is a DER-encoded private key as PKCS#1, PKCS#8, or SEC1. The
/// `aws-lc-rs` and `ring` [`CryptoProvider`]s support all three encodings,
/// but other `CryptoProviders` may not.
///
/// This function fails if `key_der` is invalid.
pub fn with_client_auth_cert(

40
rustls/src/crypto/signer.rs
View File

@ -12,6 +12,46 @@ use core::fmt::Debug;
///
/// This interface is used by rustls to use a private signing key
/// for authentication. This includes server and client authentication.
///
/// Objects of this type are always used within Rustls as
/// `Arc<dyn SigningKey>`. There are no concrete public structs in Rustls
/// that implement this trait.
///
/// There are two main ways to get a signing key:
///
/// - [`CryptoProvider::load_private_key()`], or
/// - some other method outside of the `CryptoProvider` extension trait,
/// for instance:
/// - [`crypto::ring::sign::any_ecdsa_type()`]
/// - [`crypto::ring::sign::any_eddsa_type()`]
/// - [`crypto::ring::sign::any_supported_type()`]
/// - [`crypto::aws_lc_rs::sign::any_ecdsa_type()`]
/// - [`crypto::aws_lc_rs::sign::any_eddsa_type()`]
/// - [`crypto::aws_lc_rs::sign::any_supported_type()`]
///
/// The `CryptoProvider` method `load_private_key()` is called under the hood by
/// [`ConfigBuilder::with_single_cert()`],
/// [`ConfigBuilder::with_client_auth_cert()`], and
/// [`ConfigBuilder::with_single_cert_with_ocsp()`].
///
/// A signing key created outside of the `CryptoProvider` extension trait can be used
/// to create a [`CertifiedKey`], which in turn can be used to create a
/// [`ResolvesServerCertUsingSni`]. Alternately, a `CertifiedKey` can be returned from a
/// custom implementation of the [`ResolvesServerCert`] or [`ResolvesClientCert`] traits.
///
/// [`CryptoProvider::load_private_key()`]: crate::crypto::CryptoProvider::load_private_key
/// [`ConfigBuilder::with_single_cert()`]: crate::ConfigBuilder::with_single_cert
/// [`ConfigBuilder::with_single_cert_with_ocsp()`]: crate::ConfigBuilder::with_single_cert_with_ocsp
/// [`ConfigBuilder::with_client_auth_cert()`]: crate::ConfigBuilder::with_client_auth_cert
/// [`crypto::ring::sign::any_ecdsa_type()`]: crate::crypto::ring::sign::any_ecdsa_type
/// [`crypto::ring::sign::any_eddsa_type()`]: crate::crypto::ring::sign::any_eddsa_type
/// [`crypto::ring::sign::any_supported_type()`]: crate::crypto::ring::sign::any_supported_type
/// [`crypto::aws_lc_rs::sign::any_ecdsa_type()`]: crate::crypto::aws_lc_rs::sign::any_ecdsa_type
/// [`crypto::aws_lc_rs::sign::any_eddsa_type()`]: crate::crypto::aws_lc_rs::sign::any_eddsa_type
/// [`crypto::aws_lc_rs::sign::any_supported_type()`]: crate::crypto::aws_lc_rs::sign::any_supported_type
/// [`ResolvesServerCertUsingSni`]: crate::server::ResolvesServerCertUsingSni
/// [`ResolvesServerCert`]: crate::server::ResolvesServerCert
/// [`ResolvesClientCert`]: crate::client::ResolvesClientCert
pub trait SigningKey: Debug + Send + Sync {
/// Choose a `SignatureScheme` from those offered.
///

12
rustls/src/server/builder.rs
View File

@ -62,9 +62,9 @@ impl ConfigBuilder<ServerConfig, WantsServerCert> {
/// disregarded.
///
/// `cert_chain` is a vector of DER-encoded certificates.
/// `key_der` is a DER-encoded private key -- the precise set of supported key
/// types and parameters is defined by the selected [`CryptoProvider`]'s `load_private_key()`
/// method.
/// `key_der` is a DER-encoded private key as PKCS#1, PKCS#8, or SEC1. The
/// `aws-lc-rs` and `ring` [`CryptoProvider`]s support all three encodings,
/// but other `CryptoProviders` may not.
///
/// This function fails if `key_der` is invalid.
pub fn with_single_cert(
@ -85,9 +85,9 @@ impl ConfigBuilder<ServerConfig, WantsServerCert> {
/// subsequent connections, irrespective of things like SNI hostname.
///
/// `cert_chain` is a vector of DER-encoded certificates.
/// `key_der` is a DER-encoded private key -- the precise set of supported key
/// types and parameters is defined by the selected [`CryptoProvider`]'s `load_private_key()`
/// method.
/// `key_der` is a DER-encoded private key as PKCS#1, PKCS#8, or SEC1. The
/// `aws-lc-rs` and `ring` [`CryptoProvider`]s support all three encodings,
/// but other `CryptoProviders` may not.
/// `ocsp` is a DER-encoded OCSP response. Ignored if zero length.
///
/// This function fails if `key_der` is invalid.