TLS and Device Authentication
Every Syncthing connection is encrypted and mutually authenticated using TLS 1.3. Understanding how this works prevents misconfiguration and helps you audit your security posture.
Understand how Device IDs are derived from TLS certificates and why that design eliminates the need for a central certificate authority.
| Property | Detail |
|---|---|
| Protocol | TLS 1.3 (mandatory) |
| Authentication | Mutual — both peers verify each other |
| Certificate storage | ~/.local/share/syncthing/cert.pem + key.pem |
| Device ID derived from | SHA-256 of the device's public certificate |
| Trust model | TOFU — Trust On First Use |
How Device IDs Work
flowchart TD
A[Syncthing starts for the first time] --> B[Generates a self-signed TLS certificate]
B --> C[SHA-256 hash of the certificate public key]
C --> D[Luhn-encoded 63-character Device ID]
D --> E[Used to identify and trust the device permanently]
The Device ID is not a username or password — it is a cryptographic fingerprint. Sharing your Device ID with a peer allows them to establish an encrypted, authenticated channel. Anyone who does not have your Device ID cannot connect.
Viewing Your Certificate and Device ID
# Print Device ID from the command line
syncthing --device-id
# View the certificate files directly
ls -la ~/.local/share/syncthing/
# cert.pem key.pem config.xml ...
# Inspect the certificate
openssl x509 -in ~/.local/share/syncthing/cert.pem -noout -text | grep -E "Subject|Validity|Public"
Expected output:
MFZGK...-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX (63 chars)
Never share your key.pem file. The certificate (cert.pem) contains only the public key and is safe to share, but the private key must stay on the device. If key.pem is compromised, regenerate the certificate and re-authenticate all peers.
Certificate Regeneration
If you need to rotate the certificate (e.g., suspected key compromise):
# Stop Syncthing first
systemctl --user stop syncthing
# or
sudo systemctl stop syncthing@$USER
# Remove old certificate and key
rm ~/.local/share/syncthing/cert.pem
rm ~/.local/share/syncthing/key.pem
# Restart — Syncthing generates a new cert on startup
systemctl --user start syncthing
# Get the new Device ID
syncthing --device-id
Regenerating the certificate changes your Device ID. You must re-share the new ID with all peers and re-accept the connection on each pairing device.
Trust on First Use (TOFU)
Syncthing uses a TOFU model:
- First connection: You see the remote Device ID and accept it manually.
- Subsequent connections: Syncthing verifies the certificate matches the stored ID — any change triggers a rejection.
- No CA needed: There is no certificate authority. Trust is established by out-of-band sharing of the Device ID (e.g., QR code, email, chat).
# List all trusted/configured devices in config.xml
grep -A3 "<device " ~/.local/share/syncthing/config.xml | grep "id="
Practical Security Checklist
| Check | Command / Action |
|---|---|
| Confirm TLS 1.3 is active | Inspect logs: INFO: TLS 1.3 on connection events |
| Verify peer Device ID before sharing folders | Actions → Show ID in GUI, compare out-of-band |
| Ensure key.pem is not world-readable | chmod 600 ~/.local/share/syncthing/key.pem |
| Periodically audit trusted devices | GUI → Devices tab → remove stale entries |
| Block GUI on public interface | See GUI Hardening |
Common Mistakes
| Mistake | Effect | Fix |
|---|---|---|
Sharing key.pem instead of cert.pem | Attacker can impersonate your device | Only share Device ID (63-char string) |
| Accepting a peer with unverified Device ID | MITM possible during first connection | Verify ID via a secondary channel (phone, QR) |
| Forgetting to re-pair after cert rotation | Peers reject new Device ID | Re-share new ID and re-accept on all peers |