 1/draftietfjosejsonwebalgorithms18.txt 20131229 05:25:55.808306409 0800
+++ 2/draftietfjosejsonwebalgorithms19.txt 20131229 05:25:56.000311155 0800
@@ 1,18 +1,18 @@
JOSE Working Group M. Jones
InternetDraft Microsoft
Intended status: Standards Track November 12, 2013
Expires: May 16, 2014
+Intended status: Standards Track December 29, 2013
+Expires: July 2, 2014
JSON Web Algorithms (JWA)
 draftietfjosejsonwebalgorithms18
+ draftietfjosejsonwebalgorithms19
Abstract
The JSON Web Algorithms (JWA) specification registers cryptographic
algorithms and identifiers to be used with the JSON Web Signature
(JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK)
specifications. It defines several IANA registries for these
identifiers.
Status of this Memo
@@ 23,21 +23,21 @@
InternetDrafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as InternetDrafts. The list of current Internet
Drafts is at http://datatracker.ietf.org/drafts/current/.
InternetDrafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use InternetDrafts as reference
material or to cite them other than as "work in progress."
 This InternetDraft will expire on May 16, 2014.
+ This InternetDraft will expire on July 2, 2014.
Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/licenseinfo) in effect on the date of
publication of this document. Please review these documents
@@ 51,123 +51,123 @@
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. Cryptographic Algorithms for Digital Signatures and MACs . . . 6
3.1. "alg" (Algorithm) Header Parameter Values for JWS . . . . 6
3.2. HMAC with SHA2 Functions . . . . . . . . . . . . . . . . 7
3.3. Digital Signature with RSASSAPKCS1V1_5 . . . . . . . . . 8
3.4. Digital Signature with ECDSA . . . . . . . . . . . . . . . 9
3.5. Digital Signature with RSASSAPSS . . . . . . . . . . . . 10
 3.6. Using the Algorithm "none" . . . . . . . . . . . . . . . . 10
 4. Cryptographic Algorithms for Key Management . . . . . . . . . 11
 4.1. "alg" (Algorithm) Header Parameter Values for JWE . . . . 11
 4.2. Key Encryption with RSAESPKCS1V1_5 . . . . . . . . . . . 13
 4.3. Key Encryption with RSAES OAEP . . . . . . . . . . . . . . 13
 4.4. Key Wrapping with AES Key Wrap . . . . . . . . . . . . . . 13
 4.5. Direct Encryption with a Shared Symmetric Key . . . . . . 14
+ 3.6. Using the Algorithm "none" . . . . . . . . . . . . . . . . 11
+ 4. Cryptographic Algorithms for Key Management . . . . . . . . . 12
+ 4.1. "alg" (Algorithm) Header Parameter Values for JWE . . . . 12
+ 4.2. Key Encryption with RSAESPKCS1V1_5 . . . . . . . . . . . 14
+ 4.3. Key Encryption with RSAES OAEP . . . . . . . . . . . . . . 14
+ 4.4. Key Wrapping with AES Key Wrap . . . . . . . . . . . . . . 14
+ 4.5. Direct Encryption with a Shared Symmetric Key . . . . . . 15
4.6. Key Agreement with Elliptic Curve DiffieHellman
 Ephemeral Static (ECDHES) . . . . . . . . . . . . . . . . 14
 4.6.1. Header Parameters Used for ECDH Key Agreement . . . . 14
 4.6.1.1. "epk" (Ephemeral Public Key) Header Parameter . . 15
 4.6.1.2. "apu" (Agreement PartyUInfo) Header Parameter . . 15
 4.6.1.3. "apv" (Agreement PartyVInfo) Header Parameter . . 15
 4.6.2. Key Derivation for ECDH Key Agreement . . . . . . . . 15
 4.7. Key Encryption with AES GCM . . . . . . . . . . . . . . . 17
 4.7.1. Header Parameters Used for AES GCM Key Encryption . . 17
 4.7.1.1. "iv" (Initialization Vector) Header Parameter . . 17
 4.7.1.2. "tag" (Authentication Tag) Header Parameter . . . 17
 4.8. Key Encryption with PBES2 . . . . . . . . . . . . . . . . 17
 4.8.1. Header Parameters Used for PBES2 Key Encryption . . . 18
 4.8.1.1. "p2s" (PBES2 salt) Parameter . . . . . . . . . . . 18
 4.8.1.2. "p2c" (PBES2 count) Parameter . . . . . . . . . . 18
 5. Cryptographic Algorithms for Content Encryption . . . . . . . 19
 5.1. "enc" (Encryption Method) Header Parameter Values for
 JWE . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
 5.2. AES_CBC_HMAC_SHA2 Algorithms . . . . . . . . . . . . . . . 20
 5.2.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 . . . . 20
 5.2.2. Generic AES_CBC_HMAC_SHA2 Algorithm . . . . . . . . . 20
 5.2.2.1. AES_CBC_HMAC_SHA2 Encryption . . . . . . . . . . . 20
 5.2.2.2. AES_CBC_HMAC_SHA2 Decryption . . . . . . . . . . . 22
 5.2.3. AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . 23
 5.2.4. AES_192_CBC_HMAC_SHA_384 . . . . . . . . . . . . . . . 23
 5.2.5. AES_256_CBC_HMAC_SHA_512 . . . . . . . . . . . . . . . 23
 5.2.6. Plaintext Encryption with AES_CBC_HMAC_SHA2 . . . . . 24
 5.3. Plaintext Encryption with AES GCM . . . . . . . . . . . . 24
 6. Cryptographic Algorithms for Keys . . . . . . . . . . . . . . 24
 6.1. "kty" (Key Type) Parameter Values . . . . . . . . . . . . 25
 6.2. Parameters for Elliptic Curve Keys . . . . . . . . . . . . 25
 6.2.1. Parameters for Elliptic Curve Public Keys . . . . . . 25
 6.2.1.1. "crv" (Curve) Parameter . . . . . . . . . . . . . 25
 6.2.1.2. "x" (X Coordinate) Parameter . . . . . . . . . . . 26
 6.2.1.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . 26
 6.2.2. Parameters for Elliptic Curve Private Keys . . . . . . 26
 6.2.2.1. "d" (ECC Private Key) Parameter . . . . . . . . . 26
 6.3. Parameters for RSA Keys . . . . . . . . . . . . . . . . . 26
 6.3.1. Parameters for RSA Public Keys . . . . . . . . . . . . 27
 6.3.1.1. "n" (Modulus) Parameter . . . . . . . . . . . . . 27
 6.3.1.2. "e" (Exponent) Parameter . . . . . . . . . . . . . 27
 6.3.2. Parameters for RSA Private Keys . . . . . . . . . . . 27
 6.3.2.1. "d" (Private Exponent) Parameter . . . . . . . . . 27
 6.3.2.2. "p" (First Prime Factor) Parameter . . . . . . . . 27
 6.3.2.3. "q" (Second Prime Factor) Parameter . . . . . . . 28
 6.3.2.4. "dp" (First Factor CRT Exponent) Parameter . . . . 28
 6.3.2.5. "dq" (Second Factor CRT Exponent) Parameter . . . 28
 6.3.2.6. "qi" (First CRT Coefficient) Parameter . . . . . . 28
 6.3.2.7. "oth" (Other Primes Info) Parameter . . . . . . . 28
 6.4. Parameters for Symmetric Keys . . . . . . . . . . . . . . 29
 6.4.1. "k" (Key Value) Parameter . . . . . . . . . . . . . . 29
 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29
 7.1. JSON Web Signature and Encryption Algorithms Registry . . 30
 7.1.1. Registration Template . . . . . . . . . . . . . . . . 31
 7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 32
 7.2. JWE Header Parameter Names Registration . . . . . . . . . 37
 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 38
 7.3. JSON Web Encryption Compression Algorithms Registry . . . 38
 7.3.1. Registration Template . . . . . . . . . . . . . . . . 39
 7.3.2. Initial Registry Contents . . . . . . . . . . . . . . 39
 7.4. JSON Web Key Types Registry . . . . . . . . . . . . . . . 39
 7.4.1. Registration Template . . . . . . . . . . . . . . . . 40
 7.4.2. Initial Registry Contents . . . . . . . . . . . . . . 40
 7.5. JSON Web Key Parameters Registration . . . . . . . . . . . 41
 7.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 41
 7.6. JSON Web Key Elliptic Curve Registry . . . . . . . . . . . 43
 7.6.1. Registration Template . . . . . . . . . . . . . . . . 43
 7.6.2. Initial Registry Contents . . . . . . . . . . . . . . 44
 8. Security Considerations . . . . . . . . . . . . . . . . . . . 45
 8.1. Algorithms and Key Sizes will be Deprecated . . . . . . . 45
 8.2. Key Lifetimes . . . . . . . . . . . . . . . . . . . . . . 45
 8.3. RSAESPKCS1v1_5 Security Considerations . . . . . . . . . 45
 8.4. AES GCM Security Considerations . . . . . . . . . . . . . 46
 8.5. Plaintext JWS Security Considerations . . . . . . . . . . 46
 8.6. Differences between Digital Signatures and MACs . . . . . 47
 8.7. Denial of Service Attacks . . . . . . . . . . . . . . . . 47
 8.8. Reusing Key Material when Encrypting Keys . . . . . . . . 47
 8.9. Password Considerations . . . . . . . . . . . . . . . . . 48
