draft-ietf-jose-json-web-algorithms-10.txt   draft-ietf-jose-json-web-algorithms-11.txt 
JOSE Working Group M. Jones JOSE Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track April 25, 2013 Intended status: Standards Track May 28, 2013
Expires: October 27, 2013 Expires: November 29, 2013
JSON Web Algorithms (JWA) JSON Web Algorithms (JWA)
draft-ietf-jose-json-web-algorithms-10 draft-ietf-jose-json-web-algorithms-11
Abstract Abstract
The JSON Web Algorithms (JWA) specification enumerates cryptographic The JSON Web Algorithms (JWA) specification enumerates cryptographic
algorithms and identifiers to be used with the JSON Web Signature algorithms and identifiers to be used with the JSON Web Signature
(JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK) (JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK)
specifications. specifications.
Status of this Memo Status of this Memo
skipping to change at page 1, line 33 skipping to change at page 1, line 33
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on October 27, 2013. This Internet-Draft will expire on November 29, 2013.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 12 skipping to change at page 2, line 12
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1. Terms Incorporated from the JWS Specification . . . . . . 4 2.1. Terms Incorporated from the JWS Specification . . . . . . 4
2.2. Terms Incorporated from the JWE Specification . . . . . . 5 2.2. Terms Incorporated from the JWE Specification . . . . . . 5
2.3. Terms Incorporated from the JWK Specification . . . . . . 7 2.3. Terms Incorporated from the JWK Specification . . . . . . 8
2.4. Defined Terms . . . . . . . . . . . . . . . . . . . . . . 8 2.4. Defined Terms . . . . . . . . . . . . . . . . . . . . . . 8
3. Cryptographic Algorithms for JWS . . . . . . . . . . . . . . . 8 3. Cryptographic Algorithms for JWS . . . . . . . . . . . . . . . 8
3.1. "alg" (Algorithm) Header Parameter Values for JWS . . . . 8 3.1. "alg" (Algorithm) Header Parameter Values for JWS . . . . 8
3.2. MAC with HMAC SHA-256, HMAC SHA-384, or HMAC SHA-512 . . . 9 3.2. MAC with HMAC SHA-256, HMAC SHA-384, or HMAC SHA-512 . . . 9
3.3. Digital Signature with RSA SHA-256, RSA SHA-384, or 3.3. Digital Signature with RSASSA-PKCS1-V1_5 and SHA-256,
RSA SHA-512 . . . . . . . . . . . . . . . . . . . . . . . 10 SHA-384, or SHA-512 . . . . . . . . . . . . . . . . . . . 10
3.4. Digital Signature with ECDSA P-256 SHA-256, ECDSA 3.4. Digital Signature with ECDSA P-256 SHA-256, ECDSA
P-384 SHA-384, or ECDSA P-521 SHA-512 . . . . . . . . . . 11 P-384 SHA-384, or ECDSA P-521 SHA-512 . . . . . . . . . . 11
3.5. Using the Algorithm "none" . . . . . . . . . . . . . . . . 12 3.5. Digital Signature with RSASSA-PSS and SHA-256 or
3.6. Additional Digital Signature/MAC Algorithms and SHA-512 . . . . . . . . . . . . . . . . . . . . . . . . . 13
Parameters . . . . . . . . . . . . . . . . . . . . . . . . 13 3.6. Using the Algorithm "none" . . . . . . . . . . . . . . . . 14
4. Cryptographic Algorithms for JWE . . . . . . . . . . . . . . . 13 3.7. Additional Digital Signature/MAC Algorithms and
4.1. "alg" (Algorithm) Header Parameter Values for JWE . . . . 13 Parameters . . . . . . . . . . . . . . . . . . . . . . . . 14
4. Cryptographic Algorithms for JWE . . . . . . . . . . . . . . . 15
4.1. "alg" (Algorithm) Header Parameter Values for JWE . . . . 15
4.2. "enc" (Encryption Method) Header Parameter Values for 4.2. "enc" (Encryption Method) Header Parameter Values for
JWE . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 JWE . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.3. Key Encryption with RSAES-PKCS1-V1_5 . . . . . . . . . . . 16 4.3. Key Encryption with RSAES-PKCS1-V1_5 . . . . . . . . . . . 17
4.4. Key Encryption with RSAES OAEP . . . . . . . . . . . . . . 16 4.4. Key Encryption with RSAES OAEP . . . . . . . . . . . . . . 17
4.5. Key Wrapping with AES Key Wrap . . . . . . . . . . . . . . 16 4.5. Key Wrapping with AES Key Wrap . . . . . . . . . . . . . . 18
4.6. Direct Encryption with a Shared Symmetric Key . . . . . . 16 4.6. Direct Encryption with a Shared Symmetric Key . . . . . . 18
4.7. Key Agreement with Elliptic Curve Diffie-Hellman 4.7. Key Agreement with Elliptic Curve Diffie-Hellman
Ephemeral Static (ECDH-ES) . . . . . . . . . . . . . . . . 16 Ephemeral Static (ECDH-ES) . . . . . . . . . . . . . . . . 18
4.7.1. Key Derivation for "ECDH-ES" . . . . . . . . . . . . . 17 4.7.1. Key Derivation for "ECDH-ES" . . . . . . . . . . . . . 19
4.8. AES_CBC_HMAC_SHA2 Algorithms . . . . . . . . . . . . . . . 18 4.8. AES_CBC_HMAC_SHA2 Algorithms . . . . . . . . . . . . . . . 20
4.8.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 . . . . 18 4.8.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 . . . . 20
4.8.2. Generic AES_CBC_HMAC_SHA2 Algorithm . . . . . . . . . 19 4.8.2. Generic AES_CBC_HMAC_SHA2 Algorithm . . . . . . . . . 20
4.8.2.1. AES_CBC_HMAC_SHA2 Encryption . . . . . . . . . . . 19 4.8.2.1. AES_CBC_HMAC_SHA2 Encryption . . . . . . . . . . . 20
4.8.2.2. AES_CBC_HMAC_SHA2 Decryption . . . . . . . . . . . 21 4.8.2.2. AES_CBC_HMAC_SHA2 Decryption . . . . . . . . . . . 22
4.8.3. AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . 21 4.8.3. AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . 23
4.8.4. AES_256_CBC_HMAC_SHA_512 . . . . . . . . . . . . . . . 22 4.8.4. AES_256_CBC_HMAC_SHA_512 . . . . . . . . . . . . . . . 23
4.8.5. Plaintext Encryption with AES_CBC_HMAC_SHA2 . . . . . 22 4.8.5. Plaintext Encryption with AES_CBC_HMAC_SHA2 . . . . . 23
4.9. Plaintext Encryption with AES GCM . . . . . . . . . . . . 22 4.9. Plaintext Encryption with AES GCM . . . . . . . . . . . . 24
4.10. Additional Encryption Algorithms and Parameters . . . . . 23 4.10. Additional Encryption Algorithms and Parameters . . . . . 24
5. Cryptographic Algorithms for JWK . . . . . . . . . . . . . . . 23 5. Cryptographic Algorithms for JWK . . . . . . . . . . . . . . . 25
5.1. "kty" (Key Type) Parameter Values for JWK . . . . . . . . 23 5.1. "kty" (Key Type) Parameter Values for JWK . . . . . . . . 25
5.2. JWK Parameters for Elliptic Curve Keys . . . . . . . . . . 24 5.2. JWK Parameters for Elliptic Curve Keys . . . . . . . . . . 25
5.2.1. JWK Parameters for Elliptic Curve Public Keys . . . . 24 5.2.1. JWK Parameters for Elliptic Curve Public Keys . . . . 25
5.2.1.1. "crv" (Curve) Parameter . . . . . . . . . . . . . 24 5.2.1.1. "crv" (Curve) Parameter . . . . . . . . . . . . . 25
5.2.1.2. "x" (X Coordinate) Parameter . . . . . . . . . . . 24 5.2.1.2. "x" (X Coordinate) Parameter . . . . . . . . . . . 26
5.2.1.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . 25 5.2.1.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . 26
5.2.2. JWK Parameters for Elliptic Curve Private Keys . . . . 25 5.2.2. JWK Parameters for Elliptic Curve Private Keys . . . . 26
5.2.2.1. "d" (ECC Private Key) Parameter . . . . . . . . . 25 5.2.2.1. "d" (ECC Private Key) Parameter . . . . . . . . . 26
5.3. JWK Parameters for RSA Keys . . . . . . . . . . . . . . . 25 5.3. JWK Parameters for RSA Keys . . . . . . . . . . . . . . . 27
5.3.1. JWK Parameters for RSA Public Keys . . . . . . . . . . 25 5.3.1. JWK Parameters for RSA Public Keys . . . . . . . . . . 27
5.3.1.1. "n" (Modulus) Parameter . . . . . . . . . . . . . 25 5.3.1.1. "n" (Modulus) Parameter . . . . . . . . . . . . . 27
5.3.1.2. "e" (Exponent) Parameter . . . . . . . . . . . . . 26 5.3.1.2. "e" (Exponent) Parameter . . . . . . . . . . . . . 27
5.3.2. JWK Parameters for RSA Private Keys . . . . . . . . . 26 5.3.2. JWK Parameters for RSA Private Keys . . . . . . . . . 27
5.3.2.1. "d" (Private Exponent) Parameter . . . . . . . . . 26 5.3.2.1. "d" (Private Exponent) Parameter . . . . . . . . . 27
5.3.2.2. "p" (First Prime Factor) Parameter . . . . . . . . 26 5.3.2.2. "p" (First Prime Factor) Parameter . . . . . . . . 28
5.3.2.3. "q" (Second Prime Factor) Parameter . . . . . . . 26 5.3.2.3. "q" (Second Prime Factor) Parameter . . . . . . . 28
5.3.2.4. "dp" (First Factor CRT Exponent) Parameter . . . . 26 5.3.2.4. "dp" (First Factor CRT Exponent) Parameter . . . . 28
5.3.2.5. "dq" (Second Factor CRT Exponent) Parameter . . . 27 5.3.2.5. "dq" (Second Factor CRT Exponent) Parameter . . . 28
5.3.2.6. "qi" (First CRT Coefficient) Parameter . . . . . . 27 5.3.2.6. "qi" (First CRT Coefficient) Parameter . . . . . . 28
5.3.2.7. "oth" (Other Primes Info) Parameter . . . . . . . 27 5.3.2.7. "oth" (Other Primes Info) Parameter . . . . . . . 28
5.3.3. JWK Parameters for Symmetric Keys . . . . . . . . . . 28 5.3.3. JWK Parameters for Symmetric Keys . . . . . . . . . . 29
5.3.3.1. "k" (Key Value) Parameter . . . . . . . . . . . . 28 5.3.3.1. "k" (Key Value) Parameter . . . . . . . . . . . . 29
5.4. Additional Key Types and Parameters . . . . . . . . . . . 28 5.4. Additional Key Types and Parameters . . . . . . . . . . . 29
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29
6.1. JSON Web Signature and Encryption Algorithms Registry . . 29 6.1. JSON Web Signature and Encryption Algorithms Registry . . 30
6.1.1. Template . . . . . . . . . . . . . . . . . . . . . . . 29 6.1.1. Template . . . . . . . . . . . . . . . . . . . . . . . 30
6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 30 6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 31
6.2. JSON Web Key Types Registry . . . . . . . . . . . . . . . 33 6.2. JSON Web Key Types Registry . . . . . . . . . . . . . . . 34
6.2.1. Registration Template . . . . . . . . . . . . . . . . 33 6.2.1. Registration Template . . . . . . . . . . . . . . . . 34
6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 33 6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 35
6.3. JSON Web Key Parameters Registration . . . . . . . . . . . 34 6.3. JSON Web Key Parameters Registration . . . . . . . . . . . 35
6.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 34 6.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 35
7. Security Considerations . . . . . . . . . . . . . . . . . . . 35 7. Security Considerations . . . . . . . . . . . . . . . . . . . 37
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 36 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 38
8.1. Normative References . . . . . . . . . . . . . . . . . . . 36 8.1. Normative References . . . . . . . . . . . . . . . . . . . 38
8.2. Informative References . . . . . . . . . . . . . . . . . . 38 8.2. Informative References . . . . . . . . . . . . . . . . . . 40
Appendix A. Digital Signature/MAC Algorithm Identifier Appendix A. Digital Signature/MAC Algorithm Identifier
Cross-Reference . . . . . . . . . . . . . . . . . . . 39 Cross-Reference . . . . . . . . . . . . . . . . . . . 41
Appendix B. Encryption Algorithm Identifier Cross-Reference . . . 41 Appendix B. Encryption Algorithm Identifier Cross-Reference . . . 43
Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms . . . . . 43 Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms . . . . . 45
C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 . . . . . . . . . 44 C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 . . . . . . . . . 46
C.2. Test Cases for AES_256_CBC_HMAC_SHA_512 . . . . . . . . . 45 C.2. Test Cases for AES_256_CBC_HMAC_SHA_512 . . . . . . . . . 47
Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 46 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 48
Appendix E. Document History . . . . . . . . . . . . . . . . . . 46 Appendix E. Document History . . . . . . . . . . . . . . . . . . 48
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 51 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 54
1. Introduction 1. Introduction
The JSON Web Algorithms (JWA) specification enumerates cryptographic The JSON Web Algorithms (JWA) specification enumerates cryptographic
algorithms and identifiers to be used with the JSON Web Signature algorithms and identifiers to be used with the JSON Web Signature
(JWS) [JWS], JSON Web Encryption (JWE) [JWE], and JSON Web Key (JWK) (JWS) [JWS], JSON Web Encryption (JWE) [JWE], and JSON Web Key (JWK)
[JWK] specifications. All these specifications utilize JavaScript [JWK] specifications. All these specifications utilize JavaScript
Object Notation (JSON) [RFC4627] based data structures. This Object Notation (JSON) [RFC4627] based data structures. This
specification also describes the semantics and operations that are specification also describes the semantics and operations that are
specific to these algorithms and key types. specific to these algorithms and key types.
skipping to change at page 4, line 43 skipping to change at page 4, line 43
specification are incorporated into this specification: specification are incorporated into this specification:
JSON Web Signature (JWS) A data structure representing a digitally JSON Web Signature (JWS) A data structure representing a digitally
signed or MACed message. The structure represents three values: signed or MACed message. The structure represents three values:
the JWS Header, the JWS Payload, and the JWS Signature. the JWS Header, the JWS Payload, and the JWS Signature.
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].
JWS Header A JSON Text Object that describes the digital signature JWS Header A JSON Text Object (or JSON Text Objects, when using the
or MAC operation applied to create the JWS Signature value. JWS JSON Serialization) that describes the digital signature or
MAC operation applied to create the JWS Signature value. The
members of the JWS Header object(s) are Header Parameters.
JWS Payload The sequence of octets to be secured -- a.k.a., the JWS Payload The sequence of octets to be secured -- a.k.a., the
message. The payload can contain an arbitrary sequence of octets. message. The payload can contain an arbitrary sequence of octets.
JWS Signature A sequence of octets containing the cryptographic JWS Signature A sequence of octets containing the cryptographic
material that ensures the integrity of the JWS Header and the JWS material that ensures the integrity of the JWS Protected Header
Payload. The JWS Signature value is a digital signature or MAC and the JWS Payload. The JWS Signature value is a digital
value calculated over the JWS Signing Input using the parameters signature or MAC value calculated over the JWS Signing Input using
specified in the JWS Header. the parameters specified in the JWS Header.
JWS Protected Header A JSON Text Object that contains the portion of
the JWS Header that is integrity protected. For the JWS Compact
Serialization, this comprises the entire JWS Header. For the JWS
JSON Serialization, this is one component of the JWS Header.
Base64url Encoding The URL- and filename-safe Base64 encoding Base64url Encoding The URL- and filename-safe Base64 encoding
described in RFC 4648 [RFC4648], Section 5, with the (non URL- described in RFC 4648 [RFC4648], Section 5, with the (non URL-
safe) '=' padding characters omitted, as permitted by Section 3.2. safe) '=' padding characters omitted, as permitted by Section 3.2.
(See Appendix C of [JWS] for notes on implementing base64url (See Appendix C of [JWS] for notes on implementing base64url
encoding without padding.) encoding without padding.)
Encoded JWS Header Base64url encoding of the JWS Header. Encoded JWS Header Base64url encoding of the JWS Protected Header.
Encoded JWS Payload Base64url encoding of the JWS Payload. Encoded JWS Payload Base64url encoding of the JWS Payload.
Encoded JWS Signature Base64url encoding of the JWS Signature. Encoded JWS Signature Base64url encoding of the JWS Signature.
JWS Signing Input The concatenation of the Encoded JWS Header, a JWS Signing Input The concatenation of the Encoded JWS Header, a
period ('.') character, and the Encoded JWS Payload. period ('.') character, and the Encoded JWS Payload.
Collision Resistant Namespace A namespace that allows names to be Collision Resistant Namespace A namespace that allows names to be
allocated in a manner such that they are highly unlikely to allocated in a manner such that they are highly unlikely to
skipping to change at page 6, line 13 skipping to change at page 6, line 23
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 Associated Data (AAD) An input to an Authenticated Additional Authenticated Data (AAD) An input to an Authenticated
Encryption operation that is integrity protected but not Encryption operation that is integrity protected but not
encrypted. encrypted.
Authentication Tag An output of an Authenticated Encryption Authentication Tag An output of an Authenticated Encryption
operation that ensures the integrity of the Ciphertext and the operation that ensures the integrity of the Ciphertext and the
Additional Associated Data. Additional Authenticated Data. Note that some algorithms may not
use an Authentication Tag, in which case this value is the empty
octet sequence.
Content Encryption Key (CEK) A symmetric key for the Authenticated Content Encryption Key (CEK) A symmetric key for the Authenticated
Encryption algorithm used to encrypt the Plaintext for the Encryption algorithm used to encrypt the Plaintext for the
recipient to produce the Ciphertext and the Authentication Tag. recipient to produce the Ciphertext and the Authentication Tag.
JWE Header A JSON Text Object that describes the encryption JWE Header A JSON Text Object (or JSON Text Objects, when using the
operations applied to create the JWE Encrypted Key, the JWE JWE JSON Serialization) that describes the encryption operations
Ciphertext, and the JWE Authentication Tag. applied to create the JWE Encrypted Key, the JWE Ciphertext, and
the JWE Authentication Tag. The members of the JWE Header
object(s) are Header Parameters.
JWE Encrypted Key The result of encrypting the Content Encryption JWE Encrypted Key The result of encrypting the Content Encryption
Key (CEK) with the intended recipient's key using the specified Key (CEK) with the intended recipient's key using the specified
algorithm. Note that for some algorithms, the JWE Encrypted Key algorithm. Note that for some algorithms, the JWE Encrypted Key
value is specified as being the empty octet sequence. value is specified as being the empty octet sequence.
JWE Initialization Vector A sequence of octets containing the JWE Initialization Vector A sequence of octets containing the
Initialization Vector used when encrypting the Plaintext. Initialization Vector used when encrypting the Plaintext. Note
that some algorithms may not use an Initialization Vector, in
which case this value is the empty octet sequence.
JWE Ciphertext A sequence of octets containing the Ciphertext for a JWE Ciphertext A sequence of octets containing the Ciphertext for a
JWE. JWE.
JWE Authentication Tag A sequence of octets containing the JWE Authentication Tag A sequence of octets containing the
Authentication Tag for a JWE. Authentication Tag for a JWE.
Encoded JWE Header Base64url encoding of the JWE Header. JWE Protected Header A JSON Text Object that contains the portion of
the JWE Header that is integrity protected. For the JWE Compact
Serialization, this comprises the entire JWE Header. For the JWE
JSON Serialization, this is one component of the JWE Header.
Encoded JWE Header Base64url encoding of the JWE Protected Header.
Encoded JWE Encrypted Key Base64url encoding of the JWE Encrypted Encoded JWE Encrypted Key Base64url encoding of the JWE Encrypted
Key. Key.
Encoded JWE Initialization Vector Base64url encoding of the JWE Encoded JWE Initialization Vector Base64url encoding of the JWE
Initialization Vector. Initialization Vector.
Encoded JWE Ciphertext Base64url encoding of the JWE Ciphertext. Encoded JWE Ciphertext Base64url encoding of the JWE Ciphertext.
Encoded JWE Authentication Tag Base64url encoding of the JWE Encoded JWE Authentication Tag Base64url encoding of the JWE
skipping to change at page 8, line 9 skipping to change at page 8, line 24
JSON Web Key (JWK) A JSON object that represents a cryptographic JSON Web Key (JWK) A JSON object that represents a cryptographic
key. key.
JSON Web Key Set (JWK Set) A JSON object that contains an array of JSON Web Key Set (JWK Set) A JSON object that contains an array of
JWKs as the value of its "keys" member. JWKs as the value of its "keys" member.
2.4. Defined Terms 2.4. Defined Terms
These terms are defined for use by this specification: These terms are defined for use by this specification:
Header Parameter Name The name of a member of the JSON object Header Parameter A name/value pair that is member of a JWS Header or
JWE Header.
Header Parameter Name The name of a member of a JSON object
representing a JWS Header or JWE Header. representing a JWS Header or JWE Header.
Header Parameter Value The value of a member of the JSON object Header Parameter Value The value of a member of a JSON object
representing a JWS Header or JWE Header. representing a JWS Header or JWE Header.
3. Cryptographic Algorithms for JWS 3. Cryptographic Algorithms for JWS
JWS uses cryptographic algorithms to digitally sign or create a JWS uses cryptographic algorithms to digitally sign or create a
Message Authentication Codes (MAC) of the contents of the JWS Header Message Authentication Codes (MAC) of the contents of the JWS Header
and the JWS Payload. The use of the following algorithms for and the JWS Payload. The use of the following algorithms for
producing JWSs is defined in this section. producing JWSs is defined in this section.
3.1. "alg" (Algorithm) Header Parameter Values for JWS 3.1. "alg" (Algorithm) Header Parameter Values for JWS
The table below is the set of "alg" (algorithm) header parameter The table below is the set of "alg" (algorithm) header parameter
values defined by this specification for use with JWS, each of which values defined by this specification for use with JWS, each of which
is explained in more detail in the following sections: is explained in more detail in the following sections:
+--------------+--------------------------------+-------------------+ +-----------+--------------------------------------+----------------+
| alg | Digital Signature or MAC | Implementation | | alg | Digital Signature or MAC Algorithm | Implementation |
| Parameter | Algorithm | Requirements | | Parameter | | Requirements |
| Value | | | | Value | | |
+--------------+--------------------------------+-------------------+ +-----------+--------------------------------------+----------------+
| HS256 | HMAC using SHA-256 hash | REQUIRED | | HS256 | HMAC using SHA-256 hash algorithm | REQUIRED |
| | algorithm | | | HS384 | HMAC using SHA-384 hash algorithm | OPTIONAL |
| HS384 | HMAC using SHA-384 hash | OPTIONAL | | HS512 | HMAC using SHA-512 hash algorithm | OPTIONAL |
| | algorithm | | | RS256 | RSASSA-PKCS-v1_5 using SHA-256 hash | RECOMMENDED |
| HS512 | HMAC using SHA-512 hash | OPTIONAL | | | algorithm | |
| | algorithm | | | RS384 | RSASSA-PKCS-v1_5 using SHA-384 hash | OPTIONAL |
| RS256 | RSASSA using SHA-256 hash | RECOMMENDED | | | algorithm | |
| | algorithm | | | RS512 | RSASSA-PKCS-v1_5 using SHA-512 hash | OPTIONAL |
| RS384 | RSASSA using SHA-384 hash | OPTIONAL | | | algorithm | |
| | algorithm | | | ES256 | ECDSA using P-256 curve and SHA-256 | RECOMMENDED+ |
| RS512 | RSASSA using SHA-512 hash | OPTIONAL | | | hash algorithm | |
| | algorithm | | | ES384 | ECDSA using P-384 curve and SHA-384 | OPTIONAL |
| ES256 | ECDSA using P-256 curve and | RECOMMENDED+ | | | hash algorithm | |
| | SHA-256 hash algorithm | | | ES512 | ECDSA using P-521 curve and SHA-512 | OPTIONAL |
| ES384 | ECDSA using P-384 curve and | OPTIONAL | | | hash algorithm | |
| | SHA-384 hash algorithm | | | PS256 | RSASSA-PSS using SHA-256 hash | OPTIONAL |
| ES512 | ECDSA using P-521 curve and | OPTIONAL | | | algorithm and MGF1 mask generation | |
| | SHA-512 hash algorithm | | | | function with SHA-256 | |
| none | No digital signature or MAC | REQUIRED | | PS512 | RSASSA-PSS using SHA-512 hash | OPTIONAL |
| | value included | | | | algorithm and MGF1 mask generation | |
+--------------+--------------------------------+-------------------+ | | function with SHA-512 | |
| none | No digital signature or MAC value | REQUIRED |
| | included | |
+-----------+--------------------------------------+----------------+
All the names are short because a core goal of JWS is for the All the names are short because a core goal of JWS is for the
representations to be compact. However, there is no a priori length representations to be compact. However, there is no a priori length
restriction on "alg" values. restriction on "alg" values.
The use of "+" in the Implementation Requirements indicates that the The use of "+" in the Implementation Requirements indicates that the
requirement strength is likely to be increased in a future version of requirement strength is likely to be increased in a future version of
the specification. the specification.
See Appendix A for a table cross-referencing the digital signature See Appendix A for a table cross-referencing the digital signature
skipping to change at page 10, line 20 skipping to change at page 10, line 46
be rejected. be rejected.
Securing content with the HMAC SHA-384 and HMAC SHA-512 algorithms is Securing content with the HMAC SHA-384 and HMAC SHA-512 algorithms is
performed identically to the procedure for HMAC SHA-256 - just using performed identically to the procedure for HMAC SHA-256 - just using
the corresponding hash algorithm with correspondingly larger minimum the corresponding hash algorithm with correspondingly larger minimum
key sizes and result values: 384 bits each for HMAC SHA-384 and 512 key sizes and result values: 384 bits each for HMAC SHA-384 and 512
bits each for HMAC SHA-512. bits each for HMAC SHA-512.
An example using this algorithm is shown in Appendix A.1 of [JWS]. An example using this algorithm is shown in Appendix A.1 of [JWS].
3.3. Digital Signature with RSA SHA-256, RSA SHA-384, or RSA SHA-512 3.3. Digital Signature with RSASSA-PKCS1-V1_5 and SHA-256, SHA-384, or
SHA-512
This section defines the use of the RSASSA-PKCS1-V1_5 digital This section defines the use of the RSASSA-PKCS1-V1_5 digital
signature algorithm as defined in Section 8.2 of RFC 3447 [RFC3447], signature algorithm as defined in Section 8.2 of RFC 3447 [RFC3447]
(commonly known as PKCS #1), using SHA-256, SHA-384, or SHA-512 [SHS] (commonly known as PKCS #1), using SHA-256, SHA-384, or SHA-512 [SHS]
as the hash functions. The "alg" (algorithm) header parameter values as the hash functions. The "alg" (algorithm) header parameter values
"RS256", "RS384", and "RS512" are used in the JWS Header to indicate "RS256", "RS384", and "RS512" are used in the JWS Header to indicate
that the Encoded JWS Signature contains a base64url encoded RSA that the Encoded JWS Signature contains a base64url encoded RSASSA-
digital signature using the respective hash function. PKCS1-V1_5 digital signature using the respective hash function.
A key of size 2048 bits or larger MUST be used with these algorithms. A key of size 2048 bits or larger MUST be used with these algorithms.
The RSA SHA-256 digital signature is generated as follows: The RSASSA-PKCS1-V1_5 SHA-256 digital signature is generated as
follows:
1. Generate a digital signature of the octets of the ASCII 1. Generate a digital signature of the octets of the ASCII
representation of the JWS Signing Input using RSASSA-PKCS1-V1_5- representation of the JWS Signing Input using RSASSA-PKCS1-V1_5-
SIGN and the SHA-256 hash function with the desired private key. SIGN and the SHA-256 hash function with the desired private key.
The output will be an octet sequence. The output will be an octet sequence.
2. Base64url encode the resulting octet sequence. 2. Base64url encode the resulting octet sequence.
The output is the Encoded JWS Signature for that JWS. The output is the Encoded JWS Signature for that JWS.
The RSA SHA-256 digital signature for a JWS is validated as follows: The RSASSA-PKCS1-V1_5 SHA-256 digital signature for a JWS is
validated as follows:
1. Take the Encoded JWS Signature and base64url decode it into an 1. Take the Encoded JWS Signature and base64url decode it into an
octet sequence. If decoding fails, the JWS MUST be rejected. octet sequence. If decoding fails, the JWS MUST be rejected.
2. Submit the octets of the ASCII representation of the JWS Signing 2. Submit the octets of the ASCII representation of the JWS Signing
Input and the public key corresponding to the private key used by Input and the public key corresponding to the private key used by
the signer to the RSASSA-PKCS1-V1_5-VERIFY algorithm using SHA- the signer to the RSASSA-PKCS1-V1_5-VERIFY algorithm using SHA-
256 as the hash function. 256 as the hash function.
3. If the validation fails, the JWS MUST be rejected. 3. If the validation fails, the JWS MUST be rejected.
Signing with the RSA SHA-384 and RSA SHA-512 algorithms is performed Signing with the RSASSA-PKCS1-V1_5 SHA-384 and RSASSA-PKCS1-V1_5 SHA-
identically to the procedure for RSA SHA-256 - just using the 512 algorithms is performed identically to the procedure for RSASSA-
corresponding hash algorithm with correspondingly larger result PKCS1-V1_5 SHA-256 - just using the corresponding hash algorithm with
values: 384 bits for RSA SHA-384 and 512 bits for RSA SHA-512. correspondingly larger result values: 384 bits for RSASSA-PKCS1-V1_5
SHA-384 and 512 bits for RSASSA-PKCS1-V1_5 SHA-512.
An example using this algorithm is shown in Appendix A.2 of [JWS]. An example using this algorithm is shown in Appendix A.2 of [JWS].
3.4. Digital Signature with ECDSA P-256 SHA-256, ECDSA P-384 SHA-384, 3.4. Digital Signature with ECDSA P-256 SHA-256, ECDSA P-384 SHA-384,
or ECDSA P-521 SHA-512 or ECDSA P-521 SHA-512
The Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] provides The Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] provides
for the use of Elliptic Curve cryptography, which is able to provide for the use of Elliptic Curve cryptography, which is able to provide
equivalent security to RSA cryptography but using shorter key sizes equivalent security to RSA cryptography but using shorter key sizes
and with greater processing speed. This means that ECDSA digital and with greater processing speed. This means that ECDSA digital
skipping to change at page 12, line 44 skipping to change at page 13, line 27
algorithms is performed identically to the procedure for ECDSA P-256 algorithms is performed identically to the procedure for ECDSA P-256
SHA-256 - just using the corresponding hash algorithm with SHA-256 - just using the corresponding hash algorithm with
correspondingly larger result values. For ECDSA P-384 SHA-384, R and correspondingly larger result values. For ECDSA P-384 SHA-384, R and
S will be 384 bits each, resulting in a 96 octet sequence. For ECDSA S will be 384 bits each, resulting in a 96 octet sequence. For ECDSA
P-521 SHA-512, R and S will be 521 bits each, resulting in a 132 P-521 SHA-512, R and S will be 521 bits each, resulting in a 132
octet sequence. octet sequence.
Examples using these algorithms are shown in Appendices A.3 and A.4 Examples using these algorithms are shown in Appendices A.3 and A.4
of [JWS]. of [JWS].
3.5. Using the Algorithm "none" 3.5. Digital Signature with RSASSA-PSS and SHA-256 or SHA-512
This section defines the use of the RSASSA-PSS digital signature
algorithm as defined in Section 8.1 of RFC 3447 [RFC3447] with the
MGF1 mask generation function, always using the same hash function
for both the RSASSA-PSS hash function and the MGF1 hash function.
Use of both SHA-256 and SHA-512 as these hash functions is defined.
All other algorithm parameters use the defaults specified in Section
A.2.3 of RFC 3447. The "alg" (algorithm) header parameter values
"PS256" and "PS512" is used in the JWS Header to indicate that the
Encoded JWS Signature contains a base64url encoded RSASSA-PSS digital
signature using the respective hash function in both roles.
A key of size 2048 bits or larger MUST be used with this algorithm.
The RSASSA-PSS SHA-256 digital signature is generated as follows:
1. Generate a digital signature of the octets of the ASCII
representation of the JWS Signing Input using RSASSA-PSS-SIGN,
the SHA-256 hash function, and the MGF1 mask generation function
with SHA-256 with the desired private key. The output will be an
octet sequence.
2. Base64url encode the resulting octet sequence.
The output is the Encoded JWS Signature for that JWS.
The RSASSA-PSS SHA-256 digital signature for a JWS is validated as
follows:
1. Take the Encoded JWS Signature and base64url decode it into an
octet sequence. If decoding fails, the JWS MUST be rejected.
2. Submit the octets of the ASCII representation of the JWS Signing
Input and the public key corresponding to the private key used by
the signer to the RSASSA-PSS-VERIFY algorithm using SHA-256 as
the hash function and using MGF1 as the mask generation function
with SHA-256.
3. If the validation fails, the JWS MUST be rejected.
Signing with the RSASSA-PSS SHA-512 algorithm is performed
identically to the procedure for RSASSA-PSS SHA-256 - just using the
alternative hash algorithm in both roles.
3.6. Using the Algorithm "none"
JWSs MAY also be created that do not provide integrity protection. JWSs MAY also be created that do not provide integrity protection.
Such a JWS is called a "Plaintext JWS". Plaintext JWSs MUST use the Such a JWS is called a "Plaintext JWS". Plaintext JWSs MUST use the
"alg" value "none", and are formatted identically to other JWSs, but "alg" value "none", and are formatted identically to other JWSs, but
with the empty string for its JWS Signature value. with the empty string for its JWS Signature value.
3.6. Additional Digital Signature/MAC Algorithms and Parameters 3.7. Additional Digital Signature/MAC Algorithms and Parameters
Additional algorithms MAY be used to protect JWSs with corresponding Additional algorithms MAY be used to protect JWSs with corresponding
"alg" (algorithm) header parameter values being defined to refer to "alg" (algorithm) header parameter values being defined to refer to
them. New "alg" header parameter values SHOULD either be registered them. New "alg" header parameter values SHOULD either be registered
in the IANA JSON Web Signature and Encryption Algorithms registry in the IANA JSON Web Signature and Encryption Algorithms registry
Section 6.1 or be a value that contains a Collision Resistant Section 6.1 or be a value that contains a Collision Resistant
Namespace. In particular, it is permissible to use the algorithm Namespace. In particular, it is permissible to use the algorithm
identifiers defined in XML DSIG [RFC3275], XML DSIG 2.0 identifiers defined in XML DSIG [RFC3275], XML DSIG 2.0
[W3C.CR-xmldsig-core2-20120124], and related specifications as "alg" [W3C.CR-xmldsig-core2-20120124], and related specifications as "alg"
values. values.
As indicated by the common registry, JWSs and JWEs share a common As indicated by the common registry, JWSs and JWEs share a common
"alg" value space. The values used by the two specifications MUST be "alg" value space. The values used by the two specifications MUST be
distinct, as the "alg" value can be used to determine whether the distinct, as the "alg" value can be used to determine whether the
object is a JWS or JWE. object is a JWS or JWE.
Likewise, additional reserved Header Parameter Names MAY be defined Likewise, additional reserved Header Parameter Names can be defined
via the IANA JSON Web Signature and Encryption Header Parameters via the IANA JSON Web Signature and Encryption Header Parameters
registry [JWS]. As indicated by the common registry, JWSs and JWEs registry [JWS]. As indicated by the common registry, JWSs and JWEs
share a common header parameter space; when a parameter is used by share a common header parameter space; when a parameter is used by
both specifications, its usage must be compatible between the both specifications, its usage must be compatible between the
specifications. specifications.
4. Cryptographic Algorithms for JWE 4. Cryptographic Algorithms for JWE
JWE uses cryptographic algorithms to encrypt the Content Encryption JWE uses cryptographic algorithms to encrypt the Content Encryption
Key (CEK) and the Plaintext. This section specifies a set of Key (CEK) and the Plaintext. This section specifies a set of
skipping to change at page 17, line 45 skipping to change at page 19, line 24
The Concat KDF parameters are set as follows: The Concat KDF parameters are set as follows:
Z This is set to the representation of the shared secret Z as an Z This is set to the representation of the shared secret Z as an
octet sequence. octet sequence.
keydatalen This is set to the number of bits in the desired output keydatalen This is set to the number of bits in the desired output
key. For "ECDH-ES", this is length of the key used by the "enc" key. For "ECDH-ES", this is length of the key used by the "enc"
algorithm. For "ECDH-ES+A128KW", and "ECDH-ES+A256KW", this is algorithm. For "ECDH-ES+A128KW", and "ECDH-ES+A256KW", this is
128 and 256, respectively. 128 and 256, respectively.
AlgorithmID This is set to the concatenation of keydatalen AlgorithmID This is set to the octets of the UTF-8 representation of
represented as a 32 bit big endian integer and the octets of the the "alg" header parameter value.
UTF-8 representation of the "alg" header parameter value.
PartyUInfo The PartyUInfo value is of the form Datalen || Data, PartyUInfo PartyUInfo contains a random data value provided by the
where Data is a variable-length string of zero or more octets, and sender. If provided, this value MUST contain at least 512 bits
Datalen is a fixed-length, big endian 32 bit counter that and a unique value SHOULD be used for each recipient. Use of
indicates the length (in octets) of Data, with || being PartyUInfo is OPTIONAL when a different ephemeral key is used for
concatenation. If an "apu" (agreement PartyUInfo) header each key agreement transaction. The PartyUInfo value is of the
form Datalen || Data, where Data is a variable-length string of
zero or more octets, and Datalen is a fixed-length, big endian 32
bit counter that indicates the length (in octets) of Data, with ||
being concatenation. If an "apu" (agreement PartyUInfo) header
parameter is present, Data is set to the result of base64url parameter is present, Data is set to the result of base64url
decoding the "apu" value and Datalen is set to the number of decoding the "apu" value and Datalen is set to the number of
octets in Data. Otherwise, Datalen is set to 0 and Data is set to octets in Data. Otherwise, Datalen is set to 0 and Data is set to
the empty octet sequence. the empty octet sequence.
PartyVInfo The PartyVInfo value is of the form Datalen || Data, PartyVInfo This is set to the empty octet sequence.
where Data is a variable-length string of zero or more octets, and
Datalen is a fixed-length, big endian 32 bit counter that
indicates the length (in octets) of Data, with || being
concatenation. If an "apv" (agreement PartyVInfo) header
parameter is present, Data is set to the result of base64url
decoding the "apv" value and Datalen is set to the number of
octets in Data. Otherwise, Datalen is set to 0 and Data is set to
the empty octet sequence.
SuppPubInfo This is set to the empty octet sequence. SuppPubInfo This is set to the keydatalen represented as a 32 bit
big endian integer.
SuppPrivInfo This is set to the empty octet sequence. SuppPrivInfo This is set to the empty octet sequence.
4.8. AES_CBC_HMAC_SHA2 Algorithms 4.8. AES_CBC_HMAC_SHA2 Algorithms
This section defines a family of authenticated encryption algorithms This section defines a family of authenticated encryption algorithms
built using a composition of Advanced Encryption Standard (AES) in built using a composition of Advanced Encryption Standard (AES) in
Cipher Block Chaining (CBC) mode with PKCS #5 padding [AES] Cipher Block Chaining (CBC) mode with PKCS #5 padding [AES]
[NIST.800-38A] operations and HMAC [RFC2104] [SHS] operations. This [NIST.800-38A] operations and HMAC [RFC2104] [SHS] operations. This
algorithm family is called AES_CBC_HMAC_SHA2. It also defines two algorithm family is called AES_CBC_HMAC_SHA2. It also defines two
skipping to change at page 19, line 5 skipping to change at page 20, line 29
Authentication Tag values remaining separate, rather than being Authentication Tag values remaining separate, rather than being
concatenated with the Ciphertext value in the output representation. concatenated with the Ciphertext value in the output representation.
This algorithm family is a generalization of the algorithm family in This algorithm family is a generalization of the algorithm family in
[I-D.mcgrew-aead-aes-cbc-hmac-sha2], and can be used to implement [I-D.mcgrew-aead-aes-cbc-hmac-sha2], and can be used to implement
those algorithms. those algorithms.
4.8.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 4.8.1. Conventions Used in Defining AES_CBC_HMAC_SHA2
We use the following notational conventions. We use the following notational conventions.
CBC-PKCS5-ENC(X,P) denotes the AES CBC encryption of P using PKCS CBC-PKCS5-ENC(X, P) denotes the AES CBC encryption of P using PKCS
#5 padding using the cipher with the key X. #5 padding using the cipher with the key X.
MAC(Y, M) denotes the application of the Message Authentication MAC(Y, M) denotes the application of the Message Authentication
Code (MAC) to the message M, using the key Y. Code (MAC) to the message M, using the key Y.
The concatenation of two octet strings A and B is denoted as The concatenation of two octet strings A and B is denoted as
A || B. A || B.
4.8.2. Generic AES_CBC_HMAC_SHA2 Algorithm 4.8.2. Generic AES_CBC_HMAC_SHA2 Algorithm
skipping to change at page 22, line 28 skipping to change at page 23, line 47
The length of the input key K is 64 octets. The length of the input key K is 64 octets.
The HMAC SHA-512 value is truncated to T_LEN=32 octets instead of The HMAC SHA-512 value is truncated to T_LEN=32 octets instead of
16 octets. 16 octets.
4.8.5. Plaintext Encryption with AES_CBC_HMAC_SHA2 4.8.5. Plaintext Encryption with AES_CBC_HMAC_SHA2
The algorithm value "A128CBC-HS256" is used as the "alg" value when The algorithm value "A128CBC-HS256" is used as the "alg" value when
using AES_128_CBC_HMAC_SHA_256 with JWE. The algorithm value using AES_128_CBC_HMAC_SHA_256 with JWE. The algorithm value
"A256CBC-HS512" is used as the "alg" value when using "A256CBC-HS512" is used as the "alg" value when using
AES_256_CBC_HMAC_SHA_512 with JWE. In both cases, the Additional AES_256_CBC_HMAC_SHA_512 with JWE. The Additional Authenticated Data
Authenticated Data value used is the concatenation of the Encoded JWE value used is the octets of the ASCII representation of the Encoded
Header value, a period ('.') character, and the Encoded JWE Encrypted JWE Header value. The JWE Initialization Vector value used is the IV
Key. The JWE Initialization Vector value used is the IV value. value.
4.9. Plaintext Encryption with AES GCM 4.9. Plaintext Encryption with AES GCM
This section defines the specifics of encrypting the JWE Plaintext This section defines the specifics of encrypting the JWE Plaintext
with Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM) with Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM)
[AES] [NIST.800-38D] using 128 or 256 bit keys. The "enc" header [AES] [NIST.800-38D] using 128 or 256 bit keys. The "enc" header
parameter values "A128GCM" or "A256GCM" are used in this case. parameter values "A128GCM" or "A256GCM" are used in this case.
The CEK is used as the encryption key. The CEK is used as the encryption key.
Use of an initialization vector of size 96 bits is REQUIRED with this Use of an initialization vector of size 96 bits is REQUIRED with this
algorithm. algorithm.
The Additional Authenticated Data parameter is used to secure the The Additional Authenticated Data value used is the octets of the
header and key values. (The Additional Authenticated Data value used ASCII representation of the Encoded JWE Header value.
is the octets of the ASCII representation of the concatenation of the
Encoded JWE Header, a period ('.') character, and the Encoded JWE
Encrypted Key per Section 5 of the JWE specification.) This same
Additional Authenticated Data value is used when decrypting as well.
The requested size of the Authentication Tag output MUST be 128 bits, The requested size of the Authentication Tag output MUST be 128 bits,
regardless of the key size. regardless of the key size.
The JWE Authentication Tag is set to be the Authentication Tag value The JWE Authentication Tag is set to be the Authentication Tag value
produced by the encryption. During decryption, the received JWE produced by the encryption. During decryption, the received JWE
Authentication Tag is used as the Authentication Tag value. Authentication Tag is used as the Authentication Tag value.
An example using this algorithm is shown in Appendix A.1 of [JWE]. An example using this algorithm is shown in Appendix A.1 of [JWE].
skipping to change at page 23, line 30 skipping to change at page 24, line 47
it is permissible to use the algorithm identifiers defined in XML it is permissible to use the algorithm identifiers defined in XML
Encryption [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 Encryption [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1
[W3C.CR-xmlenc-core1-20120313], and related specifications as "alg" [W3C.CR-xmlenc-core1-20120313], and related specifications as "alg"
and "enc" values. and "enc" values.
As indicated by the common registry, JWSs and JWEs share a common As indicated by the common registry, JWSs and JWEs share a common
"alg" value space. The values used by the two specifications MUST be "alg" value space. The values used by the two specifications MUST be
distinct, as the "alg" value can be used to determine whether the distinct, as the "alg" value can be used to determine whether the
object is a JWS or JWE. object is a JWS or JWE.
Likewise, additional reserved Header Parameter Names MAY be defined Likewise, additional reserved Header Parameter Names can be defined
via the IANA JSON Web Signature and Encryption Header Parameters via the IANA JSON Web Signature and Encryption Header Parameters
registry [JWS]. As indicated by the common registry, JWSs and JWEs registry [JWS]. As indicated by the common registry, JWSs and JWEs
share a common header parameter space; when a parameter is used by share a common header parameter space; when a parameter is used by
both specifications, its usage must be compatible between the both specifications, its usage must be compatible between the
specifications. specifications.
5. Cryptographic Algorithms for JWK 5. Cryptographic Algorithms for JWK
A JSON Web Key (JWK) [JWK] is a JavaScript Object Notation (JSON) A JSON Web Key (JWK) [JWK] is a JavaScript Object Notation (JSON)
[RFC4627] data structure that represents a cryptographic key. A JSON [RFC4627] data structure that represents a cryptographic key. A JSON
skipping to change at page 31, line 20 skipping to change at page 32, line 38
o Implementation Requirements: OPTIONAL o Implementation Requirements: OPTIONAL
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 3.1 of [[ this document ]] o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "ES512" o Algorithm Name: "ES512"
o Algorithm Usage Location(s): "alg" o Algorithm Usage Location(s): "alg"
o Implementation Requirements: OPTIONAL o Implementation Requirements: OPTIONAL
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 3.1 of [[ this document ]] o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "PS256"
o Algorithm Usage Location(s): "alg"
o Implementation Requirements: RECOMMENDED
o Change Controller: IETF
o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "PS512"
o Algorithm Usage Location(s): "alg"
o Implementation Requirements: RECOMMENDED
o Change Controller: IETF
o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "none" o Algorithm Name: "none"
o Algorithm Usage Location(s): "alg" o Algorithm Usage Location(s): "alg"
o Implementation Requirements: REQUIRED o Implementation Requirements: REQUIRED
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 3.1 of [[ this document ]] o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "RSA1_5" o Algorithm Name: "RSA1_5"
o Algorithm Usage Location(s): "alg" o Algorithm Usage Location(s): "alg"
o Implementation Requirements: REQUIRED o Implementation Requirements: REQUIRED
o Change Controller: IETF o Change Controller: IETF
skipping to change at page 34, line 21 skipping to change at page 36, line 4
6.3. JSON Web Key Parameters Registration 6.3. JSON Web Key Parameters Registration
This specification registers the parameter names defined in Sections This specification registers the parameter names defined in Sections
5.2, 5.3, and 5.3.3 in the IANA JSON Web Key Parameters registry 5.2, 5.3, and 5.3.3 in the IANA JSON Web Key Parameters registry
[JWK]. [JWK].
6.3.1. Registry Contents 6.3.1. Registry Contents
o Parameter Name: "crv" o Parameter Name: "crv"
o Parameter Information Class: Public
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 5.2.1.1 of [[ this document ]] o Specification Document(s): Section 5.2.1.1 of [[ this document ]]
o Parameter Name: "x" o Parameter Name: "x"
o Parameter Information Class: Public
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 5.2.1.2 of [[ this document ]] o Specification Document(s): Section 5.2.1.2 of [[ this document ]]
o Parameter Name: "y" o Parameter Name: "y"
o Parameter Information Class: Public
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 5.2.1.3 of [[ this document ]] o Specification Document(s): Section 5.2.1.3 of [[ this document ]]
o Parameter Name: "d" o Parameter Name: "d"
o Parameter Information Class: Private
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 5.2.2.1 of [[ this document ]] o Specification Document(s): Section 5.2.2.1 of [[ this document ]]
o Parameter Name: "n" o Parameter Name: "n"
o Parameter Information Class: Public
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 5.3.1.1 of [[ this document ]] o Specification Document(s): Section 5.3.1.1 of [[ this document ]]
o Parameter Name: "e" o Parameter Name: "e"
o Parameter Information Class: Public
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 5.3.1.2 of [[ this document ]] o Specification Document(s): Section 5.3.1.2 of [[ this document ]]
o Parameter Name: "d" o Parameter Name: "d"
o Parameter Information Class: Private
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 5.3.2.1 of [[ this document ]] o Specification Document(s): Section 5.3.2.1 of [[ this document ]]
o Parameter Name: "p" o Parameter Name: "p"
o Parameter Information Class: Private
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 5.3.2.2 of [[ this document ]] o Specification Document(s): Section 5.3.2.2 of [[ this document ]]
o Parameter Name: "q" o Parameter Name: "q"
o Parameter Information Class: Private
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 5.3.2.3 of [[ this document ]] o Specification Document(s): Section 5.3.2.3 of [[ this document ]]
o Parameter Name: "dp" o Parameter Name: "dp"
o Parameter Information Class: Private
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 5.3.2.4 of [[ this document ]] o Specification Document(s): Section 5.3.2.4 of [[ this document ]]
o Parameter Name: "dq" o Parameter Name: "dq"
o Parameter Information Class: Private
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 5.3.2.5 of [[ this document ]] o Specification Document(s): Section 5.3.2.5 of [[ this document ]]
o Parameter Name: "qi" o Parameter Name: "qi"
o Parameter Information Class: Private
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 5.3.2.6 of [[ this document ]] o Specification Document(s): Section 5.3.2.6 of [[ this document ]]
o Parameter Name: "oth" o Parameter Name: "oth"
o Parameter Information Class: Private
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 5.3.2.7 of [[ this document ]] o Specification Document(s): Section 5.3.2.7 of [[ this document ]]
o Parameter Name: "k" o Parameter Name: "k"
o Parameter Information Class: Private
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 5.3.3.1 of [[ this document ]] o Specification Document(s): Section 5.3.3.1 of [[ this document ]]
7. Security Considerations 7. 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
skipping to change at page 36, line 9 skipping to change at page 38, line 6
this specification will no longer be considered sufficiently secure this specification will no longer be considered sufficiently secure
and will be removed. Therefore, implementers and deployments must be and will be removed. Therefore, implementers and deployments must be
prepared for this eventuality. prepared for this eventuality.
Algorithms of matching strengths should be used together whenever Algorithms of matching strengths should be used together whenever
possible. For instance, when AES Key Wrap is used with a given key possible. For instance, when AES Key Wrap is used with a given key
size, using the same key size is recommended when AES GCM is also size, using the same key size is recommended when AES GCM is also
used. used.
While Section 8 of RFC 3447 [RFC3447] explicitly calls for people not While Section 8 of RFC 3447 [RFC3447] explicitly calls for people not
to adopt RSASSA-PKCS1 for new applications and instead requests that to adopt RSASSA-PKCS-v1_5 for new applications and instead requests
people transition to RSASSA-PSS, this specification does include that people transition to RSASSA-PSS, this specification does include
RSASSA-PKCS1, for interoperability reasons, because it commonly RSASSA-PKCS-v1_5, for interoperability reasons, because it commonly
implemented. implemented.
Keys used with RSAES-PKCS1-v1_5 must follow the constraints in Keys used with RSAES-PKCS1-v1_5 must follow the constraints in
Section 7.2 of RFC 3447 [RFC3447]. In particular, keys with a low Section 7.2 of RFC 3447 [RFC3447]. In particular, keys with a low
public key exponent value must not be used. public key exponent value must not be used.
Plaintext JWSs (JWSs that use the "alg" value "none") provide no Plaintext JWSs (JWSs that use the "alg" value "none") provide no
integrity protection. Thus, they must only be used in contexts where integrity protection. Thus, they must only be used in contexts where
the payload is secured by means other than a digital signature or MAC the payload is secured by means other than a digital signature or MAC
value, or need not be secured. value, or need not be secured.
skipping to change at page 36, line 47 skipping to change at page 38, line 44
[AES] National Institute of Standards and Technology (NIST), [AES] National Institute of Standards and Technology (NIST),
"Advanced Encryption Standard (AES)", FIPS PUB 197, "Advanced Encryption Standard (AES)", FIPS PUB 197,
November 2001. November 2001.
[DSS] National Institute of Standards and Technology, "Digital [DSS] National Institute of Standards and Technology, "Digital
Signature Standard (DSS)", FIPS PUB 186-3, June 2009. Signature Standard (DSS)", FIPS PUB 186-3, June 2009.
[JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web
Encryption (JWE)", draft-ietf-jose-json-web-encryption Encryption (JWE)", draft-ietf-jose-json-web-encryption
(work in progress), April 2013. (work in progress), May 2013.
[JWK] Jones, M., "JSON Web Key (JWK)", [JWK] Jones, M., "JSON Web Key (JWK)",
draft-ietf-jose-json-web-key (work in progress), draft-ietf-jose-json-web-key (work in progress), May 2013.
April 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), April 2013. in progress), May 2013.
[NIST.800-38A] [NIST.800-38A]
National Institute of Standards and Technology (NIST), National Institute of Standards and Technology (NIST),
"Recommendation for Block Cipher Modes of Operation", "Recommendation for Block Cipher Modes of Operation",
NIST PUB 800-38A, December 2001. NIST PUB 800-38A, December 2001.
[NIST.800-38D] [NIST.800-38D]
National Institute of Standards and Technology (NIST), National Institute of Standards and Technology (NIST),
"Recommendation for Block Cipher Modes of Operation: "Recommendation for Block Cipher Modes of Operation:
Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D,
skipping to change at page 40, line 5 skipping to change at page 41, line 33
Appendix A. Digital Signature/MAC Algorithm Identifier Cross-Reference Appendix A. Digital Signature/MAC Algorithm Identifier Cross-Reference
This appendix contains a table cross-referencing the digital This appendix contains a table cross-referencing the digital
signature and MAC "alg" (algorithm) values used in this specification signature and MAC "alg" (algorithm) values used in this specification
with the equivalent identifiers used by other standards and software with the equivalent identifiers used by other standards and software
packages. See XML DSIG [RFC3275], XML DSIG 2.0 packages. See XML DSIG [RFC3275], XML DSIG 2.0
[W3C.CR-xmldsig-core2-20120124], and Java Cryptography Architecture [W3C.CR-xmldsig-core2-20120124], and Java Cryptography Architecture
[JCA] for more information about the names defined by those [JCA] for more information about the names defined by those
documents. documents.
+-------+-----+----------------------------+----------+-------------+ +---------+----+---------------------------+----------+-------------+
| Algor | JWS | XML DSIG | JCA | OID | | Algorit | JW | XML DSIG | JCA | OID |
| ithm | | | | | | hm | S | | | |
+-------+-----+----------------------------+----------+-------------+ +---------+----+---------------------------+----------+-------------+
| HMAC | HS2 | http://www.w3.org/2001/04/ | HmacSHA2 | 1.2.840.113 | | HMAC | HS | http://www.w3.org/2001/04 | HmacSHA2 | 1.2.840.113 |
| using | 56 | xmldsig-more#hmac-sha256 | 56 | 549.2.9 | | using | 25 | /xmldsig-more#hmac-sha256 | 56 | 549.2.9 |
| SHA-2 | | | | | | SHA-256 | 6 | | | |
| 56 | | | | | | hash | | | | |
| hash | | | | | | algorit | | | | |
| algo | | | | | | hm | | | | |
| rithm | | | | | | HMAC | HS | http://www.w3.org/2001/04 | HmacSHA3 | 1.2.840.113 |
| HMAC | HS3 | http://www.w3.org/2001/04/ | HmacSHA3 | 1.2.840.113 | | using | 38 | /xmldsig-more#hmac-sha384 | 84 | 549.2.10 |
| using | 84 | xmldsig-more#hmac-sha384 | 84 | 549.2.10 | | SHA-384 | 4 | | | |
| SHA-3 | | | | | | hash | | | | |
| 84 | | | | | | algorit | | | | |
| hash | | | | | | hm | | | | |
| algo | | | | | | HMAC | HS | http://www.w3.org/2001/04 | HmacSHA5 | 1.2.840.113 |
| rithm | | | | | | using | 51 | /xmldsig-more#hmac-sha512 | 12 | 549.2.11 |
| HMAC | HS5 | http://www.w3.org/2001/04/ | HmacSHA5 | 1.2.840.113 | | SHA-512 | 2 | | | |
| using | 12 | xmldsig-more#hmac-sha512 | 12 | 549.2.11 | | hash | | | | |
| SHA-5 | | | | | | algorit | | | | |
| 12 | | | | | | hm | | | | |
| hash | | | | | | RSASSA- | RS | http://www.w3.org/2001/04 | SHA256wi | 1.2.840.113 |
| algo | | | | | | PKCS-v1 | 25 | /xmldsig-more#rsa-sha256 | thRSA | 549.1.1.11 |
| rithm | | | | | | _5using | 6 | | | |
| RSASS | RS2 | http://www.w3.org/2001/04/ | SHA256wi | 1.2.840.113 | | SHA-2 | | | | |
| A | 56 | xmldsig-more#rsa-sha256 | thRSA | 549.1.1.11 | | 56hash | | | | |
| usin | | | | | | algor | | | | |
| gSHA- | | | | | | ithm | | | | |
| 256 | | | | | | RSASSA- | RS | http://www.w3.org/2001/04 | SHA384wi | 1.2.840.113 |
| has | | | | | | PKCS-v1 | 38 | /xmldsig-more#rsa-sha384 | thRSA | 549.1.1.12 |
| h alg | | | | | | _5using | 4 | | | |
| orith | | | | | | SHA-3 | | | | |
| m | | | | | | 84hash | | | | |
| RSASS | RS3 | http://www.w3.org/2001/04/ | SHA384wi | 1.2.840.113 | | algor | | | | |
| A | 84 | xmldsig-more#rsa-sha384 | thRSA | 549.1.1.12 | | ithm | | | | |
| usin | | | | | | RSASSA- | RS | http://www.w3.org/2001/04 | SHA512wi | 1.2.840.113 |
| gSHA- | | | | | | PKCS-v1 | 51 | /xmldsig-more#rsa-sha512 | thRSA | 549.1.1.13 |
| 384 | | | | | | _5using | 2 | | | |
| has | | | | | | SHA-5 | | | | |
| h alg | | | | | | 12hash | | | | |
| orith | | | | | | algor | | | | |
| m | | | | | | ithm | | | | |
| RSASS | RS5 | http://www.w3.org/2001/04/ | SHA512wi | 1.2.840.113 | | ECDSA | ES | http://www.w3.org/2001/04 | SHA256wi | 1.2.840.100 |
| A | 12 | xmldsig-more#rsa-sha512 | thRSA | 549.1.1.13 | | using | 25 | /xmldsig-more#ecdsa-sha25 | thECDSA | 45.4.3.2 |
| usin | | | | | | P-256 | 6 | 6 | | |
| gSHA- | | | | | | curve | | | | |
| 512 | | | | | | and | | | | |
| has | | | | | | SHA-256 | | | | |
| h alg | | | | | | hash | | | | |
| orith | | | | | | algorit | | | | |
| m | | | | | | hm | | | | |
| ECDSA | ES2 | http://www.w3.org/2001/04/ | SHA256wi | 1.2.840.100 | | ECDSA | ES | http://www.w3.org/2001/04 | SHA384wi | 1.2.840.100 |
| using | 56 | xmldsig-more#ecdsa-sha256 | thECDSA | 45.4.3.2 | | using | 38 | /xmldsig-more#ecdsa-sha38 | thECDSA | 45.4.3.3 |
| P-256 | | | | | | P-384 | 4 | 4 | | |
| curve | | | | | | curve | | | | |
| and | | | | | | and | | | | |
| SHA-2 | | | | | | SHA-384 | | | | |
| 56 | | | | | | hash | | | | |
| hash | | | | | | algorit | | | | |
| algo | | | | | | hm | | | | |
| rithm | | | | | | ECDSA | ES | http://www.w3.org/2001/04 | SHA512wi | 1.2.840.100 |
| ECDSA | ES3 | http://www.w3.org/2001/04/ | SHA384wi | 1.2.840.100 | | using | 51 | /xmldsig-more#ecdsa-sha51 | thECDSA | 45.4.3.4 |
| using | 84 | xmldsig-more#ecdsa-sha384 | thECDSA | 45.4.3.3 | | P-521 | 2 | 2 | | |
| P-384 | | | | | | curve | | | | |
| curve | | | | | | and | | | | |
| and | | | | | | SHA-512 | | | | |
| SHA-3 | | | | | | hash | | | | |
| 84 | | | | | | algorit | | | | |
| hash | | | | | | hm | | | | |
| algo | | | | | | RSASSA- | PS | | | |
| rithm | | | | | | PSS | 25 | | | |
| ECDSA | ES5 | http://www.w3.org/2001/04/ | SHA512wi | 1.2.840.100 | | using | 6 | | | |
| using | 12 | xmldsig-more#ecdsa-sha512 | thECDSA | 45.4.3.4 | | SHA-25 | | | | |
| P-521 | | | | | | 6hash | | | | |
| curve | | | | | | algori | | | | |
| and | | | | | | thm and | | | | |
| SHA-5 | | | | | | MGF1 | | | | |
| 12 | | | | | | mask | | | | |
| hash | | | | | | gener | | | | |
| algo | | | | | | ation | | | | |
| rithm | | | | | | func | | | | |
+-------+-----+----------------------------+----------+-------------+ | tionwit | | | | |
| h SHA | | | | |
| -256 | | | | |
| RSASSA- | PS | | | |
| PSS | 51 | | | |
| using | 2 | | | |
| SHA-51 | | | | |
| 2hash | | | | |
| algori | | | | |
| thm and | | | | |
| MGF1 | | | | |
| mask | | | | |
| gener | | | | |
| ation | | | | |
| func | | | | |
| tionwit | | | | |
| h SHA | | | | |
| -512 | | | | |
+---------+----+---------------------------+----------+-------------+
Appendix B. Encryption Algorithm Identifier Cross-Reference Appendix B. Encryption Algorithm Identifier Cross-Reference
This appendix contains a table cross-referencing the "alg" This appendix contains a table cross-referencing the "alg"
(algorithm) and "enc" (encryption method) values used in this (algorithm) and "enc" (encryption method) values used in this
specification with the equivalent identifiers used by other standards specification with the equivalent identifiers used by other standards
and software packages. See XML Encryption and software packages. See XML Encryption
[W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1
[W3C.CR-xmlenc-core1-20120313], and Java Cryptography Architecture [W3C.CR-xmlenc-core1-20120313], and Java Cryptography Architecture
skipping to change at page 46, line 38 skipping to change at page 48, line 38
Nat Sakimura, Jim Schaad, Hannes Tschofenig, and Sean Turner. Nat Sakimura, Jim Schaad, 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 E. Document History Appendix E. Document History
[[ to be removed by the RFC editor before publication as an RFC ]] [[ to be removed by the RFC editor before publication as an RFC ]]
-11
o Removed the Encrypted Key value from the AAD computation since it
is already effectively integrity protected by the encryption
process. The AAD value now only contains the representation of
the JWE Encrypted Header.
o Removed "apv" (agreement PartyVInfo) since it is no longer used.
o Added more information about the use of PartyUInfo during key
agreement.
o Use the keydatalen as the SuppPubInfo value for the Concat KDF
when doing key agreement, as RFC 2631 does.
o Added algorithm identifiers for RSASSA-PSS with SHA-256 and SHA-
512.
o Added a Parameter Information Class value to the JSON Web Key
Parameters registry, which registers whether the parameter conveys
public or private information.
-10 -10
o Changed the JWE processing rules for multiple recipients so that a o Changed the JWE processing rules for multiple recipients so that a
single AAD value contains the header parameters and encrypted key single AAD value contains the header parameters and encrypted key
values for all the recipients, enabling AES GCM to be safely used values for all the recipients, enabling AES GCM to be safely used
for multiple recipients. for multiple recipients.
-09 -09
o Expanded the scope of the JWK parameters to include private and o Expanded the scope of the JWK parameters to include private and
 End of changes. 58 change blocks. 
249 lines changed or deleted 380 lines changed or added

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