1SYNCTHING-DEVICE-IDS(7) Syncthing SYNCTHING-DEVICE-IDS(7)
2
6 syncthing-device-ids - Understanding Device IDs
7 Every device is identified by a device ID. The device ID is used for
9 address resolution, authentication and authorization. The term “device
10 ID” could interchangeably have been “key ID” since the device ID is a
11 direct property of the public key in use.
12
14 To understand device IDs we need to look at the underlying mechanisms.
15 At first startup, Syncthing will create a public/private keypair.
16 Currently this is a 384 bit ECDSA key (3072 bit RSA prior to v0.12.5,
18 which is what is used as an example in this article). The keys are
19 saved in the form of the private key (key.pem) and a self signed cer‐
20 tificate (cert.pem). The self signing part doesn’t actually add any se‐
21 curity or functionality as far as Syncthing is concerned but it enables
22 the use of the keys in a standard TLS exchange.
23 The typical certificate will look something like this, inspected with
25 openssl x509:
26 Certificate:
28 Data:
29 Version: 3 (0x2)
30 Serial Number: 0 (0x0)
31 Signature Algorithm: sha1WithRSAEncryption
32 Issuer: CN=syncthing
33 Validity
34 Not Before: Mar 30 21:10:52 2014 GMT
35 Not After : Dec 31 23:59:59 2049 GMT
36 Subject: CN=syncthing
37 Subject Public Key Info:
38 Public Key Algorithm: rsaEncryption
39 RSA Public Key: (3072 bit)
40 Modulus (3072 bit):
41 00:da:83:8a:c0:95:af:0a:42:af:43:74:65:29:f2:
42 30:e3:b9:12:d2:6b:70:93:da:0b:7b:8a:1e:e5:79:
43 ...
44 99:09:4c:a9:7b:ba:4a:6a:8b:3b:e6:e7:c7:2c:00:
45 90:aa:bc:ad:94:e7:80:95:d2:1b
46 Exponent: 65537 (0x10001)
47 X509v3 extensions:
48 X509v3 Key Usage: critical
49 Digital Signature, Key Encipherment
50 X509v3 Extended Key Usage:
51 TLS Web Server Authentication, TLS Web Client Authentication
52 X509v3 Basic Constraints: critical
53 CA:FALSE
54 Signature Algorithm: sha1WithRSAEncryption
55 68:72:43:8b:83:61:09:68:f0:ef:f0:43:b7:30:a6:73:1e:a8:
56 d9:24:6c:2d:b4:bc:c9:e8:3e:0b:1e:3c:cc:7a:b2:c8:f1:1d:
57 ...
58 88:7e:e2:61:aa:4c:02:e3:64:b0:da:70:3a:cd:1c:3d:86:db:
59 df:54:b9:4e:be:1b
60 We can see here that the certificate is little more than a container
62 for the public key; the serial number is zero and the Issuer and Sub‐
63 ject are both “syncthing” where a qualified name might otherwise be ex‐
64 pected.
65 An advanced user could replace the key.pem and cert.pem files with a
67 keypair generated directly by the openssl utility or other mechanism.
68
70 To form a device ID the SHA-256 hash of the certificate data in DER
71 form is calculated. This means the hash covers all information under
72 the Certificate: section above.
73 The hashing results in a 256 bit hash which we encode using base32.
75 Base32 encodes five bits per character so we need 256 / 5 = 51.2 char‐
76 acters to encode the device ID. This becomes 52 characters in practice,
77 but 52 characters of base32 would decode to 260 bits which is not a
78 whole number of bytes. The base32 encoding adds padding to 280 bits
79 (the next multiple of both 5 and 8 bits) so the resulting ID looks
80 something like:
81 MFZWI3DBONSGYYLTMRWGC43ENRQXGZDMMFZWI3DBONSGYYLTMRWA====
83 The padding (====) is stripped away, the device ID split into four
85 groups, and check digits <https://forum.syncthing.net/t/v0-9-0-new-
86 node-id-format/478> are added for each group. For presentation purposes
87 the device ID is grouped with dashes, resulting in the final value:
88 MFZWI3D-BONSGYC-YLTMRWG-C43ENR5-QXGZDMM-FZWI3DP-BONSGYY-LTMRWAD
90 Connection Establishment
92 Now we know what device IDs are, here’s how they are used in Syncthing.
93 When you add a device ID to the configuration, Syncthing will attempt
94 to connect to that device. The first thing we need to do is figure out
95 the IP and port to connect to. There are three possibilities here:
96 • The IP and port can be set statically in the configuration. The IP
98 can equally well be a host name, so if you have a static IP or a dy‐
99 namic DNS setup this might be a good option.
100 • Using local discovery, if enabled. Every Syncthing instance on a LAN
102 periodically broadcasts information about itself (device ID, address,
103 port number). If we’ve seen one of these broadcasts for a given de‐
104 vice ID that’s where we try to connect.
105 • Using global discovery, if enabled. Every Syncthing instance an‐
107 nounces itself to the global discovery service (device ID and exter‐
108 nal port number - the internal address is not announced to the global
109 server). If we don’t have a static address and haven’t seen any local
110 announcements the global discovery server will be queried for an ad‐
111 dress.
112 Once we have an address and port a TCP connection is established and a
114 TLS handshake performed. As part of the handshake both devices present
115 their certificates. Once the handshake has completed and the peer cer‐
116 tificate is known, the following steps are performed:
117 1. Calculate the remote device ID by processing the received certifi‐
119 cate as above.
120 2. Weed out a few possible misconfigurations - i.e. if the device ID is
122 that of the local device or of a device we already have an active
123 connection to. Drop the connection in these cases.
124 3. Verify the remote device ID against the configuration. If it is not
126 a device ID we are expecting to talk to, drop the connection.
127 4. Verify the certificate CommonName against the configuration. By de‐
129 fault, we expect it to be syncthing, but when using custom certifi‐
130 cates this can be changed.
131 5. If everything checks out so far, accept the connection.
133
135 The SHA-256 hash is cryptographically collision resistant. This means
136 that there is no way that we know of to create two different messages
137 with the same hash.
138 You can argue that of course there are collisions - there’s an infinite
140 amount of inputs and a finite amount of outputs - so by definition
141 there are infinitely many messages that result in the same hash.
142 I’m going to quote stack overflow <https://stackoverflow.com/ques‐
144 tions/4014090/is-it-safe-to-ignore-the-possibility-of-sha-collisions-
145 in-practice> here:
146 The usual answer goes thus: what is the probability that a rogue as‐
147 teroid crashes on Earth within the next second, obliterating civi‐
148 lization-as-we- know-it, and killing off a few billion people ? It
149 can be argued that any unlucky event with a probability lower than
150 that is not actually very important.
151 If we have a “perfect” hash function with output size n, and we have
153 p messages to hash (individual message length is not important),
154 then probability of collision is about p2/2n+1 (this is an approxi‐
155 mation which is valid for “small” p, i.e. substantially smaller than
156 2n/2). For instance, with SHA-256 (n=256) and one billion messages
157 (p=10^9) then the probability is about 4.3*10^-60.
158 A mass-murderer space rock happens about once every 30 million years
160 on average. This leads to a probability of such an event occurring
161 in the next second to about 10^-15. That’s 45 orders of magnitude
162 more probable than the SHA-256 collision. Briefly stated, if you
163 find SHA-256 collisions scary then your priorities are wrong.
164 It’s also worth noting that the property of SHA-256 that we are using
166 is not simply collision resistance but resistance to a preimage attack,
167 i.e. even if you can find two messages that result in a hash collision
168 that doesn’t help you attack Syncthing (or TLS in general). You need to
169 create a message that hashes to exactly the hash that my certificate
170 already has or you won’t get in.
171 Note also that it’s not good enough to find a random blob of bits that
173 happen to have the same hash as my certificate. You need to create a
174 valid DER-encoded, signed certificate that has the same hash as mine.
175 The difficulty of this is staggeringly far beyond the already stagger‐
176 ing difficulty of finding a SHA-256 collision.
177
179 As far as I know, these are the issues or potential issues with the
180 above mechanism.
181 Discovery Spoofing
183 Currently, the local discovery mechanism isn’t protected by crypto.
184 This means that any device can in theory announce itself for any device
185 ID and potentially receive connections for that device from the local
186 network.
187 Long Device IDs are Painful
189 It’s a mouthful to read over the phone, annoying to type into an SMS or
190 even into a computer. And it needs to be done twice, once for each
191 side.
192 This isn’t a vulnerability as such, but a user experience problem.
194 There are various possible solutions:
195 • Use shorter device IDs with verification based on the full ID (“You
197 entered MFZWI3; I found and connected to a device with the ID
198 MFZWI3-DBONSG-YYLTMR-WGC43E-NRQXGZ-DMMFZW-I3DBON-SGYYLT-MRWA, please
199 confirm that this is correct”).
200 • Use shorter device IDs with an out of band authentication, a la Blue‐
202 tooth pairing. You enter a one time PIN into Syncthing and give that
203 PIN plus a short device ID to another user. On initial connect, both
204 sides verify that the other knows the correct PIN before accepting
205 the connection.
206
208 The Syncthing Authors
209
211 2014-2019, The Syncthing Authors
212v1.25.0 Oct 05, 2023 SYNCTHING-DEVICE-IDS(7)