+ Ephemeral Static (ECDHES) . . . . . . . . . . . . . . . . 15
+ 4.6.1. Header Parameters Used for ECDH Key Agreement . . . . 16
+ 4.6.1.1. "epk" (Ephemeral Public Key) Header Parameter . . 16
+ 4.6.1.2. "apu" (Agreement PartyUInfo) Header Parameter . . 16
+ 4.6.1.3. "apv" (Agreement PartyVInfo) Header Parameter . . 16
+ 4.6.2. Key Derivation for ECDH Key Agreement . . . . . . . . 17
+ 4.7. Key Encryption with AES GCM . . . . . . . . . . . . . . . 18
+ 4.7.1. Header Parameters Used for AES GCM Key Encryption . . 19
+ 4.7.1.1. "iv" (Initialization Vector) Header Parameter . . 19
+ 4.7.1.2. "tag" (Authentication Tag) Header Parameter . . . 19
+ 4.8. Key Encryption with PBES2 . . . . . . . . . . . . . . . . 19
+ 4.8.1. Header Parameters Used for PBES2 Key Encryption . . . 20
+ 4.8.1.1. "p2s" (PBES2 salt) Parameter . . . . . . . . . . . 20
+ 4.8.1.2. "p2c" (PBES2 count) Parameter . . . . . . . . . . 20
+ 5. Cryptographic Algorithms for Content Encryption . . . . . . . 21
+ 5.1. "enc" (Encryption Algorithm) Header Parameter Values
+ for JWE . . . . . . . . . . . . . . . . . . . . . . . . . 21
+ 5.2. AES_CBC_HMAC_SHA2 Algorithms . . . . . . . . . . . . . . . 22
+ 5.2.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 . . . . 22
+ 5.2.2. Generic AES_CBC_HMAC_SHA2 Algorithm . . . . . . . . . 22
+ 5.2.2.1. AES_CBC_HMAC_SHA2 Encryption . . . . . . . . . . . 22
+ 5.2.2.2. AES_CBC_HMAC_SHA2 Decryption . . . . . . . . . . . 24
+ 5.2.3. AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . 25
+ 5.2.4. AES_192_CBC_HMAC_SHA_384 . . . . . . . . . . . . . . . 25
+ 5.2.5. AES_256_CBC_HMAC_SHA_512 . . . . . . . . . . . . . . . 25
+ 5.2.6. Content Encryption with AES_CBC_HMAC_SHA2 . . . . . . 26
+ 5.3. Content Encryption with AES GCM . . . . . . . . . . . . . 26
+ 6. Cryptographic Algorithms for Keys . . . . . . . . . . . . . . 27
+ 6.1. "kty" (Key Type) Parameter Values . . . . . . . . . . . . 27
+ 6.2. Parameters for Elliptic Curve Keys . . . . . . . . . . . . 27
+ 6.2.1. Parameters for Elliptic Curve Public Keys . . . . . . 28
+ 6.2.1.1. "crv" (Curve) Parameter . . . . . . . . . . . . . 28
+ 6.2.1.2. "x" (X Coordinate) Parameter . . . . . . . . . . . 28
+ 6.2.1.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . 28
+ 6.2.2. Parameters for Elliptic Curve Private Keys . . . . . . 29
+ 6.2.2.1. "d" (ECC Private Key) Parameter . . . . . . . . . 29
+ 6.3. Parameters for RSA Keys . . . . . . . . . . . . . . . . . 29
+ 6.3.1. Parameters for RSA Public Keys . . . . . . . . . . . . 29
+ 6.3.1.1. "n" (Modulus) Parameter . . . . . . . . . . . . . 29
+ 6.3.1.2. "e" (Exponent) Parameter . . . . . . . . . . . . . 29
+ 6.3.2. Parameters for RSA Private Keys . . . . . . . . . . . 30
+ 6.3.2.1. "d" (Private Exponent) Parameter . . . . . . . . . 30
+ 6.3.2.2. "p" (First Prime Factor) Parameter . . . . . . . . 30
+ 6.3.2.3. "q" (Second Prime Factor) Parameter . . . . . . . 30
+ 6.3.2.4. "dp" (First Factor CRT Exponent) Parameter . . . . 30
+ 6.3.2.5. "dq" (Second Factor CRT Exponent) Parameter . . . 31
+ 6.3.2.6. "qi" (First CRT Coefficient) Parameter . . . . . . 31
+ 6.3.2.7. "oth" (Other Primes Info) Parameter . . . . . . . 31
+ 6.4. Parameters for Symmetric Keys . . . . . . . . . . . . . . 32
+ 6.4.1. "k" (Key Value) Parameter . . . . . . . . . . . . . . 32
+ 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32
+ 7.1. JSON Web Signature and Encryption Algorithms Registry . . 33
+ 7.1.1. Registration Template . . . . . . . . . . . . . . . . 33
+ 7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 34
+ 7.2. JWE Header Parameter Names Registration . . . . . . . . . 40
+ 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 40
+ 7.3. JSON Web Encryption Compression Algorithms Registry . . . 41
+ 7.3.1. Registration Template . . . . . . . . . . . . . . . . 41
+ 7.3.2. Initial Registry Contents . . . . . . . . . . . . . . 42
+ 7.4. JSON Web Key Types Registry . . . . . . . . . . . . . . . 42
+ 7.4.1. Registration Template . . . . . . . . . . . . . . . . 42
+ 7.4.2. Initial Registry Contents . . . . . . . . . . . . . . 43
+ 7.5. JSON Web Key Parameters Registration . . . . . . . . . . . 44
+ 7.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 44
+ 7.6. JSON Web Key Elliptic Curve Registry . . . . . . . . . . . 46
+ 7.6.1. Registration Template . . . . . . . . . . . . . . . . 46
+ 7.6.2. Initial Registry Contents . . . . . . . . . . . . . . 47
+ 8. Security Considerations . . . . . . . . . . . . . . . . . . . 47
+ 8.1. Algorithms and Key Sizes will be Deprecated . . . . . . . 48
+ 8.2. Key Lifetimes . . . . . . . . . . . . . . . . . . . . . . 48
+ 8.3. RSAESPKCS1v1_5 Security Considerations . . . . . . . . . 48
+ 8.4. AES GCM Security Considerations . . . . . . . . . . . . . 48
+ 8.5. Plaintext JWS Security Considerations . . . . . . . . . . 49
+ 8.6. Differences between Digital Signatures and MACs . . . . . 49
+ 8.7. Denial of Service Attacks . . . . . . . . . . . . . . . . 50
+ 8.8. Reusing Key Material when Encrypting Keys . . . . . . . . 50
+ 8.9. Password Considerations . . . . . . . . . . . . . . . . . 50
 9. Internationalization Considerations . . . . . . . . . . . . . 48
 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 48
 10.1. Normative References . . . . . . . . . . . . . . . . . . . 48
 10.2. Informative References . . . . . . . . . . . . . . . . . . 50
 Appendix A. Algorithm Identifier CrossReference . . . . . . . . 52
