draft-ietf-jose-json-web-algorithms-20.txt   draft-ietf-jose-json-web-algorithms-21.txt 
JOSE Working Group M. Jones JOSE Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track January 20, 2014 Intended status: Standards Track February 14, 2014
Expires: July 24, 2014 Expires: August 18, 2014
JSON Web Algorithms (JWA) JSON Web Algorithms (JWA)
draft-ietf-jose-json-web-algorithms-20 draft-ietf-jose-json-web-algorithms-21
Abstract Abstract
The JSON Web Algorithms (JWA) specification registers cryptographic The JSON Web Algorithms (JWA) specification registers cryptographic
algorithms and identifiers to be used with the JSON Web Signature algorithms and identifiers to be used with the JSON Web Signature
(JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK) (JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK)
specifications. It defines several IANA registries for these specifications. It defines several IANA registries for these
identifiers. identifiers.
Status of this Memo Status of this Memo
skipping to change at page 1, line 34 skipping to change at page 1, line 34
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on July 24, 2014. This Internet-Draft will expire on August 18, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 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 36 skipping to change at page 2, line 36
4.6.1.1. "epk" (Ephemeral Public Key) Header Parameter . . 16 4.6.1.1. "epk" (Ephemeral Public Key) Header Parameter . . 16
4.6.1.2. "apu" (Agreement PartyUInfo) Header Parameter . . 16 4.6.1.2. "apu" (Agreement PartyUInfo) Header Parameter . . 16
4.6.1.3. "apv" (Agreement PartyVInfo) Header Parameter . . 16 4.6.1.3. "apv" (Agreement PartyVInfo) Header Parameter . . 16
4.6.2. Key Derivation for ECDH Key Agreement . . . . . . . . 17 4.6.2. Key Derivation for ECDH Key Agreement . . . . . . . . 17
4.7. Key Encryption with AES GCM . . . . . . . . . . . . . . . 18 4.7. Key Encryption with AES GCM . . . . . . . . . . . . . . . 18
4.7.1. Header Parameters Used for AES GCM Key Encryption . . 19 4.7.1. Header Parameters Used for AES GCM Key Encryption . . 19
4.7.1.1. "iv" (Initialization Vector) Header Parameter . . 19 4.7.1.1. "iv" (Initialization Vector) Header Parameter . . 19
4.7.1.2. "tag" (Authentication Tag) Header Parameter . . . 19 4.7.1.2. "tag" (Authentication Tag) Header Parameter . . . 19
4.8. Key Encryption with PBES2 . . . . . . . . . . . . . . . . 19 4.8. Key Encryption with PBES2 . . . . . . . . . . . . . . . . 19
4.8.1. Header Parameters Used for PBES2 Key Encryption . . . 20 4.8.1. Header Parameters Used for PBES2 Key Encryption . . . 20
4.8.1.1. "p2s" (PBES2 salt) Parameter . . . . . . . . . . . 20 4.8.1.1. "p2s" (PBES2 salt input) Parameter . . . . . . . . 20
4.8.1.2. "p2c" (PBES2 count) Parameter . . . . . . . . . . 20 4.8.1.2. "p2c" (PBES2 count) Parameter . . . . . . . . . . 20
5. Cryptographic Algorithms for Content Encryption . . . . . . . 21 5. Cryptographic Algorithms for Content Encryption . . . . . . . 21
5.1. "enc" (Encryption Algorithm) Header Parameter Values 5.1. "enc" (Encryption Algorithm) Header Parameter Values
for JWE . . . . . . . . . . . . . . . . . . . . . . . . . 21 for JWE . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.2. AES_CBC_HMAC_SHA2 Algorithms . . . . . . . . . . . . . . . 22 5.2. AES_CBC_HMAC_SHA2 Algorithms . . . . . . . . . . . . . . . 22
5.2.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 . . . . 22 5.2.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 . . . . 22
5.2.2. Generic AES_CBC_HMAC_SHA2 Algorithm . . . . . . . . . 22 5.2.2. Generic AES_CBC_HMAC_SHA2 Algorithm . . . . . . . . . 22
5.2.2.1. AES_CBC_HMAC_SHA2 Encryption . . . . . . . . . . . 22 5.2.2.1. AES_CBC_HMAC_SHA2 Encryption . . . . . . . . . . . 22
5.2.2.2. AES_CBC_HMAC_SHA2 Decryption . . . . . . . . . . . 24 5.2.2.2. AES_CBC_HMAC_SHA2 Decryption . . . . . . . . . . . 24
5.2.3. AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . 25 5.2.3. AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . 25
skipping to change at page 19, line 46 skipping to change at page 19, line 46
encryption of a JWE CEK, by first deriving a key encryption key from encryption of a JWE CEK, by first deriving a key encryption key from
a user-supplied password using PBES2 schemes as specified in Section a user-supplied password using PBES2 schemes as specified in Section
6.2 of [RFC2898], then by encrypting the JWE CEK using the derived 6.2 of [RFC2898], then by encrypting the JWE CEK using the derived
key. key.
These algorithms use HMAC SHA-2 algorithms as the Pseudo-Random These algorithms use HMAC SHA-2 algorithms as the Pseudo-Random
Function (PRF) for the PBKDF2 key derivation and AES Key Wrap Function (PRF) for the PBKDF2 key derivation and AES Key Wrap
[RFC3394] for the encryption scheme. The PBES2 password input is an [RFC3394] for the encryption scheme. The PBES2 password input is an
octet sequence; if the password to be used is represented as a text octet sequence; if the password to be used is represented as a text
string rather than an octet sequence, the UTF-8 encoding of the text string rather than an octet sequence, the UTF-8 encoding of the text
string MUST be used as the octet sequence. The salt MUST be provided string MUST be used as the octet sequence. The salt parameter MUST
as the "p2s" Header Parameter value, and MUST be base64url decoded to be computed from the "p2s" (PBES2 salt input) Header Parameter value
obtain the value. The iteration count parameter MUST be provided as and the "alg" (algorithm) Header Parameter value as specified in the
the "p2c" Header Parameter value. The algorithms respectively use "p2s" definition below. The iteration count parameter MUST be
HMAC SHA-256, HMAC SHA-384, and HMAC SHA-512 as the PRF and use 128, provided as the "p2c" Header Parameter value. The algorithms
192, and 256 bit AES Key Wrap keys. Their derived-key lengths respectively use HMAC SHA-256, HMAC SHA-384, and HMAC SHA-512 as the
respectively are 16, 24, and 32 octets. PRF and use 128, 192, and 256 bit AES Key Wrap keys. Their derived-
key lengths respectively are 16, 24, and 32 octets.
The following "alg" (algorithm) Header Parameter values are used to The following "alg" (algorithm) Header Parameter values are used to
indicate that the JWE Encrypted Key is the result of encrypting the indicate that the JWE Encrypted Key is the result of encrypting the
CEK using the result of the corresponding password-based encryption CEK using the result of the corresponding password-based encryption
algorithm as the key encryption key for the corresponding key algorithm as the key encryption key for the corresponding key
wrapping algorithm: wrapping algorithm:
+---------------------+---------------------------------------------+ +---------------------+---------------------------------------------+
| alg Parameter Value | Key Management Algorithm | | alg Parameter Value | Key Management Algorithm |
+---------------------+---------------------------------------------+ +---------------------+---------------------------------------------+
skipping to change at page 20, line 30 skipping to change at page 20, line 31
+---------------------+---------------------------------------------+ +---------------------+---------------------------------------------+
See Appendix C of JSON Web Key (JWK) [JWK] for an example key See Appendix C of JSON Web Key (JWK) [JWK] for an example key
encryption computation using "PBES2-HS256+A128KW". encryption computation using "PBES2-HS256+A128KW".
4.8.1. Header Parameters Used for PBES2 Key Encryption 4.8.1. Header Parameters Used for PBES2 Key Encryption
The following Header Parameters are used for Key Encryption with The following Header Parameters are used for Key Encryption with
PBES2. PBES2.
4.8.1.1. "p2s" (PBES2 salt) Parameter 4.8.1.1. "p2s" (PBES2 salt input) Parameter
The "p2s" (PBES2 salt) Header Parameter contains the PBKDF2 salt The "p2s" (PBES2 salt input) Header Parameter encodes a Salt Input
value, encoded using base64url. This Header Parameter MUST be value, which is used as part of the PBKDF2 salt value. The "p2s"
value is BASE64URL(Salt Input). This Header Parameter MUST be
present and MUST be understood and processed by implementations when present and MUST be understood and processed by implementations when
these algorithms are used. these algorithms are used.
The salt expands the possible keys that can be derived from a given The salt expands the possible keys that can be derived from a given
password. A salt value containing 8 or more octets MUST be used. A password. A Salt Input value containing 8 or more octets MUST be
new salt value MUST be generated randomly for every encryption used. A new Salt Input value MUST be generated randomly for every
operation; see [RFC4086] for considerations on generating random encryption operation; see [RFC4086] for considerations on generating
values. random values. The salt value used is (UTF8(Alg) || 0x00 || Salt
Input), where Alg is the "alg" Header Parameter value.
4.8.1.2. "p2c" (PBES2 count) Parameter 4.8.1.2. "p2c" (PBES2 count) Parameter
The "p2c" (PBES2 count) Header Parameter contains the PBKDF2 The "p2c" (PBES2 count) Header Parameter contains the PBKDF2
iteration count, represented as a positive integer. This Header iteration count, represented as a positive integer. This Header
Parameter MUST be present and MUST be understood and processed by Parameter MUST be present and MUST be understood and processed by
implementations when these algorithms are used. implementations when these algorithms are used.
The iteration count adds computational expense, ideally compounded by The iteration count adds computational expense, ideally compounded by
the possible range of keys introduced by the salt. A minimum the possible range of keys introduced by the salt. A minimum
skipping to change at page 51, line 25 skipping to change at page 51, line 25
of particular concern if these algorithms are used to protect data of particular concern if these algorithms are used to protect data
that an attacker can have indefinite number of attempts to circumvent that an attacker can have indefinite number of attempts to circumvent
the protection, such as protected data stored on a file system. the protection, such as protected data stored on a file system.
9. Internationalization Considerations 9. Internationalization Considerations
Passwords obtained from users are likely to require preparation and Passwords obtained from users are likely to require preparation and
normalization to account for differences of octet sequences generated normalization to account for differences of octet sequences generated
by different input devices, locales, etc. It is RECOMMENDED that by different input devices, locales, etc. It is RECOMMENDED that
applications to perform the steps outlined in applications to perform the steps outlined in
[I-D.melnikov-precis-saslprepbis] to prepare a password supplied [I-D.ietf-precis-saslprepbis] to prepare a password supplied directly
directly by a user before performing key derivation and encryption. by a user before performing key derivation and encryption.
10. References 10. References
10.1. Normative References 10.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-4, July 2013. Signature Standard (DSS)", FIPS PUB 186-4, July 2013.
[I-D.ietf-json-rfc4627bis] [I-D.ietf-json-rfc4627bis]
Bray, T., "The JSON Data Interchange Format", Bray, T., "The JSON Data Interchange Format",
draft-ietf-json-rfc4627bis-10 (work in progress), draft-ietf-json-rfc4627bis-10 (work in progress),
December 2013. December 2013.
[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), January 2014. (work in progress), February 2014.
[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),
January 2014. February 2014.
[JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", draft-ietf-jose-json-web-signature (work Signature (JWS)", draft-ietf-jose-json-web-signature (work
in progress), January 2014. in progress), February 2014.
[NIST.800-38A] [NIST.800-38A]
National Institute of Standards and Technology (NIST), National Institute of Standards and Technology (NIST),
"Recommendation for Block Cipher Modes of Operation", "Recommendation for Block Cipher Modes of Operation",
NIST PUB 800-38A, December 2001. NIST PUB 800-38A, December 2001.
[NIST.800-38D] [NIST.800-38D]
National Institute of Standards and Technology (NIST), National Institute of Standards and Technology (NIST),
"Recommendation for Block Cipher Modes of Operation: "Recommendation for Block Cipher Modes of Operation:
Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D,
skipping to change at page 52, line 50 skipping to change at page 52, line 43
[RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography
Specification Version 2.0", RFC 2898, September 2000. 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.
[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
Encryption", RFC 5116, January 2008.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
[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.
[SEC1] Standards for Efficient Cryptography Group, "SEC 1: [SEC1] Standards for Efficient Cryptography Group, "SEC 1:
Elliptic Curve Cryptography", May 2009. Elliptic Curve Cryptography", May 2009.
[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.
10.2. Informative References 10.2. Informative References
[CanvasApp] [CanvasApp]
Facebook, "Canvas Applications", 2010. Facebook, "Canvas Applications", 2010.
[I-D.ietf-precis-saslprepbis]
Saint-Andre, P. and A. Melnikov, "Preparation and
Comparison of Internationalized Strings Representing
Usernames and Passwords", draft-ietf-precis-saslprepbis-06
(work in progress), December 2013.
[I-D.mcgrew-aead-aes-cbc-hmac-sha2] [I-D.mcgrew-aead-aes-cbc-hmac-sha2]
McGrew, D., Foley, J., and K. Paterson, "Authenticated McGrew, D., Foley, J., and K. Paterson, "Authenticated
Encryption with AES-CBC and HMAC-SHA", Encryption with AES-CBC and HMAC-SHA",
draft-mcgrew-aead-aes-cbc-hmac-sha2-02 (work in progress), draft-mcgrew-aead-aes-cbc-hmac-sha2-04 (work in progress),
July 2013. February 2014.
[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 54, line 29 skipping to change at page 54, line 19
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.
[RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness
Requirements for Security", BCP 106, RFC 4086, June 2005.
[RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated
Encryption", RFC 5116, January 2008.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
[W3C.CR-xmldsig-core2-20120124] [W3C.CR-xmldsig-core2-20120124]
Cantor, S., Roessler, T., Eastlake, D., Yiu, K., Reagle, Cantor, S., Roessler, T., Eastlake, D., Yiu, K., Reagle,
J., Solo, D., Datta, P., and F. Hirsch, "XML Signature J., Solo, D., Datta, P., and F. Hirsch, "XML Signature
Syntax and Processing Version 2.0", World Wide Web Syntax and Processing Version 2.0", World Wide Web
Consortium CR CR-xmldsig-core2-20120124, January 2012, Consortium CR CR-xmldsig-core2-20120124, January 2012,
<http://www.w3.org/TR/2012/CR-xmldsig-core2-20120124>. <http://www.w3.org/TR/2012/CR-xmldsig-core2-20120124>.
[W3C.CR-xmlenc-core1-20120313] [W3C.CR-xmlenc-core1-20120313]
Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch,
"XML Encryption Syntax and Processing Version 1.1", World "XML Encryption Syntax and Processing Version 1.1", World
skipping to change at page 64, line 17 skipping to change at page 64, line 17
Hannes Tschofenig, and Sean Turner. 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 ]]
-21
o Compute the PBES2 salt parameter as (UTF8(Alg) || 0x00 || Salt
Input), where the "p2s" Header Parameter encodes the Salt Input
value and Alg is the "alg" Header Parameter value.
o Changed some references from being normative to informative,
addressing issue #90.
-20 -20
o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis, o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis,
addressing issue #90. addressing issue #90.
-19 -19
o Used tables to show the correspondence between algorithm o Used tables to show the correspondence between algorithm
identifiers and algorithm descriptions and parameters in the identifiers and algorithm descriptions and parameters in the
algorithm definition sections, addressing issue #183. algorithm definition sections, addressing issue #183.
 End of changes. 19 change blocks. 
43 lines changed or deleted 54 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/