1SYNCTHING-DEVICE-IDS(7)            Syncthing           SYNCTHING-DEVICE-IDS(7)
2
3
4

NAME

6       syncthing-device-ids - Understanding Device IDs
7
8       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

KEYS

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
17       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
24       The typical certificate will look something like this,  inspected  with
25       openssl x509:
26
27          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
61       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
66       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

DEVICE IDS

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
74       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
82          MFZWI3DBONSGYYLTMRWGC43ENRQXGZDMMFZWI3DBONSGYYLTMRWA====
83
84       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
89          MFZWI3D-BONSGYC-YLTMRWG-C43ENR5-QXGZDMM-FZWI3DP-BONSGYY-LTMRWAD
90
91   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
97       • 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
101       • 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
106       • 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
113       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
118       1. Calculate the remote device ID by processing the  received  certifi‐
119          cate as above.
120
121       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
125       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
128       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
132       5. If everything checks out so far, accept the connection.
133

AN ASIDE ABOUT COLLISIONS

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
139       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
143       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
152          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
159          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
165       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
172       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

PROBLEMS AND VULNERABILITIES

179       As far as I know, these are the issues or  potential  issues  with  the
180       above mechanism.
181
182   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
188   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
193       This isn’t a vulnerability as such,  but  a  user  experience  problem.
194       There are various possible solutions:
195
196       • 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
201       • 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

AUTHOR

208       The Syncthing Authors
209
211       2014-2019, The Syncthing Authors
212
213
214
215
216v1.25.0                          Oct 05, 2023          SYNCTHING-DEVICE-IDS(7)
Impressum