+ 9. Internationalization Considerations . . . . . . . . . . . . . 51
+ 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 51
+ 10.1. Normative References . . . . . . . . . . . . . . . . . . . 51
+ 10.2. Informative References . . . . . . . . . . . . . . . . . . 53
+ Appendix A. Algorithm Identifier CrossReference . . . . . . . . 54
A.1. Digital Signature/MAC Algorithm Identifier
 CrossReference . . . . . . . . . . . . . . . . . . . . . 52
 A.2. Key Management Algorithm Identifier CrossReference . . . 53
 A.3. Content Encryption Algorithm Identifier CrossReference . 53
 Appendix B. Test Cases for AES_CBC_HMAC_SHA2 Algorithms . . . . . 54
 B.1. Test Cases for AES_128_CBC_HMAC_SHA_256 . . . . . . . . . 55
 B.2. Test Cases for AES_192_CBC_HMAC_SHA_384 . . . . . . . . . 56
 B.3. Test Cases for AES_256_CBC_HMAC_SHA_512 . . . . . . . . . 57
 Appendix C. Example ECDHES Key Agreement Computation . . . . . . 58
 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 60
 Appendix E. Document History . . . . . . . . . . . . . . . . . . 61
 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 68
+ CrossReference . . . . . . . . . . . . . . . . . . . . . 55
+ A.2. Key Management Algorithm Identifier CrossReference . . . 55
+ A.3. Content Encryption Algorithm Identifier CrossReference . 56
+ Appendix B. Test Cases for AES_CBC_HMAC_SHA2 Algorithms . . . . . 57
+ B.1. Test Cases for AES_128_CBC_HMAC_SHA_256 . . . . . . . . . 58
+ B.2. Test Cases for AES_192_CBC_HMAC_SHA_384 . . . . . . . . . 59
+ B.3. Test Cases for AES_256_CBC_HMAC_SHA_512 . . . . . . . . . 60
+ Appendix C. Example ECDHES Key Agreement Computation . . . . . . 61
+ Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 63
+ Appendix E. Document History . . . . . . . . . . . . . . . . . . 64
+ Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 71
1. Introduction
The JSON Web Algorithms (JWA) specification registers cryptographic
algorithms and identifiers to be used with the JSON Web Signature
(JWS) [JWS], JSON Web Encryption (JWE) [JWE], and JSON Web Key (JWK)
[JWK] specifications. It defines several IANA registries for these
identifiers. All these specifications utilize JavaScript Object
Notation (JSON) [RFC4627] based data structures. This specification
also describes the semantics and operations that are specific to
@@ 277,178 +277,212 @@
See Appendix A.1 for a table crossreferencing the JWS digital
signature and MAC "alg" (algorithm) values defined in this
specification with the equivalent identifiers used by other standards
and software packages.
3.2. HMAC with SHA2 Functions
Hashbased Message Authentication Codes (HMACs) enable one to use a
secret plus a cryptographic hash function to generate a Message
Authentication Code (MAC). This can be used to demonstrate that
 whoever generated the MAC was in possession of the MAC key.

 The algorithm for implementing and validating HMACs is provided in
 RFC 2104 [RFC2104]. This section defines the use of the HMAC SHA
 256, HMAC SHA384, and HMAC SHA512 functions [SHS]. The "alg"
 (algorithm) Header Parameter values "HS256", "HS384", and "HS512" are
 used in the JWS Header to indicate that the JWS Signature contains an
 HMAC value using the respective hash function.
+ whoever generated the MAC was in possession of the MAC key. The
+ algorithm for implementing and validating HMACs is provided in RFC
+ 2104 [RFC2104].
A key of the same size as the hash output (for instance, 256 bits for
"HS256") or larger MUST be used with this algorithm.
The HMAC SHA256 MAC is generated per RFC 2104, using SHA256 as the
hash algorithm "H", using the JWS Signing Input as the "text" value,
and using the shared key. The HMAC output value is the JWS
Signature.
+ The following "alg" (algorithm) Header Parameter values are used to
+ indicate that the JWS Signature is an HMAC value computed using the
+ corresponding algorithm:
+
+ +++
+  alg Parameter Value  MAC Algorithm 
+ +++
+  HS256  HMAC using SHA256 
+  HS384  HMAC using SHA384 
+  HS512  HMAC using SHA512 
+ +++
+
The HMAC SHA256 MAC for a JWS is validated by computing an HMAC
value per RFC 2104, using SHA256 as the hash algorithm "H", using
the received JWS Signing Input as the "text" value, and using the
shared key. This computed HMAC value is then compared to the result
of base64url decoding the received encoded JWS Signature value.
Alternatively, the computed HMAC value can be base64url encoded and
compared to the received encoded JWS Signature value, as this
comparison produces the same result as comparing the unencoded
values. In either case, if the values match, the HMAC has been
validated.
 Securing content with the HMAC SHA384 and HMAC SHA512 algorithms is
 performed identically to the procedure for HMAC SHA256  just using
 the corresponding hash algorithms with correspondingly larger minimum
 key sizes and result values: 384 bits each for HMAC SHA384 and 512
 bits each for HMAC SHA512.
+ Securing content and validation with the HMAC SHA384 and HMAC SHA
+ 512 algorithms is performed identically to the procedure for HMAC
+ SHA256  just using the corresponding hash algorithms with
+ correspondingly larger minimum key sizes and result values: 384 bits
+ each for HMAC SHA384 and 512 bits each for HMAC SHA512.
An example using this algorithm is shown in Appendix A.1 of [JWS].
3.3. Digital Signature with RSASSAPKCS1V1_5
This section defines the use of the RSASSAPKCS1V1_5 digital
signature algorithm as defined in Section 8.2 of RFC 3447 [RFC3447]
 (commonly known as PKCS #1), using SHA256, SHA384, or SHA512 [SHS]
 as the hash functions. The "alg" (algorithm) header parameter values
 "RS256", "RS384", and "RS512" are used in the JWS Header to indicate
 that the JWS Signature contains a RSASSAPKCS1V1_5 digital signature
 using the respective hash function.
+ (commonly known as PKCS #1), using SHA2 [SHS] hash functions.
A key of size 2048 bits or larger MUST be used with these algorithms.
The RSASSAPKCS1V1_5 SHA256 digital signature is generated as
follows: Generate a digital signature of the JWS Signing Input using
RSASSAPKCS1V1_5SIGN and the SHA256 hash function with the desired
private key. This is the JWS Signature value.
+ The following "alg" (algorithm) Header Parameter values are used to
+ indicate that the JWS Signature is a digital signature value computed
+ using the corresponding algorithm:
+
+ +++
+  alg Parameter Value  Digital Signature Algorithm 
+ +++
+  RS256  RSASSAPKCSv1_5 using SHA256 
+  RS384  RSASSAPKCSv1_5 using SHA384 
+  RS512  RSASSAPKCSv1_5 using SHA512 
+ +++
+
The RSASSAPKCS1V1_5 SHA256 digital signature for a JWS is
validated as follows: Submit the JWS Signing Input, the JWS
Signature, and the public key corresponding to the private key used
by the signer to the RSASSAPKCS1V1_5VERIFY algorithm using SHA256
as the hash function.
 Signing with the RSASSAPKCS1V1_5 SHA384 and RSASSAPKCS1V1_5 SHA
 512 algorithms is performed identically to the procedure for RSASSA
 PKCS1V1_5 SHA256  just using the corresponding hash algorithms
 instead of SHA256.
+ Signing and validation with the RSASSAPKCS1V1_5 SHA384 and RSASSA
+ PKCS1V1_5 SHA512 algorithms is performed identically to the
+ procedure for RSASSAPKCS1V1_5 SHA256  just using the
+ corresponding hash algorithms instead of SHA256.
An example using this algorithm is shown in Appendix A.2 of [JWS].
3.4. Digital Signature with ECDSA
The Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] provides
for the use of Elliptic Curve cryptography, which is able to provide
equivalent security to RSA cryptography but using shorter key sizes
and with greater processing speed. This means that ECDSA digital
signatures will be substantially smaller in terms of length than
equivalently strong RSA digital signatures.
This specification defines the use of ECDSA with the P256 curve and
the SHA256 cryptographic hash function, ECDSA with the P384 curve
and the SHA384 hash function, and ECDSA with the P521 curve and the
SHA512 hash function. The P256, P384, and P521 curves are
 defined in [DSS]. The "alg" (algorithm) Header Parameter values
 "ES256", "ES384", and "ES512" are used in the JWS Header to indicate
 that the JWS Signature contains a base64url encoded ECDSA P256 SHA
 256, ECDSA P384 SHA384, or ECDSA P521 SHA512 digital signature,
 respectively.
+ defined in [DSS].
The ECDSA P256 SHA256 digital signature is generated as follows:
1. Generate a digital signature of the JWS Signing Input using ECDSA
P256 SHA256 with the desired private key. The output will be
the pair (R, S), where R and S are 256 bit unsigned integers.
2. Turn R and S into octet sequences in big endian order, with each
array being be 32 octets long. The octet sequence
representations MUST NOT be shortened to omit any leading zero
octets contained in the values.
3. Concatenate the two octet sequences in the order R and then S.
(Note that many ECDSA implementations will directly produce this
concatenation as their output.)
4. The resulting 64 octet sequence is the JWS Signature value.
+ The following "alg" (algorithm) Header Parameter values are used to
+ indicate that the JWS Signature is a digital signature value computed
+ using the corresponding algorithm:
+
+ +++
+  alg Parameter Value  Digital Signature Algorithm 
+ +++
+  ES256  ECDSA using P256 and SHA256 
+  ES384  ECDSA using P384 and SHA384 
+  ES512  ECDSA using P521 and SHA512 
+ +++
+
The ECDSA P256 SHA256 digital signature for a JWS is validated as
follows:
1. The JWS Signature value MUST be a 64 octet sequence. If it is
not a 64 octet sequence, the validation has failed.
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
endian octet order).
3. Submit the JWS Signing Input R, S and the public key (x, y) to
the ECDSA P256 SHA256 validator.
 Signing with the ECDSA P384 SHA384 and ECDSA P521 SHA512
 algorithms is performed identically to the procedure for ECDSA P256
 SHA256  just using the corresponding hash algorithms with
 correspondingly larger result values. For ECDSA P384 SHA384, R and
 S will be 384 bits each, resulting in a 96 octet sequence. For ECDSA
 P521 SHA512, R and S will be 521 bits each, resulting in a 132
 octet sequence.
