idnits 2.17.1 draft-ietf-httpbis-encryption-encoding-04.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 31, 2016) is 2733 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'FIPS180-4' ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Downref: Normative reference to an Informational RFC: RFC 5869 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 7233 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7235 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7540 (Obsoleted by RFC 9113) Summary: 4 errors (**), 0 flaws (~~), 1 warning (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP Working Group M. Thomson 3 Internet-Draft Mozilla 4 Intended status: Standards Track October 31, 2016 5 Expires: May 4, 2017 7 Encrypted Content-Encoding for HTTP 8 draft-ietf-httpbis-encryption-encoding-04 10 Abstract 12 This memo introduces a content coding for HTTP that allows message 13 payloads to be encrypted. 15 Note to Readers 17 Discussion of this draft takes place on the HTTP working group 18 mailing list (ietf-http-wg@w3.org), which is archived at 19 https://lists.w3.org/Archives/Public/ietf-http-wg/ . 21 Working Group information can be found at http://httpwg.github.io/ ; 22 source code and issues list for this draft can be found at 23 https://github.com/httpwg/http-extensions/labels/encryption . 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on May 4, 2017. 42 Copyright Notice 44 Copyright (c) 2016 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 61 2. The "aes128gcm" HTTP Content Coding . . . . . . . . . . . . . 3 62 2.1. Encryption Content Coding Header . . . . . . . . . . . . 5 63 2.2. Content Encryption Key Derivation . . . . . . . . . . . . 6 64 2.3. Nonce Derivation . . . . . . . . . . . . . . . . . . . . 7 65 3. Crypto-Key Header Field . . . . . . . . . . . . . . . . . . . 7 66 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 8 67 4.1. Encryption of a Response . . . . . . . . . . . . . . . . 8 68 4.2. Encryption with Multiple Records . . . . . . . . . . . . 9 69 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 70 5.1. Key and Nonce Reuse . . . . . . . . . . . . . . . . . . . 10 71 5.2. Data Encryption Limits . . . . . . . . . . . . . . . . . 10 72 5.3. Content Integrity . . . . . . . . . . . . . . . . . . . . 10 73 5.4. Leaking Information in Headers . . . . . . . . . . . . . 11 74 5.5. Poisoning Storage . . . . . . . . . . . . . . . . . . . . 11 75 5.6. Sizing and Timing Attacks . . . . . . . . . . . . . . . . 12 76 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 77 6.1. The "aes128gcm" HTTP Content Coding . . . . . . . . . . . 12 78 6.2. Crypto-Key Header Field . . . . . . . . . . . . . . . . . 12 79 6.3. The HTTP Crypto-Key Parameter Registry . . . . . . . . . 12 80 6.3.1. keyid . . . . . . . . . . . . . . . . . . . . . . . . 13 81 6.3.2. aes128gcm . . . . . . . . . . . . . . . . . . . . . . 13 82 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 83 7.1. Normative References . . . . . . . . . . . . . . . . . . 13 84 7.2. Informative References . . . . . . . . . . . . . . . . . 14 85 Appendix A. JWE Mapping . . . . . . . . . . . . . . . . . . . . 15 86 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 16 87 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16 89 1. Introduction 91 It is sometimes desirable to encrypt the contents of a HTTP message 92 (request or response) so that when the payload is stored (e.g., with 93 a HTTP PUT), only someone with the appropriate key can read it. 95 For example, it might be necessary to store a file on a server 96 without exposing its contents to that server. Furthermore, that same 97 file could be replicated to other servers (to make it more resistant 98 to server or network failure), downloaded by clients (to make it 99 available offline), etc. without exposing its contents. 101 These uses are not met by the use of TLS [RFC5246], since it only 102 encrypts the channel between the client and server. 104 This document specifies a content coding (Section 3.1.2 of [RFC7231]) 105 for HTTP to serve these and other use cases. 107 This content coding is not a direct adaptation of message-based 108 encryption formats - such as those that are described by [RFC4880], 109 [RFC5652], [RFC7516], and [XMLENC] - which are not suited to stream 110 processing, which is necessary for HTTP. The format described here 111 cleaves more closely to the lower level constructs described in 112 [RFC5116]. 114 To the extent that message-based encryption formats use the same 115 primitives, the format can be considered as sequence of encrypted 116 messages with a particular profile. For instance, Appendix A 117 explains how the format is congruent with a sequence of JSON Web 118 Encryption [RFC7516] values with a fixed header. 120 This mechanism is likely only a small part of a larger design that 121 uses content encryption. How clients and servers acquire and 122 identify keys will depend on the use case. Though a complete key 123 management system is not described, this document defines an Crypto- 124 Key header field that can be used to convey keying material. 126 1.1. Notational Conventions 128 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 129 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 130 document are to be interpreted as described in [RFC2119]. 132 Base64url encoding is defined in Section 2 of [RFC7515]. 134 2. The "aes128gcm" HTTP Content Coding 136 The "aes128gcm" HTTP content coding indicates that a payload has been 137 encrypted using Advanced Encryption Standard (AES) in Galois/Counter 138 Mode (GCM) as identified as AEAD_AES_128_GCM in [RFC5116], 139 Section 5.1. The AEAD_AES_128_GCM algorithm uses a 128 bit content 140 encryption key. 142 Using this content coding requires knowledge of a key. The Crypto- 143 Key header field (Section 3) can be included to describe how the 144 content encryption key is derived or retrieved. Keys might be 145 provided in messages that are separate from those with encrypted 146 content using Crypto-Key, or provided through external mechanisms. 148 The "aes128gcm" content coding uses a single fixed set of encryption 149 primitives. Cipher suite agility is achieved by defining a new 150 content coding scheme. This ensures that only the HTTP Accept- 151 Encoding header field is necessary to negotiate the use of 152 encryption. 154 The "aes128gcm" content coding uses a fixed record size. The final 155 encoding consists of a header (see Section 2.1), zero or more fixed 156 size encrypted records, and a partial record. The partial record 157 MUST be shorter than the fixed record size. 159 +-----------+ content is rs octets minus padding 160 | data | of between 2 and 65537 octets; 161 +-----------+ the last record is smaller 162 | 163 v 164 +-----+-----------+ add padding to get rs octets; 165 | pad | data | the last record contains 166 +-----+-----------+ up to rs minus 1 octets 167 | 168 v 169 +--------------------+ encrypt with AEAD_AES_128_GCM; 170 | ciphertext | final size is rs plus 16 octets 171 +--------------------+ the last record is smaller 173 The record size determines the length of each portion of plaintext 174 that is enciphered, with the exception of the final record, which is 175 necessarily smaller. The record size ("rs") is included in the 176 content coding header (see Section 2.1). 178 AEAD_AES_128_GCM produces ciphertext 16 octets longer than its input 179 plaintext. Therefore, the length of each enciphered record other 180 than the last is equal to the value of the "rs" parameter plus 16 181 octets. To prevent an attacker from truncating a stream, an encoder 182 MUST append a record that contains only padding and is smaller than 183 the full record size if the final record ends on a record boundary. 184 A receiver MUST fail to decrypt if the final record ciphertext is 185 less than 18 octets in size or equal to the record size plus 16 (that 186 is, the size of a full encrypted record). Valid records always 187 contain at least two octets of padding and a 16 octet authentication 188 tag. 190 Each record contains between 2 and 65537 octets of padding, inserted 191 into a record before the enciphered content. Padding consists of a 192 two octet unsigned integer in network byte order, followed that 193 number of zero-valued octets. A receiver MUST fail to decrypt if any 194 padding octet other than the first two are non-zero, or a record has 195 more padding than the record size can accommodate. 197 The nonce for each record is a 96-bit value constructed from the 198 record sequence number and the input keying material. Nonce 199 derivation is covered in Section 2.3. 201 The additional data passed to each invocation of AEAD_AES_128_GCM is 202 a zero-length octet sequence. 204 A consequence of this record structure is that range requests 205 [RFC7233] and random access to encrypted payload bodies are possible 206 at the granularity of the record size. Partial records at the ends 207 of a range cannot be decrypted. Thus, it is best if range requests 208 start and end on record boundaries. 210 Selecting the record size most appropriate for a given situation 211 requires a trade-off. A smaller record size allows decrypted octets 212 to be released more rapidly, which can be appropriate for 213 applications that depend on responsiveness. Smaller records also 214 reduce the additional data required if random access into the 215 ciphertext is needed. Applications that depend on being able to pad 216 by arbitrary amounts cannot increase the record size beyond 65537 217 octets. 219 Applications that don't depending on streaming, random access, or 220 arbitrary padding can use larger records, or even a single record. A 221 larger record size reduces the processing and data overheads. 223 2.1. Encryption Content Coding Header 225 The content coding uses a header block that includes all parameters 226 needed to decrypt the content (other than the key). The header block 227 is placed in the body of a message ahead of the sequence of records. 229 +-----------+--------+-----------+---------------+ 230 | salt (16) | rs (4) | idlen (1) | keyid (idlen) | 231 +-----------+--------+-----------+---------------+ 233 salt: The "salt" parameter comprises the first 16 octets of the 234 "aes128gcm" content coding header. The same "salt" parameter 235 value MUST NOT be reused for two different payload bodies that 236 have the same input keying material; generating a random salt for 237 every application of the content coding ensures that content 238 encryption key reuse is highly unlikely. 240 rs: The "rs" or record size parameter contains an unsigned 32-bit 241 integer in network byte order that describes the record size in 242 octets. Note that it is therefore impossible to exceed the 243 2^36-31 limit on plaintext input to AEAD_AES_128_GCM. Values 244 smaller than 3 are invalid. 246 keyid: The "keyid" parameter can be used to identify the keying 247 material that is used. When the Crypto-Key header field is used, 248 the "keyid" identifies a matching value in that field. The 249 "keyid" parameter MUST be used if keying material included in an 250 Crypto-Key header field is needed to derive the content encryption 251 key. The "keyid" parameter can also be used to identify keys in 252 an application-specific fashion. 254 2.2. Content Encryption Key Derivation 256 In order to allow the reuse of keying material for multiple different 257 HTTP messages, a content encryption key is derived for each message. 258 The content encryption key is derived from the decoded value of the 259 "salt" parameter using the HMAC-based key derivation function (HKDF) 260 described in [RFC5869] using the SHA-256 hash algorithm [FIPS180-4]. 262 The value of the "salt" parameter is the salt input to HKDF function. 263 The keying material identified by the "keyid" parameter is the input 264 keying material (IKM) to HKDF. Input keying material can either be 265 prearranged, or can be described using the Crypto-Key header field 266 (Section 3). The extract phase of HKDF therefore produces a 267 pseudorandom key (PRK) as follows: 269 PRK = HMAC-SHA-256(salt, IKM) 271 The info parameter to HKDF is set to the ASCII-encoded string 272 "Content-Encoding: aes128gcm" and a single zero octet: 274 cek_info = "Content-Encoding: aes128gcm" || 0x00 276 Note: Concatenation of octet sequences is represented by the "||" 277 operator. 279 AEAD_AES_128_GCM requires a 16 octet (128 bit) content encryption key 280 (CEK), so the length (L) parameter to HKDF is 16. The second step of 281 HKDF can therefore be simplified to the first 16 octets of a single 282 HMAC: 284 CEK = HMAC-SHA-256(PRK, cek_info || 0x01) 286 2.3. Nonce Derivation 288 The nonce input to AEAD_AES_128_GCM is constructed for each record. 289 The nonce for each record is a 12 octet (96 bit) value that is 290 produced from the record sequence number and a value derived from the 291 input keying material. 293 The input keying material and salt values are input to HKDF with 294 different info and length parameters. 296 The length (L) parameter is 12 octets. The info parameter for the 297 nonce is the ASCII-encoded string "Content-Encoding: nonce", 298 terminated by a a single zero octet: 300 nonce_info = "Content-Encoding: nonce" || 0x00 302 The result is combined with the record sequence number - using 303 exclusive or - to produce the nonce. The record sequence number 304 (SEQ) is a 96-bit unsigned integer in network byte order that starts 305 at zero. 307 Thus, the final nonce for each record is a 12 octet value: 309 NONCE = HMAC-SHA-256(PRK, nonce_info || 0x01) XOR SEQ 311 This nonce construction prevents removal or reordering of records. 312 However, it permits truncation of the tail of the sequence (see 313 Section 2 for how this is avoided). 315 3. Crypto-Key Header Field 317 A Crypto-Key header field can be used to describe the input keying 318 material used by the "aes128gcm" content coding. 320 Ordinarily, this header field will not appear in the same message as 321 the encrypted content. Including the encryption key with the 322 encrypted payload reduces the value of using encryption to a somewhat 323 complicated checksum. However, the Crypto-Key header field could be 324 used in one message to provision keys for other messages. 326 The Crypto-Key header field uses the extended ABNF syntax defined in 327 Section 1.2 of [RFC7230] and the "parameter" and "OWS" rules from 328 [RFC7231]. 330 Crypto-Key = #crypto-key-params 331 crypto-key-params = [ parameter *( OWS ";" OWS parameter ) ] 333 keyid: The "keyid" parameter corresponds to the "keyid" parameter in 334 the content coding. 336 aes128gcm: The "aes128gcm" parameter contains the base64url-encoded 337 octets [RFC7515] of the input keying material for the "aes128gcm" 338 content coding. 340 Crypto-Key header field values with multiple instances of the same 341 parameter name in a single crypto-key-params production are invalid. 343 The input keying material used by the key derivation (see 344 Section 2.2) can be determined based on the information in the 345 Crypto-Key header field. 347 The value or values provided in the Crypto-Key header field is valid 348 only for the current HTTP message unless additional information 349 indicates a greater scope. 351 Alternative methods for determining input keying material MAY be 352 defined by specifications that use this content coding. This 353 document only defines the use of the "aes128gcm" parameter which 354 describes an explicit key. 356 The "aes128gcm" parameter MUST decode to at least 16 octets in order 357 to be used as input keying material for "aes128gcm" content coding. 359 4. Examples 361 This section shows a few examples of the encrypted content coding. 363 Note: All binary values in the examples in this section use base64url 364 encoding [RFC7515]. This includes the bodies of requests. 365 Whitespace and line wrapping is added to fit formatting constraints. 367 4.1. Encryption of a Response 369 Here, a successful HTTP GET response has been encrypted using input 370 keying material that is identified by the string "a1". 372 The encrypted data in this example is the UTF-8 encoded string "I am 373 the walrus". The input keying material is included in the Crypto-Key 374 header field. The content body contains a single record only and is 375 shown here using base64url encoding for presentation reasons. 377 HTTP/1.1 200 OK 378 Content-Type: application/octet-stream 379 Content-Length: 33 380 Content-Encoding: aes128gcm 381 Crypto-Key: aes128gcm=B33e_VeFrOyIHwFTIfmesA 383 9Y1iaZMzICC05DO3y8dWiAAAopoAzpM9l8LHdpDaO9C-UvT4kttTI_edSsHv1o5b 384 lWZ5mBYL 386 Note that the media type has been changed to "application/octet- 387 stream" to avoid exposing information about the content. 388 Alternatively (and equivalently), the Content-Type header field can 389 be omitted. 391 4.2. Encryption with Multiple Records 393 This example shows the same encrypted message, but split into records 394 of 10 octets each. The first record includes a single additional 395 octet of padding, which causes the end of the content to align with a 396 record boundary, forcing the creation of a third record that contains 397 only padding. 399 HTTP/1.1 200 OK 400 Content-Length: 70 401 Content-Encoding: aes128gcm 402 Crypto-Key: keyid="a1"; aes128gcm="BO3ZVPxUlnLORbVGMpbT1Q" 404 _lgOPHdbKmIaLnZC7_8huQAAAAoCYTGkQWUSYylMKzMduBHDCFDwL2oODx8nkh0n 405 uOTNrh48DaWSm02DiQPzQAOGe6xRAeBj588hH6jQRTh_szFRS2Nwx9Aeuiic 407 5. Security Considerations 409 This mechanism assumes the presence of a key management framework 410 that is used to manage the distribution of keys between valid senders 411 and receivers. Defining key management is part of composing this 412 mechanism into a larger application, protocol, or framework. 414 Implementation of cryptography - and key management in particular - 415 can be difficult. For instance, implementations need to account for 416 the potential for exposing keying material on side channels, such as 417 might be exposed by the time it takes to perform a given operation. 418 The requirements for a good implementation of cryptographic 419 algorithms can change over time. 421 5.1. Key and Nonce Reuse 423 Encrypting different plaintext with the same content encryption key 424 and nonce in AES-GCM is not safe [RFC5116]. The scheme defined here 425 uses a fixed progression of nonce values. Thus, a new content 426 encryption key is needed for every application of the content coding. 427 Since input keying material can be reused, a unique "salt" parameter 428 is needed to ensure a content encryption key is not reused. 430 If a content encryption key is reused - that is, if input keying 431 material and salt are reused - this could expose the plaintext and 432 the authentication key, nullifying the protection offered by 433 encryption. Thus, if the same input keying material is reused, then 434 the salt parameter MUST be unique each time. This ensures that the 435 content encryption key is not reused. An implementation SHOULD 436 generate a random salt parameter for every message; a counter could 437 achieve the same result. 439 5.2. Data Encryption Limits 441 There are limits to the data that AEAD_AES_128_GCM can encipher. The 442 maximum value for the record size is limited by the size of the "rs" 443 field in the header (see Section 2.1), which ensures that the 2^36-31 444 limit for a single application of AEAD_AES_128_GCM is not reached 445 [RFC5116]. In order to preserve a 2^-40 probability of 446 indistinguishability under chosen plaintext attack (IND-CPA), the 447 total amount of plaintext that can be enciphered MUST be less than 448 2^44.5 blocks of 16 octets [AEBounds]. 450 If rs is a multiple of 16 octets, this means 398 terabytes can be 451 encrypted safely, including padding. However, if the record size is 452 not a multiple of 16 octets, the total amount of data that can be 453 safely encrypted is reduced proportionally. The worst case is a 454 record size of 3 octets, for which at most 74 terabytes of plaintext 455 can be encrypted, of which at least two-thirds is padding. 457 5.3. Content Integrity 459 This mechanism only provides content origin authentication. The 460 authentication tag only ensures that an entity with access to the 461 content encryption key produced the encrypted data. 463 Any entity with the content encryption key can therefore produce 464 content that will be accepted as valid. This includes all recipients 465 of the same HTTP message. 467 Furthermore, any entity that is able to modify both the Encryption 468 header field and the HTTP message body can replace the contents. 470 Without the content encryption key or the input keying material, 471 modifications to or replacement of parts of a payload body are not 472 possible. 474 5.4. Leaking Information in Headers 476 Because only the payload body is encrypted, information exposed in 477 header fields is visible to anyone who can read the HTTP message. 478 This could expose side-channel information. 480 For example, the Content-Type header field can leak information about 481 the payload body. 483 There are a number of strategies available to mitigate this threat, 484 depending upon the application's threat model and the users' 485 tolerance for leaked information: 487 1. Determine that it is not an issue. For example, if it is 488 expected that all content stored will be "application/json", or 489 another very common media type, exposing the Content-Type header 490 field could be an acceptable risk. 492 2. If it is considered sensitive information and it is possible to 493 determine it through other means (e.g., out of band, using hints 494 in other representations, etc.), omit the relevant headers, and/ 495 or normalize them. In the case of Content-Type, this could be 496 accomplished by always sending Content-Type: application/octet- 497 stream (the most generic media type), or no Content-Type at all. 499 3. If it is considered sensitive information and it is not possible 500 to convey it elsewhere, encapsulate the HTTP message using the 501 application/http media type (Section 8.3.2 of [RFC7230]), 502 encrypting that as the payload of the "outer" message. 504 5.5. Poisoning Storage 506 This mechanism only offers encryption of content; it does not perform 507 authentication or authorization, which still needs to be performed 508 (e.g., by HTTP authentication [RFC7235]). 510 This is especially relevant when a HTTP PUT request is accepted by a 511 server; if the request is unauthenticated, it becomes possible for a 512 third party to deny service and/or poison the store. 514 5.6. Sizing and Timing Attacks 516 Applications using this mechanism need to be aware that the size of 517 encrypted messages, as well as their timing, HTTP methods, URIs and 518 so on, may leak sensitive information. 520 This risk can be mitigated through the use of the padding that this 521 mechanism provides. Alternatively, splitting up content into 522 segments and storing the separately might reduce exposure. HTTP/2 523 [RFC7540] combined with TLS [RFC5246] might be used to hide the size 524 of individual messages. 526 6. IANA Considerations 528 6.1. The "aes128gcm" HTTP Content Coding 530 This memo registers the "aes128gcm" HTTP content coding in the HTTP 531 Content Codings Registry, as detailed in Section 2. 533 o Name: aes128gcm 535 o Description: AES-GCM encryption with a 128-bit content encryption 536 key 538 o Reference: this specification 540 6.2. Crypto-Key Header Field 542 This memo registers the "Crypto-Key" HTTP header field in the 543 Permanent Message Header Registry, as detailed in Section 3. 545 o Field name: Crypto-Key 547 o Protocol: HTTP 549 o Status: Standard 551 o Reference: this specification 553 o Notes: 555 6.3. The HTTP Crypto-Key Parameter Registry 557 This memo establishes a registry for parameters used by the "Crypto- 558 Key" header field under the "Hypertext Transfer Protocol (HTTP) 559 Parameters" grouping. The "Hypertext Transfer Protocol (HTTP) 560 Crypto-Key Parameters" operates under an "Specification Required" 561 policy [RFC5226]. 563 Entries in this registry are expected to include the following 564 information: 566 o Parameter Name: The name of the parameter. 568 o Purpose: A brief description of the purpose of the parameter. 570 o Reference: A reference to a specification that defines the 571 semantics of the parameter. 573 The initial contents of this registry are: 575 6.3.1. keyid 577 o Parameter Name: keyid 579 o Purpose: Identify the key that is in use. 581 o Reference: this document 583 6.3.2. aes128gcm 585 o Parameter Name: aes128gcm 587 o Purpose: Provide an explicit input keying material value for the 588 aes128gcm content coding. 590 o Reference: this document 592 7. References 594 7.1. Normative References 596 [FIPS180-4] 597 Department of Commerce, National., "NIST FIPS 180-4, 598 Secure Hash Standard", March 2012, 599 . 602 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 603 Requirement Levels", BCP 14, RFC 2119, 604 DOI 10.17487/RFC2119, March 1997, 605 . 607 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 608 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 609 . 611 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 612 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 613 DOI 10.17487/RFC5226, May 2008, 614 . 616 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 617 Key Derivation Function (HKDF)", RFC 5869, 618 DOI 10.17487/RFC5869, May 2010, 619 . 621 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 622 Protocol (HTTP/1.1): Message Syntax and Routing", 623 RFC 7230, DOI 10.17487/RFC7230, June 2014, 624 . 626 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 627 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 628 DOI 10.17487/RFC7231, June 2014, 629 . 631 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 632 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 633 2015, . 635 7.2. Informative References 637 [AEBounds] 638 Luykx, A. and K. Paterson, "Limits on Authenticated 639 Encryption Use in TLS", March 2016, 640 . 642 [RFC4880] Callas, J., Donnerhacke, L., Finney, H., Shaw, D., and R. 643 Thayer, "OpenPGP Message Format", RFC 4880, 644 DOI 10.17487/RFC4880, November 2007, 645 . 647 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 648 (TLS) Protocol Version 1.2", RFC 5246, 649 DOI 10.17487/RFC5246, August 2008, 650 . 652 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 653 RFC 5652, DOI 10.17487/RFC5652, September 2009, 654 . 656 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 657 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 658 RFC 7233, DOI 10.17487/RFC7233, June 2014, 659 . 661 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 662 Protocol (HTTP/1.1): Authentication", RFC 7235, 663 DOI 10.17487/RFC7235, June 2014, 664 . 666 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 667 RFC 7516, DOI 10.17487/RFC7516, May 2015, 668 . 670 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 671 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 672 DOI 10.17487/RFC7540, May 2015, 673 . 675 [XMLENC] Eastlake, D., Reagle, J., Hirsch, F., Roessler, T., 676 Imamura, T., Dillaway, B., Simon, E., Yiu, K., and M. 677 Nystroem, "XML Encryption Syntax and Processing", W3C 678 Recommendation REC-xmlenc-core1-20130411 , January 2013, 679 . 681 Appendix A. JWE Mapping 683 The "aes128gcm" content coding can be considered as a sequence of 684 JSON Web Encryption (JWE) objects [RFC7516], each corresponding to a 685 single fixed size record that includes leading padding. The 686 following transformations are applied to a JWE object that might be 687 expressed using the JWE Compact Serialization: 689 o The JWE Protected Header is fixed to the value { "alg": "dir", 690 "enc": "A128GCM" }, describing direct encryption using AES-GCM 691 with a 128-bit content encryption key. This header is not 692 transmitted, it is instead implied by the value of the Content- 693 Encoding header field. 695 o The JWE Encrypted Key is empty, as stipulated by the direct 696 encryption algorithm. 698 o The JWE Initialization Vector ("iv") for each record is set to the 699 exclusive or of the 96-bit record sequence number, starting at 700 zero, and a value derived from the input keying material (see 701 Section 2.3). This value is also not transmitted. 703 o The final value is the concatenated header, JWE Ciphertext, and 704 JWE Authentication Tag, all expressed without base64url encoding. 705 The "." separator is omitted, since the length of these fields is 706 known. 708 Thus, the example in Section 4.1 can be rendered using the JWE 709 Compact Serialization as: 711 eyAiYWxnIjogImRpciIsICJlbmMiOiAiQTEyOEdDTSIgfQ..31iQYc1v4a36EgyJ. 712 AM6TPZfCx3aQ2jvQvlL0-JLb.21Mj951Kwe_WjluVZnmYFgs 714 Where the first line represents the fixed JWE Protected Header, an 715 empty JWE Encrypted Key, and the algorithmically-determined JWE 716 Initialization Vector. The second line contains the encoded body, 717 split into JWE Ciphertext and JWE Authentication Tag. 719 Appendix B. Acknowledgements 721 Mark Nottingham was an original author of this document. 723 The following people provided valuable input: Richard Barnes, David 724 Benjamin, Peter Beverloo, JR Conlin, Mike Jones, Stephen Farrell, 725 Adam Langley, John Mattsson, Julian Reschke, Eric Rescorla, Jim 726 Schaad, and Magnus Westerlund. 728 Author's Address 730 Martin Thomson 731 Mozilla 733 Email: martin.thomson@gmail.com