draft-ietf-jose-json-web-algorithms-16.txt   draft-ietf-jose-json-web-algorithms-17.txt 
JOSE Working Group M. Jones JOSE Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track September 15, 2013 Intended status: Standards Track October 7, 2013
Expires: March 19, 2014 Expires: April 10, 2014
JSON Web Algorithms (JWA) JSON Web Algorithms (JWA)
draft-ietf-jose-json-web-algorithms-16 draft-ietf-jose-json-web-algorithms-17
Abstract Abstract
The JSON Web Algorithms (JWA) specification registers cryptographic The JSON Web Algorithms (JWA) specification registers 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. It defines several IANA registries for these specifications. It defines several IANA registries for these
identifiers. identifiers.
Status of this Memo Status of this Memo
skipping to change at page 1, line 34 skipping to change at page 1, line 34
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 March 19, 2014. This Internet-Draft will expire on April 10, 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 10 skipping to change at page 2, line 10
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
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 . . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1. Terms Incorporated from the JWS Specification . . . . . . 5 3. Cryptographic Algorithms for Digital Signatures and MACs . . . 6
2.2. Terms Incorporated from the JWE Specification . . . . . . 6 3.1. "alg" (Algorithm) Header Parameter Values for JWS . . . . 6
2.3. Terms Incorporated from the JWK Specification . . . . . . 9 3.2. HMAC with SHA-2 Functions . . . . . . . . . . . . . . . . 7
2.4. Defined Terms . . . . . . . . . . . . . . . . . . . . . . 9 3.3. Digital Signature with RSASSA-PKCS1-V1_5 . . . . . . . . . 8
3. Cryptographic Algorithms for Digital Signatures and MACs . . . 9 3.4. Digital Signature with ECDSA . . . . . . . . . . . . . . . 9
3.1. "alg" (Algorithm) Header Parameter Values for JWS . . . . 9 3.5. Digital Signature with RSASSA-PSS . . . . . . . . . . . . 10
3.2. HMAC with SHA-2 Functions . . . . . . . . . . . . . . . . 10 3.6. Using the Algorithm "none" . . . . . . . . . . . . . . . . 11
3.3. Digital Signature with RSASSA-PKCS1-V1_5 . . . . . . . . . 11 4. Cryptographic Algorithms for Encryption . . . . . . . . . . . 11
3.4. Digital Signature with ECDSA . . . . . . . . . . . . . . . 12 4.1. "alg" (Algorithm) Header Parameter Values for JWE . . . . 11
3.5. Digital Signature with RSASSA-PSS . . . . . . . . . . . . 14
3.6. Using the Algorithm "none" . . . . . . . . . . . . . . . . 15
4. Cryptographic Algorithms for Encryption . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 JWE . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.3. Key Encryption with RSAES-PKCS1-V1_5 . . . . . . . . . . . 21 4.3. Key Encryption with RSAES-PKCS1-V1_5 . . . . . . . . . . . 17
4.4. Key Encryption with RSAES OAEP . . . . . . . . . . . . . . 21 4.4. Key Encryption with RSAES OAEP . . . . . . . . . . . . . . 17
4.5. Key Wrapping with AES Key Wrap . . . . . . . . . . . . . . 21 4.5. Key Wrapping with AES Key Wrap . . . . . . . . . . . . . . 18
4.6. Direct Encryption with a Shared Symmetric Key . . . . . . 21 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) . . . . . . . . . . . . . . . . 22 Ephemeral Static (ECDH-ES) . . . . . . . . . . . . . . . . 18
4.7.1. Header Parameters Used for ECDH Key Agreement . . . . 22 4.7.1. Header Parameters Used for ECDH Key Agreement . . . . 19
4.7.1.1. "epk" (Ephemeral Public Key) Header Parameter . . 22 4.7.1.1. "epk" (Ephemeral Public Key) Header Parameter . . 19
4.7.1.2. "apu" (Agreement PartyUInfo) Header Parameter . . 23 4.7.1.2. "apu" (Agreement PartyUInfo) Header Parameter . . 19
4.7.1.3. "apv" (Agreement PartyVInfo) Header Parameter . . 23 4.7.1.3. "apv" (Agreement PartyVInfo) Header Parameter . . 19
4.7.2. Key Derivation for ECDH Key Agreement . . . . . . . . 23 4.7.2. Key Derivation for ECDH Key Agreement . . . . . . . . 19
4.8. Key Encryption with AES GCM . . . . . . . . . . . . . . . 24 4.8. Key Encryption with AES GCM . . . . . . . . . . . . . . . 21
4.8.1. Header Parameters Used for AES GCM Key Encryption . . 25 4.8.1. Header Parameters Used for AES GCM Key Encryption . . 21
4.8.1.1. "iv" (Initialization Vector) Header Parameter . . 25 4.8.1.1. "iv" (Initialization Vector) Header Parameter . . 21
4.8.1.2. "tag" (Authentication Tag) Header Parameter . . . 25 4.8.1.2. "tag" (Authentication Tag) Header Parameter . . . 22
4.9. Key Encryption with PBES2 . . . . . . . . . . . . . . . . 25 4.9. Key Encryption with PBES2 . . . . . . . . . . . . . . . . 22
4.9.1. Header Parameters Used for PBES2 Key Encryption . . . 26 4.9.1. Header Parameters Used for PBES2 Key Encryption . . . 22
4.9.1.1. "p2s" (PBES2 salt) Parameter . . . . . . . . . . . 26 4.9.1.1. "p2s" (PBES2 salt) Parameter . . . . . . . . . . . 22
4.9.1.2. "p2c" (PBES2 count) Parameter . . . . . . . . . . 26 4.9.1.2. "p2c" (PBES2 count) Parameter . . . . . . . . . . 23
4.10. AES_CBC_HMAC_SHA2 Algorithms . . . . . . . . . . . . . . . 26 4.10. AES_CBC_HMAC_SHA2 Algorithms . . . . . . . . . . . . . . . 23
4.10.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 . . . . 27 4.10.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 . . . . 23
4.10.2. Generic AES_CBC_HMAC_SHA2 Algorithm . . . . . . . . . 27 4.10.2. Generic AES_CBC_HMAC_SHA2 Algorithm . . . . . . . . . 23
4.10.2.1. AES_CBC_HMAC_SHA2 Encryption . . . . . . . . . . . 27 4.10.2.1. AES_CBC_HMAC_SHA2 Encryption . . . . . . . . . . . 24
4.10.2.2. AES_CBC_HMAC_SHA2 Decryption . . . . . . . . . . . 29 4.10.2.2. AES_CBC_HMAC_SHA2 Decryption . . . . . . . . . . . 25
4.10.3. AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . 29 4.10.3. AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . 26
4.10.4. AES_192_CBC_HMAC_SHA_384 . . . . . . . . . . . . . . . 30 4.10.4. AES_192_CBC_HMAC_SHA_384 . . . . . . . . . . . . . . . 26
4.10.5. AES_256_CBC_HMAC_SHA_512 . . . . . . . . . . . . . . . 30 4.10.5. AES_256_CBC_HMAC_SHA_512 . . . . . . . . . . . . . . . 27
4.10.6. Plaintext Encryption with AES_CBC_HMAC_SHA2 . . . . . 30 4.10.6. Plaintext Encryption with AES_CBC_HMAC_SHA2 . . . . . 27
4.11. Plaintext Encryption with AES GCM . . . . . . . . . . . . 27
4.11. Plaintext Encryption with AES GCM . . . . . . . . . . . . 31 5. Cryptographic Algorithms for Keys . . . . . . . . . . . . . . 28
5. Cryptographic Algorithms for Keys . . . . . . . . . . . . . . 31 5.1. "kty" (Key Type) Parameter Values . . . . . . . . . . . . 28
5.1. "kty" (Key Type) Parameter Values . . . . . . . . . . . . 31 5.2. Parameters for Elliptic Curve Keys . . . . . . . . . . . . 28
5.2. Parameters for Elliptic Curve Keys . . . . . . . . . . . . 32 5.2.1. Parameters for Elliptic Curve Public Keys . . . . . . 28
5.2.1. Parameters for Elliptic Curve Public Keys . . . . . . 32 5.2.1.1. "crv" (Curve) Parameter . . . . . . . . . . . . . 29
5.2.1.1. "crv" (Curve) Parameter . . . . . . . . . . . . . 32 5.2.1.2. "x" (X Coordinate) Parameter . . . . . . . . . . . 29
5.2.1.2. "x" (X Coordinate) Parameter . . . . . . . . . . . 33 5.2.1.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . 29
5.2.1.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . 33 5.2.2. Parameters for Elliptic Curve Private Keys . . . . . . 29
5.2.2. Parameters for Elliptic Curve Private Keys . . . . . . 33 5.2.2.1. "d" (ECC Private Key) Parameter . . . . . . . . . 29
5.2.2.1. "d" (ECC Private Key) Parameter . . . . . . . . . 33 5.3. Parameters for RSA Keys . . . . . . . . . . . . . . . . . 30
5.3. Parameters for RSA Keys . . . . . . . . . . . . . . . . . 33 5.3.1. Parameters for RSA Public Keys . . . . . . . . . . . . 30
5.3.1. Parameters for RSA Public Keys . . . . . . . . . . . . 33 5.3.1.1. "n" (Modulus) Parameter . . . . . . . . . . . . . 30
5.3.1.1. "n" (Modulus) Parameter . . . . . . . . . . . . . 33 5.3.1.2. "e" (Exponent) Parameter . . . . . . . . . . . . . 30
5.3.1.2. "e" (Exponent) Parameter . . . . . . . . . . . . . 34 5.3.2. Parameters for RSA Private Keys . . . . . . . . . . . 30
5.3.2. Parameters for RSA Private Keys . . . . . . . . . . . 34 5.3.2.1. "d" (Private Exponent) Parameter . . . . . . . . . 30
5.3.2.1. "d" (Private Exponent) Parameter . . . . . . . . . 34 5.3.2.2. "p" (First Prime Factor) Parameter . . . . . . . . 31
5.3.2.2. "p" (First Prime Factor) Parameter . . . . . . . . 34 5.3.2.3. "q" (Second Prime Factor) Parameter . . . . . . . 31
5.3.2.3. "q" (Second Prime Factor) Parameter . . . . . . . 34 5.3.2.4. "dp" (First Factor CRT Exponent) Parameter . . . . 31
5.3.2.4. "dp" (First Factor CRT Exponent) Parameter . . . . 35 5.3.2.5. "dq" (Second Factor CRT Exponent) Parameter . . . 31
5.3.2.5. "dq" (Second Factor CRT Exponent) Parameter . . . 35 5.3.2.6. "qi" (First CRT Coefficient) Parameter . . . . . . 31
5.3.2.6. "qi" (First CRT Coefficient) Parameter . . . . . . 35 5.3.2.7. "oth" (Other Primes Info) Parameter . . . . . . . 32
5.3.2.7. "oth" (Other Primes Info) Parameter . . . . . . . 35 5.4. Parameters for Symmetric Keys . . . . . . . . . . . . . . 32
5.4. Parameters for Symmetric Keys . . . . . . . . . . . . . . 36 5.4.1. "k" (Key Value) Parameter . . . . . . . . . . . . . . 33
5.4.1. "k" (Key Value) Parameter . . . . . . . . . . . . . . 36 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 6.1. JSON Web Signature and Encryption Algorithms Registry . . 34
6.1. JSON Web Signature and Encryption Algorithms Registry . . 37 6.1.1. Template . . . . . . . . . . . . . . . . . . . . . . . 34
6.1.1. Template . . . . . . . . . . . . . . . . . . . . . . . 38 6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 35
6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 38 6.2. JWE Header Parameter Names Registration . . . . . . . . . 39
6.2. JWE Header Parameter Names Registration . . . . . . . . . 43 6.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 39
6.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 43 6.3. JSON Web Encryption Compression Algorithms Registry . . . 40
6.3. JSON Web Encryption Compression Algorithms Registry . . . 44 6.3.1. Registration Template . . . . . . . . . . . . . . . . 40
6.3.1. Registration Template . . . . . . . . . . . . . . . . 44 6.3.2. Initial Registry Contents . . . . . . . . . . . . . . 41
6.3.2. Initial Registry Contents . . . . . . . . . . . . . . 45 6.4. JSON Web Key Types Registry . . . . . . . . . . . . . . . 41
6.4. JSON Web Key Types Registry . . . . . . . . . . . . . . . 45 6.4.1. Registration Template . . . . . . . . . . . . . . . . 41
6.4.1. Registration Template . . . . . . . . . . . . . . . . 45 6.4.2. Initial Registry Contents . . . . . . . . . . . . . . 42
6.4.2. Initial Registry Contents . . . . . . . . . . . . . . 46 6.5. JSON Web Key Parameters Registration . . . . . . . . . . . 43
6.5. JSON Web Key Parameters Registration . . . . . . . . . . . 46 6.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 43
6.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 46 6.6. JSON Web Key Elliptic Curve Registry . . . . . . . . . . . 45
6.6. JSON Web Key Elliptic Curve Registry . . . . . . . . . . . 48 6.6.1. Registration Template . . . . . . . . . . . . . . . . 45
6.6.1. Registration Template . . . . . . . . . . . . . . . . 48 6.6.2. Initial Registry Contents . . . . . . . . . . . . . . 46
6.6.2. Initial Registry Contents . . . . . . . . . . . . . . 49 7. Security Considerations . . . . . . . . . . . . . . . . . . . 46
7. Security Considerations . . . . . . . . . . . . . . . . . . . 49 7.1. Algorithms and Key Sizes will be Deprecated . . . . . . . 46
7.1. Algorithms and Key Sizes will be Deprecated . . . . . . . 50 7.2. Key Lifetimes . . . . . . . . . . . . . . . . . . . . . . 47
7.2. Key Lifetimes . . . . . . . . . . . . . . . . . . . . . . 50 7.3. RSAES-PKCS1-v1_5 Security Considerations . . . . . . . . . 47
7.3. RSAES-PKCS1-v1_5 Security Considerations . . . . . . . . . 50 7.4. AES GCM Security Considerations . . . . . . . . . . . . . 47
7.4. AES GCM Security Considerations . . . . . . . . . . . . . 50 7.5. Plaintext JWS Security Considerations . . . . . . . . . . 47
7.5. Plaintext JWS Security Considerations . . . . . . . . . . 51 7.6. Denial of Service Attacks . . . . . . . . . . . . . . . . 48
7.6. Denial of Service Attacks . . . . . . . . . . . . . . . . 51 7.7. Reusing Key Material when Encrypting Keys . . . . . . . . 48
7.7. Reusing Key Material when Encrypting Keys . . . . . . . . 52 7.8. Password Considerations . . . . . . . . . . . . . . . . . 48
7.8. Password Considerations . . . . . . . . . . . . . . . . . 52 8. Internationalization Considerations . . . . . . . . . . . . . 49
8. Internationalization Considerations . . . . . . . . . . . . . 52 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 49
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 53 9.1. Normative References . . . . . . . . . . . . . . . . . . . 49
9.1. Normative References . . . . . . . . . . . . . . . . . . . 53 9.2. Informative References . . . . . . . . . . . . . . . . . . 51
9.2. Informative References . . . . . . . . . . . . . . . . . . 55
Appendix A. Digital Signature/MAC Algorithm Identifier Appendix A. Digital Signature/MAC Algorithm Identifier
Cross-Reference . . . . . . . . . . . . . . . . . . . 56 Cross-Reference . . . . . . . . . . . . . . . . . . . 53
Appendix B. Encryption Algorithm Identifier Cross-Reference . . . 57 Appendix B. Encryption Algorithm Identifier Cross-Reference . . . 53
Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms . . . . . 58 Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms . . . . . 54
C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 . . . . . . . . . 59 C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 . . . . . . . . . 55
C.2. Test Cases for AES_192_CBC_HMAC_SHA_384 . . . . . . . . . 60 C.2. Test Cases for AES_192_CBC_HMAC_SHA_384 . . . . . . . . . 56
C.3. Test Cases for AES_256_CBC_HMAC_SHA_512 . . . . . . . . . 61 C.3. Test Cases for AES_256_CBC_HMAC_SHA_512 . . . . . . . . . 57
Appendix D. Example ECDH-ES Key Agreement Computation . . . . . . 62 Appendix D. Example ECDH-ES Key Agreement Computation . . . . . . 58
Appendix E. Acknowledgements . . . . . . . . . . . . . . . . . . 64 Appendix E. Acknowledgements . . . . . . . . . . . . . . . . . . 60
Appendix F. Document History . . . . . . . . . . . . . . . . . . 65 Appendix F. Document History . . . . . . . . . . . . . . . . . . 61
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 72 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 68
1. Introduction 1. Introduction
The JSON Web Algorithms (JWA) specification registers cryptographic The JSON Web Algorithms (JWA) specification registers 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. It defines several IANA registries for these [JWK] specifications. It defines several IANA registries for these
identifiers. All these specifications utilize JavaScript Object identifiers. All these specifications utilize JavaScript Object
Notation (JSON) [RFC4627] based data structures. This specification Notation (JSON) [RFC4627] based data structures. This specification
also describes the semantics and operations that are specific to also describes the semantics and operations that are specific to
skipping to change at page 5, line 35 skipping to change at page 5, line 35
1.1. Notational Conventions 1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in Key words for use in document are to be interpreted as described in Key words for use in
RFCs to Indicate Requirement Levels [RFC2119]. If these words are RFCs to Indicate Requirement Levels [RFC2119]. If these words are
used without being spelled in uppercase then they are to be used without being spelled in uppercase then they are to be
interpreted with their normal natural language meanings. interpreted with their normal natural language meanings.
2. Terminology BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per
Section 2.
2.1. Terms Incorporated from the JWS Specification
These terms defined by the JSON Web Signature (JWS) [JWS]
specification are incorporated into this specification:
JSON Web Signature (JWS) A data structure representing a digitally
signed or MACed message. The structure represents three values:
the JWS Header, the JWS Payload, and the JWS Signature.
JSON Text Object A UTF-8 [RFC3629] encoded text string representing
a JSON object; the syntax of JSON objects is defined in Section
2.2 of [RFC4627].
JWS Header A JSON Text Object (or JSON Text Objects, when using the
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
message. The payload can contain an arbitrary sequence of octets.
JWS Signature A sequence of octets containing the cryptographic
material that ensures the integrity of the JWS Protected Header
and the JWS Payload. The JWS Signature value is a digital
signature or MAC value calculated over the JWS Signing Input using
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 Base64 encoding using the URL- and filename-safe
character set defined in Section 5 of RFC 4648 [RFC4648], with all
trailing '=' characters omitted (as permitted by Section 3.2).
(See Appendix C of [JWS] for notes on implementing base64url
encoding without padding.)
Encoded JWS Header Base64url encoding of the JWS Protected Header. UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation
of STRING.
Encoded JWS Payload Base64url encoding of the JWS Payload. ASCII(STRING) denotes the octets of the ASCII [USASCII]
representation of STRING.
Encoded JWS Signature Base64url encoding of the JWS Signature. The concatenation of two values A and B is denoted as A || B.
JWS Signing Input The concatenation of the Encoded JWS Header, a 2. Terminology
period ('.') character, and the Encoded JWS Payload.
2.2. Terms Incorporated from the JWE Specification These terms defined by the JSON Web Signature (JWS) [JWS]
specification are incorporated into this specification: "JSON Web
Signature (JWS)", "JSON Text Object", "JWS Header", "JWS Payload",
"JWS Signature", "JWS Protected Header", "Base64url Encoding", and
"JWS Signing Input".
These terms defined by the JSON Web Encryption (JWE) [JWE] These terms defined by the JSON Web Encryption (JWE) [JWE]
specification are incorporated into this specification: specification are incorporated into this specification: "JSON Web
Encryption (JWE)", "Authenticated Encryption", "Plaintext",
JSON Web Encryption (JWE) A data structure representing an encrypted "Ciphertext", "Additional Authenticated Data (AAD)", "Authentication
message. The structure represents five values: the JWE Header, Tag", "Content Encryption Key (CEK)", "JWE Header", "JWE Encrypted
the JWE Encrypted Key, the JWE Initialization Vector, the JWE Key", "JWE Initialization Vector", "JWE Ciphertext", "JWE
Ciphertext, and the JWE Authentication Tag. Authentication Tag", "JWE Protected Header", "Key Management Mode",
"Key Encryption", "Key Wrapping", "Direct Key Agreement", "Key
Authenticated Encryption An Authenticated Encryption algorithm is Agreement with Key Wrapping", and "Direct Encryption".
one that provides an integrated content integrity check.
Authenticated Encryption algorithms accept two inputs, the
Plaintext and the Additional Authenticated Data value, and produce
two outputs, the Ciphertext and the Authentication Tag value. AES
Galois/Counter Mode (GCM) is one such algorithm.
Plaintext The sequence of octets to be encrypted -- a.k.a., the
message. The plaintext can contain an arbitrary sequence of
octets.
Ciphertext An encrypted representation of the Plaintext.
Additional Authenticated Data (AAD) An input to an Authenticated
Encryption operation that is integrity protected but not
encrypted.
Authentication Tag An output of an Authenticated Encryption
operation that ensures the integrity of the Ciphertext and the
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
Encryption algorithm used to encrypt the Plaintext for the
recipient to produce the Ciphertext and the Authentication Tag.
JWE Header A JSON Text Object (or JSON Text Objects, when using the
JWE JSON Serialization) that describes the encryption operations
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
Key (CEK) with the intended recipient's key using the specified
algorithm. Note that for some algorithms, the JWE Encrypted Key
value is specified as being the empty octet sequence.
JWE Initialization Vector A sequence of octets containing the
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.
JWE Authentication Tag A sequence of octets containing the
Authentication Tag for a JWE.
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
Key.
Encoded JWE Initialization Vector Base64url encoding of the JWE
Initialization Vector.
Encoded JWE Ciphertext Base64url encoding of the JWE Ciphertext.
Encoded JWE Authentication Tag Base64url encoding of the JWE
Authentication Tag.
Key Management Mode A method of determining the Content Encryption
Key (CEK) value to use. Each algorithm used for determining the
CEK value uses a specific Key Management Mode. Key Management
Modes employed by this specification are Key Encryption, Key
Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping,
and Direct Encryption.
Key Encryption A Key Management Mode in which the Content Encryption
Key (CEK) value is encrypted to the intended recipient using an
asymmetric encryption algorithm.
Key Wrapping A Key Management Mode in which the Content Encryption
Key (CEK) value is encrypted to the intended recipient using a
symmetric key wrapping algorithm.
Direct Key Agreement A Key Management Mode in which a key agreement
algorithm is used to agree upon the Content Encryption Key (CEK)
value.
Key Agreement with Key Wrapping A Key Management Mode in which a key
agreement algorithm is used to agree upon a symmetric key used to
encrypt the Content Encryption Key (CEK) value to the intended
recipient using a symmetric key wrapping algorithm.
Direct Encryption A Key Management Mode in which the Content
Encryption Key (CEK) value used is the secret symmetric key value
shared between the parties.
2.3. Terms Incorporated from the JWK Specification
These terms defined by the JSON Web Key (JWK) [JWK] specification are These terms defined by the JSON Web Key (JWK) [JWK] specification are
incorporated into this specification: incorporated into this specification: "JSON Web Key (JWK)" and "JSON
Web Key Set (JWK Set)".
JSON Web Key (JWK) A JSON object that represents a cryptographic
key.
JSON Web Key Set (JWK Set) A JSON object that contains an array of
JWKs as the value of its "keys" member.
2.4. Defined Terms
These terms are defined for use by this specification: These terms are defined for use by this specification:
Header Parameter A name/value pair that is member of a JWS Header or Header Parameter A name/value pair that is member of a JWS Header or
JWE Header. JWE Header.
Header Parameter Name The name of a member of a JSON object
representing a JWS Header or JWE Header.
Header Parameter Value The value of a member of a JSON object
representing a JWS Header or JWE Header.
3. Cryptographic Algorithms for Digital Signatures and MACs 3. Cryptographic Algorithms for Digital Signatures and MACs
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. and the JWS Payload.
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
skipping to change at page 11, line 8 skipping to change at page 8, line 8
3.2. HMAC with SHA-2 Functions 3.2. HMAC with SHA-2 Functions
Hash-based Message Authentication Codes (HMACs) enable one to use a Hash-based Message Authentication Codes (HMACs) enable one to use a
secret plus a cryptographic hash function to generate a Message secret plus a cryptographic hash function to generate a Message
Authentication Code (MAC). This can be used to demonstrate that Authentication Code (MAC). This can be used to demonstrate that
whoever generated the MAC was in possession of the MAC key. whoever generated the MAC was in possession of the MAC key.
The algorithm for implementing and validating HMACs is provided in The algorithm for implementing and validating HMACs is provided in
RFC 2104 [RFC2104]. This section defines the use of the HMAC SHA- RFC 2104 [RFC2104]. This section defines the use of the HMAC SHA-
256, HMAC SHA-384, and HMAC SHA-512 functions [SHS]. The "alg" 256, HMAC SHA-384, and HMAC SHA-512 functions [SHS]. The "alg"
(algorithm) header parameter values "HS256", "HS384", and "HS512" are (algorithm) Header Parameter values "HS256", "HS384", and "HS512" are
used in the JWS Header to indicate that the Encoded JWS Signature used in the JWS Header to indicate that the JWS Signature contains an
contains a base64url encoded HMAC value using the respective hash HMAC value using the respective hash function.
function.
A key of the same size as the hash output (for instance, 256 bits for A key of the same size as the hash output (for instance, 256 bits for
"HS256") or larger MUST be used with this algorithm. "HS256") or larger MUST be used with this algorithm.
The HMAC SHA-256 MAC is generated per RFC 2104, using SHA-256 as the The HMAC SHA-256 MAC is generated per RFC 2104, using SHA-256 as the
hash algorithm "H", using the octets of the ASCII [USASCII] hash algorithm "H", using the JWS Signing Input as the "text" value,
representation of the JWS Signing Input as the "text" value, and and using the shared key. The HMAC output value is the JWS
using the shared key. The HMAC output value is the JWS Signature.
The JWS signature is base64url encoded to produce the Encoded JWS
Signature. Signature.
The HMAC SHA-256 MAC for a JWS is validated by computing an HMAC The HMAC SHA-256 MAC for a JWS is validated by computing an HMAC
value per RFC 2104, using SHA-256 as the hash algorithm "H", using value per RFC 2104, using SHA-256 as the hash algorithm "H", using
the octets of the ASCII representation of the received JWS Signing the received JWS Signing Input as the "text" value, and using the
Input as the "text" value, and using the shared key. This computed shared key. This computed HMAC value is then compared to the result
HMAC value is then compared to the result of base64url decoding the of base64url decoding the received encoded JWS Signature value.
received Encoded JWS signature. Alternatively, the computed HMAC Alternatively, the computed HMAC value can be base64url encoded and
value can be base64url encoded and compared to the received Encoded compared to the received encoded JWS Signature value, as this
JWS Signature, as this comparison produces the same result as comparison produces the same result as comparing the unencoded
comparing the unencoded values. In either case, if the values match, values. In either case, if the values match, the HMAC has been
the HMAC has been validated. validated.
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 algorithms with correspondingly larger minimum the corresponding hash algorithms 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 RSASSA-PKCS1-V1_5 3.3. Digital Signature with RSASSA-PKCS1-V1_5
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 RSASSA- that the JWS Signature contains a RSASSA-PKCS1-V1_5 digital signature
PKCS1-V1_5 digital signature using the respective hash function. 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 RSASSA-PKCS1-V1_5 SHA-256 digital signature is generated as The RSASSA-PKCS1-V1_5 SHA-256 digital signature is generated as
follows: follows: Generate a digital signature of the JWS Signing Input using
RSASSA-PKCS1-V1_5-SIGN and the SHA-256 hash function with the desired
1. Generate a digital signature of the octets of the ASCII private key. This is the JWS Signature value.
representation of the JWS Signing Input using RSASSA-PKCS1-V1_5-
SIGN and the SHA-256 hash function 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-PKCS1-V1_5 SHA-256 digital signature for a JWS is The RSASSA-PKCS1-V1_5 SHA-256 digital signature for a JWS is
validated as follows: validated as follows: Submit the JWS Signing Input, the JWS
Signature, and the public key corresponding to the private key used
1. Take the Encoded JWS Signature and base64url decode it into an by the signer to the RSASSA-PKCS1-V1_5-VERIFY algorithm using SHA-256
octet sequence. If decoding fails, the validation has failed. as the hash function.
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-PKCS1-V1_5-VERIFY algorithm using SHA-
256 as the hash function.
Signing with the RSASSA-PKCS1-V1_5 SHA-384 and RSASSA-PKCS1-V1_5 SHA- Signing with the RSASSA-PKCS1-V1_5 SHA-384 and RSASSA-PKCS1-V1_5 SHA-
512 algorithms is performed identically to the procedure for RSASSA- 512 algorithms is performed identically to the procedure for RSASSA-
PKCS1-V1_5 SHA-256 - just using the corresponding hash algorithms PKCS1-V1_5 SHA-256 -- just using the corresponding hash algorithms
instead of SHA-256. instead of SHA-256.
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 3.4. Digital Signature with ECDSA
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
signatures will be substantially smaller in terms of length than signatures will be substantially smaller in terms of length than
equivalently strong RSA digital signatures. equivalently strong RSA digital signatures.
This specification defines the use of ECDSA with the P-256 curve and This specification defines the use of ECDSA with the P-256 curve and
the SHA-256 cryptographic hash function, ECDSA with the P-384 curve the SHA-256 cryptographic hash function, ECDSA with the P-384 curve
and the SHA-384 hash function, and ECDSA with the P-521 curve and the and the SHA-384 hash function, and ECDSA with the P-521 curve and the
SHA-512 hash function. The P-256, P-384, and P-521 curves are SHA-512 hash function. The P-256, P-384, and P-521 curves are
defined in [DSS]. The "alg" (algorithm) header parameter values defined in [DSS]. The "alg" (algorithm) Header Parameter values
"ES256", "ES384", and "ES512" are used in the JWS Header to indicate "ES256", "ES384", and "ES512" are used in the JWS Header to indicate
that the Encoded JWS Signature contains a base64url encoded ECDSA that the JWS Signature contains a base64url encoded ECDSA P-256 SHA-
P-256 SHA-256, ECDSA P-384 SHA-384, or ECDSA P-521 SHA-512 digital 256, ECDSA P-384 SHA-384, or ECDSA P-521 SHA-512 digital signature,
signature, respectively. respectively.
The ECDSA P-256 SHA-256 digital signature is generated as follows: The ECDSA P-256 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 JWS Signing Input using ECDSA
representation of the JWS Signing Input using ECDSA P-256 SHA-256 P-256 SHA-256 with the desired private key. The output will be
with the desired private key. The output will be the pair (R, the pair (R, S), where R and S are 256 bit unsigned integers.
S), where R and S are 256 bit unsigned integers.
2. Turn R and S into octet sequences in big endian order, with each 2. Turn R and S into octet sequences in big endian order, with each
array being be 32 octets long. The octet sequence array being be 32 octets long. The octet sequence
representations MUST NOT be shortened to omit any leading zero representations MUST NOT be shortened to omit any leading zero
octets contained in the values. octets contained in the values.
3. Concatenate the two octet sequences in the order R and then S. 3. Concatenate the two octet sequences in the order R and then S.
(Note that many ECDSA implementations will directly produce this (Note that many ECDSA implementations will directly produce this
concatenation as their output.) concatenation as their output.)
4. Base64url encode the resulting 64 octet sequence. 4. The resulting 64 octet sequence is the JWS Signature value.
The output is the Encoded JWS Signature for the JWS.
The ECDSA P-256 SHA-256 digital signature for a JWS is validated as The ECDSA P-256 SHA-256 digital signature for a JWS is validated as
follows: follows:
1. Take the Encoded JWS Signature and base64url decode it into an 1. The JWS Signature value MUST be a 64 octet sequence. If it is
octet sequence. If decoding fails, the validation has failed. not a 64 octet sequence, the validation has failed.
2. The output of the base64url decoding MUST be a 64 octet sequence.
If decoding does not result in a 64 octet sequence, the
validation has failed.
3. Split the 64 octet sequence into two 32 octet sequences. The 2. Split the 64 octet sequence into two 32 octet sequences. The
first array will be R and the second S (with both being in big first array will be R and the second S (with both being in big
endian octet order). endian octet order).
4. Submit the octets of the ASCII representation of the JWS Signing 3. Submit the JWS Signing Input R, S and the public key (x, y) to
Input R, S and the public key (x, y) to the ECDSA P-256 SHA-256 the ECDSA P-256 SHA-256 validator.
validator.
Signing with the ECDSA P-384 SHA-384 and ECDSA P-521 SHA-512 Signing with the ECDSA P-384 SHA-384 and ECDSA P-521 SHA-512
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 algorithms with SHA-256 -- just using the corresponding hash algorithms 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. Digital Signature with RSASSA-PSS 3.5. Digital Signature with RSASSA-PSS
This section defines the use of the RSASSA-PSS digital signature This section defines the use of the RSASSA-PSS digital signature
algorithm as defined in Section 8.1 of RFC 3447 [RFC3447] with the algorithm as defined in Section 8.1 of RFC 3447 [RFC3447] with the
MGF1 mask generation function, always using the same hash function MGF1 mask generation function, always using the same hash function
for both the RSASSA-PSS hash function and the MGF1 hash function. for both the RSASSA-PSS hash function and the MGF1 hash function.
Use of SHA-256, SHA-384, and SHA-512 as these hash functions is Use of SHA-256, SHA-384, and SHA-512 as these hash functions is
defined. The size of the salt value is the same size as the hash defined. The size of the salt value is the same size as the hash
function output. All other algorithm parameters use the defaults function output. All other algorithm parameters use the defaults
specified in Section A.2.3 of RFC 3447. The "alg" (algorithm) header specified in Section A.2.3 of RFC 3447. The "alg" (algorithm) header
parameter values "PS256", "PS384", and "PS512" are used in the JWS parameter values "PS256", "PS384", and "PS512" are used in the JWS
Header to indicate that the Encoded JWS Signature contains a Header to indicate that the JWS Signature contains a base64url
base64url encoded RSASSA-PSS digital signature using the respective encoded RSASSA-PSS digital signature using the respective hash
hash function in both roles. function in both roles.
A key of size 2048 bits or larger MUST be used with this algorithm. 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: The RSASSA-PSS SHA-256 digital signature is generated as follows:
Generate a digital signature of the JWS Signing Input using RSASSA-
1. Generate a digital signature of the octets of the ASCII PSS-SIGN, the SHA-256 hash function, and the MGF1 mask generation
representation of the JWS Signing Input using RSASSA-PSS-SIGN, function with SHA-256 with the desired private key. This is the JWS
the SHA-256 hash function, and the MGF1 mask generation function signature value.
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 The RSASSA-PSS SHA-256 digital signature for a JWS is validated as
follows: follows: Submit the JWS Signing Input, the JWS Signature, and the
public key corresponding to the private key used by the signer to the
1. Take the Encoded JWS Signature and base64url decode it into an RSASSA-PSS-VERIFY algorithm using SHA-256 as the hash function and
octet sequence. If decoding fails, the validation has failed. using MGF1 as the mask generation function with SHA-256.
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.
Signing with the RSASSA-PSS SHA-384 and RSASSA-PSS SHA-512 algorithms Signing with the RSASSA-PSS SHA-384 and RSASSA-PSS SHA-512 algorithms
is performed identically to the procedure for RSASSA-PSS SHA-256 - is performed identically to the procedure for RSASSA-PSS SHA-256 --
just using the alternative hash algorithm in both roles. just using the alternative hash algorithm in both roles.
3.6. Using the Algorithm "none" 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. See Section 7.5 with the empty string for its JWS Signature value. See Section 7.5
for security considerations associated with using this algorithm. for security considerations associated with using this algorithm.
4. Cryptographic Algorithms for Encryption 4. Cryptographic Algorithms for Encryption
JWE uses cryptographic algorithms to encrypt the Content Encryption JWE uses cryptographic algorithms to encrypt the Content Encryption
Key (CEK) and the Plaintext. Key (CEK) and the Plaintext.
4.1. "alg" (Algorithm) Header Parameter Values for JWE 4.1. "alg" (Algorithm) Header Parameter Values for JWE
The table below is the set of "alg" (algorithm) header parameter The table below is the set of "alg" (algorithm) Header Parameter
values that are defined by this specification for use with JWE. values that are defined by this specification for use with JWE.
These algorithms are used to encrypt the CEK, producing the JWE These algorithms are used to encrypt the CEK, producing the JWE
Encrypted Key, or to use key agreement to agree upon the CEK. Encrypted Key, or to use key agreement to agree upon the CEK.
+-------------------+-----------------+------------+----------------+ +-------------------+-----------------+------------+----------------+
| alg Parameter | Key Management | Additional | Implementation | | alg Parameter | Key Management | Additional | Implementation |
| Value | Algorithm | Header | Requirements | | Value | Algorithm | Header | Requirements |
| | | Parameters | | | | | Parameters | |
+-------------------+-----------------+------------+----------------+ +-------------------+-----------------+------------+----------------+
| RSA1_5 | RSAES-PKCS1-V1_ | (none) | Required | | RSA1_5 | RSAES-PKCS1-V1_ | (none) | Required |
skipping to change at page 19, line 40 skipping to change at page 16, line 24
Header Parameters are used by the algorithm, beyond "alg", which all Header Parameters are used by the algorithm, beyond "alg", which all
use. All but "dir" and "ECDH-ES" also produce a JWE Encrypted Key use. All but "dir" and "ECDH-ES" also produce a JWE Encrypted Key
value. value.
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.
4.2. "enc" (Encryption Method) Header Parameter Values for JWE 4.2. "enc" (Encryption Method) Header Parameter Values for JWE
The table below is the set of "enc" (encryption method) header The table below is the set of "enc" (encryption method) Header
parameter values that are defined by this specification for use with Parameter values that are defined by this specification for use with
JWE. These algorithms are used to encrypt the Plaintext, which JWE. These algorithms are used to encrypt the Plaintext, which
produces the Ciphertext. produces the Ciphertext.
+-------------+------------------------+------------+---------------+ +-------------+------------------------+------------+---------------+
| enc | Content Encryption | Additional | Implementatio | | enc | Content Encryption | Additional | Implementatio |
| Parameter | Algorithm | Header | nRequirements | | Parameter | Algorithm | Header | nRequirements |
| Value | | Parameters | | | Value | | Parameters | |
+-------------+------------------------+------------+---------------+ +-------------+------------------------+------------+---------------+
| A128CBC-HS2 | The | (none) | Required | | A128CBC-HS2 | The | (none) | Required |
| 56 | AES_128_CBC_HMAC_SHA_2 | | | | 56 | AES_128_CBC_HMAC_SHA_2 | | |
skipping to change at page 21, line 8 skipping to change at page 17, line 35
Ciphertext and JWE Authentication Tag values. Ciphertext and JWE Authentication Tag values.
See Appendix B for a table cross-referencing the encryption "alg" See Appendix B for a table cross-referencing the encryption "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. and software packages.
4.3. Key Encryption with RSAES-PKCS1-V1_5 4.3. Key Encryption with RSAES-PKCS1-V1_5
This section defines the specifics of encrypting a JWE CEK with This section defines the specifics of encrypting a JWE CEK with
RSAES-PKCS1-V1_5 [RFC3447]. The "alg" header parameter value RSAES-PKCS1-V1_5 [RFC3447]. The "alg" Header Parameter value
"RSA1_5" is used in this case. "RSA1_5" is used in this case.
A key of size 2048 bits or larger MUST be used with this algorithm. A key of size 2048 bits or larger MUST be used with this algorithm.
An example using this algorithm is shown in Appendix A.2 of [JWE]. An example using this algorithm is shown in Appendix A.2 of [JWE].
4.4. Key Encryption with RSAES OAEP 4.4. Key Encryption with RSAES OAEP
This section defines the specifics of encrypting a JWE CEK with RSAES This section defines the specifics of encrypting a JWE CEK with RSAES
using Optimal Asymmetric Encryption Padding (OAEP) [RFC3447], with using Optimal Asymmetric Encryption Padding (OAEP) [RFC3447], with
the default parameters specified by RFC 3447 in Section A.2.1. the default parameters specified by RFC 3447 in Section A.2.1.
(Those default parameters are using a hash function of SHA-1 and a (Those default parameters are using a hash function of SHA-1 and a
mask generation function of MGF1 with SHA-1.) The "alg" header mask generation function of MGF1 with SHA-1.) The "alg" Header
parameter value "RSA-OAEP" is used in this case. Parameter value "RSA-OAEP" is used in this case.
A key of size 2048 bits or larger MUST be used with this algorithm. A key of size 2048 bits or larger MUST be used with this algorithm.
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].
4.5. Key Wrapping with AES Key Wrap 4.5. Key Wrapping with AES Key Wrap
This section defines the specifics of encrypting a JWE CEK with the This section defines the specifics of encrypting a JWE CEK with the
Advanced Encryption Standard (AES) Key Wrap Algorithm [RFC3394] using Advanced Encryption Standard (AES) Key Wrap Algorithm [RFC3394] using
the default initial value specified in Section 2.2.3.1 using 128, the default initial value specified in Section 2.2.3.1 using 128,
192, or 256 bit keys. The "alg" header parameter values "A128KW", 192, or 256 bit keys. The "alg" Header Parameter values "A128KW",
"A192KW", or "A256KW" are respectively used in this case. "A192KW", or "A256KW" are respectively used in this case.
An example using this algorithm is shown in Appendix A.3 of [JWE]. An example using this algorithm is shown in Appendix A.3 of [JWE].
4.6. Direct Encryption with a Shared Symmetric Key 4.6. Direct Encryption with a Shared Symmetric Key
This section defines the specifics of directly performing symmetric This section defines the specifics of directly performing symmetric
key encryption without performing a key wrapping step. In this case, key encryption without performing a key wrapping step. In this case,
the shared symmetric key is used directly as the Content Encryption the shared symmetric key is used directly as the Content Encryption
Key (CEK) value for the "enc" algorithm. An empty octet sequence is Key (CEK) value for the "enc" algorithm. An empty octet sequence is
used as the JWE Encrypted Key value. The "alg" header parameter used as the JWE Encrypted Key value. The "alg" Header Parameter
value "dir" is used in this case. value "dir" is used in this case.
Refer to the security considerations on key lifetimes in Section 7.2 Refer to the security considerations on key lifetimes in Section 7.2
and AES GCM in Section 7.4 when considering utilizing direct and AES GCM in Section 7.4 when considering utilizing direct
encryption. encryption.
4.7. Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static 4.7. Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static
(ECDH-ES) (ECDH-ES)
This section defines the specifics of key agreement with Elliptic This section defines the specifics of key agreement with Elliptic
skipping to change at page 22, line 20 skipping to change at page 18, line 45
the Concat KDF, as defined in Section 5.8.1 of [NIST.800-56A]. The the Concat KDF, as defined in Section 5.8.1 of [NIST.800-56A]. The
key agreement result can be used in one of two ways: key agreement result can be used in one of two ways:
1. directly as the Content Encryption Key (CEK) for the "enc" 1. directly as the Content Encryption Key (CEK) for the "enc"
algorithm, in the Direct Key Agreement mode, or algorithm, in the Direct Key Agreement mode, or
2. as a symmetric key used to wrap the CEK with the "A128KW", 2. as a symmetric key used to wrap the CEK with the "A128KW",
"A192KW", or "A256KW" algorithms, in the Key Agreement with Key "A192KW", or "A256KW" algorithms, in the Key Agreement with Key
Wrapping mode. Wrapping mode.
The "alg" header parameter value "ECDH-ES" is used in the Direct Key The "alg" Header Parameter value "ECDH-ES" is used in the Direct Key
Agreement mode and the values "ECDH-ES+A128KW", "ECDH-ES+A192KW", or Agreement mode and the values "ECDH-ES+A128KW", "ECDH-ES+A192KW", or
"ECDH-ES+A256KW" are used in the Key Agreement with Key Wrapping "ECDH-ES+A256KW" are used in the Key Agreement with Key Wrapping
mode. mode.
In the Direct Key Agreement case, the output of the Concat KDF MUST In the Direct Key Agreement case, the output of the Concat KDF MUST
be a key of the same length as that used by the "enc" algorithm; in be a key of the same length as that used by the "enc" algorithm; in
this case, the empty octet sequence is used as the JWE Encrypted Key this case, the empty octet sequence is used as the JWE Encrypted Key
value. In the Key Agreement with Key Wrapping case, the output of value. In the Key Agreement with Key Wrapping case, the output of
the Concat KDF MUST be a key of the length needed for the specified the Concat KDF MUST be a key of the length needed for the specified
key wrapping algorithm, one of 128, 192, or 256 bits respectively. key wrapping algorithm, one of 128, 192, or 256 bits respectively.
A new ephemeral public key value MUST be generated for each key A new ephemeral public key value MUST be generated for each key
agreement operation. agreement operation.
4.7.1. Header Parameters Used for ECDH Key Agreement 4.7.1. Header Parameters Used for ECDH Key Agreement
The following Header Parameter Names are used for key agreement as The following Header Parameter names are used for key agreement as
defined below. defined below.
4.7.1.1. "epk" (Ephemeral Public Key) Header Parameter 4.7.1.1. "epk" (Ephemeral Public Key) Header Parameter
The "epk" (ephemeral public key) value created by the originator for The "epk" (ephemeral public key) value created by the originator for
the use in key agreement algorithms. This key is represented as a the use in key agreement algorithms. This key is represented as a
JSON Web Key [JWK] public key value. It MUST contain only public key JSON Web Key [JWK] public key value. It MUST contain only public key
parameters and SHOULD contain only the minimum JWK parameters parameters and SHOULD contain only the minimum JWK parameters
necessary to represent the key; other JWK parameters included can be necessary to represent the key; other JWK parameters included can be
checked for consistency and honored or can be ignored. This Header checked for consistency and honored or can be ignored. This Header
skipping to change at page 23, line 44 skipping to change at page 20, line 18
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", "ECDH-ES+A192KW", and algorithm. For "ECDH-ES+A128KW", "ECDH-ES+A192KW", and
"ECDH-ES+A256KW", this is 128, 192, and 256, respectively. "ECDH-ES+A256KW", this is 128, 192, and 256, respectively.
AlgorithmID The AlgorithmID value is of the form Datalen || Data, AlgorithmID The AlgorithmID value is of the form Datalen || Data,
where Data is a variable-length string of zero or more octets, and where Data is a variable-length string of zero or more octets, and
Datalen is a fixed-length, big endian 32 bit counter that Datalen is a fixed-length, big endian 32 bit counter that
indicates the length (in octets) of Data, with || being indicates the length (in octets) of Data. In the Direct Key
concatenation. In the Direct Key Agreement case, Data is set to Agreement case, Data is set to the octets of the UTF-8
the octets of the UTF-8 representation of the "enc" header representation of the "enc" Header Parameter value. In the Key
parameter value. In the Key Agreement with Key Wrapping case, Agreement with Key Wrapping case, Data is set to the octets of the
Data is set to the octets of the UTF-8 representation of the "alg" UTF-8 representation of the "alg" Header Parameter value.
header parameter value.
PartyUInfo The PartyUInfo value is of the form Datalen || Data, PartyUInfo The PartyUInfo value is of the form Datalen || Data,
where Data is a variable-length string of zero or more octets, and where Data is a variable-length string of zero or more octets, and
Datalen is a fixed-length, big endian 32 bit counter that Datalen is a fixed-length, big endian 32 bit counter that
indicates the length (in octets) of Data, with || being indicates the length (in octets) of Data. If an "apu" (agreement
concatenation. If an "apu" (agreement PartyUInfo) header PartyUInfo) Header Parameter is present, Data is set to the result
parameter is present, Data is set to the result of base64url of base64url decoding the "apu" value and Datalen is set to the
decoding the "apu" value and Datalen is set to the number of number of octets in Data. Otherwise, Datalen is set to 0 and Data
octets in Data. Otherwise, Datalen is set to 0 and Data is set to is set to the empty octet sequence.
the empty octet sequence.
PartyVInfo The PartyVInfo value is of the form Datalen || Data, PartyVInfo The PartyVInfo value is of the form Datalen || Data,
where Data is a variable-length string of zero or more octets, and where Data is a variable-length string of zero or more octets, and
Datalen is a fixed-length, big endian 32 bit counter that Datalen is a fixed-length, big endian 32 bit counter that
indicates the length (in octets) of Data, with || being indicates the length (in octets) of Data. If an "apv" (agreement
concatenation. If an "apv" (agreement PartyVInfo) header PartyVInfo) Header Parameter is present, Data is set to the result
parameter is present, Data is set to the result of base64url of base64url decoding the "apv" value and Datalen is set to the
decoding the "apv" value and Datalen is set to the number of number of octets in Data. Otherwise, Datalen is set to 0 and Data
octets in Data. Otherwise, Datalen is set to 0 and Data is set to is set to the empty octet sequence.
the empty octet sequence.
SuppPubInfo This is set to the keydatalen represented as a 32 bit SuppPubInfo This is set to the keydatalen represented as a 32 bit
big endian integer. big endian integer.
SuppPrivInfo This is set to the empty octet sequence. SuppPrivInfo This is set to the empty octet sequence.
Applications MUST specify what values should be used in the "apu" and Applications MUST specify what values should be used in the "apu" and
"apv" parameters. The "apu" and "apv" values MUST be distinct. "apv" parameters. The "apu" and "apv" values MUST be distinct.
Applications wishing to conform to [NIST.800-56A] need to provide Applications wishing to conform to [NIST.800-56A] need to provide
values that meet the requirements of that document, e.g., by using values that meet the requirements of that document, e.g., by using
skipping to change at page 24, line 49 skipping to change at page 21, line 18
the "apv" field should not be present. the "apv" field should not be present.
See Appendix D for an example key agreement computation using this See Appendix D for an example key agreement computation using this
method. method.
4.8. Key Encryption with AES GCM 4.8. Key Encryption with AES GCM
This section defines the specifics of encrypting a JWE Content This section defines the specifics of encrypting a JWE Content
Encryption Key (CEK) with Advanced Encryption Standard (AES) in Encryption Key (CEK) with Advanced Encryption Standard (AES) in
Galois/Counter Mode (GCM) [AES] [NIST.800-38D] using 128, 192, or 256 Galois/Counter Mode (GCM) [AES] [NIST.800-38D] using 128, 192, or 256
bit keys. The "alg" header parameter values "A128GCMKW", bit keys. The "alg" Header Parameter values "A128GCMKW",
"A192GCMKW", or "A256GCMKW" are respectively used in this case. "A192GCMKW", or "A256GCMKW" are respectively used in this case.
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. The Initialization Vector is represented in base64url algorithm. The Initialization Vector is represented in base64url
encoded form as the "iv" (initialization vector) header parameter encoded form as the "iv" (initialization vector) Header Parameter
value. value.
The Additional Authenticated Data value used is the empty octet The Additional Authenticated Data value used is the empty octet
string. string.
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 Encrypted Key value is the Ciphertext output. The JWE Encrypted Key value is the Ciphertext output.
The Authentication Tag output is represented in base64url encoded The Authentication Tag output is represented in base64url encoded
form as the "tag" (authentication tag) header parameter value. form as the "tag" (authentication tag) Header Parameter value.
4.8.1. Header Parameters Used for AES GCM Key Encryption 4.8.1. Header Parameters Used for AES GCM Key Encryption
The following Header Parameters are used for AES GCM key encryption. The following Header Parameters are used for AES GCM key encryption.
4.8.1.1. "iv" (Initialization Vector) Header Parameter 4.8.1.1. "iv" (Initialization Vector) Header Parameter
The "iv" (initialization vector) header parameter value is the The "iv" (initialization vector) Header Parameter value is the
base64url encoded representation of the Initialization Vector value base64url encoded representation of the Initialization Vector value
used for the key encryption operation. This Header Parameter is used for the key encryption operation. This Header Parameter is
REQUIRED and MUST be understood and processed by implementations when REQUIRED and MUST be understood and processed by implementations when
these algorithms are used. these algorithms are used.
4.8.1.2. "tag" (Authentication Tag) Header Parameter 4.8.1.2. "tag" (Authentication Tag) Header Parameter
The "tag" (authentication tag) header parameter value is the The "tag" (authentication tag) Header Parameter value is the
base64url encoded representation of the Authentication Tag value base64url encoded representation of the Authentication Tag value
resulting from the key encryption operation. This Header Parameter resulting from the key encryption operation. This Header Parameter
is REQUIRED and MUST be understood and processed by implementations is REQUIRED and MUST be understood and processed by implementations
when these algorithms are used. when these algorithms are used.
4.9. Key Encryption with PBES2 4.9. Key Encryption with PBES2
The "PBES2-HS256+A128KW", "PBES2-HS384+A192KW", and The "PBES2-HS256+A128KW", "PBES2-HS384+A192KW", and
"PBES2-HS512+A256KW" composite algorithms are used to perform "PBES2-HS512+A256KW" composite algorithms are used to perform
password-based encryption of a JWE CEK, by first deriving a key password-based encryption of a JWE CEK, by first deriving a key
encryption key from a user-supplied password, then encrypting the JWE encryption key from a user-supplied password, then encrypting the JWE
CEK using the derived key. These algorithms are PBES2 schemes as CEK using the derived key. These algorithms are PBES2 schemes as
specified in Section 6.2 of [RFC2898]. specified in Section 6.2 of [RFC2898].
These algorithms use HMAC SHA-2 algorithms as the Pseudo-Random These algorithms use HMAC SHA-2 algorithms as the Pseudo-Random
Function (PRF) for the PBKDF2 key derivation and AES Key Wrap Function (PRF) for the PBKDF2 key derivation and AES Key Wrap
[RFC3394] for the encryption scheme. The salt MUST be provided as [RFC3394] for the encryption scheme. The salt MUST be provided as
the "p2s" header parameter value, and MUST be base64url decoded to the "p2s" Header Parameter value, and MUST be base64url decoded to
obtain the value. The iteration count parameter MUST be provided as obtain the value. The iteration count parameter MUST be provided as
the "p2c" header parameter value. The algorithms respectively use the "p2c" Header Parameter value. The algorithms respectively use
HMAC SHA-256, HMAC SHA-384, and HMAC SHA-512 as the PRF and use 128, HMAC SHA-256, HMAC SHA-384, and HMAC SHA-512 as the PRF and use 128,
192, and 256 bit AES Key Wrap keys. Their derived-key lengths 192, and 256 bit AES Key Wrap keys. Their derived-key lengths
respectively are 16, 24, and 32 octets. respectively are 16, 24, and 32 octets.
See Appendix C of JSON Web Key (JWK) [JWK] for an example key
encryption computation using "PBES2-HS256+A128KW".
4.9.1. Header Parameters Used for PBES2 Key Encryption 4.9.1. Header Parameters Used for PBES2 Key Encryption
The following Header Parameters are used for Key Encryption with The following Header Parameters are used for Key Encryption with
PBES2. PBES2.
4.9.1.1. "p2s" (PBES2 salt) Parameter 4.9.1.1. "p2s" (PBES2 salt) Parameter
The "p2s" (PBES2 salt) header parameter contains the PBKDF2 salt The "p2s" (PBES2 salt) Header Parameter contains the PBKDF2 salt
value, encoded using base64url. This Header Parameter is REQUIRED value, encoded using base64url. This Header Parameter is REQUIRED
and MUST be understood and processed by implementations when these and MUST be understood and processed by implementations when these
algorithms are used. algorithms are used.
The salt expands the possible keys that can be derived from a given The salt expands the possible keys that can be derived from a given
password. A salt value containing 8 or more octets MUST be used. A password. A salt value containing 8 or more octets MUST be used. A
new salt value MUST be generated randomly for every encryption new salt value MUST be generated randomly for every encryption
operation; see [RFC4086] for considerations on generating random operation; see [RFC4086] for considerations on generating random
values. values.
4.9.1.2. "p2c" (PBES2 count) Parameter 4.9.1.2. "p2c" (PBES2 count) Parameter
The "p2c" (PBES2 count) header parameter contains the PBKDF2 The "p2c" (PBES2 count) Header Parameter contains the PBKDF2
iteration count, represented as a positive integer. This Header iteration count, represented as a positive integer. This Header
Parameter is REQUIRED and MUST be understood and processed by Parameter is REQUIRED and MUST be understood and processed by
implementations when these algorithms are used. implementations when these algorithms are used.
The iteration count adds computational expense, ideally compounded by The iteration count adds computational expense, ideally compounded by
the possible range of keys introduced by the salt. A minimum the possible range of keys introduced by the salt. A minimum
iteration count of 1000 is RECOMMENDED. iteration count of 1000 is RECOMMENDED.
4.10. AES_CBC_HMAC_SHA2 Algorithms 4.10. AES_CBC_HMAC_SHA2 Algorithms
skipping to change at page 27, line 23 skipping to change at page 23, line 48
4.10.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 4.10.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
A || B.
4.10.2. Generic AES_CBC_HMAC_SHA2 Algorithm 4.10.2. Generic AES_CBC_HMAC_SHA2 Algorithm
This section defines AES_CBC_HMAC_SHA2 in a manner that is This section defines AES_CBC_HMAC_SHA2 in a manner that is
independent of the AES CBC key size or hash function to be used. independent of the AES CBC key size or hash function to be used.
Section 4.10.2.1 and Section 4.10.2.2 define the generic encryption Section 4.10.2.1 and Section 4.10.2.2 define the generic encryption
and decryption algorithms. Section 4.10.3 and Section 4.10.5 define and decryption algorithms. Section 4.10.3 and Section 4.10.5 define
instances of AES_CBC_HMAC_SHA2 that specify those details. instances of AES_CBC_HMAC_SHA2 that specify those details.
4.10.2.1. AES_CBC_HMAC_SHA2 Encryption 4.10.2.1. AES_CBC_HMAC_SHA2 Encryption
skipping to change at page 31, line 5 skipping to change at page 27, line 30
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. 16.
4.10.6. Plaintext Encryption with AES_CBC_HMAC_SHA2 4.10.6. 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
"A192CBC-HS384" is used as the "alg" value when using "A192CBC-HS384" is used as the "alg" value when using
AES_192_CBC_HMAC_SHA_384 with JWE. The algorithm value AES_192_CBC_HMAC_SHA_384 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. The Additional Authenticated Data AES_256_CBC_HMAC_SHA_512 with JWE.
value used is the octets of the ASCII representation of the Encoded
JWE Header value. The JWE Initialization Vector value used is the IV
value.
4.11. Plaintext Encryption with AES GCM 4.11. 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, 192, or 256 bit keys. The "enc" [AES] [NIST.800-38D] using 128, 192, or 256 bit keys. The "enc"
header parameter values "A128GCM", "A192GCM", or "A256GCM" are Header Parameter values "A128GCM", "A192GCM", or "A256GCM" are
respectively used in this case. respectively 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 value used is the octets of the
ASCII representation of the Encoded JWE Header value.
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].
5. Cryptographic Algorithms for Keys 5. Cryptographic Algorithms for Keys
skipping to change at page 32, line 38 skipping to change at page 28, line 51
drawn from a finite field, which together define a point on an drawn from a finite field, which together define a point on an
elliptic curve. The following members MUST be present for elliptic elliptic curve. The following members MUST be present for elliptic
curve public keys: curve public keys:
o "crv" o "crv"
o "x" o "x"
o "y" o "y"
SEC1 point compression is not supported for any values.
5.2.1.1. "crv" (Curve) Parameter 5.2.1.1. "crv" (Curve) Parameter
The "crv" (curve) member identifies the cryptographic curve used with The "crv" (curve) member identifies the cryptographic curve used with
the key. Curve values from [DSS] used by this specification are: the key. Curve values from [DSS] used by this specification are:
o "P-256" o "P-256"
o "P-384" o "P-384"
o "P-521" o "P-521"
skipping to change at page 37, line 38 skipping to change at page 34, line 11
this specification, in order to enable broadly-informed review of this specification, in order to enable broadly-informed review of
registration decisions. In cases where a registration decision could registration decisions. In cases where a registration decision could
be perceived as creating a conflict of interest for a particular be perceived as creating a conflict of interest for a particular
Expert, that Expert should defer to the judgment of the other Expert, that Expert should defer to the judgment of the other
Expert(s). Expert(s).
6.1. JSON Web Signature and Encryption Algorithms Registry 6.1. JSON Web Signature and Encryption Algorithms Registry
This specification establishes the IANA JSON Web Signature and This specification establishes the IANA JSON Web Signature and
Encryption Algorithms registry for values of the JWS and JWE "alg" Encryption Algorithms registry for values of the JWS and JWE "alg"
(algorithm) and "enc" (encryption method) header parameters. The (algorithm) and "enc" (encryption method) Header Parameters. The
registry records the algorithm name, the algorithm usage locations registry records the algorithm name, the algorithm usage locations
from the set "alg" and "enc", implementation requirements, and a from the set "alg" and "enc", implementation requirements, and a
reference to the specification that defines it. The same algorithm reference to the specification that defines it. The same algorithm
name MAY be registered multiple times, provided that the sets of name MAY be registered multiple times, provided that the sets of
usage locations are disjoint. usage locations are disjoint.
It is suggested that when algorithms can use keys of different It is suggested that when algorithms can use keys of different
lengths, that the length of the key be included in the algorithm lengths, that the length of the key be included in the algorithm
name. This allows readers of the JSON text to easily make security name. This allows readers of the JSON text to easily make security
consideration decisions. consideration decisions.
skipping to change at page 43, line 26 skipping to change at page 39, line 44
o Specification Document(s): Section 4.2 of [[ this document ]] o Specification Document(s): Section 4.2 of [[ this document ]]
o Algorithm Name: "A256GCM" o Algorithm Name: "A256GCM"
o Algorithm Usage Location(s): "enc" o Algorithm Usage Location(s): "enc"
o Implementation Requirements: Recommended o Implementation Requirements: Recommended
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 4.2 of [[ this document ]] o Specification Document(s): Section 4.2 of [[ this document ]]
6.2. JWE Header Parameter Names Registration 6.2. JWE Header Parameter Names Registration
This specification registers the Header Parameter Names defined in This specification registers the Header Parameter names defined in
Section 4.7.1, Section 4.8.1, and Section 4.9.1 in the IANA JSON Web Section 4.7.1, Section 4.8.1, and Section 4.9.1 in the IANA JSON Web
Signature and Encryption Header Parameters registry defined in [JWS]. Signature and Encryption Header Parameters registry defined in [JWS].
6.2.1. Registry Contents 6.2.1. Registry Contents
o Header Parameter Name: "epk" o Header Parameter Name: "epk"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 4.7.1.1 of [[ this document ]] o Specification Document(s): Section 4.7.1.1 of [[ this document ]]
o Header Parameter Name: "apu" o Header Parameter Name: "apu"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 4.7.1.2 of [[ this document ]] o Specification Document(s): Section 4.7.1.2 of [[ this document ]]
skipping to change at page 53, line 25 skipping to change at page 50, line 7
[I-D.melnikov-precis-saslprepbis] [I-D.melnikov-precis-saslprepbis]
Saint-Andre, P. and A. Melnikov, "Preparation and Saint-Andre, P. and A. Melnikov, "Preparation and
Comparison of Internationalized Strings Representing Comparison of Internationalized Strings Representing
Simple User Names and Passwords", Simple User Names and Passwords",
draft-melnikov-precis-saslprepbis-04 (work in progress), draft-melnikov-precis-saslprepbis-04 (work in progress),
September 2012. September 2012.
[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), September 2013. (work in progress), October 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),
September 2013. October 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), September 2013. in progress), October 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 54, line 25 skipping to change at page 51, line 8
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003. 10646", STD 63, RFC 3629, November 2003.
[RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness
Requirements for Security", BCP 106, RFC 4086, June 2005. Requirements for Security", BCP 106, RFC 4086, June 2005.
[RFC4627] Crockford, D., "The application/json Media Type for [RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006. JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, October 2006.
[RFC4868] Kelly, S. and S. Frankel, "Using HMAC-SHA-256, HMAC-SHA- [RFC4868] Kelly, S. and S. Frankel, "Using HMAC-SHA-256, HMAC-SHA-
384, and HMAC-SHA-512 with IPsec", RFC 4868, May 2007. 384, and HMAC-SHA-512 with IPsec", RFC 4868, May 2007.
[RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated
Encryption", RFC 5116, January 2008. Encryption", RFC 5116, January 2008.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226, IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008. May 2008.
skipping to change at page 62, line 37 skipping to change at page 58, line 37
agreement computation in this example (including the private part) agreement computation in this example (including the private part)
is: is:
{"kty":"EC", {"kty":"EC",
"crv":"P-256", "crv":"P-256",
"x":"weNJy2HscCSM6AEDTDg04biOvhFhyyWvOHQfeF_PxMQ", "x":"weNJy2HscCSM6AEDTDg04biOvhFhyyWvOHQfeF_PxMQ",
"y":"e8lnCO-AlStT-NJVX-crhB7QRYhiix03illJOVAOyck", "y":"e8lnCO-AlStT-NJVX-crhB7QRYhiix03illJOVAOyck",
"d":"VEmDZpDXXK8p8N0Cndsxs924q6nS1RXFASRl6BfUqdw" "d":"VEmDZpDXXK8p8N0Cndsxs924q6nS1RXFASRl6BfUqdw"
} }
Header parameter values used in this example are as follows. In this Header Parameter values used in this example are as follows. In this
example, the "apu" (agreement PartyUInfo) parameter value is the example, the "apu" (agreement PartyUInfo) parameter value is the
base64url encoding of the UTF-8 string "Alice" and the "apv" base64url encoding of the UTF-8 string "Alice" and the "apv"
(agreement PartyVInfo) parameter value is the base64url encoding of (agreement PartyVInfo) parameter value is the base64url encoding of
the UTF-8 string "Bob". The "epk" parameter is used to communicate the UTF-8 string "Bob". The "epk" parameter is used to communicate
the sender's (Alice's) ephemeral public key value to the recipient the sender's (Alice's) ephemeral public key value to the recipient
(Bob). (Bob).
{"alg":"ECDH-ES", {"alg":"ECDH-ES",
"enc":"A128GCM", "enc":"A128GCM",
"apu":"QWxpY2U", "apu":"QWxpY2U",
skipping to change at page 64, line 24 skipping to change at page 60, line 24
0, 0, 0, 7, 65, 49, 50, 56, 71, 67, 77, 0, 0, 0, 5, 65, 108, 105, 99, 0, 0, 0, 7, 65, 49, 50, 56, 71, 67, 77, 0, 0, 0, 5, 65, 108, 105, 99,
101, 0, 0, 0, 3, 66, 111, 98, 0, 0, 0, 128] 101, 0, 0, 0, 3, 66, 111, 98, 0, 0, 0, 128]
The resulting derived key, which is the first 128 bits of the round 1 The resulting derived key, which is the first 128 bits of the round 1
hash output is: hash output is:
[86, 170, 141, 234, 248, 35, 109, 32, 92, 34, 40, 205, 113, 167, 16, [86, 170, 141, 234, 248, 35, 109, 32, 92, 34, 40, 205, 113, 167, 16,
26] 26]
The base64url encoded representation of this derived key is: The base64url encoded representation of this derived key is:
usEpwFIC_qrmBExntFwxMA VqqN6vgjbSBcIijNcacQGg
Appendix E. Acknowledgements Appendix E. Acknowledgements
Solutions for signing and encrypting JSON content were previously Solutions for signing and encrypting JSON content were previously
explored by Magic Signatures [MagicSignatures], JSON Simple Sign explored by Magic Signatures [MagicSignatures], JSON Simple Sign
[JSS], Canvas Applications [CanvasApp], JSON Simple Encryption [JSE], [JSS], Canvas Applications [CanvasApp], JSON Simple Encryption [JSE],
and JavaScript Message Security Format [I-D.rescorla-jsms], all of and JavaScript Message Security Format [I-D.rescorla-jsms], all of
which influenced this draft. which influenced this draft.
The Authenticated Encryption with AES-CBC and HMAC-SHA The Authenticated Encryption with AES-CBC and HMAC-SHA
skipping to change at page 65, line 17 skipping to change at page 61, line 17
Sean Turner. 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 F. Document History Appendix F. 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 ]]
-17
o Explicitly named all the logical components of a JWS and JWE and
defined the processing rules and serializations in terms of those
components, addressing issues #60, #61, and #62.
o Removed processing steps in algorithm definitions that duplicated
processing steps in JWS or JWE, addressing issue #56.
o Replaced verbose repetitive phases such as "base64url encode the
octets of the UTF-8 representation of X" with mathematical
notation such as "BASE64URL(UTF8(X))".
o Terms used in multiple documents are now defined in one place and
incorporated by reference. Some lightly used or obvious terms
were also removed. This addresses issue #58.
o Changes to address minor issue #53.
-16 -16
o Added a DataLen prefix to the AlgorithmID value in the Concat KDF o Added a DataLen prefix to the AlgorithmID value in the Concat KDF
computation. computation.
o Added OIDs for encryption algorithms, additional signature o Added OIDs for encryption algorithms, additional signature
algorithm OIDs, and additional XML DSIG/ENC URIs in the algorithm algorithm OIDs, and additional XML DSIG/ENC URIs in the algorithm
cross-reference tables. cross-reference tables.
o Changes to address editorial and minor issues #28, #36, #39, #52, o Changes to address editorial and minor issues #28, #36, #39, #52,
 End of changes. 72 change blocks. 
417 lines changed or deleted 245 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/