protocol.md (18036B)
1 ### Persisting the account 2 3 Persisting a Ring account private key and certificate is implementation 4 defined. 5 6 Access to a saved Ring account private key must be authenticated and 7 authorized. Authentication and authorization method to access the 8 account private key is implementation defined. 9 10 ### Adding a device to a Ring account 11 12 *See [RFC 5280](https://tools.ietf.org/html/rfc5280)* 13 14 A **device** is defined by an RSA key pair with a key length of at least 15 4096 bits. 16 17 A **device certificate** is defined as an x509 certificate whose subject 18 is a device public key, signed with an account private key. The 19 certificate MUST be valid. The issuer UID field MUST be the hexadecimal 20 form of the account public key fingerprint. 21 22 Persisting a device private key and certificate is implementation 23 defined. Access to a saved device private key should be authenticated. 24 Authentication method to access the device private key is implementation 25 defined. 26 27 ### Removing a device from a Ring account 28 29 A device can be "removed" from a Ring account through revocation of the 30 device certificate. Revoked device certificates are added to one or more 31 standard x509 Certificate Revocation List (CRL). CRLs for revoked device 32 must be valid and signed with the corresponding CA key, which is the 33 Ring account private key. 34 35 ### Account transmission format 36 37 The **account archive format** defines how to serialize an account 38 private key for transmission, for instance to sign a new device 39 certificate. 40 41 The account archive is an encrypted JSON object with the following 42 structure: 43 44 ``` 45 { 46 "ringAccountKey": (PEM-encoded account private key string), 47 "ringAccountCert": (PEM-encoded account certificate string), 48 "ringAccountCRL": (PEM-encoded account CRL string) 49 } 50 ``` 51 52 The JSON object can contain additional implementation-defined key-value 53 pairs. Implementation-defined key names shouldn't start with "ring". 54 55 The string JSON object is encrypted using a key defined as : 56 57 ``` 58 salt = PIN + timestamp 59 key = argon2(password, salt) 60 ``` 61 62 Where PIN is a random 32bits number in hexadecimal form, "+" is string 63 concatenation, timestamp is the current UNIX timestamp divided by 1200 64 (20 minutes) and password is a user-chosen password. 65 66 The PIN should be shown to the user to be copied manually on the new 67 physical device along with the password. 68 69 Contacting another account 70 -------------------------- 71 72 ### ICE descriptor exchange over OpenDHT 73 74 - **Listening for incoming calls** 75 76 A device listens for incoming call by performing a listen OpenDHT 77 operation on 78 79 `h("callto"+deviceID)` 80 81 where h is SHA1, "+" is the string concatenation and deviceID is the 82 hexadecimal form of the deviceID. 83 84 Received OpenDHT values that are not encrypted or not properly signed 85 must be dropped. The value must be encrypted with the called device 86 public key and signed with the calling device private key according to 87 OpenDHT specifications. 88 89 - **Sending the Initial Offer** 90 91 *See [RFC 5245](https://tools.ietf.org/html/rfc5245)* 92 93 RFC 5245 defines ICE (Interactive Connectivity Establishment), a 94 protocol for NAT traversal. 95 96 ICE is used in Ring to establish a peer-to-peer communication between 97 two devices. 98 99 The calling device gathers candidates and build an Initial Offer 100 according to the ICE specifications and starts the ICE negotiation 101 process. 102 103 The calling device puts the encrypted ICE offer (the Initial Offer) on 104 the DHT at h("callto"+deviceID) where deviceID is the hexadecimal form 105 of the called deviceID. 106 107 - **ICE serialization format** 108 109 ICE messages exchanged between peers during a call setup use following 110 format. An ICE message is a chunk of binary data, following 111 [msgpack](http://msgpack.org/) data format. 112 113 This protocol is a compound of msgpack values, successively packed in 114 this order: 115 116 117 + an integer giving the version of ICE message format protocol used for the rest of the data. Current defined protocol version is **1**. 118 + a 2-elements array of strings of the ICE local session ufrag and the ICE local session password 119 + an integer giving the number of components in the ICE session 120 + an array of string, of the previous number entries, where each string describe the ICE candidate, formated as an "a=" line (without the "a=" header) described in [rfc5245, section 4.3](https://tools.ietf.org/html/rfc5245#page-26) 121 122 - **Sending the Answer** 123 124 Upon reception of the encrypted and signed Initial ICE Offer (through 125 the listen operation), a called device should perform authorization 126 checks of the calling device, identified as the Initial Offer signer. 127 Authorization rules are implementation defined, but a typical 128 implementation would authorize known or trusted contacts. 129 130 If the calling device is not authorized or if for any implementation 131 defined reason the called device refuses the incoming connection 132 request, the called device must ignore the Initial Offer and may log the 133 event. 134 135 If the called device authorizes the caller and wish to accept the 136 connection it must build an ICE answer, start the ICE negotiation 137 process and send the encrypted and signed ICE answer at the same DHT 138 key. 139 140 ### DTLS negotiation 141 142 Once a peer-to-peer communication channel has been established, the 143 called device listens on it for incoming DTLS connections (acting as a 144 DTLS server) while the caller initiates an outgoing DTLS connection 145 (acting as a DTLS client). 146 147 The DTLS communication must be RFC6347 compliant 148 ([1](https://tools.ietf.org/html/rfc6347)). 149 150 Peers must only support PFS cypher suites. The set of supported cypher 151 suites is implementation defined but should include at least 152 ECDHE-AES-GCM (TODO: specify the exact suites recommended to support). 153 154 During the DTLS handshake, both peers must provide their respective 155 device certificate chain and must authenticate the other peer, checking 156 that its public key is the same used during the DHT ICE exchange. 157 158 ### SIP call 159 160 Once an encrypted and authenticated peer-to-peer communication channel 161 is available, the SIP protocol [2](https://tools.ietf.org/html/rfc3261) 162 must be used to place a call and send messages. The caller might send a 163 SIP INVITE as soon as the DTLS channel is established. 164 165 The SIP implementation must support ICE and SRTP. 166 167 Supported codecs are implementation defined, but Ring clients should 168 support the Opus audio coded and the H264 video codec. 169 170 SRTP must be used when negotiating media with SIP, using a new random 171 key for each media and each negotiation. ICE should be used when 172 negotiating media with SIP. 173 174 Cryptographic primitives 175 ------------------------ 176 177 ### Password stretching 178 179 *See [Argon2 180 specifications](https://github.com/P-H-C/phc-winner-argon2/blob/master/argon2-specs.pdf)* 181 182 Passwords are stretched using argon2i using t\_cost = 16, m\_cost = 183 2\^16 (64 MiB), mono-threaded, to generate a 512 bits hash. 184 185 The result is then hashed again using SHA{1, 256, 512} depending on the 186 requested key size. 187 188 ### Encryption 189 190 ##### Using a provided key (128, 192 or 256 bits) 191 192 Encryption uses standard AES-GCM as implemented by Nettle using a random 193 IV for each encryption. 194 195 ##### Using a text password 196 197 The password is stretched to generate a 256 bits key and a random salt 198 of 128 bits. 199 200 The input data is encrypted using AES-GCM (see above) and the salt is 201 appended at the beginning of the resulting cypher-text. 202 203 ##### During a call 204 205 Audio/video data are exchanged using encrypted RTP channels between 206 peers. 207 208 The protocol is a classic SRTP, with following supported crypto suites: 209 210 - Ring account force AES\_CM\_128\_HMAC\_SHA1\_80 211 - SIP can use AES\_CM\_128\_HMAC\_SHA1\_80 or 212 AES\_CM\_128\_HMAC\_SHA1\_32 213 214 The master key and salt is a random number, different for each call. On 215 call's master key is constant during the full live of a call. 216 217 The keys are exchanged using SDES method: keys are written into the SIP 218 SDP messages during the SIP INVITE negotiation. When SDES is used, Ring 219 forces the underlaying transport to be secure (encrypted) to not 220 disclose these keys. Ring supports DTLS natively for SIP and Ring 221 accounts for such. The call cannot be done if this condition is not 222 fulfilled. 223 224 225 226 227 ### Outgoing and Incoming calls 228 229 - Contactable addresses (i.e. IP addresses) of the user are given to 230 peer only: 231 - When we call a peer (outgoing call). 232 - When a **trusted** peer is calling (incoming call). 233 - All combination forms of how a specific device can be contacted is 234 summarized by a ICE message: 235 - *[RFC 5245](https://tools.ietf.org/html/rfc5245)* defines ICE 236 (Interactive Connectivity Establishment), a protocol for 237 NAT traversal. 238 - ICE is used in Jami to establish a peer-to-peer communication 239 between two devices. 240 241 #### Making an outgoing call 242 243 1. The calling device gathers candidates and build an **Initial Offer** 244 according to the ICE specifications. 245 2. The calling device puts the encrypted ICE offer (the *Initial 246 Offer*) on the DHT at: 247 `h("`[`callto:"+DeviceID`](callto:%22+DeviceID)`)` where *h* is 248 SHA1, *+* is the string concatenation, *DeviceID* is in 249 hexadecimal form. 250 3. The calling device waits on the peer answer, with its own ICE 251 candidates lists. 252 4. At peer answer reception, the calling device starts the 253 ICE negotiation. 254 5. If the negotiation succeed, the process continues on a client-side 255 DTLS session establishment over the created ICE socket (see below). 256 257 #### Listening for incoming calls 258 259 1. A device listens for incoming calls by performing a listen OpenDHT 260 operation on `h("`[`callto:"+DeviceID`](callto:%22+DeviceID)`)` 261 where *h* is SHA1, *+* is the string concatenation and *DeviceID* is 262 in hexadecimal form. 263 2. At ICE *Initial Offer* reception, the called device **must** do a 264 security validation of the peer (see below). 265 3. If the security validation succeed, the called device starts the 266 ICE negotiation. 267 4. If the negotiation succeed, the process continues on a server-side 268 DTLS session establishment over the created ICE socket (see below). 269 270 - *Note: OpenDHT drops values that are not properly encrypted or 271 signed, as specified by OpenDHT protocol.* 272 273 #### ICE serialization format 274 275 - ICE messages exchanged between peers during a call set up use 276 following format. 277 - An ICE message is a chunk of binary data, following 278 [msgpack](http://msgpack.org/) data format. 279 280 ``` 281 <8-bits unsigned integer> giving the version of ICE message format protocol used for the rest of the data, 282 <C++ std::pair of string> of the ICE local session ufrag and the ICE local session password, 283 <8-bits unsigned integer> giving the number of components in the ICE session, 284 <array of string> of the previous number entries, where each string describe the ICE candidate, formated as an "a=" line (without the "a=" header) described in [rfc5245, section 4.3](https://tools.ietf.org/html/rfc5245#page-26) 285 ``` 286 287 - **Current defined protocol is 1**: 288 289 #### Security Validation of the Peer 290 291 - Upon reception of the encrypted and signed Initial ICE Offer 292 (through the listen operation), a called device should perform 293 authorization checks of the calling device, identified as the 294 Initial Offer signer. 295 - Authorization rules are implementation defined, but a typical 296 implementation would authorize known or trusted contacts. 297 - If the calling device is not authorized or if for any implementation 298 defined reason the called device refuses the incoming connection 299 request, the called device must ignore the Initial Offer and may log 300 the event. 301 - If the called device authorizes the caller and wish to accept the 302 connection it must build an ICE answer, start the ICE negotiation 303 process and send the encrypted and signed ICE answer at the same 304 DHT key. 305 306 #### DTLS negotiation 307 308 - Once a peer-to-peer communication channel has been established by 309 ICE protocol, the called device starts a server-side DTLS session on 310 the ICE socket, while the caller starts a client-side DTLS session 311 on the other side of the ICE socket. 312 - The DTLS communication is 313 [RFC6347](https://tools.ietf.org/html/rfc6347) compliant using 314 gnutls library. 315 - To prevent peer certificates to be displayed in plain-text for the 316 call anonymity, the session handshake is done twice: 317 318 1. A first handshake in **anonymous mode** to create a secure but 319 anonymous transport. 320 2. A second handshake in **certificate mode**, over the first one, to 321 prove the identity of peers. 322 323 - Only PFS cipher suites are supported: 324 - The set of supported cipher suites is implementation defined but 325 should include at least ECDHE-AES-GCM. 326 - The actual cipher suites (in gnutls form) is: 327 - anonymous step: 328 `SECURE192:-KX-ALL:+ANON-ECDH:+ANON-DH:+SECURE192:-VERS-TLS-ALL:+VERS-DTLS-ALL:-RSA:%SERVER_PRECEDENCE:%SAFE_RENEGOTIATION` 329 - certificate step: 330 `SECURE192:-VERS-TLS-ALL:+VERS-DTLS-ALL:-RSA:%SERVER_PRECEDENCE:%SAFE_RENEGOTIATION` 331 332 #### SIP signaling 333 334 - Used over the DTLS session to signaling the call (vcard, media 335 negotiation, hangup, instant messaging, ...) 336 - Once an encrypted and authenticated peer-to-peer communication 337 channel is available, the [SIP 338 protocol](https://tools.ietf.org/html/rfc3261) must be used to place 339 a call and send messages. 340 - The caller might send a SIP INVITE as soon as the DTLS channel 341 is established. 342 - The SIP implementation must support ICE and SRTP. 343 - Supported codecs are implementation defined, but Jami clients should 344 support the Opus audio coded and the H264 video codec. 345 - SRTP must be used when negotiating media with SIP, using a new 346 random key for each media and each negotiation. ICE should be used 347 when negotiating media with SIP. 348 349 350 ## extra 351 352 353 To add a new contact, you send them a trust request over the DHT 354 consisting of <check this> the account certificate. If they accept the 355 request, they will send you their account certificate 356 357 358 who do not know each other's IP address. 359 360 361 362 So 363 364 365 366 367 ## Usages 368 369 - The JamiId: 370 - It's the DHT key where the list of account devices are published 371 and where all devices listen to synchronize on account 372 changes (i.e. adding or revoke a device). 373 - The Jami certificate RSA keys are used as long-term keys to 374 sign/encrypt/decrypt messages sent over the DHT: 375 - private key to sign-off and decrypt incoming messages and 376 device certificates. 377 - public key to encrypt messages (this is done by the message 378 issuer using the receiver public key). 379 - A device can be "removed" from a Jami account through revocation of 380 the device certificate: 381 - Revoked device certificates are added to one or more standard 382 x509 Certificate Revocation List (CRL). 383 - CRLs for revoked device must be valid and signed with the 384 corresponding CA key, which is the Jami account private key. 385 386 ### Long-term Storage 387 388 - Why storing data? 389 390 <!-- --> 391 392 - - Jami needs to load certificates and key-pairs each time the 393 application is started. 394 - When Jami creates a new device, these information are also 395 needed, shared from another trusted device in a secure way. 396 - All platforms doesn't provide secure way to store data, Jami 397 supports this fact by encrypting data stored outside the 398 memory (i.e. on a file-system) using a user defined password 399 during the account creation. 400 401 <!-- --> 402 403 - These files are stored on user device (see below for details): 404 - a compressed and encrypted archive with private account data. 405 - the public certificates chain as a CRT file 406 - the device private key. 407 408 #### Jami archive (export.gz) 409 410 - Contains private account data. 411 - Currently transmitted over the DHT network when device is created 412 or revoked. 413 - It's a JSON compressed and encrypted file. 414 415 <!-- --> 416 417 - The current format is (could change at any time): 418 419 ``` 420 { 421 ringCaKey: <base64 serialized PEM-encoded CA private key>, 422 ringAccountKey: <base64 serialized PEM-encoded Jami private key> 423 ringAccountCert: <base64 serialized PEM-encoded Jami certificate (public key)>, 424 ethKey: <base64 serialized of the optional 160-bits Etherium key used to register the JamiId on a public blockchain>, 425 ringAccountCRL: <base64 serialized of packet list of revoked device certificates PEM-encoded>, 426 ringAccountContacts: <JSON dictionary to export trusted user contacts> 427 } 428 ``` 429 430 - The JSON byte-stream is compressed using \*gzip\* algorithm. 431 432 <!-- --> 433 434 - Then the gzip-stream is encrypted using AES-GCM-256 symmetric cipher 435 with a 256-bits key. 436 - This key is derived from the user provided password, a PIN and a 437 timestamp, using 438 [Argon2](https://github.com/P-H-C/phc-winner-argon2) (a password 439 stretching and normalizer) as follow: 440 441 ``` 442 salt = PIN + timestamp 443 key = argon2(password, salt) 444 argon2 is the argon2i algorithm using t_cost = 16, m_cost = 2^16 (64 MiB), mono-threaded, to generate a 512-bits key and then hashed with SHA-256 to generate a 256-bits key. 445 PIN is a random 32bits number in hexadecimal form. 446 + is string concatenation operator. 447 timestamp is the current UNIX timestamp divided by 1200 (20 minutes). 448 password is a user-chosen password (given at account creation). 449 ``` 450 451 - The PIN should be shown to the user to be copied manually on the new 452 physical device along with the password to finish the device 453 creation process. 454 - NOTE: when exporting a file on the DHT or anywhere else, the daemon update the archive first, to write latest contacts. This is the reason why the password is needed when exporting (it's not just a copy of the archive somewhere else) 455 456 #### Jami device certificate chain (ring\_device.crt) 457 458 - PEM format 459 - Includes the Device certificate and parent certificates (Jami device 460 certificate and parents) 461 462 #### Device private key (ring\_device.key) 463 464 - PEM format 465 - not encrypted, we let the device file-system protect this file 466 467 #### Exporting data (creating new devices) 468 469 *TBD* 470 471 472 ### Contact Request 473 474 *TBD* 475 476 ### Instant Message 477 478 *TBD* 479 480 ### Presence 481 482 *TBD* 483 484 485 ### Security / Privacy 486 487 Jami provides perfect forward secrecy for calls and in call text 488 messages with different Eliptic Curve Diffie-Hellman key negociation at 489 every call. For out of call messaging single RSA-4096 is used. The 490 cryptography library used is GNUTLS