idnits 2.17.1 draft-amringer-jose-chacha-02.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 document seems to lack a Security Considerations section. ** The abstract seems to contain references ([RFC8439], [I-D.irtf-cfrg-xchacha]), 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 -- The document date (January 9, 2020) is 1540 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 289 -- Looks like a reference, but probably isn't: '2' on line 291 == Missing Reference: 'RFC-THIS' is mentioned on line 249, but not defined == Outdated reference: A later version (-03) exists of draft-irtf-cfrg-xchacha-01 Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 (No Working Group) G. Amringer 3 Internet-Draft January 9, 2020 4 Intended status: Informational 5 Expires: July 12, 2020 7 Chacha derived AEAD algorithms in JSON Object Signing and Encryption 8 (JOSE) 9 draft-amringer-jose-chacha-02 11 Abstract 13 This document defines how to use the AEAD algorithms 14 "AEAD_XCHACHA20_POLY1305" and "AEAD_CHACHA20_POLY1305" from [RFC8439] 15 and [I-D.irtf-cfrg-xchacha] in JSON Object Signing and Encryption 16 (JOSE). 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 July 12, 2020. 35 Copyright Notice 37 Copyright (c) 2020 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 1.1. Notation and Conventions . . . . . . . . . . . . . . . . 2 54 2. Key Encryption . . . . . . . . . . . . . . . . . . . . . . . 3 55 2.1. Algorithms . . . . . . . . . . . . . . . . . . . . . . . 3 56 2.2. Header Parameters Used for Key Encryption . . . . . . . . 3 57 2.2.1. "iv" (Initialization Vector) Header Parameter . . . . 3 58 2.2.2. "tag" (Authentication Tag) Header Parameter . . . . . 4 59 3. Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral 60 Static . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 4. Content Encryption . . . . . . . . . . . . . . . . . . . . . 4 62 4.1. Algorithms . . . . . . . . . . . . . . . . . . . . . . . 4 63 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 64 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 65 6.1. Normative References . . . . . . . . . . . . . . . . . . 6 66 6.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 7 67 Appendix A. Example using XC20PKW . . . . . . . . . . . . . . . 7 68 Appendix B. Example using ECDH-ES+XC20PKW . . . . . . . . . . . 8 69 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 71 1. Introduction 73 The Internet Research Task Force (IRTF) Crypto Forum Research Group 74 (CFRG) defined the ChaCha20 and Poly1305 algorithms to be used in 75 IETF protocols both independantly and as an AEAD construction 76 ([RFC8439]). It has also been presented with a definition of an 77 eXtended-nonce variant ([I-D.irtf-cfrg-xchacha]) for use in stateless 78 contexts. This document defines how to use those algorithms in JOSE 79 in an interoperable manner. 81 This document defines the conventions to use in the context of 82 [RFC7516], and [RFC7517]. 84 1.1. Notation and Conventions 86 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 87 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 88 document are to be interpreted as described in [RFC2119]. 90 The JOSE key format ("JSON Web Key (JWK)") is defined by [RFC7517] 91 and thumbprints for it ("JSON Web Key (JWK) Thumbprint") in 92 [RFC7638]. 94 2. Key Encryption 96 2.1. Algorithms 98 This section defines the specifics of encrypting a JWE Content 99 Encryption Key (CEK) with AEAD_CHACHA20_POLY1305 [RFC8439] and 100 AEAD_XCHACHA20_POLY1305 [I-D.irtf-cfrg-xchacha]. 102 Use of an Initialization Vector (IV) is REQUIRED with this algorithm. 103 The IV is represented in base64url-encoded form as the "iv" 104 (initialization vector) Header Parameter value. 106 The Additional Authenticated Data value used is the empty octet 107 string. 109 The JWE Encrypted Key value is the ciphertext output. 111 The Authentication Tag output is represented in base64url-encoded 112 form as the "tag" (authentication tag) Header Parameter value. 114 The following "alg" (algorithm) Header Parameter values are used to 115 indicate that the JWE Encrypted Key is the result of encrypting the 116 CEK using the corresponding algorithm and IV size: 118 +-------------------------+----------+-------------+ 119 | Algorithm | IV size | "alg" value | 120 +-------------------------+----------+-------------+ 121 | AEAD_CHACHA20_POLY1305 | 96 bits | C20PKW | 122 | AEAD_XCHACHA20_POLY1305 | 192 bits | XC20PKW | 123 +-------------------------+----------+-------------+ 125 2.2. Header Parameters Used for Key Encryption 127 The following Header Parameters are used for both algorithms defined 128 for key encryption. 130 2.2.1. "iv" (Initialization Vector) Header Parameter 132 The "iv" (initialization vector) Header Parameter value is the 133 base64url-encoded representation of the 96-bit or 192-bit IV value 134 used for the key encryption operation. This Header Parameter MUST be 135 present and MUST be understood and processed by implementations when 136 these algorithms are used. 138 2.2.2. "tag" (Authentication Tag) Header Parameter 140 The "tag" (authentication tag) Header Parameter value is the 141 base64url-encoded representation of the 128-bit Authentication Tag 142 value resulting from the key encryption operation. This Header 143 Parameter MUST be present and MUST be understood and processed by 144 implementations when these algorithms are used. 146 3. Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static 148 This section defines the specifics of key agreement with Elliptic 149 Curve Diffie-Hellman Ephemeral Static [RFC6090], in combination with 150 the Concat KDF, as defined in Section 5.8.2.1 of NIST.800-56A [1] for 151 use as a symmetric key to wrap the CEK with the "C20PKW", or 152 "XC20PKW" algorithms, in the Key Agreement with Key Wrapping mode. 154 This mode is used exactly as defined in Section 4.6 of RFC7518 [2], 155 except that the combined key wrapping algorithms are the ones 156 indicated in this document. All headers pertaining to both the ECDH- 157 ES and key wrapping components ("iv",' "tag", "epk", "apu", "apv") 158 have the same meaning and requirement as in their original 159 definitions. 161 The following "alg" (algorithm) Header Parameter values are used to 162 indicate that the JWE Encrypted Key is the result of encrypting the 163 CEK using the corresponding algorithm: 165 +-----------------+-------------------------------------------------+ 166 | "alg" value | Key Management Algorithm | 167 +-----------------+-------------------------------------------------+ 168 | ECDH-ES+C20PKW | ECDH-ES using Concat KDF and CEK wrapped with | 169 | | C20PKW | 170 | ECDH-ES+XC20PKW | ECDH-ES using Concat KDF and CEK wrapped with | 171 | | XC20PKW | 172 +-----------------+-------------------------------------------------+ 174 4. Content Encryption 176 4.1. Algorithms 178 This section defines the specifics of performing authenticated 179 encryption with ChaCha20-Poly1305. 181 The CEK is used as the encryption key. 183 Use of an IV is REQUIRED with this algorithm. 185 The following "enc" (encryption algorithm) Header Parameter values 186 are used to indicate that the JWE Ciphertext and JWE Authentication 187 Tag values have been computed using the corresponding algorithm and 188 IV size: 190 +-------------------------+----------+-------------+ 191 | Algorithm | IV size | "alg" value | 192 +-------------------------+----------+-------------+ 193 | AEAD_CHACHA20_POLY1305 | 96 bits | C20P | 194 | AEAD_XCHACHA20_POLY1305 | 192 bits | XC20P | 195 +-------------------------+----------+-------------+ 197 5. IANA Considerations 199 The following is added to the "JSON Web Signature and Encryption 200 Algorithms" registry: 202 o Algorithm Name: "C20PKW" 203 o Algorithm Description: Key wrapping with ChaCha20-Poly1305 204 o Algorithm Usage Location(s): "alg" 205 o JOSE Implementation Requirements: Optional 206 o Change Controller: IESG 207 o Specification Document(s): Section 2 of [RFC-THIS] 208 o Algorithm Analysis Documents(s): [RFC8439] 210 o Algorithm Name: "XC20PKW" 211 o Algorithm Description: Key wrapping with XChaCha20-Poly1305 212 o Algorithm Usage Location(s): "alg" 213 o JOSE Implementation Requirements: Optional 214 o Change Controller: IESG 215 o Specification Document(s): Section 2 of [RFC-THIS] 216 o Algorithm Analysis Documents(s): [I-D.irtf-cfrg-xchacha] 218 o Algorithm Name: "ECDH-ES+C20PKW" 219 o Algorithm Description: ECDH-ES using Concat KDF and "C20PKW" 220 wrapping 221 o Algorithm Usage Location(s): "alg" 222 o JOSE Implementation Requirements: Optional 223 o Change Controller: IESG 224 o Specification Document(s): Section 3 of [RFC-THIS] 225 o Algorithm Analysis Documents(s): n/a 227 o Algorithm Name: "ECDH-ES+XC20PKW" 228 o Algorithm Description: ECDH-ES using Concat KDF and "XC20PKW" 229 wrapping 230 o Algorithm Usage Location(s): "alg" 231 o JOSE Implementation Requirements: Optional 232 o Change Controller: IESG 233 o Specification Document(s): Section 3 of [RFC-THIS] 234 o Algorithm Analysis Documents(s): n/a 236 o Algorithm Name: "C20P" 237 o Algorithm Description: ChaCha20-Poly1305 238 o Algorithm Usage Location(s): "enc" 239 o JOSE Implementation Requirements: Optional 240 o Change Controller: IESG 241 o Specification Document(s): Section 4 of [RFC-THIS] 242 o Algorithm Analysis Documents(s): [RFC8439] 244 o Algorithm Name: "XC20P" 245 o Algorithm Description: ChaCha20-Poly1305 246 o Algorithm Usage Location(s): "enc" 247 o JOSE Implementation Requirements: Optional 248 o Change Controller: IESG 249 o Specification Document(s): Section 4 of [RFC-THIS] 250 o Algorithm Analysis Documents(s): [I-D.irtf-cfrg-xchacha] 252 6. References 254 6.1. Normative References 256 [I-D.irtf-cfrg-xchacha] 257 Arciszewski, S., "XChaCha: eXtended-nonce ChaCha and 258 AEAD_XChaCha20_Poly1305", draft-irtf-cfrg-xchacha-01 (work 259 in progress), July 2019. 261 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 262 Requirement Levels", BCP 14, RFC 2119, 263 DOI 10.17487/RFC2119, March 1997, 264 . 266 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 267 Curve Cryptography Algorithms", RFC 6090, 268 DOI 10.17487/RFC6090, February 2011, 269 . 271 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 272 RFC 7516, DOI 10.17487/RFC7516, May 2015, 273 . 275 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 276 DOI 10.17487/RFC7517, May 2015, 277 . 279 [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) 280 Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September 281 2015, . 283 [RFC8439] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF 284 Protocols", RFC 8439, DOI 10.17487/RFC8439, June 2018, 285 . 287 6.2. URIs 289 [1] https://csrc.nist.gov/publications/detail/sp/800-56a/rev-3/final 291 [2] https://tools.ietf.org/html/rfc7518#section-4.6 293 Appendix A. Example using XC20PKW 295 *Considering the payload of "Hello World!" (Base64URL):* 297 SGVsbG8gV29ybGQh 299 *We begin by generating the XChacha20-Poly1309 content encryption key 300 (Base64URL):* 302 la2knCeFPAvUE2IVPm-RNrwj4UrHffLU6Y1tx3d5T1Q 304 *We follow by encrypting the CEK using XChacha20-Poly1309 itself. We 305 generate a new key and a nonce:* 307 KEK (Base64URL) 309 Rpv7sxPJYeNjKr-L8gPrKtQLHX-1dDuqtJuriVQ0eUY 311 Nonce (Base64URL) 313 LuNNS5RAagkOQVewQOLRp9noXET_YsPX 315 *Using those parameters, we end up with the following output from 316 XChacha20-Poly1309:* 318 Ciphertext (Base64URL) 320 K-kXEFjmSsjKzU91 322 Tag (Base64URL) 324 VT2Z9a93JFe2om2gboUz4g 326 *We then construct the following JWE header:* 327 {"alg":"XC20PKW","enc":"XC20P","iv":"LuNNS5RAagkOQVewQOLRp9noXET 328 _YsPX","tag":"VT2Z9a93JFe2om2gboUz4g"} 330 *The next step is to prepare the content encryption:* 332 AAD (Base64URL) 334 eyJhbGciOiJYQzIwUEtXIiwiZW5jIjoiWEMyMFAiLCJpdiI6Ikx1Tk5TNVJBYWdr 335 T1FWZXdRT0xScDlub1hFVF9Zc1BYIiwidGFnIjoiVlQyWjlhOTNKRmUyb20yZ2Jv 336 VXo0ZyJ9 338 Key (generated earlier): 340 la2knCeFPAvUE2IVPm-RNrwj4UrHffLU6Y1tx3d5T1Q 342 Nonce (Base64URL) 344 LHs6vru3ggyuAzgT2UJkWyqJuZSv0Gae 346 *We then encrypt the payload with XChacha20-Poly1309 using the 347 previous parameters, which results in the following output:* 349 Ciphertext (Base64URL) 351 QgxRd4qQrkQNaEK3 353 Tag (Base64URL) 355 aQDs_RkdWabvzmxYEnoShg 357 *Lastly, we combine all the previous outputs to form the following 358 JWE:* 360 eyJhbGciOiJYQzIwUEtXIiwiZW5jIjoiWEMyMFAiLCJpdiI6Ikx1Tk5TNVJBYWdr 361 T1FWZXdRT0xScDlub1hFVF9Zc1BYIiwidGFnIjoiVlQyWjlhOTNKRmUyb20yZ2Jv 362 VXo0ZyJ9.K-kXEFjmSsjKzU91.LHs6vru3ggyuAzgT2UJkWyqJuZSv0Gae.QgxRd 363 4qQrkQNaEK3.aQDs_RkdWabvzmxYEnoShg 365 Appendix B. Example using ECDH-ES+XC20PKW 367 *Considering the payload of "Hello World!" (Base64URL):* 369 SGVsbG8gV29ybGQh 371 *We begin by generating the XChacha20-Poly1309 content encryption key 372 (Base64URL):* 374 O2-TuP5Qz_ab6N61LhVS6asFdN_X5zF0YhJ6Df0vtoE 376 *We follow by encrypting the CEK using XChacha20-Poly1309 itself 377 following a key agreement. We generate a new key pair:* 379 Private X (Base64URL) 381 OtbkdOjp6SIgQ-TMXlqg48Ds8ycsSCxadJrjCurCcSM 383 Public X (Base64URL) 385 xxXXpDLvS0z-Zlx5J6dsVPPVonYufe9zTKfat0dEryM 387 *Using the recipient public key, we generate a shared secret* 389 Recipient PK (Base64URL) 391 8llBJmFOkoFO8TYhFyDFm90Z8c6ytiD18wUgM5alCHY 393 Shared Secret (Base64URL) 395 llX-1dAQU6BiuTDUq4DgRy9Ob-1zoLp-1hvmKa8baGk 397 *We can now derive a KEK:* 399 APU (Base64URL) 401 Q2tkNDNqSkZNb2FHeGVJZW9FUHgtNF9SYlNmLWd1T19MRHpvbDhrLWFnM2NELXhm 402 dzdWX1IzM0lXVHRDZ0NqVmhmWTVQa29aT3AyTGwxZTR5ZWZ4d2c 404 KEK (Base64URL) 406 jPC4ybPvJ-FF4qz7hYiHDxr7XGQdQCMDjWaQ-y_MJfQ 408 *We can now perform XChacha20-Poly1309 on the CEK using a new random 409 nonce:* 411 Nonce (Base64URL) 413 1Ef_Hs3NdFIujh9-uZEYLz4N_b1K1CJl 415 Ciphertext (Base64URL) 417 mzHMc5XlqW-jkGP4 419 Tag (Base64URL) 421 G8A4JnNmsG2wgvQh6Q5A8g 423 *We then construct the following JWE header:* 424 {"alg":"ECDH-ES+XC20PKW","enc":"XC20P","iv":"1Ef_Hs3NdFIujh9-uZE 425 YLz4N_b1K1CJl","tag":"G8A4JnNmsG2wgvQh6Q5A8g","apu":"Q2tkNDNqSkZ 426 Nb2FHeGVJZW9FUHgtNF9SYlNmLWd1T19MRHpvbDhrLWFnM2NELXhmdzdWX1IzM0l 427 XVHRDZ0NqVmhmWTVQa29aT3AyTGwxZTR5ZWZ4d2c","epk":{"typ":"OKP","cr 428 v":"X25519","x":"xxXXpDLvS0z-Zlx5J6dsVPPVonYufe9zTKfat0dEryM"}} 430 *The next step is to prepare the content encryption:* 432 AAD (Base64URL) 434 eyJhbGciOiJFQ0RILUVTK1hDMjBQS1ciLCJlbmMiOiJYQzIwUCIsIml2IjoiMUVm 435 X0hzM05kRkl1amg5LXVaRVlMejROX2IxSzFDSmwiLCJ0YWciOiJHOEE0Sm5ObXNH 436 MndndlFoNlE1QThnIiwiYXB1IjoiUTJ0a05ETnFTa1pOYjJGSGVHVkpaVzlGVUhn 437 dE5GOVNZbE5tTFdkMVQxOU1SSHB2YkRockxXRm5NMk5FTFhobWR6ZFdYMUl6TTBs 438 WFZIUkRaME5xVm1obVdUVlFhMjlhVDNBeVRHd3haVFI1WldaNGQyYyIsImVwayI6 439 eyJ0eXAiOiJPS1AiLCJjcnYiOiJYMjU1MTkiLCJ4IjoieHhYWHBETHZTMHotWmx4 440 NUo2ZHNWUFBWb25ZdWZlOXpUS2ZhdDBkRXJ5TSJ9fQ 442 Key (generated earlier): 444 O2-TuP5Qz_ab6N61LhVS6asFdN_X5zF0YhJ6Df0vtoE 446 Nonce (Base64URL) 448 okZz0AJz-PfUL4OGjioPLsg6-siwyq2I 450 *We then encrypt the payload with XChacha20-Poly1309 using the 451 previous parameters, which results in the following output:* 453 Ciphertext (Base64URL) 455 yxpuuXB7DcXBlyVE 457 Tag (Base64URL) 459 IwvDEC8hxltfzidjmUKeMg 461 *Lastly, we combine all the previous outputs to form the following 462 JWE:* 463 eyJhbGciOiJFQ0RILUVTK1hDMjBQS1ciLCJlbmMiOiJYQzIwUCIsIml2IjoiMUVm 464 X0hzM05kRkl1amg5LXVaRVlMejROX2IxSzFDSmwiLCJ0YWciOiJHOEE0Sm5ObXNH 465 MndndlFoNlE1QThnIiwiYXB1IjoiUTJ0a05ETnFTa1pOYjJGSGVHVkpaVzlGVUhn 466 dE5GOVNZbE5tTFdkMVQxOU1SSHB2YkRockxXRm5NMk5FTFhobWR6ZFdYMUl6TTBs 467 WFZIUkRaME5xVm1obVdUVlFhMjlhVDNBeVRHd3haVFI1WldaNGQyYyIsImVwayI6 468 eyJ0eXAiOiJPS1AiLCJjcnYiOiJYMjU1MTkiLCJ4IjoieHhYWHBETHZTMHotWmx4 469 NUo2ZHNWUFBWb25ZdWZlOXpUS2ZhdDBkRXJ5TSJ9fQ.mzHMc5XlqW-jkGP4.okZz 470 0AJz-PfUL4OGjioPLsg6-siwyq2I.yxpuuXB7DcXBlyVE.IwvDEC8hxltfzidjmU 471 KeMg 473 Author's Address 475 Guillaume Amringer 476 Canada 478 Email: g.amringer@gmail.com