+ Signing and validation with the ECDSA P384 SHA384 and ECDSA P521
+ SHA512 algorithms is performed identically to the procedure for
+ ECDSA P256 SHA256  just using the corresponding hash algorithms
+ with correspondingly larger result values. For ECDSA P384 SHA384,
+ R and S will be 384 bits each, resulting in a 96 octet sequence. For
+ ECDSA P521 SHA512, R and S will be 521 bits each, resulting in a
+ 132 octet sequence.
Examples using these algorithms are shown in Appendices A.3 and A.4
of [JWS].
3.5. Digital Signature with RSASSAPSS
This section defines the use of the RSASSAPSS 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 RSASSAPSS hash function and the MGF1 hash function.
 Use of SHA256, SHA384, and SHA512 as these hash functions is
 defined. The size of the salt value is the same size as the hash
 function output. All other algorithm parameters use the defaults
 specified in Section A.2.3 of RFC 3447. The "alg" (algorithm) header
 parameter values "PS256", "PS384", and "PS512" are used in the JWS
 Header to indicate that the JWS Signature contains a base64url
 encoded RSASSAPSS digital signature using the respective hash
 function in both roles.
+ MGF1 mask generation function and SHA2 hash functions, always using
+ the same hash function for both the RSASSAPSS hash function and the
+ MGF1 hash function. The size of the salt value is the same size as
+ the hash function output. All other algorithm parameters use the
+ defaults specified in Section A.2.3 of RFC 3447.
A key of size 2048 bits or larger MUST be used with this algorithm.
The RSASSAPSS SHA256 digital signature is generated as follows:
Generate a digital signature of the JWS Signing Input using RSASSA
PSSSIGN, the SHA256 hash function, and the MGF1 mask generation
function with SHA256 with the desired private key. This is the JWS
signature value.
+ The following "alg" (algorithm) Header Parameter values are used to
+ indicate that the JWS Signature is a digital signature value computed
+ using the corresponding algorithm:
+
+ +++
+  alg Parameter Value  Digital Signature Algorithm 
+ +++
+  PS256  RSASSAPSS using SHA256 and MGF1 with 
+   SHA256 
+  PS384  RSASSAPSS using SHA384 and MGF1 with 
+   SHA384 
+  PS512  RSASSAPSS using SHA512 and MGF1 with 
+   SHA512 
+ +++
+
The RSASSAPSS SHA256 digital signature for a JWS is validated as
follows: Submit the JWS Signing Input, the JWS Signature, and the
public key corresponding to the private key used by the signer to the
RSASSAPSSVERIFY algorithm using SHA256 as the hash function and
using MGF1 as the mask generation function with SHA256.
 Signing with the RSASSAPSS SHA384 and RSASSAPSS SHA512 algorithms
 is performed identically to the procedure for RSASSAPSS SHA256 
 just using the alternative hash algorithm in both roles.
+ Signing and validation with the RSASSAPSS SHA384 and RSASSAPSS
+ SHA512 algorithms is performed identically to the procedure for
+ RSASSAPSS SHA256  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.
Such a JWS is called a "Plaintext JWS". A Plaintext JWS MUST use the
"alg" value "none", and is formatted identically to other JWSs, but
MUST use the empty octet sequence as its JWS Signature value.
Receivers MUST verify that the JWS Signature value is the empty octet
sequence. See Section 8.5 for security considerations associated
with using this algorithm.
@@ 548,47 +583,60 @@
the specification.
See Appendix A.2 for a table crossreferencing the JWE "alg"
(algorithm) values defined in this specification with the equivalent
identifiers used by other standards and software packages.
4.2. Key Encryption with RSAESPKCS1V1_5
This section defines the specifics of encrypting a JWE CEK with
RSAESPKCS1V1_5 [RFC3447]. The "alg" Header Parameter value
 "RSA1_5" is used in this case.
+ "RSA1_5" is used for 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].
4.3. Key Encryption with RSAES OAEP
This section defines the specifics of encrypting a JWE CEK with RSAES
using Optimal Asymmetric Encryption Padding (OAEP) [RFC3447], with
the default parameters specified by RFC 3447 in Section A.2.1.
(Those default parameters are using a hash function of SHA1 and a
mask generation function of MGF1 with SHA1.) The "alg" Header
 Parameter value "RSAOAEP" is used in this case.
+ Parameter value "RSAOAEP" is used for 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].
4.4. Key Wrapping with AES Key Wrap
This section defines the specifics of encrypting a JWE CEK with the
Advanced Encryption Standard (AES) Key Wrap Algorithm [RFC3394] using
 the default initial value specified in Section 2.2.3.1 using a 128,
 192, or 256 bit key. The "alg" Header Parameter values "A128KW",
 "A192KW", or "A256KW" are respectively used in this case.
+ the default initial value specified in Section 2.2.3.1.
+
+ The following "alg" (algorithm) Header Parameter values are used to
+ indicate that the JWE Encrypted Key is the result of encrypting the
+ CEK using the corresponding algorithm and key size:
+ +++
+  alg Parameter  Key Management Algorithm 
+  Value  
+ +++
+  A128KW  AES Key Wrap with default initial value using 
+   128 bit key 
+  A192KW  AES Key Wrap with default initial value using 
+   192 bit key 
+  A256KW  AES Key Wrap with default initial value using 
+   256 bit key 
+ +++
An example using this algorithm is shown in Appendix A.3 of [JWE].
4.5. Direct Encryption with a Shared Symmetric Key
This section defines the specifics of directly performing symmetric
key encryption without performing a key wrapping step. In this case,
the shared symmetric key is used directly as the Content Encryption
Key (CEK) value for the "enc" algorithm. An empty octet sequence is
used as the JWE Encrypted Key value. The "alg" Header Parameter
value "dir" is used in this case.
@@ 605,34 +653,50 @@
the Concat KDF, as defined in Section 5.8.1 of [NIST.80056A]. The
key agreement result can be used in one of two ways:
1. directly as the Content Encryption Key (CEK) for the "enc"
algorithm, in the Direct Key Agreement mode, or
2. as a symmetric key used to wrap the CEK with the "A128KW",
"A192KW", or "A256KW" algorithms, in the Key Agreement with Key
Wrapping mode.
 The "alg" Header Parameter value "ECDHES" is used in the Direct Key
 Agreement mode. In this mode, the output of the Concat KDF MUST be a
 key of the same length as that used by the "enc" algorithm; in this
+ A new ephemeral public key value MUST be generated for each key
+ agreement operation.
+
+ In Direct Key Agreement mode, the output of the Concat KDF MUST 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
 value.
