Skip to main content

Connection

rustls

Trait Connection 

Source 
pub trait Connection: Debug + Deref<Target = ConnectionOutputs> {
    type Side: SideData;

    // Required methods
    fn write_tls(
        &mut self,
        plaintext: OutboundPlain<'_>,
        tls: &mut Vec<u8>,
    ) -> Result<(), Error>;
    fn wants_read(&self) -> bool;
    fn process_new_packets<'a, 'm>(
        &'a mut self,
        input: &'m mut dyn TlsInputBuffer,
        tls: &'a mut Vec<u8>,
    ) -> MessageHandler<'a, 'm, Self::Side>;
    fn exporter(&mut self) -> Result<KeyingMaterialExporter, Error>;
    fn dangerous_extract_secrets(self) -> Result<ExtractedSecrets, Error>;
    fn refresh_traffic_keys(&mut self, tls: &mut Vec<u8>) -> Result<(), Error>;
    fn send_close_notify(&mut self, tls: &mut Vec<u8>);
    fn is_handshaking(&self) -> bool;
    fn fips(&self) -> FipsStatus;
}
Expand description

A trait generalizing over buffered client or server connections.

Required Associated Types§

Source

type Side: SideData

The side (client or server) that this type implements.

Required Methods§

Source

fn write_tls( &mut self, plaintext: OutboundPlain<'_>, tls: &mut Vec<u8>, ) -> Result<(), Error>

Writes the application data from plaintext into TLS records and appends them to tls.

This will fail if either the handshake is not complete yet (because we don’t yet have the keys to encrypt application data) or if the send path has been closed by sending a close_notify alert.

Source

fn wants_read(&self) -> bool

Returns true if the caller should call Self::process_new_packets() as soon as possible.

Source

fn process_new_packets<'a, 'm>( &'a mut self, input: &'m mut dyn TlsInputBuffer, tls: &'a mut Vec<u8>, ) -> MessageHandler<'a, 'm, Self::Side>

Build a MessageHandler to process messages from the input buffer.

Source

fn exporter(&mut self) -> Result<KeyingMaterialExporter, Error>

Returns an object that can derive key material from the agreed connection secrets.

See RFC 5705 for more details on what this is for.

This function can be called at most once per connection.

This function will error:

  • if called prior to the handshake completing; (check with Self::is_handshaking() first).
  • if called more than once per connection.
Source

fn dangerous_extract_secrets(self) -> Result<ExtractedSecrets, Error>

Extract secrets, so they can be used when configuring kTLS, for example.

Should be used with care as it exposes secret key material.

Source

fn refresh_traffic_keys(&mut self, tls: &mut Vec<u8>) -> Result<(), Error>

Sends a TLS1.3 key_update message into tls to refresh a connection’s keys.

The main reason to call this manually is to roll keys when it is known a connection will be idle for a long period.

rustls implicitly and automatically refreshes traffic keys when needed according to the selected cipher suite’s cryptographic constraints. There is therefore no need to call this manually to avoid cryptographic keys “wearing out”.

This call refreshes our encryption keys. Once the peer receives the message, it refreshes its encryption and decryption keys and sends a response. Once we receive that response, we refresh our decryption keys to match. At the end of this process, keys in both directions have been refreshed.

This fails with Error::HandshakeNotComplete if called before the initial handshake is complete, or if a version prior to TLS1.3 is negotiated.

§Usage advice

Note that other implementations (including rustls) may enforce limits on the number of key_update messages allowed on a given connection to prevent denial of service. Therefore, this should be called sparingly.

rustls only allows one outstanding request at a time; this function succeeds but sends nothing if a request is already in-flight.

Source

fn send_close_notify(&mut self, tls: &mut Vec<u8>)

Writes a close_notify warning alert into tls.

This informs the peer that the connection is being closed.

Does nothing if any close_notify or fatal alert was already sent.

Source

fn is_handshaking(&self) -> bool

Returns true if the connection is currently performing the TLS handshake.

During this time, Self::write_tls() will return an error.

Source

fn fips(&self) -> FipsStatus

Return the FIPS validation status of the connection.

This is different from CryptoProvider::fips(): it is concerned only with cryptography, whereas this also covers TLS-level configuration that NIST recommends, as well as ECH HPKE suites if applicable.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§