draft-ietf-jose-json-web-algorithms-12.txt   draft-ietf-jose-json-web-algorithms-13.txt 
JOSE Working Group M. Jones JOSE Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track July 11, 2013 Intended status: Standards Track July 15, 2013
Expires: January 12, 2014 Expires: January 16, 2014
JSON Web Algorithms (JWA) JSON Web Algorithms (JWA)
draft-ietf-jose-json-web-algorithms-12 draft-ietf-jose-json-web-algorithms-13
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 12, 2014. This Internet-Draft will expire on January 16, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1. Terms Incorporated from the JWS Specification . . . . . . 4 2.1. Terms Incorporated from the JWS Specification . . . . . . 5
2.2. Terms Incorporated from the JWE Specification . . . . . . 5 2.2. Terms Incorporated from the JWE Specification . . . . . . 6
2.3. Terms Incorporated from the JWK Specification . . . . . . 8 2.3. Terms Incorporated from the JWK Specification . . . . . . 9
2.4. Defined Terms . . . . . . . . . . . . . . . . . . . . . . 8 2.4. Defined Terms . . . . . . . . . . . . . . . . . . . . . . 9
3. Cryptographic Algorithms for JWS . . . . . . . . . . . . . . . 8 3. Cryptographic Algorithms for JWS . . . . . . . . . . . . . . . 9
3.1. "alg" (Algorithm) Header Parameter Values for JWS . . . . 8 3.1. "alg" (Algorithm) Header Parameter Values for JWS . . . . 9
3.2. MAC with HMAC SHA-256, HMAC SHA-384, or HMAC SHA-512 . . . 9 3.2. MAC with HMAC SHA-256, HMAC SHA-384, or HMAC SHA-512 . . . 10
3.3. Digital Signature with RSASSA-PKCS1-V1_5 and SHA-256, 3.3. Digital Signature with RSASSA-PKCS1-V1_5 and SHA-256,
SHA-384, or SHA-512 . . . . . . . . . . . . . . . . . . . 10 SHA-384, or SHA-512 . . . . . . . . . . . . . . . . . . . 11
3.4. Digital Signature with ECDSA P-256 SHA-256, ECDSA 3.4. Digital Signature with ECDSA P-256 SHA-256, ECDSA
P-384 SHA-384, or ECDSA P-521 SHA-512 . . . . . . . . . . 11 P-384 SHA-384, or ECDSA P-521 SHA-512 . . . . . . . . . . 12
3.5. Digital Signature with RSASSA-PSS and SHA-256 or 3.5. Digital Signature with RSASSA-PSS and SHA-256 or
SHA-512 . . . . . . . . . . . . . . . . . . . . . . . . . 13 SHA-512 . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.6. Using the Algorithm "none" . . . . . . . . . . . . . . . . 14 3.6. Using the Algorithm "none" . . . . . . . . . . . . . . . . 15
3.7. Additional Digital Signature/MAC Algorithms and 3.7. Additional Digital Signature/MAC Algorithms and
Parameters . . . . . . . . . . . . . . . . . . . . . . . . 14 Parameters . . . . . . . . . . . . . . . . . . . . . . . . 15
4. Cryptographic Algorithms for JWE . . . . . . . . . . . . . . . 15 4. Cryptographic Algorithms for JWE . . . . . . . . . . . . . . . 16
4.1. "alg" (Algorithm) Header Parameter Values for JWE . . . . 15 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 JWE . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.3. Key Encryption with RSAES-PKCS1-V1_5 . . . . . . . . . . . 19 4.3. Key Encryption with RSAES-PKCS1-V1_5 . . . . . . . . . . . 20
4.4. Key Encryption with RSAES OAEP . . . . . . . . . . . . . . 19 4.4. Key Encryption with RSAES OAEP . . . . . . . . . . . . . . 21
4.5. Key Wrapping with AES Key Wrap . . . . . . . . . . . . . . 19 4.5. Key Wrapping with AES Key Wrap . . . . . . . . . . . . . . 21
4.6. Direct Encryption with a Shared Symmetric Key . . . . . . 19 4.6. Direct Encryption with a Shared Symmetric Key . . . . . . 21
4.7. Key Agreement with Elliptic Curve Diffie-Hellman 4.7. Key Agreement with Elliptic Curve Diffie-Hellman
Ephemeral Static (ECDH-ES) . . . . . . . . . . . . . . . . 19 Ephemeral Static (ECDH-ES) . . . . . . . . . . . . . . . . 21
4.7.1. Header Parameters Used for ECDH Key Agreement . . . . 20 4.7.1. Header Parameters Used for ECDH Key Agreement . . . . 22
4.7.1.1. "epk" (Ephemeral Public Key) Header Parameter . . 20 4.7.1.1. "epk" (Ephemeral Public Key) Header Parameter . . 22
4.7.1.2. "apu" (Agreement PartyUInfo) Header Parameter . . 20 4.7.1.2. "apu" (Agreement PartyUInfo) Header Parameter . . 22
4.7.1.3. "apv" (Agreement PartyVInfo) Header Parameter . . 20 4.7.1.3. "apv" (Agreement PartyVInfo) Header Parameter . . 22
4.7.2. Key Derivation for ECDH Key Agreement . . . . . . . . 21 4.7.2. Key Derivation for ECDH Key Agreement . . . . . . . . 22
4.8. AES_CBC_HMAC_SHA2 Algorithms . . . . . . . . . . . . . . . 22 4.8. Key Encryption with AES GCM . . . . . . . . . . . . . . . 24
4.8.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 . . . . 22 4.8.1. Header Parameters Used for AES GCM Key Encryption . . 24
4.8.2. Generic AES_CBC_HMAC_SHA2 Algorithm . . . . . . . . . 23 4.8.1.1. "iv" (Initialization Vector) Header Parameter . . 24
4.8.2.1. AES_CBC_HMAC_SHA2 Encryption . . . . . . . . . . . 23 4.8.1.2. "tag" (Authentication Tag) Header Parameter . . . 24
4.8.2.2. AES_CBC_HMAC_SHA2 Decryption . . . . . . . . . . . 24 4.9. Key Encryption with PBES2 . . . . . . . . . . . . . . . . 25
4.8.3. AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . 25 4.9.1. PBES2-HS256+A128KW . . . . . . . . . . . . . . . . . . 25
4.8.4. AES_256_CBC_HMAC_SHA_512 . . . . . . . . . . . . . . . 25 4.9.2. PBES2-HS256+A256KW . . . . . . . . . . . . . . . . . . 25
4.8.5. Plaintext Encryption with AES_CBC_HMAC_SHA2 . . . . . 26 4.10. AES_CBC_HMAC_SHA2 Algorithms . . . . . . . . . . . . . . . 25
4.9. Plaintext Encryption with AES GCM . . . . . . . . . . . . 26 4.10.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 . . . . 26
4.10. Additional Encryption Algorithms and Parameters . . . . . 26 4.10.2. Generic AES_CBC_HMAC_SHA2 Algorithm . . . . . . . . . 26
5. Cryptographic Algorithms for JWK . . . . . . . . . . . . . . . 27 4.10.2.1. AES_CBC_HMAC_SHA2 Encryption . . . . . . . . . . . 26
5.1. "kty" (Key Type) Parameter Values for JWK . . . . . . . . 27 4.10.2.2. AES_CBC_HMAC_SHA2 Decryption . . . . . . . . . . . 28
5.2. JWK Parameters for Elliptic Curve Keys . . . . . . . . . . 28
5.2.1. JWK Parameters for Elliptic Curve Public Keys . . . . 28 4.10.3. AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . 28
5.2.1.1. "crv" (Curve) Parameter . . . . . . . . . . . . . 28 4.10.4. AES_256_CBC_HMAC_SHA_512 . . . . . . . . . . . . . . . 29
5.2.1.2. "x" (X Coordinate) Parameter . . . . . . . . . . . 28 4.10.5. Plaintext Encryption with AES_CBC_HMAC_SHA2 . . . . . 29
5.2.1.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . 28 4.11. Plaintext Encryption with AES GCM . . . . . . . . . . . . 29
5.2.2. JWK Parameters for Elliptic Curve Private Keys . . . . 29 4.12. Additional Encryption Algorithms and Parameters . . . . . 30
5.2.2.1. "d" (ECC Private Key) Parameter . . . . . . . . . 29 5. Cryptographic Algorithms for JWK . . . . . . . . . . . . . . . 30
5.3. JWK Parameters for RSA Keys . . . . . . . . . . . . . . . 29 5.1. "kty" (Key Type) Parameter Values for JWK . . . . . . . . 30
5.3.1. JWK Parameters for RSA Public Keys . . . . . . . . . . 29 5.2. JWK Parameters for Elliptic Curve Keys . . . . . . . . . . 31
5.3.1.1. "n" (Modulus) Parameter . . . . . . . . . . . . . 29 5.2.1. JWK Parameters for Elliptic Curve Public Keys . . . . 31
5.3.1.2. "e" (Exponent) Parameter . . . . . . . . . . . . . 29 5.2.1.1. "crv" (Curve) Parameter . . . . . . . . . . . . . 31
5.3.2. JWK Parameters for RSA Private Keys . . . . . . . . . 30 5.2.1.2. "x" (X Coordinate) Parameter . . . . . . . . . . . 32
5.3.2.1. "d" (Private Exponent) Parameter . . . . . . . . . 30 5.2.1.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . 32
5.3.2.2. "p" (First Prime Factor) Parameter . . . . . . . . 30 5.2.2. JWK Parameters for Elliptic Curve Private Keys . . . . 32
5.3.2.3. "q" (Second Prime Factor) Parameter . . . . . . . 30 5.2.2.1. "d" (ECC Private Key) Parameter . . . . . . . . . 32
5.3.2.4. "dp" (First Factor CRT Exponent) Parameter . . . . 30 5.3. JWK Parameters for RSA Keys . . . . . . . . . . . . . . . 32
5.3.2.5. "dq" (Second Factor CRT Exponent) Parameter . . . 30 5.3.1. JWK Parameters for RSA Public Keys . . . . . . . . . . 32
5.3.2.6. "qi" (First CRT Coefficient) Parameter . . . . . . 30 5.3.1.1. "n" (Modulus) Parameter . . . . . . . . . . . . . 33
5.3.2.7. "oth" (Other Primes Info) Parameter . . . . . . . 31 5.3.1.2. "e" (Exponent) Parameter . . . . . . . . . . . . . 33
5.3.3. JWK Parameters for Symmetric Keys . . . . . . . . . . 31 5.3.2. JWK Parameters for RSA Private Keys . . . . . . . . . 33
5.3.3.1. "k" (Key Value) Parameter . . . . . . . . . . . . 31 5.3.2.1. "d" (Private Exponent) Parameter . . . . . . . . . 33
5.4. Additional Key Types and Parameters . . . . . . . . . . . 32 5.3.2.2. "p" (First Prime Factor) Parameter . . . . . . . . 33
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 5.3.2.3. "q" (Second Prime Factor) Parameter . . . . . . . 33
6.1. JSON Web Signature and Encryption Algorithms Registry . . 32 5.3.2.4. "dp" (First Factor CRT Exponent) Parameter . . . . 34
6.1.1. Template . . . . . . . . . . . . . . . . . . . . . . . 33 5.3.2.5. "dq" (Second Factor CRT Exponent) Parameter . . . 34
6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 33 5.3.2.6. "qi" (First CRT Coefficient) Parameter . . . . . . 34
6.2. JSON Web Key Types Registry . . . . . . . . . . . . . . . 37 5.3.2.7. "oth" (Other Primes Info) Parameter . . . . . . . 34
6.2.1. Registration Template . . . . . . . . . . . . . . . . 37 5.3.3. JWK Parameters for Symmetric Keys . . . . . . . . . . 35
6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 37 5.3.3.1. "k" (Key Value) Parameter . . . . . . . . . . . . 35
6.3. JSON Web Key Parameters Registration . . . . . . . . . . . 38 5.3.4. JWK Parameters for PBKDF2 Keys . . . . . . . . . . . . 35
6.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 38 5.3.4.1. "s" (salt) Parameter . . . . . . . . . . . . . . . 35
6.4. Registration of JWE Header Parameter Names . . . . . . . . 39 5.3.4.2. "c" (count) Parameter . . . . . . . . . . . . . . 35
6.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 40 5.3.4.3. "hint" (password hint) Parameter . . . . . . . . . 36
7. Security Considerations . . . . . . . . . . . . . . . . . . . 40 5.4. Additional Key Types and Parameters . . . . . . . . . . . 36
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 41 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36
8.1. Normative References . . . . . . . . . . . . . . . . . . . 41 6.1. JSON Web Signature and Encryption Algorithms Registry . . 37
8.2. Informative References . . . . . . . . . . . . . . . . . . 43 6.1.1. Template . . . . . . . . . . . . . . . . . . . . . . . 37
6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 38
6.2. JSON Web Key Types Registry . . . . . . . . . . . . . . . 41
6.2.1. Registration Template . . . . . . . . . . . . . . . . 42
6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 42
6.3. JSON Web Key Parameters Registration . . . . . . . . . . . 43
6.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 43
6.4. Registration of JWE Header Parameter Names . . . . . . . . 45
6.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 45
7. Security Considerations . . . . . . . . . . . . . . . . . . . 45
7.1. Reusing Key Material when Encrypting Keys . . . . . . . . 47
7.2. Password Considerations . . . . . . . . . . . . . . . . . 47
8. Internationalization Considerations . . . . . . . . . . . . . 47
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 . . . . . . . . . . . . . . . . . . . 44 Cross-Reference . . . . . . . . . . . . . . . . . . . 51
Appendix B. Encryption Algorithm Identifier Cross-Reference . . . 46 Appendix B. Encryption Algorithm Identifier Cross-Reference . . . 53
Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms . . . . . 48 Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms . . . . . 55
C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 . . . . . . . . . 49 C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 . . . . . . . . . 56
C.2. Test Cases for AES_256_CBC_HMAC_SHA_512 . . . . . . . . . 50 C.2. Test Cases for AES_256_CBC_HMAC_SHA_512 . . . . . . . . . 57
Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 51 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 58
Appendix E. Document History . . . . . . . . . . . . . . . . . . 51 Appendix E. Document History . . . . . . . . . . . . . . . . . . 58
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 57 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 64
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 15, line 20 skipping to change at page 16, line 20
Key (CEK) and the Plaintext. This section specifies a set of Key (CEK) and the Plaintext. This section specifies a set of
specific algorithms for these purposes. specific algorithms for these purposes.
4.1. "alg" (Algorithm) Header Parameter Values for JWE 4.1. "alg" (Algorithm) Header Parameter Values for JWE
The table below is the set of "alg" (algorithm) header parameter The table below is the set of "alg" (algorithm) header parameter
values that are defined by this specification for use with JWE. values that are defined by this specification for use with JWE.
These algorithms are used to encrypt the CEK, producing the JWE These algorithms are used to encrypt the CEK, producing the JWE
Encrypted Key, or to use key agreement to agree upon the CEK. Encrypted Key, or to use key agreement to agree upon the CEK.
+----------------+--------------------+------------+----------------+ +-------------------+-----------------+------------+----------------+
| alg Parameter | Key Management | Additional | Implementation | | alg Parameter | Key Management | Additional | Implementation |
| Value | Algorithm | Header | Requirements | | Value | Algorithm | Header | Requirements |
| | | Parameters | | | | | Parameters | |
+----------------+--------------------+------------+----------------+ +-------------------+-----------------+------------+----------------+
| RSA1_5 | RSAES-PKCS1-V1_5 | (none) | REQUIRED | | RSA1_5 | RSAES-PKCS1-V1_ | (none) | REQUIRED |
| | [RFC3447] | | | | | 5[RFC3447] | | |
| RSA-OAEP | RSAES using | (none) | OPTIONAL | | RSA-OAEP | RSAES using | (none) | OPTIONAL |
| | Optimal Asymmetric | | | | | Optimal | | |
| | Encryption Padding | | | | | Asymmetric | | |
| | (OAEP) [RFC3447], | | | | | Encryption | | |
| | with the default | | | | | Padding (OAEP) | | |
| | parameters | | | | | [RFC3447], with | | |
| | specified by RFC | | | | | the default | | |
| | 3447 in Section | | | | | parameters | | |
| | A.2.1 | | | | | specified by | | |
| A128KW | Advanced | (none) | RECOMMENDED | | | RFC 3447 in | | |
| | Encryption | | | | | Section A.2.1 | | |
| | Standard (AES) Key | | | | A128KW | Advanced | (none) | RECOMMENDED |
| | Wrap Algorithm | | | | | Encryption | | |
| | [RFC3394] using | | | | | Standard (AES) | | |
| | the default | | | | | Key Wrap | | |
| | initial value | | | | | Algorithm | | |
| | specified in | | | | | [RFC3394] using | | |
| | Section 2.2.3.1 | | | | | the default | | |
| | and using 128 bit | | | | | initial value | | |
| | keys | | | | | specified in | | |
| A256KW | AES Key Wrap | (none) | RECOMMENDED | | | Section 2.2.3.1 | | |
| | Algorithm using | | | | | and using 128 | | |
| | the default | | | | | bit keys | | |
| | initial value | | | | A256KW | AES Key Wrap | (none) | RECOMMENDED |
| | specified in | | | | | Algorithm using | | |
| | Section 2.2.3.1 | | | | | the default | | |
| | and using 256 bit | | | | | initial value | | |
| | keys | | | | | specified in | | |
| dir | Direct use of a | (none) | RECOMMENDED | | | Section 2.2.3.1 | | |
| | shared symmetric | | | | | and using 256 | | |
| | key as the Content | | | | | bit keys | | |
| | Encryption Key | | | | dir | Direct use of a | (none) | RECOMMENDED |
| | (CEK) for the | | | | | shared | | |
| | content encryption | | | | | symmetric key | | |
| | step (rather than | | | | | as the Content | | |
| | using the | | | | | Encryption Key | | |
| | symmetric key to | | | | | (CEK) for the | | |
| | wrap the CEK) | | | | | content | | |
| ECDH-ES | Elliptic Curve | "epk", | RECOMMENDED+ | | | encryption step | | |
| | Diffie-Hellman | "apu", | | | | (rather than | | |
| | Ephemeral Static | "apv" | | | | using the | | |
| | [RFC6090] key | | | | | symmetric key | | |
| | agreement using | | | | | to wrap the | | |
| | the Concat KDF, as | | | | | CEK) | | |
| | defined in Section | | | | ECDH-ES | Elliptic Curve | "epk", | RECOMMENDED+ |
| | 5.8.1 of | | | | | Diffie-Hellman | "apu", | |
| | [NIST.800-56A], | | | | | Ephemeral | "apv" | |
| | with the | | | | | Static | | |
| | agreed-upon key | | | | | [RFC6090] key | | |
| | being used | | | | | agreement using | | |
| | directly as the | | | | | the Concat KDF, | | |
| | Content Encryption | | | | | as defined in | | |
| | Key (CEK) (rather | | | | | Section 5.8.1 | | |
| | than being used to | | | | | of | | |
| | wrap the CEK), as | | | | | [NIST.800-56A], | | |
| | specified in | | | | | with the | | |
| | Section 4.7 | | | | | agreed-upon key | | |
| ECDH-ES+A128KW | Elliptic Curve | "epk", | RECOMMENDED | | | being used | | |
| | Diffie-Hellman | "apu", | | | | directly as the | | |
| | Ephemeral Static | "apv" | | | | Content | | |
| | key agreement per | | | | | Encryption Key | | |
| | "ECDH-ES" and | | | | | (CEK) (rather | | |
| | Section 4.7, but | | | | | than being used | | |
| | where the | | | | | to wrap the | | |
| | agreed-upon key is | | | | | CEK), as | | |
| | used to wrap the | | | | | specified in | | |
| | Content Encryption | | | | | Section 4.7 | | |
| | Key (CEK) with the | | | | ECDH-ES+A128KW | Elliptic Curve | "epk", | RECOMMENDED |
| | "A128KW" function | | | | | Diffie-Hellman | "apu", | |
| | (rather than being | | | | | Ephemeral | "apv" | |
| | used directly as | | | | | Static key | | |
| | the CEK) | | | | | agreement per | | |
| ECDH-ES+A256KW | Elliptic Curve | "epk", | RECOMMENDED | | | "ECDH-ES" and | | |
| | Diffie-Hellman | "apu", | | | | Section 4.7, | | |
| | Ephemeral Static | "apv" | | | | but where the | | |
| | key agreement per | | | | | agreed-upon key | | |
| | "ECDH-ES" and | | | | | is used to wrap | | |
| | Section 4.7, but | | | | | the Content | | |
| | where the | | | | | Encryption Key | | |
| | agreed-upon key is | | | | | (CEK) with the | | |
| | used to wrap the | | | | | "A128KW" | | |
| | Content Encryption | | | | | function | | |
| | Key (CEK) with the | | | | | (rather than | | |
| | "A256KW" function | | | | | being used | | |
| | (rather than being | | | | | directly as the | | |
| | used directly as | | | | | CEK) | | |
| | the CEK) | | | | ECDH-ES+A256KW | Elliptic Curve | "epk", | RECOMMENDED |
+----------------+--------------------+------------+----------------+ | | Diffie-Hellman | "apu", | |
| | Ephemeral | "apv" | |
| | Static key | | |
| | agreement, but | | |
| | where the | | |
| | agreed-upon key | | |
| | is used to wrap | | |
| | the Content | | |
| | Encryption Key | | |
| | (CEK) with the | | |
| | "A256KW" | | |
| | function | | |
| | (rather than | | |
| | being used | | |
| | directly as the | | |
| | CEK) | | |
| A128GCMKW | AES in | "iv", | OPTIONAL |
| | Galois/Counter | "tag" | |
| | Mode (GCM) | | |
| | [AES] | | |
| | [NIST.800-38D] | | |
| | using 128 bit | | |
| | keys | | |
| A256GCMKW | AES GCM using | "iv", | OPTIONAL |
| | 256 bit keys | "tag" | |
| PBES2-HS256+A128K | PBES2 [RFC2898] | (none) | OPTIONAL |
| W | with HMAC | | |
| | SHA-256 as the | | |
| | PRF and AES Key | | |
| | Wrap [RFC3394] | | |
| | using 128 bit | | |
| | keys for the | | |
| | encryption | | |
| | scheme | | |
| PBES2-HS256+A256K | PBES2 with HMAC | (none) | OPTIONAL |
| W | SHA-256 as the | | |
| | PRF and AES Key | | |
| | Wrap using 256 | | |
| | bit keys for | | |
| | the encryption | | |
| | 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.
The Additional Header Parameters column indicates what additional The Additional Header Parameters column indicates what additional
Header Parameters are used by the algorithm, beyond "alg", which all Header Parameters are used by the algorithm, beyond "alg", which all
use. All but "dir" and "ECDH-ES" also produce a JWE Encrypted Key use. All but "dir" and "ECDH-ES" also produce a JWE Encrypted Key
value. value.
skipping to change at page 18, line 22 skipping to change at page 20, line 15
+-------------+------------------------+------------+---------------+ +-------------+------------------------+------------+---------------+
| enc | Content Encryption | Additional | Implementatio | | enc | Content Encryption | Additional | Implementatio |
| Parameter | Algorithm | Header | nRequirements | | Parameter | Algorithm | Header | nRequirements |
| Value | | Parameters | | | Value | | Parameters | |
+-------------+------------------------+------------+---------------+ +-------------+------------------------+------------+---------------+
| A128CBC-HS2 | The | (none) | REQUIRED | | A128CBC-HS2 | The | (none) | REQUIRED |
| 56 | AES_128_CBC_HMAC_SHA_2 | | | | 56 | AES_128_CBC_HMAC_SHA_2 | | |
| | 56 authenticated | | | | | 56 authenticated | | |
| | encryption algorithm, | | | | | encryption algorithm, | | |
| | as defined in | | | | | as defined in | | |
| | Section 4.8.3. This | | | | | Section 4.10.3. This | | |
| | algorithm uses a 256 | | | | | algorithm uses a 256 | | |
| | bit key. | | | | | 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.8.4. This | | | | | Section 4.10.4. 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 | | |
| 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 and produce use. All also use a JWE Initialization Vector value and produce JWE
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"
(algorithm) and "enc" (encryption method) values used in this (algorithm) and "enc" (encryption method) values used in this
specification with the equivalent identifiers used by other standards specification with the equivalent identifiers used by other standards
and software packages. and software packages.
4.3. Key Encryption with RSAES-PKCS1-V1_5 4.3. Key Encryption with RSAES-PKCS1-V1_5
This section defines the specifics of encrypting a JWE CEK with This section defines the specifics of encrypting a JWE CEK with
RSAES-PKCS1-V1_5 [RFC3447]. The "alg" header parameter value RSAES-PKCS1-V1_5 [RFC3447]. The "alg" header parameter value
skipping to change at page 22, line 15 skipping to change at page 24, line 4
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.
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. AES_CBC_HMAC_SHA2 Algorithms 4.8. Key Encryption with AES GCM
This section defines the specifics of encrypting a JWE Content
Encryption Key (CEK) with Advanced Encryption Standard (AES) in
Galois/Counter Mode (GCM) [AES] [NIST.800-38D] using 128 or 256 bit
keys. The "alg" header parameter values "A128GCMKW" or "A256GCMKW"
are respectively used in this case.
Use of an Initialization Vector of size 96 bits is REQUIRED with this
algorithm. The Initialization Vector is represented in base64url
encoded form as the "iv" (initialization vector) header parameter
value.
The Additional Authenticated Data value used is the empty octet
string.
The requested size of the Authentication Tag output MUST be 128 bits,
regardless of the key size.
The JWE Encrypted Key value is the Ciphertext output.
The Authentication Tag output is represented in base64url encoded
form as the "tag" (authentication tag) header parameter value.
4.8.1. Header Parameters Used for AES GCM Key Encryption
The following Header Parameter Names are used for AES GCM key
encryption. They MAY also be used by other algorithms if so
specified by those algorithm parameter definitions.
4.8.1.1. "iv" (Initialization Vector) Header Parameter
The "iv" (initialization vector) header parameter value is the
base64url encoded representation of the Initialization Vector value
used for the key encryption operation. This Header Parameter is
REQUIRED and MUST be understood and processed by implementations when
these algorithms are used.
4.8.1.2. "tag" (Authentication Tag) Header Parameter
The "tag" (authentication tag) header parameter value is the
base64url encoded representation of the Authentication Tag value
resulting from the key encryption operation. This Header Parameter
is REQUIRED and MUST be understood and processed by implementations
when these algorithms are used.
4.9. Key Encryption with PBES2
The "PBES2-HS256+A128KW" and "PBES2-HS256+A256KW" algorithms defined
below are used to encrypt a JWE Content Master Key using a user-
supplied password to derive the key encryption key. With these
algorithms, the derived key is used to encrypt the JWE Content Master
Key. These algorithms combine a key derivation function with an
encryption scheme to encrypt the JWE Content Master Key according to
PBES2 from Section 6.2 of [RFC2898].
4.9.1. PBES2-HS256+A128KW
The "PBES2-HS256+A128KW" algorithm uses HMAC SHA-256 as the Pseudo-
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 "PBES2-HS256+A256KW" algorithm uses HMAC SHA-256 as the Pseudo-
Random Function (PRF) and AES Key Wrap using 256 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 32
octets.
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 two
instances of this family, one using 128 bit CBC keys and HMAC SHA-256 instances of this family, one using 128 bit CBC keys and HMAC SHA-256
and the other using 256 bit CBC keys and HMAC SHA-512. Test cases and the other using 256 bit CBC keys and HMAC SHA-512. Test cases
for these algorithms can be found in Appendix C. for these algorithms can be found in Appendix C.
skipping to change at page 22, line 37 skipping to change at page 26, line 4
algorithm family is called AES_CBC_HMAC_SHA2. It also defines two algorithm family is called AES_CBC_HMAC_SHA2. It also defines two
instances of this family, one using 128 bit CBC keys and HMAC SHA-256 instances of this family, one using 128 bit CBC keys and HMAC SHA-256
and the other using 256 bit CBC keys and HMAC SHA-512. Test cases and the other using 256 bit CBC keys and HMAC SHA-512. Test cases
for these algorithms can be found in Appendix C. 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 algorithm family is a generalization of the algorithm family in This algorithm family is a generalization of the algorithm family in
[I-D.mcgrew-aead-aes-cbc-hmac-sha2], and can be used to implement [I-D.mcgrew-aead-aes-cbc-hmac-sha2], and can be used to implement
those algorithms. those algorithms.
4.8.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 4.10.1. Conventions Used in Defining AES_CBC_HMAC_SHA2
We use the following notational conventions. We use the following notational conventions.
CBC-PKCS5-ENC(X, P) denotes the AES CBC encryption of P using PKCS CBC-PKCS5-ENC(X, P) denotes the AES CBC encryption of P using PKCS
#5 padding using the cipher with the key X. #5 padding using the cipher with the key X.
MAC(Y, M) denotes the application of the Message Authentication MAC(Y, M) denotes the application of the Message Authentication
Code (MAC) to the message M, using the key Y. Code (MAC) to the message M, using the key Y.
The concatenation of two octet strings A and B is denoted as The concatenation of two octet strings A and B is denoted as
A || B. A || B.
4.8.2. Generic AES_CBC_HMAC_SHA2 Algorithm 4.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.8.2.1 and Section 4.8.2.2 define the generic encryption and Section 4.10.2.1 and Section 4.10.2.2 define the generic encryption
decryption algorithms. Section 4.8.3 and Section 4.8.4 define and decryption algorithms. Section 4.10.3 and Section 4.10.4 define
instances of AES_CBC_HMAC_SHA2 that specify those details. instances of AES_CBC_HMAC_SHA2 that specify those details.
4.8.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.
The encryption process is as follows, or uses an equivalent set of The encryption process is as follows, or uses an equivalent set of
steps: steps:
skipping to change at page 23, line 38 skipping to change at page 27, line 6
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.8.3 and Section 4.8.4). The number of algorithms (in Section 4.10.3 and Section 4.10.4). 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 24, line 35 skipping to change at page 28, line 4
The encryption process can be illustrated as follows. Here K, P, A, The encryption process can be illustrated as follows. Here K, P, A,
IV, and E denote the key, plaintext, associated data, initialization IV, and E denote the key, plaintext, associated data, initialization
vector, and ciphertext, respectively. vector, and ciphertext, respectively.
MAC_KEY = initial MAC_KEY_LEN bytes of K, MAC_KEY = initial MAC_KEY_LEN bytes of K,
ENC_KEY = final ENC_KEY_LEN bytes of K, ENC_KEY = final ENC_KEY_LEN bytes of K,
E = CBC-PKCS5-ENC(ENC_KEY, P), E = CBC-PKCS5-ENC(ENC_KEY, P),
M = MAC(MAC_KEY, A || IV || E || AL), M = MAC(MAC_KEY, A || IV || E || AL),
T = initial T_LEN bytes of M. T = initial T_LEN bytes of M.
4.8.2.2. AES_CBC_HMAC_SHA2 Decryption 4.10.2.2. AES_CBC_HMAC_SHA2 Decryption
The authenticated decryption operation has four inputs: K, A, E, and The authenticated decryption operation has four inputs: K, A, E, and
T as defined above. It has only a single output, either a plaintext T as defined above. It has only a single output, either a plaintext
value P or a special symbol FAIL that indicates that the inputs are value P or a special symbol FAIL that indicates that the inputs are
not authentic. The authenticated decryption algorithm is as follows, not authentic. The authenticated decryption algorithm is as follows,
or uses an equivalent set of steps: or uses an equivalent set of steps:
1. The secondary keys MAC_KEY and ENC_KEY are generated from the 1. The secondary keys MAC_KEY and ENC_KEY are generated from the
input key K as in Step 1 of Section 4.8.2.1. input key K as in Step 1 of Section 4.10.2.1.
2. The integrity and authenticity of A and E are checked by 2. The integrity and authenticity of A and E are checked by
computing an HMAC with the inputs as in Step 5 of computing an HMAC with the inputs as in Step 5 of
Section 4.8.2.1. The value T, from the previous step, is Section 4.10.2.1. The value T, from the previous step, is
compared to the first MAC_KEY length bits of the HMAC output. If compared to the first MAC_KEY length bits of the HMAC output. If
those values are identical, then A and E are considered valid, those values are identical, then A and E are considered valid,
and processing is continued. Otherwise, all of the data used in and processing is continued. Otherwise, all of the data used in
the MAC validation are discarded, and the AEAD decryption the MAC validation are discarded, and the AEAD decryption
operation returns an indication that it failed, and the operation operation returns an indication that it failed, and the operation
halts. (But see Section 10 of [JWE] for security considerations halts. (But see Section 10 of [JWE] for security considerations
on thwarting timing attacks.) on thwarting timing attacks.)
3. The value E is decrypted and the PKCS #5 padding is removed. The 3. The value E is decrypted and the PKCS #5 padding is removed. The
value IV is used as the initialization vector. The value ENC_KEY value IV is used as the initialization vector. The value ENC_KEY
is used as the decryption key. is used as the decryption key.
4. The plaintext value is returned. 4. The plaintext value is returned.
4.8.3. AES_128_CBC_HMAC_SHA_256 4.10.3. AES_128_CBC_HMAC_SHA_256
This algorithm is a concrete instantiation of the generic This algorithm is a concrete instantiation of the generic
AES_CBC_HMAC_SHA2 algorithm above. It uses the HMAC message AES_CBC_HMAC_SHA2 algorithm above. It uses the HMAC message
authentication code [RFC2104] with the SHA-256 hash function [SHS] to authentication code [RFC2104] with the SHA-256 hash function [SHS] to
provide message authentication, with the HMAC output truncated to 128 provide message authentication, with the HMAC output truncated to 128
bits, corresponding to the HMAC-SHA-256-128 algorithm defined in bits, corresponding to the HMAC-SHA-256-128 algorithm defined in
[RFC4868]. For encryption, it uses AES in the Cipher Block Chaining [RFC4868]. For encryption, it uses AES in the Cipher Block Chaining
(CBC) mode of operation as defined in Section 6.2 of [NIST.800-38A], (CBC) mode of operation as defined in Section 6.2 of [NIST.800-38A],
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.8.4. AES_256_CBC_HMAC_SHA_512 4.10.4. 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.
MAC_KEY_LEN is 32 octets. MAC_KEY_LEN is 32 octets.
The length of the input key K is 64 octets. The length of the input key K is 64 octets.
The HMAC SHA-512 value is truncated to T_LEN=32 octets instead of The HMAC SHA-512 value is truncated to T_LEN=32 octets instead of
16 octets. 16 octets.
4.8.5. Plaintext Encryption with AES_CBC_HMAC_SHA2 4.10.5. Plaintext Encryption with AES_CBC_HMAC_SHA2
The algorithm value "A128CBC-HS256" is used as the "alg" value when The algorithm value "A128CBC-HS256" is used as the "alg" value when
using AES_128_CBC_HMAC_SHA_256 with JWE. The algorithm value using AES_128_CBC_HMAC_SHA_256 with JWE. The algorithm value
"A256CBC-HS512" is used as the "alg" value when using "A256CBC-HS512" is used as the "alg" value when using
AES_256_CBC_HMAC_SHA_512 with JWE. 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.9. 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 or 256 bit keys. The "enc" header
parameter values "A128GCM" or "A256GCM" are respectively used in this parameter values "A128GCM" or "A256GCM" are respectively used in this
case. 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
skipping to change at page 26, line 45 skipping to change at page 30, line 12
The requested size of the Authentication Tag output MUST be 128 bits, The requested size of the Authentication Tag output MUST be 128 bits,
regardless of the key size. regardless of the key size.
The JWE Authentication Tag is set to be the Authentication Tag value The JWE Authentication Tag is set to be the Authentication Tag value
produced by the encryption. During decryption, the received JWE produced by the encryption. During decryption, the received JWE
Authentication Tag is used as the Authentication Tag value. Authentication Tag is used as the Authentication Tag value.
An example using this algorithm is shown in Appendix A.1 of [JWE]. An example using this algorithm is shown in Appendix A.1 of [JWE].
4.10. Additional Encryption Algorithms and Parameters 4.12. Additional Encryption Algorithms and Parameters
Additional algorithms MAY be used to protect JWEs with corresponding Additional algorithms MAY be used to protect JWEs with corresponding
"alg" (algorithm) and "enc" (encryption method) header parameter "alg" (algorithm) and "enc" (encryption method) header parameter
values being defined to refer to them. New "alg" and "enc" header values being defined to refer to them. New "alg" and "enc" header
parameter values SHOULD either be registered in the IANA JSON Web parameter values SHOULD either be registered in the IANA JSON Web
Signature and Encryption Algorithms registry Section 6.1 or be a Signature and Encryption Algorithms registry Section 6.1 or be a
value that contains a Collision Resistant Namespace. In particular, value that contains a Collision Resistant Namespace. In particular,
it is permissible to use the algorithm identifiers defined in XML it is permissible to use the algorithm identifiers defined in XML
Encryption [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 Encryption [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1
[W3C.CR-xmlenc-core1-20120313], and related specifications as "alg" [W3C.CR-xmlenc-core1-20120313], and related specifications as "alg"
skipping to change at page 27, line 45 skipping to change at page 31, line 14
+-------------+----------------------------------+------------------+ +-------------+----------------------------------+------------------+
| 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 32, line 5 skipping to change at page 35, line 25
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 36, line 28 skipping to change at page 40, line 40
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+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 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 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: "PBES2-HS256+A128KW"
o Algorithm Usage Location(s): "alg"
o Implementation Requirements: OPTIONAL
o Change Controller: IETF
o Specification Document(s): Section 4.9.1 of [[ this document ]]
o Algorithm Name: "PBES2-HS256+A256KW"
o Algorithm Usage Location(s): "alg"
o Implementation Requirements: OPTIONAL
o Change Controller: IETF
o Specification Document(s): Section 4.9.2 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: "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
skipping to change at page 37, line 46 skipping to change at page 42, line 37
Reference to the document(s) that specify the parameter, Reference to the document(s) that specify the parameter,
preferably including URI(s) that can be used to retrieve copies of preferably including URI(s) that can be used to retrieve copies of
the document(s). An indication of the relevant sections may also the document(s). An indication of the relevant sections may also
be included but is not required. be included but is not required.
6.2.2. Initial Registry Contents 6.2.2. Initial Registry Contents
o "kty" Parameter Value: "EC" o "kty" Parameter Value: "EC"
o Implementation Requirements: RECOMMENDED+ o Implementation Requirements: RECOMMENDED+
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 5.1 of [[ this document ]] o Specification Document(s): Section 5.2 of [[ this document ]]
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.1 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.1 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"
skipping to change at page 39, line 44 skipping to change at page 44, line 39
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 in the IANA JSON Web Signature and Encryption Header Section 4.7.1 and Section 4.8.1 in the IANA JSON Web Signature and
Parameters registry [JWS]. 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
o Change Controller: IETF o Change Controller: IETF
o Specification Document(s): Section 4.7.1.2 of [[ this document ]] o Specification Document(s): Section 4.7.1.2 of [[ this document ]]
o Header Parameter Name: "apv" o Header Parameter Name: "apv"
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.3 of [[ this document ]] o Specification Document(s): Section 4.7.1.3 of [[ this document ]]
o Header Parameter Name: "iv"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF
o Specification Document(s): Section 4.8.1.1 of [[ this document ]]
o Header Parameter Name: "tag"
o Header Parameter Usage Location(s): JWE
o Change Controller: IETF
o Specification Document(s): Section 4.8.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.
skipping to change at page 41, line 9 skipping to change at page 46, line 30
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.
Keys used with RSAES-PKCS1-v1_5 must follow the constraints in Keys used with RSAES-PKCS1-v1_5 must follow the constraints in
Section 7.2 of RFC 3447 [RFC3447]. In particular, keys with a low Section 7.2 of RFC 3447 [RFC3447]. In particular, keys with a low
public key exponent value must not be used. public key exponent value must not be used.
Keys used with AES GCM must follow the constraints in Section 8.3 of
[NIST.800-38D], which states: "The total number of invocations of the
authenticated encryption function shall not exceed 2^32, including
all IV lengths and all instances of the authenticated encryption
function with the given key". In accordance with this rule, AES GCM
MUST NOT be used with the same key encryption key or with the same
direct encryption key more than 2^32 times.
Plaintext JWSs (JWSs that use the "alg" value "none") provide no Plaintext JWSs (JWSs that use the "alg" value "none") provide no
integrity protection. Thus, they must only be used in contexts where integrity protection. Thus, they must only be used in contexts where
the payload is secured by means other than a digital signature or MAC the payload is secured by means other than a digital signature or MAC
value, or need not be secured. value, or need not be secured.
Receiving agents that validate signatures and sending agents that Receiving agents that validate signatures and sending agents that
encrypt messages need to be cautious of cryptographic processing encrypt messages need to be cautious of cryptographic processing
usage when validating signatures and encrypting messages using keys usage when validating signatures and encrypting messages using keys
larger than those mandated in this specification. An attacker could larger than those mandated in this specification. An attacker could
send certificates with keys that would result in excessive send certificates with keys that would result in excessive
cryptographic processing, for example, keys larger than those cryptographic processing, for example, keys larger than those
mandated in this specification, which could swamp the processing mandated in this specification, which could swamp the processing
element. Agents that use such keys without first validating the element. Agents that use such keys without first validating the
certificate to a trust anchor are advised to have some sort of certificate to a trust anchor are advised to have some sort of
cryptographic resource management system to prevent such attacks. cryptographic resource management system to prevent such attacks.
8. References 7.1. Reusing Key Material when Encrypting Keys
8.1. Normative References It is NOT RECOMMENDED to reuse the same key material (Key Encryption
Key, Content Master Key, Initialization Vector, etc.) to encrypt
multiple JWK or JWK Set objects, or to encrypt the same JWK or JWK
Set object multiple times. One suggestion for preventing re-use is
to always generate a new set key material for each encryption
operation, based on the considerations noted in this document as well
as from [RFC4086].
7.2. Password Considerations
While convenient for end users, passwords are vulnerable to a number
of attacks. To help mitigate some of these limitations, this
document applies principles from [RFC2898] to derive cryptographic
keys from user-supplied passwords.
However, the strength of the password still has a significant impact.
A high-entry password has greater resistance to dictionary attacks.
[NIST-800-63-1] contains guidelines for estimating password entropy,
which can help applications and users generate stronger passwords.
An ideal password is one that is as large (or larger) than the
derived key length but less than the PRF's block size. Passwords
larger than the PRF's block size are first hashed, which reduces an
attacker's effective search space to the length of the hash algorithm
(32 octets for HMAC SHA-256). It is RECOMMENDED that the password be
no longer than 64 octets long for "PBES2-HS256+A256KW".
Still, care needs to be taken in where and how password-based
encryption is used. Such algorithms MUST NOT be used where the
attacker can make an indefinite number of attempts to circumvent the
protection.
8. Internationalization Considerations
Passwords obtained from users are likely to require preparation and
normalization to account for differences of octet sequences generated
by different input devices, locales, etc. It is RECOMMENDED that
applications to perform the steps outlined in
[I-D.melnikov-precis-saslprepbis] to prepare a password supplied
directly by a user before performing key derivation and encryption.
9. References
9.1. Normative References
[AES] National Institute of Standards and Technology (NIST), [AES] National Institute of Standards and Technology (NIST),
"Advanced Encryption Standard (AES)", FIPS PUB 197, "Advanced Encryption Standard (AES)", FIPS PUB 197,
November 2001. November 2001.
[DSS] National Institute of Standards and Technology, "Digital [DSS] National Institute of Standards and Technology, "Digital
Signature Standard (DSS)", FIPS PUB 186-3, June 2009. Signature Standard (DSS)", FIPS PUB 186-3, June 2009.
[I-D.melnikov-precis-saslprepbis]
Saint-Andre, P. and A. Melnikov, "Preparation and
Comparison of Internationalized Strings Representing
Simple User Names and Passwords",
draft-melnikov-precis-saslprepbis-04 (work in progress),
September 2012.
[JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web
Encryption (JWE)", draft-ietf-jose-json-web-encryption Encryption (JWE)", draft-ietf-jose-json-web-encryption
(work in progress), July 2013. (work in progress), July 2013.
[JWK] Jones, M., "JSON Web Key (JWK)", [JWK] Jones, M., "JSON Web Key (JWK)",
draft-ietf-jose-json-web-key (work in progress), draft-ietf-jose-json-web-key (work in progress),
July 2013. July 2013.
[JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", draft-ietf-jose-json-web-signature (work Signature (JWS)", draft-ietf-jose-json-web-signature (work
skipping to change at page 42, line 24 skipping to change at page 49, line 8
Using Discrete Logarithm Cryptography", NIST Special Using Discrete Logarithm Cryptography", NIST Special
Publication 800-56A, Revision 2, May 2013. Publication 800-56A, Revision 2, May 2013.
[RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
Hashing for Message Authentication", RFC 2104, Hashing for Message Authentication", RFC 2104,
February 1997. February 1997.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography
Specification Version 2.0", RFC 2898, September 2000.
[RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard
(AES) Key Wrap Algorithm", RFC 3394, September 2002. (AES) Key Wrap Algorithm", RFC 3394, September 2002.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003. 10646", STD 63, RFC 3629, November 2003.
[RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness
Requirements for Security", BCP 106, RFC 4086, June 2005.
[RFC4627] Crockford, D., "The application/json Media Type for [RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006. JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, October 2006. Encodings", RFC 4648, October 2006.
[RFC4868] Kelly, S. and S. Frankel, "Using HMAC-SHA-256, HMAC-SHA- [RFC4868] Kelly, S. and S. Frankel, "Using HMAC-SHA-256, HMAC-SHA-
384, and HMAC-SHA-512 with IPsec", RFC 4868, May 2007. 384, and HMAC-SHA-512 with IPsec", RFC 4868, May 2007.
[RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated
skipping to change at page 43, line 7 skipping to change at page 49, line 46
[RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic
Curve Cryptography Algorithms", RFC 6090, February 2011. Curve Cryptography Algorithms", RFC 6090, February 2011.
[SHS] National Institute of Standards and Technology, "Secure [SHS] National Institute of Standards and Technology, "Secure
Hash Standard (SHS)", FIPS PUB 180-3, October 2008. Hash Standard (SHS)", FIPS PUB 180-3, October 2008.
[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.
8.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. and K. Paterson, "Authenticated Encryption with
AES-CBC and HMAC-SHA", AES-CBC and HMAC-SHA",
draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress), draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress),
October 2012. October 2012.
[I-D.miller-jose-jwe-protected-jwk]
Miller, M., "Using JavaScript Object Notation (JSON) Web
Encryption (JWE) for Protecting JSON Web Key (JWK)
Objects", draft-miller-jose-jwe-protected-jwk-02 (work in
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
progress), March 2011. progress), March 2011.
[JCA] Oracle, "Java Cryptography Architecture", 2011. [JCA] Oracle, "Java Cryptography Architecture", 2011.
[JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple
Encryption", September 2010. Encryption", September 2010.
[JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign",
September 2010. September 2010.
[MagicSignatures] [MagicSignatures]
Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic
Signatures", January 2011. Signatures", January 2011.
[NIST-800-63-1]
National Institute of Standards and Technology (NIST),
"Electronic Authentication Guideline", NIST 800-63-1,
December 2011.
[RFC2631] Rescorla, E., "Diffie-Hellman Key Agreement Method", [RFC2631] Rescorla, E., "Diffie-Hellman Key Agreement Method",
RFC 2631, June 1999. RFC 2631, June 1999.
[RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup
Language) XML-Signature Syntax and Processing", RFC 3275, Language) XML-Signature Syntax and Processing", RFC 3275,
March 2002. March 2002.
[RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography
Standards (PKCS) #1: RSA Cryptography Specifications Standards (PKCS) #1: RSA Cryptography Specifications
Version 2.1", RFC 3447, February 2003. Version 2.1", RFC 3447, February 2003.
skipping to change at page 48, line 41 skipping to change at page 55, line 41
| keys | | | | | 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.8. They are the AES_CBC_HMAC_SHA2 algorithms defined in Section 4.10. They are
also intended to correspond to test cases that may appear in a future also intended to correspond to test cases that may appear in a future
version of [I-D.mcgrew-aead-aes-cbc-hmac-sha2], demonstrating that version of [I-D.mcgrew-aead-aes-cbc-hmac-sha2], demonstrating that
the cryptographic computations performed are the same. the cryptographic computations performed are the same.
The variable names are those defined in Section 4.8. All values are The variable names are those defined in Section 4.10. All values are
hexadecimal. hexadecimal.
C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 C.1. Test Cases for AES_128_CBC_HMAC_SHA_256
AES_128_CBC_HMAC_SHA_256 AES_128_CBC_HMAC_SHA_256
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
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
skipping to change at page 51, line 20 skipping to change at page 58, line 20
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.
McGrew and Kenny Paterson. The test cases for AES_CBC_HMAC_SHA2 are McGrew and Kenny Paterson. The test cases for AES_CBC_HMAC_SHA2 are
based upon those for [I-D.mcgrew-aead-aes-cbc-hmac-sha2] by John based upon those for [I-D.mcgrew-aead-aes-cbc-hmac-sha2] by John
Foley. Foley.
Matt Miller wrote Using JavaScript Object Notation (JSON) Web
Encryption (JWE) for Protecting JSON Web Key (JWK) Objects
[I-D.miller-jose-jwe-protected-jwk], which the password-based
encryption content of this draft is based upon.
This specification is the work of the JOSE Working Group, which This specification is the work of the JOSE Working Group, which
includes dozens of active and dedicated participants. In particular, includes dozens of active and dedicated participants. In particular,
the following individuals contributed ideas, feedback, and wording the following individuals contributed ideas, feedback, and wording
that influenced this specification: that influenced this specification:
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, Tony Nadalin, Axel Nennker, John Panzer, Emmanuel Raviart, Manger, Matt Miller, Tony Nadalin, Axel Nennker, John Panzer,
Nat Sakimura, Jim Schaad, Hannes Tschofenig, and Sean Turner. Emmanuel Raviart, Nat Sakimura, Jim Schaad, Hannes Tschofenig, and
Sean Turner.
Jim Schaad and Karen O'Donoghue chaired the JOSE working group and Jim Schaad and Karen O'Donoghue chaired the JOSE working group and
Sean Turner and Stephen Farrell served as Security area directors Sean Turner and Stephen Farrell served as Security area directors
during the creation of this specification. during the creation of this specification.
Appendix E. Document History Appendix E. Document History
[[ to be removed by the RFC editor before publication as an RFC ]] [[ to be removed by the RFC editor before publication as an RFC ]]
-13
o Added key encryption with AES GCM as specified in
draft-jones-jose-aes-gcm-key-wrap-01, addressing issue #13.
o Added security considerations text limiting the number of times
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
#28.
o Added password-based key encryption as specified in
draft-miller-jose-jwe-protected-jwk-02.
-12 -12
o In the Direct Key Agreement case, the Concat KDF AlgorithmID is o In the Direct Key Agreement case, the Concat KDF AlgorithmID is
set to the octets of the UTF-8 representation of the "enc" header set to the octets of the UTF-8 representation of the "enc" header
parameter value. parameter value.
o Restored the "apv" (agreement PartyVInfo) parameter. o Restored the "apv" (agreement PartyVInfo) parameter.
o Moved the "epk", "apu", and "apv" Header Parameter definitions to o Moved the "epk", "apu", and "apv" Header Parameter definitions to
be with the algorithm descriptions that use them. be with the algorithm descriptions that use them.
 End of changes. 55 change blocks. 
217 lines changed or deleted 534 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/