+ value. The "alg" Header Parameter value "ECDHES" is used in the
+ Direct Key Agreement mode.
 The "alg" Header Parameter values "ECDHES+A128KW", "ECDHES+A192KW",
 or "ECDHES+A256KW" are used in the Key Agreement with Key Wrapping
 mode. In this mode, the output of 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.
+ In Key Agreement with Key Wrapping mode, the output of the Concat KDF
+ MUST be a key of the length needed for the specified key wrapping
+ algorithm. In this case, the JWE Encrypted Key is the CEK wrapped
+ with the agreed upon key.
 A new ephemeral public key value MUST be generated for each key
 agreement operation.
+ The following "alg" (algorithm) Header Parameter values are used to
+ indicate that the JWE Encrypted Key is the result of encrypting the
+ CEK using the result of the key agreement algorithm as the key
+ encryption key for the corresponding key wrapping algorithm:
+
+ +++
+  alg Parameter  Key Management Algorithm 
+  Value  
+ +++
+  ECDHES+A128KW  ECDHES using Concat KDF and CEK wrapped with 
+   "A128KW" 
+  ECDHES+A192KW  ECDHES using Concat KDF and CEK wrapped with 
+   "A192KW" 
+  ECDHES+A256KW  ECDHES using Concat KDF and CEK wrapped with 
+   "A256KW" 
+ +++
4.6.1. Header Parameters Used for ECDH Key Agreement
The following Header Parameter names are used for key agreement as
defined below.
4.6.1.1. "epk" (Ephemeral Public Key) Header Parameter
The "epk" (ephemeral public key) value created by the originator for
the use in key agreement algorithms. This key is represented as a
@@ 723,40 +787,50 @@
EphemeralStatic mode in [RFC2631]) and the "apv" field should not be
present.
See Appendix C for an example key agreement computation using this
method.
4.7. Key Encryption with AES GCM
This section defines the specifics of encrypting a JWE Content
Encryption Key (CEK) with Advanced Encryption Standard (AES) in
 Galois/Counter Mode (GCM) [AES] [NIST.80038D] using a 128, 192, or
 256 bit key. The "alg" Header Parameter values "A128GCMKW",
 "A192GCMKW", or "A256GCMKW" are respectively used in this case.
+ Galois/Counter Mode (GCM) [AES] [NIST.80038D].
Use of an Initialization Vector of size 96 bits is REQUIRED with this
algorithm. The Initialization Vector is represented in base64url
encoded form as the "iv" (initialization vector) Header Parameter
value.
The Additional Authenticated Data value used is the empty octet
string.
The requested size of the Authentication Tag output MUST be 128 bits,
regardless of the key size.
The JWE Encrypted Key value is the Ciphertext output.
The Authentication Tag output is represented in base64url encoded
form as the "tag" (authentication tag) Header Parameter value.
+ The following "alg" (algorithm) Header Parameter values are used to
+ indicate that the JWE Encrypted Key is the result of encrypting the
+ CEK using the corresponding algorithm and key size:
+
+ +++
+  alg Parameter Value  Key Management Algorithm 
+ +++
+  A128GCMKW  Key wrapping with AES GCM using 128 bit key 
+  A192GCMKW  Key wrapping with AES GCM using 192 bit key 
+  A256GCMKW  Key wrapping with AES GCM using 256 bit key 
+ +++
+
4.7.1. Header Parameters Used for AES GCM Key Encryption
The following Header Parameters are used for AES GCM key encryption.
4.7.1.1. "iv" (Initialization Vector) Header Parameter
The "iv" (initialization vector) Header Parameter value is the
base64url encoded representation of the Initialization Vector value
used for the key encryption operation. This Header Parameter MUST be
present and MUST be understood and processed by implementations when
@@ 765,40 +839,56 @@
4.7.1.2. "tag" (Authentication Tag) Header Parameter
The "tag" (authentication tag) Header Parameter value is the
base64url encoded representation of the Authentication Tag value
resulting from the key encryption operation. This Header Parameter
MUST be present and MUST be understood and processed by
implementations when these algorithms are used.
4.8. Key Encryption with PBES2
 The "PBES2HS256+A128KW", "PBES2HS384+A192KW", and
 "PBES2HS512+A256KW" composite algorithms are used to perform
 passwordbased encryption of a JWE CEK, by first deriving a key
 encryption key from a usersupplied password, then encrypting the JWE
 CEK using the derived key. These algorithms are PBES2 schemes as
 specified in Section 6.2 of [RFC2898].
+ This section defines the specifies of performing passwordbased
+ encryption of a JWE CEK, by first deriving a key encryption key from
+ a usersupplied password using PBES2 schemes as specified in Section
+ 6.2 of [RFC2898], then by encrypting the JWE CEK using the derived
+ key.
These algorithms use HMAC SHA2 algorithms as the PseudoRandom
Function (PRF) for the PBKDF2 key derivation and AES Key Wrap
[RFC3394] for the encryption scheme. The PBES2 password input is an
octet sequence; if the password to be used is represented as a text
string rather than an octet sequence, the UTF8 encoding of the text
string MUST be used as the octet sequence. The salt MUST be provided
as the "p2s" Header Parameter value, and MUST be base64url decoded to
obtain the value. The iteration count parameter MUST be provided as
the "p2c" Header Parameter value. The algorithms respectively use
HMAC SHA256, HMAC SHA384, and HMAC SHA512 as the PRF and use 128,
192, and 256 bit AES Key Wrap keys. Their derivedkey lengths
respectively are 16, 24, and 32 octets.
+ The following "alg" (algorithm) Header Parameter values are used to
+ indicate that the JWE Encrypted Key is the result of encrypting the
+ CEK using the result of the corresponding passwordbased encryption
+ algorithm as the key encryption key for the corresponding key
+ wrapping algorithm:
+
+ +++
+  alg Parameter Value  Key Management Algorithm 
+ +++
+  PBES2HS256+A128KW  PBES2 with HMAC SHA256 and "A128KW" 
+   wrapping 
+  PBES2HS384+A192KW  PBES2 with HMAC SHA384 and "A192KW" 
+   wrapping 
+  PBES2HS512+A256KW  PBES2 with HMAC SHA512 and "A256KW" 
+   wrapping 
+ +++
+
See Appendix C of JSON Web Key (JWK) [JWK] for an example key
encryption computation using "PBES2HS256+A128KW".
4.8.1. Header Parameters Used for PBES2 Key Encryption
The following Header Parameters are used for Key Encryption with
PBES2.
4.8.1.1. "p2s" (PBES2 salt) Parameter
@@ 821,23 +911,23 @@
implementations when these algorithms are used.
The iteration count adds computational expense, ideally compounded by
the possible range of keys introduced by the salt. A minimum
iteration count of 1000 is RECOMMENDED.
5. Cryptographic Algorithms for Content Encryption
JWE uses cryptographic algorithms to encrypt the Plaintext.
5.1. "enc" (Encryption Method) Header Parameter Values for JWE
+5.1. "enc" (Encryption Algorithm) 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 algorithm) Header
Parameter values that are defined by this specification for use with
JWE. These algorithms are used to encrypt the Plaintext, which
produces the Ciphertext.
+++++
 enc  Content Encryption  Additional  Implementatio 
 Parameter  Algorithm  Header  nRequirements 
 Value   Parameters  
+++++
 A128CBCHS2  AES_128_CBC_HMAC_SHA_2  (none)  Required 
@@ 862,21 +952,21 @@
 A256GCM  AES GCM using 256 bit  (none)  Recommended 
  key   
+++++
The Additional Header Parameters column indicates what additional
Header Parameters are used by the algorithm, beyond "enc", which all
use. All also use a JWE Initialization Vector value and produce JWE
Ciphertext and JWE Authentication Tag values.
See Appendix A.3 for a table crossreferencing the JWE "enc"
 (encryption method) values defined in this specification with the
+ (encryption algorithm) values defined in this specification with the
equivalent identifiers used by other standards and software packages.
5.2. AES_CBC_HMAC_SHA2 Algorithms
This section defines a family of authenticated encryption algorithms
built using a composition of Advanced Encryption Standard (AES) in
Cipher Block Chaining (CBC) mode with PKCS #5 padding [AES]
[NIST.80038A] operations and HMAC [RFC2104] [SHS] operations. This
algorithm family is called AES_CBC_HMAC_SHA2. It also defines three
instances of this family, the first using 128 bit CBC keys and HMAC
@@ 1016,95 +1107,118 @@
5.2.3. AES_128_CBC_HMAC_SHA_256
This algorithm is a concrete instantiation of the generic
AES_CBC_HMAC_SHA2 algorithm above. It uses the HMAC message
authentication code [RFC2104] with the SHA256 hash function [SHS] to
provide message authentication, with the HMAC output truncated to 128
bits, corresponding to the HMACSHA256128 algorithm defined in
[RFC4868]. For encryption, it uses AES in the Cipher Block Chaining
(CBC) mode of operation as defined in Section 6.2 of [NIST.80038A],
 with PKCS #5 padding.
