Trait rustls::crypto::ActiveKeyExchange

source ·
pub trait ActiveKeyExchange: Send + Sync {
    // Required methods
    fn complete(
        self: Box<Self>,
        peer_pub_key: &[u8],
    ) -> Result<SharedSecret, Error>;
    fn pub_key(&self) -> &[u8] ;
    fn group(&self) -> NamedGroup;

    // Provided methods
    fn complete_for_tls_version(
        self: Box<Self>,
        peer_pub_key: &[u8],
        tls_version: &SupportedProtocolVersion,
    ) -> Result<SharedSecret, Error> { ... }
    fn ffdhe_group(&self) -> Option<FfdheGroup<'static>> { ... }
}
Expand description

An in-progress key exchange originating from a SupportedKxGroup.

Required Methods§

source

fn complete(self: Box<Self>, peer_pub_key: &[u8]) -> Result<SharedSecret, Error>

Completes the key exchange, given the peer’s public key.

This method must return an error if peer_pub_key is invalid: either mis-encoded, or an invalid public key (such as, but not limited to, being in a small order subgroup).

If the key exchange algorithm is FFDHE, the result must be left-padded with zeros, as required by RFC 8446 (see complete_for_tls_version() for more details).

The shared secret is returned as a SharedSecret which can be constructed from a &[u8].

This consumes and so terminates the ActiveKeyExchange.

source

fn pub_key(&self) -> &[u8]

Return the public key being used.

For ECDHE, the encoding required is defined in RFC8446 section 4.2.8.2.

For FFDHE, the encoding required is defined in RFC8446 section 4.2.8.1.

source

fn group(&self) -> NamedGroup

Return the group being used.

Provided Methods§

source

fn complete_for_tls_version( self: Box<Self>, peer_pub_key: &[u8], tls_version: &SupportedProtocolVersion, ) -> Result<SharedSecret, Error>

Completes the key exchange for the given TLS version, given the peer’s public key.

Note that finite-field Diffie–Hellman key exchange has different requirements for the derived shared secret in TLS 1.2 and TLS 1.3 (ECDHE key exchange is the same in TLS 1.2 and TLS 1.3):

In TLS 1.2, the calculated secret is required to be stripped of leading zeros (RFC 5246).

In TLS 1.3, the calculated secret is required to be padded with leading zeros to be the same byte-length as the group modulus (RFC 8446).

The default implementation of this method delegates to complete() assuming it is implemented for TLS 1.3 (i.e., for FFDHE KX, removes padding as needed). Implementers of this trait are encouraged to just implement complete() assuming TLS 1.3, and let the default implementation of this method handle TLS 1.2-specific requirements.

This method must return an error if peer_pub_key is invalid: either mis-encoded, or an invalid public key (such as, but not limited to, being in a small order subgroup).

The shared secret is returned as a SharedSecret which can be constructed from a &[u8].

This consumes and so terminates the ActiveKeyExchange.

source

fn ffdhe_group(&self) -> Option<FfdheGroup<'static>>

FFDHE group the ActiveKeyExchange is operating in.

Return None if this group is not a FFDHE one.

The default implementation calls FfdheGroup::from_named_group: this function is extremely linker-unfriendly so it is recommended all key exchange implementers provide this function.

rustls::ffdhe_groups contains suitable values to return from this, for example rustls::ffdhe_groups::FFDHE2048.

Implementors§