draft-ietf-jose-json-web-algorithms-13.txt   draft-ietf-jose-json-web-algorithms-14.txt 
JOSE Working Group M. Jones JOSE Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track July 15, 2013 Intended status: Standards Track July 29, 2013
Expires: January 16, 2014 Expires: January 30, 2014
JSON Web Algorithms (JWA) JSON Web Algorithms (JWA)
draft-ietf-jose-json-web-algorithms-13 draft-ietf-jose-json-web-algorithms-14
Abstract Abstract
The JSON Web Algorithms (JWA) specification enumerates cryptographic The JSON Web Algorithms (JWA) specification enumerates cryptographic
algorithms and identifiers to be used with the JSON Web Signature algorithms and identifiers to be used with the JSON Web Signature
(JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK) (JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK)
specifications. specifications.
Status of this Memo Status of this Memo
skipping to change at page 1, line 33 skipping to change at page 1, line 33
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 16, 2014. This Internet-Draft will expire on January 30, 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 16 skipping to change at page 2, line 16
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 2.1. Terms Incorporated from the JWS Specification . . . . . . 5
2.2. Terms Incorporated from the JWE Specification . . . . . . 6 2.2. Terms Incorporated from the JWE Specification . . . . . . 6
2.3. Terms Incorporated from the JWK Specification . . . . . . 9 2.3. Terms Incorporated from the JWK Specification . . . . . . 9
2.4. Defined Terms . . . . . . . . . . . . . . . . . . . . . . 9 2.4. Defined Terms . . . . . . . . . . . . . . . . . . . . . . 9
3. Cryptographic Algorithms for JWS . . . . . . . . . . . . . . . 9 3. Cryptographic Algorithms for JWS . . . . . . . . . . . . . . . 9
3.1. "alg" (Algorithm) Header Parameter Values for JWS . . . . 9 3.1. "alg" (Algorithm) Header Parameter Values for JWS . . . . 9
3.2. MAC with HMAC SHA-256, HMAC SHA-384, or HMAC SHA-512 . . . 10 3.2. MAC with HMAC SHA-2 Functions . . . . . . . . . . . . . . 11
3.3. Digital Signature with RSASSA-PKCS1-V1_5 and SHA-256, 3.3. Digital Signature with RSASSA-PKCS1-V1_5 . . . . . . . . . 12
SHA-384, or SHA-512 . . . . . . . . . . . . . . . . . . . 11 3.4. Digital Signature with ECDSA . . . . . . . . . . . . . . . 13
3.4. Digital Signature with ECDSA P-256 SHA-256, ECDSA 3.5. Digital Signature with RSASSA-PSS . . . . . . . . . . . . 14
P-384 SHA-384, or ECDSA P-521 SHA-512 . . . . . . . . . . 12
3.5. Digital Signature with RSASSA-PSS and SHA-256 or
SHA-512 . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.6. Using the Algorithm "none" . . . . . . . . . . . . . . . . 15 3.6. Using the Algorithm "none" . . . . . . . . . . . . . . . . 15
3.7. Additional Digital Signature/MAC Algorithms and 3.7. Additional Digital Signature/MAC Algorithms and
Parameters . . . . . . . . . . . . . . . . . . . . . . . . 15 Parameters . . . . . . . . . . . . . . . . . . . . . . . . 15
4. Cryptographic Algorithms for JWE . . . . . . . . . . . . . . . 16 4. Cryptographic Algorithms for JWE . . . . . . . . . . . . . . . 16
4.1. "alg" (Algorithm) Header Parameter Values for JWE . . . . 16 4.1. "alg" (Algorithm) Header Parameter Values for JWE . . . . 16
4.2. "enc" (Encryption Method) Header Parameter Values for 4.2. "enc" (Encryption Method) Header Parameter Values for
JWE . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 JWE . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.3. Key Encryption with RSAES-PKCS1-V1_5 . . . . . . . . . . . 20 4.3. Key Encryption with RSAES-PKCS1-V1_5 . . . . . . . . . . . 22
4.4. Key Encryption with RSAES OAEP . . . . . . . . . . . . . . 21 4.4. Key Encryption with RSAES OAEP . . . . . . . . . . . . . . 22
4.5. Key Wrapping with AES Key Wrap . . . . . . . . . . . . . . 21 4.5. Key Wrapping with AES Key Wrap . . . . . . . . . . . . . . 22
4.6. Direct Encryption with a Shared Symmetric Key . . . . . . 21 4.6. Direct Encryption with a Shared Symmetric Key . . . . . . 22
4.7. Key Agreement with Elliptic Curve Diffie-Hellman 4.7. Key Agreement with Elliptic Curve Diffie-Hellman
Ephemeral Static (ECDH-ES) . . . . . . . . . . . . . . . . 21 Ephemeral Static (ECDH-ES) . . . . . . . . . . . . . . . . 22
4.7.1. Header Parameters Used for ECDH Key Agreement . . . . 22 4.7.1. Header Parameters Used for ECDH Key Agreement . . . . 23
4.7.1.1. "epk" (Ephemeral Public Key) Header Parameter . . 22 4.7.1.1. "epk" (Ephemeral Public Key) Header Parameter . . 23
4.7.1.2. "apu" (Agreement PartyUInfo) Header Parameter . . 22 4.7.1.2. "apu" (Agreement PartyUInfo) Header Parameter . . 23
4.7.1.3. "apv" (Agreement PartyVInfo) Header Parameter . . 22 4.7.1.3. "apv" (Agreement PartyVInfo) Header Parameter . . 24
4.7.2. Key Derivation for ECDH Key Agreement . . . . . . . . 22 4.7.2. Key Derivation for ECDH Key Agreement . . . . . . . . 24
4.8. Key Encryption with AES GCM . . . . . . . . . . . . . . . 24 4.8. Key Encryption with AES GCM . . . . . . . . . . . . . . . 25
4.8.1. Header Parameters Used for AES GCM Key Encryption . . 24 4.8.1. Header Parameters Used for AES GCM Key Encryption . . 26
4.8.1.1. "iv" (Initialization Vector) Header Parameter . . 24 4.8.1.1. "iv" (Initialization Vector) Header Parameter . . 26
4.8.1.2. "tag" (Authentication Tag) Header Parameter . . . 24 4.8.1.2. "tag" (Authentication Tag) Header Parameter . . . 26
4.9. Key Encryption with PBES2 . . . . . . . . . . . . . . . . 25 4.9. Key Encryption with PBES2 . . . . . . . . . . . . . . . . 26
4.9.1. PBES2-HS256+A128KW . . . . . . . . . . . . . . . . . . 25 4.9.1. Header Parameters Used for PBES2 Key Encryption . . . 26
4.9.2. PBES2-HS256+A256KW . . . . . . . . . . . . . . . . . . 25 4.9.1.1. "p2s" (PBES2 salt) Parameter . . . . . . . . . . . 26
4.10. AES_CBC_HMAC_SHA2 Algorithms . . . . . . . . . . . . . . . 25 4.9.1.2. "p2c" (PBES2 count) Parameter . . . . . . . . . . 27
4.10.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 . . . . 26 4.10. AES_CBC_HMAC_SHA2 Algorithms . . . . . . . . . . . . . . . 27
4.10.2. Generic AES_CBC_HMAC_SHA2 Algorithm . . . . . . . . . 26 4.10.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 . . . . 27
4.10.2.1. AES_CBC_HMAC_SHA2 Encryption . . . . . . . . . . . 26 4.10.2. Generic AES_CBC_HMAC_SHA2 Algorithm . . . . . . . . . 28
4.10.2.2. AES_CBC_HMAC_SHA2 Decryption . . . . . . . . . . . 28 4.10.2.1. AES_CBC_HMAC_SHA2 Encryption . . . . . . . . . . . 28
4.10.2.2. AES_CBC_HMAC_SHA2 Decryption . . . . . . . . . . . 30
4.10.3. AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . 28 4.10.3. AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . 30
4.10.4. AES_256_CBC_HMAC_SHA_512 . . . . . . . . . . . . . . . 29 4.10.4. AES_192_CBC_HMAC_SHA_384 . . . . . . . . . . . . . . . 31
4.10.5. Plaintext Encryption with AES_CBC_HMAC_SHA2 . . . . . 29 4.10.5. AES_256_CBC_HMAC_SHA_512 . . . . . . . . . . . . . . . 31
4.11. Plaintext Encryption with AES GCM . . . . . . . . . . . . 29 4.10.6. Plaintext Encryption with AES_CBC_HMAC_SHA2 . . . . . 31
4.12. Additional Encryption Algorithms and Parameters . . . . . 30 4.11. Plaintext Encryption with AES GCM . . . . . . . . . . . . 32
5. Cryptographic Algorithms for JWK . . . . . . . . . . . . . . . 30 4.12. Additional Encryption Algorithms and Parameters . . . . . 32
5.1. "kty" (Key Type) Parameter Values for JWK . . . . . . . . 30 5. Cryptographic Algorithms for JWK . . . . . . . . . . . . . . . 33
5.2. JWK Parameters for Elliptic Curve Keys . . . . . . . . . . 31 5.1. "kty" (Key Type) Parameter Values for JWK . . . . . . . . 33
5.2.1. JWK Parameters for Elliptic Curve Public Keys . . . . 31 5.2. JWK Parameters for Elliptic Curve Keys . . . . . . . . . . 33
5.2.1.1. "crv" (Curve) Parameter . . . . . . . . . . . . . 31 5.2.1. JWK Parameters for Elliptic Curve Public Keys . . . . 33
5.2.1.2. "x" (X Coordinate) Parameter . . . . . . . . . . . 32 5.2.1.1. "crv" (Curve) Parameter . . . . . . . . . . . . . 34
5.2.1.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . 32 5.2.1.2. "x" (X Coordinate) Parameter . . . . . . . . . . . 34
5.2.2. JWK Parameters for Elliptic Curve Private Keys . . . . 32 5.2.1.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . 34
5.2.2.1. "d" (ECC Private Key) Parameter . . . . . . . . . 32 5.2.2. JWK Parameters for Elliptic Curve Private Keys . . . . 34
5.3. JWK Parameters for RSA Keys . . . . . . . . . . . . . . . 32 5.2.2.1. "d" (ECC Private Key) Parameter . . . . . . . . . 34
5.3.1. JWK Parameters for RSA Public Keys . . . . . . . . . . 32 5.3. JWK Parameters for RSA Keys . . . . . . . . . . . . . . . 35
5.3.1.1. "n" (Modulus) Parameter . . . . . . . . . . . . . 33 5.3.1. JWK Parameters for RSA Public Keys . . . . . . . . . . 35
5.3.1.2. "e" (Exponent) Parameter . . . . . . . . . . . . . 33 5.3.1.1. "n" (Modulus) Parameter . . . . . . . . . . . . . 35
5.3.2. JWK Parameters for RSA Private Keys . . . . . . . . . 33 5.3.1.2. "e" (Exponent) Parameter . . . . . . . . . . . . . 35
5.3.2.1. "d" (Private Exponent) Parameter . . . . . . . . . 33 5.3.2. JWK Parameters for RSA Private Keys . . . . . . . . . 35
5.3.2.2. "p" (First Prime Factor) Parameter . . . . . . . . 33 5.3.2.1. "d" (Private Exponent) Parameter . . . . . . . . . 35
5.3.2.3. "q" (Second Prime Factor) Parameter . . . . . . . 33 5.3.2.2. "p" (First Prime Factor) Parameter . . . . . . . . 36
5.3.2.4. "dp" (First Factor CRT Exponent) Parameter . . . . 34 5.3.2.3. "q" (Second Prime Factor) Parameter . . . . . . . 36
5.3.2.5. "dq" (Second Factor CRT Exponent) Parameter . . . 34 5.3.2.4. "dp" (First Factor CRT Exponent) Parameter . . . . 36
5.3.2.6. "qi" (First CRT Coefficient) Parameter . . . . . . 34 5.3.2.5. "dq" (Second Factor CRT Exponent) Parameter . . . 36
5.3.2.7. "oth" (Other Primes Info) Parameter . . . . . . . 34 5.3.2.6. "qi" (First CRT Coefficient) Parameter . . . . . . 36
5.3.3. JWK Parameters for Symmetric Keys . . . . . . . . . . 35 5.3.2.7. "oth" (Other Primes Info) Parameter . . . . . . . 36
5.3.3.1. "k" (Key Value) Parameter . . . . . . . . . . . . 35 5.3.3. JWK Parameters for Symmetric Keys . . . . . . . . . . 37
5.3.4. JWK Parameters for PBKDF2 Keys . . . . . . . . . . . . 35 5.3.3.1. "k" (Key Value) Parameter . . . . . . . . . . . . 37
5.3.4.1. "s" (salt) Parameter . . . . . . . . . . . . . . . 35 5.4. Additional Key Types and Parameters . . . . . . . . . . . 37
5.3.4.2. "c" (count) Parameter . . . . . . . . . . . . . . 35 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38
5.3.4.3. "hint" (password hint) Parameter . . . . . . . . . 36 6.1. JSON Web Signature and Encryption Algorithms Registry . . 38
5.4. Additional Key Types and Parameters . . . . . . . . . . . 36 6.1.1. Template . . . . . . . . . . . . . . . . . . . . . . . 38
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 39
6.1. JSON Web Signature and Encryption Algorithms Registry . . 37 6.2. JSON Web Key Types Registry . . . . . . . . . . . . . . . 44
6.1.1. Template . . . . . . . . . . . . . . . . . . . . . . . 37 6.2.1. Registration Template . . . . . . . . . . . . . . . . 44
6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 38 6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 45
6.2. JSON Web Key Types Registry . . . . . . . . . . . . . . . 41 6.3. JSON Web Key Parameters Registration . . . . . . . . . . . 45
6.2.1. Registration Template . . . . . . . . . . . . . . . . 42 6.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 45
6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 42 6.4. Registration of JWE Header Parameter Names . . . . . . . . 47
6.3. JSON Web Key Parameters Registration . . . . . . . . . . . 43 6.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 47
6.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 43 7. Security Considerations . . . . . . . . . . . . . . . . . . . 48
6.4. Registration of JWE Header Parameter Names . . . . . . . . 45 7.1. Reusing Key Material when Encrypting Keys . . . . . . . . 49
6.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 45 7.2. Password Considerations . . . . . . . . . . . . . . . . . 49
7. Security Considerations . . . . . . . . . . . . . . . . . . . 45 8. Internationalization Considerations . . . . . . . . . . . . . 50
7.1. Reusing Key Material when Encrypting Keys . . . . . . . . 47 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 50
7.2. Password Considerations . . . . . . . . . . . . . . . . . 47 9.1. Normative References . . . . . . . . . . . . . . . . . . . 50
8. Internationalization Considerations . . . . . . . . . . . . . 47 9.2. Informative References . . . . . . . . . . . . . . . . . . 52
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 48
9.1. Normative References . . . . . . . . . . . . . . . . . . . 48
9.2. Informative References . . . . . . . . . . . . . . . . . . 49
Appendix A. Digital Signature/MAC Algorithm Identifier Appendix A. Digital Signature/MAC Algorithm Identifier
Cross-Reference . . . . . . . . . . . . . . . . . . . 51 Cross-Reference . . . . . . . . . . . . . . . . . . . 53
Appendix B. Encryption Algorithm Identifier Cross-Reference . . . 53
Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms . . . . . 55 Appendix B. Encryption Algorithm Identifier Cross-Reference . . . 56
C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 . . . . . . . . . 56 Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms . . . . . 59
C.2. Test Cases for AES_256_CBC_HMAC_SHA_512 . . . . . . . . . 57 C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 . . . . . . . . . 60
Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 58 C.2. Test Cases for AES_192_CBC_HMAC_SHA_384 . . . . . . . . . 61
Appendix E. Document History . . . . . . . . . . . . . . . . . . 58 C.3. Test Cases for AES_256_CBC_HMAC_SHA_512 . . . . . . . . . 62
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 64 Appendix D. Example ECDH-ES Key Agreement Computation . . . . . . 63
Appendix E. Acknowledgements . . . . . . . . . . . . . . . . . . 65
Appendix F. Document History . . . . . . . . . . . . . . . . . . 65
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 72
1. Introduction 1. Introduction
The JSON Web Algorithms (JWA) specification enumerates cryptographic The JSON Web Algorithms (JWA) specification enumerates cryptographic
algorithms and identifiers to be used with the JSON Web Signature algorithms and identifiers to be used with the JSON Web Signature
(JWS) [JWS], JSON Web Encryption (JWE) [JWE], and JSON Web Key (JWK) (JWS) [JWS], JSON Web Encryption (JWE) [JWE], and JSON Web Key (JWK)
[JWK] specifications. All these specifications utilize JavaScript [JWK] specifications. All these specifications utilize JavaScript
Object Notation (JSON) [RFC4627] based data structures. This Object Notation (JSON) [RFC4627] based data structures. This
specification also describes the semantics and operations that are specification also describes the semantics and operations that are
specific to these algorithms and key types. specific to these algorithms and key types.
skipping to change at page 10, line 28 skipping to change at page 10, line 28
| | algorithm | | | | algorithm | |
| ES256 | ECDSA using P-256 curve and SHA-256 | RECOMMENDED+ | | ES256 | ECDSA using P-256 curve and SHA-256 | RECOMMENDED+ |
| | hash algorithm | | | | hash algorithm | |
| ES384 | ECDSA using P-384 curve and SHA-384 | OPTIONAL | | ES384 | ECDSA using P-384 curve and SHA-384 | OPTIONAL |
| | hash algorithm | | | | hash algorithm | |
| ES512 | ECDSA using P-521 curve and SHA-512 | OPTIONAL | | ES512 | ECDSA using P-521 curve and SHA-512 | OPTIONAL |
| | hash algorithm | | | | hash algorithm | |
| PS256 | RSASSA-PSS using SHA-256 hash | OPTIONAL | | PS256 | RSASSA-PSS using SHA-256 hash | OPTIONAL |
| | algorithm and MGF1 mask generation | | | | algorithm and MGF1 mask generation | |
| | function with SHA-256 | | | | function with SHA-256 | |
| PS384 | RSASSA-PSS using SHA-384 hash | OPTIONAL |
| | algorithm and MGF1 mask generation | |
| | function with SHA-384 | |
| PS512 | RSASSA-PSS using SHA-512 hash | OPTIONAL | | PS512 | RSASSA-PSS using SHA-512 hash | OPTIONAL |
| | algorithm and MGF1 mask generation | | | | algorithm and MGF1 mask generation | |
| | function with SHA-512 | | | | function with SHA-512 | |
| none | No digital signature or MAC value | REQUIRED | | none | No digital signature or MAC value | REQUIRED |
| | included | | | | included | |
+-----------+--------------------------------------+----------------+ +-----------+--------------------------------------+----------------+
All the names are short because a core goal of JWS is for the All the names are short because a core goal of JWS is for the
representations to be compact. However, there is no a priori length representations to be compact. However, there is no a priori length
restriction on "alg" values. restriction on "alg" values.
The use of "+" in the Implementation Requirements indicates that the The use of "+" in the Implementation Requirements indicates that the
requirement strength is likely to be increased in a future version of requirement strength is likely to be increased in a future version of
the specification. the specification.
See Appendix A for a table cross-referencing the digital signature See Appendix A for a table cross-referencing the digital signature
and MAC "alg" (algorithm) values used in this specification with the and MAC "alg" (algorithm) values used in this specification with the
equivalent identifiers used by other standards and software packages. equivalent identifiers used by other standards and software packages.
3.2. MAC with HMAC SHA-256, HMAC SHA-384, or HMAC SHA-512 3.2. MAC with HMAC 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 the Authentication Code (MAC). This can be used to demonstrate that the
MAC matches the hashed content, in this case the JWS Signing Input, MAC matches the hashed content, in this case the JWS Signing Input,
which therefore demonstrates that whoever generated the MAC was in which therefore demonstrates that whoever generated the MAC was in
possession of the secret. The means of exchanging the shared key is possession of the secret. The means of exchanging the shared key is
outside the scope of this specification. outside the scope of this specification.
The algorithm for implementing and validating HMACs is provided in The algorithm for implementing and validating HMACs is provided in
skipping to change at page 11, line 46 skipping to change at page 12, line 5
be rejected. be rejected.
Securing content with the HMAC SHA-384 and HMAC SHA-512 algorithms is Securing content with the HMAC SHA-384 and HMAC SHA-512 algorithms is
performed identically to the procedure for HMAC SHA-256 - just using performed identically to the procedure for HMAC SHA-256 - just using
the corresponding hash algorithm with correspondingly larger minimum the corresponding hash algorithm with correspondingly larger minimum
key sizes and result values: 384 bits each for HMAC SHA-384 and 512 key sizes and result values: 384 bits each for HMAC SHA-384 and 512
bits each for HMAC SHA-512. bits each for HMAC SHA-512.
An example using this algorithm is shown in Appendix A.1 of [JWS]. An example using this algorithm is shown in Appendix A.1 of [JWS].
3.3. Digital Signature with RSASSA-PKCS1-V1_5 and SHA-256, SHA-384, or 3.3. Digital Signature with RSASSA-PKCS1-V1_5
SHA-512
This section defines the use of the RSASSA-PKCS1-V1_5 digital This section defines the use of the RSASSA-PKCS1-V1_5 digital
signature algorithm as defined in Section 8.2 of RFC 3447 [RFC3447] signature algorithm as defined in Section 8.2 of RFC 3447 [RFC3447]
(commonly known as PKCS #1), using SHA-256, SHA-384, or SHA-512 [SHS] (commonly known as PKCS #1), using SHA-256, SHA-384, or SHA-512 [SHS]
as the hash functions. The "alg" (algorithm) header parameter values as the hash functions. The "alg" (algorithm) header parameter values
"RS256", "RS384", and "RS512" are used in the JWS Header to indicate "RS256", "RS384", and "RS512" are used in the JWS Header to indicate
that the Encoded JWS Signature contains a base64url encoded RSASSA- that the Encoded JWS Signature contains a base64url encoded RSASSA-
PKCS1-V1_5 digital signature using the respective hash function. PKCS1-V1_5 digital signature using the respective hash function.
A key of size 2048 bits or larger MUST be used with these algorithms. A key of size 2048 bits or larger MUST be used with these algorithms.
skipping to change at page 12, line 44 skipping to change at page 13, line 5
3. If the validation fails, the JWS MUST be rejected. 3. If the validation fails, the JWS MUST be rejected.
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 algorithm with PKCS1-V1_5 SHA-256 - just using the corresponding hash algorithm with
correspondingly larger result values: 384 bits for RSASSA-PKCS1-V1_5 correspondingly larger result values: 384 bits for RSASSA-PKCS1-V1_5
SHA-384 and 512 bits for RSASSA-PKCS1-V1_5 SHA-512. SHA-384 and 512 bits for RSASSA-PKCS1-V1_5 SHA-512.
An example using this algorithm is shown in Appendix A.2 of [JWS]. An example using this algorithm is shown in Appendix A.2 of [JWS].
3.4. Digital Signature with ECDSA P-256 SHA-256, ECDSA P-384 SHA-384, 3.4. Digital Signature with ECDSA
or ECDSA P-521 SHA-512
The Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] provides The Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] provides
for the use of Elliptic Curve cryptography, which is able to provide for the use of Elliptic Curve cryptography, which is able to provide
equivalent security to RSA cryptography but using shorter key sizes equivalent security to RSA cryptography but using shorter key sizes
and with greater processing speed. This means that ECDSA digital and with greater processing speed. This means that ECDSA digital
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
skipping to change at page 14, line 27 skipping to change at page 14, line 34
algorithms is performed identically to the procedure for ECDSA P-256 algorithms is performed identically to the procedure for ECDSA P-256
SHA-256 - just using the corresponding hash algorithm with SHA-256 - just using the corresponding hash algorithm with
correspondingly larger result values. For ECDSA P-384 SHA-384, R and correspondingly larger result values. For ECDSA P-384 SHA-384, R and
S will be 384 bits each, resulting in a 96 octet sequence. For ECDSA S will be 384 bits each, resulting in a 96 octet sequence. For ECDSA
P-521 SHA-512, R and S will be 521 bits each, resulting in a 132 P-521 SHA-512, R and S will be 521 bits each, resulting in a 132
octet sequence. octet sequence.
Examples using these algorithms are shown in Appendices A.3 and A.4 Examples using these algorithms are shown in Appendices A.3 and A.4
of [JWS]. of [JWS].
3.5. Digital Signature with RSASSA-PSS and SHA-256 or SHA-512 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 both SHA-256 and SHA-512 as these hash functions is defined. Use of SHA-256, SHA-384, and SHA-512 as these hash functions is
All other algorithm parameters use the defaults specified in Section defined. All other algorithm parameters use the defaults specified
A.2.3 of RFC 3447. The "alg" (algorithm) header parameter values in Section A.2.3 of RFC 3447. The "alg" (algorithm) header parameter
"PS256" and "PS512" is used in the JWS Header to indicate that the values "PS256", "PS384", and "PS512" are used in the JWS Header to
Encoded JWS Signature contains a base64url encoded RSASSA-PSS digital indicate that the Encoded JWS Signature contains a base64url encoded
signature using the respective hash function in both roles. RSASSA-PSS digital signature using the respective hash function in
both roles.
A key of size 2048 bits or larger MUST be used with this algorithm. 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:
1. Generate a digital signature of the octets of the ASCII 1. Generate a digital signature of the octets of the ASCII
representation of the JWS Signing Input using RSASSA-PSS-SIGN, representation of the JWS Signing Input using RSASSA-PSS-SIGN,
the SHA-256 hash function, and the MGF1 mask generation function the SHA-256 hash function, and the MGF1 mask generation function
with SHA-256 with the desired private key. The output will be an with SHA-256 with the desired private key. The output will be an
octet sequence. octet sequence.
skipping to change at page 15, line 21 skipping to change at page 15, line 29
octet sequence. If decoding fails, the JWS MUST be rejected. octet sequence. If decoding fails, the JWS MUST be rejected.
2. Submit the octets of the ASCII representation of the JWS Signing 2. Submit the octets of the ASCII representation of the JWS Signing
Input and the public key corresponding to the private key used by Input and the public key corresponding to the private key used by
the signer to the RSASSA-PSS-VERIFY algorithm using SHA-256 as the signer to the RSASSA-PSS-VERIFY algorithm using SHA-256 as
the hash function and using MGF1 as the mask generation function the hash function and using MGF1 as the mask generation function
with SHA-256. with SHA-256.
3. If the validation fails, the JWS MUST be rejected. 3. If the validation fails, the JWS MUST be rejected.
Signing with the RSASSA-PSS SHA-512 algorithm is performed Signing with the RSASSA-PSS SHA-384 and RSASSA-PSS SHA-512 algorithms
identically to the procedure for RSASSA-PSS SHA-256 - just using the is performed identically to the procedure for RSASSA-PSS SHA-256 -
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. with the empty string for its JWS Signature value.
3.7. Additional Digital Signature/MAC Algorithms and Parameters 3.7. Additional Digital Signature/MAC Algorithms and Parameters
skipping to change at page 17, line 4 skipping to change at page 17, line 16
| | Standard (AES) | | | | | Standard (AES) | | |
| | Key Wrap | | | | | Key Wrap | | |
| | Algorithm | | | | | Algorithm | | |
| | [RFC3394] using | | | | | [RFC3394] using | | |
| | the default | | | | | the default | | |
| | initial value | | | | | initial value | | |
| | specified in | | | | | specified in | | |
| | Section 2.2.3.1 | | | | | Section 2.2.3.1 | | |
| | and using 128 | | | | | and using 128 | | |
| | bit keys | | | | | bit keys | | |
| A192KW | AES Key Wrap | (none) | OPTIONAL |
| | Algorithm using | | |
| | the default | | |
| | initial value | | |
| | specified in | | |
| | Section 2.2.3.1 | | |
| | and using 192 | | |
| | bit keys | | |
| A256KW | AES Key Wrap | (none) | RECOMMENDED | | A256KW | AES Key Wrap | (none) | RECOMMENDED |
| | Algorithm using | | | | | Algorithm using | | |
| | the default | | | | | the default | | |
| | initial value | | | | | initial value | | |
| | specified in | | | | | specified in | | |
| | Section 2.2.3.1 | | | | | Section 2.2.3.1 | | |
| | and using 256 | | | | | and using 256 | | |
| | bit keys | | | | | bit keys | | |
| dir | Direct use of a | (none) | RECOMMENDED | | dir | Direct use of a | (none) | RECOMMENDED |
| | shared | | | | | shared | | |
skipping to change at page 18, line 11 skipping to change at page 18, line 34
| | CEK), as | | | | | CEK), as | | |
| | specified in | | | | | specified in | | |
| | Section 4.7 | | | | | Section 4.7 | | |
| ECDH-ES+A128KW | Elliptic Curve | "epk", | RECOMMENDED | | ECDH-ES+A128KW | Elliptic Curve | "epk", | RECOMMENDED |
| | Diffie-Hellman | "apu", | | | | Diffie-Hellman | "apu", | |
| | Ephemeral | "apv" | | | | Ephemeral | "apv" | |
| | Static key | | | | | Static key | | |
| | agreement per | | | | | agreement per | | |
| | "ECDH-ES" and | | | | | "ECDH-ES" and | | |
| | Section 4.7, | | | | | Section 4.7, | | |
| | but where the | | | | | where the | | |
| | agreed-upon key | | | | | agreed-upon key | | |
| | is used to wrap | | | | | is used to wrap | | |
| | the Content | | | | | the Content | | |
| | Encryption Key | | | | | Encryption Key | | |
| | (CEK) with the | | | | | (CEK) with the | | |
| | "A128KW" | | | | | "A128KW" | | |
| | function | | | | | function | | |
| | (rather than | | | | | (rather than | | |
| | being used | | | | | being used | | |
| | directly as the | | | | | directly as the | | |
| | CEK) | | | | | CEK) | | |
| ECDH-ES+A192KW | Elliptic Curve | "epk", | OPTIONAL |
| | Diffie-Hellman | "apu", | |
| | Ephemeral | "apv" | |
| | Static key | | |
| | agreement, | | |
| | where the | | |
| | agreed-upon key | | |
| | is used to wrap | | |
| | the Content | | |
| | Encryption Key | | |
| | (CEK) with the | | |
| | "A192KW" | | |
| | function | | |
| | (rather than | | |
| | being used | | |
| | directly as the | | |
| | CEK) | | |
| ECDH-ES+A256KW | Elliptic Curve | "epk", | RECOMMENDED | | ECDH-ES+A256KW | Elliptic Curve | "epk", | RECOMMENDED |
| | Diffie-Hellman | "apu", | | | | Diffie-Hellman | "apu", | |
| | Ephemeral | "apv" | | | | Ephemeral | "apv" | |
| | Static key | | | | | Static key | | |
| | agreement, but | | | | | agreement, | | |
| | where the | | | | | where the | | |
| | agreed-upon key | | | | | agreed-upon key | | |
| | is used to wrap | | | | | is used to wrap | | |
| | the Content | | | | | the Content | | |
| | Encryption Key | | | | | Encryption Key | | |
| | (CEK) with the | | | | | (CEK) with the | | |
| | "A256KW" | | | | | "A256KW" | | |
| | function | | | | | function | | |
| | (rather than | | | | | (rather than | | |
| | being used | | | | | being used | | |
| | directly as the | | | | | directly as the | | |
| | CEK) | | | | | CEK) | | |
| A128GCMKW | AES in | "iv", | OPTIONAL | | A128GCMKW | AES in | "iv", | OPTIONAL |
| | Galois/Counter | "tag" | | | | Galois/Counter | "tag" | |
| | Mode (GCM) | | | | | Mode (GCM) | | |
| | [AES] | | | | | [AES] | | |
| | [NIST.800-38D] | | | | | [NIST.800-38D] | | |
| | using 128 bit | | | | | using 128 bit | | |
| | keys | | | | | keys | | |
| A192GCMKW | AES GCM using | "iv", | OPTIONAL |
| | 192 bit keys | "tag" | |
| A256GCMKW | AES GCM using | "iv", | OPTIONAL | | A256GCMKW | AES GCM using | "iv", | OPTIONAL |
| | 256 bit keys | "tag" | | | | 256 bit keys | "tag" | |
| PBES2-HS256+A128K | PBES2 [RFC2898] | (none) | OPTIONAL | | PBES2-HS256+A128K | PBES2 [RFC2898] | "p2s", | OPTIONAL |
| W | with HMAC | | | | W | with HMAC | "p2c" | |
| | SHA-256 as the | | | | | SHA-256 as the | | |
| | PRF and AES Key | | | | | PRF and AES Key | | |
| | Wrap [RFC3394] | | | | | Wrap [RFC3394] | | |
| | using 128 bit | | | | | using 128 bit | | |
| | keys for the | | | | | keys for the | | |
| | encryption | | | | | encryption | | |
| | scheme | | | | | scheme | | |
| PBES2-HS256+A256K | PBES2 with HMAC | (none) | OPTIONAL | | PBES2-HS256+A192K | PBES2 with HMAC | "p2s", | OPTIONAL |
| W | SHA-256 as the | | | | W | SHA-256 as the | "p2c" | |
| | PRF and AES Key | | |
| | Wrap using 192 | | |
| | bit keys for | | |
| | the encryption | | |
| | scheme | | |
| PBES2-HS256+A256K | PBES2 with HMAC | "p2s", | OPTIONAL |
| W | SHA-256 as the | "p2c" | |
| | PRF and AES Key | | | | | PRF and AES Key | | |
| | Wrap using 256 | | | | | Wrap using 256 | | |
| | bit keys for | | | | | bit keys for | | |
| | the encryption | | | | | the encryption | | |
| | scheme | | | | | scheme | | |
+-------------------+-----------------+------------+----------------+ +-------------------+-----------------+------------+----------------+
All the names are short because a core goal of JWE is for the All the names are short because a core goal of JWE is for the
representations to be compact. However, there is no a priori length representations to be compact. However, there is no a priori length
restriction on "alg" values. restriction on "alg" values.
skipping to change at page 20, line 18 skipping to change at page 21, line 18
| 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 | | |
| | 56 authenticated | | | | | 56 authenticated | | |
| | encryption algorithm, | | | | | encryption algorithm, | | |
| | as defined in | | | | | as defined in | | |
| | Section 4.10.3. This | | | | | Section 4.10.3. This | | |
| | algorithm uses a 256 | | | | | algorithm uses a 256 | | |
| | bit key. | | | | | bit key. | | |
| A192CBC-HS3 | The | (none) | OPTIONAL |
| 84 | AES_192_CBC_HMAC_SHA_3 | | |
| | 84 authenticated | | |
| | encryption algorithm, | | |
| | as defined in | | |
| | Section 4.10.4. This | | |
| | algorithm uses a 384 | | |
| | bit key. | | |
| A256CBC-HS5 | The | (none) | REQUIRED | | A256CBC-HS5 | The | (none) | REQUIRED |
| 12 | AES_256_CBC_HMAC_SHA_5 | | | | 12 | AES_256_CBC_HMAC_SHA_5 | | |
| | 12 authenticated | | | | | 12 authenticated | | |
| | encryption algorithm, | | | | | encryption algorithm, | | |
| | as defined in | | | | | as defined in | | |
| | Section 4.10.4. This | | | | | Section 4.10.5. This | | |
| | algorithm uses a 512 | | | | | algorithm uses a 512 | | |
| | bit key. | | | | | bit key. | | |
| A128GCM | AES in Galois/Counter | (none) | RECOMMENDED | | A128GCM | AES in Galois/Counter | (none) | RECOMMENDED |
| | Mode (GCM) [AES] | | | | | Mode (GCM) [AES] | | |
| | [NIST.800-38D] using | | | | | [NIST.800-38D] using | | |
| | 128 bit keys | | | | | 128 bit keys | | |
| A192GCM | AES GCM using 192 bit | (none) | OPTIONAL |
| | keys | | |
| A256GCM | AES GCM using 256 bit | (none) | RECOMMENDED | | A256GCM | AES GCM using 256 bit | (none) | RECOMMENDED |
| | keys | | | | | keys | | |
+-------------+------------------------+------------+---------------+ +-------------+------------------------+------------+---------------+
The Additional Header Parameters column indicates what additional The Additional Header Parameters column indicates what additional
Header Parameters are used by the algorithm, beyond "enc", which all Header Parameters are used by the algorithm, beyond "enc", which all
use. All also use a JWE Initialization Vector value and produce JWE use. All also use a JWE Initialization Vector value and produce JWE
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"
skipping to change at page 21, line 20 skipping to change at page 22, line 30
"alg" header parameter value "RSA-OAEP" is used in this case. "alg" header 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 or the default initial value specified in Section 2.2.3.1 using 128,
256 bit keys. The "alg" header parameter values "A128KW" or "A256KW" 192, or 256 bit keys. The "alg" header parameter values "A128KW",
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
skipping to change at page 21, line 46 skipping to change at page 23, line 8
(ECDH-ES) (ECDH-ES)
This section defines the specifics of key agreement with Elliptic This section defines the specifics of key agreement with Elliptic
Curve Diffie-Hellman Ephemeral Static [RFC6090], and using the Concat Curve Diffie-Hellman Ephemeral Static [RFC6090], and using the Concat
KDF, as defined in Section 5.8.1 of [NIST.800-56A]. The key KDF, as defined in Section 5.8.1 of [NIST.800-56A]. The key
agreement result can be used in one of two ways: 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 either the "A128KW" 2. as a symmetric key used to wrap the CEK with either the "A128KW",
or "A256KW" algorithms, in the Key Agreement with Key Wrapping "A192KW", or "A256KW" algorithms, in the Key Agreement with Key
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" and "ECDH-ES+A256KW" Agreement mode and the values "ECDH-ES+A128KW", "ECDH-ES+A192KW", or
are used in the Key Agreement with Key Wrapping mode. "ECDH-ES+A256KW" are used in the Key Agreement with Key Wrapping
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, either 128 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 transaction. agreement transaction.
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 reserved and are used for The following Header Parameter Names are reserved and are used for
key agreement as defined below. They MAY also be used for other key agreement as defined below. They MAY also be used for other
algorithms if so specified by those algorithm parameter definitions. algorithms if so specified by those algorithm parameter definitions.
skipping to change at page 23, line 14 skipping to change at page 24, line 29
Key derivation is performed using the Concat KDF, as defined in Key derivation is performed using the Concat KDF, as defined in
Section 5.8.1 of [NIST.800-56A], where the Digest Method is SHA-256. Section 5.8.1 of [NIST.800-56A], where the Digest Method is SHA-256.
The Concat KDF parameters are set as follows: The Concat KDF parameters are set as follows:
Z This is set to the representation of the shared secret Z as an Z This is set to the representation of the shared secret Z as an
octet sequence. octet sequence.
keydatalen This is set to the number of bits in the desired output keydatalen This is set to the number of bits in the desired output
key. For "ECDH-ES", this is length of the key used by the "enc" key. For "ECDH-ES", this is length of the key used by the "enc"
algorithm. For "ECDH-ES+A128KW", and "ECDH-ES+A256KW", this is algorithm. For "ECDH-ES+A128KW", "ECDH-ES+A192KW", and
128 and 256, respectively. "ECDH-ES+A256KW", this is 128, 192, and 256, respectively.
AlgorithmID In the Direct Key Agreement case, this is set to the AlgorithmID In the Direct Key Agreement case, this is set to the
octets of the UTF-8 representation of the "enc" header parameter octets of the UTF-8 representation of the "enc" header parameter
value. In the Key Agreement with Key Wrapping case, this is set value. In the Key Agreement with Key Wrapping case, this is set
to the octets of the UTF-8 representation of the "alg" header to the octets of the UTF-8 representation of the "alg" header
parameter value. 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
skipping to change at page 23, line 48 skipping to change at page 25, line 14
parameter is present, Data is set to the result of base64url parameter is present, Data is set to the result of base64url
decoding the "apv" value and Datalen is set to the number of decoding the "apv" value and Datalen is set to the number of
octets in Data. Otherwise, Datalen is set to 0 and Data is set to octets in Data. Otherwise, Datalen is set to 0 and Data 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.
See Appendix D for an example key agreement computation using this
method.
Note: The Diffie-Hellman Key Agreement Method [RFC2631] uses a key Note: The Diffie-Hellman Key Agreement Method [RFC2631] uses a key
derivation function similar to the Concat KDF, but with fewer derivation function similar to the Concat KDF, but with fewer
parameters. Rather than having separate PartyUInfo and PartyVInfo parameters. Rather than having separate PartyUInfo and PartyVInfo
parameters, it uses a single PartyAInfo parameter, which is a random parameters, it uses a single PartyAInfo parameter, which is a random
string provided by the sender, that contains 512 bits of information, string provided by the sender, that contains 512 bits of information,
when provided. It has no SuppPrivInfo parameter. Should it be when provided. It has no SuppPrivInfo parameter. Should it be
appropriate for the application, key agreement can be performed in a appropriate for the application, key agreement can be performed in a
manner akin to RFC 2631 by using the PartyAInfo value as the "apu" manner akin to RFC 2631 by using the PartyAInfo value as the "apu"
(Agreement PartyUInfo) header parameter value, when provided, and by (Agreement PartyUInfo) header parameter value, when provided, and by
using no "apv" (Agreement PartyVInfo) header parameter. using no "apv" (Agreement PartyVInfo) header parameter.
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 or 256 bit Galois/Counter Mode (GCM) [AES] [NIST.800-38D] using 128, 192, or 256
keys. The "alg" header parameter values "A128GCMKW" or "A256GCMKW" bit keys. The "alg" header parameter values "A128GCMKW",
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 Parameter Names are used for AES GCM key The following Header Parameters are used for AES GCM key encryption.
encryption. They MAY also be used by other algorithms if so They MAY also be used by other algorithms if so specified by those
specified by those algorithm parameter definitions. algorithm parameter definitions.
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" and "PBES2-HS256+A256KW" algorithms defined The "PBES2-HS256+A128KW", "PBES2-HS256+A192KW", and
below are used to encrypt a JWE Content Master Key using a user- "PBES2-HS256+A256KW" algorithms are used to encrypt a JWE Content
supplied password to derive the key encryption key. With these Master Key using a user-supplied password to derive the key
algorithms, the derived key is used to encrypt the JWE Content Master encryption key. With these algorithms, the derived key is used to
Key. These algorithms combine a key derivation function with an encrypt the JWE Content Master Key. These algorithms combine a key
encryption scheme to encrypt the JWE Content Master Key according to derivation function with an encryption scheme to encrypt the JWE
PBES2 from Section 6.2 of [RFC2898]. Content Master Key according to PBES2 from Section 6.2 of [RFC2898].
4.9.1. PBES2-HS256+A128KW These algorithms use HMAC SHA-256 as the Pseudo-Random Function (PRF)
and AES Key Wrap [RFC3394] for the encryption scheme. The salt (s)
and iteration count (c) parameters MUST be provided as the "p2s" and
"p2c" header parameter values. The algorithms respectively use 128,
192, and 256 bit AES Key Wrap keys. Their derived-key lengths
(dkLen) respectively are 16, 24, and 32 octets.
The "PBES2-HS256+A128KW" algorithm uses HMAC SHA-256 as the Pseudo- 4.9.1. Header Parameters Used for PBES2 Key Encryption
Random Function (PRF) and AES Key Wrap [RFC3394] using 128 bit keys
for the encryption scheme. The salt (s) and iteration count (c) MUST
be specified by the "s" and "c" parameters (respectively) in the
applicable PBKDF2 JWK object. The derived-key length (dkLen) is 16
octets.
4.9.2. PBES2-HS256+A256KW The following Header Parameters are used for Key Encryption with
PBES2.
The "PBES2-HS256+A256KW" algorithm uses HMAC SHA-256 as the Pseudo- 4.9.1.1. "p2s" (PBES2 salt) Parameter
Random Function (PRF) and AES Key Wrap using 256 bit keys for the
encryption scheme. The salt (s) and iteration count (c) MUST be The "p2s" (PBES2 salt) header parameter contains the PBKDF2 salt
specified by the "s" and "c" parameters (respectively) in the value (s) as a base64url encoded string. This value MUST NOT be the
applicable PBKDF2 JWK object. The derived-key length (dkLen) is 32 empty string. This Header Parameter is REQUIRED and MUST be
octets. understood and processed by implementations when these algorithms are
used.
The salt expands the possible keys that can be derived from a given
password. [RFC2898] originally recommended a minimum salt length of
8 octets (since there is no concern here of a derived key being re-
used for different purposes). The salt MUST be generated randomly;
see [RFC4086] for considerations on generating random values.
4.9.1.2. "p2c" (PBES2 count) Parameter
The "p2c" (PBES2 count) header parameter contains the PBKDF2
iteration count (c), as an integer. This value MUST NOT be less than
1, as per [RFC2898]. This Header Parameter is REQUIRED and MUST be
understood and processed by implementations when these algorithms are
used.
The iteration count adds computational expense, ideally compounded by
the possible range of keys introduced by the salt. [RFC2898]
originally recommended a minimum iteration count of 1000.
4.10. AES_CBC_HMAC_SHA2 Algorithms 4.10. AES_CBC_HMAC_SHA2 Algorithms
This section defines a family of authenticated encryption algorithms This section defines a family of authenticated encryption algorithms
built using a composition of Advanced Encryption Standard (AES) in built using a composition of Advanced Encryption Standard (AES) in
Cipher Block Chaining (CBC) mode with PKCS #5 padding [AES] Cipher Block Chaining (CBC) mode with PKCS #5 padding [AES]
[NIST.800-38A] operations and HMAC [RFC2104] [SHS] operations. This [NIST.800-38A] operations and HMAC [RFC2104] [SHS] operations. This
algorithm family is called AES_CBC_HMAC_SHA2. It also defines two algorithm family is called AES_CBC_HMAC_SHA2. It also defines three
instances of this family, one using 128 bit CBC keys and HMAC SHA-256 instances of this family, the first using 128 bit CBC keys and HMAC
and the other using 256 bit CBC keys and HMAC SHA-512. Test cases SHA-256, the second using 192 bit CBC keys and HMAC SHA-384, and the
for these algorithms can be found in Appendix C. third using 256 bit CBC keys and HMAC SHA-512. Test cases for these
algorithms can be found in Appendix C.
These algorithms are based upon Authenticated Encryption with AES-CBC These algorithms are based upon Authenticated Encryption with AES-CBC
and HMAC-SHA [I-D.mcgrew-aead-aes-cbc-hmac-sha2], performing the same and HMAC-SHA [I-D.mcgrew-aead-aes-cbc-hmac-sha2], performing the same
cryptographic computations, but with the Initialization Vector and cryptographic computations, but with the Initialization Vector and
Authentication Tag values remaining separate, rather than being Authentication Tag values remaining separate, rather than being
concatenated with the Ciphertext value in the output representation. concatenated with the Ciphertext value in the output representation.
This option is discussed in Appendix B of that specification. This
This algorithm family is a generalization of the algorithm family in algorithm family is a generalization of the algorithm family in
[I-D.mcgrew-aead-aes-cbc-hmac-sha2], and can be used to implement [I-D.mcgrew-aead-aes-cbc-hmac-sha2], and can be used to implement
those algorithms. those algorithms.
4.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.
skipping to change at page 26, line 27 skipping to change at page 28, line 19
Code (MAC) to the message M, using the key Y. Code (MAC) to the message M, using the key Y.
The concatenation of two octet strings A and B is denoted as The concatenation of two octet strings A and B is denoted as
A || B. A || B.
4.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.4 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
The authenticated encryption algorithm takes as input four octet The authenticated encryption algorithm takes as input four octet
strings: a secret key K, a plaintext P, associated data A, and an strings: a secret key K, a plaintext P, associated data A, and an
initialization vector IV. The authenticated ciphertext value E and initialization vector IV. The authenticated ciphertext value E and
the authentication tag value T are provided as outputs. The data in the authentication tag value T are provided as outputs. The data in
the plaintext are encrypted and authenticated, and the associated the plaintext are encrypted and authenticated, and the associated
data are authenticated, but not encrypted. data are authenticated, but not encrypted.
skipping to change at page 27, line 6 skipping to change at page 28, line 47
MAC_KEY consists of the initial MAC_KEY_LEN octets of K, in MAC_KEY consists of the initial MAC_KEY_LEN octets of K, in
order. order.
ENC_KEY consists of the final ENC_KEY_LEN octets of K, in ENC_KEY consists of the final ENC_KEY_LEN octets of K, in
order. order.
Here we denote the number of octets in the MAC_KEY as Here we denote the number of octets in the MAC_KEY as
MAC_KEY_LEN, and the number of octets in ENC_KEY as ENC_KEY_LEN; MAC_KEY_LEN, and the number of octets in ENC_KEY as ENC_KEY_LEN;
the values of these parameters are specified by the AEAD the values of these parameters are specified by the AEAD
algorithms (in Section 4.10.3 and Section 4.10.4). The number of algorithms (in Section 4.10.3 and Section 4.10.5). The number of
octets in the input key K is the sum of MAC_KEY_LEN and octets in the input key K is the sum of MAC_KEY_LEN and
ENC_KEY_LEN. When generating the secondary keys from K, MAC_KEY ENC_KEY_LEN. When generating the secondary keys from K, MAC_KEY
and ENC_KEY MUST NOT overlap. Note that the MAC key comes before and ENC_KEY MUST NOT overlap. Note that the MAC key comes before
the encryption key in the input key K; this is in the opposite the encryption key in the input key K; this is in the opposite
order of the algorithm names in the identifier order of the algorithm names in the identifier
"AES_CBC_HMAC_SHA2". "AES_CBC_HMAC_SHA2".
2. The Initialization Vector (IV) used is a 128 bit value generated 2. The Initialization Vector (IV) used is a 128 bit value generated
randomly or pseudorandomly for use in the cipher. randomly or pseudorandomly for use in the cipher.
skipping to change at page 29, line 7 skipping to change at page 31, line 5
with PKCS #5 padding. with PKCS #5 padding.
The input key K is 32 octets long. The input key K is 32 octets long.
The AES CBC IV is 16 octets long. ENC_KEY_LEN is 16 octets. The AES CBC IV is 16 octets long. ENC_KEY_LEN is 16 octets.
The SHA-256 hash algorithm is used in HMAC. MAC_KEY_LEN is 16 The SHA-256 hash algorithm is used in HMAC. MAC_KEY_LEN is 16
octets. The HMAC-SHA-256 output is truncated to T_LEN=16 octets, by octets. The HMAC-SHA-256 output is truncated to T_LEN=16 octets, by
stripping off the final 16 octets. stripping off the final 16 octets.
4.10.4. AES_256_CBC_HMAC_SHA_512 4.10.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.
SHA-384 is used in HMAC instead of SHA-256.
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.
The HMAC SHA-384 value is truncated to T_LEN=24 octets instead of
16.
4.10.5. AES_256_CBC_HMAC_SHA_512
AES_256_CBC_HMAC_SHA_512 is based on AES_128_CBC_HMAC_SHA_256, but AES_256_CBC_HMAC_SHA_512 is based on AES_128_CBC_HMAC_SHA_256, but
with the following differences: with the following differences:
A 256 bit AES CBC key is used instead of 128. A 256 bit AES CBC key is used instead of 128.
SHA-512 is used in HMAC instead of SHA-256. SHA-512 is used in HMAC instead of SHA-256.
ENC_KEY_LEN is 32 octets. ENC_KEY_LEN is 32 octets instead of 16.
MAC_KEY_LEN is 32 octets. MAC_KEY_LEN is 32 octets instead of 16.
The length of the input key K is 64 octets. The length of the input key K is 64 octets instead of 32.
The HMAC SHA-512 value is truncated to T_LEN=32 octets instead of The HMAC SHA-512 value is truncated to T_LEN=32 octets instead of
16 octets. 16.
4.10.5. 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
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. The Additional Authenticated Data
value used is the octets of the ASCII representation of the Encoded value used is the octets of the ASCII representation of the Encoded
JWE Header value. The JWE Initialization Vector value used is the IV JWE Header value. The JWE Initialization Vector value used is the IV
value. 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 or 256 bit keys. The "enc" header [AES] [NIST.800-38D] using 128, 192, or 256 bit keys. The "enc"
parameter values "A128GCM" or "A256GCM" are respectively used in this header parameter values "A128GCM", "A192GCM", or "A256GCM" are
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 The Additional Authenticated Data value used is the octets of the
ASCII representation of the Encoded JWE Header value. 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,
skipping to change at page 31, line 14 skipping to change at page 33, line 30
+-------------+----------------------------------+------------------+ +-------------+----------------------------------+------------------+
| kty | Key Type | Implementation | | kty | Key Type | Implementation |
| Parameter | | Requirements | | Parameter | | Requirements |
| Value | | | | Value | | |
+-------------+----------------------------------+------------------+ +-------------+----------------------------------+------------------+
| EC | Elliptic Curve [DSS] key type | RECOMMENDED+ | | EC | Elliptic Curve [DSS] key type | RECOMMENDED+ |
| RSA | RSA [RFC3447] key type | REQUIRED | | RSA | RSA [RFC3447] key type | REQUIRED |
| oct | Octet sequence key type (used to | RECOMMENDED+ | | oct | Octet sequence key type (used to | RECOMMENDED+ |
| | represent symmetric keys) | | | | represent symmetric keys) | |
| PBKDF2 | Password-Based Key Derivation | OPTIONAL |
| | Function 2 [RFC2898] key type | |
+-------------+----------------------------------+------------------+ +-------------+----------------------------------+------------------+
All the names are short because a core goal of JWK is for the All the names are short because a core goal of JWK is for the
representations to be compact. However, there is no a priori length representations to be compact. However, there is no a priori length
restriction on "kty" values. restriction on "kty" values.
The use of "+" in the Implementation Requirements indicates that the The use of "+" in the Implementation Requirements indicates that the
requirement strength is likely to be increased in a future version of requirement strength is likely to be increased in a future version of
the specification. the specification.
skipping to change at page 33, line 28 skipping to change at page 35, line 39
public key. It is represented as the base64url encoding of the public key. It is represented as the base64url encoding of the
value's unsigned big endian representation as an octet sequence. The value's unsigned big endian representation as an octet sequence. The
array representation MUST utilize the minimum number of octets to array representation MUST utilize the minimum number of octets to
represent the value. For instance, when representing the value represent the value. For instance, when representing the value
65537, the octet sequence to be base64url encoded MUST consist of the 65537, the octet sequence to be base64url encoded MUST consist of the
three octets [1, 0, 1]. three octets [1, 0, 1].
5.3.2. JWK Parameters for RSA Private Keys 5.3.2. JWK Parameters for RSA Private Keys
In addition to the members used to represent RSA public keys, the In addition to the members used to represent RSA public keys, the
following members are used to represent RSA private keys. All are following members are used to represent RSA private keys. The
REQUIRED for RSA private keys except for "oth", which is sometimes parameter "d" is REQUIRED for RSA private keys. The others enable
REQUIRED and sometimes MUST NOT be present, as described below. optimizations and are RECOMMENDED. If any of the others are present
then all MUST be present, with the exception of "oth", which MUST
only be present when more than two prime factors were used.
5.3.2.1. "d" (Private Exponent) Parameter 5.3.2.1. "d" (Private Exponent) Parameter
The "d" (private exponent) member contains the private exponent value The "d" (private exponent) member contains the private exponent value
for the RSA private key. It is represented as the base64url encoding for the RSA private key. It is represented as the base64url encoding
of the value's unsigned big endian representation as an octet of the value's unsigned big endian representation as an octet
sequence. The array representation MUST NOT be shortened to omit any sequence. The array representation MUST NOT be shortened to omit any
leading zero octets. For instance, when representing 2048 bit leading zero octets. For instance, when representing 2048 bit
integers, the octet sequence to be base64url encoded MUST contain 256 integers, the octet sequence to be base64url encoded MUST contain 256
octets, including any leading zero octets. octets, including any leading zero octets.
skipping to change at page 35, line 25 skipping to change at page 37, line 39
When the JWK "kty" member value is "oct" (octet sequence), the When the JWK "kty" member value is "oct" (octet sequence), the
following member is used to represent a symmetric key (or another key following member is used to represent a symmetric key (or another key
whose value is a single octet sequence): whose value is a single octet sequence):
5.3.3.1. "k" (Key Value) Parameter 5.3.3.1. "k" (Key Value) Parameter
The "k" (key value) member contains the value of the symmetric (or The "k" (key value) member contains the value of the symmetric (or
other single-valued) key. It is represented as the base64url other single-valued) key. It is represented as the base64url
encoding of the octet sequence containing the key value. encoding of the octet sequence containing the key value.
5.3.4. JWK Parameters for PBKDF2 Keys
When the JWK "kty" member value is "PBKDF2", the following members
are used to represent the parameters necessary to derive a cipher key
from a password using the PBKDF2 algorithm [RFC2898]:
5.3.4.1. "s" (salt) Parameter
The REQUIRED "s" parameter contains the PBKDF2 salt value (S) as a
base64url encoded string. This value MUST NOT be the empty string.
The salt expands the possible keys that can be derived from a given
password. [RFC2898] originally recommended a minimum salt length of
8 octets (since there is no concern here of a derived key being re-
used for different purposes). The salt MUST be generated randomly;
see [RFC4086] for considerations on generating random values.
5.3.4.2. "c" (count) Parameter
The REQUIRED "c" parameter contains the PBKDF2 iteration count (c),
as an integer. This value MUST NOT be less than 1, as per [RFC2898].
The iteration count adds computational expense, ideally compounded by
the possible range of keys introduced by the salt. [RFC2898]
originally recommended a minimum iteration count of 1000.
5.3.4.3. "hint" (password hint) Parameter
The OPTIONAL "hint" parameter contains a description clue to the
password, as a string. If present, this value SHOULD NOT be the
empty string.
The hint is typically displayed to the user as a reminder or mnemonic
for the actual password used. This parameter MUST NOT contain the
actual password, and implementations MAY use various heuristic
algorithms to prohibit hints that are alternate forms of the actual
password.
5.4. Additional Key Types and Parameters 5.4. Additional Key Types and Parameters
Keys using additional key types can be represented using JWK data Keys using additional key types can be represented using JWK data
structures with corresponding "kty" (key type) parameter values being structures with corresponding "kty" (key type) parameter values being
defined to refer to them. New "kty" parameter values SHOULD either defined to refer to them. New "kty" parameter values SHOULD either
be registered in the IANA JSON Web Key Types registry Section 6.2 or be registered in the IANA JSON Web Key Types registry Section 6.2 or
be a value that contains a Collision Resistant Namespace. be a value that contains a Collision Resistant Namespace.
Likewise, parameters for representing keys for additional key types Likewise, parameters for representing keys for additional key types
or additional key properties SHOULD either be registered in the IANA or additional key properties SHOULD either be registered in the IANA
skipping to change at page 39, line 22 skipping to change at page 40, line 45
o Specification Document(s): Section 3.1 of [[ this document ]] o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "ES512" o Algorithm Name: "ES512"
o Algorithm Usage Location(s): "alg" o Algorithm Usage Location(s): "alg"
o Implementation Requirements: OPTIONAL o Implementation Requirements: OPTIONAL
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 3.1 of [[ this document ]] o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "PS256" o Algorithm Name: "PS256"
o Algorithm Usage Location(s): "alg" o Algorithm Usage Location(s): "alg"
o Implementation Requirements: RECOMMENDED o Implementation Requirements: OPTIONAL
o Change Controller: IETF
o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "PS384"
o Algorithm Usage Location(s): "alg"
o Implementation Requirements: OPTIONAL
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 3.1 of [[ this document ]] o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "PS512" o Algorithm Name: "PS512"
o Algorithm Usage Location(s): "alg" o Algorithm Usage Location(s): "alg"
o Implementation Requirements: RECOMMENDED o Implementation Requirements: OPTIONAL
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 3.1 of [[ this document ]] o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "none" o Algorithm Name: "none"
o Algorithm Usage Location(s): "alg" o Algorithm Usage Location(s): "alg"
o Implementation Requirements: REQUIRED o Implementation Requirements: REQUIRED
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 3.1 of [[ this document ]] o Specification Document(s): Section 3.1 of [[ this document ]]
o Algorithm Name: "RSA1_5" o Algorithm Name: "RSA1_5"
skipping to change at page 40, line 4 skipping to change at page 41, line 32
o Algorithm Usage Location(s): "alg" o Algorithm Usage Location(s): "alg"
o Implementation Requirements: REQUIRED o Implementation Requirements: REQUIRED
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1 of [[ this document ]] o Specification Document(s): Section 4.1 of [[ this document ]]
o Algorithm Name: "RSA-OAEP" o Algorithm Name: "RSA-OAEP"
o Algorithm Usage Location(s): "alg" o Algorithm Usage Location(s): "alg"
o Implementation Requirements: OPTIONAL o Implementation Requirements: OPTIONAL
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1 of [[ this document ]] o Specification Document(s): Section 4.1 of [[ this document ]]
o Algorithm Name: "A128KW" o Algorithm Name: "A128KW"
o Algorithm Usage Location(s): "alg" o Algorithm Usage Location(s): "alg"
o Implementation Requirements: RECOMMENDED o Implementation Requirements: RECOMMENDED
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1 of [[ this document ]] o Specification Document(s): Section 4.1 of [[ this document ]]
o Algorithm Name: "A192KW"
o Algorithm Usage Location(s): "alg"
o Implementation Requirements: OPTIONAL
o Change Controller: IETF
o Specification Document(s): Section 4.1 of [[ this document ]]
o Algorithm Name: "A256KW" o Algorithm Name: "A256KW"
o Algorithm Usage Location(s): "alg" o Algorithm Usage Location(s): "alg"
o Implementation Requirements: RECOMMENDED o Implementation Requirements: RECOMMENDED
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1 of [[ this document ]] o Specification Document(s): Section 4.1 of [[ this document ]]
o Algorithm Name: "dir" o Algorithm Name: "dir"
o Algorithm Usage Location(s): "alg" o Algorithm Usage Location(s): "alg"
o Implementation Requirements: RECOMMENDED o Implementation Requirements: RECOMMENDED
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1 of [[ this document ]] o Specification Document(s): Section 4.1 of [[ this document ]]
o Algorithm Name: "ECDH-ES" o Algorithm Name: "ECDH-ES"
o Algorithm Usage Location(s): "alg" o Algorithm Usage Location(s): "alg"
o Implementation Requirements: RECOMMENDED+ o Implementation Requirements: RECOMMENDED+
o Change Controller: IETF o Change Controller: IETF
skipping to change at page 40, line 34 skipping to change at page 42, line 22
o Implementation Requirements: RECOMMENDED+ o Implementation Requirements: RECOMMENDED+
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1 of [[ this document ]] o Specification Document(s): Section 4.1 of [[ this document ]]
o Algorithm Name: "ECDH-ES+A128KW" o Algorithm Name: "ECDH-ES+A128KW"
o Algorithm Usage Location(s): "alg" o Algorithm Usage Location(s): "alg"
o Implementation Requirements: RECOMMENDED o Implementation Requirements: RECOMMENDED
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1 of [[ this document ]] o Specification Document(s): Section 4.1 of [[ this document ]]
o Algorithm Name: "ECDH-ES+A192KW"
o Algorithm Usage Location(s): "alg"
o Implementation Requirements: OPTIONAL
o Change Controller: IETF
o Specification Document(s): Section 4.1 of [[ this document ]]
o Algorithm Name: "ECDH-ES+A256KW" o Algorithm Name: "ECDH-ES+A256KW"
o Algorithm Usage Location(s): "alg" o Algorithm Usage Location(s): "alg"
o Implementation Requirements: RECOMMENDED o Implementation Requirements: RECOMMENDED
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.1 of [[ this document ]] o Specification Document(s): Section 4.1 of [[ this document ]]
o Algorithm Name: "A128GCMKW" o Algorithm Name: "A128GCMKW"
o Algorithm Usage Location(s): "alg" o Algorithm Usage Location(s): "alg"
o Implementation Requirements: OPTIONAL o Implementation Requirements: OPTIONAL
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.8 of [[ this document ]] o Specification Document(s): Section 4.8 of [[ this document ]]
o Algorithm Name: "A192GCMKW"
o Algorithm Usage Location(s): "alg"
o Implementation Requirements: OPTIONAL
o Change Controller: IETF
o Specification Document(s): Section 4.8 of [[ this document ]]
o Algorithm Name: "A256GCMKW" o Algorithm Name: "A256GCMKW"
o Algorithm Usage Location(s): "alg" o Algorithm Usage Location(s): "alg"
o Implementation Requirements: OPTIONAL o Implementation Requirements: OPTIONAL
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.8 of [[ this document ]] o Specification Document(s): Section 4.8 of [[ this document ]]
o Algorithm Name: "PBES2-HS256+A128KW" o Algorithm Name: "PBES2-HS256+A128KW"
o Algorithm Usage Location(s): "alg" o Algorithm Usage Location(s): "alg"
o Implementation Requirements: OPTIONAL o Implementation Requirements: OPTIONAL
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.9.1 of [[ this document ]] o Specification Document(s): Section 4.9 of [[ this document ]]
o Algorithm Name: "PBES2-HS256+A192KW"
o Algorithm Usage Location(s): "alg"
o Implementation Requirements: OPTIONAL
o Change Controller: IETF
o Specification Document(s): Section 4.9 of [[ this document ]]
o Algorithm Name: "PBES2-HS256+A256KW" o Algorithm Name: "PBES2-HS256+A256KW"
o Algorithm Usage Location(s): "alg" o Algorithm Usage Location(s): "alg"
o Implementation Requirements: OPTIONAL o Implementation Requirements: OPTIONAL
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.9.2 of [[ this document ]] o Specification Document(s): Section 4.9 of [[ this document ]]
o Algorithm Name: "A128CBC-HS256" o Algorithm Name: "A128CBC-HS256"
o Algorithm Usage Location(s): "enc" o Algorithm Usage Location(s): "enc"
o Implementation Requirements: REQUIRED o Implementation Requirements: REQUIRED
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.2 of [[ this document ]] o Specification Document(s): Section 4.2 of [[ this document ]]
o Algorithm Name: "A192CBC-HS384"
o Algorithm Usage Location(s): "enc"
o Implementation Requirements: OPTIONAL
o Change Controller: IETF
o Specification Document(s): Section 4.2 of [[ this document ]]
o Algorithm Name: "A256CBC-HS512" o Algorithm Name: "A256CBC-HS512"
o Algorithm Usage Location(s): "enc" o Algorithm Usage Location(s): "enc"
o Implementation Requirements: REQUIRED o Implementation Requirements: REQUIRED
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.2 of [[ this document ]] o Specification Document(s): Section 4.2 of [[ this document ]]
o Algorithm Name: "A128GCM" o Algorithm Name: "A128GCM"
o Algorithm Usage Location(s): "enc" o Algorithm Usage Location(s): "enc"
o Implementation Requirements: RECOMMENDED o Implementation Requirements: RECOMMENDED
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.2 of [[ this document ]] o Specification Document(s): Section 4.2 of [[ this document ]]
o Algorithm Name: "A192GCM"
o Algorithm Usage Location(s): "enc"
o Implementation Requirements: OPTIONAL
o Change Controller: IETF
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: IETF o Change Controller: IETF
o Specification Document(s): Section 4.2 of [[ this document ]] o Specification Document(s): Section 4.2 of [[ this document ]]
6.2. JSON Web Key Types Registry 6.2. JSON Web Key Types Registry
This specification establishes the IANA JSON Web Key Types registry This specification establishes the IANA JSON Web Key Types registry
for values of the JWK "kty" (key type) parameter. The registry for values of the JWK "kty" (key type) parameter. The registry
skipping to change at page 42, line 49 skipping to change at page 45, line 22
o "kty" Parameter Value: "RSA" o "kty" Parameter Value: "RSA"
o Implementation Requirements: REQUIRED o Implementation Requirements: REQUIRED
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 5.3 of [[ this document ]] o Specification Document(s): Section 5.3 of [[ this document ]]
o "kty" Parameter Value: "oct" o "kty" Parameter Value: "oct"
o Implementation Requirements: RECOMMENDED+ o Implementation Requirements: RECOMMENDED+
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 5.3.3 of [[ this document ]] o Specification Document(s): Section 5.3.3 of [[ this document ]]
o "kty" Paramater value: "PBKDF2"
o Implementation Requirements: OPTIONAL
o Change Controller: IETF
o Specification Document(s): Section 5.3.4 of [[ this document ]]
6.3. JSON Web Key Parameters Registration 6.3. JSON Web Key Parameters Registration
This specification registers the parameter names defined in Sections This specification registers the parameter names defined in Sections
5.2, 5.3, and 5.3.3 in the IANA JSON Web Key Parameters registry 5.2, 5.3, and 5.3.3 in the IANA JSON Web Key Parameters registry
[JWK]. [JWK].
6.3.1. Registry Contents 6.3.1. Registry Contents
o Parameter Name: "crv" o Parameter Name: "crv"
o Parameter Information Class: Public o Parameter Information Class: Public
skipping to change at page 44, line 39 skipping to change at page 47, line 7
o Parameter Name: "oth" o Parameter Name: "oth"
o Parameter Information Class: Private o Parameter Information Class: Private
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 5.3.2.7 of [[ this document ]] o Specification Document(s): Section 5.3.2.7 of [[ this document ]]
o Parameter Name: "k" o Parameter Name: "k"
o Parameter Information Class: Private o Parameter Information Class: Private
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 5.3.3.1 of [[ this document ]] o Specification Document(s): Section 5.3.3.1 of [[ this document ]]
o Parameter Name: "s"
o Parameter Information Class: Public
o Change Controller: IETF
o Specification Document(s): Section 5.3.4.1 of [[ this document ]]
o Parameter Name: "c"
o Parameter Information Class: Public
o Change Controller: IETF
o Specification Document(s): Section 5.3.4.2 of [[ this document ]]
o Parameter Name: "hint"
o Parameter Information Class: Public
o Change Controller: IETF
o Specification Document(s): Section 5.3.4.3 of [[ this document ]]
6.4. Registration of JWE Header Parameter Names 6.4. Registration of JWE Header Parameter Names
This specification registers the Header Parameter Names defined in This specification registers the Header Parameter Names defined in
Section 4.7.1 and Section 4.8.1 in the IANA JSON Web Signature and Section 4.7.1, Section 4.8.1, and Section 4.9.1 in the IANA JSON Web
Encryption Header Parameters registry [JWS]. Signature and Encryption Header Parameters registry [JWS].
6.4.1. Registry Contents 6.4.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: IETF o Change Controller: IETF
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
skipping to change at page 45, line 41 skipping to change at page 47, line 40
o Header Parameter Name: "iv" o Header Parameter Name: "iv"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.8.1.1 of [[ this document ]] o Specification Document(s): Section 4.8.1.1 of [[ this document ]]
o Header Parameter Name: "tag" o Header Parameter Name: "tag"
o Header Parameter Usage Location(s): JWE o Header Parameter Usage Location(s): JWE
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.8.1.2 of [[ this document ]] o Specification Document(s): Section 4.8.1.2 of [[ this document ]]
o Header Parameter Name: "p2s"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF
o Specification Document(s): Section 4.9.1.1 of [[ this document ]]
o Header Parameter Name: "p2c"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF
o Specification Document(s): Section 4.9.1.2 of [[ this document ]]
7. Security Considerations 7. Security Considerations
All of the security issues faced by any cryptographic application All of the security issues faced by any cryptographic application
must be faced by a JWS/JWE/JWK agent. Among these issues are must be faced by a JWS/JWE/JWK agent. Among these issues are
protecting the user's private and symmetric keys, preventing various protecting the user's private and symmetric keys, preventing various
attacks, and helping the user avoid mistakes such as inadvertently attacks, and helping the user avoid mistakes such as inadvertently
encrypting a message for the wrong recipient. The entire list of encrypting a message for the wrong recipient. The entire list of
security considerations is beyond the scope of this document, but security considerations is beyond the scope of this document, but
some significant considerations are listed here. some significant considerations are listed here.
The security considerations in [AES], [DSS], [JWE], [JWK], [JWS], The security considerations in [AES], [DSS], [JWE], [JWK], [JWS],
[NIST.800-38A], [NIST.800-38D], [NIST.800-56A], [RFC2104], [RFC3394], [NIST.800-38A], [NIST.800-38D], [NIST.800-56A], [RFC2104], [RFC3394],
[RFC3447], [RFC5116], [RFC6090], and [SHS] apply to this [RFC3447], [RFC5116], [RFC6090], and [SHS] apply to this
specification. specification.
Eventually the algorithms and/or key sizes currently described in Eventually the algorithms and/or key sizes currently described in
this specification will no longer be considered sufficiently secure this specification will no longer be considered sufficiently secure
and will be removed. Therefore, implementers and deployments must be and will be removed. Therefore, implementers and deployments must be
prepared for this eventuality. prepared for this eventuality.
Many algorithms have associated security considerations related to
key lifetimes and/or the number of times that a key may be used.
Those security considerations continue to apply when using those
algorithms with JOSE data structures.
Algorithms of matching strengths should be used together whenever Algorithms of matching strengths should be used together whenever
possible. For instance, when AES Key Wrap is used with a given key possible. For instance, when AES Key Wrap is used with a given key
size, using the same key size is recommended when AES GCM is also size, using the same key size is recommended when AES GCM is also
used. used.
While Section 8 of RFC 3447 [RFC3447] explicitly calls for people not While Section 8 of RFC 3447 [RFC3447] explicitly calls for people not
to adopt RSASSA-PKCS-v1_5 for new applications and instead requests to adopt RSASSA-PKCS-v1_5 for new applications and instead requests
that people transition to RSASSA-PSS, this specification does include that people transition to RSASSA-PSS, this specification does include
RSASSA-PKCS-v1_5, for interoperability reasons, because it commonly RSASSA-PKCS-v1_5, for interoperability reasons, because it commonly
implemented. implemented.
skipping to change at page 49, line 52 skipping to change at page 52, line 19
[USASCII] American National Standards Institute, "Coded Character [USASCII] American National Standards Institute, "Coded Character
Set -- 7-bit American Standard Code for Information Set -- 7-bit American Standard Code for Information
Interchange", ANSI X3.4, 1986. Interchange", ANSI X3.4, 1986.
9.2. Informative References 9.2. Informative References
[CanvasApp] [CanvasApp]
Facebook, "Canvas Applications", 2010. Facebook, "Canvas Applications", 2010.
[I-D.mcgrew-aead-aes-cbc-hmac-sha2] [I-D.mcgrew-aead-aes-cbc-hmac-sha2]
McGrew, D. and K. Paterson, "Authenticated Encryption with McGrew, D., Foley, J., and K. Paterson, "Authenticated
AES-CBC and HMAC-SHA", Encryption with AES-CBC and HMAC-SHA",
draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress), draft-mcgrew-aead-aes-cbc-hmac-sha2-02 (work in progress),
October 2012. July 2013.
[I-D.miller-jose-jwe-protected-jwk] [I-D.miller-jose-jwe-protected-jwk]
Miller, M., "Using JavaScript Object Notation (JSON) Web Miller, M., "Using JavaScript Object Notation (JSON) Web
Encryption (JWE) for Protecting JSON Web Key (JWK) Encryption (JWE) for Protecting JSON Web Key (JWK)
Objects", draft-miller-jose-jwe-protected-jwk-02 (work in Objects", draft-miller-jose-jwe-protected-jwk-02 (work in
progress), June 2013. progress), June 2013.
[I-D.rescorla-jsms] [I-D.rescorla-jsms]
Rescorla, E. and J. Hildebrand, "JavaScript Message Rescorla, E. and J. Hildebrand, "JavaScript Message
Security Format", draft-rescorla-jsms-00 (work in Security Format", draft-rescorla-jsms-00 (work in
skipping to change at page 53, line 29 skipping to change at page 56, line 5
| thm and | | | | | | thm and | | | | |
| MGF1 | | | | | | MGF1 | | | | |
| mask | | | | | | mask | | | | |
| gener | | | | | | gener | | | | |
| ation | | | | | | ation | | | | |
| func | | | | | | func | | | | |
| tionwit | | | | | | tionwit | | | | |
| h SHA | | | | | | h SHA | | | | |
| -256 | | | | | | -256 | | | | |
| RSASSA- | PS | | | | | RSASSA- | PS | | | |
| PSS | 38 | | | |
| using | 4 | | | |
| SHA-38 | | | | |
| 4hash | | | | |
| algori | | | | |
| thm and | | | | |
| MGF1 | | | | |
| mask | | | | |
| gener | | | | |
| ation | | | | |
| func | | | | |
| tionwit | | | | |
| h SHA | | | | |
| -384 | | | | |
| RSASSA- | PS | | | |
| PSS | 51 | | | | | PSS | 51 | | | |
| using | 2 | | | | | using | 2 | | | |
| SHA-51 | | | | | | SHA-51 | | | | |
| 2hash | | | | | | 2hash | | | | |
| algori | | | | | | algori | | | | |
| thm and | | | | | | thm and | | | | |
| MGF1 | | | | | | MGF1 | | | | |
| mask | | | | | | mask | | | | |
| gener | | | | | | gener | | | | |
| ation | | | | | | ation | | | | |
skipping to change at page 54, line 4 skipping to change at page 56, line 42
| h SHA | | | | | | h SHA | | | | |
| -512 | | | | | | -512 | | | | |
+---------+----+---------------------------+----------+-------------+ +---------+----+---------------------------+----------+-------------+
Appendix B. Encryption Algorithm Identifier Cross-Reference Appendix B. Encryption Algorithm Identifier Cross-Reference
This appendix contains a table cross-referencing the "alg" This appendix contains a table cross-referencing the "alg"
(algorithm) and "enc" (encryption method) values used in this (algorithm) and "enc" (encryption method) values used in this
specification with the equivalent identifiers used by other standards specification with the equivalent identifiers used by other standards
and software packages. See XML Encryption and software packages. See XML Encryption
[W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1
[W3C.CR-xmlenc-core1-20120313], and Java Cryptography Architecture [W3C.CR-xmlenc-core1-20120313], and Java Cryptography Architecture
[JCA] for more information about the names defined by those [JCA] for more information about the names defined by those
documents. documents.
For the composite algorithms "A128CBC-HS256" and "A256CBC-HS512", the For the composite algorithms "A128CBC-HS256", "A192CBC-HS384", and
corresponding AES CBC algorithm identifiers are listed. "A256CBC-HS512", the corresponding AES CBC algorithm identifiers are
listed.
+----------+--------+--------------------------+--------------------+ +----------+--------+--------------------------+--------------------+
| Algorith | JWE | XML ENC | JCA | | Algorith | JWE | XML ENC | JCA |
| m | | | | | m | | | |
+----------+--------+--------------------------+--------------------+ +----------+--------+--------------------------+--------------------+
| RSAES-PK | RSA1_5 | http://www.w3.org/2001/0 | RSA/ECB/PKCS1Paddi | | RSAES-PK | RSA1_5 | http://www.w3.org/2001/0 | RSA/ECB/PKCS1Paddi |
| CS1-V1_5 | | 4/xmlenc#rsa-1_5 | ng | | CS1-V1_5 | | 4/xmlenc#rsa-1_5 | ng |
| RSAES | RSA-OA | http://www.w3.org/2001/0 | RSA/ECB/OAEPWithSH | | RSAES | RSA-OA | http://www.w3.org/2001/0 | RSA/ECB/OAEPWithSH |
| using | EP | 4/xmlenc#rsa-oaep-mgf1p | A-1AndMGF1Padding | | using | EP | 4/xmlenc#rsa-oaep-mgf1p | A-1AndMGF1Padding |
| Optimal | | | | | Optimal | | | |
skipping to change at page 54, line 44 skipping to change at page 57, line 36
| Advanced | A128KW | http://www.w3.org/2001/0 | | | Advanced | A128KW | http://www.w3.org/2001/0 | |
| Encrypti | | 4/xmlenc#kw-aes128 | | | Encrypti | | 4/xmlenc#kw-aes128 | |
| on | | | | | on | | | |
| Standar | | | | | Standar | | | |
| d(AES) | | | | | d(AES) | | | |
| Key Wra | | | | | Key Wra | | | |
| pAlgorit | | | | | pAlgorit | | | |
| hmusing | | | | | hmusing | | | |
| 128 bi | | | | | 128 bi | | | |
| t keys | | | | | t keys | | | |
| AES Key | A192KW | http://www.w3.org/2001/0 | |
| Wrap | | 4/xmlenc#kw-aes192 | |
| Algorith | | | |
| musing | | | |
| 192 bit | | | |
| keys | | | |
| AES Key | A256KW | http://www.w3.org/2001/0 | | | AES Key | A256KW | http://www.w3.org/2001/0 | |
| Wrap | | 4/xmlenc#kw-aes256 | | | Wrap | | 4/xmlenc#kw-aes256 | |
| Algorith | | | | | Algorith | | | |
| musing | | | | | musing | | | |
| 256 bit | | | | | 256 bit | | | |
| keys | | | | | keys | | | |
| AES in | A128CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi | | AES in | A128CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi |
| Cipher | C-HS25 | 4/xmlenc#aes128-cbc | ng | | Cipher | C-HS25 | 4/xmlenc#aes128-cbc | ng |
| Block | 6 | | | | Block | 6 | | |
| Chaining | | | | | Chaining | | | |
| (CBC) | | | | | (CBC) | | | |
| mode | | | | | mode | | | |
| with | | | | | with | | | |
| PKCS #5 | | | | | PKCS #5 | | | |
| padding | | | | | padding | | | |
| using | | | | | using | | | |
| 128 bit | | | | | 128 bit | | | |
| keys | | | | | keys | | | |
| AES in | A192CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi |
| CBC mode | C-HS38 | 4/xmlenc#aes192-cbc | ng |
| with | 4 | | |
| PKCS #5 | | | |
| padding | | | |
| using | | | |
| 192 bit | | | |
| keys | | | |
| AES in | A256CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi | | AES in | A256CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi |
| CBC mode | C-HS51 | 4/xmlenc#aes256-cbc | ng | | CBC mode | C-HS51 | 4/xmlenc#aes256-cbc | ng |
| with | 2 | | | | with | 2 | | |
| PKCS #5 | | | | | PKCS #5 | | | |
| padding | | | | | padding | | | |
| using | | | | | using | | | |
| 256 bit | | | | | 256 bit | | | |
| keys | | | | | keys | | | |
| AES in | A128GC | http://www.w3.org/2009/x | AES/GCM/NoPadding | | AES in | A128GC | http://www.w3.org/2009/x | AES/GCM/NoPadding |
| Galois/C | M | mlenc11#aes128-gcm | | | Galois/C | M | mlenc11#aes128-gcm | |
| ounter | | | | | ounter | | | |
| Mode | | | | | Mode | | | |
| (GCM) | | | | | (GCM) | | | |
| using | | | | | using | | | |
| 128 bit | | | | | 128 bit | | | |
| keys | | | | | keys | | | |
| AES GCM | A192GC | http://www.w3.org/2009/x | AES/GCM/NoPadding |
| using | M | mlenc11#aes192-gcm | |
| 192 bit | | | |
| keys | | | |
| AES GCM | A256GC | http://www.w3.org/2009/x | AES/GCM/NoPadding | | AES GCM | A256GC | http://www.w3.org/2009/x | AES/GCM/NoPadding |
| using | M | mlenc11#aes256-gcm | | | using | M | mlenc11#aes256-gcm | |
| 256 bit | | | | | 256 bit | | | |
| keys | | | | | keys | | | |
+----------+--------+--------------------------+--------------------+ +----------+--------+--------------------------+--------------------+
Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms
The following test cases can be used to validate implementations of The following test cases can be used to validate implementations of
the AES_CBC_HMAC_SHA2 algorithms defined in Section 4.10. They are the AES_CBC_HMAC_SHA2 algorithms defined in Section 4.10. They are
skipping to change at page 57, line 5 skipping to change at page 61, line 5
6e 13 33 14 c5 40 19 e8 ca 79 80 df a4 b9 cf 1b 6e 13 33 14 c5 40 19 e8 ca 79 80 df a4 b9 cf 1b
38 4c 48 6f 3a 54 c5 10 78 15 8e e5 d7 9d e5 9f 38 4c 48 6f 3a 54 c5 10 78 15 8e e5 d7 9d e5 9f
bd 34 d8 48 b3 d6 95 50 a6 76 46 34 44 27 ad e5 bd 34 d8 48 b3 d6 95 50 a6 76 46 34 44 27 ad e5
4b 88 51 ff b5 98 f7 f8 00 74 b9 47 3c 82 e2 db 4b 88 51 ff b5 98 f7 f8 00 74 b9 47 3c 82 e2 db
M = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 M = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4
e6 e5 45 82 47 65 15 f0 ad 9f 75 a2 b7 1c 73 ef e6 e5 45 82 47 65 15 f0 ad 9f 75 a2 b7 1c 73 ef
T = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 T = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4
C.2. Test Cases for AES_256_CBC_HMAC_SHA_512 C.2. Test Cases for AES_192_CBC_HMAC_SHA_384
K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f
10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f
20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f
MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f
10 11 12 13 14 15 16 17
ENC_KEY = 18 19 1a 1b 1c 1d 1e 1f 20 21 22 23 24 25 26 27
28 29 2a 2b 2c 2d 2e 2f
P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20
6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75
69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65
74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62
65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69
6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66
20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f
75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65
IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04
A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63
69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20
4b 65 72 63 6b 68 6f 66 66 73
AL = 00 00 00 00 00 00 01 50
E = ea 65 da 6b 59 e6 1e db 41 9b e6 2d 19 71 2a e5
d3 03 ee b5 00 52 d0 df d6 69 7f 77 22 4c 8e db
00 0d 27 9b dc 14 c1 07 26 54 bd 30 94 42 30 c6
57 be d4 ca 0c 9f 4a 84 66 f2 2b 22 6d 17 46 21
4b f8 cf c2 40 0a dd 9f 51 26 e4 79 66 3f c9 0b
3b ed 78 7a 2f 0f fc bf 39 04 be 2a 64 1d 5c 21
05 bf e5 91 ba e2 3b 1d 74 49 e5 32 ee f6 0a 9a
c8 bb 6c 6b 01 d3 5d 49 78 7b cd 57 ef 48 49 27
f2 80 ad c9 1a c0 c4 e7 9c 7b 11 ef c6 00 54 e3
M = 84 90 ac 0e 58 94 9b fe 51 87 5d 73 3f 93 ac 20
75 16 80 39 cc c7 33 d7 45 94 f8 86 b3 fa af d4
86 f2 5c 71 31 e3 28 1e 36 c7 a2 d1 30 af de 57
T = 84 90 ac 0e 58 94 9b fe 51 87 5d 73 3f 93 ac 20
75 16 80 39 cc c7 33 d7
C.3. Test Cases for AES_256_CBC_HMAC_SHA_512
K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f
10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f
20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f
30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f
MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f
10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f
ENC_KEY = 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f ENC_KEY = 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f
skipping to change at page 58, line 5 skipping to change at page 63, line 5
be 26 38 d0 9d d7 a4 93 09 30 80 6d 07 03 b1 f6 be 26 38 d0 9d d7 a4 93 09 30 80 6d 07 03 b1 f6
M = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf M = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf
2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5
fd 30 a5 65 c6 16 ff b2 f3 64 ba ec e6 8f c4 07 fd 30 a5 65 c6 16 ff b2 f3 64 ba ec e6 8f c4 07
53 bc fc 02 5d de 36 93 75 4a a1 f5 c3 37 3b 9c 53 bc fc 02 5d de 36 93 75 4a a1 f5 c3 37 3b 9c
T = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf T = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf
2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5
Appendix D. Acknowledgements Appendix D. Example ECDH-ES Key Agreement Computation
This example uses ECDH-ES Key Agreement and the Concat KDF to derive
the Content Encryption Key (CEK) in the manner described in
Section 4.7. In this example, the ECDH-ES Direct Key Agreement mode
("alg" value "ECDH-ES") is used to produce an agreed upon key for AES
GCM with 128 bit keys ("enc" value "A128GCM").
In this example, a sender Alice is encrypting content to a recipient
Bob. The sender (Alice) generates an ephemeral key for the key
agreement computation. Alice's ephemeral key (in JWK format) used
for the key agreement computation in this example (including the
private part) is:
{"kty":"EC",
"crv":"P-256",
"x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0",
"y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps",
"d":"0_NxaRPUMQoAJt50Gz8YiTr8gRTwyEaCumd-MToTmIo"
}
The recipient's (Bob's) key (in JWK format) used for the key
agreement computation in this example (including the private part)
is:
{"kty":"EC",
"crv":"P-256",
"x":"weNJy2HscCSM6AEDTDg04biOvhFhyyWvOHQfeF_PxMQ",
"y":"e8lnCO-AlStT-NJVX-crhB7QRYhiix03illJOVAOyck",
"d":"VEmDZpDXXK8p8N0Cndsxs924q6nS1RXFASRl6BfUqdw"
}
Header parameter values used in this example are as follows. In this
example, the "apu" (agreement PartyUInfo) parameter value is the
base64url encoding of the UTF-8 string "Alice" and the "apv"
(agreement PartyVInfo) parameter value is the base64url encoding of
the UTF-8 string "Bob". The "epk" parameter is used to communicate
the sender's (Alice's) ephemeral public key value to the recipient
(Bob).
{"alg":"ECDH-ES",
"enc":"A128GCM",
"apu":"QWxpY2U",
"apv":"Qm9i",
"epk":
{"kty":"EC",
"crv":"P-256",
"x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0",
"y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps"
}
}
The resulting Concat KDF [NIST.800-56A] parameter values are:
Z This is set to the ECDH-ES key agreement output. (This value is
often not directly exposed by libraries, due to NIST security
requirements, and only serves as an input to a KDF.)
keydatalen This value is 128 - the number of bits in the desired
output key (because "A128GCM" uses a 128 bit key).
AlgorithmID This is set to the octets representing the UTF-8 string
"A128GCM" - [65, 49, 50, 56, 71, 67, 77].
PartyUInfo This is set to the octets representing the 32 bit big
endian value 5 - [0, 0, 0, 5] - the number of octets in the
PartyUInfo content "Alice", followed, by the octets representing
the UTF-8 string "Alice" - [65, 108, 105, 99, 101].
PartyVInfo This is set to the octets representing the 32 bit big
endian value 3 - [0, 0, 0, 3] - the number of octets in the
PartyUInfo content "Bob", followed, by the octets representing the
UTF-8 string "Bob" - [66, 111, 98].
SuppPubInfo This is set to the octets representing the 32 bit big
endian value 128 - [0, 0, 0, 128] - the keydatalen value.
SuppPrivInfo This is set to the empty octet sequence.
The resulting derived key, represented as a base64url encoded value
is:
jSNmj9QK9ZGQJ2xg5_TJpA
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
[I-D.mcgrew-aead-aes-cbc-hmac-sha2] specification, upon which the [I-D.mcgrew-aead-aes-cbc-hmac-sha2] specification, upon which the
AES_CBC_HMAC_SHA2 algorithms are based, was written by David A. AES_CBC_HMAC_SHA2 algorithms are based, was written by David A.
skipping to change at page 58, line 40 skipping to change at page 65, line 40
Dirk Balfanz, Richard Barnes, John Bradley, Brian Campbell, Breno de Dirk Balfanz, Richard Barnes, John Bradley, Brian Campbell, Breno de
Medeiros, Yaron Y. Goland, Dick Hardt, Jeff Hodges, Edmund Jay, James Medeiros, Yaron Y. Goland, Dick Hardt, Jeff Hodges, Edmund Jay, James
Manger, Matt Miller, Tony Nadalin, Axel Nennker, John Panzer, Manger, Matt Miller, Tony Nadalin, Axel Nennker, John Panzer,
Emmanuel Raviart, Nat Sakimura, Jim Schaad, Hannes Tschofenig, and Emmanuel Raviart, Nat Sakimura, Jim Schaad, Hannes Tschofenig, and
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 E. 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 ]]
-14
o Removed "PBKDF2" key type and added "p2s" and "p2c" header
parameters for use with the PBES2 algorithms.
o Made the RSA private key parameters that are there to enable
optimizations be RECOMMENDED rather than REQUIRED.
o Added algorithm identifiers for AES algorithms using 192 bit keys
and for RSASSA-PSS using HMAC SHA-384.
o Added security considerations about key lifetimes, addressing
issue #18.
o Added an example ECDH-ES key agreement computation.
-13 -13
o Added key encryption with AES GCM as specified in o Added key encryption with AES GCM as specified in
draft-jones-jose-aes-gcm-key-wrap-01, addressing issue #13. draft-jones-jose-aes-gcm-key-wrap-01, addressing issue #13.
o Added security considerations text limiting the number of times o Added security considerations text limiting the number of times
that an AES GCM key can be used for key encryption or direct that an AES GCM key can be used for key encryption or direct
encryption, per Section 8.3 of NIST SP 800-38D, addressing issue encryption, per Section 8.3 of NIST SP 800-38D, addressing issue
#28. #28.
 End of changes. 79 change blocks. 
251 lines changed or deleted 517 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/