+ with PKCS #5 padding and a 128 bit initialization vector (IV) value.
+
+ The AES_CBC_HMAC_SHA2 parameters specific to AES_128_CBC_HMAC_SHA_256
+ are:
The input key K is 32 octets long.
 The AES CBC IV is 16 octets long. ENC_KEY_LEN is 16 octets.
+ ENC_KEY_LEN is 16 octets.
 The SHA256 hash algorithm is used in HMAC. MAC_KEY_LEN is 16
 octets. The HMACSHA256 output is truncated to T_LEN=16 octets, by
+ MAC_KEY_LEN is 16 octets.
+
+ The SHA256 hash algorithm is used for the HMAC.
+
+ The HMACSHA256 output is truncated to T_LEN=16 octets, by
stripping off the final 16 octets.
5.2.4. AES_192_CBC_HMAC_SHA_384
AES_192_CBC_HMAC_SHA_384 is based on AES_128_CBC_HMAC_SHA_256, but
with the following differences:
 A 192 bit AES CBC key is used instead of 128.

 SHA384 is used in HMAC instead of SHA256.
+ The input key K is 48 octets long instead of 32.
ENC_KEY_LEN is 24 octets instead of 16.
MAC_KEY_LEN is 24 octets instead of 16.
 The length of the input key K is 48 octets instead of 32.
+ SHA384 is used for the HMAC instead of SHA256.
The HMAC SHA384 value is truncated to T_LEN=24 octets instead of
16.
5.2.5. AES_256_CBC_HMAC_SHA_512
AES_256_CBC_HMAC_SHA_512 is based on AES_128_CBC_HMAC_SHA_256, but
with the following differences:
 A 256 bit AES CBC key is used instead of 128.

 SHA512 is used in HMAC instead of SHA256.
+ The input key K is 64 octets long instead of 32.
ENC_KEY_LEN is 32 octets instead of 16.
MAC_KEY_LEN is 32 octets instead of 16.
 The length of the input key K is 64 octets instead of 32.
+ SHA512 is used for the HMAC instead of SHA256.
The HMAC SHA512 value is truncated to T_LEN=32 octets instead of
16.
5.2.6. Plaintext Encryption with AES_CBC_HMAC_SHA2
+5.2.6. Content Encryption with AES_CBC_HMAC_SHA2
 The algorithm value "A128CBCHS256" is used as the "alg" value when
 using AES_128_CBC_HMAC_SHA_256 with JWE. The algorithm value
 "A192CBCHS384" is used as the "alg" value when using
 AES_192_CBC_HMAC_SHA_384 with JWE. The algorithm value
 "A256CBCHS512" is used as the "alg" value when using
 AES_256_CBC_HMAC_SHA_512 with JWE.
+ The following "enc" (encryption algorithm) Header Parameter values
+ are used to indicate that the JWE Ciphertext and JWE Authentication
+ Tag values have been computed using the corresponding algorithm:
5.3. Plaintext Encryption with AES GCM
+ +++
+  enc Parameter  Content Encryption Algorithm 
+  Value  
+ +++
+  A128CBCHS256  AES_128_CBC_HMAC_SHA_256 authenticated encryption 
+   algorithm, as defined in Section 5.2.3 
+  A192CBCHS384  AES_192_CBC_HMAC_SHA_384 authenticated encryption 
+   algorithm, as defined in Section 5.2.4 
+  A256CBCHS512  AES_256_CBC_HMAC_SHA_512 authenticated encryption 
+   algorithm, as defined in Section 5.2.5 
+ +++
+
+5.3. Content Encryption with AES GCM
This section defines the specifics of encrypting the JWE Plaintext
with Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM)
 [AES] [NIST.80038D] using a 128, 192, or 256 bit key. The "enc"
 Header Parameter values "A128GCM", "A192GCM", or "A256GCM" are
 respectively used in this case.
+ [AES] [NIST.80038D]. The "enc" Header Parameter values "A128GCM",
+ "A192GCM", or "A256GCM" are respectively used in this case.
The CEK is used as the encryption key.
Use of an initialization vector of size 96 bits is REQUIRED with this
algorithm.
The requested size of the Authentication Tag output MUST be 128 bits,
regardless of the key size.
The JWE Authentication Tag is set to be the Authentication Tag value
produced by the encryption. During decryption, the received JWE
Authentication Tag is used as the Authentication Tag value.
+ The following "enc" (encryption algorithm) Header Parameter values
+ are used to indicate that the JWE Ciphertext and JWE Authentication
+ Tag values have been computed using the corresponding algorithm and
+ key size:
+
+ +++
+  enc Parameter Value  Content Encryption Algorithm 
+ +++
+  A128GCM  AES GCM using 128 bit key 
+  A192GCM  AES GCM using 192 bit key 
+  A256GCM  AES GCM using 256 bit key 
+ +++
+
An example using this algorithm is shown in Appendix A.1 of [JWE].
6. Cryptographic Algorithms for Keys
A JSON Web Key (JWK) [JWK] is a JSON data structure that represents a
cryptographic key. These keys can be either asymmetric or symmetric.
They can hold both public and private information about the key.
This section defines the parameters for keys using the algorithms
specified by this document.
@@ 1382,21 +1497,21 @@
this specification, in order to enable broadlyinformed review of
registration decisions. In cases where a registration decision could
be perceived as creating a conflict of interest for a particular
Expert, that Expert should defer to the judgment of the other
Expert(s).
7.1. JSON Web Signature and Encryption Algorithms Registry
This specification establishes the IANA JSON Web Signature and
Encryption Algorithms registry for values of the JWS and JWE "alg"
 (algorithm) and "enc" (encryption method) Header Parameters. The
+ (algorithm) and "enc" (encryption algorithm) Header Parameters. The
registry records the algorithm name, the algorithm usage locations,
implementation requirements, and a reference to the specification
that defines it. The same algorithm name can be registered multiple
times, provided that the sets of usage locations are disjoint.
It is suggested that when algorithms can use keys of different
lengths, that the length of the key be included in the algorithm
name. This allows readers of the JSON text to easily make security
consideration decisions.
@@ 1422,298 +1536,297 @@
Algorithm Usage Location(s):
The algorithm usage location. This must be one or more of the
values "alg" or "enc" if the algorithm is to be used with JWS or
JWE. The value "JWK" is used if the algorithm identifier will be
used as a JWK "alg" member value, but will not be used with JWS or
JWE; this could be the case, for instance, for nonauthenticated
encryption algorithms. Other values may be used with the approval
of a Designated Expert.
 Implementation Requirements:
 The algorithm implementation requirements, which must be one the
 words Required, Recommended, Optional, Deprecated, or Prohibited.
 Optionally, the word can be followed by a "+" or "". The use of
 "+" indicates that the requirement strength is likely to be
 increased in a future version of the specification. The use of
 "" indicates that the requirement strength is likely to be
 decreased in a future version of the specification. Any
+ JOSE Implementation Requirements:
+ The algorithm implementation requirements for JWS and JWE, which
+ must be one the words Required, Recommended, Optional, Deprecated,
+ or Prohibited. Optionally, the word can be followed by a "+" or
+ "". The use of "+" indicates that the requirement strength is
+ likely to be increased in a future version of the specification.
+ The use of "" indicates that the requirement strength is likely
+ to be decreased in a future version of the specification. Any
identifiers registered for nonauthenticated encryption algorithms
or other algorithms that are otherwise unsuitable for direct use
as JWS or JWE algorithms must be registered as "Prohibited".
Change Controller:
For Standards Track RFCs, state "IESG". For others, give the name
of the responsible party. Other details (e.g., postal address,
email address, home page URI) may also be included.
Specification Document(s):
Reference to the document(s) that specify the parameter,
preferably including URI(s) that can be used to retrieve copies of
the document(s). An indication of the relevant sections may also
be included but is not required.
7.1.2. Initial Registry Contents
o Algorithm Name: "HS256"
o Algorithm Description: HMAC using SHA256
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Required
+ o JOSE Implementation Requirements: Required
o Change Controller: IESG
o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "HS384"
o Algorithm Description: HMAC using SHA384
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "HS512"
o Algorithm Description: HMAC using SHA512
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "RS256"
o Algorithm Description: RSASSAPKCSv1_5 using SHA256
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Recommended
+ o JOSE Implementation Requirements: Recommended
o Change Controller: IESG
o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "RS384"
o Algorithm Description: RSASSAPKCSv1_5 using SHA384
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "RS512"
o Algorithm Description: RSASSAPKCSv1_5 using SHA512
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "ES256"
o Algorithm Description: ECDSA using P256 and SHA256
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Recommended+
+ o JOSE Implementation Requirements: Recommended+
o Change Controller: IESG
o Specification Document(s): Section 3.1 of [[ this document ]]

