Skip to content

v3.1.0: DERP certificate check, WireGuard lock, ESP-IDF 6, light sleep

Choose a tag to compare

@Asimmimx Asimmimx released this 07 Nov 17:05
· 15 commits to main since this release

Security fixes for WireGuard and DERP, ESP-IDF 6 support, and automatic light sleep while the tailnet is idle. All of it was contributed by tozes in #2, #4 and #6 to #12.

Behaviour changes to know about

  • The DERP relay's certificate is now verified (CONFIG_ML_DERP_VERIFY_CERT, on by default). A self-hosted DERP server with a private certificate is refused (DERP certificate for <host> not accepted: ...) until you add its CA to the bundle or turn the option off. It adds about 70 KB of flash with the default full bundle, or 21 KB with CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_CMN.
  • TailTiny registers ESP-IDF's eventfd VFS in tailtiny_init() (default config) when CONFIG_VFS_SUPPORT_SELECT is on. If your application registers it itself with its own config, do that before tailtiny_init(): afterwards, esp_vfs_eventfd_register() returns ESP_ERR_INVALID_STATE. TailTiny reuses a VFS that's already registered.
  • ESP-IDF 5.0 to 5.2 are refused by the component manifest. They never built (esp_driver_tsens needs 5.3).
  • basic_connect is about 4 KB larger for the light-sleep change (eventfd VFS and select()).

Fixes

  • WireGuard: the timer task and lwIP's thread no longer share keypairs without a lock. Since the timers moved off lwIP's thread (wireguardif_periodic() on the WireGuard manager task), keepalives, handshakes, key expiry and incoming packets ran on that task while lwIP's thread encrypted outgoing data, with nothing between them. A keepalive and a data packet could take the same sending counter (the same ChaCha20-Poly1305 nonce under the same key), and a key could be wiped while a packet was being encrypted with it (#1). Each WireGuard device now has a mutex (wireguard-platform.h), held for everything that reads or changes keypairs, counters, handshake state and the peer table. Sends happen after it's released, to a copy of the peer's endpoint, because the UDP send waits for lwIP's thread (ml_tcpip_run()), which may be waiting for the lock. tests/host/check_wg_locking.py checks that rule in wireguardif.c; on v3.0.2's file it finds 35 unlocked calls.
  • DERP: the relay's TLS certificate is verified. The DERP connection used MBEDTLS_SSL_VERIFY_NONE, so anyone on the network path could pose as the relay. WireGuard still protected what it carried, but a fake relay could silently drop or delay it. The certificate is now checked against ESP-IDF's certificate bundle and the relay's host name (new CONFIG_ML_DERP_VERIFY_CERT, on by default; it needs MBEDTLS_CERTIFICATE_BUNDLE, also on by default). Tailscale's relays chain to ISRG Root X1, which the bundle has, from ESP-IDF v5.3.2 on. It links ESP-IDF's certificate bundle: about +70 KB of flash with the default full bundle, +21 KB with CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_CMN. Turn it off for a self-hosted DERP server with a private certificate. A refused certificate is logged with the reason.
  • idf_component.yml asks for ESP-IDF 5.3 or newer. It said 5.0, but TailTiny requires esp_driver_tsens, which ESP-IDF added in 5.3, so on 5.0 to 5.2 the build stopped at Failed to resolve component 'esp_driver_tsens'. The README already says 5.3 or newer.

ESP-IDF 6

  • cJSON comes from the component registry on ESP-IDF 6. ESP-IDF 6 no longer ships cJSON as the json component, so CMake stopped at Failed to resolve component 'json'. On ESP-IDF 6 and later, idf_component.yml now pulls espressif/cjson and TailTiny requires espressif__cjson. ESP-IDF 5 keeps its built-in json.
  • TailTiny requires the UART and GPIO driver components. ml_at_socket.c and ml_cellular.c include driver/uart.h and driver/gpio.h, which came through driver until ESP-IDF 6 split them out. TailTiny now requires esp_driver_uart and esp_driver_gpio, which exist from ESP-IDF 5.3 on.
  • Builds with GCC 15. GCC 15, which ESP-IDF 6 uses, rejects a byte array initialised from a string of exactly its length unless the array is marked nonstring, and ESP-IDF builds with -Werror. WireGuard's protocol names in wireguard.c (CONSTRUCTION, IDENTIFIER, LABEL_MAC1, LABEL_COOKIE) and Salsa20's constant in nacl_box.c are such arrays on purpose, and are now marked __attribute__((nonstring)) (GCC 8 and later).
  • DERP's TLS works with Mbed TLS 4. Mbed TLS 4, which ESP-IDF 6 ships, draws TLS randomness from PSA, made its entropy and CTR-DRBG modules private and removed mbedtls_ssl_conf_rng(). The DERP connection's entropy and CTR-DRBG contexts, their seeding and freeing, and the mbedtls_ssl_conf_rng() call are now compiled only with Mbed TLS 3 (MBEDTLS_VERSION_MAJOR < 4). ESP-IDF 6 initialises PSA at startup. Certificate verification (CONFIG_ML_DERP_VERIFY_CERT) is unchanged.
  • The Noise control channel uses wireguard-lwip's ChaCha20-Poly1305. Mbed TLS 4, which ESP-IDF 6 ships, made its ChaCha20-Poly1305 API private. ml_noise.c now uses the reference implementation that the bundled wireguard-lwip already uses for WireGuard, through noise_aead_encrypt()/noise_aead_decrypt() in the new src/ml_noise_aead.h, on every ESP-IDF version. Tailscale's nonce is 4 zero bytes and then the counter big-endian, while wireguard-lwip writes its counter little-endian into the same 8 bytes, so the wrapper passes the counter byte-swapped. tests/host/check_noise_aead.py checks it against RFC 8439's appendix A.5 vector in both byte orders, against messages sealed by Python's cryptography for other counters, an empty payload and no associated data, and that a changed byte, associated data, counter or a cut-short message is refused.

Power

  • The DERP and WireGuard tasks sleep until there's work. The DERP task polled TLS and then yielded for one tick, and the WireGuard task woke every 10 ms to check its RX queue. With CONFIG_FREERTOS_HZ=100 the chip needs a few idle ticks in a row before automatic light sleep (CONFIG_FREERTOS_USE_TICKLESS_IDLE) can engage, so with TailTiny running it almost never did. The DERP task now waits in one select() on the relay socket and an eventfd that's written whenever TX or a control request is queued, so outgoing relay packets still go out at once. It skips the wait while TX is queued or Mbed TLS holds decrypted data. The WireGuard task waits for a task notification that every producer for its queues sends. Both waits are capped at 100 ms for timers, reconnects and shutdown. An AT modem socket (cellular) can't be waited on with select(), so the DERP task keeps polling it, and it also polls when CONFIG_VFS_SUPPORT_SELECT is off or no eventfd can be created (a warning, not an init failure). tests/host/check_idle_wait.py runs the wait against a real socket and eventfd and checks the wiring.

How it was checked

  • All five examples build with ESP-IDF v5.3.2 with no warnings (basic_connect for esp32c3 and esp32s3, the others for esp32s3). The contributor also built them with ESP-IDF 6.1.
  • Host tests pass: run_tests.py, check_wg_locking.py, check_noise_aead.py and check_idle_wait.py.
  • On hardware: an ESP32-S3 running TailTiny inside the contributor's own firmware, built with ESP-IDF 6.1 (details in each PR). This release wasn't run on an ESP32-C3.

Full history: CHANGELOG.md