rustls/client/

ech.rs

use alloc::boxed::Box;
use alloc::vec;
use alloc::vec::Vec;
use core::iter;

use pki_types::{DnsName, EchConfigListBytes, FipsStatus, ServerName};
use subtle::ConstantTimeEq;

use super::config::ClientConfig;
use super::{Retrieved, Tls13Session, tls13};
use crate::common_state::Protocol;
use crate::crypto::cipher::{EncodableVersion, Payload};
use crate::crypto::hash::Hash;
use crate::crypto::hpke::{
    EncapsulatedSecret, Hpke, HpkeKem, HpkePublicKey, HpkeSealer, HpkeSuite,
    HpkeSymmetricCipherSuite,
};
use crate::crypto::{CipherSuite, SecureRandom};
use crate::enums::ProtocolVersion;
use crate::error::{EncryptedClientHelloError, Error, PeerMisbehaved, RejectedEch};
use crate::hash_hs::{HandshakeHash, HandshakeHashBuffer};
use crate::msgs::{
    ClientExtensions, ClientHelloPayload, Codec, EchConfigContents, EchConfigPayload, Encoding,
    EncryptedClientHello, EncryptedClientHelloOuter, ExtensionType, HandshakeAlignedProof,
    HandshakeMessagePayload, HandshakePayload, HelloRetryRequest, HpkeKeyConfig, Message,
    MessagePayload, PresharedKeyBinder, PresharedKeyIdentity, PresharedKeyOffer, Random,
    ServerHelloPayload, ServerNamePayload, SizedPayload,
};
use crate::tls13::Tls13CipherSuite;
use crate::tls13::key_schedule::{
    KeyScheduleEarlyClient, KeyScheduleHandshakeStart, server_ech_hrr_confirmation_secret,
};
use crate::tracing::{debug, trace, warn};

/// Controls how Encrypted Client Hello (ECH) is used in a client handshake.
#[non_exhaustive]
#[derive(Clone, Debug)]
pub enum EchMode {
    /// ECH is enabled and the ClientHello will be encrypted based on the provided
    /// configuration.
    Enable(EchConfig),

    /// No ECH configuration is available but the client should act as though it were.
    ///
    /// This is an anti-ossification measure, sometimes referred to as "GREASE"[^0].
    /// [^0]: <https://www.rfc-editor.org/rfc/rfc8701>
    Grease(EchGreaseConfig),
}

impl EchMode {
    /// Returns the FIPS status of the HPKE suite that will be used.
    pub fn fips(&self) -> FipsStatus {
        match self {
            Self::Enable(ech_config) => ech_config.suite.fips(),
            Self::Grease(grease_config) => grease_config.suite.fips(),
        }
    }
}

impl From<EchConfig> for EchMode {
    fn from(config: EchConfig) -> Self {
        Self::Enable(config)
    }
}

impl From<EchGreaseConfig> for EchMode {
    fn from(config: EchGreaseConfig) -> Self {
        Self::Grease(config)
    }
}

/// Configuration for performing encrypted client hello.
///
/// Note: differs from the protocol-encoded EchConfig (`EchConfigMsg`).
#[derive(Clone, Debug)]
pub struct EchConfig {
    /// The selected EchConfig.
    pub(crate) config: EchConfigPayload,

    /// An HPKE instance corresponding to a suite from the `config` we have selected as
    /// a compatible choice.
    pub(crate) suite: &'static dyn Hpke,
}

