rustls

Module kernel

Source
Expand description

Kernel connection API.

This module gives you the bare minimum you need to implement a TLS connection that does its own encryption and decryption while still using rustls to manage connection secrets and session tickets. It is intended for use cases like kTLS where you want to use rustls to establish the connection but want to use something else to do the encryption/decryption after that.

There are only two things that KernelConnection is able to do:

  1. Compute new traffic secrets when a key update occurs.
  2. Save received session tickets sent by a server peer.

That’s it. Everything else you will need to implement yourself.

§Entry Point

The entry points into this API are UnbufferedClientConnection::dangerous_into_kernel_connection and UnbufferedServerConnection::dangerous_into_kernel_connection.

In order to actually create an KernelConnection all of the following must be true:

  • the connection must have completed its handshake,
  • the connection must have no buffered TLS data waiting to be sent, and,
  • the config used to create the connection must have enable_extract_secrets set to true.

This sounds fairly complicated to achieve at first glance. However, if you drive an unbuffered connection through the handshake until it returns WriteTraffic then it will end up in an appropriate state to convert into an external connection.

§Cipher Suite Confidentiality Limits

Some cipher suites (notably AES-GCM) have vulnerabilities where they are no longer secure once a certain number of messages have been sent. Normally, rustls tracks how many messages have been written or read and will automatically either refresh keys or emit an error when approaching the confidentiality limit of the cipher suite.

KernelConnection has no way to track this. It is the responsibility of the user of the API to track approximately how many messages have been sent and either refresh the traffic keys or abort the connection before the confidentiality limit is reached.

You can find the current confidentiality limit by looking at CipherSuiteCommon::confidentiality_limit for the cipher suite selected by the connection.

Structs§

KernelConnection
A kernel connection.