noise.h

Go to the documentation of this file.

#pragma once
#include "esphome/core/defines.h"
#ifdef USE_NOISE
#include <array>
#include <cstddef>
#include <cstdint>
#include "esphome/core/log.h"
 
// Forward decl from <noise/protocol.h>
using NoiseHandshakeState = struct NoiseHandshakeState_s;
 
namespace esphome::noise {
 
using psk_t = std::array<uint8_t, 32>;
 
class NoiseContext {
 public:
  // The all-zeros PSK is reserved: it marks the device as unprovisioned and
  // doubles as the well-known provisioning PSK that unprovisioned devices
  // accept for Noise handshakes (passive-sniffing protection only, no
  // authentication). It is never a valid real key.
  static bool is_all_zeros(const psk_t &psk) {
    uint8_t acc = 0;
    for (uint8_t b : psk) {
      acc |= b;
    }
    return acc == 0;
  }
  void set_psk(const uint8_t *psk) { this->psk_ = psk; }
  void load_psk(psk_t &out) const;
  bool has_psk() const { return this->psk_ != nullptr; }
 
 protected:
  const uint8_t *psk_{nullptr};
};
 
const LogString *noise_err_to_logstr(int err);
 
#ifdef USE_NOISE_SPARE_EPHEMERAL
// One responder ephemeral key pair made ahead of time (about 60 ms on ESP8266), refilled by the api server
// while idle and consumed by the next noise handshake of any transport; empty means the handshake generates
// its own. Private key then public key; the private key stays in RAM until consumed.
static constexpr size_t SPARE_EPHEMERAL_KEY_SIZE = 32;
static constexpr size_t SPARE_EPHEMERAL_SIZE = 2 * SPARE_EPHEMERAL_KEY_SIZE;
extern uint8_t spare_ephemeral[SPARE_EPHEMERAL_SIZE];  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
// The clamp always sets bit 254, so it doubles as the ready flag
inline bool has_spare_ephemeral() { return (spare_ephemeral[SPARE_EPHEMERAL_KEY_SIZE - 1] & 0x40) != 0; }
void prepare_spare_ephemeral();
int consume_spare_ephemeral(NoiseHandshakeState *state);
#endif
 
// Shared wire format for the noise transports (api and ota): every frame is
// FRAME_INDICATOR, a 16-bit big-endian payload length, then the payload.
// Handshake payloads start with a status byte; transport payloads end with
// the ChaCha20-Poly1305 MAC.
static constexpr uint8_t FRAME_INDICATOR = 0x01;
static constexpr size_t FRAME_HEADER_SIZE = 3;
static constexpr size_t MAC_SIZE = 16;
static constexpr size_t MAX_HANDSHAKE_SIZE = 128;
static constexpr uint8_t HANDSHAKE_STATUS_OK = 0x00;
static constexpr uint8_t HANDSHAKE_STATUS_REJECT = 0x01;
 
inline void write_frame_header(uint8_t *buf, uint16_t payload_len) {
  buf[0] = FRAME_INDICATOR;
  buf[1] = (uint8_t) (payload_len >> 8);
  buf[2] = (uint8_t) payload_len;
}
 
size_t format_reject_payload(uint8_t *buf, size_t capacity, const LogString *reason);
 
const LogString *reject_reason_for(int err);
 
static constexpr size_t MAC_FAILURE_PAYLOAD_SIZE = sizeof("Handshake MAC failure");
 
}  // namespace esphome::noise
#endif  // USE_NOISE