Repository navigation
v3.1.0: DERP certificate check, WireGuard lock, ESP-IDF 6, light sleep
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 withCONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_CMN. - TailTiny registers ESP-IDF's eventfd VFS in
tailtiny_init()(default config) whenCONFIG_VFS_SUPPORT_SELECTis on. If your application registers it itself with its own config, do that beforetailtiny_init(): afterwards,esp_vfs_eventfd_register()returnsESP_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_tsensneeds 5.3). basic_connectis about 4 KB larger for the light-sleep change (eventfd VFS andselect()).
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.pychecks that rule inwireguardif.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 (newCONFIG_ML_DERP_VERIFY_CERT, on by default; it needsMBEDTLS_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 withCONFIG_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.ymlasks for ESP-IDF 5.3 or newer. It said 5.0, but TailTiny requiresesp_driver_tsens, which ESP-IDF added in 5.3, so on 5.0 to 5.2 the build stopped atFailed 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
jsoncomponent, so CMake stopped atFailed to resolve component 'json'. On ESP-IDF 6 and later,idf_component.ymlnow pullsespressif/cjsonand TailTiny requiresespressif__cjson. ESP-IDF 5 keeps its built-injson. - TailTiny requires the UART and GPIO driver components.
ml_at_socket.candml_cellular.cincludedriver/uart.handdriver/gpio.h, which came throughdriveruntil ESP-IDF 6 split them out. TailTiny now requiresesp_driver_uartandesp_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 inwireguard.c(CONSTRUCTION,IDENTIFIER,LABEL_MAC1,LABEL_COOKIE) and Salsa20's constant innacl_box.care 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 thembedtls_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.cnow uses the reference implementation that the bundled wireguard-lwip already uses for WireGuard, throughnoise_aead_encrypt()/noise_aead_decrypt()in the newsrc/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.pychecks it against RFC 8439's appendix A.5 vector in both byte orders, against messages sealed by Python'scryptographyfor 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=100the 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 oneselect()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 withselect(), so the DERP task keeps polling it, and it also polls whenCONFIG_VFS_SUPPORT_SELECTis off or no eventfd can be created (a warning, not an init failure).tests/host/check_idle_wait.pyruns 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_connectfor 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.pyandcheck_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