o Algorithm Name: "ES384"
o Algorithm Description: ECDSA using P384 and SHA384
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "ES512"
o Algorithm Description: ECDSA using P521 and SHA512
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "PS256"
o Algorithm Description: RSASSAPSS using SHA256 and MGF1 with SHA
256
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "PS384"
o Algorithm Description: RSASSAPSS using SHA384 and MGF1 with SHA
384
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 3.1 of [[ this document ]]
+
o Algorithm Name: "PS512"
o Algorithm Description: RSASSAPSS using SHA512 and MGF1 with SHA
512
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "none"
o Algorithm Description: No digital signature or MAC performed
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "RSA1_5"
o Algorithm Description: RSAESPKCS1V1_5
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Required
+ o JOSE Implementation Requirements: Required
o Change Controller: IESG
o Specification Document(s): Section 4.1 of [[ this document ]]
o Algorithm Name: "RSAOAEP"
o Algorithm Description: RSAES using OAEP with default parameters
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 4.1 of [[ this document ]]
o Algorithm Name: "A128KW"
o Algorithm Description: AES Key Wrap using 128 bit key
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Recommended
+ o JOSE Implementation Requirements: Recommended
o Change Controller: IESG
o Specification Document(s): Section 4.1 of [[ this document ]]
o Algorithm Name: "A192KW"
o Algorithm Description: AES Key Wrap using 192 bit key
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 4.1 of [[ this document ]]
o Algorithm Name: "A256KW"
o Algorithm Description: AES Key Wrap using 256 bit key
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Recommended
+ o JOSE Implementation Requirements: Recommended
o Change Controller: IESG
o Specification Document(s): Section 4.1 of [[ this document ]]
o Algorithm Name: "dir"
o Algorithm Description: Direct use of a shared symmetric key
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Recommended
+ o JOSE Implementation Requirements: Recommended
o Change Controller: IESG
o Specification Document(s): Section 4.1 of [[ this document ]]
o Algorithm Name: "ECDHES"
o Algorithm Description: ECDHES using Concat KDF
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Recommended+
+ o JOSE Implementation Requirements: Recommended+
o Change Controller: IESG
o Specification Document(s): Section 4.1 of [[ this document ]]
o Algorithm Name: "ECDHES+A128KW"
o Algorithm Description: ECDHES using Concat KDF and "A128KW"
wrapping
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Recommended
+ o JOSE Implementation Requirements: Recommended
o Change Controller: IESG
o Specification Document(s): Section 4.1 of [[ this document ]]
o Algorithm Name: "ECDHES+A192KW"
o Algorithm Description: ECDHES using Concat KDF and "A192KW"
wrapping
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 4.1 of [[ this document ]]
o Algorithm Name: "ECDHES+A256KW"
o Algorithm Description: ECDHES using Concat KDF and "A256KW"
wrapping
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Recommended
+ o JOSE Implementation Requirements: Recommended
o Change Controller: IESG
o Specification Document(s): Section 4.1 of [[ this document ]]
o Algorithm Name: "A128GCMKW"
o Algorithm Description: Key wrapping with AES GCM using 128 bit key
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 4.7 of [[ this document ]]
o Algorithm Name: "A192GCMKW"
o Algorithm Description: Key wrapping with AES GCM using 192 bit key
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 4.7 of [[ this document ]]
o Algorithm Name: "A256GCMKW"
o Algorithm Description: Key wrapping with AES GCM using 256 bit key
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 4.7 of [[ this document ]]

o Algorithm Name: "PBES2HS256+A128KW"
o Algorithm Description: PBES2 with HMAC SHA256 and "A128KW"
wrapping
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 4.8 of [[ this document ]]
o Algorithm Name: "PBES2HS384+A192KW"
o Algorithm Description: PBES2 with HMAC SHA384 and "A192KW"
wrapping
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 4.8 of [[ this document ]]
o Algorithm Name: "PBES2HS512+A256KW"
o Algorithm Description: PBES2 with HMAC SHA512 and "A256KW"
wrapping
o Algorithm Usage Location(s): "alg"
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 4.8 of [[ this document ]]
o Algorithm Name: "A128CBCHS256"
o Algorithm Description: AES_128_CBC_HMAC_SHA_256 authenticated
encryption algorithm
o Algorithm Usage Location(s): "enc"
 o Implementation Requirements: Required
+ o JOSE Implementation Requirements: Required
o Change Controller: IESG
o Specification Document(s): Section 5.1 of [[ this document ]]
o Algorithm Name: "A192CBCHS384"
o Algorithm Description: AES_192_CBC_HMAC_SHA_384 authenticated
encryption algorithm
o Algorithm Usage Location(s): "enc"
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 5.1 of [[ this document ]]
o Algorithm Name: "A256CBCHS512"
o Algorithm Description: AES_256_CBC_HMAC_SHA_512 authenticated
encryption algorithm
o Algorithm Usage Location(s): "enc"
 o Implementation Requirements: Required
+ o JOSE Implementation Requirements: Required
o Change Controller: IESG
o Specification Document(s): Section 5.1 of [[ this document ]]
o Algorithm Name: "A128GCM"
o Algorithm Description: AES GCM using 128 bit key
o Algorithm Usage Location(s): "enc"
 o Implementation Requirements: Recommended
+ o JOSE Implementation Requirements: Recommended
o Change Controller: IESG
o Specification Document(s): Section 5.1 of [[ this document ]]
o Algorithm Name: "A192GCM"
o Algorithm Description: AES GCM using 192 bit key
o Algorithm Usage Location(s): "enc"
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 5.1 of [[ this document ]]
o Algorithm Name: "A256GCM"
o Algorithm Description: AES GCM using 256 bit key
o Algorithm Usage Location(s): "enc"
 o Implementation Requirements: Recommended
+ o JOSE Implementation Requirements: Recommended
o Change Controller: IESG
o Specification Document(s): Section 5.1 of [[ this document ]]
7.2. JWE Header Parameter Names Registration
This specification registers the Header Parameter names defined in
Section 4.6.1, Section 4.7.1, and Section 4.8.1 in the IANA JSON Web
Signature and Encryption Header Parameters registry defined in [JWS].
7.2.1. Registry Contents
@@ 1829,54 +1942,54 @@
particular case.
Key Type Description:
Brief description of the Key Type (e.g., "Example description").
Change Controller:
For Standards Track RFCs, state "IESG". For others, give the name
of the responsible party. Other details (e.g., postal address,
email address, home page URI) may also be included.
 Implementation Requirements:
 The key type implementation requirements, which must be one the
 words Required, Recommended, Optional, or Deprecated. Optionally,
 the word can be followed by a "+" or "". The use of "+"
 indicates that the requirement strength is likely to be increased
 in a future version of the specification. The use of ""
 indicates that the requirement strength is likely to be decreased
 in a future version of the specification.
+ JOSE Implementation Requirements:
+ The key type implementation requirements for JWS and JWE, which
+ must be one the words Required, Recommended, Optional, Deprecated,
+ or Prohibited. Optionally, the word can be followed by a "+" or
+ "". The use of "+" indicates that the requirement strength is
+ likely to be increased in a future version of the specification.
+ The use of "" indicates that the requirement strength is likely
+ to be decreased in a future version of the specification.
Specification Document(s):
Reference to the document(s) that specify the parameter,
preferably including URI(s) that can be used to retrieve copies of
the document(s). An indication of the relevant sections may also
be included but is not required.
7.4.2. Initial Registry Contents
This specification registers the values defined in Section 6.1.
o "kty" Parameter Value: "EC"
o Key Type Description: Elliptic Curve
 o Implementation Requirements: Recommended+
