The Identity Layer: Which Devices Are Allowed to Speak?
For Syncthing, a device name is not an identity and a reachable network address is not permission. This chapter focuses on the identity layer: how a generated key pair becomes a device ID, how that ID is used to authorize a peer during a TLS connection, and why the result protects a cluster from uninvited devices without making the ID itself a secret. The practical judgment is simple but important: a public identifier can tell Syncthing whom to expect, while the private key and configuration determine who can impersonate that device.
From a key pair to a device ID
When Syncthing starts for the first time, the core generates a private key and a self-signed X.509 certificate. The certificate is a standard container that lets the key participate in TLS, but Syncthing does not rely on a public certificate authority to decide whether a particular peer belongs in a user's cluster. Instead, it derives the device's identity from the certificate itself.
The device ID is the SHA-256 hash of the certificate in its DER representation. In the current implementation, that produces a 32-byte value. Syncthing encodes the value in base32, adds presentation-oriented check digits, and inserts separators so that a long identifier is easier to read or compare. The displayed string is only the human-facing form of the underlying fingerprint. The important property is that the ID is tied to the certificate: change the certificate, and the derived identity changes as well.
This explains why a device ID is closer to a public-key identifier than to a password. If a user wants a laptop and a server to synchronize, they exchange IDs and add each other's IDs to their configurations. A peer cannot become authorized merely by learning the string, because both sides must have the other device configured before a normal connection is accepted. The ID tells Syncthing which certificate fingerprint to expect; it does not give an attacker the private key needed to present that certificate as the device.
The distinction is operationally significant. The ID can appear in a setup guide, a log, or a conversation about pairing devices. The private key and certificate files belong to a different category. Someone who obtains the device's TLS keys and configuration can impersonate it, connect to its peers, and gain access to the files those peers make available. Losing a device is therefore not only a hardware problem. Its identity should be revoked from the remaining devices, because the cluster's allowlist is part of the access control system.
There is also a version-sensitive detail worth keeping straight. Older documentation contains historical certificate examples and describes previous key algorithms. The current core code generates Ed25519 certificates for synchronization; it uses a separate ECDSA path for browser-compatible certificates. The stable concept is the certificate fingerprint, not the algorithm in an old example. Present-tense explanations should follow the current implementation while treating historical examples as historical.
The certificate is also what gives the identity continuity across ordinary operation. A device can change its address, move from a local connection to a wide-area connection, or reconnect after a restart without becoming a different configured peer, provided it continues to use the same certificate. The address is a route; the certificate fingerprint is the identity that the other device remembers. This is why a device name is insufficient. A user can rename a machine without changing the cryptographic object, while two machines can have similar names and still be entirely different peers.
The reverse case is just as important. If the certificate and private key are replaced, the new certificate hashes to a different device ID. Peers that still hold the old ID should not silently accept the replacement as the same device; the mismatch is a useful signal that re-pairing or another explicit configuration decision is needed. That behavior makes identity rotation visible instead of allowing a change in credentials to masquerade as a harmless network change. The check digits and separators make manual comparison less error-prone, but they do not turn the displayed ID into a secret or replace the certificate comparison performed by the software.
A device ID also does not answer every trust question. It establishes which cryptographic device is present, not whether every folder on that device should be readable or writable. Syncthing can use the same authenticated device relationship with different folder policies, including modes for a peer that may store encrypted data but must not see the plaintext. Identity is the first gate, not a universal statement that the endpoint is harmless.
The handshake is a chain of decisions
Once Syncthing has a candidate address, the two devices establish a TLS connection. The current core configures the sync transport for TLS 1.3, supplies its device certificate, requests the peer's certificate, and negotiates the Block Exchange Protocol. The encrypted channel protects the traffic in transit, but encryption alone is not enough. Syncthing must also connect the certificate it received to the device ID that the user intended to reach.
The connection service performs that link explicitly. It reads the peer certificate from the completed TLS state and hashes the certificate to derive the remote device ID. It rejects a connection if the remote identity is the local device's own identity, if it does not match the expected configured peer, or if other connection policy rejects it. After the early checks, the devices exchange a Hello message containing implementation and device information. The model can still reject an unknown device at this stage; exchanging enough information to identify an unconfigured peer does not grant that peer access.
It helps to distinguish authentication from authorization here. Authentication is the question “which certificate did the other side present?” The certificate fingerprint answers it. Authorization is the question “is that fingerprint one this device has been configured to use for this relationship?” The configuration answers it. A valid certificate from an otherwise legitimate Syncthing installation can still be unauthorized on this particular device. Conversely, a configured ID is not enough if the incoming certificate does not actually hash to that ID.
The mutual setup requirement adds a second, human-visible confirmation. When two users—or one user operating two machines—add each other's IDs and select a folder, they create an explicit relationship on both endpoints. A device that discovers or contacts only one side cannot turn that one-sided contact into access to the folder. The system may record information about an unknown device so the user can recognize a pending pairing, but the connection is not promoted into a usable synchronization relationship simply because the Hello message was well formed.
The certificate-name check is another distinct input. Syncthing's default generated certificate uses the expected project name, while advanced configurations can use a configured certificate name. The name check helps detect a certificate that does not fit the expected certificate identity conventions, but it is not the main device authorization mechanism. The fingerprint still binds the certificate to the configured device ID. Keeping these checks conceptually separate prevents a reader from treating a human-readable name as if it had the uniqueness and authorization role of the fingerprint.
The diagram is symmetrical even though the network sockets may not be. An outgoing connection begins with one device dialing, while an incoming connection begins with the other accepting. Once TLS has produced the peer certificate, each side can perform the same kind of identity comparison. This matters in home networks and NAT-heavy environments, where either device may be the one that manages to open the usable socket. Security should not depend on which side happened to dial first.
The result is a layered decision rather than one “secure connection” switch. TLS supplies a protected channel and presents certificates. The certificate hash supplies the device identity. The configured peer list supplies authorization. The Hello exchange supplies useful context, while the model and folder configuration determine whether the peer is actually allowed to participate in a particular synchronization relationship.
One implementation choice can look alarming if this chain is not understood. The core sync TLS configuration sets ordinary certificate verification to skip hostname-style checks. That is intentional in the Syncthing design: its primary identity binding is the pinned certificate fingerprint and device ID, not the question “does this certificate name match a public DNS name signed by a public CA?” The connection service still performs explicit certificate and device-ID checks, including a certificate-name check against the configured or default name. Skipping one kind of verifier is not the same as skipping authentication; it means the application owns the identity decision because the application has a different trust model.
This model is useful for devices that do not have public DNS names or public CA certificates. A laptop behind a home router does not need to prove ownership of a globally registered hostname. It needs to prove possession of the certificate whose fingerprint the other device was configured to accept. The same rule works when the connection is incoming or outgoing, local or wide-area, direct or later carried through a relay. The network path can change without changing the identity relationship.
That does not make the system invulnerable. If an attacker steals the private key, they can present the expected identity. If the operating system or an authorized endpoint is compromised, transport authentication does not protect the files from code already running inside the trust boundary. An authorized user can also make destructive changes that are perfectly valid from the network's point of view. The identity layer is designed to stop an uninvited device from joining, not to decide whether an invited device or its operator will make wise changes.
Imagine that the laptop in the example is lost. The server may still know the laptop's device ID, but that knowledge is not the dangerous part. The urgent action is to remove that ID from the server's accepted devices and from other peers, because anyone who later obtains the laptop's identity material could otherwise present a certificate that matches the allowlist. This is the same logic used when access to any credential is revoked: the system cannot infer that a familiar identity is still under the owner's control simply because its fingerprint is familiar.
The opposite situation is also instructive. A user may restore a configuration and its key material onto replacement hardware. From the cluster's perspective, that can preserve the device identity, which may be exactly what is wanted when the original machine failed but its credentials remained protected. If the user instead allows the replacement to generate a new certificate, the new device should be paired as a new identity. Syncthing's design makes that choice visible. It does not silently turn a new key into the old device merely because the hostname or folder path looks the same.
The same boundary explains why a known device ID should not be confused with secrecy. Hiding the ID would not solve the central authorization problem; the peer must be able to compare it with the certificate it receives. Protecting the private material does solve a real problem, because possession of the private key changes who can speak as that device. Good operational security therefore treats IDs as pairing information and keys/configuration as credentials.
The identity layer answers “which cryptographic peer is this?” It does not answer “where is that peer right now?” A device can be correctly configured and fully authorized yet have a changing address, sit behind a NAT, or be reachable only through a relay. Syncthing handles that next problem with discovery and fallback transports, but every candidate route must eventually return to the identity checks described here.