Merge remote-tracking branch 'upstream/dev' into noise-session-resume

esphome/components/api/api.proto

@@ -893,6 +893,20 @@ message NoiseEncryptionSetKeyResponse {
   bool success = 1;
 }
 
+// Single-use session resume ticket, sent unsolicited by the device after a
+// Noise connection authenticates. A client presents it in the ClientHello of
+// its next connection to skip the curve25519 handshake; the device then
+// issues a fresh ticket on that connection. Never sent on plaintext
+// connections. Clients that do not understand it drop it silently.
+// Contents are secret; the device generator redacts this message from dump_to
+message NoiseResumeTicket {
+  option (id) = 152;
+  option (source) = SOURCE_SERVER;
+  option (ifdef) = "USE_API_NOISE";
+
+  bytes ticket = 1;  // session_id(8) || secret(32)
+}
+
 // ==================== HOMEASSISTANT.SERVICE ====================
 message SubscribeHomeassistantServicesRequest {
   option (id) = 34;

esphome/components/api/api_connection.cpp

@@ -1779,6 +1779,9 @@ void APIConnection::complete_authentication_() {
     this->send_time_request();
   }
 #endif
+#ifdef USE_API_NOISE
+  this->send_resume_ticket_();
+#endif
 #ifdef USE_ZWAVE_PROXY
   if (zwave_proxy::global_zwave_proxy != nullptr) {
     zwave_proxy::global_zwave_proxy->api_connection_authenticated(this);
@@ -1786,6 +1789,27 @@ void APIConnection::complete_authentication_() {
 #endif
 }
 
+#ifdef USE_API_NOISE
+void APIConnection::send_resume_ticket_() {
+#ifdef USE_API_PLAINTEXT
+  // Only encrypted transports get a ticket: on dual-mode builds a plaintext
+  // connection has no frame footer
+  if (this->helper_->frame_footer_size() == 0) {
+    return;
+  }
+#endif
+  noise::ResumeTicket ticket;
+  if (!this->parent_->get_noise_ctx().resume_cache().issue(ticket)) {
+    return;
+  }
+  NoiseResumeTicket msg;
+  msg.set_ticket(reinterpret_cast<const uint8_t *>(&ticket), sizeof(ticket));
+  // A dropped ticket is harmless: the client does a full handshake next time
+  static_cast<void>(this->send_message(msg));
+  noise_clean(&ticket, sizeof(ticket));
+}
+#endif
+
 bool APIConnection::send_hello_response_(const HelloRequest &msg) {
   // Copy client name with truncation if needed (set_client_name handles truncation)
   this->helper_->set_client_name(msg.client_info.c_str(), msg.client_info.size());

esphome/components/api/api_connection.h

@@ -381,6 +381,11 @@ class APIConnection final : public APIServerConnectionBase {
   // Helper function to handle authentication completion
   void complete_authentication_();
 
+#ifdef USE_API_NOISE
+  // Issue a fresh single-use session resume ticket over the encrypted channel
+  void send_resume_ticket_();
+#endif
+
   // Pattern B helpers: send response and return success/failure
   bool send_hello_response_(const HelloRequest &msg);
   bool send_disconnect_response_();

esphome/components/api/api_frame_helper_noise.cpp

@@ -271,8 +271,8 @@ APIError APINoiseFrameHelper::state_action_client_hello_() {
   if (aerr != APIError::OK) {
     return handle_handshake_frame_error_(aerr);
   }
-  // ignore contents, may be used in future for flags
-  // Resize for: existing prologue + 2 size bytes + frame data
+  // Contents are extension flags (today: the resume offer); mixed into the
+  // prologue either way. Resize for: existing prologue + 2 size bytes + frame data
   size_t old_size = this->prologue_.size();
   size_t rx_size = this->rx_buf_.size();
   if (!this->prologue_.resize(old_size + 2 + rx_size)) [[unlikely]] {
@@ -289,6 +289,8 @@ APIError APINoiseFrameHelper::state_action_client_hello_() {
   return APIError::OK;
 }
 APIError APINoiseFrameHelper::state_action_server_hello_() {
+  // A verified resume offer (still in rx_buf_ from the client hello step)
+  // replaces the whole handshake; any failure falls back to the full one.
   // send server hello
   const auto &name = App.get_name();
   char mac[MAC_ADDRESS_BUFFER_SIZE];
@@ -302,7 +304,9 @@ APIError APINoiseFrameHelper::state_action_server_hello_() {
 
   // 1 (proto) + name (max ESPHOME_DEVICE_NAME_MAX_LEN) + 1 (name null)
   // + mac (MAC_ADDRESS_BUFFER_SIZE - 1) + 1 (mac null)
-  constexpr size_t max_msg_size = 1 + ESPHOME_DEVICE_NAME_MAX_LEN + 1 + MAC_ADDRESS_BUFFER_SIZE;
+  // + optional resume accept extension
+  constexpr size_t max_msg_size =
+      1 + ESPHOME_DEVICE_NAME_MAX_LEN + 1 + MAC_ADDRESS_BUFFER_SIZE + noise::RESUME_ACCEPT_SIZE;
   uint8_t msg[max_msg_size];
 
   // chosen proto
@@ -313,16 +317,32 @@ APIError APINoiseFrameHelper::state_action_server_hello_() {
   // node mac, terminated by null byte
   std::memcpy(msg + mac_offset, mac, MAC_ADDRESS_BUFFER_SIZE);
 
+  // The accept extension, if any, is written straight after the mac
+  size_t ext_len = this->ctx_.resume_cache().try_accept(
+      this->rx_buf_.data(), this->rx_buf_.size(), this->prologue_.data(), this->prologue_.size(), msg + total_size,
+      sizeof(msg) - total_size, send_cipher_, recv_cipher_);
+  bool resume = ext_len != 0;
+  total_size += ext_len;
+
   APIError aerr = write_frame_(msg, total_size);
   if (aerr != APIError::OK)
     return aerr;
 
-  // start handshake
-  aerr = init_handshake_();
-  if (aerr != APIError::OK)
-    return aerr;
-
-  state_ = State::HANDSHAKE;
+  if (resume) {
+    // A resuming client waits for this hello instead of pipelining
+    // handshake message 1, so the transport is ready now
+    this->frame_footer_size_ = noise_cipherstate_get_mac_length(this->send_cipher_);
+    HELPER_LOG("Session resumed!");
+    state_ = State::DATA;
+  } else {
+    aerr = init_handshake_();
+    if (aerr != APIError::OK)
+      return aerr;
+    state_ = State::HANDSHAKE;
+  }
+  // init_handshake_ copied the prologue into the handshake state; the resume
+  // path is done with it too
+  this->prologue_.release();
   return APIError::OK;
 }
 APIError APINoiseFrameHelper::state_action_handshake_() {
@@ -552,8 +572,6 @@ APIError APINoiseFrameHelper::init_handshake_() {
   APIError aerr = handle_noise_error_(err, LOG_STR("noise_handshake_init"), APIError::HANDSHAKESTATE_SETUP_FAILED);
   if (aerr != APIError::OK)
     return aerr;
-  // init copies the prologue into the handshakestate, so we can get rid of it now
-  prologue_.release();
   return APIError::OK;
 }
 

esphome/components/api/api_pb2.cpp

@@ -1061,6 +1061,16 @@ uint32_t NoiseEncryptionSetKeyResponse::calculate_size() const {
   size += ProtoSize::calc_bool(1, this->success);
   return size;
 }
+uint8_t *NoiseResumeTicket::encode(ProtoWriteBuffer &buffer PROTO_ENCODE_DEBUG_PARAM) const {
+  uint8_t *__restrict__ pos = buffer.get_pos();
+  ProtoEncode::encode_bytes(pos PROTO_ENCODE_DEBUG_ARG, 1, this->ticket_ptr_, this->ticket_len_);
+  return pos;
+}
+uint32_t NoiseResumeTicket::calculate_size() const {
+  uint32_t size = 0;
+  size += ProtoSize::calc_length(1, this->ticket_len_);
+  return size;
+}
 #endif
 #ifdef USE_API_HOMEASSISTANT_SERVICES
 uint8_t *HomeassistantServiceMap::encode(ProtoWriteBuffer &buffer PROTO_ENCODE_DEBUG_PARAM) const {

esphome/components/api/api_pb2.h

@@ -1147,6 +1147,27 @@ class NoiseEncryptionSetKeyResponse final : public ProtoMessage {
 
  protected:
 };
+class NoiseResumeTicket final : public ProtoMessage {
+ public:
+  static constexpr uint16_t MESSAGE_TYPE = 152;
+  static constexpr uint8_t ESTIMATED_SIZE = 19;
+#ifdef HAS_PROTO_MESSAGE_DUMP
+  const LogString *message_name() const override { return LOG_STR("noise_resume_ticket"); }
+#endif
+  const uint8_t *ticket_ptr_{nullptr};
+  size_t ticket_len_{0};
+  void set_ticket(const uint8_t *data, size_t len) {
+    this->ticket_ptr_ = data;
+    this->ticket_len_ = len;
+  }
+  uint8_t *encode(ProtoWriteBuffer &buffer PROTO_ENCODE_DEBUG_PARAM) const;
+  uint32_t calculate_size() const;
+#ifdef HAS_PROTO_MESSAGE_DUMP
+  const char *dump_to(DumpBuffer &out) const override;
+#endif
+
+ protected:
+};
 #endif
 #ifdef USE_API_HOMEASSISTANT_SERVICES
 class HomeassistantServiceMap final : public ProtoMessage {

esphome/components/api/api_pb2_dump.cpp

@@ -1393,6 +1393,10 @@ const char *NoiseEncryptionSetKeyResponse::dump_to(DumpBuffer &out) const {
   dump_field(out, ESPHOME_PSTR("success"), this->success);
   return out.c_str();
 }
+const char *NoiseResumeTicket::dump_to(DumpBuffer &out) const {
+  out.append_p(ESPHOME_PSTR("NoiseResumeTicket {}"));
+  return out.c_str();
+}
 #endif
 #ifdef USE_API_HOMEASSISTANT_SERVICES
 const char *HomeassistantServiceMap::dump_to(DumpBuffer &out) const {

esphome/components/noise/noise.h

@@ -6,6 +6,8 @@
 #include <cstdint>
 #include "esphome/core/log.h"
 
+#include "noise_resume.h"
+
 namespace esphome::noise {
 
 using psk_t = std::array<uint8_t, 32>;
@@ -26,12 +28,16 @@ class NoiseContext {
   void set_psk(psk_t psk) {
     this->psk_ = psk;
     this->has_psk_ = !is_all_zeros(psk);
+    // Resume tickets were minted under the old key; forget them
+    this->resume_cache_.clear();
   }
   const psk_t &get_psk() const { return this->psk_; }
   bool has_psk() const { return this->has_psk_; }
+  ResumeTicketCache &resume_cache() { return this->resume_cache_; }
 
  protected:
   psk_t psk_{};
+  ResumeTicketCache resume_cache_;
   bool has_psk_{false};
 };
 

esphome/components/noise/noise_resume.cpp

@@ -0,0 +1,127 @@
+#include "noise_resume.h"
+#ifdef USE_NOISE
+#include <cstring>
+
+#include <noise/protocol.h>
+
+#include "esphome/core/hal.h"
+#include "esphome/core/helpers.h"
+
+namespace esphome::noise {
+
+const char RESUME_LABEL_OFFER[6] PROGMEM = "offer";
+const char RESUME_LABEL_CONFIRM[8] PROGMEM = "confirm";
+const char RESUME_LABEL_KEYS[5] PROGMEM = "keys";
+bool resume_kdf(const uint8_t *secret, const char *label, size_t label_len, const uint8_t *a, size_t a_len,
+                const uint8_t *b, size_t b_len, const uint8_t *hash_in, size_t hash_in_len, uint8_t *out1,
+                size_t out1_len, uint8_t *out2) {
+  uint8_t data[RESUME_KDF_MAX_DATA];
+  uint8_t scratch[32];
+  size_t len = label_len + a_len + b_len;
+  progmem_memcpy(data, label, label_len);
+  std::memcpy(data + label_len, a, a_len);
+  std::memcpy(data + label_len + a_len, b, b_len);
+  NoiseHashState *hash = nullptr;
+  if (noise_hashstate_new_by_id(&hash, NOISE_HASH_SHA256) != NOISE_ERROR_NONE) {
+    return false;
+  }
+  int err = NOISE_ERROR_NONE;
+  if (hash_in != nullptr) {
+    err = noise_hashstate_hash_one(hash, hash_in, hash_in_len, data + len, 32);
+    len += 32;
+  }
+  if (err == NOISE_ERROR_NONE) {
+    err = noise_hashstate_hkdf(hash, secret, RESUME_SECRET_SIZE, data, len, out1, out1_len,
+                               out2 != nullptr ? out2 : scratch, 32);
+  }
+  noise_hashstate_free(hash);
+  noise_clean(data, sizeof(data));
+  noise_clean(scratch, sizeof(scratch));
+  return err == NOISE_ERROR_NONE;
+}
+
+bool ResumeTicketCache::issue(ResumeTicket &out) {
+  if (!random_bytes(reinterpret_cast<uint8_t *>(&out), sizeof(out))) {
+    return false;
+  }
+  uint8_t slot = this->next_;
+  this->next_ = static_cast<uint8_t>((slot + 1) % SLOTS);
+  this->slots_[slot] = out;
+  this->used_mask_ |= static_cast<uint8_t>(1u << slot);
+  return true;
+}
+
+size_t ResumeTicketCache::try_accept(const uint8_t *offer, size_t offer_len, const uint8_t *prologue,
+                                     size_t prologue_len, uint8_t *out_ext, size_t out_capacity,
+                                     NoiseCipherState *&send_cipher, NoiseCipherState *&recv_cipher) {
+  if (offer_len != RESUME_OFFER_SIZE || offer[0] != RESUME_OFFER_VERSION || out_capacity < RESUME_ACCEPT_SIZE) {
+    return 0;
+  }
+  const uint8_t *session_id = offer + RESUME_OFFER_SESSION_ID_OFFSET;
+  const uint8_t *client_nonce = offer + RESUME_OFFER_NONCE_OFFSET;
+  ResumeTicket *ticket = nullptr;
+  for (uint8_t i = 0; i < SLOTS; i++) {
+    if ((this->used_mask_ & (1u << i)) &&
+        std::memcmp(this->slots_[i].session_id, session_id, RESUME_SESSION_ID_SIZE) == 0) {
+      ticket = &this->slots_[i];
+      this->used_mask_ &= static_cast<uint8_t>(~(1u << i));
+      break;
+    }
+  }
+  if (ticket == nullptr) {
+    return 0;
+  }
+  uint8_t expected[RESUME_MAC_SIZE];
+  bool ok = resume_compute_offer_mac(ticket->secret, session_id, client_nonce, expected) &&
+            noise_is_equal(expected, offer + RESUME_OFFER_MAC_OFFSET, RESUME_MAC_SIZE);
+  noise_clean(expected, sizeof(expected));
+  if (!ok) {
+    // Bad MAC: keep the ticket so a forger cannot burn it
+    this->used_mask_ |= static_cast<uint8_t>(1u << static_cast<uint8_t>(ticket - this->slots_));
+    return 0;
+  }
+  // The ticket is spent from here; any later failure falls back to the full
+  // handshake and the client gets a fresh one.
+  uint8_t *server_nonce = out_ext + 1;
+  uint8_t k_c2d[32];
+  uint8_t k_d2c[32];
+  out_ext[0] = RESUME_ACCEPT_VERSION;
+  ok = random_bytes(server_nonce, RESUME_NONCE_SIZE) &&
+       resume_compute_confirm_mac(ticket->secret, client_nonce, server_nonce, out_ext + 1 + RESUME_NONCE_SIZE) &&
+       resume_derive_keys(ticket->secret, client_nonce, server_nonce, prologue, prologue_len, k_c2d, k_d2c);
+  noise_clean(ticket, sizeof(*ticket));
+  if (ok) {
+    recv_cipher = resume_make_cipher(k_c2d);
+    send_cipher = resume_make_cipher(k_d2c);
+    ok = recv_cipher != nullptr && send_cipher != nullptr;
+    if (!ok) {
+      noise_cipherstate_free(recv_cipher);
+      noise_cipherstate_free(send_cipher);
+      recv_cipher = nullptr;
+      send_cipher = nullptr;
+    }
+  }
+  noise_clean(k_c2d, sizeof(k_c2d));
+  noise_clean(k_d2c, sizeof(k_d2c));
+  return ok ? RESUME_ACCEPT_SIZE : 0;
+}
+
+void ResumeTicketCache::clear() {
+  noise_clean(this->slots_, sizeof(this->slots_));
+  this->used_mask_ = 0;
+}
+
+NoiseCipherState *resume_make_cipher(const uint8_t *key) {
+  NoiseCipherState *cipher = nullptr;
+  if (noise_cipherstate_new_by_id(&cipher, NOISE_CIPHER_CHACHAPOLY) != NOISE_ERROR_NONE) {
+    return nullptr;
+  }
+  if (noise_cipherstate_init_key(cipher, key, 32) != NOISE_ERROR_NONE) {
+    noise_cipherstate_free(cipher);
+    return nullptr;
+  }
+  return cipher;
+}
+
+}  // namespace esphome::noise
+#endif  // USE_NOISE

esphome/components/noise/noise_resume.h

@@ -0,0 +1,132 @@
+#pragma once
+#include "esphome/core/defines.h"
+#ifdef USE_NOISE
+#include <cstddef>
+#include <cstdint>
+
+// Forward declaration matching <noise/protocol/cipherstate.h>; keeps noise-c
+// headers out of everything that includes noise.h.
+extern "C" {
+typedef struct NoiseCipherState_s NoiseCipherState;  // NOLINT(modernize-use-using)
+}
+
+namespace esphome::noise {
+
+/** Session resume for the noise transports.
+ *
+ * After a full handshake the responder issues a single-use ticket over the
+ * encrypted channel. A client presents it in its next ClientHello and both
+ * sides derive the transport keys with HKDF-SHA256 alone, skipping the two
+ * curve25519 operations. Old peers ignore the extension bytes on both
+ * sides, so every mismatch degrades to a normal full handshake.
+ *
+ * HKDF is the Noise construction (noise_hashstate_hkdf). Derivations:
+ *   offer_mac   = HKDF(secret, "offer"   || session_id || client_nonce).out1[:16]
+ *   confirm_mac = HKDF(secret, "confirm" || client_nonce || server_nonce).out1[:16]
+ *   k_c2d, k_d2c = HKDF(secret, "keys" || client_nonce || server_nonce || SHA256(prologue))
+ *
+ * An offering client sends handshake message 1 only after a decline.
+ * Resumed sessions have no ephemeral DH; the ticket is wiped on use.
+ */
+
+static constexpr uint8_t RESUME_OFFER_VERSION = 0x01;
+static constexpr uint8_t RESUME_ACCEPT_VERSION = 0x01;
+static constexpr size_t RESUME_SESSION_ID_SIZE = 8;
+static constexpr size_t RESUME_NONCE_SIZE = 16;
+static constexpr size_t RESUME_MAC_SIZE = 16;
+static constexpr size_t RESUME_SECRET_SIZE = 32;
+
+// ClientHello body: version | session_id | client_nonce | offer_mac
+static constexpr size_t RESUME_OFFER_SIZE = 1 + RESUME_SESSION_ID_SIZE + RESUME_NONCE_SIZE + RESUME_MAC_SIZE;  // 41
+static constexpr size_t RESUME_OFFER_SESSION_ID_OFFSET = 1;
+static constexpr size_t RESUME_OFFER_NONCE_OFFSET = RESUME_OFFER_SESSION_ID_OFFSET + RESUME_SESSION_ID_SIZE;
+static constexpr size_t RESUME_OFFER_MAC_OFFSET = RESUME_OFFER_NONCE_OFFSET + RESUME_NONCE_SIZE;
+
+// ServerHello trailing extension: version | server_nonce | confirm_mac
+static constexpr size_t RESUME_ACCEPT_SIZE = 1 + RESUME_NONCE_SIZE + RESUME_MAC_SIZE;  // 33
+
+struct ResumeTicket {
+  uint8_t session_id[RESUME_SESSION_ID_SIZE];
+  uint8_t secret[RESUME_SECRET_SIZE];
+};
+// Sent on the wire as one blob: session_id || secret
+static_assert(sizeof(ResumeTicket) == RESUME_SESSION_ID_SIZE + RESUME_SECRET_SIZE, "ticket must be packed");
+
+/// Fixed-slot RAM cache of single-use resume tickets. Lost on reboot by
+/// design: clients fall back to a full handshake.
+class ResumeTicketCache {
+ public:
+  /// Generate a fresh ticket into out and store it, evicting the oldest
+  /// slot. Returns false (and stores nothing) if the RNG fails.
+  bool issue(ResumeTicket &out);
+  /// Accept a resume offer: verify and consume the ticket (single use; a
+  /// forged MAC never burns one), build both transport ciphers, and write
+  /// the ServerHello accept extension into out_ext. Returns the extension
+  /// length, or 0 (nothing allocated) on any miss, failure, or when
+  /// out_capacity is too small. Secrets are wiped internally.
+  size_t try_accept(const uint8_t *offer, size_t offer_len, const uint8_t *prologue, size_t prologue_len,
+                    uint8_t *out_ext, size_t out_capacity, NoiseCipherState *&send_cipher,
+                    NoiseCipherState *&recv_cipher);
+  /// Forget every ticket (PSK change).
+  void clear();
+
+  // Round robin; more clients than slots thrash and fall back to full handshakes
+  static constexpr uint8_t SLOTS = 2;
+  static_assert(SLOTS <= 8, "used_mask_ is uint8_t");
+
+ protected:
+  ResumeTicket slots_[SLOTS];
+  uint8_t used_mask_{0};
+  uint8_t next_{0};
+};
+
+/// HKDF labels, PROGMEM on ESP8266.
+extern const char RESUME_LABEL_OFFER[6];
+extern const char RESUME_LABEL_CONFIRM[8];
+extern const char RESUME_LABEL_KEYS[5];
+
+// Largest KDF input: "keys" || client_nonce || server_nonce || SHA256(prologue)
+static constexpr size_t RESUME_KDF_MAX_DATA =
+    sizeof(RESUME_LABEL_KEYS) - 1 + RESUME_NONCE_SIZE + RESUME_NONCE_SIZE + 32;
+
+/// Noise-construction HKDF-SHA256 keyed with the ticket secret over
+/// label || a || b [|| SHA256(hash_in)], at most RESUME_KDF_MAX_DATA. out2 == nullptr means MAC only.
+bool resume_kdf(const uint8_t *secret, const char *label, size_t label_len, const uint8_t *a, size_t a_len,
+                const uint8_t *b, size_t b_len, const uint8_t *hash_in, size_t hash_in_len, uint8_t *out1,
+                size_t out1_len, uint8_t *out2);
+
+/// offer_mac for the ClientHello resume offer (what a client computes and
+/// try_accept checks).
+inline bool resume_compute_offer_mac(const uint8_t *secret, const uint8_t *session_id, const uint8_t *client_nonce,
+                                     uint8_t *out_mac) {
+  static_assert(sizeof(RESUME_LABEL_OFFER) - 1 + RESUME_SESSION_ID_SIZE + RESUME_NONCE_SIZE <= RESUME_KDF_MAX_DATA,
+                "KDF buffer");
+  return resume_kdf(secret, RESUME_LABEL_OFFER, sizeof(RESUME_LABEL_OFFER) - 1, session_id, RESUME_SESSION_ID_SIZE,
+                    client_nonce, RESUME_NONCE_SIZE, nullptr, 0, out_mac, RESUME_MAC_SIZE, nullptr);
+}
+
+/// confirm_mac for the ServerHello extension.
+inline bool resume_compute_confirm_mac(const uint8_t *secret, const uint8_t *client_nonce, const uint8_t *server_nonce,
+                                       uint8_t *out_mac) {
+  static_assert(sizeof(RESUME_LABEL_CONFIRM) - 1 + RESUME_NONCE_SIZE + RESUME_NONCE_SIZE <= RESUME_KDF_MAX_DATA,
+                "KDF buffer");
+  return resume_kdf(secret, RESUME_LABEL_CONFIRM, sizeof(RESUME_LABEL_CONFIRM) - 1, client_nonce, RESUME_NONCE_SIZE,
+                    server_nonce, RESUME_NONCE_SIZE, nullptr, 0, out_mac, RESUME_MAC_SIZE, nullptr);
+}
+
+/// Derive the transport keys. k_c2d encrypts client-to-device traffic,
+/// k_d2c device-to-client.
+inline bool resume_derive_keys(const uint8_t *secret, const uint8_t *client_nonce, const uint8_t *server_nonce,
+                               const uint8_t *prologue, size_t prologue_len, uint8_t *k_c2d, uint8_t *k_d2c) {
+  static_assert(sizeof(RESUME_LABEL_KEYS) - 1 + RESUME_NONCE_SIZE + RESUME_NONCE_SIZE + 32 <= RESUME_KDF_MAX_DATA,
+                "KDF buffer");
+  return resume_kdf(secret, RESUME_LABEL_KEYS, sizeof(RESUME_LABEL_KEYS) - 1, client_nonce, RESUME_NONCE_SIZE,
+                    server_nonce, RESUME_NONCE_SIZE, prologue, prologue_len, k_c2d, 32, k_d2c);
+}
+
+/// Build a ChaChaPoly cipher state keyed with key (32 bytes); nullptr on
+/// failure. Nonce counter starts at 0, exactly like a post-split cipher.
+NoiseCipherState *resume_make_cipher(const uint8_t *key);
+
+}  // namespace esphome::noise
+#endif  // USE_NOISE

script/api_protobuf/api_protobuf.py

@@ -2531,6 +2531,11 @@ def calculate_message_max_size(desc: descriptor.DescriptorProto) -> int | None:
     return total_size
 
 
+# Contents must never reach the log: dump_to prints only the name
+SENSITIVE_MESSAGES = {"NoiseResumeTicket"}
+SENSITIVE_MESSAGES_SEEN: set[str] = set()
+
+
 def build_message_type(
     desc: descriptor.DescriptorProto,
     base_class_fields: dict[str, list[descriptor.FieldDescriptorProto]],
@@ -2808,6 +2813,10 @@ def build_message_type(
         public_content.append(prot)
     # If no fields to calculate size for or message doesn't need encoding, the default implementation in ProtoMessage will be used
 
+    if desc.name in SENSITIVE_MESSAGES:
+        dump = []
+        SENSITIVE_MESSAGES_SEEN.add(desc.name)
+
     # dump_to method declaration in header
     prot = "#ifdef HAS_PROTO_MESSAGE_DUMP\n"
     prot += "const char *dump_to(DumpBuffer &out) const override;\n"
@@ -3715,6 +3724,11 @@ static const char *const TAG = "api.service";
     except ImportError:
         pass
 
+    # A renamed message must fail the build, not silently start dumping secrets
+    missing = SENSITIVE_MESSAGES - SENSITIVE_MESSAGES_SEEN
+    if missing:
+        raise RuntimeError(f"SENSITIVE_MESSAGES not found in api.proto: {missing}")
+
 
 if __name__ == "__main__":
     sys.exit(main())

tests/components/noise/test_noise_resume.cpp

@@ -0,0 +1,224 @@
+#include <gtest/gtest.h>
+
+#include <cstring>
+
+#include <noise/protocol.h>
+
+#include "esphome/components/noise/noise.h"
+#include "esphome/components/noise/noise_resume.h"
+
+namespace esphome::noise::testing {
+
+// Known-answer vectors shared with the client implementation
+// (aioesphomeapi tests/test_noise_resume.py); the two must stay identical
+// byte for byte or resumed sessions cannot interoperate.
+static const uint8_t KAT_SECRET[RESUME_SECRET_SIZE] = {1,  2,  3,  4,  5,  6,  7,  8,  9,  10, 11, 12, 13, 14, 15, 16,
+                                                       17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32};
+static const uint8_t KAT_SESSION_ID[RESUME_SESSION_ID_SIZE] = {0xa0, 0xa1, 0xa2, 0xa3, 0xa4, 0xa5, 0xa6, 0xa7};
+static const uint8_t KAT_CLIENT_NONCE[RESUME_NONCE_SIZE] = {0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
+                                                            0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f};
+static const uint8_t KAT_SERVER_NONCE[RESUME_NONCE_SIZE] = {0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37,
+                                                            0x38, 0x39, 0x3a, 0x3b, 0x3c, 0x3d, 0x3e, 0x3f};
+static const uint8_t KAT_OFFER_MAC[RESUME_MAC_SIZE] = {0xa8, 0x08, 0xea, 0xdb, 0xec, 0x81, 0xa7, 0xcb,
+                                                       0xf4, 0xca, 0xaa, 0xb8, 0x0d, 0x7f, 0x9d, 0x01};
+static const uint8_t KAT_CONFIRM_MAC[RESUME_MAC_SIZE] = {0x09, 0xa3, 0x70, 0x3e, 0xc8, 0x34, 0x77, 0xe9,
+                                                         0x45, 0xe7, 0xf1, 0x61, 0x9d, 0x4f, 0x6a, 0x76};
+static const uint8_t KAT_K_C2D[32] = {0xd6, 0x01, 0xe3, 0xc1, 0x16, 0xa1, 0x64, 0x66, 0xdb, 0xc5, 0x9e,
+                                      0xdd, 0x60, 0x2a, 0x64, 0x1e, 0xbe, 0xf5, 0x11, 0x95, 0x98, 0xd2,
+                                      0xf2, 0x47, 0x1b, 0xc6, 0x8c, 0x51, 0x8f, 0xbe, 0xb7, 0x23};
+static const uint8_t KAT_K_D2C[32] = {0x7f, 0x8d, 0x57, 0x7e, 0x9f, 0xb4, 0xbb, 0xde, 0x86, 0xcd, 0xa9,
+                                      0xf4, 0x9b, 0x42, 0xe7, 0x24, 0xc8, 0x49, 0xce, 0x89, 0xd8, 0x96,
+                                      0x3f, 0x3c, 0x4b, 0x3f, 0x8f, 0x80, 0xc2, 0x56, 0xab, 0x65};
+
+/// The one place in this file that spells the offer wire layout
+static void build_offer(uint8_t *offer, const uint8_t *session_id, const uint8_t *client_nonce, const uint8_t *mac) {
+  offer[0] = RESUME_OFFER_VERSION;
+  std::memcpy(offer + RESUME_OFFER_SESSION_ID_OFFSET, session_id, RESUME_SESSION_ID_SIZE);
+  std::memcpy(offer + RESUME_OFFER_NONCE_OFFSET, client_nonce, RESUME_NONCE_SIZE);
+  std::memcpy(offer + RESUME_OFFER_MAC_OFFSET, mac, RESUME_MAC_SIZE);
+}
+
+/// "NoiseAPIInit" || be16(len) || offer, exactly as the api frame helper mixes it
+static constexpr size_t KAT_PROLOGUE_SIZE = 12 + 2 + RESUME_OFFER_SIZE;
+static void build_prologue(uint8_t *out, const uint8_t *offer) {
+  std::memcpy(out, "NoiseAPIInit", 12);  // NOLINT(bugprone-not-null-terminated-result)
+  out[12] = 0x00;
+  out[13] = RESUME_OFFER_SIZE;
+  std::memcpy(out + 14, offer, RESUME_OFFER_SIZE);
+}
+
+static void build_offer_for_ticket(uint8_t *offer, const ResumeTicket &ticket, const uint8_t *client_nonce) {
+  uint8_t mac[RESUME_MAC_SIZE];
+  ASSERT_TRUE(resume_compute_offer_mac(ticket.secret, ticket.session_id, client_nonce, mac));
+  build_offer(offer, ticket.session_id, client_nonce, mac);
+}
+
+/// Test access to the protected slots so a test can plant the KAT ticket
+struct TestCache : ResumeTicketCache {
+  void plant(const uint8_t *session_id, const uint8_t *secret) {
+    std::memcpy(this->slots_[0].session_id, session_id, RESUME_SESSION_ID_SIZE);
+    std::memcpy(this->slots_[0].secret, secret, RESUME_SECRET_SIZE);
+    this->used_mask_ |= 1u;
+  }
+};
+
+TEST(NoiseResumeKat, ConfirmMacMatchesClientImplementation) {
+  uint8_t mac[RESUME_MAC_SIZE];
+  ASSERT_TRUE(resume_compute_confirm_mac(KAT_SECRET, KAT_CLIENT_NONCE, KAT_SERVER_NONCE, mac));
+  EXPECT_EQ(std::memcmp(mac, KAT_CONFIRM_MAC, RESUME_MAC_SIZE), 0);
+}
+
+TEST(NoiseResumeKat, OfferMacMatchesClientImplementation) {
+  uint8_t mac[RESUME_MAC_SIZE];
+  ASSERT_TRUE(resume_compute_offer_mac(KAT_SECRET, KAT_SESSION_ID, KAT_CLIENT_NONCE, mac));
+  EXPECT_EQ(std::memcmp(mac, KAT_OFFER_MAC, RESUME_MAC_SIZE), 0);
+}
+
+TEST(NoiseResumeKat, KeyDerivationMatchesClientImplementation) {
+  // Prologue used by the shared vectors: "NoiseAPIInit" + be16(41) + a
+  // 41-byte offer whose MAC field is 16 bytes of 0xEE
+  uint8_t mac_filler[RESUME_MAC_SIZE];
+  std::memset(mac_filler, 0xEE, sizeof(mac_filler));
+  uint8_t offer[RESUME_OFFER_SIZE];
+  build_offer(offer, KAT_SESSION_ID, KAT_CLIENT_NONCE, mac_filler);
+  uint8_t prologue[KAT_PROLOGUE_SIZE];
+  build_prologue(prologue, offer);
+
+  uint8_t k_c2d[32], k_d2c[32];
+  ASSERT_TRUE(
+      resume_derive_keys(KAT_SECRET, KAT_CLIENT_NONCE, KAT_SERVER_NONCE, prologue, sizeof(prologue), k_c2d, k_d2c));
+  EXPECT_EQ(std::memcmp(k_c2d, KAT_K_C2D, 32), 0);
+  EXPECT_EQ(std::memcmp(k_d2c, KAT_K_D2C, 32), 0);
+}
+
+TEST(NoiseResumeCache, TryAcceptConsumesTicketOnceAndProvesPossession) {
+  TestCache cache;
+  cache.plant(KAT_SESSION_ID, KAT_SECRET);
+
+  uint8_t offer[RESUME_OFFER_SIZE];
+  build_offer(offer, KAT_SESSION_ID, KAT_CLIENT_NONCE, KAT_OFFER_MAC);
+  uint8_t prologue[KAT_PROLOGUE_SIZE];
+  build_prologue(prologue, offer);
+
+  uint8_t ext[RESUME_ACCEPT_SIZE];
+  NoiseCipherState *send = nullptr, *recv = nullptr;
+  ASSERT_EQ(cache.try_accept(offer, sizeof(offer), prologue, sizeof(prologue), ext, sizeof(ext), send, recv),
+            RESUME_ACCEPT_SIZE);
+  ASSERT_NE(send, nullptr);
+  ASSERT_NE(recv, nullptr);
+
+  // The extension proves possession: verify like the client does
+  EXPECT_EQ(ext[0], RESUME_ACCEPT_VERSION);
+  const uint8_t *server_nonce = ext + 1;
+  uint8_t expected_confirm[RESUME_MAC_SIZE];
+  ASSERT_TRUE(resume_compute_confirm_mac(KAT_SECRET, KAT_CLIENT_NONCE, server_nonce, expected_confirm));
+  EXPECT_EQ(std::memcmp(ext + 1 + RESUME_NONCE_SIZE, expected_confirm, RESUME_MAC_SIZE), 0);
+
+  // The ciphers must interoperate with the documented key derivation
+  uint8_t k_c2d[32], k_d2c[32];
+  ASSERT_TRUE(resume_derive_keys(KAT_SECRET, KAT_CLIENT_NONCE, server_nonce, prologue, sizeof(prologue), k_c2d, k_d2c));
+  NoiseCipherState *client_send = resume_make_cipher(k_c2d);
+  ASSERT_NE(client_send, nullptr);
+  uint8_t buf[64] = "resumed";
+  NoiseBuffer nb;
+  noise_buffer_init(nb);
+  noise_buffer_set_inout(nb, buf, 7, sizeof(buf));
+  ASSERT_EQ(noise_cipherstate_encrypt(client_send, &nb), NOISE_ERROR_NONE);
+  ASSERT_EQ(noise_cipherstate_decrypt(recv, &nb), NOISE_ERROR_NONE);
+  EXPECT_EQ(std::memcmp(buf, "resumed", 7), 0);
+  noise_cipherstate_free(client_send);
+  noise_cipherstate_free(send);
+  noise_cipherstate_free(recv);
+
+  // Single use: the same offer must miss the second time
+  NoiseCipherState *send2 = nullptr, *recv2 = nullptr;
+  EXPECT_EQ(cache.try_accept(offer, sizeof(offer), prologue, sizeof(prologue), ext, sizeof(ext), send2, recv2), 0u);
+  EXPECT_EQ(send2, nullptr);
+  EXPECT_EQ(recv2, nullptr);
+}
+
+TEST(NoiseResumeCache, BadMacOrMalformedOfferLeavesTicketIntact) {
+  TestCache cache;
+  cache.plant(KAT_SESSION_ID, KAT_SECRET);
+
+  uint8_t offer[RESUME_OFFER_SIZE];
+  uint8_t bad_mac[RESUME_MAC_SIZE];
+  std::memcpy(bad_mac, KAT_OFFER_MAC, RESUME_MAC_SIZE);
+  bad_mac[0] ^= 0x01;
+  build_offer(offer, KAT_SESSION_ID, KAT_CLIENT_NONCE, bad_mac);
+
+  uint8_t prologue[1] = {0};
+  uint8_t ext[RESUME_ACCEPT_SIZE];
+  NoiseCipherState *send = nullptr, *recv = nullptr;
+  // A forged offer must not burn the ticket
+  EXPECT_EQ(cache.try_accept(offer, sizeof(offer), prologue, sizeof(prologue), ext, sizeof(ext), send, recv), 0u);
+  // Wrong size or version must be recognized as "no offer"
+  build_offer(offer, KAT_SESSION_ID, KAT_CLIENT_NONCE, KAT_OFFER_MAC);
+  EXPECT_EQ(cache.try_accept(offer, sizeof(offer) - 1, prologue, sizeof(prologue), ext, sizeof(ext), send, recv), 0u);
+  offer[0] = 0x7f;
+  EXPECT_EQ(cache.try_accept(offer, sizeof(offer), prologue, sizeof(prologue), ext, sizeof(ext), send, recv), 0u);
+  offer[0] = RESUME_OFFER_VERSION;
+  // No room for the extension must also decline without burning it
+  EXPECT_EQ(cache.try_accept(offer, sizeof(offer), prologue, sizeof(prologue), ext, sizeof(ext) - 1, send, recv), 0u);
+  // The genuine offer still redeems
+  EXPECT_EQ(cache.try_accept(offer, sizeof(offer), prologue, sizeof(prologue), ext, sizeof(ext), send, recv),
+            RESUME_ACCEPT_SIZE);
+  noise_cipherstate_free(send);
+  noise_cipherstate_free(recv);
+}
+
+TEST(NoiseResumeCache, SetPskForgetsTickets) {
+  NoiseContext ctx;
+  ResumeTicket ticket;
+  ASSERT_TRUE(ctx.resume_cache().issue(ticket));
+
+  psk_t psk{};
+  psk[0] = 1;
+  ctx.set_psk(psk);
+
+  uint8_t offer[RESUME_OFFER_SIZE];
+  build_offer_for_ticket(offer, ticket, KAT_CLIENT_NONCE);
+  uint8_t prologue[KAT_PROLOGUE_SIZE];
+  build_prologue(prologue, offer);
+  uint8_t ext[RESUME_ACCEPT_SIZE];
+  NoiseCipherState *send = nullptr, *recv = nullptr;
+  EXPECT_EQ(
+      ctx.resume_cache().try_accept(offer, sizeof(offer), prologue, sizeof(prologue), ext, sizeof(ext), send, recv),
+      0u);
+  EXPECT_EQ(send, nullptr);
+  EXPECT_EQ(recv, nullptr);
+}
+
+TEST(NoiseResumeCache, IssueRotatesSlotsAndClearForgetsAll) {
+  ResumeTicketCache cache;
+  ResumeTicket tickets[ResumeTicketCache::SLOTS + 1];
+  for (auto &ticket : tickets) {
+    ASSERT_TRUE(cache.issue(ticket));
+  }
+  uint8_t offer[RESUME_OFFER_SIZE];
+  uint8_t prologue[1] = {0};
+  uint8_t ext[RESUME_ACCEPT_SIZE];
+
+  // The oldest ticket was evicted by the one-past-capacity issue
+  build_offer_for_ticket(offer, tickets[0], KAT_CLIENT_NONCE);
+  NoiseCipherState *send = nullptr, *recv = nullptr;
+  EXPECT_EQ(cache.try_accept(offer, sizeof(offer), prologue, sizeof(prologue), ext, sizeof(ext), send, recv), 0u);
+  // The rest remain redeemable
+  for (int i = 1; i <= ResumeTicketCache::SLOTS; i++) {
+    build_offer_for_ticket(offer, tickets[i], KAT_CLIENT_NONCE);
+    EXPECT_EQ(cache.try_accept(offer, sizeof(offer), prologue, sizeof(prologue), ext, sizeof(ext), send, recv),
+              RESUME_ACCEPT_SIZE);
+    noise_cipherstate_free(send);
+    noise_cipherstate_free(recv);
+    send = recv = nullptr;
+  }
+
+  // clear() forgets everything
+  ResumeTicket ticket;
+  ASSERT_TRUE(cache.issue(ticket));
+  cache.clear();
+  build_offer_for_ticket(offer, ticket, KAT_CLIENT_NONCE);
+  EXPECT_EQ(cache.try_accept(offer, sizeof(offer), prologue, sizeof(prologue), ext, sizeof(ext), send, recv), 0u);
+}
+
+}  // namespace esphome::noise::testing

tests/integration/fixtures/api_noise_resume.yaml

@@ -0,0 +1,9 @@
+esphome:
+  name: host-noise-resume
+host:
+api:
+  encryption:
+    key: N4Yle5YirwZhPiHHsdZLdOA73ndj/84veVaLhTvxCuU=
+# VERY_VERBOSE so the frame helper logs "Session resumed!"
+logger:
+  level: VERY_VERBOSE

tests/integration/test_api_noise_resume.py

@@ -0,0 +1,58 @@
+"""Integration test for noise session resume."""
+
+from __future__ import annotations
+
+import asyncio
+
+import aioesphomeapi.core
+import pytest
+
+from .types import APIClientConnectedFactory, RunCompiledFunction
+
+NOISE_KEY = "N4Yle5YirwZhPiHHsdZLdOA73ndj/84veVaLhTvxCuU="
+
+
+@pytest.mark.asyncio
+async def test_api_noise_resume(
+    yaml_config: str,
+    run_compiled: RunCompiledFunction,
+    api_client_connected: APIClientConnectedFactory,
+) -> None:
+    """A reconnect with the ticket from the first connection resumes the session."""
+    if not hasattr(aioesphomeapi.core, "ResumeAPIError"):
+        pytest.skip("aioesphomeapi without noise session resume")
+
+    resumed = asyncio.Event()
+    resumed_count = 0
+
+    def on_line(line: str) -> None:
+        nonlocal resumed_count
+        if "Session resumed" in line:
+            resumed_count += 1
+            resumed.set()
+
+    async with (
+        run_compiled(yaml_config, line_callback=on_line),
+        api_client_connected(noise_psk=NOISE_KEY) as client,
+    ):
+        # First connection: full handshake, the device issues a ticket
+        info = await client.device_info()
+        assert info.name == "host-noise-resume"
+        assert resumed_count == 0
+
+        # Same client reconnects and offers the ticket
+        await client.disconnect()
+        await client.connect(login=True)
+        info = await client.device_info()
+        assert info.name == "host-noise-resume"
+        await asyncio.wait_for(resumed.wait(), timeout=10.0)
+        assert resumed_count == 1
+        resumed.clear()
+
+        # The resumed session issued a fresh ticket, so it resumes again
+        await client.disconnect()
+        await client.connect(login=True)
+        info = await client.device_info()
+        assert info.name == "host-noise-resume"
+        await asyncio.wait_for(resumed.wait(), timeout=10.0)
+        assert resumed_count == 2