RFC 8188
Encrypted Content-Encoding for HTTP
Encrypted Content-Encoding for HTTP 🎀
Internet Engineering Task Force (IETF) 🌸 Request for Comments: 8188 💖 Author: M. Thomson, Mozilla ✨ Category: Standards Track 🦋 Date: June 2017 📅 ISSN: 2070-1721
Abstract 💜
okay so this memo adds a new content coding for HTTP 🧚 that lets message payloads be encrypted 🔐. literally the whole point 😭
Status of This Memo 📝
this is an Internet Standards Track document 👑
it's a product of the Internet Engineering Task Force (IETF) 💅. it represents the consensus of the IETF community 🫶, it got public review, and the Internet Engineering Steering Group (IESG) approved it for publication 🎉. if you want more on Internet Standards, check Section 2 of RFC 7841 ✨
info about the current status of this document, any errata, and how to send feedback is at http://www.rfc-editor.org/info/rfc8188 🔗
Copyright Notice ©️
Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved. 🌈
this document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they're in effect on the date of publication 📜. please actually read these, bestie, because they describe your rights and restrictions for this document 🙈. code components pulled out of this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions 💖, and they come without warranty as described in the Simplified BSD License ⚠️
Table of Contents 🗂️
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3
2. The "aes128gcm" HTTP Content Coding . . . . . . . . . . . . . 3
2.1. Encryption Content-Coding Header . . . . . . . . . . . . 5
2.2. Content-Encryption Key Derivation . . . . . . . . . . . . 6
2.3. Nonce Derivation . . . . . . . . . . . . . . . . . . . . 6
3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.1. Encryption of a Response . . . . . . . . . . . . . . . . 7
3.2. Encryption with Multiple Records . . . . . . . . . . . . 8
4. Security Considerations . . . . . . . . . . . . . . . . . . . 8
4.1. Automatic Decryption . . . . . . . . . . . . . . . . . . 9
4.2. Message Truncation . . . . . . . . . . . . . . . . . . . 9
4.3. Key and Nonce Reuse . . . . . . . . . . . . . . . . . . . 9
4.4. Data Encryption Limits . . . . . . . . . . . . . . . . . 10
4.5. Content Integrity . . . . . . . . . . . . . . . . . . . . 10
4.6. Leaking Information in Header Fields . . . . . . . . . . 10
4.7. Poisoning Storage . . . . . . . . . . . . . . . . . . . . 11
4.8. Sizing and Timing Attacks . . . . . . . . . . . . . . . . 11
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
5.1. The "aes128gcm" HTTP Content Coding . . . . . . . . . . . 12
6. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
6.1. Normative References . . . . . . . . . . . . . . . . . . 12
6.2. Informative References . . . . . . . . . . . . . . . . . 13
Appendix A. JWE Mapping . . . . . . . . . . . . . . . . . . . . 15
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 16
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 161. Introduction ✨
sometimes you want to encrypt the contents of an HTTP message (request or response) 🫧 so that when the payload gets stored (for example with an HTTP PUT), only someone holding the right key can read it 🗝️
like, say you need to store a file on a server without that server being able to see what's in it 👀. and that same file could get copied to other servers (so it survives server or network failures 🛟), or downloaded by clients (so it works offline 📴), etc., all without anyone exposing the contents 💅
Transport Layer Security (TLS) [RFC5246] doesn't cover this, bestie 🙃. it only encrypts the channel between the client and the server, so it's not enough for these cases 🚫
this document specifies a content coding (see Section 3.1.2 of [RFC7231]) for HTTP that handles these and other use cases 🎀
this content coding is NOT a straight copy of message-based encryption formats, like the ones described in [RFC4880], [RFC5652], [RFC7516], and [XMLENC] 🙅♀️. those formats don't play nicely with stream processing, and HTTP needs that 🌊. the format here sits closer to the lower-level constructs described in [RFC5116] 🧩
to the extent that message-based formats use the same primitives, this format can be thought of as a sequence of encrypted messages with a particular profile 🦋. for instance, Appendix A explains how the format lines up with a sequence of JSON Web Encryption [RFC7516] values that have a fixed header 📦
this mechanism is probably just a small piece of a bigger design that uses content encryption 🧸. how clients and servers get and identify keys depends on the use case 🔑. and yes, a key management system is not described here 🙈
1.1. Requirements Language 📚
the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here 💜
2. The "aes128gcm" HTTP Content Coding 🔐
the "aes128gcm" HTTP content coding says that a payload was encrypted using Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM), which is identified as AEAD_AES_128_GCM in [RFC5116], Section 5.1 🌸. the AEAD_AES_128_GCM algorithm uses a 128-bit content-encryption key 🗝️
using this content coding means you need to know a key 🔑. how you get that key isn't defined in this document 🤷♀️
the "aes128gcm" content coding uses one single fixed set of encryption primitives 🧱. cipher agility happens by defining a brand new content-coding scheme instead 💅. this way, only the HTTP Accept-Encoding header field is needed to negotiate whether encryption is used 🙌
the "aes128gcm" content coding also uses a fixed record size 📏. the final encoding is made of a header (see Section 2.1) and zero or more fixed-size encrypted records 🧁, and the final record can be smaller than the record size 🍰
the record size decides how long each chunk of plaintext that gets enciphered is 🪄. the record size ("rs") is included in the content-coding header (see Section 2.1) 🎀
here's the record layout: 🧩
+-----------+ content
| data | any length up to rs-17 octets
+-----------+
|
v
+-----------+-----+ add a delimiter octet (0x01 or 0x02)
| data | pad | then 0x00-valued octets to rs-16
+-----------+-----+ (or less on the last record)
|
v
+--------------------+ encrypt with AEAD_AES_128_GCM;
| ciphertext | final size is rs;
+--------------------+ the last record can be smallerAEAD_AES_128_GCM makes ciphertext that's 16 octets longer than its input plaintext 🧵. so the unencrypted content of each record is 16 octets shorter than the record size 🫧. valid records always have at least a padding delimiter octet and a 16-octet authentication tag 💖
each record has one padding delimiter octet, then any number of zero octets 🌷. the last record uses a padding delimiter octet set to the value 2 🛑, and every other record has a padding delimiter octet value of 1 ✅
when decrypting, the padding delimiter is the last non-zero-valued octet of the record 🔍. a decrypter MUST fail if the record has no non-zero octet at all 💀. a decrypter MUST fail if the last record has a padding delimiter with a value other than 2, or if any record other than the last has a padding delimiter with a value other than 1 🚨
the nonce for each record is a 96-bit value built from the record sequence number and the input-keying material 🔢. nonce derivation is covered in Section 2.3 🧠
the additional data passed to each AEAD_AES_128_GCM invocation is a zero-length octet sequence 🫙
here's the big consequence of this record structure 🌈: range requests [RFC7233] and random access to encrypted payload bodies are possible at the granularity of the record size 📍. partial records at the ends of a range can't be decrypted 🙅♀️. so it's best if range requests start and end on record boundaries ✂️. just note that random access to specific parts of encrypted data could get confused by the presence of padding 🌀
picking the right record size is a trade-off ⚖️. a smaller record size lets decrypted octets get released faster, which is great for apps that care about responsiveness ⚡. smaller records also cut down on the extra data you need if you want random access into the ciphertext 🎯
apps that don't care about streaming, random access, or arbitrary padding can use larger records, or even a single record 🛸. a larger record size means less processing and less data overhead 🏋️♀️
2.1. Encryption Content-Coding Header 🎀
the content coding uses a header block with every parameter needed to decrypt the content (except the key) 📦. the header block goes in the body of a message, right ahead of the sequence of records 💌
+-----------+--------+-----------+---------------+
| salt (16) | rs (4) | idlen (1) | keyid (idlen) |
+-----------+--------+-----------+---------------+salt: this parameter is the first 16 octets of the "aes128gcm" content-coding header 🧂. the samesaltvalue MUST NOT be reused for two different payload bodies that have the same input-keying material 🚫. generating a random salt for every application of the content coding makes content-encryption key reuse highly unlikely 🎲rs: the "rs" (record size) parameter is an unsigned 32-bit integer in network byte order, and it describes the record size in octets 📐. note that this means it's impossible to go past the 2^36-31 limit on plaintext input to AEAD_AES_128_GCM 🧮. values smaller than 18 are invalid ❌idlen: the "idlen" parameter is an unsigned 8-bit integer that defines the length of the "keyid" parameter 🔢keyid: the "keyid" parameter can be used to identify the keying material being used 🗝️. this field is as long as the "idlen" parameter says ✅. recipients that receive a message are expected to know how to retrieve keys, and the "keyid" parameter might be input to that process 🕵️♀️. a "keyid" parameter SHOULD be a UTF-8-encoded [RFC3629] string, especially when the identifier might need to be shown in textual form 💖
2.2. Content-Encryption Key Derivation 🔑
okay so, to let the same keying material get reused across lots of different HTTP messages, every message gets its own content-encryption key 💅 The key is derived from the salt parameter using the HMAC-based key derivation function (HKDF) from [RFC5869], with the SHA-256 hash algorithm [FIPS180-4]. bestie, this is giving reuse without the drama ✨
The value of the salt parameter is the salt input to the HKDF. The keying material named by the keyid parameter is the input-keying material (IKM) to HKDF. The input-keying material is expected to be handed to recipients separately 🫶 So the extract phase of HKDF makes a pseudorandom key (PRK) like this:
PRK = HMAC-SHA-256 (salt, IKM)The info parameter to HKDF is the ASCII-encoded string "Content-Encoding: aes128gcm" plus one zero octet 🌸
cek_info = "Content-Encoding: aes128gcm" || 0x00Note(1): Concatenation of octet sequences is written with the "||" operator.
Note(2): The strings used here and in Section 2.3 don't include a terminating 0x00 octet, even though some programming languages add one 🙈
AEAD_AES_128_GCM needs a 16-octet (128-bit) content-encryption key (CEK), so the length (L) parameter to HKDF is 16 💖 That means the second step of HKDF can be simplified to the first 16 octets of a single HMAC, which is so clean 🧚
CEK = HMAC-SHA-256(PRK, cek_info || 0x01)2.3. Nonce Derivation 🌈
The nonce input to AEAD_AES_128_GCM gets built for each record ✨ The nonce for each record is a 12-octet (96-bit) value derived from the record sequence number, the input-keying material, and the salt parameter. main character energy!
The input-keying material and the salt parameter go into HKDF with different info and length (L) parameters 🦋 The length (L) parameter is 12 octets. The info parameter for the nonce is the ASCII-encoded string "Content-Encoding: nonce", ending with a single zero octet:
nonce_info = "Content-Encoding: nonce" || 0x00The result gets combined with the record sequence number using exclusive or to make the nonce. The record sequence number (SEQ) is a 96-bit unsigned integer in network byte order, and it starts at zero 🔥
So the final nonce for each record is a 12-octet value:
NONCE = HMAC-SHA-256(PRK, nonce_info || 0x01) XOR SEQThis nonce construction prevents removal or reordering of records. iykyk, and this part is seriously iconic 👑
3. Examples 🎀
This section has a few examples of the encrypted-content coding. Let's gooo 💅
Note: All binary values in the examples in this section use base64 encoding with the URL and filename safe alphabet [RFC4648]. That includes the bodies of requests. Whitespace and line wrapping get added to fit formatting constraints 🍓
3.1. Encryption of a Response 💌
Here, a successful HTTP GET response has been encrypted. It uses a record size of 4096 octets and no padding (just the single-octet padding delimiter), so only a partial record is present ✨ The input-keying material is identified by an empty string, which means the keyid field in the header is zero octets long 🙈
The encrypted data in this example is the UTF-8-encoded string "I am the walrus" 🦭 The input-keying material is the value "yqdlZ-tYemfogSmv7Ws5PQ" (in base64url). The 54-octet content body holds a single record and is shown using 71 base64url characters, purely for presentation reasons 💜
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Length: 54
Content-Encoding: aes128gcm
I1BsxtFttlv3u_Oo94xnmwAAEAAA-NAVub2qFgBEuQKRapoZu-IxkIva3MEB1PD-
ly8ThjgThe media type got changed to "application/octet-stream" so we don't expose info about the content 🦋 Alternatively (and equivalently), the Content-Type header field can be left out entirely 🫶
Here are the intermediate values for this example, all in base64url:
salt (from header) = I1BsxtFttlv3u_Oo94xnmw
PRK = zyeH5phsIsgUyd4oiSEIy35x-gIi4aM7y0hCF8mwn9g
CEK = _wniytB-ofscZDh4tbSjHw
NONCE = Bcs8gkIRKLI8GeI8
unencrypted data = SSBhbSB0aGUgd2FscnVzAg3.2. Encryption with Multiple Records 🧁
This example shows the same message with input-keying material of "BO3ZVPxUlnLORbVGMpbT1Q" ✨ Here the plaintext is split into records of 25 octets each (so the rs field in the header is 25). The first record includes one 0x00 padding octet, which means there are 7 octets of message in the first record and 8 in the second 🌈 A key identifier of the UTF-8-encoded string "a1" is also included in the header 🔑
HTTP/1.1 200 OK
Content-Length: 73
Content-Encoding: aes128gcm
uNCkWiNYzKTnBN9ji3-qWAAAABkCYTHOG8chz_gnvgOqdGYovxyjuqRyJFjEDyoF
1Fvkj6hQPdPHI51OEUKEpgz3SsLWIqS_uA4. Security Considerations 🚨
Okay bestie, this part is seriously important. Key management and crypto are tricky, so read every line 🙏
This mechanism assumes there's a key management framework in place to handle distributing keys between valid senders and receivers 🗝️ Defining key management is part of composing this mechanism into a larger application, protocol, or framework.
Implementing cryptography is hard, and key management especially so 😭 Implementations need to account for the chance of exposing keying material on side channels, such as what might leak through the time it takes to perform a given operation. The requirements for a good implementation of cryptographic algorithms can change over time, so stay alert 👀
4.1. Automatic Decryption 🤖
As a content coding, an "aes128gcm" content coding might get automatically removed by a receiver in a way that isn't obvious to the ultimate consumer of a message 😳 Recipients that depend on content-origin authentication using this mechanism MUST reject messages that don't include the "aes128gcm" content coding. no exceptions, periodt 💅
4.2. Message Truncation ✂️
This content encoding is designed to permit incremental processing of large messages 🍰 It also permits random access to plaintext in a limited fashion. The content encoding lets a receiver detect when a message has been truncated 🔍
A partially delivered message MUST NOT be processed as though the entire message was successfully delivered 🙅♀️ For instance, a partially delivered message cannot be cached as though it were complete.
An attacker might exploit a willingness to process partial messages to keep a receiver stuck in a specific intermediate state 😈 Implementations that process partial messages need to make sure that any intermediate processing states don't give an attacker an advantage.
4.3. Key and Nonce Reuse 🔁
Encrypting different plaintext with the same content-encryption key and nonce in AES-GCM is not safe [RFC5116] 💀 The scheme defined here uses a fixed progression of nonce values. So a new content-encryption key is needed for every application of the content coding. Since input-keying material can be reused, a unique salt parameter is needed to make sure a content-encryption key isn't reused 🫶
If a content-encryption key is reused (that is, if input-keying material and the salt parameter are both reused), this could expose the plaintext and the authentication key, which cancels out the protection that encryption offers 😱 So, if the same input-keying material is reused, the salt parameter MUST be unique each time. This makes sure the content-encryption key isn't reused. An implementation SHOULD generate a random salt parameter for every message 🎲
4.4. Data Encryption Limits 📏
There are limits to the data that AEAD_AES_128_GCM can encipher 🙃 The maximum value for the record size is limited by the size of the rs field in the header (see Section 2.1). That keeps the 2^36-31 limit for a single application of AEAD_AES_128_GCM from being reached [RFC5116]. To preserve a 2^-40 probability of indistinguishability under chosen plaintext attack (IND-CPA), the total amount of plaintext that can be enciphered with the key derived from the same input-keying material and salt MUST be less than 2^44.5 blocks of 16 octets [AEBounds] 🧮
If the record size is a multiple of 16 octets, then 398 terabytes can be encrypted safely, padding and overhead included 🌊 However, if the record size isn't a multiple of 16 octets, the total amount of data that can be safely encrypted goes down, because partial AES blocks get encrypted. The worst case is a record size of 18 octets, where at most 74 terabytes of plaintext can be encrypted, and at least half of that is padding 😭
4.5. Content Integrity 🛡️
This mechanism only provides content-origin authentication. The authentication tag only makes sure that an entity with access to the content-encryption key produced the encrypted data 🔐
So, any entity with the content-encryption key can produce content that will be accepted as valid. That includes all recipients of the same HTTP message 👯
Furthermore, any entity that can modify both the Content-Encoding header field and the HTTP message body can replace the contents 🙀 Without the content-encryption key or the input-keying material, modifying or replacing parts of a payload body isn't possible 💖
4.6. Leaking Information in Header Fields 👀
Because only the payload body is encrypted, information in header fields is visible to anyone who can read the HTTP message 📭 This could expose side-channel information.
For example, the Content-Type header field can leak information about the payload body 🫣
There are a number of strategies to mitigate this threat, depending on the application's threat model and the users' tolerance for leaked information:
- Determine that it isn't an issue. For example, if all stored content is expected to be "application/json", or another very common media type, exposing the Content-Type header field could be an acceptable risk 🙌
- If it's considered sensitive information and it's possible to determine it through other means (e.g., out of band, or using hints in other representations), omit the relevant headers, and/or normalize them. For Content-Type, that could mean always sending
Content-Type: application/octet-stream(the most generic media type), or no Content-Type at all 🎭 - If it's considered sensitive information and it's not possible to convey it elsewhere, encapsulate the HTTP message using the application/http media type (see Section 8.3.2 of [RFC7230]), encrypting that as the payload of the "outer" message 🥷
4.7. Poisoning Storage 🧪
This mechanism only offers data-origin authentication. It does not perform authentication or authorization of the message creator, which could still need to be done (e.g., by HTTP authentication [RFC7235]) 🙅♀️
This is especially relevant when an HTTP PUT request is accepted by a server without decrypting the payload. If the request is unauthenticated, a third party can deny service and/or poison the store 😤
4.8. Sizing and Timing Attacks 🦋
Okay bestie, this one is important 😭. Apps using this mechanism have to be aware that the size of encrypted messages, plus their timing, HTTP methods, URIs and so on, can leak sensitive info. Check out [NETFLIX] or [CLINIC] if you want the receipts 🙈.
The good news is that the padding this mechanism gives you can help reduce that risk 💅. Splitting content into segments and storing them separately might also cut down exposure 🧩. And HTTP/2 [RFC7540] combined with TLS [RFC5246] might be used to hide the size of individual messages 🔒.
Padding strategy is genuinely hard 😩. A good one can depend on context. Common strategies include padding to a small set of fixed lengths, padding to multiples of a value, or padding to powers of 2 🌸. Even a good strategy can still leak size info if someone can observe the recipient's processing activity 👀. This is especially true if the trailing records of a message contain only padding ⚠️. Distributing non-padding data across records is recommended to avoid leaking size information 🍓.
5. IANA Considerations 📋
5.1. The "aes128gcm" HTTP Content Coding 💜
This memo registers the "aes128gcm" HTTP content coding in the "HTTP Content Coding Registry", as detailed in Section 2 ✨.
- Name:
aes128gcm - Description: AES-GCM encryption with a 128-bit content-encryption key
- Reference: this specification
6. References 📚
Here's the full reference list, copied exactly as written 🫶.
6.1. Normative References
[FIPS180-4]
National Institute of Standards and Technology, "Secure
Hash Standard (SHS)", FIPS PUB 180-4,
DOI 10.6028/NIST.FIPS180-4, August 2015,
<http://nvlpubs.nist.gov/nistpubs/FIPS/
NIST.FIPS.180-4.pdf>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
2003, <http://www.rfc-editor.org/info/rfc3629>.
[RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated
Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008,
<http://www.rfc-editor.org/info/rfc5116>.
[RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand
Key Derivation Function (HKDF)", RFC 5869,
DOI 10.17487/RFC5869, May 2010,
<http://www.rfc-editor.org/info/rfc5869>.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Message Syntax and Routing",
RFC 7230, DOI 10.17487/RFC7230, June 2014,
<http://www.rfc-editor.org/info/rfc7230>.
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
DOI 10.17487/RFC7231, June 2014,
<http://www.rfc-editor.org/info/rfc7231>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <http://www.rfc-editor.org/info/rfc8174>.6.2. Informative References
[AEBounds] Luykx, A. and K. Paterson, "Limits on Authenticated
Encryption Use in TLS", March 2016,
<http://www.isg.rhul.ac.uk/~kp/TLS-AEbounds.pdf>.
[CLINIC] Miller, B., Huang, L., Joseph, A., and J. Tygar, "I Know
Why You Went to the Clinic: Risks and Realization of HTTPS
Traffic Analysis", DOI 10.1007/978-3-319-08506-7_8, March
2014, <https://arxiv.org/abs/1403.0297>.
[NETFLIX] Reed, A. and M. Kranch, "Identifying HTTPS-Protected
Netflix Videos in Real-Time", Proceedings of the Seventh
ACM on Conference on Data and Application Security and
Privacy CODASPY '17, DOI 10.1145/3029806.3029821, 2017.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<http://www.rfc-editor.org/info/rfc4648>.
[RFC4880] Callas, J., Donnerhacke, L., Finney, H., Shaw, D., and R.
Thayer, "OpenPGP Message Format", RFC 4880,
DOI 10.17487/RFC4880, November 2007,
<http://www.rfc-editor.org/info/rfc4880>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246,
DOI 10.17487/RFC5246, August 2008,
<http://www.rfc-editor.org/info/rfc5246>.
[RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70,
RFC 5652, DOI 10.17487/RFC5652, September 2009,
<http://www.rfc-editor.org/info/rfc5652>.
[RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed.,
"Hypertext Transfer Protocol (HTTP/1.1): Range Requests",
RFC 7233, DOI 10.17487/RFC7233, June 2014,
<http://www.rfc-editor.org/info/rfc7233>.
[RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Authentication", RFC 7235,
DOI 10.17487/RFC7235, June 2014,
<http://www.rfc-editor.org/info/rfc7235>.
[RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
RFC 7516, DOI 10.17487/RFC7516, May 2015,
<http://www.rfc-editor.org/info/rfc7516>.
[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
DOI 10.17487/RFC7540, May 2015,
<http://www.rfc-editor.org/info/rfc7540>.
[XMLENC] Eastlake, D., Reagle, J., Hirsch, F., and T. Roessler,
"XML Encryption Syntax and Processing Version 1.1", World
Wide Web Consortium Recommendation
REC-xmlenc-core1-20130411, April 2013,
<http://www.w3.org/TR/2013/REC-xmlenc-core1-20130411>.Appendix A. JWE Mapping 🧁
The "aes128gcm" content coding can be considered as a sequence of JSON Web Encryption (JWE) [RFC7516] objects 🎀. Each one corresponds to a single fixed-size record that includes trailing padding. These transformations get applied to a JWE object that might be expressed using the JWE Compact Serialization:
- The JWE Protected Header is fixed to the value
{ "alg": "dir", "enc": "A128GCM" }, describing direct encryption using AES-GCM with a 128-bit content-encryption key. This header is not transmitted. It's instead implied by the value of the Content-Encoding header field 🕵️♀️. - The JWE Encrypted Key is empty, as stipulated by the direct encryption algorithm.
- The JWE Initialization Vector ("iv") for each record is set to the exclusive-or of the 96-bit record sequence number, starting at zero, and a value derived from the input-keying material (see Section 2.3). This value is also not transmitted.
- The final value is the concatenated header, JWE Ciphertext, and JWE Authentication Tag, all expressed without base64url encoding. The "." separator is omitted, since the length of these fields is known.
So the example in Section 3.1 can be rendered using the JWE Compact Serialization like this 🦋:
eyAiYWxnIjogImRpciIsICJlbmMiOiAiQTEyOEdDTSIgfQ..Bcs8gkIRKLI8GeI8.
-NAVub2qFgBEuQKRapoZuw.4jGQi9rcwQHU8P6XLxOGOAThe first line represents the fixed JWE Protected Header, an empty JWE Encrypted Key, and the algorithmically determined JWE Initialization Vector. The second line contains the encoded body, split into JWE Ciphertext and JWE Authentication Tag 💖.
Acknowledgements 🫶
Mark Nottingham was an original author of this document ✨.
The following people provided valuable input: Richard Barnes, David Benjamin, Peter Beverloo, JR Conlin, Mike Jones, Stephen Farrell, Adam Langley, James Manger, John Mattsson, Julian Reschke, Eric Rescorla, Jim Schaad, and Magnus Westerlund 👑.
Author's Address 💌
Martin Thomson Mozilla
Email: martin.thomson@gmail.com
📦 where this page comes from
- ietf: rfc8188 2017-06
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms