< draft-ietf-jose-json-web-encryption-11.txt   draft-ietf-jose-json-web-encryption-12.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: November 29, 2013 RTFM Expires: January 12, 2014 RTFM
J. Hildebrand J. Hildebrand
Cisco Cisco
May 28, 2013 July 11, 2013
JSON Web Encryption (JWE) JSON Web Encryption (JWE)
draft-ietf-jose-json-web-encryption-11 draft-ietf-jose-json-web-encryption-12
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) based data content using JavaScript Object Notation (JSON) based data
structures. Cryptographic algorithms and identifiers for use with structures. Cryptographic algorithms and identifiers for use with
this specification are described in the separate JSON Web Algorithms this specification are described in the separate JSON Web Algorithms
(JWA) specification. Related digital signature and MAC capabilities (JWA) specification. Related digital signature and MAC capabilities
are described in the separate JSON Web Signature (JWS) specification. are 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 November 29, 2013. This Internet-Draft will expire on January 12, 2014.
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 20 skipping to change at page 2, line 20
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 8 3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 8
3.1. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 9 3.1. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 9
4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.1. Reserved Header Parameter Names . . . . . . . . . . . . . 11 4.1. Reserved Header Parameter Names . . . . . . . . . . . . . 11
4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 11 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 11
4.1.2. "enc" (Encryption Method) Header Parameter . . . . . . 12 4.1.2. "enc" (Encryption Method) Header Parameter . . . . . . 12
4.1.3. "epk" (Ephemeral Public Key) Header Parameter . . . . 12 4.1.3. "zip" (Compression Algorithm) Header Parameter . . . . 12
4.1.4. "zip" (Compression Algorithm) Header Parameter . . . . 12 4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 12
4.1.5. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 13 4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 12
4.1.6. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 13 4.1.6. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 13
4.1.7. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 13 4.1.7. "x5t" (X.509 Certificate Thumbprint) Header
4.1.8. "x5t" (X.509 Certificate Thumbprint) Header
Parameter . . . . . . . . . . . . . . . . . . . . . . 13 Parameter . . . . . . . . . . . . . . . . . . . . . . 13
4.1.9. "x5c" (X.509 Certificate Chain) Header Parameter . . . 14 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter . . . 13
4.1.10. "kid" (Key ID) Header Parameter . . . . . . . . . . . 14 4.1.9. "kid" (Key ID) Header Parameter . . . . . . . . . . . 14
4.1.11. "typ" (Type) Header Parameter . . . . . . . . . . . . 14 4.1.10. "typ" (Type) Header Parameter . . . . . . . . . . . . 14
4.1.12. "cty" (Content Type) Header Parameter . . . . . . . . 15 4.1.11. "cty" (Content Type) Header Parameter . . . . . . . . 14
4.1.13. "apu" (Agreement PartyUInfo) Header Parameter . . . . 15 4.1.12. "crit" (Critical) Header Parameter . . . . . . . . . . 15
4.1.14. "crit" (Critical) Header Parameter . . . . . . . . . . 15 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 15
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 . . . . . . . . . . . . . . . . . 16 5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 16
5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 16 5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 16
5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 18 5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 18
5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 20 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 20
6. Cryptographic Algorithms . . . . . . . . . . . . . . . . . . . 21 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 20
6.1. CEK Encryption . . . . . . . . . . . . . . . . . . . . . . 21 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 20
7. Key Identification . . . . . . . . . . . . . . . . . . . . . . 21 7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 21
8. JWE JSON Serialization . . . . . . . . . . . . . . . . . . . . 22 7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 21
9. Implementation Considerations . . . . . . . . . . . . . . . . 24 8. Distinguishing Between JWS and JWE Objects . . . . . . . . . . 23
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24
10.1. Registration of JWE Header Parameter Names . . . . . . . . 24 9.1. Registration of JWE Header Parameter Names . . . . . . . . 24
10.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 25 9.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 24
10.2. JSON Web Signature and Encryption Type Values 10. Security Considerations . . . . . . . . . . . . . . . . . . . 26
Registration . . . . . . . . . . . . . . . . . . . . . . . 26 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26
10.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 26 11.1. Normative References . . . . . . . . . . . . . . . . . . . 26
10.3. Media Type Registration . . . . . . . . . . . . . . . . . 26 11.2. Informative References . . . . . . . . . . . . . . . . . . 28
10.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 27 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 28
11. Security Considerations . . . . . . . . . . . . . . . . . . . 28 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 28
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28 A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 29
12.1. Normative References . . . . . . . . . . . . . . . . . . . 28 A.1.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 29
12.2. Informative References . . . . . . . . . . . . . . . . . . 30 A.1.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 29
Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 30 A.1.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 29
A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 30 A.1.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 30
A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 31 A.1.6. Initialization Vector . . . . . . . . . . . . . . . . 31
A.1.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 31 A.1.7. Additional Authenticated Data . . . . . . . . . . . . 31
A.1.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 31 A.1.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 31
A.1.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 31 A.1.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 31
A.1.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 34 A.1.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 32
A.1.6. Initialization Vector . . . . . . . . . . . . . . . . 34 A.1.11. Complete Representation . . . . . . . . . . . . . . . 32
A.1.7. Additional Authenticated Data . . . . . . . . . . . . 34 A.1.12. Validation . . . . . . . . . . . . . . . . . . . . . . 32
A.1.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 34
A.1.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 35
A.1.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 35
A.1.11. Complete Representation . . . . . . . . . . . . . . . 35
A.1.12. Validation . . . . . . . . . . . . . . . . . . . . . . 36
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 . . . . . . . . . . . . . . . . . 32
A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 36 A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 33
A.2.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 36 A.2.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 33
A.2.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 36 A.2.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 33
A.2.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 37 A.2.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 33
A.2.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 39 A.2.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 34
A.2.6. Initialization Vector . . . . . . . . . . . . . . . . 39 A.2.6. Initialization Vector . . . . . . . . . . . . . . . . 35
A.2.7. Additional Authenticated Data . . . . . . . . . . . . 39 A.2.7. Additional Authenticated Data . . . . . . . . . . . . 35
A.2.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 39 A.2.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 35
A.2.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 40 A.2.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 35
A.2.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 40 A.2.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 36
A.2.11. Complete Representation . . . . . . . . . . . . . . . 40 A.2.11. Complete Representation . . . . . . . . . . . . . . . 36
A.2.12. Validation . . . . . . . . . . . . . . . . . . . . . . 40 A.2.12. Validation . . . . . . . . . . . . . . . . . . . . . . 36
A.3. Example JWE using AES Key Wrap and AES GCM . . . . . . . . 41 A.3. Example JWE using AES Key Wrap and AES GCM . . . . . . . . 36
A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 41 A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 37
A.3.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 41 A.3.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 37
A.3.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 41 A.3.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 37
A.3.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 41 A.3.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 37
A.3.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 42 A.3.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 38
A.3.6. Initialization Vector . . . . . . . . . . . . . . . . 42 A.3.6. Initialization Vector . . . . . . . . . . . . . . . . 38
A.3.7. Additional Authenticated Data . . . . . . . . . . . . 42 A.3.7. Additional Authenticated Data . . . . . . . . . . . . 38
A.3.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 42 A.3.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 38
A.3.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 43 A.3.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 39
A.3.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 43 A.3.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 39
A.3.11. Complete Representation . . . . . . . . . . . . . . . 43 A.3.11. Complete Representation . . . . . . . . . . . . . . . 39
A.3.12. Validation . . . . . . . . . . . . . . . . . . . . . . 43 A.3.12. Validation . . . . . . . . . . . . . . . . . . . . . . 39
A.4. Example JWE Using JWE JSON Serialization . . . . . . . . . 44 A.4. Example JWE Using JWE JSON Serialization . . . . . . . . . 39
A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 44 A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 40
A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 44 A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 40
A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 45 A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 40
A.4.4. Complete JWE Header Values . . . . . . . . . . . . . . 45 A.4.4. Complete JWE Header Values . . . . . . . . . . . . . . 41
A.4.5. Additional Authenticated Data . . . . . . . . . . . . 45 A.4.5. Additional Authenticated Data . . . . . . . . . . . . 41
A.4.6. Plaintext Encryption . . . . . . . . . . . . . . . . . 45 A.4.6. Plaintext Encryption . . . . . . . . . . . . . . . . . 41
A.4.7. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 46 A.4.7. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 41
A.4.8. Encoded JWE Authentication Tag . . . . . . . . . . . . 46 A.4.8. Encoded JWE Authentication Tag . . . . . . . . . . . . 42
A.4.9. Complete JWE JSON Serialization Representation . . . . 46 A.4.9. Complete JWE JSON Serialization Representation . . . . 42
Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 47 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 42
B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 47 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 43
B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 47 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 43
B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 48 B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 43
B.4. Initialization Vector Value . . . . . . . . . . . . . . . 48 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 44
B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 48 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 44
B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 48 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 44
B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 49 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 44
Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 49 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 45
Appendix D. Document History . . . . . . . . . . . . . . . . . . 49 Appendix D. Document History . . . . . . . . . . . . . . . . . . 45
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 56 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 52
1. Introduction 1. Introduction
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) [RFC4627] based data content using JavaScript Object Notation (JSON) [RFC4627] based data
structures. The JWE cryptographic mechanisms encrypt and provide structures. The JWE cryptographic mechanisms encrypt and provide
integrity protection for arbitrary sequences of octets. integrity protection for arbitrary sequences of octets.
Two closely related representations for JWE objects are defined. The Two closely related representations for JWE objects are defined. The
JWE Compact Serialization is a compact, URL-safe representation JWE Compact Serialization is a compact, URL-safe representation
skipping to change at page 5, line 40 skipping to change at page 5, line 40
document are to be interpreted as described in Key words for use in document are to be interpreted as described in Key words for use in
RFCs to Indicate Requirement Levels [RFC2119]. RFCs to Indicate Requirement Levels [RFC2119].
2. Terminology 2. Terminology
JSON Web Encryption (JWE) A data structure representing an encrypted JSON Web Encryption (JWE) A data structure representing an encrypted
message. The structure represents five values: the JWE Header, message. The structure represents five values: the JWE Header,
the JWE Encrypted Key, the JWE Initialization Vector, the JWE the JWE Encrypted Key, the JWE Initialization Vector, the JWE
Ciphertext, and the JWE Authentication Tag. Ciphertext, and the JWE Authentication Tag.
Authenticated Encryption An Authenticated Encryption algorithm is Authenticated Encryption with Associated Data (AEAD) An AEAD
one that provides an integrated content integrity check. algorithm is one that encrypts the Plaintext, allows Additional
Authenticated Encryption algorithms accept two inputs, the Authenticated Data to be specified, and provides an integrated
content integrity check over the Ciphertext and Additional
Authenticated Data. AEAD algorithms accept two inputs, the
Plaintext and the Additional Authenticated Data value, and produce Plaintext and the Additional Authenticated Data value, and produce
two outputs, the Ciphertext and the Authentication Tag value. AES two outputs, the Ciphertext and the Authentication Tag value. AES
Galois/Counter Mode (GCM) is one such algorithm. Galois/Counter Mode (GCM) is one such algorithm.
Plaintext The sequence of octets to be encrypted -- a.k.a., the Plaintext The sequence of octets to be encrypted -- a.k.a., the
message. The plaintext can contain an arbitrary sequence of message. The plaintext can contain an arbitrary sequence of
octets. octets.
Ciphertext An encrypted representation of the Plaintext. Ciphertext An encrypted representation of the Plaintext.
Additional Authenticated Data (AAD) An input to an Authenticated Additional Authenticated Data (AAD) An input to an AEAD operation
Encryption operation that is integrity protected but not that is integrity protected but not encrypted.
encrypted.
Authentication Tag An output of an Authenticated Encryption Authentication Tag An output of an AEAD operation that ensures the
operation that ensures the integrity of the Ciphertext and the integrity of the Ciphertext and the Additional Authenticated Data.
Additional Authenticated Data. Note that some algorithms may not Note that some algorithms may not use an Authentication Tag, in
use an Authentication Tag, in which case this value is the empty which case this value is the empty octet sequence.
octet sequence.
Content Encryption Key (CEK) A symmetric key for the Authenticated Content Encryption Key (CEK) A symmetric key for the AEAD algorithm
Encryption algorithm used to encrypt the Plaintext for the used to encrypt the Plaintext for the recipient to produce the
recipient to produce the Ciphertext and the Authentication Tag. Ciphertext and the Authentication Tag.
JSON Text Object A UTF-8 [RFC3629] encoded text string representing JSON Text Object A UTF-8 [RFC3629] encoded text string representing
a JSON object; the syntax of JSON objects is defined in Section a JSON object; the syntax of JSON objects is defined in Section
2.2 of [RFC4627]. 2.2 of [RFC4627].
JWE Header A JSON Text Object (or JSON Text Objects, when using the JWE Header A JSON Text Object (or JSON Text Objects, when using the
JWE JSON Serialization) that describes the encryption operations JWE JSON Serialization) that describes the encryption operations
applied to create the JWE Encrypted Key, the JWE Ciphertext, and applied to create the JWE Encrypted Key, the JWE Ciphertext, and
the JWE Authentication Tag. The members of the JWE Header the JWE Authentication Tag. The members of the JWE Header
object(s) are Header Parameters. object(s) are Header Parameters.
skipping to change at page 9, line 6 skipping to change at page 9, line 6
3. JSON Web Encryption (JWE) Overview 3. JSON Web Encryption (JWE) Overview
JWE represents encrypted content using JSON data structures and JWE represents encrypted content using JSON data structures and
base64url encoding. Five values are represented in a JWE: the JWE base64url encoding. Five values are represented in a JWE: the JWE
Header, the JWE Encrypted Key, the JWE Initialization Vector, the JWE Header, the JWE Encrypted Key, the JWE Initialization Vector, the JWE
Ciphertext, and the JWE Authentication Tag. In the Compact Ciphertext, and the JWE Authentication Tag. In the Compact
Serialization, the five values are base64url-encoded for Serialization, the five values are base64url-encoded for
transmission, and represented as the concatenation of the encoded transmission, and represented as the concatenation of the encoded
strings in that order, with the five strings being separated by four strings in that order, with the five strings being separated by four
period ('.') characters. A JSON Serialization for this information period ('.') characters. A JSON Serialization for this information
is also defined in Section 8. is also defined in Section 7.2.
JWE utilizes authenticated encryption to ensure the confidentiality JWE utilizes authenticated encryption to ensure the confidentiality
and integrity of the Plaintext and the integrity of the JWE Protected and integrity of the Plaintext and the integrity of the JWE Protected
Header. Header.
3.1. Example JWE 3.1. Example JWE
This example encrypts the plaintext "The true sign of intelligence is This example encrypts the plaintext "The true sign of intelligence is
not knowledge but imagination." to the recipient using RSAES OAEP and not knowledge but imagination." to the recipient using RSAES OAEP for
AES GCM. key encryption and AES GCM for content encryption.
The following example JWE Header declares that: The following example JWE Header declares that:
o the Content Encryption Key is encrypted to the recipient using the o the Content Encryption Key is encrypted to the recipient using the
RSAES OAEP algorithm to produce the JWE Encrypted Key and RSAES OAEP algorithm to produce the JWE Encrypted Key and
o the Plaintext is encrypted using the AES GCM algorithm with a 256 o the Plaintext is encrypted using the AES GCM algorithm with a 256
bit key to produce the Ciphertext. bit key to produce the Ciphertext.
{"alg":"RSA-OAEP","enc":"A256GCM"} {"alg":"RSA-OAEP","enc":"A256GCM"}
skipping to change at page 10, line 43 skipping to change at page 10, line 43
48V1_ALb6US04U3b. 48V1_ALb6US04U3b.
5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji
SdiwkIr3ajwQzaBtQD_A. SdiwkIr3ajwQzaBtQD_A.
XFBoMYUZodetZdvTiFvSkQ XFBoMYUZodetZdvTiFvSkQ
See Appendix A.1 for the complete details of computing this JWE. See See Appendix A.1 for the complete details of computing this JWE. See
Appendix A for additional examples. Appendix A for additional examples.
4. JWE Header 4. JWE Header
The members of the JSON object(s) represented by the JWE Header The members of the JSON object(s) representing the JWE Header
describe the encryption applied to the Plaintext and optionally describe the encryption applied to the Plaintext and optionally
additional properties of the JWE. The Header Parameter Names within additional properties of the JWE. The Header Parameter Names within
the JWE Header MUST be unique; JWEs with duplicate Header Parameter the JWE Header MUST be unique; receipients MUST either reject JWEs
Names MUST be rejected. with duplicate Header Parameter Names or use a JSON parser that
returns only the lexically last duplicate member name, as specified
in Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript].
Implementations are required to understand the specific header Implementations are required to understand the specific header
parameters defined by this specification that are designated as "MUST parameters defined by this specification that are designated as "MUST
be understood" and process them in the manner defined in this be understood" and process them in the manner defined in this
specification. All other header parameters defined by this specification. All other header parameters defined by this
specification that are not so designated MUST be ignored when not specification that are not so designated MUST be ignored when not
understood. Unless listed as a critical header parameter, per understood. Unless listed as a critical header parameter, per
Section 4.1.14, all other header parameters MUST be ignored when not Section 4.1.12, all header parameters not defined by this
understood. specification MUST be ignored when not understood.
There are two ways of distinguishing whether a header is a JWS Header
or a JWE Header. The first is by examining the "alg" (algorithm)
header parameter value. If the value represents a digital signature
or MAC algorithm, or is the value "none", it is for a JWS; if it
represents a Key Encryption, Key Wrapping, Direct Key Agreement, Key
Agreement with Key Wrapping, or Direct Encryption algorithm, it is
for a JWE. A second method is determining whether an "enc"
(encryption method) member exists. If the "enc" member exists, it is
a JWE; otherwise, it is a JWS. Both methods will yield the same
result for all legal input values.
There are three classes of Header Parameter Names: Reserved Header There are three classes of Header Parameter Names: Reserved Header
Parameter Names, Public Header Parameter Names, and Private Header Parameter Names, Public Header Parameter Names, and Private Header
Parameter Names. Parameter Names.
4.1. Reserved Header Parameter Names 4.1. Reserved Header Parameter Names
The following Header Parameter Names are reserved with meanings as The following Header Parameter Names are reserved with meanings as
defined below. All the names are short because a core goal of this defined below. All the names are short because a core goal of this
specification is for the resulting representations using the JWE specification is for the resulting representations using the JWE
skipping to change at page 11, line 41 skipping to change at page 11, line 32
Additional reserved Header Parameter Names can be defined via the Additional reserved Header Parameter Names can be defined via the
IANA JSON Web Signature and Encryption Header Parameters registry IANA JSON Web Signature and Encryption Header Parameters registry
[JWS]. As indicated by the common registry, JWSs and JWEs share a [JWS]. As indicated by the common registry, JWSs and JWEs share a
common header parameter space; when a parameter is used by both common header parameter space; when a parameter is used by both
specifications, its usage must be compatible between the specifications, its usage must be compatible between the
specifications. specifications.
4.1.1. "alg" (Algorithm) Header Parameter 4.1.1. "alg" (Algorithm) Header Parameter
The "alg" (algorithm) header parameter identifies the cryptographic The "alg" (algorithm) header parameter identifies a cryptographic
algorithm used to encrypt or determine the value of the Content algorithm used to encrypt or determine the value of the Content
Encryption Key (CEK). The algorithm specified by the "alg" value Encryption Key (CEK). The recipient MUST reject the JWE if the "alg"
MUST be supported by the implementation and there MUST be a key for value does not represent a supported algorithm, or if the recipient
use with that algorithm associated with the intended recipient or the does not have a key that can be used with that algorithm. "alg"
JWE MUST be rejected. "alg" values SHOULD either be registered in the values SHOULD either be registered in the IANA JSON Web Signature and
IANA JSON Web Signature and Encryption Algorithms registry [JWA] or Encryption Algorithms registry [JWA] or be a value that contains a
be a value that contains a Collision Resistant Namespace. The "alg" Collision Resistant Namespace. The "alg" value is a case sensitive
value is a case sensitive string containing a StringOrURI value. Use string containing a StringOrURI value. Use of this header parameter
of this header parameter is REQUIRED. This header parameter MUST be is REQUIRED. This header parameter MUST be understood by
understood by implementations. implementations.
A list of defined "alg" values can be found in the IANA JSON Web A list of defined "alg" values can be found in the IANA JSON Web
Signature and Encryption Algorithms registry [JWA]; the initial Signature and Encryption Algorithms registry [JWA]; the initial
contents of this registry are the values defined in Section 4.1 of contents of this registry are the values defined in Section 4.1 of
the JSON Web Algorithms (JWA) [JWA] specification. the JSON Web Algorithms (JWA) [JWA] specification.
4.1.2. "enc" (Encryption Method) Header Parameter 4.1.2. "enc" (Encryption Method) Header Parameter
The "enc" (encryption method) header parameter identifies the block The "enc" (encryption method) header parameter identifies the content
encryption algorithm used to encrypt the Plaintext to produce the encryption algorithm used to encrypt the Plaintext to produce the
Ciphertext. This algorithm MUST be an Authenticated Encryption Ciphertext. This algorithm MUST be an AEAD algorithm with a
algorithm with a specified key length. The algorithm specified by specified key length. The recipient MUST reject the JWE if the "enc"
the "enc" value MUST be supported by the implementation or the JWE value does not represent a supported algorithm. "enc" values SHOULD
MUST be rejected. "enc" values SHOULD either be registered in the either be registered in the IANA JSON Web Signature and Encryption
IANA JSON Web Signature and Encryption Algorithms registry [JWA] or Algorithms registry [JWA] or be a value that contains a Collision
be a value that contains a Collision Resistant Namespace. The "enc" Resistant Namespace. The "enc" value is a case sensitive string
value is a case sensitive string containing a StringOrURI value. Use containing a StringOrURI value. Use of this header parameter is
of this header parameter is REQUIRED. This header parameter MUST be REQUIRED. This header parameter MUST be understood by
understood by implementations. implementations.
A list of defined "enc" values can be found in the IANA JSON Web A list of defined "enc" values can be found in the IANA JSON Web
Signature and Encryption Algorithms registry [JWA]; the initial Signature and Encryption Algorithms registry [JWA]; the initial
contents of this registry are the values defined in Section 4.2 of contents of this registry are the values defined in Section 4.2 of
the JSON Web Algorithms (JWA) [JWA] specification. the JSON Web Algorithms (JWA) [JWA] specification.
4.1.3. "epk" (Ephemeral Public Key) Header Parameter 4.1.3. "zip" (Compression Algorithm) Header Parameter
The "epk" (ephemeral public key) value created by the originator for
the use in key agreement algorithms. This key is represented as a
JSON Web Key [JWK] value. When the "alg" value used identifies an
algorithm for which "epk" is a parameter, this parameter MUST be
present if REQUIRED by the algorithm and this header parameter MUST
be understood by implementations; otherwise, this parameter MUST be
omitted.
4.1.4. "zip" (Compression Algorithm) Header Parameter
The "zip" (compression algorithm) applied to the Plaintext before The "zip" (compression algorithm) applied to the Plaintext before
encryption, if any. If present, the value of the "zip" header encryption, if any. If present, the value of the "zip" header
parameter MUST be the case sensitive string "DEF". Compression is parameter MUST be the case sensitive string "DEF". Compression is
performed with the DEFLATE [RFC1951] algorithm. If no "zip" performed with the DEFLATE [RFC1951] algorithm. If no "zip"
parameter is present, no compression is applied to the Plaintext parameter is present, no compression is applied to the Plaintext
before encryption. This header parameter MUST be integrity before encryption. This header parameter MUST be integrity
protected, and therefore MUST occur only with the JWE Protected protected, and therefore MUST occur only with the JWE Protected
Header, when used. Use of this header parameter is OPTIONAL. This Header, when used. Use of this header parameter is OPTIONAL. This
header parameter MUST be understood by implementations. header parameter MUST be understood by implementations.
4.1.5. "jku" (JWK Set URL) Header Parameter 4.1.4. "jku" (JWK Set URL) Header Parameter
The "jku" (JWK Set URL) header parameter is a URI [RFC3986] that The "jku" (JWK Set URL) header parameter is a URI [RFC3986] that
refers to a resource for a set of JSON-encoded public keys, one of refers to a resource for a set of JSON-encoded public keys, one of
which is the key to which the JWE was encrypted; this can be used to which is the key to which the JWE was encrypted; this can be used to
determine the private key needed to decrypt the JWE. The keys MUST determine the private key needed to decrypt the JWE. The keys MUST
be encoded as a JSON Web Key Set (JWK Set) [JWK]. The protocol used be encoded as a JSON Web Key Set (JWK Set) [JWK]. The protocol used
to acquire the resource MUST provide integrity protection; an HTTP to acquire the resource MUST provide integrity protection; an HTTP
GET request to retrieve the certificate MUST use TLS [RFC2818] GET request to retrieve the JWK Set MUST use TLS [RFC2818] [RFC5246];
[RFC5246]; the identity of the server MUST be validated, as per the identity of the server MUST be validated, as per Section 3.1 of
Section 3.1 of HTTP Over TLS [RFC2818]. Use of this header parameter HTTP Over TLS [RFC2818]. Use of this header parameter is OPTIONAL.
is OPTIONAL.
4.1.6. "jwk" (JSON Web Key) Header Parameter 4.1.5. "jwk" (JSON Web Key) Header Parameter
The "jwk" (JSON Web Key) header parameter is the public key to which The "jwk" (JSON Web Key) header parameter is the public key to which
the JWE was encrypted; this can be used to determine the private key the JWE was encrypted; this can be used to determine the private key
needed to decrypt the JWE. This key is represented as a JSON Web Key needed to decrypt the JWE. This key is represented as a JSON Web Key
[JWK]. Use of this header parameter is OPTIONAL. [JWK]. Use of this header parameter is OPTIONAL.
4.1.7. "x5u" (X.509 URL) Header Parameter 4.1.6. "x5u" (X.509 URL) Header Parameter
The "x5u" (X.509 URL) header parameter is a URI [RFC3986] that refers The "x5u" (X.509 URL) header parameter is a URI [RFC3986] that refers
to a resource for the X.509 public key certificate or certificate to a resource for the X.509 public key certificate or certificate
chain [RFC5280] containing the key to which the JWE was encrypted; chain [RFC5280] containing the key to which the JWE was encrypted;
this can be used to determine the private key needed to decrypt the this can be used to determine the private key needed to decrypt the
JWE. The identified resource MUST provide a representation of the JWE. The identified resource MUST provide a representation of the
certificate or certificate chain that conforms to RFC 5280 [RFC5280] certificate or certificate chain that conforms to RFC 5280 [RFC5280]
in PEM encoded form [RFC1421]. The certificate containing the public in PEM encoded form [RFC1421]. The certificate containing the public
key to which the JWE was encrypted MUST be the first certificate. key to which the JWE was encrypted MUST be the first certificate.
This MAY be followed by additional certificates, with each subsequent This MAY be followed by additional certificates, with each subsequent
certificate being the one used to certify the previous one. The certificate being the one used to certify the previous one. The
protocol used to acquire the resource MUST provide integrity protocol used to acquire the resource MUST provide integrity
protection; an HTTP GET request to retrieve the certificate MUST use protection; an HTTP GET request to retrieve the certificate MUST use
TLS [RFC2818] [RFC5246]; the identity of the server MUST be TLS [RFC2818] [RFC5246]; the identity of the server MUST be
validated, as per Section 3.1 of HTTP Over TLS [RFC2818]. Use of validated, as per Section 3.1 of HTTP Over TLS [RFC2818]. Use of
this header parameter is OPTIONAL. this header parameter is OPTIONAL.
4.1.8. "x5t" (X.509 Certificate Thumbprint) Header Parameter 4.1.7. "x5t" (X.509 Certificate Thumbprint) Header Parameter
The "x5t" (X.509 Certificate Thumbprint) header parameter is a The "x5t" (X.509 Certificate Thumbprint) header parameter is a
base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER
encoding of the X.509 certificate [RFC5280] containing the key to encoding of the X.509 certificate [RFC5280] containing the key to
which the JWE was encrypted; this can be used to determine the which the JWE was encrypted; this can be used to determine the
private key needed to decrypt the JWE. Use of this header parameter private key needed to decrypt the JWE. Use of this header parameter
is OPTIONAL. is OPTIONAL.
If, in the future, certificate thumbprints need to be computed using If, in the future, certificate thumbprints need to be computed using
hash functions other than SHA-1, it is suggested that additional hash functions other than SHA-1, it is suggested that additional
related header parameters be defined for that purpose. For example, related header parameters be defined for that purpose. For example,
it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint
using SHA-256) header parameter could be defined by registering it in using SHA-256) header parameter could be defined by registering it in
the IANA JSON Web Signature and Encryption Header Parameters registry the IANA JSON Web Signature and Encryption Header Parameters registry
[JWS]. [JWS].
4.1.9. "x5c" (X.509 Certificate Chain) Header Parameter 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter
The "x5c" (X.509 Certificate Chain) header parameter contains the The "x5c" (X.509 Certificate Chain) header parameter contains the
X.509 public key certificate or certificate chain [RFC5280] X.509 public key certificate or certificate chain [RFC5280]
containing the key to which the JWE was encrypted; this can be used containing the key to which the JWE was encrypted; this can be used
to determine the private key needed to decrypt the JWE. The to determine the private key needed to decrypt the JWE. The
certificate or certificate chain is represented as a JSON array of certificate or certificate chain is represented as a JSON array of
certificate value strings. Each string in the array is a base64 certificate value strings. Each string in the array is a base64
encoded ([RFC4648] Section 4 -- not base64url encoded) DER encoded ([RFC4648] Section 4 -- not base64url encoded) DER
[ITU.X690.1994] PKIX certificate value. The certificate containing [ITU.X690.1994] PKIX certificate value. The certificate containing
the public key to which the JWE was encrypted MUST be the first the public key to which the JWE was encrypted MUST be the first
certificate. This MAY be followed by additional certificates, with certificate. This MAY be followed by additional certificates, with
each subsequent certificate being the one used to certify the each subsequent certificate being the one used to certify the
previous one. Use of this header parameter is OPTIONAL. previous one. Use of this header parameter is OPTIONAL.
See Appendix B of [JWS] for an example "x5c" value. See Appendix B of [JWS] for an example "x5c" value.
4.1.10. "kid" (Key ID) Header Parameter 4.1.9. "kid" (Key ID) Header Parameter
The "kid" (key ID) header parameter is a hint indicating which key to The "kid" (key ID) header parameter is a hint indicating which key to
which the JWE was encrypted; this can be used to determine the which the JWE was encrypted; this can be used to determine the
private key needed to decrypt the JWE. This parameter allows private key needed to decrypt the JWE. This parameter allows
originators to explicitly signal a change of key to recipients. originators to explicitly signal a change of key to recipients.
Should the recipient be unable to locate a key corresponding to the Should the recipient be unable to locate a key corresponding to the
"kid" value, they SHOULD treat that condition as an error. The "kid" value, they SHOULD treat that condition as an error. The
interpretation of the "kid" value is unspecified. Its value MUST be interpretation of the "kid" value is unspecified. Its value MUST be
a string. Use of this header parameter is OPTIONAL. a string. Use of this header parameter is OPTIONAL.
When used with a JWK, the "kid" value can be used to match a JWK When used with a JWK, the "kid" value can be used to match a JWK
"kid" parameter value. "kid" parameter value.
4.1.11. "typ" (Type) Header Parameter 4.1.10. "typ" (Type) Header Parameter
The "typ" (type) header parameter is used to declare the type of this The "typ" (type) header parameter MAY be used to declare the type of
object. The type value "JWE" is used to indicate that this object is this complete JWE object in an application-specific manner in
a JWE using the JWE Compact Serialization. The type value "JWE+JSON" contexts where this is useful to the application. This parameter has
is used to indicate that this object is a JWE using the JWE JSON no effect upon the JWE processing. The type value "JOSE" MAY be used
Serialization. Other type values MAY be used, and if not understood, to indicate that this object is a JWS or JWE using the JWS Compact
SHOULD be ignored. The "typ" value is a case sensitive string. Use Serialization or the JWE Compact Serialization. The type value
of this header parameter is OPTIONAL. "JOSE+JSON" MAY be used to indicate that this object is a JWS or JWE
using the JWS JSON Serialization or the JWE JSON Serialization.
Other type values MAY be used, and if not understood, SHOULD be
ignored. The "typ" value is a case sensitive string. Use of this
header parameter is OPTIONAL.
MIME Media Type [RFC2046] values MAY be used as "typ" values. MIME Media Type [RFC2046] values MAY be used as "typ" values.
"typ" values SHOULD either be registered in the IANA JSON Web "typ" values SHOULD either be registered in the IANA JSON Web
Signature and Encryption Type Values registry [JWS] or be a value Signature and Encryption Type Values registry [JWS] or be a value
that contains a Collision Resistant Namespace. that contains a Collision Resistant Namespace.
4.1.12. "cty" (Content Type) Header Parameter 4.1.11. "cty" (Content Type) Header Parameter
The "cty" (content type) header parameter is used to declare the type The "cty" (content type) header parameter MAY be used to declare the
of the encrypted content (the Plaintext). For example, the JSON Web type of the encrypted content (the Plaintext) in an application-
Token (JWT) [JWT] specification uses the "cty" value "JWT" to specific manner in contexts where this is useful to the application.
indicate that the Plaintext is a JSON Web Token (JWT). Content type This parameter has no effect upon the JWE processing. Content type
values that are not understood SHOULD be ignored. The "cty" value is values that are not understood SHOULD be ignored. The "cty" value is
a case sensitive string. Use of this header parameter is OPTIONAL. a case sensitive string. Use of this header parameter is OPTIONAL.
The values used for the "cty" header parameter come from the same The values used for the "cty" header parameter come from the same
value space as the "typ" header parameter, with the same rules value space as the "typ" header parameter, with the same rules
applying. applying.
4.1.13. "apu" (Agreement PartyUInfo) Header Parameter 4.1.12. "crit" (Critical) Header Parameter
The "apu" (agreement PartyUInfo) value for key agreement algorithms
using it (such as "ECDH-ES"), represented as a base64url encoded
string. Use of this header parameter is OPTIONAL. When the "alg"
value used identifies an algorithm for which "apu" is a parameter,
this header parameter MUST be understood by implementations;
otherwise, this parameter MUST be omitted.
4.1.14. "crit" (Critical) Header Parameter
The "crit" (critical) header parameter indicates that extensions to The "crit" (critical) header parameter indicates that extensions to
[[ this specification ]] are being used that MUST be understood and [[ this specification ]] are being used that MUST be understood and
processed. Its value is an array listing the header parameter names processed. Its value is an array listing the header parameter names
defined by those extensions that are used in the JWE Header. If any defined by those extensions that are used in the JWE Header. If any
of the listed extension header parameters are not understood and of the listed extension header parameters are not understood and
supported by the receiver, it MUST reject the JWE. Senders MUST NOT supported by the receiver, it MUST reject the JWE. Senders MUST NOT
include header parameter names defined by [[ this specification ]], include header parameter names defined by [[ this specification ]] or
duplicate names, or names that do not occur as header parameter names by [JWA] for use with JWE, duplicate names, or names that do not
within the JWE Header in the "crit" list. Senders MUST not use the occur as header parameter names within the JWE Header in the "crit"
empty list "[]" as the "crit" value. Recipients MAY reject the JWE list. Senders MUST not use the empty list "[]" as the "crit" value.
if the critical list contains any header parameter names defined by Recipients MAY reject the JWE if the critical list contains any
[[ this specification ]] or any other constraints on its use are header parameter names defined by [[ this specification ]] or by
[JWA] for use with JWE, or any other constraints on its use are
violated. This header parameter MUST be integrity protected, and violated. This header parameter MUST be integrity protected, and
therefore MUST occur only with the JWE Protected Header, when used. therefore MUST occur only with the JWE Protected Header, when used.
Use of this header parameter is OPTIONAL. This header parameter MUST Use of this header parameter is OPTIONAL. This header parameter MUST
be understood by implementations. be understood by implementations.
An example use, along with a hypothetical "exp" (expiration-time) An example use, along with a hypothetical "exp" (expiration-time)
field is: field is:
{"alg":"RSA-OAEP", {"alg":"RSA-OAEP",
"enc":"A256GCM", "enc":"A256GCM",
skipping to change at page 17, line 5 skipping to change at page 16, line 30
1. Determine the Key Management Mode employed by the algorithm used 1. Determine the Key Management Mode employed by the algorithm used
to determine the Content Encryption Key (CEK) value. (This is to determine the Content Encryption Key (CEK) value. (This is
the algorithm recorded in the "alg" (algorithm) header parameter the algorithm recorded in the "alg" (algorithm) header parameter
of the resulting JWE.) of the resulting JWE.)
2. When Key Wrapping, Key Encryption, or Key Agreement with Key 2. When Key Wrapping, Key Encryption, or Key Agreement with Key
Wrapping are employed, generate a random Content Encryption Key Wrapping are employed, generate a random Content Encryption Key
(CEK) value. See RFC 4086 [RFC4086] for considerations on (CEK) value. See RFC 4086 [RFC4086] for considerations on
generating random values. The CEK MUST have a length equal to generating random values. The CEK MUST have a length equal to
that required for the block encryption algorithm. that required for the content encryption algorithm.
3. When Direct Key Agreement or Key Agreement with Key Wrapping are 3. 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 wrap the CEK. upon key will be used to wrap the CEK.
4. When Key Wrapping, Key Encryption, or Key Agreement with Key 4. When Key Wrapping, Key Encryption, or Key Agreement with Key
Wrapping are employed, encrypt the CEK to the recipient (see Wrapping are employed, encrypt the CEK to the recipient and let
Section 6.1) and let the result be the JWE Encrypted Key. the result be the JWE Encrypted Key.
5. Otherwise, when Direct Key Agreement or Direct Encryption are 5. Otherwise, when Direct Key Agreement or Direct Encryption are
employed, let the JWE Encrypted Key be the empty octet sequence. employed, let the JWE Encrypted Key be the empty octet sequence.
6. When Direct Encryption is employed, let the Content Encryption 6. When Direct Encryption is employed, let the Content Encryption
Key (CEK) be the shared symmetric key. Key (CEK) be the shared symmetric key.
7. Base64url encode the JWE Encrypted Key to create the Encoded JWE 7. Base64url encode the JWE Encrypted Key to create the Encoded JWE
Encrypted Key. Encrypted Key.
8. If the JWE JSON Serialization is being used, repeat this process 8. If the JWE JSON Serialization is being used, repeat this process
for each recipient. for each recipient.
9. Generate a random JWE Initialization Vector of the correct size 9. Generate a random JWE Initialization Vector of the correct size
for the block encryption algorithm (if required for the for the content encryption algorithm (if required for the
algorithm); otherwise, let the JWE Initialization Vector be the algorithm); otherwise, let the JWE Initialization Vector be the
empty octet sequence. empty octet sequence.
10. Base64url encode the JWE Initialization Vector to create the 10. Base64url encode the JWE Initialization Vector to create the
Encoded JWE Initialization Vector. Encoded JWE Initialization Vector.
11. Compress the Plaintext if a "zip" parameter was included. 11. Compress the Plaintext if a "zip" parameter was included.
12. Serialize the (compressed) Plaintext into an octet sequence M. 12. Serialize the (compressed) Plaintext into an octet sequence M.
13. Create a JWE Header containing the encryption parameters used. 13. 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.
14. Base64url encode the octets of the UTF-8 representation of the 14. Base64url encode the octets of the UTF-8 representation of the
JWE Protected Header to create the Encoded JWE Header. If the JWE Protected Header to create the Encoded JWE Header. If the
JWE Protected Header is not present (which can only happen when JWE Protected Header is not present (which can only happen when
using the JWE JSON Serialization), let the Encoded JWE Header be using the JWE JSON Serialization and no "protected" member is
the empty string. present), let the Encoded JWE Header be the empty string.
15. Let the Additional Authenticated Data encryption parameter be 15. Let the Additional Authenticated Data encryption parameter be
the octets of the ASCII representation of the Encoded JWE Header the octets of the ASCII representation of the Encoded JWE Header
value. value.
16. Encrypt M using the CEK, the JWE Initialization Vector, and the 16. 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 content
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 encryption operation). from the encryption operation).
17. Base64url encode the JWE Ciphertext to create the Encoded JWE 17. Base64url encode the JWE Ciphertext to create the Encoded JWE
Ciphertext. Ciphertext.
18. Base64url encode the JWE Authentication Tag to create the 18. Base64url encode the JWE Authentication Tag to create the
Encoded JWE Authentication Tag. Encoded JWE Authentication Tag.
19. The five encoded parts are result values used in both the JWE 19. The five encoded parts are result values used in both the JWE
Compact Serialization and the JWE JSON Serialization Compact Serialization and the JWE JSON Serialization
representations. representations.
20. Create the desired serialized output. The JWE Compact 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 8. JWE JSON Serialization is described in Section 7.2.
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
process. The order of the steps is not significant in cases where process. The order of the steps is not significant in cases where
there are no dependencies between the inputs and outputs of the there are no dependencies between the inputs and outputs of the
steps. If any of these steps fails, the JWE MUST be rejected. steps. If any of these steps fails, the JWE MUST be rejected.
1. Parse the serialized input to determine the values of the JWE 1. Parse the serialized input to determine the values of the JWE
Header, the Encoded JWE Encrypted Key, the Encoded 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. When using the JWE Compact Encoded JWE Authentication Tag. When using the JWE Compact
Serialization, the Encoded JWE Header, the Encoded JWE Encrypted Serialization, the Encoded JWE Header, the Encoded JWE Encrypted
Key, the Encoded JWE Initialization Vector, the Encoded JWE Key, the Encoded JWE Initialization Vector, the Encoded JWE
Ciphertext, and the Encoded JWE Authentication Tag are Ciphertext, and the Encoded JWE Authentication Tag are
represented as text strings in that order, separated by four represented as text strings in that order, separated by four
period ('.') characters. The JWE JSON Serialization is period ('.') characters. The JWE JSON Serialization is
described in Section 8. described in Section 7.2.
2. The Encoded JWE Header, the Encoded JWE Encrypted Key, the 2. The Encoded JWE Header, the Encoded JWE Encrypted Key, the
Encoded JWE Initialization Vector, the Encoded JWE Ciphertext, Encoded JWE Initialization Vector, the Encoded JWE Ciphertext,
and the Encoded JWE Authentication Tag MUST be successfully and the Encoded JWE Authentication Tag MUST be successfully
base64url decoded following the restriction that no padding base64url decoded following the restriction that no padding
characters have been used. characters have been used.
3. The resulting JWE Protected Header MUST be a completely valid 3. The resulting JWE Protected Header MUST be a completely valid
JSON object conforming to RFC 4627 [RFC4627]. JSON object conforming to RFC 4627 [RFC4627].
skipping to change at page 19, line 44 skipping to change at page 19, line 22
9. When Direct Key Agreement or Key Agreement with Key Wrapping are 9. 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.
10. When Key Wrapping, Key Encryption, or Key Agreement with Key 10. 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. Note equal to that required for the content encryption algorithm.
that when there are multiple recipients, each recipient will Note that when there are multiple recipients, each recipient
only be able decrypt any JWE Encrypted Key values that were will only be able decrypt any JWE Encrypted Key values that were
encrypted to a key in that recipient's possession. It is encrypted to a key in that recipient's possession. It is
therefore normal to only be able to decrypt one of the per- therefore normal to only be able to decrypt one of the per-
recipient JWE Encrypted Key values to obtain the CEK value. To 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.
skipping to change at page 20, line 27 skipping to change at page 20, line 5
for each recipient contained in the representation until the CEK for each recipient contained in the representation until the CEK
value has been determined. value has been determined.
14. Let the Additional Authenticated Data encryption parameter be 14. Let the Additional Authenticated Data encryption parameter be
the octets of the ASCII representation of the Encoded JWE Header the octets of the ASCII representation of the Encoded JWE Header
value. value.
15. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 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 content 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.
16. Uncompress the decrypted plaintext if a "zip" parameter was 16. Uncompress the decrypted plaintext if a "zip" parameter was
included. included.
17. Output the resulting Plaintext. 17. Output the resulting Plaintext.
skipping to change at page 21, line 5 skipping to change at page 20, line 28
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
performed by comparing Unicode code points without normalization as performed by comparing Unicode code points without normalization as
specified in the String Comparison Rules in Section 5.3 of [JWS]. specified in the String Comparison Rules in Section 5.3 of [JWS].
6. Cryptographic Algorithms 6. Key Identification
JWE uses cryptographic algorithms to encrypt the Plaintext and the
Content Encryption Key (CEK) and to provide integrity protection for
the JWE Protected Header and JWE Ciphertext. The JSON Web Algorithms
(JWA) [JWA] specification specifies a set of cryptographic algorithms
and identifiers to be used with this specification and defines
registries for additional such algorithms. Specifically, Section 4.1
specifies a set of "alg" (algorithm) header parameter values and
Section 4.2 specifies a set of "enc" (encryption method) header
parameter values intended for use this specification. It also
describes the semantics and operations that are specific to these
algorithms.
6.1. CEK Encryption
JWE supports three forms of Content Encryption Key (CEK) encryption:
o Asymmetric encryption under the recipient's public key.
o Symmetric encryption under a key shared between the sender and
receiver.
o Symmetric encryption under a key agreed upon between the sender
and receiver.
See the algorithms registered for "enc" usage in the IANA JSON Web
Signature and Encryption Algorithms registry [JWA] and Section 4.1 of
the JSON Web Algorithms (JWA) [JWA] specification for lists of
encryption algorithms that can be used for CEK encryption.
7. Key Identification
It is necessary for the recipient of a JWE to be able to determine It is necessary for the recipient of a JWE to be able to determine
the key that was employed for the encryption operation. The key the key that was employed for the encryption operation. The key
employed can be identified using the Header Parameter methods employed can be identified using the Header Parameter methods
described in Section 4.1 or can be identified using methods that are described in Section 4.1 or can be identified using methods that are
outside the scope of this specification. Specifically, the Header outside the scope of this specification. Specifically, the Header
Parameters "jku", "jwk", "x5u", "x5t", "x5c", and "kid" can be used Parameters "jku", "jwk", "x5u", "x5t", "x5c", and "kid" can be used
to identify the key used. The sender SHOULD include sufficient to identify the key used. The sender SHOULD include sufficient
information in the Header Parameters to identify the key used, unless information in the Header Parameters to identify the key used, unless
the application uses another means or convention to determine the key the application uses another means or convention to determine the key
used. Recipients MUST reject the input when the key used cannot be used. Recipients MUST reject the input when the key used cannot be
determined. determined.
8. JWE JSON Serialization 7. Serializations
JWE objects use one of two serializations, the JWE Compact
Serialization or the JWE JSON Serialization. The JWE Compact
Serialization is mandatory to implement. Implementation of the JWE
JSON Serialization is OPTIONAL.
7.1. JWE Compact Serialization
The JWE Compact Serialization represents encrypted content as a
compact URL-safe string. This string is the concatenation of the
Encoded JWE Header, the Encoded JWE Encrypted Key, the Encoded JWE
Initialization Vector, the Encoded JWE Ciphertext, and the Encoded
JWE Authentication Tag in that order, with the five strings being
separated by four period ('.') characters. Only one recipient is
supported by the JWE Compact Serialization.
7.2. JWE JSON Serialization
The JWE JSON Serialization represents encrypted content as a JSON The JWE JSON Serialization represents encrypted content as a JSON
object. Unlike the JWE Compact Serialization, content using the JWE object. Unlike the JWE Compact Serialization, content using the JWE
JSON Serialization can be encrypted to more than one recipient. JSON Serialization can be encrypted to more than one recipient.
The representation is closely related to that used in the JWE Compact The representation is closely related to that used in the JWE Compact
Serialization, with the following differences for the JWE JSON Serialization, with the following differences for the JWE JSON
Serialization: Serialization:
o Values in the JWE JSON Serialization are represented as members of o Values in the JWE JSON Serialization are represented as members of
skipping to change at page 24, line 34 skipping to change at page 23, line 45
in potentially significant space savings if the message is large. in potentially significant space savings if the message is large.
Therefore, all header parameters that specify the treatment of the Therefore, all header parameters that specify the treatment of the
Plaintext value MUST be the same for all recipients. This primarily Plaintext value MUST be the same for all recipients. This primarily
means that the "enc" (encryption method) header parameter value in means that the "enc" (encryption method) header parameter value in
the JWE Header for each recipient and any parameters of that the JWE Header for each recipient and any parameters of that
algorithm MUST be the same. algorithm MUST be the same.
See Appendix A.4 for an example of computing a JWE using the JWE JSON See Appendix A.4 for an example of computing a JWE using the JWE JSON
Serialization. Serialization.
9. Implementation Considerations 8. Distinguishing Between JWS and JWE Objects
The JWE Compact Serialization is mandatory to implement. There are several ways of distinguishing whether an object is a JWS
Implementation of the JWE JSON Serialization is OPTIONAL. or JWE object. All these methods will yield the same result for all
legal input values.
10. IANA Considerations o If the object is using the JWS Compact Serialization or the JWE
Compact Serialization, the number of base64url encoded segments
separated by period ('.') characters differs for JWSs and JWEs.
JWSs have three segments separated by two period ('.') characters.
JWEs have five segments separated by four period ('.') characters.
10.1. Registration of JWE Header Parameter Names o If the object is using the JWS JSON Serialization or the JWE JSON
Serialization, the members used will be different. JWSs have a
"signatures" member and JWEs do not. JWEs have a "recipients"
member and JWSs do not.
o A JWS Header can be distinguished from a JWE header by examining
the "alg" (algorithm) header parameter value. If the value
represents a digital signature or MAC algorithm, or is the value
"none", it is for a JWS; if it represents a Key Encryption, Key
Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping,
or Direct Encryption algorithm, it is for a JWE.
o A JWS Header can also be distinguished from a JWE header by
determining whether an "enc" (encryption method) member exists.
If the "enc" member exists, it is a JWE; otherwise, it is a JWS.
9. IANA Considerations
9.1. Registration of JWE Header Parameter Names
This specification registers the Header Parameter Names defined in This specification registers the Header Parameter Names defined in
Section 4.1 in the IANA JSON Web Signature and Encryption Header Section 4.1 in the IANA JSON Web Signature and Encryption Header
Parameters registry [JWS]. Parameters registry [JWS].
10.1.1. Registry Contents 9.1.1. Registry Contents
o Header Parameter Name: "alg" o Header Parameter Name: "alg"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.1 of [[ this document ]] o Specification Document(s): Section 4.1.1 of [[ this document ]]
o Header Parameter Name: "enc" o Header Parameter Name: "enc"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.2 of [[ this document ]] o Specification Document(s): Section 4.1.2 of [[ this document ]]
o Header Parameter Name: "epk"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF
o Specification Document(s): Section 4.1.3 of [[ this document ]]
o Header Parameter Name: "zip" o Header Parameter Name: "zip"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.4 of [[ this document ]] o Specification Document(s): Section 4.1.3 of [[ this document ]]
o Header Parameter Name: "jku" o Header Parameter Name: "jku"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.5 of [[ this document ]] o Specification Document(s): Section 4.1.4 of [[ this document ]]
o Header Parameter Name: "jwk" o Header Parameter Name: "jwk"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification document(s): Section 4.1.6 of [[ this document ]] o Specification document(s): Section 4.1.5 of [[ this document ]]
o Header Parameter Name: "x5u" o Header Parameter Name: "x5u"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.7 of [[ this document ]] o Specification Document(s): Section 4.1.6 of [[ this document ]]
o Header Parameter Name: "x5t" o Header Parameter Name: "x5t"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.8 of [[ this document ]] o Specification Document(s): Section 4.1.7 of [[ this document ]]
o Header Parameter Name: "x5c" o Header Parameter Name: "x5c"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.9 of [[ this document ]] o Specification Document(s): Section 4.1.8 of [[ this document ]]
o Header Parameter Name: "kid" o Header Parameter Name: "kid"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.10 of [[ this document ]] o Specification Document(s): Section 4.1.9 of [[ this document ]]
o Header Parameter Name: "typ" o Header Parameter Name: "typ"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.11 of [[ this document ]] o Specification Document(s): Section 4.1.10 of [[ this document ]]
o Header Parameter Name: "cty" o Header Parameter Name: "cty"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.12 of [[ this document ]]
o Header Parameter Name: "apu"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF
o Specification Document(s): Section 4.1.13 of [[ this document ]]
o Header Parameter Name: "crit"
o Header Parameter Usage Location(s): JWS
o Change Controller: IETF
o Specification Document(s): Section 4.1.14 of [[ this document ]]
10.2. JSON Web Signature and Encryption Type Values Registration
10.2.1. Registry Contents
This specification registers the "JWE" and "JWE+JSON" type values in
the IANA JSON Web Signature and Encryption Type Values registry
[JWS]:
o "typ" Header Parameter Value: "JWE"
o Abbreviation for MIME Type: application/jwe
o Change Controller: IETF
o Specification Document(s): Section 4.1.11 of [[ this document ]] o Specification Document(s): Section 4.1.11 of [[ this document ]]
o "typ" Header Parameter Value: "JWE+JSON" o Header Parameter Name: "crit"
o Abbreviation for MIME Type: application/jwe+json o Header Parameter Usage Location(s): JWE
o Change Controller: IETF
o Specification Document(s): Section 4.1.11 of [[ this document ]]
10.3. Media Type Registration
10.3.1. Registry Contents
This specification registers the "application/jwe" and
"application/jwe+json" Media Types [RFC2046] in the MIME Media Type
registry [RFC4288] to indicate, respectively, that the content is a
JWE using the JWE Compact Serialization or a JWE using the JWE JSON
Serialization.
o Type Name: application
o Subtype Name: jwe
o Required Parameters: n/a
o Optional Parameters: n/a
o Encoding considerations: JWE values are encoded as a series of
base64url encoded values (some of which may be the empty string)
separated by period ('.') characters
o Security Considerations: See the Security Considerations section
of [[ this document ]]
o Interoperability Considerations: n/a
o Published Specification: [[ this document ]]
o Applications that use this media type: OpenID Connect and other
applications using encrypted JWTs
o Additional Information: Magic number(s): n/a, File extension(s):
n/a, Macintosh file type code(s): n/a
o Person & email address to contact for further information: Michael
B. Jones, mbj@microsoft.com
o Intended Usage: COMMON
o Restrictions on Usage: none
o Author: Michael B. Jones, mbj@microsoft.com
o Change Controller: IETF
o Type Name: application
o Subtype Name: jwe+json
o Required Parameters: n/a
o Optional Parameters: n/a
o Encoding considerations: application/jwe+json values are
represented as a JSON Object; UTF-8 encoding SHOULD be employed
for the JSON object.
o Security Considerations: See the Security Considerations section
of [[ this document ]]
o Interoperability Considerations: n/a
o Published Specification: [[ this document ]]
o Applications that use this media type: TBD
o Additional Information: Magic number(s): n/a, File extension(s):
n/a, Macintosh file type code(s): n/a
o Person & email address to contact for further information: Michael
B. Jones, mbj@microsoft.com
o Intended Usage: COMMON
o Restrictions on Usage: none
o Author: Michael B. Jones, mbj@microsoft.com
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1.12 of [[ this document ]]
11. Security Considerations 10. Security Considerations
All of the security issues faced by any cryptographic application All of the security issues faced by any cryptographic application
must be faced by a JWS/JWE/JWK agent. Among these issues are must be faced by a JWS/JWE/JWK agent. Among these issues are
protecting the user's private and symmetric keys, preventing various protecting the user's private and symmetric keys, preventing various
attacks, and helping the user avoid mistakes such as inadvertently attacks, and helping the user avoid mistakes such as inadvertently
encrypting a message for the wrong recipient. The entire list of encrypting a message for the wrong recipient. The entire list of
security considerations is beyond the scope of this document. security considerations is beyond the scope of this document.
All the security considerations in the JWS specification also apply All the security considerations in the JWS specification also apply
to this specification. Likewise, all the security considerations in to this specification. Likewise, all the security considerations in
skipping to change at page 28, line 35 skipping to change at page 26, 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.
12. References 11. References
12.1. Normative References 11.1. Normative References
[ECMAScript]
Ecma International, "ECMAScript Language Specification,
5.1 Edition", ECMA 262, June 2011.
[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.
[JWA] Jones, M., "JSON Web Algorithms (JWA)", [JWA] Jones, M., "JSON Web Algorithms (JWA)",
draft-ietf-jose-json-web-algorithms (work in progress), draft-ietf-jose-json-web-algorithms (work in progress),
May 2013. July 2013.
[JWK] Jones, M., "JSON Web Key (JWK)", [JWK] Jones, M., "JSON Web Key (JWK)",
draft-ietf-jose-json-web-key (work in progress), May 2013. draft-ietf-jose-json-web-key (work in progress),
July 2013.
[JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", draft-ietf-jose-json-web-signature (work Signature (JWS)", draft-ietf-jose-json-web-signature (work
in progress), May 2013. in progress), July 2013.
[RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic
Mail: Part I: Message Encryption and Authentication Mail: Part I: Message Encryption and Authentication
Procedures", RFC 1421, February 1993. Procedures", RFC 1421, February 1993.
[RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification
version 1.3", RFC 1951, May 1996. version 1.3", RFC 1951, May 1996.
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046, Extensions (MIME) Part Two: Media Types", RFC 2046,
skipping to change at page 29, line 36 skipping to change at page 27, line 35
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003. 10646", STD 63, RFC 3629, November 2003.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005. RFC 3986, January 2005.
[RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness
Requirements for Security", BCP 106, RFC 4086, June 2005. Requirements for Security", BCP 106, RFC 4086, June 2005.
[RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and
Registration Procedures", RFC 4288, December 2005.
[RFC4627] Crockford, D., "The application/json Media Type for [RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006. JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, October 2006. Encodings", RFC 4648, October 2006.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008. (TLS) Protocol Version 1.2", RFC 5246, August 2008.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
skipping to change at page 30, line 12 skipping to change at page 28, line 7
Infrastructure Certificate and Certificate Revocation List Infrastructure Certificate and Certificate Revocation List
(CRL) Profile", RFC 5280, May 2008. (CRL) Profile", RFC 5280, May 2008.
[W3C.CR-xmlenc-core1-20120313] [W3C.CR-xmlenc-core1-20120313]
Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch,
"XML Encryption Syntax and Processing Version 1.1", World "XML Encryption Syntax and Processing Version 1.1", World
Wide Web Consortium CR CR-xmlenc-core1-20120313, Wide Web Consortium CR CR-xmlenc-core1-20120313,
March 2012, March 2012,
<http://www.w3.org/TR/2012/CR-xmlenc-core1-20120313>. <http://www.w3.org/TR/2012/CR-xmlenc-core1-20120313>.
12.2. Informative References 11.2. Informative References
[I-D.mcgrew-aead-aes-cbc-hmac-sha2] [I-D.mcgrew-aead-aes-cbc-hmac-sha2]
McGrew, D. and K. Paterson, "Authenticated Encryption with McGrew, D. and K. Paterson, "Authenticated Encryption with
AES-CBC and HMAC-SHA", AES-CBC and HMAC-SHA",
draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress), draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress),
October 2012. October 2012.
[I-D.rescorla-jsms] [I-D.rescorla-jsms]
Rescorla, E. and J. Hildebrand, "JavaScript Message Rescorla, E. and J. Hildebrand, "JavaScript Message
Security Format", draft-rescorla-jsms-00 (work in Security Format", draft-rescorla-jsms-00 (work in
progress), March 2011. progress), March 2011.
[JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple
Encryption", September 2010. Encryption", September 2010.
[JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", draft-ietf-oauth-json-web-token (work in
progress), May 2013.
[RFC3218] Rescorla, E., "Preventing the Million Message Attack on [RFC3218] Rescorla, E., "Preventing the Million Message Attack on
Cryptographic Message Syntax", RFC 3218, January 2002. Cryptographic Message Syntax", RFC 3218, January 2002.
[RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally
Unique IDentifier (UUID) URN Namespace", RFC 4122, Unique IDentifier (UUID) URN Namespace", RFC 4122,
July 2005. July 2005.
[RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70,
RFC 5652, September 2009. RFC 5652, September 2009.
Appendix A. JWE Examples Appendix A. JWE Examples
This section provides examples of JWE computations. This section provides examples of JWE computations.
A.1. Example JWE using RSAES OAEP and AES GCM A.1. Example JWE using RSAES OAEP and AES GCM
This example encrypts the plaintext "The true sign of intelligence is This example encrypts the plaintext "The true sign of intelligence is
not knowledge but imagination." to the recipient using RSAES OAEP and not knowledge but imagination." to the recipient using RSAES OAEP for
AES GCM. The representation of this plaintext is: key encryption and AES GCM for content encryption. The
representation of this plaintext is:
[84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32,
111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99,
101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108,
101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105,
110, 97, 116, 105, 111, 110, 46] 110, 97, 116, 105, 111, 110, 46]
A.1.1. JWE Header A.1.1. JWE Header
The following example JWE Header declares that: The following example JWE Header declares that:
skipping to change at page 31, line 42 skipping to change at page 29, line 36
Generate a 256 bit random Content Encryption Key (CEK). In this Generate a 256 bit random Content Encryption Key (CEK). In this
example, the value is: example, the value is:
[177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154,
212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122,
234, 64, 252] 234, 64, 252]
A.1.4. Key Encryption A.1.4. Key Encryption
Encrypt the CEK with the recipient's public key using the RSAES OAEP Encrypt the CEK with the recipient's public key using the RSAES OAEP
algorithm to produce the JWE Encrypted Key. In this example, the RSA algorithm to produce the JWE Encrypted Key. This example uses the RSA
key parameters are: key represented in JSON Web Key [JWK] format below (with line breaks
for display purposes only):
+-----------+-------------------------------------------------------+ {"kty":"RSA",
| Parameter | Value | "n":"oahUIoWw0K0usKNuOR6H4wkf4oBUXHTxRvgb48E-BVvxkeDNjbC4he8rUW
| Name | | cJoZmds2h7M70imEVhRU5djINXtqllXI4DFqcI1DgjT9LewND8MW2Krf3S
+-----------+-------------------------------------------------------+ psk_ZkoFnilakGygTwpZ3uesH-PFABNIUYpOiN15dsQRkgr0vEhxN92i2a
| Modulus | [161, 168, 84, 34, 133, 176, 208, 173, 46, 176, 163, | sbOenSZeyaxziK72UwxrrKoExv6kc5twXTq4h-QChLOln0_mtUZwfsRaMS
| | 110, 57, 30, 135, 227, 9, 31, 226, 128, 84, 92, 116, | tPs6mS6XrgxnxbWhojf663tuEQueGC-FCMfra36C9knDFGzKsNa7LZK2dj
| | 241, 70, 248, 27, 227, 193, 62, 5, 91, 241, 145, 224, | YgyD3JR_MB_4NUJW_TqOQtwHYbxevoJArm-L5StowjzGy-_bq6Gw",
| | 205, 141, 176, 184, 133, 239, 43, 81, 103, 9, 161, | "e":"AQAB",
| | 153, 157, 179, 104, 123, 51, 189, 34, 152, 69, 97, | "d":"kLdtIj6GbDks_ApCSTYQtelcNttlKiOyPzMrXHeI-yk1F7-kpDxY4-WY5N
| | 69, 78, 93, 140, 131, 87, 182, 169, 101, 92, 142, 3, | WV5KntaEeXS1j82E375xxhWMHXyvjYecPT9fpwR_M9gV8n9Hrh2anTpTD9
| | 22, 167, 8, 212, 56, 35, 79, 210, 222, 192, 208, 252, | 3Dt62ypW3yDsJzBnTnrYu1iwWRgBKrEYY46qAZIrA2xAwnm2X7uGR1hghk
| | 49, 109, 138, 173, 253, 210, 166, 201, 63, 102, 74, | qDp0Vqj3kbSCz1XyfCs6_LehBwtxHIyh8Ripy40p24moOAbgxVw3rxT_vl
| | 5, 158, 41, 90, 144, 108, 160, 79, 10, 89, 222, 231, | t3UVe4WO3JkJOzlpUf-KTVI2Ptgm-dARxTEtE-id-4OJr0h-K-VFs3VSnd
| | 172, 31, 227, 197, 0, 19, 72, 81, 138, 78, 136, 221, | VTIznSxfyrj8ILL6MG_Uv8YAu7VILSB3lOW085-4qE3DzgrTjgyQ"
| | 121, 118, 196, 17, 146, 10, 244, 188, 72, 113, 55, | }
| | 221, 162, 217, 171, 27, 57, 233, 210, 101, 236, 154, |
| | 199, 56, 138, 239, 101, 48, 198, 186, 202, 160, 76, |
| | 111, 234, 71, 57, 183, 5, 211, 171, 136, 126, 64, 40, |
| | 75, 58, 89, 244, 254, 107, 84, 103, 7, 236, 69, 163, |
| | 18, 180, 251, 58, 153, 46, 151, 174, 12, 103, 197, |
| | 181, 161, 162, 55, 250, 235, 123, 110, 17, 11, 158, |
| | 24, 47, 133, 8, 199, 235, 107, 126, 130, 246, 73, |
| | 195, 20, 108, 202, 176, 214, 187, 45, 146, 182, 118, |
| | 54, 32, 200, 61, 201, 71, 243, 1, 255, 131, 84, 37, |
| | 111, 211, 168, 228, 45, 192, 118, 27, 197, 235, 232, |
| | 36, 10, 230, 248, 190, 82, 182, 140, 35, 204, 108, |
| | 190, 253, 186, 186, 27] |
| Exponent | [1, 0, 1] |
| Private | [144, 183, 109, 34, 62, 134, 108, 57, 44, 252, 10, |
| Exponent | 66, 73, 54, 16, 181, 233, 92, 54, 219, 101, 42, 35, |
| | 178, 63, 51, 43, 92, 119, 136, 251, 41, 53, 23, 191, |
| | 164, 164, 60, 88, 227, 229, 152, 228, 213, 149, 228, |
| | 169, 237, 104, 71, 151, 75, 88, 252, 216, 77, 251, |
| | 231, 28, 97, 88, 193, 215, 202, 248, 216, 121, 195, |
| | 211, 245, 250, 112, 71, 243, 61, 129, 95, 39, 244, |
| | 122, 225, 217, 169, 211, 165, 48, 253, 220, 59, 122, |
| | 219, 42, 86, 223, 32, 236, 39, 48, 103, 78, 122, 216, |
| | 187, 88, 176, 89, 24, 1, 42, 177, 24, 99, 142, 170, |
| | 1, 146, 43, 3, 108, 64, 194, 121, 182, 95, 187, 134, |
| | 71, 88, 96, 134, 74, 131, 167, 69, 106, 143, 121, 27, |
| | 72, 44, 245, 95, 39, 194, 179, 175, 203, 122, 16, |
| | 112, 183, 17, 200, 202, 31, 17, 138, 156, 184, 210, |
| | 157, 184, 154, 131, 128, 110, 12, 85, 195, 122, 241, |
| | 79, 251, 229, 183, 117, 21, 123, 133, 142, 220, 153, |
| | 9, 59, 57, 105, 81, 255, 138, 77, 82, 54, 62, 216, |
| | 38, 249, 208, 17, 197, 49, 45, 19, 232, 157, 251, |
| | 131, 137, 175, 72, 126, 43, 229, 69, 179, 117, 82, |
| | 157, 213, 83, 35, 57, 210, 197, 252, 171, 143, 194, |
| | 11, 47, 163, 6, 253, 75, 252, 96, 11, 187, 84, 130, |
| | 210, 7, 121, 78, 91, 79, 57, 251, 138, 132, 220, 60, |
| | 224, 173, 56, 224, 201] |
+-----------+-------------------------------------------------------+
The resulting JWE Encrypted Key value is: The resulting JWE Encrypted Key value is:
[56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203, [56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203,
22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216, 22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216,
82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220, 82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220,
145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214, 145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214,
74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182, 74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182,
13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228, 13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228,
173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158, 173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158,
skipping to change at page 34, line 25 skipping to change at page 31, line 13
1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi
6UklfCpIMfIjf7iGdXKHzg 6UklfCpIMfIjf7iGdXKHzg
A.1.6. Initialization Vector A.1.6. Initialization Vector
Generate a random 96 bit JWE Initialization Vector. In this example, Generate a random 96 bit JWE Initialization Vector. In this example,
the value is: the value is:
[227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219]
Base64url encoding this value yields the Encoded JWE Initialization Base64url encoding this value yields this Encoded JWE Initialization
Vector value: Vector value:
48V1_ALb6US04U3b 48V1_ALb6US04U3b
A.1.7. Additional Authenticated Data A.1.7. Additional Authenticated Data
Let the Additional Authenticated Data encryption parameter be the Let the Additional Authenticated Data encryption parameter be the
octets of the ASCII representation of the Encoded JWE Header value. octets of the ASCII representation of the Encoded JWE Header value.
This AAD value is: This AAD value is:
skipping to change at page 36, line 7 skipping to change at page 32, line 39
mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8
1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi
6UklfCpIMfIjf7iGdXKHzg. 6UklfCpIMfIjf7iGdXKHzg.
48V1_ALb6US04U3b. 48V1_ALb6US04U3b.
5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji
SdiwkIr3ajwQzaBtQD_A. SdiwkIr3ajwQzaBtQD_A.
XFBoMYUZodetZdvTiFvSkQ XFBoMYUZodetZdvTiFvSkQ
A.1.12. Validation A.1.12. Validation
This example illustrates the process of creating a JWE with RSA OAEP This example illustrates the process of creating a JWE with RSAES
and AES GCM. These results can be used to validate JWE decryption OAEP for key encryption and AES GCM for content encryption. These
implementations for these algorithms. Note that since the RSAES OAEP results can be used to validate JWE decryption implementations for
computation includes random values, the encryption results above will these algorithms. Note that since the RSAES OAEP computation
not be completely reproducible. However, since the AES GCM includes random values, the encryption results above will not be
computation is deterministic, the JWE Encrypted Ciphertext values completely reproducible. However, since the AES GCM computation is
will be the same for all encryptions performed using these inputs. deterministic, the JWE Encrypted Ciphertext values will be the same
for all encryptions performed using these inputs.
A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256
This example encrypts the plaintext "Live long and prosper." to the This example encrypts the plaintext "Live long and prosper." to the
recipient using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256. The recipient using RSAES-PKCS1-V1_5 for key encryption and
representation of this plaintext is: AES_128_CBC_HMAC_SHA_256 for content encryption. The representation
of this plaintext is:
[76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32,
112, 114, 111, 115, 112, 101, 114, 46] 112, 114, 111, 115, 112, 101, 114, 46]
A.2.1. JWE Header A.2.1. JWE Header
The following example JWE Header (with line breaks for display The following example JWE Header (with line breaks for display
purposes only) declares that: purposes only) declares that:
o the Content Encryption Key is encrypted to the recipient using the o the Content Encryption Key is encrypted to the recipient using the
skipping to change at page 37, line 8 skipping to change at page 33, line 42
Generate a 256 bit random Content Encryption Key (CEK). In this Generate a 256 bit random Content Encryption Key (CEK). In this
example, the key value is: example, the key value is:
[4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106,
206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156,
44, 207] 44, 207]
A.2.4. Key Encryption A.2.4. Key Encryption
Encrypt the CEK with the recipient's public key using the RSAES- Encrypt the CEK with the recipient's public key using the RSAES-
PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. In this PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. This example
example, the RSA key parameters are: uses the RSA key represented in JSON Web Key [JWK] format below (with
line breaks for display purposes only):
+-----------+-------------------------------------------------------+ {"kty":"RSA",
| Parameter | Value | "n":"sXchDaQebHnPiGvyDOAT4saGEUetSyo9MKLOoWFsueri23bOdgWp4Dy1Wl
| Name | | UzewbgBHod5pcM9H95GQRV3JDXboIRROSBigeC5yjU1hGzHHyXss8UDpre
+-----------+-------------------------------------------------------+ cbAYxknTcQkhslANGRUZmdTOQ5qTRsLAt6BTYuyvVRdhS8exSZEy_c4gs_
| Modulus | [177, 119, 33, 13, 164, 30, 108, 121, 207, 136, 107, | 7svlJJQ4H9_NxsiIoLwAEk7-Q3UXERGYw_75IDrGA84-lA_-Ct4eTlXHBI
| | 242, 12, 224, 19, 226, 198, 134, 17, 71, 173, 75, 42, | Y2EaV7t7LjJaynVJCpkv4LKjTTAumiGUIuQhrNhZLuF_RJLqHpM2kgWFLU
| | 61, 48, 162, 206, 161, 97, 108, 185, 234, 226, 219, | 7-VTdL1VbC2tejvcI2BlMkEpk1BzBZI0KQB0GaDWFLN-aEAw3vRw",
| | 118, 206, 118, 5, 169, 224, 60, 181, 90, 85, 51, 123, | "e":"AQAB",
| | 6, 224, 4, 122, 29, 230, 151, 12, 244, 127, 121, 25, | "d":"VFCWOqXr8nvZNyaaJLXdnNPXZKRaWCjkU5Q2egQQpTBMwhprMzWzpR8Sxq
| | 4, 85, 220, 144, 215, 110, 130, 17, 68, 228, 129, | 1OPThh_J6MUD8Z35wky9b8eEO0pwNS8xlh1lOFRRBoNqDIKVOku0aZb-ry
| | 138, 7, 130, 231, 40, 212, 214, 17, 179, 28, 124, | nq8cxjDTLZQ6Fz7jSjR1Klop-YKaUHc9GsEofQqYruPhzSA-QgajZGPbE_
| | 151, 178, 207, 20, 14, 154, 222, 113, 176, 24, 198, | 0ZaVDJHfyd7UUBUKunFMScbflYAAOYJqVIVwaYR5zWEEceUjNnTNo_CVSj
| | 73, 211, 113, 9, 33, 178, 80, 13, 25, 21, 25, 153, | -VvXLO5VZfCUAVLgW4dpf1SrtZjSt34YLsRarSb127reG_DUwg9Ch-Kyvj
| | 212, 206, 67, 154, 147, 70, 194, 192, 183, 160, 83, | T1SkHgUWRVGcyly7uvVGRSDwsXypdrNinPA4jlhoNdizK2zF2CWQ"
| | 98, 236, 175, 85, 23, 97, 75, 199, 177, 73, 145, 50, | }
| | 253, 206, 32, 179, 254, 236, 190, 82, 73, 67, 129, |
| | 253, 252, 220, 108, 136, 138, 11, 192, 1, 36, 239, |
| | 228, 55, 81, 113, 17, 25, 140, 63, 239, 146, 3, 172, |
| | 96, 60, 227, 233, 64, 255, 224, 173, 225, 228, 229, |
| | 92, 112, 72, 99, 97, 26, 87, 187, 123, 46, 50, 90, |
| | 202, 117, 73, 10, 153, 47, 224, 178, 163, 77, 48, 46, |
| | 154, 33, 148, 34, 228, 33, 172, 216, 89, 46, 225, |
| | 127, 68, 146, 234, 30, 147, 54, 146, 5, 133, 45, 78, |
| | 254, 85, 55, 75, 213, 86, 194, 218, 215, 163, 189, |
| | 194, 54, 6, 83, 36, 18, 153, 53, 7, 48, 89, 35, 66, |
| | 144, 7, 65, 154, 13, 97, 75, 55, 230, 132, 3, 13, |
| | 239, 71] |
| Exponent | [1, 0, 1] |
| Private | [84, 80, 150, 58, 165, 235, 242, 123, 217, 55, 38, |
| Exponent | 154, 36, 181, 221, 156, 211, 215, 100, 164, 90, 88, |
| | 40, 228, 83, 148, 54, 122, 4, 16, 165, 48, 76, 194, |
| | 26, 107, 51, 53, 179, 165, 31, 18, 198, 173, 78, 61, |
| | 56, 97, 252, 158, 140, 80, 63, 25, 223, 156, 36, 203, |
| | 214, 252, 120, 67, 180, 167, 3, 82, 243, 25, 97, 214, |
| | 83, 133, 69, 16, 104, 54, 160, 200, 41, 83, 164, 187, |
| | 70, 153, 111, 234, 242, 158, 175, 28, 198, 48, 211, |
| | 45, 148, 58, 23, 62, 227, 74, 52, 117, 42, 90, 41, |
| | 249, 130, 154, 80, 119, 61, 26, 193, 40, 125, 10, |
| | 152, 174, 227, 225, 205, 32, 62, 66, 6, 163, 100, 99, |
| | 219, 19, 253, 25, 105, 80, 201, 29, 252, 157, 237, |
| | 69, 1, 80, 171, 167, 20, 196, 156, 109, 249, 88, 0, |
| | 3, 152, 38, 165, 72, 87, 6, 152, 71, 156, 214, 16, |
| | 71, 30, 82, 51, 103, 76, 218, 63, 9, 84, 163, 249, |
| | 91, 215, 44, 238, 85, 101, 240, 148, 1, 82, 224, 91, |
| | 135, 105, 127, 84, 171, 181, 152, 210, 183, 126, 24, |
| | 46, 196, 90, 173, 38, 245, 219, 186, 222, 27, 240, |
| | 212, 194, 15, 66, 135, 226, 178, 190, 52, 245, 74, |
| | 65, 224, 81, 100, 85, 25, 204, 165, 203, 187, 175, |
| | 84, 100, 82, 15, 11, 23, 202, 151, 107, 54, 41, 207, |
| | 3, 136, 229, 134, 131, 93, 139, 50, 182, 204, 93, |
| | 130, 89] |
+-----------+-------------------------------------------------------+
The resulting JWE Encrypted Key value is: The resulting JWE Encrypted Key value is:
[80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151, [80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151,
176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181, 176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181,
156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156, 156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156,
116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223, 116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223,
226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66, 226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66,
212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253, 212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253,
215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128, 215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128,
skipping to change at page 39, line 26 skipping to change at page 35, line 14
-B3oWh2TbqmScqXMR4gp_A -B3oWh2TbqmScqXMR4gp_A
A.2.6. Initialization Vector A.2.6. Initialization Vector
Generate a random 128 bit JWE Initialization Vector. In this Generate a random 128 bit JWE Initialization Vector. In this
example, the value is: example, the value is:
[3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104,
101] 101]
Base64url encoding this value yields the Encoded JWE Initialization Base64url encoding this value yields this Encoded JWE Initialization
Vector value: Vector value:
AxY8DCtDaGlsbGljb3RoZQ AxY8DCtDaGlsbGljb3RoZQ
A.2.7. Additional Authenticated Data A.2.7. Additional Authenticated Data
Let the Additional Authenticated Data encryption parameter be the Let the Additional Authenticated Data encryption parameter be the
octets of the ASCII representation of the Encoded JWE Header value. octets of the ASCII representation of the Encoded JWE Header value.
This AAD value is: This AAD value is:
skipping to change at page 40, line 49 skipping to change at page 36, line 40
NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8
rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv
-B3oWh2TbqmScqXMR4gp_A. -B3oWh2TbqmScqXMR4gp_A.
AxY8DCtDaGlsbGljb3RoZQ. AxY8DCtDaGlsbGljb3RoZQ.
KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.
9hH0vgRfYgPnAHOd8stkvw 9hH0vgRfYgPnAHOd8stkvw
A.2.12. Validation A.2.12. Validation
This example illustrates the process of creating a JWE with RSAES- This example illustrates the process of creating a JWE with RSAES-
PKCS1-V1_5 and AES_CBC_HMAC_SHA2. These results can be used to PKCS1-V1_5 for key encryption and AES_CBC_HMAC_SHA2 for content
validate JWE decryption implementations for these algorithms. Note encryption. These results can be used to validate JWE decryption
that since the RSAES-PKCS1-V1_5 computation includes random values, implementations for these algorithms. Note that since the RSAES-
the encryption results above will not be completely reproducible. PKCS1-V1_5 computation includes random values, the encryption results
However, since the AES CBC computation is deterministic, the JWE above will not be completely reproducible. However, since the AES
Encrypted Ciphertext values will be the same for all encryptions CBC computation is deterministic, the JWE Encrypted Ciphertext values
performed using these inputs. will be the same for all encryptions performed using these inputs.
A.3. Example JWE using AES Key Wrap and AES GCM A.3. Example JWE using AES Key Wrap and AES GCM
This example encrypts the plaintext "Live long and prosper." to the This example encrypts the plaintext "Live long and prosper." to the
recipient using AES Key Wrap and AES GCM. The representation of this recipient using AES Key Wrap for key encryption and AES GCM for
plaintext is: content encryption. The representation of this plaintext is:
[76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32,
112, 114, 111, 115, 112, 101, 114, 46] 112, 114, 111, 115, 112, 101, 114, 46]
A.3.1. JWE Header A.3.1. JWE Header
The following example JWE Header declares that: The following example JWE Header declares that:
o the Content Encryption Key is encrypted to the recipient using the o the Content Encryption Key is encrypted to the recipient using the
AES Key Wrap algorithm with a 128 bit key to produce the JWE AES Key Wrap algorithm with a 128 bit key to produce the JWE
skipping to change at page 41, line 50 skipping to change at page 37, line 40
Generate a 256 bit random Content Encryption Key (CEK). In this Generate a 256 bit random Content Encryption Key (CEK). In this
example, the value is: example, the value is:
[4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106,
206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156,
44, 207] 44, 207]
A.3.4. Key Encryption A.3.4. Key Encryption
Encrypt the CEK with the shared symmetric key using the AES Key Wrap Encrypt the CEK with the shared symmetric key using the AES Key Wrap
algorithm to produce the JWE Encrypted Key. In this example, the algorithm to produce the JWE Encrypted Key. This example uses the
shared symmetric key value is: symmetric key represented in JSON Web Key [JWK] format below:
[25, 172, 32, 130, 225, 114, 26, 181, 138, 106, 254, 192, 95, 133, {"kty":"oct",
74, 82] "k":"GawgguFyGrWKav7AX4VKUg"
}
The resulting JWE Encrypted Key value is: The resulting JWE Encrypted Key value is:
[232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216,
22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3,
76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 76, 124, 193, 11, 98, 37, 173, 61, 104, 57]
A.3.5. Encoded JWE Encrypted Key A.3.5. Encoded JWE Encrypted Key
Base64url encode the JWE Encrypted Key to produce the Encoded JWE Base64url encode the JWE Encrypted Key to produce the Encoded JWE
skipping to change at page 42, line 30 skipping to change at page 38, line 20
6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ
A.3.6. Initialization Vector A.3.6. Initialization Vector
Generate a random 128 bit JWE Initialization Vector. In this Generate a random 128 bit JWE Initialization Vector. In this
example, the value is: example, the value is:
[3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104,
101] 101]
Base64url encoding this value yields the Encoded JWE Initialization Base64url encoding this value yields this Encoded JWE Initialization
Vector value: Vector value:
AxY8DCtDaGlsbGljb3RoZQ AxY8DCtDaGlsbGljb3RoZQ
A.3.7. Additional Authenticated Data A.3.7. Additional Authenticated Data
Let the Additional Authenticated Data encryption parameter be the Let the Additional Authenticated Data encryption parameter be the
octets of the ASCII representation of the Encoded JWE Header value. octets of the ASCII representation of the Encoded JWE Header value.
This AAD value is: This AAD value is:
skipping to change at page 43, line 49 skipping to change at page 39, line 39
purposes only) is: purposes only) is:
eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0.
6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ.
AxY8DCtDaGlsbGljb3RoZQ. AxY8DCtDaGlsbGljb3RoZQ.
KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.
U0m_YmjN04DJvceFICbCVQ U0m_YmjN04DJvceFICbCVQ
A.3.12. Validation A.3.12. Validation
This example illustrates the process of creating a JWE with symmetric This example illustrates the process of creating a JWE with AES Key
key wrap and AES_CBC_HMAC_SHA2. These results can be used to Wrap for key encryption and AES GCM for content encryption. These
validate JWE decryption implementations for these algorithms. Also, results can be used to validate JWE decryption implementations for
since both the AES Key Wrap and AES GCM computations are these algorithms. Also, since both the AES Key Wrap and AES GCM
deterministic, the resulting JWE value will be the same for all computations are deterministic, the resulting JWE value will be the
encryptions performed using these inputs. Since the computation is same for all encryptions performed using these inputs. Since the
reproducible, these results can also be used to validate JWE computation is reproducible, these results can also be used to
encryption implementations for these algorithms. validate JWE encryption implementations for these algorithms.
A.4. Example JWE Using JWE JSON Serialization A.4. Example JWE Using JWE JSON Serialization
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 algorithm and key Two recipients are present in this example. The algorithm and key
used for the first recipient are the same as that used in used for the first recipient are the same as that used in
Appendix A.2. The algorithm and key used for the second recipient Appendix A.2. The algorithm and key used for the second recipient
skipping to change at page 49, line 21 skipping to change at page 45, line 13
194, 85] 194, 85]
Appendix C. Acknowledgements Appendix C. 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
discussions that helped inform the content of this specification and discussions that helped inform the content of this specification and
to Eric Rescorla and Joe Hildebrand for allowing the reuse of text to Eric Rescorla and Joe Hildebrand for allowing the reuse of text
from [I-D.rescorla-jsms] in this document. from [I-D.rescorla-jsms] in this document.
Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund
Jay for validating the examples in this specification. Jay for validating the examples in this specification.
This specification is the work of the JOSE Working Group, which This specification is the work of the JOSE Working Group, which
skipping to change at page 49, line 49 skipping to change at page 45, line 41
Hannes Tschofenig, and Sean Turner. Hannes 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 D. 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 ]]
-12
o Clarified that the "typ" and "cty" header parameters are used in
an application-specific manner and have no effect upon the JWE
processing.
o Replaced the MIME types "application/jwe+json" and
"application/jwe" with "application/jose+json" and
"application/jose".
o Stated that receipients MUST either reject JWEs with duplicate
Header Parameter Names or use a JSON parser that returns only the
lexically last duplicate member name.
o Moved the "epk", "apu", and "apv" Header Parameter definitions to
be with the algorithm descriptions that use them.
o Added a Serializations section with parallel treatment of the JWE
Compact Serialization and the JWE JSON Serialization and also
moved the former Implementation Considerations content there.
o Restored use of the term "AEAD".
o Changed terminology from "block encryption" to "content
encryption".
-11 -11
o Added Key Identification section. o Added Key Identification section.
o Removed the Encrypted Key value from the AAD computation since it o Removed the Encrypted Key value from the AAD computation since it
is already effectively integrity protected by the encryption is already effectively integrity protected by the encryption
process. The AAD value now only contains the representation of process. The AAD value now only contains the representation of
the JWE Encrypted Header. the JWE Encrypted Header.
o For the JWE JSON Serialization, enable header parameter values to o For the JWE JSON Serialization, enable header parameter values to
be specified in any of three parameters: the "protected" member be specified in any of three parameters: the "protected" member
that is integrity protected and shared among all recipients, the that is integrity protected and shared among all recipients, the
 End of changes. 91 change blocks. 
500 lines changed or deleted 356 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/