idnits 2.17.1 draft-hallambaker-json-key-exchange-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 468 has weird spacing: '...egistry jose-...' -- The document date (April 11, 2018) is 2207 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 511 -- Looks like a reference, but probably isn't: '2' on line 514 == Missing Reference: 'RFC2119' is mentioned on line 141, but not defined Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group P. Hallam-Baker 3 Internet-Draft Comodo Group Inc. 4 Intended status: Informational April 11, 2018 5 Expires: October 13, 2018 7 JSON Key Exchange 8 draft-hallambaker-json-key-exchange-03 10 Abstract 12 The JSON Key Exchange 14 This document is also available online at 15 http://mathmesh.com/Documents/draft-hallambaker-json-key- 16 exchange.html [1] . 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on October 13, 2018. 35 Copyright Notice 37 Copyright (c) 2018 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (https://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 55 2.2. Defined Terms . . . . . . . . . . . . . . . . . . . . . . 4 56 2.3. Related Specifications . . . . . . . . . . . . . . . . . 4 57 2.4. Implementation Status . . . . . . . . . . . . . . . . . . 4 58 3. Key Exchange Protocol . . . . . . . . . . . . . . . . . . . . 4 59 3.1. Parameters . . . . . . . . . . . . . . . . . . . . . . . 4 60 3.2. Notation . . . . . . . . . . . . . . . . . . . . . . . . 4 61 3.3. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 5 62 3.4. Keys . . . . . . . . . . . . . . . . . . . . . . . . . . 5 63 3.5. Derived Keys . . . . . . . . . . . . . . . . . . . . . . 5 64 3.6. Initial Keying Request . . . . . . . . . . . . . . . . . 6 65 3.6.1. Initial Request Message . . . . . . . . . . . . . . . 6 66 3.6.2. Initial Response Message . . . . . . . . . . . . . . 6 67 3.7. Rekeying. . . . . . . . . . . . . . . . . . . . . . . . . 6 68 3.7.1. Rekeying Request Message . . . . . . . . . . . . . . 7 69 3.7.2. Rekeying Response Message . . . . . . . . . . . . . . 7 70 3.8. Initial Key Exchange Example . . . . . . . . . . . . . . 7 71 3.9. Rekey Example . . . . . . . . . . . . . . . . . . . . . . 10 72 4. Key Exchange Service . . . . . . . . . . . . . . . . . . . . 10 73 4.1. Shared classes . . . . . . . . . . . . . . . . . . . . . 10 74 4.1.1. Structure: Algorithms . . . . . . . . . . . . . . . . 10 75 4.2. Utility Transactions . . . . . . . . . . . . . . . . . . 10 76 4.3. Transaction: Exchange . . . . . . . . . . . . . . . . . . 10 77 4.3.1. Message: ExchangeRequest . . . . . . . . . . . . . . 10 78 4.3.2. Message: ExchangeResponse . . . . . . . . . . . . . . 11 79 5. Security Considerations . . . . . . . . . . . . . . . . . . . 11 80 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 81 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 82 7.1. Normative References . . . . . . . . . . . . . . . . . . 11 83 7.2. Informative References . . . . . . . . . . . . . . . . . 12 84 7.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 12 85 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 87 1. Introduction 89 This document describes a lightweight key agreement mechanism using 90 between 2 and four Diffe-Hellman or Elliptic Curve Diffie-Hallman 91 keys. The mechanism may be used establish a shared session key with 92 authentication of any or none of the initiator and the responder. 94 The approach described is similar to that adopted in the X3DH Key 95 agreement [X3DH] used in Signal. 97 The objective of the key exchange is limited to establishing a shared 98 secret between two mutually authenticated parties that cannot be 99 derived by any other parties and cannot be reconstructed by either of 100 the parties after the ephemeral contributions have been deleted. 102 The key exchange is intended for use as one component in a multi- 103 layer security approach in which comprehensive security is provided 104 through use of encryption and authentication at multiple layers in 105 the protocol stack. 107 [[This figure is not viewable in this format. The figure is 108 available at http://mathmesh.com/Documents/draft-hallambaker-json- 109 key-exchange.html [2].]] 111 Multi-layer security 113 Specifically, this key exchange is intended for use at the 114 presentation layer (e.g. authenticate and encrypt HTTP message 115 bodies) to establish keys for authentication and optional encryption 116 of messages in Web Service transactions. 118 Data Layer Encryption of cryptographic keys, protocol configuration 119 profiles. 121 Presentation Layer Authentication of parties to a Web Service 122 transaction. 124 Transport Layer Protect metadata against interception at single 125 point on the message path (link or node) 127 Link Layer Protect messages against traffic analysis by means of 128 interception at multiple points on the message path 130 2. Definitions 132 This section presents the related specifications and standard, the 133 terms that are used as terms of art within the documents and the 134 terms used as requirements language. 136 2.1. Requirements Language 138 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 139 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 140 document are to be interpreted as described in [RFC2119]. 142 2.2. Defined Terms 144 No terms of art are defined. 146 2.3. Related Specifications 148 JSON Key Exchange is used extensively in the Mathematical Mesh and 149 related protocols [draft-hallambaker-mesh-architecture] . 151 2.4. Implementation Status 153 The implementation status of the reference code base is described in 154 the companion document [draft-hallambaker-mesh-developer] . 156 3. Key Exchange Protocol 158 3.1. Parameters 160 The following parameters are defined 162 Algorithm The key exchange protocol. Diffie Hellman in discrete 163 log, EdECDH25519 or EdECDH448.[RFC8032] 165 Key Derivation Function The key derivation function. This is always 166 HKDF [RFC5869] 168 Key Wrap Function The Key Wrap function. This is always RFC3394 169 [RFC3394] 171 It should be noted that the algorithm described makes use of the 172 Edwards form of the curve and not the Montgomery form described in 173 [RFC7748] . While these curves are isomorphic, implementations of the 174 Montgomery ladder do not lend themselves easily to the approach 175 shown. 177 3.2. Notation 179 The notation adopted in [X3DH] is applied with minor modifications. 181 X ||Y The concatenation of the byte sequence X followed by the byte 182 sequence Y. 184 KE (PK1, PK2) The result of performing the key exchange (Diffie- 185 Hellman or Elliptic Curve Diffie Hellman) with the public 186 parameters of PK1 and the private parameters of PK2. 188 PK1+PK2 The public, private key pair formed by combining the public, 189 private parameters of PK1 and PK2. 191 Expand (PRK, info, L) The KDF expansion function that derives a key 192 of length L bits from the Pre Random Key PRK using the string info 193 as the salt. 195 Extract (IKM, salt) The KDF extraction function that derives a Pre- 196 Random Key from the Initial Keying Material IKM and the salt value 197 salt. If the salt value is specified as 0, the default salt of a 198 string of zero bits the same length as the Pre-Random Key to be 199 extracted is used. 201 3.3. Roles 203 Client The party that initiates the key exchange 205 Service The party that responds to the key exchange 207 3.4. Keys 209 IKC The identification key of the client. The encoding of this key 210 MAY include one or more credentials such as a Mesh personal 211 profile or an X.509 certificate binding the key to an identity. 213 IKS  The identification key of the service. The encoding of 214 this key MAY include one or more credentials such as a Mesh 215 personal profile or an X.509 certificate binding the key to an 216 identity. 218 EKC  The ephemeral key of the client. 220 EKS  The ephemeral key of the service. 222 3.5. Derived Keys 224 The key derivation function is used to derive separate keys for 225 different purposes as shown below. The value L is the number of bits 226 requires to key the algorithm specified. The salt value used to 227 derive the PRK from the IKM is either the default salt value (all 228 zeros) or the previous Rekey value as described below. 230 AK (PRK) Authentication Key = Expand (PRK, "authentication", L) 232 EK (PRK) Encryption Key = Expand (PRK, "encryption", L) 234 RA (PRK) Rekey Key = Expand (PRK, "rekey", L) 236 W (PRK) Witness value= Expand (PRK, "witness", L) 238 3.6. Initial Keying Request 240 A key exchange request is either an initial key exchange request or a 241 rekeying request. An initial key exchange request MAY be issued at 242 any time but a rekeying request cannot be sent until at least one 243 initial keying request has been completed. 245 Rekey messages are authenticated under a Rekey shared secret 246 established in a previous session. This may be the immediately 247 preceding session or any prior session whose rekey token has not 248 expired. 250 3.6.1. Initial Request Message 252 The client sends their identity and ephemeral key to the service. { 253 IKC, EKC } 255 If the request message is an initial keying request, a credential 256 associated with the identity key MAY be provided. The request MAY be 257 authenticated by means of a digital signature. 259 3.6.2. Initial Response Message 261 The service calculates the IKM value as follows: 263 IKM = KE (IKC + EKC, IKS + EKS) 265 PRK = Extract (IKM, 0) 267 The service returns the values { IKS, EKS, W(IKM) } in a message 268 authenticated under AK(IKM) 270 3.7. Rekeying. 272 Unless the key agreement is performed to a device of restricted 273 capability, rekeying imposes minimal load on client or server and can 274 be performed often, particularly if the Ed25519 curve is used for 275 rekeying. 277 The state required for rekeying is separate from the keys used to 278 encrypt and/or authenticate messages. This allows an application to 279 store the rekeying key between communication sessions without risk of 280 compromising the confidentiality or integrity of messages. 282 The use of the chaining salt ensures that rekeying cannot compromise 283 the security of an already established key, even if a weaker key 284 exchange algorithm is used. Thus a client MAY use an Ed488 key to 285 perform an initial key exchange and then preform rekey operations 286 using a 288 3.7.1. Rekeying Request Message 290 The client sends a new ephemeral key to the service. { CEK } 292 The request message MUST be authenticated under the rekeying key of 293 the shared secret of any unexpired session previously agreed. This 294 allows the credentials of the parties to be omitted while providing 295 the advantage of establishing a fresh forward secrecy session. 297 3.7.2. Rekeying Response Message 299 The service calculates the IKM value as follows: 301 IKM = KE (EKC, EKS) 303 The service returns the values { EKS, W(IKM) } in a message 304 authenticated under AK(IKM) 306 PRK = Extract (IKM, RA') 308 Where RA' is the previous rekeying key output. 310 3.8. Initial Key Exchange Example 312 Alice requests access to a service using her account identifier 313 alice@example.com. She has already registered her Mesh personal 314 profile with the service where it is bound to her account identifier 315 as the corresponding credential. 317 The Key exchange request is: 319 POST /.well-known/jwcexchange/HTTP/1.1 320 Host: example.com 321 Content-Length: 1068 323 { 324 "ExchangeRequest": { 325 "ClientCredential": { 326 "PublicKeyDH": { 327 "kid": "MB5OU-335BC-AUKOZ-E62ZE-4ME2J-IYUVJ", 328 "Domain": " 329 YE6bnq1MlX5ojaJto6PLP_PEwA", 330 "Public": " 331 5PxAR4YJvsf7XS1m25OnhkSh_F5yopwHCClxQZO4I2w5uc-twDYhRhFPazUBBKkT 332 G7ruS1qFJC-vuzcI6UL9Ee0QeJ9plnWoJA5CsoTFg_dHQVKEkdW5D227NT5OnvCe 333 AH1yinKSoIcRh4CXSG3MMC9oBOIj7YF4oWSgJ-T4ruMLXONac-o6T_2h-00dD9OP 334 Mpkj8_OdX3TdNwKnkSNJRrGj5F8UunJU9C85Tr1eh-U7wzW753RaqwN3R-B3LVjl 335 t4d1qiKbqGEzSjknSrjtUIReuAYtCI0fqOTap-6XcvdB_SHs4vPZ8oErIU0aTB65 336 VTtje5fm16tp-3o8P7x6WQ"}}, 337 "ClientNonce": { 338 "PublicKeyDH": { 339 "kid": "MB6Z6-GUF3J-RQRD3-IHIPS-UNOCI-HZDDR", 340 "Domain": " 341 YE6bnq1MlX5ojaJto6PLP_PEwA", 342 "Public": " 343 rVQmfx5-bSS6pTLwARcg_SyCBlNjZzWJ0yu9F7SE_2FuOJneQSqXOg1Gefz5UB2T 344 dD3W8wyKHJHAPyvX05vhQcicGNKLB9MO5x4Pzn2Klwm0-W4jJNZ1qHjuy_l81six 345 VqdGlRT44q9LTG326BJMmZMv_bij_lz3qTa8vOb9WTXfk458OV0ELphXmGSghi5t 346 x_rrS9z9gpKR5a22qTraHpdQJvIpXO0HPGddn_sQ3K2DWCtfVTi7aiwr7kwsO3p6 347 -NIHuAG4zRo86NE0UM_e6B4b7zX5cLt2n1_rqVNzwJOER1pRxgiFRtdJ43HyBVzv 348 uW1BMrZzT0JCR9g5kGG_OA"}}}} 350 Figure 1 352 The Keyu Exchange response is 353 HTTP/1.1 200 OK 354 Date: Wed 11 Apr 2018 09:01:08 355 Content-Length: 1360 357 { 358 "ExchangeResponse": { 359 "Status": 201, 360 "StatusDescription": "Operation completed successfully", 361 "Ticket": " 362 T3BhcXVlIHZhbHVlIG91dHNpZGUgc2NvcGUgb2Ygc3BlY2lmaWNhdGlvbg", 363 "Witness": " 364 tKE46P84C0qjGur7cbZNLxhfrU7NSEj98AKEIVh_zzg", 365 "ServerCredential": { 366 "PublicKeyDH": { 367 "kid": "MDD5A-RFNE7-JNUOS-23LTY-O4NIJ-PAYKM", 368 "Domain": " 369 YE6bnq1MlX5ojaJto6PLP_PEwA", 370 "Public": " 371 W-SCGVPSf1zgtgj_hwlLLt_CQnYttpxn4Ze4r18B5UO-a8G1XxeQEUjjUUvRqDMX 372 6KIWbrctjKOx2pIxAbMM3k9EzIk1lyvdhaXnSs-bBEHJpuqWzaz46JEt_49Nwppb 373 _Qr0j4gFvqrr0Fr7uXIuoihF8byL7b4M69dvRT9wE1KQSw0hTdcnmWgN0x0IcWcY 374 v3DTqGImtMibFkbgozj7csH-4UsMYDfqQx-DgGXLd0OkvN5CFqS030GRD9iDT9R4 375 98TQgLK8YD6J08_i2ADAGiP_GwHvDHZHkq0jFkgris5JJvEbfXgS7h8yYEnzgUPL 376 7xKt1vGcYs5ZQzHu8X6RGg"}}, 377 "ServerNonce": { 378 "PublicKeyDH": { 379 "kid": "MBD52-J4WFR-XKDUI-5BGL7-VHCQK-ZEHI7", 380 "Domain": " 381 YE6bnq1MlX5ojaJto6PLP_PEwA", 382 "Public": " 383 FkxMhJ64ZzdWI9QoBAeFEnB-9BupOu-B0FLmGMB9kkusumORQI-qiYQiGkEH93hH 384 qSelOLGuM83VzC-SS3UQKmlDVb1rbRSCqZXbkLCnc8KHeiBp0r8rmVIH8XicYLhP 385 _k9N5EjGmfcowGzOxZkO1d7g4sXEIv_Djr5hFf57F41zAvB34-ny2ZsD2jMyG4r5 386 26bMr69ceLEwfqXx5_rDc3CljfC1cAdBMsZSslFokurzq9X0nF2maPeYRpN3Ytbn 387 opzWmSyQZkoFg8Is9vnk6Dzy0mRHALpY0L6cMEEyYwNEhV7uGLMZsRtRLVDHvkAN 388 q2vUlh-CxthTdIWYFLjw4wA"}}, 389 "Encryption": ["A256CBC-HS512"], 390 "Authentication": ["HS512"]}} 392 Figure 2 394 Note that the example has the witness value but does not authenticate 395 the signed result at present. Perhaps it would be better to create 396 the witness value from the ticket data which eliminates the need for 397 authenticating the response?? 399 3.9. Rekey Example 401 (TBS) 403 4. Key Exchange Service 405 Supports key exchange to establish a shared secret and bound ticket 406 between a client and a service 408 HTTP Well Known Service Prefix: /.well-known/jwcexchange 410 Every Recrypt Service transaction consists of exactly one request 411 followed by exactly one response. 413 4.1. Shared classes 415 4.1.1. Structure: Algorithms 417 Describes an algorithm suite. Each suite consists of sets of 418 authentication and encryption algorithms which are mutually 419 compatible. i.e. the counterparty MAY select any one of the 420 encryption algorithms and use it with any one of the authentication 421 algorithms. 423 Encryption: String [0..Many] Algorithm identifiers of encryption and 424 authenticated encryption algorithms offered 426 Authentication: String [0..Many] Authentication algorithm offer 428 4.2. Utility Transactions 430 4.3. Transaction: Exchange 432 Request: ExchangeRequest 434 Request: ExchangeRequest 436 Response: ExchangeResponse 438 Perform Key Exchange to establish shared key bound to a ticket. 440 4.3.1. Message: ExchangeRequest 442 Initiate the key exchange request. 444 Offer: Algorithms [0..Many] Set of message authentication and 445 encryption algorithms offered by the client 447 4.3.2. Message: ExchangeResponse 449 Returns the server parameters. 451 Ticket: Binary (Optional) Opaque session identifier. 453 Witness: Binary (Optional) Opaque witness value used to prove 454 binding to the ticket. 456 Encryption: String [0..Many] Algorithm identifiers of encryption or 457 authenticated encryption algorithm chosen 459 Authentication: String [0..Many] Algorithm identifiers of 460 authentication algorithm chosen 462 5. Security Considerations 464 6. IANA Considerations 466 The following registrations are required: 468 HTTP Content Coding Registry jose-jwb 470 Well-Known URIs /.well-known/srv/ 472 [Or change registry to FCFS] 474 7. References 476 7.1. Normative References 478 [draft-hallambaker-mesh-architecture] 479 Hallam-Baker, P., "Mathematical Mesh: Architecture", 480 draft-hallambaker-mesh-architecture-04 (work in progress), 481 September 2017. 483 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 484 (AES) Key Wrap Algorithm", RFC 3394, DOI 10.17487/RFC3394, 485 September 2002. 487 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 488 Key Derivation Function (HKDF)", RFC 5869, 489 DOI 10.17487/RFC5869, May 2010. 491 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital 492 Signature Algorithm (EdDSA)", RFC 8032, 493 DOI 10.17487/RFC8032, January 2017. 495 7.2. Informative References 497 [draft-hallambaker-mesh-developer] 498 Hallam-Baker, P., "Mathematical Mesh: Reference 499 Implementation", draft-hallambaker-mesh-developer-06 (work 500 in progress), April 2018. 502 [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves 503 for Security", RFC 7748, DOI 10.17487/RFC7748, January 504 2016. 506 [X3DH] Marlinspike, M. and T. Perrin, "The X3DH Key Agreement 507 Protocol", November 2011. 509 7.3. URIs 511 [1] http://mathmesh.com/Documents/draft-hallambaker-json-key- 512 exchange.html 514 [2] http://mathmesh.com/Documents/draft-hallambaker-json-key- 515 exchange.html 517 Author's Address 519 Phillip Hallam-Baker 520 Comodo Group Inc. 522 Email: philliph@comodo.com