< draft-ietf-jose-json-web-encryption-12.txt   draft-ietf-jose-json-web-encryption-13.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: January 12, 2014 RTFM Expires: January 16, 2014 RTFM
J. Hildebrand J. Hildebrand
Cisco Cisco
July 11, 2013 July 15, 2013
JSON Web Encryption (JWE) JSON Web Encryption (JWE)
draft-ietf-jose-json-web-encryption-12 draft-ietf-jose-json-web-encryption-13
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 January 12, 2014. This Internet-Draft will expire on January 16, 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 41 skipping to change at page 2, line 41
4.2. Public Header Parameter Names . . . . . . . . . . . . . . 15 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 15
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. Key Identification . . . . . . . . . . . . . . . . . . . . . . 20 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 20
7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 20 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 20
7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 21 7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 21
7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 21 7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 21
8. Distinguishing Between JWS and JWE Objects . . . . . . . . . . 23 8. Distinguishing Between JWS and JWE Objects . . . . . . . . . . 24
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24
9.1. Registration of JWE Header Parameter Names . . . . . . . . 24 9.1. Registration of JWE Header Parameter Names . . . . . . . . 24
9.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 24 9.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 25
10. Security Considerations . . . . . . . . . . . . . . . . . . . 26 10. Security Considerations . . . . . . . . . . . . . . . . . . . 26
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26
11.1. Normative References . . . . . . . . . . . . . . . . . . . 26 11.1. Normative References . . . . . . . . . . . . . . . . . . . 26
11.2. Informative References . . . . . . . . . . . . . . . . . . 28 11.2. Informative References . . . . . . . . . . . . . . . . . . 28
Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 28 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 29
A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 28 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 29
A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 29 A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 29
A.1.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 29 A.1.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 29
A.1.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 29 A.1.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 29
A.1.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 29 A.1.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 30
A.1.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 30 A.1.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 30
A.1.6. Initialization Vector . . . . . . . . . . . . . . . . 31 A.1.6. Initialization Vector . . . . . . . . . . . . . . . . 31
A.1.7. Additional Authenticated Data . . . . . . . . . . . . 31 A.1.7. Additional Authenticated Data . . . . . . . . . . . . 31
A.1.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 31 A.1.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 31
A.1.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 31 A.1.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 32
A.1.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 32 A.1.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 32
A.1.11. Complete Representation . . . . . . . . . . . . . . . 32 A.1.11. Complete Representation . . . . . . . . . . . . . . . 32
A.1.12. Validation . . . . . . . . . . . . . . . . . . . . . . 32 A.1.12. Validation . . . . . . . . . . . . . . . . . . . . . . 32
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 . . . . . . . . . . . . . . . . . 32 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 33
A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 33 A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 33
A.2.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 33 A.2.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 33
A.2.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 33 A.2.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 33
A.2.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 33 A.2.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 33
A.2.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 34 A.2.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 34
A.2.6. Initialization Vector . . . . . . . . . . . . . . . . 35 A.2.6. Initialization Vector . . . . . . . . . . . . . . . . 35
A.2.7. Additional Authenticated Data . . . . . . . . . . . . 35 A.2.7. Additional Authenticated Data . . . . . . . . . . . . 35
A.2.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 35 A.2.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 35
A.2.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 35 A.2.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 35
A.2.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 36 A.2.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 36
A.2.11. Complete Representation . . . . . . . . . . . . . . . 36 A.2.11. Complete Representation . . . . . . . . . . . . . . . 36
A.2.12. Validation . . . . . . . . . . . . . . . . . . . . . . 36 A.2.12. Validation . . . . . . . . . . . . . . . . . . . . . . 36
A.3. Example JWE using AES Key Wrap and AES GCM . . . . . . . . 36 A.3. Example JWE using AES Key Wrap and
AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 36
A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 37 A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 37
A.3.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 37 A.3.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 37
A.3.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 37 A.3.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 37
A.3.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 37 A.3.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 37
A.3.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 38 A.3.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 38
A.3.6. Initialization Vector . . . . . . . . . . . . . . . . 38 A.3.6. Initialization Vector . . . . . . . . . . . . . . . . 38
A.3.7. Additional Authenticated Data . . . . . . . . . . . . 38 A.3.7. Additional Authenticated Data . . . . . . . . . . . . 38
A.3.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 38 A.3.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 38
A.3.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 39 A.3.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 39
A.3.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 39 A.3.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 39
skipping to change at page 10, line 46 skipping to change at page 10, line 46
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) representing 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; receipients MUST either reject JWEs the JWE Header MUST be unique; recipients MUST either reject JWEs
with duplicate Header Parameter Names or use a JSON parser that with duplicate Header Parameter Names or use a JSON parser that
returns only the lexically last duplicate member name, as specified returns only the lexically last duplicate member name, as specified
in Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript]. 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
skipping to change at page 19, line 48 skipping to change at page 19, line 48
12. When Direct Encryption is employed, let the Content Encryption 12. When Direct Encryption is employed, let the Content Encryption
Key (CEK) be the shared symmetric key. Key (CEK) be the shared symmetric key.
13. If the JWE JSON Serialization is being used, repeat this process 13. If the JWE JSON Serialization is being used, repeat this process
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. However if a top-level "aad" member is present when
using the JWE JSON Serialization, instead let the Additional
Authenticated Data encryption parameter be the octets of the
ASCII representation of the concatenation of the Encoded JWE
Header value, a period ('.') character, and the "aad" field
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 content 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.
skipping to change at page 22, line 36 skipping to change at page 22, line 40
o The header parameter values used when creating or validating per- o The header parameter values used when creating or validating per-
recipient Ciphertext and Authentication Tag values are the union recipient Ciphertext and Authentication Tag values are the union
of the three sets of header parameter values that may be present: of the three sets of header parameter values that may be present:
(1) the per-recipient values in the "header" member of the (1) the per-recipient values in the "header" member of the
recipient's array element, (2) the shared integrity-protected recipient's array element, (2) the shared integrity-protected
values in the "protected" member, and (3) the shared non- values in the "protected" member, and (3) the shared non-
integrity-protected values in the "unprotected" member. The union integrity-protected values in the "unprotected" member. The union
of these sets of header parameters comprises the JWE Header. The of these sets of header parameters comprises the JWE Header. The
header parameter names in the three locations MUST be disjoint. header parameter names in the three locations MUST be disjoint.
o An "aad" (Additional Authenticated Data) member can be included to
supply a base64url encoded value to be integrity protected but not
encrypted. (Note that this can also be achieved when using either
serialization by including the AAD value as a protected header
parameter value, but at the cost of the value being double
base64url encoded.)
The syntax of a JWE using the JWE JSON Serialization is as follows: The syntax of a JWE using the JWE JSON Serialization is as follows:
{"protected":<integrity-protected shared header contents>", {"protected":<integrity-protected shared header contents>",
"unprotected":<non-integrity-protected shared header contents>", "unprotected":<non-integrity-protected shared header contents>",
"recipients":[ "recipients":[
{"header":"<per-recipient unprotected header 1 contents>", {"header":"<per-recipient unprotected header 1 contents>",
"encrypted_key":"<encrypted key 1 contents>"}, "encrypted_key":"<encrypted key 1 contents>"},
... ...
{"header":"<per-recipient unprotected header N contents>", {"header":"<per-recipient unprotected header N contents>",
"encrypted_key":"<encrypted key N contents>"}], "encrypted_key":"<encrypted key N contents>"}],
"aad":"<additional authenticated data contents>",
"iv":"<initialization vector contents>", "iv":"<initialization vector contents>",
"ciphertext":"<ciphertext contents>", "ciphertext":"<ciphertext contents>",
"tag":"<authentication tag contents>" "tag":"<authentication tag contents>"
} }
Of these members, only the "ciphertext" member MUST be present. The Of these members, only the "ciphertext" member MUST be present. The
"iv", "tag", and "encrypted_key" members MUST be present when "iv", "tag", and "encrypted_key" members MUST be present when
corresponding JWE Initialization Vector, JWE Authentication Tag, and corresponding JWE Initialization Vector, JWE Authentication Tag, and
JWE Encrypted Key values are non-empty. The "recipients" member MUST JWE Encrypted Key values are non-empty. The "recipients" member MUST
be present when any "header" or "encrypted_key" members are needed be present when any "header" or "encrypted_key" members are needed
skipping to change at page 36, line 48 skipping to change at page 36, line 48
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 for key encryption and AES_CBC_HMAC_SHA2 for content PKCS1-V1_5 for key encryption and AES_CBC_HMAC_SHA2 for content
encryption. These results can be used to validate JWE decryption encryption. These results can be used to validate JWE decryption
implementations for these algorithms. Note that since the RSAES- implementations for these algorithms. Note that since the RSAES-
PKCS1-V1_5 computation includes random values, the encryption results PKCS1-V1_5 computation includes random values, the encryption results
above will not be completely reproducible. However, since the AES above will not be completely reproducible. However, since the AES
CBC computation is deterministic, the JWE Encrypted Ciphertext values CBC computation is deterministic, the JWE Encrypted Ciphertext values
will be the same for all encryptions 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_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 AES Key Wrap for key encryption and AES GCM for recipient using AES Key Wrap for key encryption and AES GCM for
content encryption. The representation of this 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
skipping to change at page 45, line 41 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 ]]
-13
o Added an "aad" (Additional Authenticated Data) member for the JWE
JSON Serialization, enabling Additional Authenticated Data to be
supplied that is not double base64url encoded, addressing issue
#29.
-12 -12
o Clarified that the "typ" and "cty" header parameters are used in o Clarified that the "typ" and "cty" header parameters are used in
an application-specific manner and have no effect upon the JWE an application-specific manner and have no effect upon the JWE
processing. processing.
o Replaced the MIME types "application/jwe+json" and o Replaced the MIME types "application/jwe+json" and
"application/jwe" with "application/jose+json" and "application/jwe" with "application/jose+json" and
"application/jose". "application/jose".
o Stated that receipients MUST either reject JWEs with duplicate o Stated that recipients MUST either reject JWEs with duplicate
Header Parameter Names or use a JSON parser that returns only the Header Parameter Names or use a JSON parser that returns only the
lexically last duplicate member name. lexically last duplicate member name.
o Moved the "epk", "apu", and "apv" Header Parameter definitions to o Moved the "epk", "apu", and "apv" Header Parameter definitions to
be with the algorithm descriptions that use them. be with the algorithm descriptions that use them.
o Added a Serializations section with parallel treatment of the JWE o Added a Serializations section with parallel treatment of the JWE
Compact Serialization and the JWE JSON Serialization and also Compact Serialization and the JWE JSON Serialization and also
moved the former Implementation Considerations content there. moved the former Implementation Considerations content there.
 End of changes. 18 change blocks. 
15 lines changed or deleted 36 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/