Struct ArcKeys

pub struct ArcKeys(/* private fields */);

Long packet keys, for encryption and decryption keys for those long packets, as well as keys for adding and removing long packet header protection.

• When sending, obtain the local keys for packet encryption and adding header protection. If the keys are not ready, skip sending the packet of this level immidiately.
• When receiving a packet and decrypting it, obtain the remote keys for removing header protection and packet decryption. If the keys are not ready, wait asynchronously until the keys to be ready to continue.

Note

The keys for 1-RTT packets are a separate structure, see ArcOneRttKeys.

Implementations

impl ArcKeys

pub fn new_pending() -> Self

Create a Pending state ArcKeys.

For a new Quic connection, initially only the Initial key is known, and the 0-RTT and Handshake keys are unknown. Therefore, the 0-RTT and Handshake keys can be created in a Pending state, waiting for updates during the TLS handshake process.

pub fn with_keys(keys: Keys) -> Self

Create an ArcKeys with a specified rustls::quic::Keys.

The initial keys are known at first, can use this method to create the ArcKeys.

pub fn get_remote_keys(&self) -> GetRemoteKeys<'_>

Asynchronously obtain the remote keys for removing header protection and packet decryption.

Rreturn GetRemoteKeys, which implemented Future trait.

Example

The following is only a demonstration. In fact, removing header protection and decrypting packets are far more complex!

use qbase::packet::keys::ArcKeys;

async fn decrypt_demo(keys: ArcKeys, cipher_text: &mut [u8]) {
    let Some(keys) = keys.get_remote_keys().await else {
        return;
    };

    let hpk = keys.remote.header.as_ref();
    let pk = keys.remote.packet.as_ref();

    // use hpk to remove header protection...
    // use pk to decrypt packet body...
}

pub fn get_local_keys(&self) -> Option<Arc<Keys>>

Get the local keys for packet encryption and adding header protection. If the keys is not ready, just return None immediately.

Example

The following is only a demonstration. In fact, encrypting packets and adding header protection are far more complex!

use qbase::packet::keys::ArcKeys;

fn encrypt_demo(keys: ArcKeys, plain_text: &mut [u8]) {
    let Some(keys) = keys.get_local_keys() else {
        return;
    };

    let hpk = keys.local.header.as_ref();
    let pk = keys.local.packet.as_ref();

    // use pk to encrypt packet body...
    // use hpk to add header protection...
}

pub fn set_keys(&self, keys: Keys)

Set the keys to the ArcKeys.

As the TLS handshake progresses, higher-level keys will be obtained. These keys are set to the related ArcKeys through this method, and its internal waker will be awakened to notify the packet decryption task to continue, if the internal waker was registered.

pub fn invalid(&self) -> Option<Arc<Keys>>

Retire the keys, which means that the keys are no longer available.

This is used when the connection enters the closing state or draining state. Especially in the closing state, the return keys are used to generate the final packet containing the ConnectionClose frame, and decrypt the data packets received from the peer for a while.

Trait Implementations

impl Clone for ArcKeys

fn clone(&self) -> ArcKeys

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.