+ o JOSE Implementation Requirements: Recommended+
o Change Controller: IESG
o Specification Document(s): Section 6.2 of [[ this document ]]
o "kty" Parameter Value: "RSA"
o Key Type Description: RSA
 o Implementation Requirements: Required
+ o JOSE Implementation Requirements: Required
o Change Controller: IESG
o Specification Document(s): Section 6.3 of [[ this document ]]
o "kty" Parameter Value: "oct"
o Key Type Description: Octet sequence
 o Implementation Requirements: Required
+ o JOSE Implementation Requirements: Required
o Change Controller: IESG
o Specification Document(s): Section 6.4 of [[ this document ]]
7.5. JSON Web Key Parameters Registration
This specification registers the parameter names defined in Sections
6.2, 6.3, and 6.4 in the IANA JSON Web Key Parameters registry
defined in [JWK].
7.5.1. Registry Contents
@@ 2001,56 +2115,57 @@
it is RECOMMENDED that the name be short  not to exceed 8
characters without a compelling reason to do so. This name is
casesensitive. Names may not match other registered names in a
caseinsensitive manner unless the Designated Expert(s) state that
there is a compelling reason to allow an exception in this
particular case.
Curve Description:
Brief description of the curve (e.g., "Example description").
 Implementation Requirements:
 The curve implementation requirements, which must be one the words
 Required, Recommended, Optional, or Deprecated. Optionally, the
 word can be followed by a "+" or "". The use of "+" indicates
 that the requirement strength is likely to be increased in a
 future version of the specification. The use of "" indicates
 that the requirement strength is likely to be decreased in a
 future version of the specification.
+ JOSE Implementation Requirements:
+ The curve implementation requirements for JWS and JWE, which must
+ be one the words Required, Recommended, Optional, Deprecated, or
+ Prohibited. Optionally, the word can be followed by a "+" or "".
+ The use of "+" indicates that the requirement strength is likely
+ to be increased in a future version of the specification. The use
+ of "" indicates that the requirement strength is likely to be
+ decreased in a future version of the specification.
Change Controller:
For Standards Track RFCs, state "IESG". For others, give the name
of the responsible party. Other details (e.g., postal address,
email address, home page URI) may also be included.
Specification Document(s):
Reference to the document(s) that specify the parameter,
preferably including URI(s) that can be used to retrieve copies of
the document(s). An indication of the relevant sections may also
be included but is not required.
7.6.2. Initial Registry Contents
o Curve Name: "P256"
o Curve Description: P256 curve
 o Implementation Requirements: Recommended+
+ o JOSE Implementation Requirements: Recommended+
o Change Controller: IESG
o Specification Document(s): Section 6.2.1.1 of [[ this document ]]
o Curve Name: "P384"
o Curve Description: P384 curve
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 6.2.1.1 of [[ this document ]]
+
o Curve Name: "P521"
o Curve Description: P521 curve
 o Implementation Requirements: Optional
+ o JOSE Implementation Requirements: Optional
o Change Controller: IESG
o Specification Document(s): Section 6.2.1.1 of [[ this document ]]
8. Security Considerations
All of the security issues faced by any cryptographic application
must be faced by a JWS/JWE/JWK agent. Among these issues are
protecting the user's private and symmetric keys, preventing various
attacks, and helping the user avoid mistakes such as inadvertently
encrypting a message for the wrong recipient. The entire list of
@@ 2149,21 +2264,21 @@
the security properties that each of them provides. These need to be
taken into consideration when designing protocols and selecting the
algorithms to be used in protocols.
Both signatures and MACs provide for integrity checking  verifying
that the message has not been modified since the integrity value was
computed. However, MACs provide for origination identification only
under specific circumstances. It can normally be assumed that a
private key used for a signature is only in the hands of a single
entity (although perhaps a distributed entity, in the case of
 replicated servers), however a MAC key needs to be in the hands of
+ replicated servers); however, a MAC key needs to be in the hands of
all the entities that use it for integrity computation and checking.
This means that origination can only be determined if a MAC key is
known only to two entities and the receiver knows that it did not
create the message. MAC validation cannot be used to prove
origination to a third party.
8.7. Denial of Service Attacks
Receiving agents that validate signatures and sending agents that
encrypt messages need to be cautious of cryptographic processing
@@ 2235,29 +2350,29 @@
[ID.melnikovprecissaslprepbis]
SaintAndre, P. and A. Melnikov, "Preparation and
Comparison of Internationalized Strings Representing
Simple User Names and Passwords",
draftmelnikovprecissaslprepbis04 (work in progress),
September 2012.
[JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web
Encryption (JWE)", draftietfjosejsonwebencryption
 (work in progress), November 2013.
+ (work in progress), December 2013.
[JWK] Jones, M., "JSON Web Key (JWK)",
draftietfjosejsonwebkey (work in progress),
 November 2013.
+ December 2013.
[JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", draftietfjosejsonwebsignature (work
 in progress), November 2013.
+ in progress), December 2013.
[NIST.80038A]
National Institute of Standards and Technology (NIST),
"Recommendation for Block Cipher Modes of Operation",
NIST PUB 80038A, December 2001.
[NIST.80038D]
National Institute of Standards and Technology (NIST),
"Recommendation for Block Cipher Modes of Operation:
Galois/Counter Mode (GCM) and GMAC", NIST PUB 80038D,
@@ 2358,22 +2473,22 @@
[RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup
Language) XMLSignature Syntax and Processing", RFC 3275,
March 2002.
[RFC3447] Jonsson, J. and B. Kaliski, "PublicKey Cryptography
Standards (PKCS) #1: RSA Cryptography Specifications
Version 2.1", RFC 3447, February 2003.
[W3C.CRxmldsigcore220120124]
 Eastlake, D., Reagle, J., Yiu, K., Solo, D., Datta, P.,
 Hirsch, F., Cantor, S., and T. Roessler, "XML Signature
+ Cantor, S., Roessler, T., Eastlake, D., Yiu, K., Reagle,
+ J., Solo, D., Datta, P., and F. Hirsch, "XML Signature
Syntax and Processing Version 2.0", World Wide Web
Consortium CR CRxmldsigcore220120124, January 2012,
.
[W3C.CRxmlenccore120120313]
Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch,
"XML Encryption Syntax and Processing Version 1.1", World
Wide Web Consortium CR CRxmlenccore120120313,
March 2012,
.
@@ 2451,21 +2566,21 @@
 KW  /04/xmlenc#kwaes128   01.3.4.1.5 
 A192  http://www.w3.org/2001   2.16.840.1.1 
 KW  /04/xmlenc#kwaes192   01.3.4.1.25 
 A256  http://www.w3.org/2001   2.16.840.1.1 
 KW  /04/xmlenc#kwaes256   01.3.4.1.45 
+++++
A.3. Content Encryption Algorithm Identifier CrossReference
This section contains a table crossreferencing the JWE "enc"
 (encryption method) values defined in this specification with the
+ (encryption algorithm) values defined in this specification with the
equivalent identifiers used by other standards and software packages.
For the composite algorithms "A128CBCHS256", "A192CBCHS384", and
"A256CBCHS512", the corresponding AES CBC algorithm identifiers are
listed.
+++++
 JWE  XML ENC  JCA  OID 
+++++
 A128CBC  http://www.w3.org/2001/  AES/CBC/PKCS  2.16.840.1.101 
@@ 2772,20 +2887,31 @@
Hannes Tschofenig, and Sean Turner.
Jim Schaad and Karen O'Donoghue chaired the JOSE working group and
Sean Turner and Stephen Farrell served as Security area directors
during the creation of this specification.
Appendix E. Document History
[[ to be removed by the RFC Editor before publication as an RFC ]]
+ 19
+
+ o Used tables to show the correspondence between algorithm
+ identifiers and algorithm descriptions and parameters in the
+ algorithm definition sections, addressing issue #183.
+
+ o Changed the "Implementation Requirements" registry field names to
+ "JOSE Implementation Requirements" to make it clear that these
+ implementation requirements apply only to JWS and JWE
+ implementations.
+
18
o Changes to address editorial and minor issues #129, #134, #135,
#158, #161, #185, #186, and #187.
o Added and used Description registry fields.
17
o Explicitly named all the logical components of a JWS and JWE and