Struct KernelConnection

pub struct KernelConnection<Data> { /* private fields */ }

A kernel connection.

This does not directly wrap a kernel connection, rather it gives you the minimal interfaces you need to implement a well-behaved TLS connection on top of kTLS.

See the crate::kernel module docs for more details.

Implementations

impl<Data> KernelConnection<Data>

pub fn negotiated_cipher_suite(&self) -> SupportedCipherSuite

Retrieves the ciphersuite agreed with the peer.

pub fn protocol_version(&self) -> ProtocolVersion

Retrieves the protocol version agreed with the peer.

pub fn update_tx_secret( &mut self, ) -> Result<(u64, ConnectionTrafficSecrets), Error>

Update the traffic secret used for encrypting messages sent to the peer.

Returns the new traffic secret and initial sequence number to use.

In order to use the new secret you should send a TLS 1.3 key update to the peer and then use the new traffic secrets to encrypt any future messages.

Note that it is only possible to update the traffic secrets on a TLS 1.3 connection. Attempting to do so on a non-TLS 1.3 connection will result in an error.

pub fn update_rx_secret( &mut self, ) -> Result<(u64, ConnectionTrafficSecrets), Error>

Update the traffic secret used for decrypting messages received from the peer.

Returns the new traffic secret and initial sequence number to use.

You should call this method once you receive a TLS 1.3 key update message from the peer.

Note that it is only possible to update the traffic secrets on a TLS 1.3 connection. Attempting to do so on a non-TLS 1.3 connection will result in an error.

impl KernelConnection<ClientConnectionData>

pub fn handle_new_session_ticket(&mut self, payload: &[u8]) -> Result<(), Error>

Handle a new_session_ticket message from the peer.

This will register the session ticket within with rustls so that it can be used to establish future TLS connections.

Getting the right payload

This method expects to be passed the inner payload of the handshake message. This means that you will need to parse the header of the handshake message in order to determine the correct payload to pass in. The message format is described in RFC 8446 section 4. payload should not include the msg_type or length fields.

Code to parse out the payload should look something like this

use rustls::{ContentType, HandshakeType};
use rustls::kernel::KernelConnection;
use rustls::client::ClientConnectionData;

let conn: &mut KernelConnection<ClientConnectionData> = // ...
let typ: ContentType = // ...
let mut message: &[u8] = // ...

// Processing for other messages not included in this example
assert_eq!(typ, ContentType::Handshake);

// There may be multiple handshake payloads within a single handshake message.
while !message.is_empty() {
    let (typ, len, rest) = match message {
        &[typ, a, b, c, ref rest @ ..] => (
            HandshakeType::from(typ),
            u32::from_be_bytes([0, a, b, c]) as usize,
            rest
        ),
        _ => panic!("error handling not included in this example")
    };

    // Processing for other messages not included in this example.
    assert_eq!(typ, HandshakeType::NewSessionTicket);
    assert!(rest.len() >= len, "invalid handshake message");

    let (payload, rest) = rest.split_at(len);
    message = rest;

    conn.handle_new_session_ticket(payload)?;
}

Errors

This method will return an error if:

• This connection is not a TLS 1.3 connection (in TLS 1.2 session tickets are sent as part of the handshake).
• The provided payload is not a valid new_session_ticket payload or has extra unparsed trailing data.
• An error occurs while the connection updates the session ticket store.