< draft-ietf-jose-json-web-encryption-09.txt   draft-ietf-jose-json-web-encryption-10.txt >
JOSE Working Group M. Jones JOSE Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track E. Rescorla Intended status: Standards Track E. Rescorla
Expires: October 25, 2013 RTFM Expires: October 27, 2013 RTFM
J. Hildebrand J. Hildebrand
Cisco Cisco
April 23, 2013 April 25, 2013
JSON Web Encryption (JWE) JSON Web Encryption (JWE)
draft-ietf-jose-json-web-encryption-09 draft-ietf-jose-json-web-encryption-10
Abstract Abstract
JSON Web Encryption (JWE) is a means of representing encrypted JSON Web Encryption (JWE) is a means of representing encrypted
content using JavaScript Object Notation (JSON) data structures. content using JavaScript Object Notation (JSON) data structures.
Cryptographic algorithms and identifiers for use with this Cryptographic algorithms and identifiers for use with this
specification are described in the separate JSON Web Algorithms (JWA) specification are described in the separate JSON Web Algorithms (JWA)
specification. Related digital signature and MAC capabilities are specification. Related digital signature and MAC capabilities are
described in the separate JSON Web Signature (JWS) specification. described in the separate JSON Web Signature (JWS) specification.
skipping to change at page 1, line 38 skipping to change at page 1, line 38
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on October 25, 2013. This Internet-Draft will expire on October 27, 2013.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 41 skipping to change at page 2, line 41
4.1.11. "typ" (Type) Header Parameter . . . . . . . . . . . . 15 4.1.11. "typ" (Type) Header Parameter . . . . . . . . . . . . 15
4.1.12. "cty" (Content Type) Header Parameter . . . . . . . . 15 4.1.12. "cty" (Content Type) Header Parameter . . . . . . . . 15
4.1.13. "apu" (Agreement PartyUInfo) Header Parameter . . . . 15 4.1.13. "apu" (Agreement PartyUInfo) Header Parameter . . . . 15
4.1.14. "apv" (Agreement PartyVInfo) Header Parameter . . . . 16 4.1.14. "apv" (Agreement PartyVInfo) Header Parameter . . . . 16
4.1.15. "crit" (Critical) Header Parameter . . . . . . . . . . 16 4.1.15. "crit" (Critical) Header Parameter . . . . . . . . . . 16
4.2. Public Header Parameter Names . . . . . . . . . . . . . . 16 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 16
4.3. Private Header Parameter Names . . . . . . . . . . . . . . 16 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 16
5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 17 5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 17
5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 17 5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 17
5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 19 5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 19
5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 20 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 21
6. Encrypting JWEs with Cryptographic Algorithms . . . . . . . . 21 6. Encrypting JWEs with Cryptographic Algorithms . . . . . . . . 21
6.1. CEK Encryption . . . . . . . . . . . . . . . . . . . . . . 21 6.1. CEK Encryption . . . . . . . . . . . . . . . . . . . . . . 22
7. JSON Serialization . . . . . . . . . . . . . . . . . . . . . . 21 7. JSON Serialization . . . . . . . . . . . . . . . . . . . . . . 22
7.1. Example JWE-JS . . . . . . . . . . . . . . . . . . . . . . 23 7.1. Example JWE-JS . . . . . . . . . . . . . . . . . . . . . . 23
8. Implementation Considerations . . . . . . . . . . . . . . . . 24 8. Implementation Considerations . . . . . . . . . . . . . . . . 25
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25
9.1. Registration of JWE Header Parameter Names . . . . . . . . 24 9.1. Registration of JWE Header Parameter Names . . . . . . . . 25
9.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 24 9.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 25
9.2. JSON Web Signature and Encryption Type Values 9.2. JSON Web Signature and Encryption Type Values
Registration . . . . . . . . . . . . . . . . . . . . . . . 26 Registration . . . . . . . . . . . . . . . . . . . . . . . 27
9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 26 9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 27
9.3. Media Type Registration . . . . . . . . . . . . . . . . . 26 9.3. Media Type Registration . . . . . . . . . . . . . . . . . 27
9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 26 9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 27
10. Security Considerations . . . . . . . . . . . . . . . . . . . 28 10. Security Considerations . . . . . . . . . . . . . . . . . . . 29
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29
11.1. Normative References . . . . . . . . . . . . . . . . . . . 28 11.1. Normative References . . . . . . . . . . . . . . . . . . . 29
11.2. Informative References . . . . . . . . . . . . . . . . . . 30 11.2. Informative References . . . . . . . . . . . . . . . . . . 31
Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 30 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 31
A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 31 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 31
A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 31 A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 32
A.1.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 31 A.1.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 32
A.1.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 31 A.1.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 32
A.1.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 31 A.1.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 32
A.1.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 34 A.1.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 35
A.1.6. Initialization Vector . . . . . . . . . . . . . . . . 34 A.1.6. Initialization Vector . . . . . . . . . . . . . . . . 35
A.1.7. Additional Authenticated Data Parameter . . . . . . . 34 A.1.7. Additional Authenticated Data Parameter . . . . . . . 35
A.1.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 35 A.1.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 36
A.1.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 35 A.1.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 36
A.1.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 36 A.1.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 37
A.1.11. Complete Representation . . . . . . . . . . . . . . . 36 A.1.11. Complete Representation . . . . . . . . . . . . . . . 37
A.1.12. Validation . . . . . . . . . . . . . . . . . . . . . . 36 A.1.12. Validation . . . . . . . . . . . . . . . . . . . . . . 37
A.2. Example JWE using RSAES-PKCS1-V1_5 and A.2. Example JWE using RSAES-PKCS1-V1_5 and
AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 36 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 37
A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 37 A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 38
A.2.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 37 A.2.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 38
A.2.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 37 A.2.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 38
A.2.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 37 A.2.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 38
A.2.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 40 A.2.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 41
A.2.6. Initialization Vector . . . . . . . . . . . . . . . . 40 A.2.6. Initialization Vector . . . . . . . . . . . . . . . . 41
A.2.7. Additional Authenticated Data Parameter . . . . . . . 40 A.2.7. Additional Authenticated Data Parameter . . . . . . . 41
A.2.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 41 A.2.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 42
A.2.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 41 A.2.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 42
A.2.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 42 A.2.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 43
A.2.11. Complete Representation . . . . . . . . . . . . . . . 42 A.2.11. Complete Representation . . . . . . . . . . . . . . . 43
A.2.12. Validation . . . . . . . . . . . . . . . . . . . . . . 42 A.2.12. Validation . . . . . . . . . . . . . . . . . . . . . . 43
A.3. Example JWE using AES Key Wrap and AES GCM . . . . . . . . 42 A.3. Example JWE using AES Key Wrap and AES GCM . . . . . . . . 43
A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 43 A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 44
A.3.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 43 A.3.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 44
A.3.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 43 A.3.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 44
A.3.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 43 A.3.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 44
A.3.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 44 A.3.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 45
A.3.6. Initialization Vector . . . . . . . . . . . . . . . . 44 A.3.6. Initialization Vector . . . . . . . . . . . . . . . . 45
A.3.7. Additional Authenticated Data Parameter . . . . . . . 44 A.3.7. Additional Authenticated Data Parameter . . . . . . . 45
A.3.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 44 A.3.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 45
A.3.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 45 A.3.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 46
A.3.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 45 A.3.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 46
A.3.11. Complete Representation . . . . . . . . . . . . . . . 45 A.3.11. Complete Representation . . . . . . . . . . . . . . . 46
A.3.12. Validation . . . . . . . . . . . . . . . . . . . . . . 45 A.3.12. Validation . . . . . . . . . . . . . . . . . . . . . . 46
Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 46 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 47
B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 46 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 47
B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 46 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 47
B.3. Create 64 Bit Big Endian Representation of AAD Length . . 47 B.3. Create 64 Bit Big Endian Representation of AAD Length . . 48
B.4. Initialization Vector Value . . . . . . . . . . . . . . . 47 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 48
B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 47 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 48
B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 48 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 49
B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 48 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 49
Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 48 Appendix C. Possible Compact Serialization for Multiple
Appendix D. Document History . . . . . . . . . . . . . . . . . . 49 Recipients . . . . . . . . . . . . . . . . . . . . . 49
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 54 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 50
Appendix E. Document History . . . . . . . . . . . . . . . . . . 51
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 56
1. Introduction 1. Introduction
JSON Web Encryption (JWE) is a compact encryption format intended for JSON Web Encryption (JWE) is a compact encryption format intended for
space constrained environments such as HTTP Authorization headers and space constrained environments such as HTTP Authorization headers and
URI query parameters. It represents this content using JavaScript URI query parameters. It represents this content using JavaScript
Object Notation (JSON) [RFC4627] based data structures. The JWE Object Notation (JSON) [RFC4627] based data structures. The JWE
cryptographic mechanisms encrypt and provide integrity protection for cryptographic mechanisms encrypt and provide integrity protection for
arbitrary sequences of octets. arbitrary sequences of octets.
skipping to change at page 18, line 20 skipping to change at page 18, line 20
11. Serialize the (compressed) Plaintext into an octet sequence M. 11. Serialize the (compressed) Plaintext into an octet sequence M.
12. Create a JWE Header containing the encryption parameters used. 12. Create a JWE Header containing the encryption parameters used.
Note that white space is explicitly allowed in the Note that white space is explicitly allowed in the
representation and no canonicalization need be performed before representation and no canonicalization need be performed before
encoding. encoding.
13. Base64url encode the octets of the UTF-8 representation of the 13. Base64url encode the octets of the UTF-8 representation of the
JWE Header to create the Encoded JWE Header. JWE Header to create the Encoded JWE Header.
14. Let the Additional Authenticated Data value be the octets of the 14. If the JWE JSON Serialization is being used, repeat this process
ASCII representation of the concatenation of the Encoded JWE for each recipient.
Header, a period ('.') character, and the Encoded JWE Encrypted
Key.
15. Encrypt M using the CEK, the JWE Initialization Vector, and the 15. Let the value X be the concatenation of the Encoded JWE Header
values computed above, with a tilde ('~') character between each
Encoded JWE Header value. (In the single recipient case, X is
simply the single Encoded JWE Header value.)
16. Let the value Y be the concatenation of the Encoded JWE
Encrypted Key values computed above, with a tilde ('~')
character between each Encoded JWE Encrypted Key value. The
order of the Encoded JWE Encrypted Key values MUST be the same
as the order of the corresponding Encoded JWE Header values in
the previous step. (In the single recipient case, Y is simply
the single Encoded JWE Encrypted Key value.)
17. Let the Additional Authenticated Data value be the octets of the
ASCII representation of the concatenation of X, a period ('.')
character, and Y.
18. Encrypt M using the CEK, the JWE Initialization Vector, and the
Additional Authenticated Data value using the specified block Additional Authenticated Data value using the specified block
encryption algorithm to create the JWE Ciphertext value and the encryption algorithm to create the JWE Ciphertext value and the
JWE Authentication Tag (which is the Authentication Tag output JWE Authentication Tag (which is the Authentication Tag output
from the calculation). from the encryption operation).
16. Base64url encode the JWE Ciphertext to create the Encoded JWE 19. Base64url encode the JWE Ciphertext to create the Encoded JWE
Ciphertext. Ciphertext.
17. Base64url encode the JWE Authentication Tag to create the 20. Base64url encode the JWE Authentication Tag to create the
Encoded JWE Authentication Tag. Encoded JWE Authentication Tag.
18. The five encoded parts are the result values used in both the 21. The five encoded parts are the result values used in both the
JWE Compact Serialization and the JWE JSON Serialization JWE Compact Serialization and the JWE JSON Serialization
representations. representations.
19. If the JWE JSON Serialization is being used, repeat this process 22. Create the desired serialized output. The JWE Compact
for each recipient.
20. Create the desired serialized output. The JWE Compact
Serialization of this result is the concatenation of the Encoded Serialization of this result is the concatenation of the Encoded
JWE Header, the Encoded JWE Encrypted Key, the Encoded JWE JWE Header, the Encoded JWE Encrypted Key, the Encoded JWE
Initialization Vector, the Encoded JWE Ciphertext, and the Initialization Vector, the Encoded JWE Ciphertext, and the
Encoded JWE Authentication Tag in that order, with the five Encoded JWE Authentication Tag in that order, with the five
strings being separated by four period ('.') characters. The strings being separated by four period ('.') characters. The
JWE JSON Serialization is described in Section 7. JWE JSON Serialization is described in Section 7.
5.2. Message Decryption 5.2. Message Decryption
The message decryption process is the reverse of the encryption The message decryption process is the reverse of the encryption
skipping to change at page 19, line 49 skipping to change at page 20, line 12
7. When Direct Key Agreement or Key Agreement with Key Wrapping are 7. When Direct Key Agreement or Key Agreement with Key Wrapping are
employed, use the key agreement algorithm to compute the value employed, use the key agreement algorithm to compute the value
of the agreed upon key. When Direct Key Agreement is employed, of the agreed upon key. When Direct Key Agreement is employed,
let the Content Encryption Key (CEK) be the agreed upon key. let the Content Encryption Key (CEK) be the agreed upon key.
When Key Agreement with Key Wrapping is employed, the agreed When Key Agreement with Key Wrapping is employed, the agreed
upon key will be used to decrypt the JWE Encrypted Key. upon key will be used to decrypt the JWE Encrypted Key.
8. When Key Wrapping, Key Encryption, or Key Agreement with Key 8. When Key Wrapping, Key Encryption, or Key Agreement with Key
Wrapping are employed, decrypt the JWE Encrypted Key to produce Wrapping are employed, decrypt the JWE Encrypted Key to produce
the Content Encryption Key (CEK). The CEK MUST have a length the Content Encryption Key (CEK). The CEK MUST have a length
equal to that required for the block encryption algorithm. To equal to that required for the block encryption algorithm. Note
that when there are multiple recipients, each recipient will
only be able decrypt any JWE Encrypted Key values that were
encrypted to a key in that recipient's possession. It is
therefore normal to only be able to decrypt one of the per-
recipient JWE Encrypted Key values to obtain the CEK value. To
mitigate against attacks described in RFC 3218 [RFC3218], the mitigate against attacks described in RFC 3218 [RFC3218], the
recipient MUST NOT distinguish between format, padding, and recipient MUST NOT distinguish between format, padding, and
length errors of encrypted keys. It is strongly recommended, in length errors of encrypted keys. It is strongly recommended, in
the event of receiving an improperly formatted key, that the the event of receiving an improperly formatted key, that the
receiver substitute a randomly generated CEK and proceed to the receiver substitute a randomly generated CEK and proceed to the
next step, to mitigate timing attacks. next step, to mitigate timing attacks.
9. Otherwise, when Direct Key Agreement or Direct Encryption are 9. Otherwise, when Direct Key Agreement or Direct Encryption are
employed, verify that the JWE Encrypted Key value is empty octet employed, verify that the JWE Encrypted Key value is empty octet
sequence. sequence.
10. When Direct Encryption is employed, let the Content Encryption 10. When Direct Encryption is employed, let the Content Encryption
Key (CEK) be the shared symmetric key. Key (CEK) be the shared symmetric key.
11. Let the Additional Authenticated Data value be the octets of the 11. If the JWE JSON Serialization is being used, repeat this process
ASCII representation of the concatenation of the Encoded JWE for each recipient contained in the representation.
Header, a period ('.') character, and the Encoded JWE Encrypted
Key.
12. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 12. Let the value X be the concatenation of the Encoded JWE Header
values identified above, with a tilde ('~') character between
each Encoded JWE Header value. (In the single recipient case, X
is simply the single Encoded JWE Header value.)
13. Let the value Y be the concatenation of the Encoded JWE
Encrypted Key values identified above, with a tilde ('~')
character between each Encoded JWE Encrypted Key value. The
order of the Encoded JWE Encrypted Key values MUST be the same
as the order of the corresponding Encoded JWE Header values in
the previous step. (In the single recipient case, Y is simply
the single Encoded JWE Encrypted Key value.)
14. Let the Additional Authenticated Data value be the octets of the
ASCII representation of the concatenation of X, a period ('.')
character, and Y.
15. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization
Vector, the Additional Authenticated Data value, and the JWE Vector, the Additional Authenticated Data value, and the JWE
Authentication Tag (which is the Authentication Tag input to the Authentication Tag (which is the Authentication Tag input to the
calculation) using the specified block encryption algorithm, calculation) using the specified block encryption algorithm,
returning the decrypted plaintext and verifying the JWE returning the decrypted plaintext and verifying the JWE
Authentication Tag in the manner specified for the algorithm, Authentication Tag in the manner specified for the algorithm,
rejecting the input without emitting any decrypted output if the rejecting the input without emitting any decrypted output if the
JWE Authentication Tag is incorrect. JWE Authentication Tag is incorrect.
13. Uncompress the decrypted plaintext if a "zip" parameter was 16. Uncompress the decrypted plaintext if a "zip" parameter was
included. included.
14. Output the resulting Plaintext. 17. Output the resulting Plaintext.
15. If the JWE JSON Serialization is being used, repeat this process
for each recipient contained in the representation.
5.3. String Comparison Rules 5.3. String Comparison Rules
Processing a JWE inevitably requires comparing known strings to Processing a JWE inevitably requires comparing known strings to
values in JSON objects. For example, in checking what the encryption values in JSON objects. For example, in checking what the encryption
method is, the Unicode string encoding "enc" will be checked against method is, the Unicode string encoding "enc" will be checked against
the member names in the JWE Header to see if there is a matching the member names in the JWE Header to see if there is a matching
Header Parameter Name. Header Parameter Name.
Comparisons between JSON strings and other Unicode strings MUST be Comparisons between JSON strings and other Unicode strings MUST be
skipping to change at page 21, line 46 skipping to change at page 22, line 27
See the algorithms registered for "enc" usage in the IANA JSON Web See the algorithms registered for "enc" usage in the IANA JSON Web
Signature and Encryption Algorithms registry [JWA] and Section 4.1 of Signature and Encryption Algorithms registry [JWA] and Section 4.1 of
the JSON Web Algorithms (JWA) [JWA] specification for lists of the JSON Web Algorithms (JWA) [JWA] specification for lists of
encryption algorithms that can be used for CEK encryption. encryption algorithms that can be used for CEK encryption.
7. JSON Serialization 7. JSON Serialization
The JWE JSON Serialization represents encrypted content as a JSON The JWE JSON Serialization represents encrypted content as a JSON
object with a "recipients" member containing an array of per- object with a "recipients" member containing an array of per-
recipient information, an "initialization_vector" member containing a recipient information, an "initialization_vector" member containing a
shared Encoded JWE Initialization Vector value, and a "ciphertext" shared Encoded JWE Initialization Vector value, a "ciphertext" member
member containing a shared Encoded JWE Ciphertext value. Each member containing a shared Encoded JWE Ciphertext value, and an
of the "recipients" array is a JSON object with a "header" member "authentication_tag" member containing a shared Encoded JWE
containing an Encoded JWE Header value, an "encrypted_key" member Authentication Tag value. Each member of the "recipients" array is a
containing an Encoded JWE Encrypted Key value, and an JSON object with a "header" member containing an Encoded JWE Header
"authentication_tag" member containing an Encoded JWE Authentication value and an "encrypted_key" member containing an Encoded JWE
Tag value. Encrypted Key value.
Unlike the JWE Compact Serialization, content using the JWE JSON Unlike the JWE Compact Serialization, content using the JWE JSON
Serialization MAY be encrypted to more than one recipient. Each Serialization MAY be encrypted to more than one recipient. Each
recipient requires: recipient requires:
o a JWE Header value specifying the cryptographic parameters used to o a JWE Header value specifying the cryptographic parameters used to
encrypt the JWE Encrypted Key to that recipient and the parameters encrypt the JWE Encrypted Key to that recipient and the parameters
used to encrypt the plaintext to produce the JWE Ciphertext; this used to encrypt the plaintext to produce the JWE Ciphertext; this
is represented as an Encoded JWE Header value in the "header" is represented as an Encoded JWE Header value in the "header"
member of an object in the "recipients" array. member of an object in the "recipients" array.
o a JWE Encrypted Key value used to encrypt the ciphertext; this is o a JWE Encrypted Key value used to encrypt the ciphertext; this is
represented as an Encoded JWE Encrypted Key value in the represented as an Encoded JWE Encrypted Key value in the
"encrypted_key" member of the same object in the "recipients" "encrypted_key" member of the same object in the "recipients"
array. array.
o a JWE Authentication Tag that ensures the integrity of the
Ciphertext and the parameters used to create it; this is
represented as an Encoded JWE Authentication Tag value in the
"authentication_tag" member of the same object in the "recipients"
array.
Therefore, the syntax is: Therefore, the syntax is:
{"recipients":[ {"recipients":[
{"header":"<header 1 contents>", {"header":"<header 1 contents>",
"encrypted_key":"<encrypted key 1 contents>", "encrypted_key":"<encrypted key 1 contents>"},
"authentication_tag":"<authentication tag 1 contents>"},
... ...
{"header":"<header N contents>", {"header":"<header N contents>",
"encrypted_key":"<encrypted key N contents>", "encrypted_key":"<encrypted key N contents>"}],
"authentication_tag":"<authentication tag N contents>"}],
"initialization_vector":"<initialization vector contents>", "initialization_vector":"<initialization vector contents>",
"ciphertext":"<ciphertext contents>" "ciphertext":"<ciphertext contents>",
"authentication_tag":"<authentication tag contents>"
} }
The contents of the Encoded JWE Header, Encoded JWE Encrypted Key, The contents of the Encoded JWE Header, Encoded JWE Encrypted Key,
Encoded JWE Initialization Vector, Encoded JWE Ciphertext, and Encoded JWE Initialization Vector, Encoded JWE Ciphertext, and
Encoded JWE Authentication Tag values are exactly as specified in the Encoded JWE Authentication Tag values are exactly as specified in the
rest of this specification. They are interpreted and validated in rest of this specification. They are interpreted and validated in
the same manner, with each corresponding "header", "encrypted_key", the same manner, with each corresponding "header" and "encrypted_key"
and "authentication_tag" value being created and validated together. value being created and validated together.
Each JWE Encrypted Key value and the corresponding JWE Authentication
Tag are computed using the parameters of the corresponding JWE Header
value in the same manner as for the JWE Compact Serialization. This
has the desirable result that each Encoded JWE Encrypted Key value in
the "recipients" array and each Encoded JWE Authentication Tag in the
same array element are identical to the values that would have been
computed for the same parameters in the JWE Compact Serialization, as
are the shared JWE Ciphertext and JWE Initialization Vector values.
All recipients use the same JWE Ciphertext and JWE Initialization All recipients use the same JWE Ciphertext, JWE Initialization
Vector values, resulting in potentially significant space savings if Vector, and JWE Authentication Tag values, resulting in potentially
the message is large. Therefore, all header parameters that specify significant space savings if the message is large. Therefore, all
the treatment of the JWE Ciphertext value MUST be the same for all header parameters that specify the treatment of the JWE Ciphertext
recipients. This primarily means that the "enc" (encryption method) value MUST be the same for all recipients. This primarily means that
header parameter value in the JWE Header for each recipient MUST be the "enc" (encryption method) header parameter value in the JWE
the same. Header for each recipient MUST be the same.
7.1. Example JWE-JS 7.1. Example JWE-JS
This section contains an example using the JWE JSON Serialization. This section contains an example using the JWE JSON Serialization.
This example demonstrates the capability for encrypting the same This example demonstrates the capability for encrypting the same
plaintext to multiple recipients. plaintext to multiple recipients.
Two recipients are present in this example: the first using the Two recipients are present in this example: the first using the
RSAES-PKCS1-V1_5 algorithm to encrypt the Content Encryption Key RSAES-PKCS1-V1_5 algorithm to encrypt the Content Encryption Key
(CEK) and the second using RSAES OAEP to encrypt the CEK. The (CEK) and the second using RSAES OAEP to encrypt the CEK. The
skipping to change at page 23, line 41 skipping to change at page 24, line 6
and: and:
{"alg":"RSA-OAEP","enc":"A128CBC-HS256"} {"alg":"RSA-OAEP","enc":"A128CBC-HS256"}
The keys used for the first recipient are the same as those in The keys used for the first recipient are the same as those in
Appendix A.2, as is the Plaintext used. The encryption key used for Appendix A.2, as is the Plaintext used. The encryption key used for
the second recipient is the same as that used in Appendix A.3; the the second recipient is the same as that used in Appendix A.3; the
block encryption keys and parameters for the second recipient are the block encryption keys and parameters for the second recipient are the
same as those for the first recipient (which must be the case, since same as those for the first recipient (which must be the case, since
the Initialization Vector and Ciphertext are shared). the Initialization Vector and Ciphertext are shared). Thus, the same
two Encoded JWE Header and JWE Encoded Encrypted Key values are used
in this example as are used in those examples.
The value X used as part of the AAD value is the concatenation of the
Encoded JWE Header values, separated by a tilde ('~') character. In
this example, the value of X (with line breaks for display purposes
only) is:
eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0
~
eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0
The value Y used as part of the AAD value is the concatenation of the
Encoded JWE Encrypted Key values, separated by a tilde ('~')
character. In this example, the value of Y (with line breaks for
display purposes only) is:
nJa_uE2D0wlKz-OcwSbKFzj302xYSI-RLBM6hbVGmP4axtJQPA9S0po3s3NMk
mOmkkawnfwPNjpc0mc3z79cuQWkQPFQo-mDxmogz8dxBcheaTUg3ZvpbGCXxZ
jDYENRWiZ5M9BiLy09BIF5mHp85QL6XED1JEZMOh-1uT1lqPDcDD79qWtrCfE
JmNmfsx5fcB2PfAcVtQ0t_YmOXx5_Gu0it1nILKXLR2Ynf9mfLhEcC5LebpWy
EHW6WzQ4iH9SIcIupPV1iKCzmJcPrDBJ5Fc_KMBcXBinaS__wftNywaGgfi_N
Ssx24LxtK6fIkejRlMBmCfxv0Tg8CtxpURigg
~
6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ
The AAD value used for the block encryption is the octets of the
ASCII representation of the concatenation of X, a period ('.')
character, and Y. This concatenation (with line breaks for display
purposes only) is:
eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0
~
eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0
.
nJa_uE2D0wlKz-OcwSbKFzj302xYSI-RLBM6hbVGmP4axtJQPA9S0po3s3NMk
mOmkkawnfwPNjpc0mc3z79cuQWkQPFQo-mDxmogz8dxBcheaTUg3ZvpbGCXxZ
jDYENRWiZ5M9BiLy09BIF5mHp85QL6XED1JEZMOh-1uT1lqPDcDD79qWtrCfE
JmNmfsx5fcB2PfAcVtQ0t_YmOXx5_Gu0it1nILKXLR2Ynf9mfLhEcC5LebpWy
EHW6WzQ4iH9SIcIupPV1iKCzmJcPrDBJ5Fc_KMBcXBinaS__wftNywaGgfi_N
Ssx24LxtK6fIkejRlMBmCfxv0Tg8CtxpURigg
~
6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ
The complete JSON Web Encryption JSON Serialization (JWE-JS) for The complete JSON Web Encryption JSON Serialization (JWE-JS) for
these values is as follows (with line breaks for display purposes these values is as follows (with line breaks for display purposes
only): only):
{"recipients":[ {"recipients":[
{"header": {"header":
"eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", "eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0",
"encrypted_key": "encrypted_key":
"nJa_uE2D0wlKz-OcwSbKFzj302xYSI-RLBM6hbVGmP4axtJQPA9S0po3s3NMk "nJa_uE2D0wlKz-OcwSbKFzj302xYSI-RLBM6hbVGmP4axtJQPA9S0po3s3NMk
mOmkkawnfwPNjpc0mc3z79cuQWkQPFQo-mDxmogz8dxBcheaTUg3ZvpbGCXxZ mOmkkawnfwPNjpc0mc3z79cuQWkQPFQo-mDxmogz8dxBcheaTUg3ZvpbGCXxZ
jDYENRWiZ5M9BiLy09BIF5mHp85QL6XED1JEZMOh-1uT1lqPDcDD79qWtrCfE jDYENRWiZ5M9BiLy09BIF5mHp85QL6XED1JEZMOh-1uT1lqPDcDD79qWtrCfE
JmNmfsx5fcB2PfAcVtQ0t_YmOXx5_Gu0it1nILKXLR2Ynf9mfLhEcC5LebpWy JmNmfsx5fcB2PfAcVtQ0t_YmOXx5_Gu0it1nILKXLR2Ynf9mfLhEcC5LebpWy
EHW6WzQ4iH9SIcIupPV1iKCzmJcPrDBJ5Fc_KMBcXBinaS__wftNywaGgfi_N EHW6WzQ4iH9SIcIupPV1iKCzmJcPrDBJ5Fc_KMBcXBinaS__wftNywaGgfi_N
Ssx24LxtK6fIkejRlMBmCfxv0Tg8CtxpURigg", Ssx24LxtK6fIkejRlMBmCfxv0Tg8CtxpURigg"},
"authentication_tag":
"fY2U_Hx5VcfXmipEldHhMA"},
{"header": {"header":
"eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", "eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0",
"encrypted_key": "encrypted_key":
"6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ", "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}],
"authentication_tag":
"CEH4ZS25HNrocFNPVN0SrA"}],
"initialization_vector": "initialization_vector":
"AxY8DCtDaGlsbGljb3RoZQ", "AxY8DCtDaGlsbGljb3RoZQ",
"ciphertext": "ciphertext":
"KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY" "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY",
"authentication_tag":
"LlhRZFfphc2f5X3nTTJP6g"
} }
8. Implementation Considerations 8. Implementation Considerations
The JWE Compact Serialization is mandatory to implement. The JWE Compact Serialization is mandatory to implement.
Implementation of the JWE JSON Serialization is OPTIONAL. Implementation of the JWE JSON Serialization is OPTIONAL.
9. IANA Considerations 9. IANA Considerations
9.1. Registration of JWE Header Parameter Names 9.1. Registration of JWE Header Parameter Names
skipping to change at page 28, line 30 skipping to change at page 29, line 30
recipient to be used as an oracle for decrypting messages. RFC 3218 recipient to be used as an oracle for decrypting messages. RFC 3218
[RFC3218] should be consulted for specific countermeasures to attacks [RFC3218] should be consulted for specific countermeasures to attacks
on RSAES-PKCS1-V1_5. An attacker might modify the contents of the on RSAES-PKCS1-V1_5. An attacker might modify the contents of the
"alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a
formatting error that can be detected and used to recover the CEK formatting error that can be detected and used to recover the CEK
even if RSAES OAEP was used to encrypt the CEK. It is therefore even if RSAES OAEP was used to encrypt the CEK. It is therefore
particularly important to report all formatting errors to the CEK, particularly important to report all formatting errors to the CEK,
Additional Authenticated Data, or ciphertext as a single error when Additional Authenticated Data, or ciphertext as a single error when
the JWE is rejected. the JWE is rejected.
AES GCM MUST NOT be used when using the JWE JSON Serialization for
multiple recipients, since this would result in the same
Initialization Vector and Plaintext values being used for multiple
GCM encryptions. This is prohibited by the GCM specification because
of severe security vulnerabilities that would result, were GCM used
in this way.
11. References 11. References
11.1. Normative References 11.1. Normative References
[ITU.X690.1994] [ITU.X690.1994]
International Telecommunications Union, "Information International Telecommunications Union, "Information
Technology - ASN.1 encoding rules: Specification of Basic Technology - ASN.1 encoding rules: Specification of Basic
Encoding Rules (BER), Canonical Encoding Rules (CER) and Encoding Rules (BER), Canonical Encoding Rules (CER) and
Distinguished Encoding Rules (DER)", ITU-T Recommendation Distinguished Encoding Rules (DER)", ITU-T Recommendation
X.690, 1994. X.690, 1994.
skipping to change at page 48, line 22 skipping to change at page 49, line 22
173, 226] 173, 226]
B.7. Truncate HMAC Value to Create Authentication Tag B.7. Truncate HMAC Value to Create Authentication Tag
Use the first half (128 bits) of the HMAC output M as the Use the first half (128 bits) of the HMAC output M as the
Authentication Tag output T. This truncated value is: Authentication Tag output T. This truncated value is:
[8, 65, 248, 101, 45, 185, 28, 218, 232, 112, 83, 79, 84, 221, 18, [8, 65, 248, 101, 45, 185, 28, 218, 232, 112, 83, 79, 84, 221, 18,
172] 172]
Appendix C. Acknowledgements Appendix C. Possible Compact Serialization for Multiple Recipients
The JWE encryption process in Section 5.1, and in particular in steps
15 and 16, hint at a possible compact serialization when there are
multiple recipients. This possible compact serialization
concatenates instances of the per-recipient fields, separating them
with tilde ('~') characters, which are URL-safe.
The concatenation of the Encoded JWE Header values goes before the
first period ('.') character in the compact serialization. The
concatenation of the corresponding Encoded JWE Encoded Key values
goes between the first and second period ('.') characters in the
compact serialization.
A complete compact serialization of the multi-recipient JWE in
Section 7.1 (with line breaks for display purposes only) would be:
eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0
~
eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0
.
nJa_uE2D0wlKz-OcwSbKFzj302xYSI-RLBM6hbVGmP4axtJQPA9S0po3s3NMk
mOmkkawnfwPNjpc0mc3z79cuQWkQPFQo-mDxmogz8dxBcheaTUg3ZvpbGCXxZ
jDYENRWiZ5M9BiLy09BIF5mHp85QL6XED1JEZMOh-1uT1lqPDcDD79qWtrCfE
JmNmfsx5fcB2PfAcVtQ0t_YmOXx5_Gu0it1nILKXLR2Ynf9mfLhEcC5LebpWy
EHW6WzQ4iH9SIcIupPV1iKCzmJcPrDBJ5Fc_KMBcXBinaS__wftNywaGgfi_N
Ssx24LxtK6fIkejRlMBmCfxv0Tg8CtxpURigg
~
6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ
.
AxY8DCtDaGlsbGljb3RoZQ
.
KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY
.
LlhRZFfphc2f5X3nTTJP6g
Note that the octets of the UTF-8 representation of the first two
parts of this serialization, including the period ('.') character
separating them, are used as the AAD value in step 17 of the JWE
encryption process in Section 5.1.
This representation is suggested for those who may desire or require
a compact, URL-safe serialization of JWEs with multiple recipients.
It is a suggestion to implementers for whom this functionality would
be valuable, and not a normative part of this specification.
Appendix D. Acknowledgements
Solutions for encrypting JSON content were also explored by JSON Solutions for encrypting JSON content were also explored by JSON
Simple Encryption [JSE] and JavaScript Message Security Format Simple Encryption [JSE] and JavaScript Message Security Format
[I-D.rescorla-jsms], both of which significantly influenced this [I-D.rescorla-jsms], both of which significantly influenced this
draft. This draft attempts to explicitly reuse as many of the draft. This draft attempts to explicitly reuse as many of the
relevant concepts from XML Encryption 1.1 relevant concepts from XML Encryption 1.1
[W3C.CR-xmlenc-core1-20120313] and RFC 5652 [RFC5652] as possible, [W3C.CR-xmlenc-core1-20120313] and RFC 5652 [RFC5652] as possible,
while utilizing simple compact JSON-based data structures. while utilizing simple compact JSON-based data structures.
Special thanks are due to John Bradley and Nat Sakimura for the Special thanks are due to John Bradley and Nat Sakimura for the
skipping to change at page 49, line 6 skipping to change at page 51, line 19
Richard Barnes, John Bradley, Brian Campbell, Breno de Medeiros, Dick Richard Barnes, John Bradley, Brian Campbell, Breno de Medeiros, Dick
Hardt, Jeff Hodges, Edmund Jay, James Manger, Tony Nadalin, Axel Hardt, Jeff Hodges, Edmund Jay, James Manger, Tony Nadalin, Axel
Nennker, Emmanuel Raviart, Nat Sakimura, Jim Schaad, Hannes Nennker, Emmanuel Raviart, Nat Sakimura, Jim Schaad, Hannes
Tschofenig, and Sean Turner. Tschofenig, and Sean Turner.
Jim Schaad and Karen O'Donoghue chaired the JOSE working group and Jim Schaad and Karen O'Donoghue chaired the JOSE working group and
Sean Turner and Stephen Farrell served as Security area directors Sean Turner and Stephen Farrell served as Security area directors
during the creation of this specification. during the creation of this specification.
Appendix D. Document History Appendix E. Document History
[[ to be removed by the RFC editor before publication as an RFC ]] [[ to be removed by the RFC editor before publication as an RFC ]]
-10
o Changed the JWE processing rules for multiple recipients so that a
single AAD value contains the header parameters and encrypted key
values for all the recipients, enabling AES GCM to be safely used
for multiple recipients.
o Added an appendix suggesting a possible compact serialization for
JWEs with multiple recipients.
-09 -09
o Added JWE JSON Serialization, as specified by o Added JWE JSON Serialization, as specified by
draft-jones-jose-jwe-json-serialization-04. draft-jones-jose-jwe-json-serialization-04.
o Registered "application/jwe-js" MIME type and "JWE-JS" typ header o Registered "application/jwe-js" MIME type and "JWE-JS" typ header
parameter value. parameter value.
o Defined that the default action for header parameters that are not o Defined that the default action for header parameters that are not
understood is to ignore them unless specifically designated as understood is to ignore them unless specifically designated as
 End of changes. 37 change blocks. 
146 lines changed or deleted 251 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/