Trait rustls::crypto::ActiveKeyExchange

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>> { ... }
}

An in-progress key exchange originating from a SupportedKxGroup.

Required Methods

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.

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.

fn group(&self) -> NamedGroup

Return the group being used.

Provided Methods

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.

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