idnits 2.17.1 draft-amringer-jose-chacha-01.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 (July 23, 2019) is 1738 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 260 -- Looks like a reference, but probably isn't: '2' on line 262 == Missing Reference: 'RFC-THIS' is mentioned on line 220, 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 July 23, 2019 4 Intended status: Informational 5 Expires: January 24, 2020 7 Chacha derived AEAD algorithms in JSON Object Signing and Encryption 8 (JOSE) 9 draft-amringer-jose-chacha-01 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 January 24, 2020. 35 Copyright Notice 37 Copyright (c) 2019 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 . . . . . . . . . . . . . . . . . . . . . . . 2 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 . . . . . 3 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 . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 6.1. Normative References . . . . . . . . . . . . . . . . . . 5 66 6.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 6 67 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6 69 1. Introduction 71 The Internet Research Task Force (IRTF) Crypto Forum Research Group 72 (CFRG) defined the ChaCha20 and Poly1305 algorithms to be used in 73 IETF protocols both independantly and as an AEAD construction 74 ([RFC8439]). It has also been presented with a definition of an 75 eXtended-nonce variant ([I-D.irtf-cfrg-xchacha]) for use in stateless 76 contexts. This document defines how to use those algorithms in JOSE 77 in an interoperable manner. 79 This document defines the conventions to use in the context of 80 [RFC7516], and [RFC7517]. 82 1.1. Notation and Conventions 84 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 85 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 86 document are to be interpreted as described in [RFC2119]. 88 The JOSE key format ("JSON Web Key (JWK)") is defined by [RFC7517] 89 and thumbprints for it ("JSON Web Key (JWK) Thumbprint") in 90 [RFC7638]. 92 2. Key Encryption 93 2.1. Algorithms 95 This section defines the specifics of encrypting a JWE Content 96 Encryption Key (CEK) with AEAD_CHACHA20_POLY1305 [RFC8439] and 97 AEAD_XCHACHA20_POLY1305 [I-D.irtf-cfrg-xchacha]. 99 Use of an Initialization Vector (IV) is REQUIRED with this algorithm. 100 The IV is represented in base64url-encoded form as the "iv" 101 (initialization vector) Header Parameter value. 103 The Additional Authenticated Data value used is the empty octet 104 string. 106 The JWE Encrypted Key value is the ciphertext output. 108 The Authentication Tag output is represented in base64url-encoded 109 form as the "tag" (authentication tag) Header Parameter value. 111 The following "alg" (algorithm) Header Parameter values are used to 112 indicate that the JWE Encrypted Key is the result of encrypting the 113 CEK using the corresponding algorithm and IV size: 115 +-------------------------+----------+-------------+ 116 | Algorithm | IV size | "alg" value | 117 +-------------------------+----------+-------------+ 118 | AEAD_CHACHA20_POLY1305 | 96 bits | C20PKW | 119 | AEAD_XCHACHA20_POLY1305 | 192 bits | XC20PKW | 120 +-------------------------+----------+-------------+ 122 2.2. Header Parameters Used for Key Encryption 124 The following Header Parameters are used for both algorithms defined 125 for key encryption. 127 2.2.1. "iv" (Initialization Vector) Header Parameter 129 The "iv" (initialization vector) Header Parameter value is the 130 base64url-encoded representation of the 96-bit or 192-bit IV value 131 used for the key encryption operation. This Header Parameter MUST be 132 present and MUST be understood and processed by implementations when 133 these algorithms are used. 135 2.2.2. "tag" (Authentication Tag) Header Parameter 137 The "tag" (authentication tag) Header Parameter value is the 138 base64url-encoded representation of the 128-bit Authentication Tag 139 value resulting from the key encryption operation. This Header 140 Parameter MUST be present and MUST be understood and processed by 141 implementations when these algorithms are used. 143 3. Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static 145 This section defines the specifics of key agreement with Elliptic 146 Curve Diffie-Hellman Ephemeral Static [RFC6090], in combination with 147 the Concat KDF, as defined in Section 5.8.2.1 of NIST.800-56A [1] for 148 use as a symmetric key to wrap the CEK with the "C20PKW", or 149 "XC20PKW" algorithms, in the Key Agreement with Key Wrapping mode. 151 This mode is used exactly as defined in Section 4.6 of RFC7518 [2], 152 except that the combined key wrapping algorithms are the ones 153 indicated in this document. All headers pertaining to both the ECDH- 154 ES and key wrapping components ("iv",' "tag", "epk", "apu", "apv") 155 have the same meaning and requirement as in their original 156 definitions. 158 The following "alg" (algorithm) Header Parameter values are used to 159 indicate that the JWE Encrypted Key is the result of encrypting the 160 CEK using the corresponding algorithm: 162 +-----------------+-------------------------------------------------+ 163 | "alg" value | Key Management Algorithm | 164 +-----------------+-------------------------------------------------+ 165 | ECDH-ES+C20PKW | ECDH-ES using Concat KDF and CEK wrapped with | 166 | | C20PKW | 167 | ECDH-ES+XC20PKW | ECDH-ES using Concat KDF and CEK wrapped with | 168 | | XC20PKW | 169 +-----------------+-------------------------------------------------+ 171 4. Content Encryption 173 4.1. Algorithms 175 This section defines the specifics of performing authenticated 176 encryption with ChaCha20-Poly1305. 178 The CEK is used as the encryption key. 180 Use of an IV is REQUIRED with this algorithm. 182 The following "enc" (encryption algorithm) Header Parameter values 183 are used to indicate that the JWE Ciphertext and JWE Authentication 184 Tag values have been computed using the corresponding algorithm and 185 IV size: 187 +-------------------------+----------+-------------+ 188 | Algorithm | IV size | "alg" value | 189 +-------------------------+----------+-------------+ 190 | AEAD_CHACHA20_POLY1305 | 96 bits | C20P | 191 | AEAD_XCHACHA20_POLY1305 | 192 bits | XC20P | 192 +-------------------------+----------+-------------+ 194 5. IANA Considerations 196 The following is added to the "JSON Web Signature and Encryption 197 Algorithms" registry: 199 o Algorithm Name: "C20PKW" o Algorithm Description: Key wrapping with 200 ChaCha20-Poly1305 o Algorithm Usage Location(s): "alg" o JOSE 201 Implementation Requirements: Recommended o Change Controller: IESG o 202 Specification Document(s): Section 2 of [RFC-THIS] o Algorithm 203 Analysis Documents(s): [RFC8439] 205 o Algorithm Name: "XC20PKW" o Algorithm Description: Key wrapping 206 with XChaCha20-Poly1305 o Algorithm Usage Location(s): "alg" o JOSE 207 Implementation Requirements: Recommended o Change Controller: IESG o 208 Specification Document(s): Section 2 of [RFC-THIS] o Algorithm 209 Analysis Documents(s): [I-D.irtf-cfrg-xchacha] 211 o Algorithm Name: "C20P" o Algorithm Description: ChaCha20-Poly1305 o 212 Algorithm Usage Location(s): "enc" o JOSE Implementation 213 Requirements: Recommended o Change Controller: IESG o Specification 214 Document(s): Section 3 of [RFC-THIS] o Algorithm Analysis 215 Documents(s): [RFC8439] 217 o Algorithm Name: "XC20P" o Algorithm Description: ChaCha20-Poly1305 218 o Algorithm Usage Location(s): "enc" o JOSE Implementation 219 Requirements: Recommended o Change Controller: IESG o Specification 220 Document(s): Section 3 of [RFC-THIS] o Algorithm Analysis 221 Documents(s): [I-D.irtf-cfrg-xchacha] 223 6. References 225 6.1. Normative References 227 [I-D.irtf-cfrg-xchacha] 228 Arciszewski, S., "XChaCha: eXtended-nonce ChaCha and 229 AEAD_XChaCha20_Poly1305", draft-irtf-cfrg-xchacha-01 (work 230 in progress), July 2019. 232 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 233 Requirement Levels", BCP 14, RFC 2119, 234 DOI 10.17487/RFC2119, March 1997, 235 . 237 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 238 Curve Cryptography Algorithms", RFC 6090, 239 DOI 10.17487/RFC6090, February 2011, 240 . 242 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 243 RFC 7516, DOI 10.17487/RFC7516, May 2015, 244 . 246 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 247 DOI 10.17487/RFC7517, May 2015, 248 . 250 [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) 251 Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September 252 2015, . 254 [RFC8439] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF 255 Protocols", RFC 8439, DOI 10.17487/RFC8439, June 2018, 256 . 258 6.2. URIs 260 [1] https://csrc.nist.gov/publications/detail/sp/800-56a/rev-3/final 262 [2] https://tools.ietf.org/html/rfc7518#section-4.6 264 Author's Address 266 Guillaume Amringer 267 Canada 269 Email: g.amringer@gmail.com