impl EchConfig {
    /// Construct an EchConfig by selecting a ECH config from the provided bytes that is compatible
    /// with one of the given HPKE suites.
    ///
    /// The config list bytes should be sourced from a DNS-over-HTTPS lookup resolving the `HTTPS`
    /// resource record for the host name of the server you wish to connect via ECH,
    /// and extracting the ECH configuration from the `ech` parameter. The extracted bytes should
    /// be base64 decoded to yield the `EchConfigListBytes` you provide to rustls.
    ///
    /// One of the provided ECH configurations must be compatible with the HPKE provider's supported
    /// suites or an error will be returned.
    ///
    /// See the [`ech-client.rs`] example for a complete example of fetching ECH configs from DNS.
    ///
    /// [`ech-client.rs`]: https://github.com/rustls/rustls/blob/main/examples/src/bin/ech-client.rs
    pub fn new(
        ech_config_list: EchConfigListBytes<'_>,
        hpke_suites: &[&'static dyn Hpke],
    ) -> Result<Self, Error> {
        let ech_configs = Vec::<EchConfigPayload>::read_bytes(&ech_config_list).map_err(|_| {
            Error::InvalidEncryptedClientHello(EncryptedClientHelloError::InvalidConfigList)
        })?;

        Self::new_for_configs(ech_configs, hpke_suites)
    }

    /// Build an EchConfig for retrying ECH using a retry config from a server's previous rejection
    ///
    /// Returns an error if the server provided no retry configurations in `RejectedEch`, or if
    /// none of the retry configurations are compatible with the supported `hpke_suites`.
    pub fn for_retry(
        rejection: RejectedEch,
        hpke_suites: &[&'static dyn Hpke],
    ) -> Result<Self, Error> {
        let Some(configs) = rejection.retry_configs else {
            return Err(EncryptedClientHelloError::NoCompatibleConfig.into());
        };

        Self::new_for_configs(configs, hpke_suites)
    }

    pub(super) fn state(
        &self,
        server_name: ServerName<'static>,
        config: &ClientConfig,
    ) -> Result<EchState, Error> {
        EchState::new(
            self,
            server_name,
            !config
                .resolver()
                .supported_certificate_types()
                .is_empty(),
            config.provider().secure_random,
            config.enable_sni,
        )
    }

    /// Compute the HPKE `SetupBaseS` `info` parameter for this ECH configuration.
    ///
    /// See <https://datatracker.ietf.org/doc/html/rfc9849#section-6.1>.
    pub(crate) fn hpke_info(&self) -> Vec<u8> {
        let mut info = Vec::with_capacity(128);
        // "tls ech" || 0x00 || ECHConfig
        info.extend_from_slice(b"tls ech\0");
        self.config.encode(&mut info);
        info
    }

    fn new_for_configs(
        ech_configs: Vec<EchConfigPayload>,
        hpke_suites: &[&'static dyn Hpke],
    ) -> Result<Self, Error> {
        for (i, config) in ech_configs.iter().enumerate() {
            let contents = match config {
                EchConfigPayload::V18(contents) => contents,
                EchConfigPayload::Unknown { version, .. } => {
                    warn!("ECH config {} has unsupported version {:?}", i + 1, version);
                    continue; // Unsupported version.
                }
            };

            if contents.has_unknown_mandatory_extension() || contents.has_duplicate_extension() {
                warn!("ECH config has duplicate, or unknown mandatory extensions: {contents:?}",);
                continue; // Unsupported, or malformed extensions.
            }

            let key_config = &contents.key_config;
            for cipher_suite in &key_config.symmetric_cipher_suites {
                if cipher_suite.aead_id.tag_len().is_none() {
                    continue; // Unsupported EXPORT_ONLY AEAD cipher suite.
                }

                let suite = HpkeSuite {
                    kem: key_config.kem_id,
                    sym: *cipher_suite,
                };
                if let Some(hpke) = hpke_suites
                    .iter()
                    .find(|hpke| hpke.suite() == suite)
                {
                    debug!(
                        "selected ECH config ID {:?} suite {:?} public_name {:?}",
                        key_config.config_id, suite, contents.public_name
                    );
                    return Ok(Self {
                        config: config.clone(),
                        suite: *hpke,
                    });
                }
            }
        }

        Err(EncryptedClientHelloError::NoCompatibleConfig.into())
    }
}

/// Configuration for GREASE Encrypted Client Hello.
#[derive(Clone, Debug)]
pub struct EchGreaseConfig {
    pub(crate) suite: &'static dyn Hpke,
    pub(crate) placeholder_key: HpkePublicKey,
}

impl EchGreaseConfig {
    /// Construct a GREASE ECH configuration.
    ///
    /// This configuration is used when the client wishes to offer ECH to prevent ossification,
    /// but doesn't have a real ECH configuration to use for the remote server. In this case
    /// a placeholder or "GREASE"[^0] extension is used.
    ///
    /// Returns an error if the HPKE provider does not support the given suite.
    ///
    /// [^0]: <https://www.rfc-editor.org/rfc/rfc8701>
    pub fn new(suite: &'static dyn Hpke, placeholder_key: HpkePublicKey) -> Self {
        Self {
            suite,
            placeholder_key,
        }
    }

    /// Build a GREASE ECH extension based on the placeholder configuration.
    ///
    /// See <https://datatracker.ietf.org/doc/html/rfc9849#name-grease-ech> for
    /// more information.
    pub(crate) fn grease_ext(
        &self,
        secure_random: &'static dyn SecureRandom,
        inner_name: ServerName<'static>,
        outer_hello: &ClientHelloPayload,
    ) -> Result<EncryptedClientHello, Error> {
        trace!("Preparing GREASE ECH extension");

        // Pick a random config id.
        let mut config_id: [u8; 1] = [0; 1];
        secure_random.fill(&mut config_id[..])?;

        let suite = self.suite.suite();

        // Construct a dummy ECH state - we don't have a real ECH config from a server since
        // this is for GREASE.
        let mut grease_state = EchState::new(
            &EchConfig {
                config: EchConfigPayload::V18(EchConfigContents {
                    key_config: HpkeKeyConfig {
                        config_id: config_id[0],
                        kem_id: HpkeKem::DHKEM_P256_HKDF_SHA256,
                        public_key: SizedPayload::from(self.placeholder_key.0.clone()),
                        symmetric_cipher_suites: vec![suite.sym],
                    },
                    maximum_name_length: 0,
                    public_name: DnsName::try_from("filler").unwrap(),
                    extensions: Vec::default(),
                }),
                suite: self.suite,
            },
            inner_name,
            false,
            secure_random,
            false, // Does not matter if we enable/disable SNI here. Inner hello is not used.
        )?;

        // Construct an inner hello using the outer hello - this allows us to know the size of
        // dummy payload we should use for the GREASE extension.
        let encoded_inner_hello = grease_state.encode_inner_hello(outer_hello, None, None)?;

        // Generate a payload of random data equivalent in length to a real inner hello.
        let payload_len = encoded_inner_hello.len()
            + suite
                .sym
                .aead_id
                .tag_len()
                // Safety: we have confirmed the AEAD is supported when building the config. All
                //  supported AEADs have a tag length.
                .unwrap();
        let mut payload = vec![0; payload_len];
        secure_random.fill(&mut payload)?;

        // Return the GREASE extension.
        Ok(EncryptedClientHello::Outer(EncryptedClientHelloOuter {
            cipher_suite: suite.sym,
            config_id: config_id[0],
            enc: SizedPayload::from(Payload::new(grease_state.enc.0)),
            payload: SizedPayload::from(Payload::new(payload)),
        }))
    }
}

/// An enum representing ECH offer status.
#[non_exhaustive]
#[derive(Debug, Default, Clone, Copy, Eq, PartialEq)]
pub enum EchStatus {
    /// ECH was not offered - it is a normal TLS handshake.
    #[default]
    NotOffered,
    /// GREASE ECH was sent. This is not considered offering ECH.
    Grease,
    /// ECH was offered but we do not yet know whether the offer was accepted or rejected.
    Offered,
    /// ECH was offered and the server accepted.
    Accepted,
    /// ECH was offered and the server rejected.
    Rejected,
}

/// Contextual data for a TLS client handshake that has offered encrypted client hello (ECH).
pub(crate) struct EchState {
    // The public DNS name from the ECH configuration we've chosen - this is included as the SNI
    // value for the "outer" client hello. It can only be a DnsName, not an IP address.
    pub(crate) outer_name: DnsName<'static>,
    // If we're resuming in the inner hello, this is the early key schedule to use for encrypting
    // early data if the ECH offer is accepted.
    pub(crate) early_data_key_schedule: Option<KeyScheduleEarlyClient>,
    // A random value we use for the inner hello.
    pub(crate) inner_hello_random: Random,
    // A transcript buffer maintained for the inner hello. Once ECH is confirmed we switch to
    // using this transcript for the handshake.
    pub(crate) inner_hello_transcript: HandshakeHashBuffer,
    // A source of secure random data.
    secure_random: &'static dyn SecureRandom,
    // An HPKE sealer context that can be used for encrypting ECH data.
    sender: Box<dyn HpkeSealer>,
    // The ID of the ECH configuration we've chosen - this is included in the outer ECH extension.
    config_id: u8,
    // The private server name we'll use for the inner protected hello.
    inner_name: ServerName<'static>,
    // The advertised maximum name length from the ECH configuration we've chosen - this is used
    // for padding calculations.
    maximum_name_length: u8,
    // A supported symmetric cipher suite from the ECH configuration we've chosen - this is
    // included in the outer ECH extension.
    cipher_suite: HpkeSymmetricCipherSuite,
    // A secret encapsulated to the public key of the remote server. This is included in the
    // outer ECH extension for non-retry outer hello messages.
    enc: EncapsulatedSecret,
    // Whether the inner client hello should contain a server name indication (SNI) extension.
    enable_sni: bool,
    // The extensions sent in the inner hello.
    sent_extensions: Vec<ExtensionType>,
    // The GREASE PSK identities offered in the first outer hello, if any. A retry hello
    // re-offers the same identities.
    grease_psk_identities: Option<Vec<PresharedKeyIdentity>>,
}

impl EchState {
    pub(crate) fn new(
        config: &EchConfig,
        inner_name: ServerName<'static>,
        client_auth_enabled: bool,
        secure_random: &'static dyn SecureRandom,
        enable_sni: bool,
    ) -> Result<Self, Error> {
        let EchConfigPayload::V18(config_contents) = &config.config else {
            // the public EchConfig::new() constructor ensures we only have supported
            // configurations.
            unreachable!("ECH config version mismatch");
        };
        let key_config = &config_contents.key_config;

        // Encapsulate a secret for the server's public key, and set up a sender context
        // we can use to seal messages.
        let (enc, sender) = config.suite.setup_sealer(
            &config.hpke_info(),
            &HpkePublicKey(key_config.public_key.to_vec()),
        )?;

        // Start a new transcript buffer for the inner hello.
        let mut inner_hello_transcript = HandshakeHashBuffer::new();
        if client_auth_enabled {
            inner_hello_transcript.set_client_auth_enabled();
        }

        Ok(Self {
            outer_name: config_contents.public_name.clone(),
            early_data_key_schedule: None,
            inner_hello_random: Random::new(secure_random)?,
            inner_hello_transcript,
            secure_random,
            sender,
            config_id: key_config.config_id,
            inner_name,
            maximum_name_length: config_contents.maximum_name_length,
            cipher_suite: config.suite.suite().sym,
            enc,
            enable_sni,
            sent_extensions: Vec::new(),
            grease_psk_identities: None,
        })
    }

    /// Construct a ClientHelloPayload offering ECH.
    ///
    /// An outer hello, with a protected inner hello for the `inner_name` will be returned, and the
    /// ECH context will be updated to reflect the inner hello that was offered.
    ///
    /// If `retry_req` is `Some`, then the outer hello will be constructed for a hello retry request.
    ///
    /// If `resuming` is `Some`, then the inner hello will be constructed for a resumption handshake.
    pub(crate) fn ech_hello(
        &mut self,
        mut outer_hello: ClientHelloPayload,
        retry_req: Option<&HelloRetryRequest>,
        resuming: Option<&Retrieved<&Tls13Session>>,
    ) -> Result<ClientHelloPayload, Error> {
        trace!(
            "Preparing ECH offer {}",
            if retry_req.is_some() { "for retry" } else { "" }
        );

        // Construct the encoded inner hello and update the transcript.
        let encoded_inner_hello = self.encode_inner_hello(&outer_hello, retry_req, resuming)?;

        // Complete the ClientHelloOuterAAD with an ech extension, the payload should be a placeholder
        // of size L, all zeroes. L == length of encrypting encoded client hello inner w/ the selected
        // HPKE AEAD. (sum of plaintext + tag length, typically).
        let payload_len = encoded_inner_hello.len()
            + self
                .cipher_suite
                .aead_id
                .tag_len()
                // Safety: we've already verified this AEAD is supported when loading the config
                // that was used to create the ECH context. All supported AEADs have a tag length.
                .unwrap();

        // Outer hello's created in response to a hello retry request omit the enc value.
        let enc = match retry_req.is_some() {
            true => Vec::default(),
            false => self.enc.0.clone(),
        };

        fn outer_hello_ext(ctx: &EchState, enc: Vec<u8>, payload: Vec<u8>) -> EncryptedClientHello {
            EncryptedClientHello::Outer(EncryptedClientHelloOuter {
                cipher_suite: ctx.cipher_suite,
                config_id: ctx.config_id,
                enc: SizedPayload::from(Payload::new(enc)),
                payload: SizedPayload::from(Payload::new(payload)),
            })
        }

        // The outer handshake is not permitted to resume a session. If we're resuming in the
        // inner handshake we remove the PSK extension from the outer hello, replacing it
        // with a GREASE PSK to implement the "ClientHello Malleability Mitigation" mentioned
        // in 10.12.3.
        if let Some(psk_offer) = outer_hello.preshared_key_offer.as_mut() {
            self.grease_psk(psk_offer)?;
        }

        // To compute the encoded AAD we add a placeholder extension with an empty payload.
        outer_hello.encrypted_client_hello =
            Some(outer_hello_ext(self, enc.clone(), vec![0; payload_len]));

        // Next we compute the proper extension payload.
        let payload = self
            .sender
            .seal(&outer_hello.get_encoding(), &encoded_inner_hello)?;

        // And then we replace the placeholder extension with the real one.
        outer_hello.encrypted_client_hello = Some(outer_hello_ext(self, enc, payload));

        Ok(outer_hello)
    }

    /// Confirm whether an ECH offer was accepted based on examining the server hello.
    pub(crate) fn confirm_acceptance(
        self,
        ks: &KeyScheduleHandshakeStart,
        server_hello: &ServerHelloPayload,
        server_hello_encoded: &Payload<'_>,
        hash: &'static dyn Hash,
        server_name: &mut ServerName<'static>,
    ) -> Result<Option<EchAccepted>, Error> {
        // Start the inner transcript hash now that we know the hash algorithm to use.
        let inner_transcript = self
            .inner_hello_transcript
            .start_hash(hash);

        // Fork the transcript that we've started with the inner hello to use for a confirmation step.
        // We need to preserve the original inner_transcript to use if this confirmation succeeds.
        let mut confirmation_transcript = inner_transcript.clone();

        // Add the server hello confirmation - this is computed by altering the received
        // encoding rather than reencoding it.
        confirmation_transcript
            .add_message(&Self::server_hello_conf(server_hello, server_hello_encoded));

        // Derive a confirmation secret from the inner hello random and the confirmation transcript.
        let derived = ks.server_ech_confirmation_secret(
            self.inner_hello_random.0.as_ref(),
            confirmation_transcript.current_hash(),
        );

        // Check that first 8 digits of the derived secret match the last 8 digits of the original
        // server random. This match signals that the server accepted the ECH offer.
        // Indexing safety: Random is [0; 32] by construction.

        match ConstantTimeEq::ct_eq(derived.as_ref(), server_hello.random.0[24..].as_ref()).into() {
            true => {
                trace!("ECH accepted by server");
                Ok(Some(EchAccepted {
                    transcript: inner_transcript,
                    random: self.inner_hello_random,
                    sent_extensions: self.sent_extensions,
                }))
            }
            false => {
                trace!("ECH rejected by server");

                // "If the server rejects ECH, the client proceeds with the handshake, authenticating
                // for ECHConfig.contents.public_name"
                // -- <https://www.rfc-editor.org/info/rfc9849/#section-6.1.6>
                *server_name = self.outer_name.into();

                Ok(None)
            }
        }
    }

    pub(crate) fn confirm_hrr_acceptance(
        &self,
        hrr: &HelloRetryRequest,
        cs: &Tls13CipherSuite,
    ) -> Result<bool, Error> {
        // The client checks for the "encrypted_client_hello" extension.
        let ech_conf = match &hrr.encrypted_client_hello {
            // If none is found, the server has implicitly rejected ECH.
            None => return Ok(false),
            // Otherwise, if it has a length other than 8, the client aborts the
            // handshake with a "decode_error" alert.
            Some(ech_conf) if ech_conf.bytes().len() != 8 => {
                return Err(PeerMisbehaved::IllegalHelloRetryRequestWithInvalidEch.into());
            }
            Some(ech_conf) => ech_conf,
        };

        // Otherwise the client computes hrr_accept_confirmation as described in Section
        // 7.2.1
        let confirmation_transcript = self.inner_hello_transcript.clone();
        let mut confirmation_transcript =
            confirmation_transcript.start_hash(cs.common.hash_provider);
        confirmation_transcript.rollup_for_hrr();
        confirmation_transcript.add_message(&Self::hello_retry_request_conf(hrr));

        let derived = server_ech_hrr_confirmation_secret(
            cs.hkdf_provider,
            &self.inner_hello_random.0,
            confirmation_transcript.current_hash(),
        );

        match ConstantTimeEq::ct_eq(derived.as_ref(), ech_conf.bytes()).into() {
            true => {
                trace!("ECH accepted by server in hello retry request");
                Ok(true)
            }
            false => {
                trace!("ECH rejected by server in hello retry request");
                Ok(false)
            }
        }
    }

    /// Update the ECH context inner hello transcript based on a received hello retry request message.
    ///
    /// This will start the in-progress transcript using the given `hash`, convert it into an HRR
    /// buffer, and then add the hello retry message `m`.
    pub(crate) fn transcript_hrr_update(
        &mut self,
        hash: &'static dyn Hash,
        m: &Message<'_>,
        proof: &HandshakeAlignedProof,
    ) {
        trace!("Updating ECH inner transcript for HRR");

        let inner_transcript = self
            .inner_hello_transcript
            .clone()
            .start_hash(hash);

        let mut inner_transcript_buffer = inner_transcript.into_hrr_buffer(proof);
        inner_transcript_buffer.add_message(m);
        self.inner_hello_transcript = inner_transcript_buffer;
    }

    // See https://datatracker.ietf.org/doc/html/rfc9849#name-grease-psk
    pub(super) fn grease_psk(&mut self, psk_offer: &mut PresharedKeyOffer) -> Result<(), Error> {
        match &self.grease_psk_identities {
            // This is a retry hello: re-offer the identities and ages from the first hello,
            // as a genuine PSK offer would. Only the binders are regenerated below; a fresh
            // GREASE PSK here would "stick out" to an attacker triggering a retry.
            Some(identities) => psk_offer.identities = identities.clone(),
            None => {
                for ident in psk_offer.identities.iter_mut() {
                    // "For each PSK identity advertised in the ClientHelloInner, the
                    // client generates a random PSK identity with the same length."
                    let Some(identity) = ident.identity.as_mut() else {
                        unreachable!();
                    };
                    self.secure_random.fill(identity)?;

                    // "It also generates a random, 32-bit, unsigned integer to use as
                    // the obfuscated_ticket_age."
                    let mut ticket_age = [0_u8; 4];
                    self.secure_random
                        .fill(&mut ticket_age)?;
                    ident.obfuscated_ticket_age = u32::from_be_bytes(ticket_age);
                }

                self.grease_psk_identities = Some(psk_offer.identities.clone());
            }
        }

        // "Likewise, for each inner PSK binder, the client generates a random string
        // of the same length."
        psk_offer.binders = psk_offer
            .binders
            .iter()
            .map(|old_binder| {
                // We can't access the wrapped binder PresharedKeyBinder's PayloadU8 mutably,
                // so we construct new PresharedKeyBinder's from scratch with the same length.
                let mut new_binder = vec![0; old_binder.as_ref().len()];
                self.secure_random
                    .fill(&mut new_binder)?;
                Ok::<PresharedKeyBinder, Error>(PresharedKeyBinder::from(new_binder))
            })
            .collect::<Result<_, _>>()?;
        Ok(())
    }

    // 5.1 "Encoding the ClientHelloInner"
    fn encode_inner_hello(
        &mut self,
        outer_hello: &ClientHelloPayload,
        retryreq: Option<&HelloRetryRequest>,
        resuming: Option<&Retrieved<&Tls13Session>>,
    ) -> Result<Vec<u8>, Error> {
        // Start building an inner hello using the outer_hello as a template.
        let mut inner_hello = ClientHelloPayload {
            // Some information is copied over as-is.
            client_version: outer_hello.client_version,

            // Set the inner hello random to the one we generated when creating the ECH state.
            // We hold on to the inner_hello_random in the ECH state to use later for confirming
            // whether ECH was accepted or not.
            random: self.inner_hello_random,
            session_id: outer_hello.session_id,

            // We remove the empty renegotiation info SCSV from the outer hello's ciphersuite.
            // Similar to the TLS 1.2 specific extensions we will filter out, this is seen as a
            // TLS 1.2 only feature by bogo.
            cipher_suites: outer_hello
                .cipher_suites
                .iter()
                .filter(|cs| **cs != CipherSuite::TLS_EMPTY_RENEGOTIATION_INFO_SCSV)
                .copied()
                .collect(),
            compression_methods: outer_hello.compression_methods.clone(),

            // We will build up the included extensions ourselves.
            extensions: Box::new(ClientExtensions::default()),
        };

        inner_hello.order_seed = outer_hello.order_seed;

        // The inner hello will always have an inner variant of the ECH extension added.
        // See Section 6.1 rule 4.
        inner_hello.encrypted_client_hello = Some(EncryptedClientHello::Inner);

        let inner_sni = match &self.inner_name {
            // The inner hello only gets a SNI value if enable_sni is true and the inner name
            // is a domain name (not an IP address).
            ServerName::DnsName(dns_name) if self.enable_sni => Some(dns_name),
            _ => None,
        };

        // Now we consider each of the outer hello's extensions - we can either:
        // 1. Omit the extension if it isn't appropriate (e.g. is a TLS 1.2 extension).
        // 2. Add the extension to the inner hello as-is.
        // 3. Compress the extension, by collecting it into a list of to-be-compressed
        //    extensions we'll handle separately.
        let outer_extensions = outer_hello.used_extensions_in_encoding_order();
        let mut compressed_exts = Vec::with_capacity(outer_extensions.len());
        for ext in outer_extensions {
            // Some outer hello extensions are only useful in the context where a TLS 1.3
            // connection allows TLS 1.2. This isn't the case for ECH so we skip adding them
            // to the inner hello.
            if matches!(
                ext,
                ExtensionType::ExtendedMainSecret
                    | ExtensionType::SessionTicket
                    | ExtensionType::ECPointFormats
            ) {
                continue;
            }

            if ext == ExtensionType::ServerName {
                // We may want to replace the outer hello SNI with our own inner hello specific SNI.
                if let Some(sni_value) = inner_sni {
                    inner_hello.server_name = Some(ServerNamePayload::from(sni_value));
                }
                // We don't want to add, or compress, the SNI from the outer hello.
                continue;
            }

            // Compressed extensions need to be put aside to include in one contiguous block.
            // Uncompressed extensions get added directly to the inner hello.
            if ext.ech_compress() {
                compressed_exts.push(ext);
            }

            inner_hello.clone_one(outer_hello, ext);
        }

        // We've added all the uncompressed extensions. Now we need to add the contiguous
        // block of to-be-compressed extensions.
        inner_hello.contiguous_extensions = compressed_exts.clone();

        // Note which extensions we're sending in the inner hello. This may differ from
        // the outer hello (e.g. the inner hello may omit SNI while the outer hello will
        // always have the ECH cover name in SNI).
        self.sent_extensions = inner_hello.collect_used();

        // If we're resuming, we need to update the PSK binder in the inner hello.
        if let Some(resuming) = resuming.as_ref() {
            let mut chp = HandshakeMessagePayload(HandshakePayload::ClientHello(inner_hello));

            let key_schedule =
                KeyScheduleEarlyClient::new(resuming.suite, resuming.secret.bytes())?;
            tls13::fill_in_psk_binder(&key_schedule, &self.inner_hello_transcript, &mut chp);
            self.early_data_key_schedule = Some(key_schedule);

            // fill_in_psk_binder works on an owned HandshakeMessagePayload, so we need to
            // extract our inner hello back out of it to retain ownership.
            inner_hello = match chp.0 {
                HandshakePayload::ClientHello(chp) => chp,
                // Safety: we construct the HMP above and know its type unconditionally.
                _ => unreachable!(),
            };
        }

        trace!("ECH Inner Hello: {inner_hello:#?}");

        // Encode the inner hello according to the rules required for ECH. This differs
        // from the standard encoding in several ways. Notably this is where we will
        // replace the block of contiguous to-be-compressed extensions with a marker.
        let mut encoded_hello = inner_hello.ech_inner_encoding(compressed_exts);

        // Calculate padding
        // max_name_len = L
        let max_name_len = usize::from(self.maximum_name_length);
        let max_name_len = if max_name_len > 0 { max_name_len } else { 255 };

        let name_padding_len = match &inner_hello.server_name {
            Some(ServerNamePayload::SingleDnsName(name)) => {
                // name.len() = D
                // max(0, L - D)
                Ord::max(0, max_name_len.saturating_sub(name.as_ref().len()))
            }
            // L + 9
            // "This is the length of a "server_name" extension with an L-byte name."
            _ => max_name_len + 9,
        };
        encoded_hello.extend(iter::repeat_n(0, name_padding_len));

        // Let L be the length of the EncodedClientHelloInner with all the padding computed so far
        // Let N = 31 - ((L - 1) % 32) and add N bytes of padding.
        let padding_len = 31 - ((encoded_hello.len() - 1) % 32);
        encoded_hello.extend(iter::repeat_n(0, padding_len));

        // Construct the inner hello message that will be used for the transcript.
        let inner_hello_msg = Message {
            version: match retryreq {
                // <https://datatracker.ietf.org/doc/html/rfc9846#section-5.1>:
                // "This value MUST be set to 0x0303 for all records generated
                //  by a TLS 1.3 implementation ..."
                Some(_) => EncodableVersion::Legacy(ProtocolVersion::TLSv1_2),
                // "... other than an initial ClientHello (i.e., one not
                // generated after a HelloRetryRequest), where it MAY also be
                // 0x0301 for compatibility purposes"
                //
                // (retryreq == None means we're in the "initial ClientHello" case)
                None => EncodableVersion::InitialClientHello(Protocol::Tcp),
            },
            payload: MessagePayload::handshake(HandshakeMessagePayload(
                HandshakePayload::ClientHello(inner_hello),
            )),
        };

        // Update the inner transcript buffer with the inner hello message.
        self.inner_hello_transcript
            .add_message(&inner_hello_msg);

        Ok(encoded_hello)
    }

    fn server_hello_conf(
        server_hello: &ServerHelloPayload,
        server_hello_encoded: &Payload<'_>,
    ) -> Message<'static> {
        // The confirmation is computed over the server hello, which has had
        // its `random` field altered to zero the final 8 bytes.
        //
        // nb. we don't require that we can round-trip a `ServerHelloPayload`, to
        // allow for efficiency in its in-memory representation.  That means
        // we operate here on the received encoding, as the confirmation needs
        // to be computed on that.
        let mut encoded = server_hello_encoded.clone().into_vec();
        encoded[SERVER_HELLO_ECH_CONFIRMATION_SPAN].fill(0x00);

        Message {
            version: EncodableVersion::Legacy(ProtocolVersion::TLSv1_3),
            payload: MessagePayload::Handshake {
                encoded: Payload::Owned(encoded),
                parsed: HandshakeMessagePayload(HandshakePayload::ServerHello(
                    server_hello.clone(),
                )),
            },
        }
    }

    fn hello_retry_request_conf(retry_req: &HelloRetryRequest) -> Message<'_> {
        Self::ech_conf_message(HandshakeMessagePayload(
            HandshakePayload::HelloRetryRequest(retry_req.clone()),
        ))
    }

    fn ech_conf_message(hmp: HandshakeMessagePayload<'_>) -> Message<'_> {
        let mut hmp_encoded = Vec::new();
        hmp.payload_encode(&mut hmp_encoded, Encoding::EchConfirmation);
        Message {
            version: EncodableVersion::Legacy(ProtocolVersion::TLSv1_3),
            payload: MessagePayload::Handshake {
                encoded: Payload::new(hmp_encoded),
                parsed: hmp,
            },
        }
    }
}

/// The last eight bytes of the ServerHello's random, taken from a Handshake message containing it.
///
/// This has:
/// - a HandshakeType (1 byte),
/// - an exterior length (3 bytes),
/// - the legacy_version (2 bytes), and
/// - the balance of the random field (24 bytes).
const SERVER_HELLO_ECH_CONFIRMATION_SPAN: core::ops::Range<usize> =
    (1 + 3 + 2 + 24)..(1 + 3 + 2 + 32);

/// Returned from EchState::confirm_acceptance when the server has accepted the ECH offer.
///
/// Holds the state required to continue the handshake with the inner hello from the ECH offer.
pub(crate) struct EchAccepted {
    pub(crate) transcript: HandshakeHash,
    pub(crate) random: Random,
    pub(crate) sent_extensions: Vec<ExtensionType>,
}

#[cfg(test)]
mod tests {
    use core::sync::atomic::{AtomicU8, Ordering};
    use core::time::Duration;
    use std::string::String;

    use pki_types::{CertificateDer, SubjectPublicKeyInfoDer, UnixTime};

    use super::*;
    use crate::client::{
        ClientSessionKey, ClientSessionMemoryCache, ClientSessionStore, Resumption,
        Tls13ClientSessionInput, VerifiedIdentity,
    };
    use crate::conn::Connection;
    use crate::crypto::cipher::Record;
    use crate::crypto::hpke::{HpkeAead, HpkeKdf};
    use crate::crypto::{CipherSuite, GetRandomFailed, Identity, TEST_PROVIDER, tls13_only};
    use crate::msgs::{
        Compression, HelloRetryRequestExtensions, NewSessionTicketPayloadTls13, Random, Reader,
        ServerExtensions, SessionId,
    };
    use crate::sync::Arc;
    use crate::tls13::Tls13ProtocolSuite;
    use crate::{RootCertStore, VecInput};

    #[test]
    fn server_hello_conf_alters_server_hello_random() {
        let server_hello = ServerHelloPayload {
            legacy_version: ProtocolVersion::TLSv1_2,
            random: Random([0xffu8; 32]),
            session_id: SessionId::empty(),
            cipher_suite: CipherSuite::TLS13_AES_256_GCM_SHA384,
            compression_method: Compression::Null,
            extensions: Box::new(ServerExtensions::default()),
        };
        let message = Message {
            version: EncodableVersion::Legacy(ProtocolVersion::TLSv1_3),
            payload: MessagePayload::handshake(HandshakeMessagePayload(
                HandshakePayload::ServerHello(server_hello.clone()),
            )),
        };
        let Message {
            payload:
                MessagePayload::Handshake {
                    encoded: server_hello_encoded_before,
                    ..
                },
            ..
        } = &message
        else {
            unreachable!("ServerHello is a handshake message");
        };

        let message = EchState::server_hello_conf(&server_hello, server_hello_encoded_before);

        let Message {
            payload:
                MessagePayload::Handshake {
                    encoded: server_hello_encoded_after,
                    ..
                },
            ..
        } = &message
        else {
            unreachable!("ServerHello is a handshake message");
        };

        assert_eq!(
            std::format!("{server_hello_encoded_before:x?}"),
            "020000280303ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff001302000000",
            "beforehand eight bytes at end of Random should be 0xff here ^^^^^^^^^^^^^^^^            "
        );
        assert_eq!(
            std::format!("{server_hello_encoded_after:x?}"),
            "020000280303ffffffffffffffffffffffffffffffffffffffffffffffff0000000000000000001302000000",
            "                          afterwards those bytes are zeroed ^^^^^^^^^^^^^^^^            "
        );
    }

    #[test]
    fn inner_client_hello_length_conceals_inner_name_length() {
        let base_inner_len = inner_hello_encoding_for_name(dns_name_of_len(1), true)
            .unwrap()
            .len();
        assert!(
            base_inner_len % 32 == 0,
            "inner hello length must be 32-byte padded"
        );
        assert!(
            base_inner_len >= 256,
            "inner hello must include inner name and its padding"
        );

        for inner_name_len in 1..251 {
            assert_eq!(
                inner_hello_encoding_for_name(dns_name_of_len(inner_name_len), true)
                    .unwrap()
                    .len(),
                base_inner_len,
                "all inner hello lengths must be invariant wrt inner name length"
            );
        }
    }

    #[test]
    fn inner_client_hello_length_does_not_leak_length_of_omitted_inner_name() {
        let base_inner_len = inner_hello_encoding_for_name(dns_name_of_len(1), false)
            .unwrap()
            .len();
        assert!(
            base_inner_len % 32 == 0,
            "inner hello length must be 32-byte padded"
        );
        assert!(
            base_inner_len >= 256,
            "inner hello must include maximum_name_length bytes of padding"
        );

        for inner_name_len in 1..251 {
            assert_eq!(
                inner_hello_encoding_for_name(dns_name_of_len(inner_name_len), false)
                    .unwrap()
                    .len(),
                base_inner_len,
                "all inner hello lengths must be invariant wrt inner name length"
            );
        }
    }

    #[test]
    fn ech_rejected_by_hello_retry_request_conceals_inner_psk() {
        let mut roots = RootCertStore::empty();
        roots
            .add(CertificateDer::from_slice(include_bytes!(
                "../../../test-ca/rsa-2048/ca.der"
            )))
            .unwrap();

        // `TEST_PROVIDER`'s fixed-fill `SecureRandom` would mask a regression here: a
        // fresh GREASE PSK generated for the retry would repeat the first hello's
        // identity by happenstance. A counter makes consecutive fills distinct.
        let mut provider = tls13_only(TEST_PROVIDER.clone());
        provider.secure_random = &CountingRandom;

        let config = ClientConfig::builder(Arc::new(provider))
            .with_ech(EchMode::Enable(EchConfig {
                config: EchConfigPayload::V18(EchConfigContents {
                    key_config: HpkeKeyConfig {
                        config_id: 0,
                        kem_id: MockHpke::SUITE.kem,
                        public_key: vec![0; 32].into(),
                        symmetric_cipher_suites: vec![MockHpke::SUITE.sym],
                    },
                    maximum_name_length: 255,
                    public_name: DnsName::try_from("public.example.com").unwrap(),
                    extensions: vec![],
                }),
                suite: &MockHpke,
            }))
            .with_root_certificates(roots)
            .with_no_client_auth()
            .unwrap();
        let store = Arc::new(ClientSessionMemoryCache::new(256));
        let config = Arc::new(ClientConfig {
            resumption: Resumption::store(store.clone()),
            ..config
        });

        // cache a ticket for the concealed inner name
        let server_name = ServerName::try_from("inner.example.com").unwrap();
        store.insert_tls13_ticket(
            ClientSessionKey {
                config_hash: config.config_hash(),
                server_name: server_name.clone(),
            },
            Tls13Session::new(
                &NewSessionTicketPayloadTls13::new(
                    Duration::from_secs(1800),
                    0x1234_5678,
                    [0u8; 32],
                    TICKET.to_vec(),
                ),
                Tls13ClientSessionInput {
                    suite: Tls13ProtocolSuite::Tcp(TEST_PROVIDER.tls13_cipher_suites[0]),
                    peer_identity: VerifiedIdentity::assertion(Identity::RawPublicKey(
                        SubjectPublicKeyInfoDer::from(&b"spki"[..]),
                    )),
                    quic_params: None,
                },
                &[0x55; 32],
                UnixTime::now(),
            ),
        );

        let mut first_flight = Vec::new();
        let mut conn = config
            .connect(server_name)
            .build(&mut first_flight)
            .unwrap();

        // the ticket belongs to the concealed inner name, so the outer hello offers
        // a GREASE PSK in its place
        let first = client_hello_in(&first_flight);
        assert_ne!(psk_identity(&first), TICKET);

        // a HelloRetryRequest without `encrypted_client_hello` rejects our ECH offer
        let hrr = Message {
            version: EncodableVersion::Legacy(ProtocolVersion::TLSv1_2),
            payload: MessagePayload::handshake(HandshakeMessagePayload(
                HandshakePayload::HelloRetryRequest(HelloRetryRequest {
                    legacy_version: ProtocolVersion::TLSv1_2,
                    session_id: first.session_id,
                    cipher_suite: first.cipher_suites[0],
                    extensions: HelloRetryRequestExtensions {
                        cookie: Some(SizedPayload::from(vec![1, 2, 3, 4])),
                        supported_versions: Some(ProtocolVersion::TLSv1_3),
                        ..HelloRetryRequestExtensions::default()
                    },
                }),
            )),
        };
        let mut input = VecInput::default();
        input
            .read(&mut hrr.into_wire_bytes().as_slice())
            .unwrap();
        let mut retry_flight = Vec::new();
        conn.read_tls(&mut input, &mut retry_flight)
            .handle_all(&mut Vec::new())
            .unwrap();

        // we continue with a second outer hello: it must conceal the ticket too, and
        // must re-offer the first hello's GREASE identity as a genuine PSK offer would
        let second = client_hello_in(&retry_flight);
        assert_ne!(psk_identity(&second), TICKET);
        assert_eq!(psk_identity(&second), psk_identity(&first));

        fn client_hello_in(bytes: &[u8]) -> ClientHelloPayload {
            let mut reader = Reader::new(bytes);
            while reader.any_left() {
                let record = Record::<Payload<'_>>::read(&mut reader)
                    .unwrap()
                    .into_owned();
                if let Ok(Message {
                    payload:
                        MessagePayload::Handshake {
                            parsed: HandshakeMessagePayload(HandshakePayload::ClientHello(ch)),
                            ..
                        },
                    ..
                }) = Message::try_from(&record)
                {
                    return ch;
                }
            }
            panic!("no ClientHello written");
        }

        fn psk_identity(hello: &ClientHelloPayload) -> &[u8] {
            hello
                .preshared_key_offer
                .as_ref()
                .unwrap()
                .identities[0]
                .identity
                .bytes()
        }

        const TICKET: &[u8] = b"inner name resumption ticket";

        #[derive(Debug)]
        struct CountingRandom;

        impl SecureRandom for CountingRandom {
            fn fill(&self, bytes: &mut [u8]) -> Result<(), GetRandomFailed> {
                static COUNTER: AtomicU8 = AtomicU8::new(0);
                for byte in bytes.iter_mut() {
                    *byte = COUNTER.fetch_add(1, Ordering::Relaxed);
                }
                Ok(())
            }
        }
    }

    fn inner_hello_encoding_for_name(
        name: DnsName<'static>,
        enable_sni: bool,
    ) -> Result<Vec<u8>, Error> {
        let config = EchConfig {
            config: EchConfigPayload::V18(EchConfigContents {
                key_config: HpkeKeyConfig {
                    config_id: 0,
                    kem_id: MockHpke::SUITE.kem,
                    public_key: vec![0; 32].into(),
                    symmetric_cipher_suites: vec![],
                },
                maximum_name_length: 255,
                public_name: DnsName::try_from("public").unwrap(),
                extensions: vec![],
            }),
            suite: &MockHpke,
        };

        EchState::new(
            &config,
            ServerName::from(name.clone()),
            false,
            TEST_PROVIDER.secure_random,
            enable_sni,
        )
        .unwrap()
        .encode_inner_hello(
            &ClientHelloPayload {
                client_version: ProtocolVersion::TLSv1_3,
                random: Random([0u8; 32]),
                session_id: SessionId::empty(),
                cipher_suites: vec![],
                compression_methods: vec![Compression::Null],
                extensions: Box::new(ClientExtensions {
                    server_name: Some(ServerNamePayload::from(&name)),
                    ..Default::default()
                }),
            },
            None,
            None,
        )
    }

    fn dns_name_of_len(mut len: usize) -> DnsName<'static> {
        let mut s = String::new();
        let labels = len.div_ceil(63);
        for _ in 0..labels {
            let chars = Ord::min(len, 63);
            len -= chars;
            for _ in 0..chars {
                s.push('a');
            }
            if len != 0 {
                s.push('.');
            }
        }
        DnsName::try_from(s).unwrap()
    }

    #[derive(Debug)]
    struct MockHpke;

    impl MockHpke {
        const SUITE: HpkeSuite = HpkeSuite {
            kem: HpkeKem::DHKEM_P256_HKDF_SHA256,
            sym: HpkeSymmetricCipherSuite {
                kdf_id: HpkeKdf::HKDF_SHA256,
                aead_id: HpkeAead::AES_128_GCM,
            },
        };
    }

    impl Hpke for MockHpke {
        #[cfg_attr(coverage_nightly, coverage(off))]
        fn seal(
            &self,
            _info: &[u8],
            _aad: &[u8],
            _plaintext: &[u8],
            _pub_key: &HpkePublicKey,
        ) -> Result<(EncapsulatedSecret, Vec<u8>), Error> {
            todo!()
        }

        fn setup_sealer(
            &self,
            _info: &[u8],
            _pub_key: &HpkePublicKey,
        ) -> Result<(EncapsulatedSecret, Box<dyn HpkeSealer + 'static>), Error> {
            Ok((EncapsulatedSecret(vec![]), Box::new(MockHpkeSealer)))
        }

        #[cfg_attr(coverage_nightly, coverage(off))]
        fn open(
            &self,
            _enc: &EncapsulatedSecret,
            _info: &[u8],
            _aad: &[u8],
            _ciphertext: &[u8],
            _secret_key: &crate::crypto::hpke::HpkePrivateKey,
        ) -> Result<Vec<u8>, Error> {
            todo!()
        }

        #[cfg_attr(coverage_nightly, coverage(off))]
        fn setup_opener(
            &self,
            _enc: &EncapsulatedSecret,
            _info: &[u8],
            _secret_key: &crate::crypto::hpke::HpkePrivateKey,
        ) -> Result<Box<dyn crate::crypto::hpke::HpkeOpener + 'static>, Error> {
            todo!()
        }

        #[cfg_attr(coverage_nightly, coverage(off))]
        fn generate_key_pair(
            &self,
        ) -> Result<(HpkePublicKey, crate::crypto::hpke::HpkePrivateKey), Error> {
            todo!()
        }

        fn suite(&self) -> HpkeSuite {
            Self::SUITE
        }
    }

    #[derive(Debug)]
    struct MockHpkeSealer;

    impl HpkeSealer for MockHpkeSealer {
        fn seal(&mut self, _aad: &[u8], plaintext: &[u8]) -> Result<Vec<u8>, Error> {
            // ciphertext length as if sealed with the AEAD named in `MockHpke::SUITE`
            Ok(vec![0xff; plaintext.len() + 16])
        }
    }
}