draft-ietf-jose-json-web-algorithms-23.txt   draft-ietf-jose-json-web-algorithms-24.txt 
JOSE Working Group M. Jones JOSE Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track March 3, 2014 Intended status: Standards Track March 18, 2014
Expires: September 4, 2014 Expires: September 19, 2014
JSON Web Algorithms (JWA) JSON Web Algorithms (JWA)
draft-ietf-jose-json-web-algorithms-23 draft-ietf-jose-json-web-algorithms-24
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 September 4, 2014. This Internet-Draft will expire on September 19, 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 5, line 12 skipping to change at page 5, line 12
Appendix E. Document History . . . . . . . . . . . . . . . . . . 64 Appendix E. Document History . . . . . . . . . . . . . . . . . . 64
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 72 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 72
1. Introduction 1. Introduction
The JSON Web Algorithms (JWA) specification registers cryptographic The JSON Web Algorithms (JWA) specification registers cryptographic
algorithms and identifiers to be used with the JSON Web Signature algorithms and identifiers to be used with the JSON Web Signature
(JWS) [JWS], JSON Web Encryption (JWE) [JWE], and JSON Web Key (JWK) (JWS) [JWS], JSON Web Encryption (JWE) [JWE], and JSON Web Key (JWK)
[JWK] specifications. It defines several IANA registries for these [JWK] specifications. It defines several IANA registries for these
identifiers. All these specifications utilize JavaScript Object identifiers. All these specifications utilize JavaScript Object
Notation (JSON) [RFC7158] based data structures. This specification Notation (JSON) [RFC7159] based data structures. This specification
also describes the semantics and operations that are specific to also describes the semantics and operations that are specific to
these algorithms and key types. these algorithms and key types.
Registering the algorithms and identifiers here, rather than in the Registering the algorithms and identifiers here, rather than in the
JWS, JWE, and JWK specifications, is intended to allow them to remain JWS, JWE, and JWK specifications, is intended to allow them to remain
unchanged in the face of changes in the set of Required, Recommended, unchanged in the face of changes in the set of Required, Recommended,
Optional, and Deprecated algorithms over time. This also allows Optional, and Deprecated algorithms over time. This also allows
changes to the JWS, JWE, and JWK specifications without changing this changes to the JWS, JWE, and JWK specifications without changing this
document. document.
skipping to change at page 23, line 8 skipping to change at page 23, line 8
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 5.2.2.1 and Section 5.2.2.2 define the generic encryption and Section 5.2.2.1 and Section 5.2.2.2 define the generic encryption and
decryption algorithms. Section 5.2.3 and Section 5.2.5 define decryption algorithms. Section 5.2.3 and Section 5.2.5 define
instances of AES_CBC_HMAC_SHA2 that specify those details. instances of AES_CBC_HMAC_SHA2 that specify those details.
5.2.2.1. AES_CBC_HMAC_SHA2 Encryption 5.2.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, additional authenticated data
initialization vector IV. The authenticated ciphertext value E and A, and an initialization vector IV. The authenticated ciphertext
the authentication tag value T are provided as outputs. The data in value E and the authentication tag value T are provided as outputs.
the plaintext are encrypted and authenticated, and the associated The data in the plaintext are encrypted and authenticated, and the
data are authenticated, but not encrypted. additional authenticated 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:
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 follows. Each of these two keys is an octet input key K as follows. Each of these two keys is an octet
string. string.
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.
skipping to change at page 23, line 51 skipping to change at page 23, line 51
3. The plaintext is CBC encrypted using PKCS #5 padding using 3. The plaintext is CBC encrypted using PKCS #5 padding using
ENC_KEY as the key, and the IV. We denote the ciphertext output ENC_KEY as the key, and the IV. We denote the ciphertext output
from this step as E. from this step as E.
4. The octet string AL is equal to the number of bits in A expressed 4. The octet string AL is equal to the number of bits in A expressed
as a 64-bit unsigned integer in network byte order. as a 64-bit unsigned integer in network byte order.
5. A message authentication tag T is computed by applying HMAC 5. A message authentication tag T is computed by applying HMAC
[RFC2104] to the following data, in order: [RFC2104] to the following data, in order:
the associated data A, the additional authenticated data A,
the initialization vector IV, the initialization vector IV,
the ciphertext E computed in the previous step, and the ciphertext E computed in the previous step, and
the octet string AL defined above. the octet string AL defined above.
The string MAC_KEY is used as the MAC key. We denote the output The string MAC_KEY is used as the MAC key. We denote the output
of the MAC computed in this step as M. The first T_LEN bits of M of the MAC computed in this step as M. The first T_LEN bits of M
are used as T. are used as T.
6. The Ciphertext E and the Authentication Tag T are returned as the 6. The Ciphertext E and the Authentication Tag T are returned as the
outputs of the authenticated encryption. outputs of the authenticated encryption.
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, additional authenticated data,
vector, and ciphertext, respectively. initialization 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.
skipping to change at page 26, line 23 skipping to change at page 26, line 23
MAC_KEY_LEN is 32 octets instead of 16. MAC_KEY_LEN is 32 octets instead of 16.
SHA-512 is used for the HMAC instead of SHA-256. SHA-512 is used for the HMAC instead of SHA-256.
The HMAC SHA-512 value is truncated to T_LEN=32 octets instead of The HMAC SHA-512 value is truncated to T_LEN=32 octets instead of
16. 16.
5.2.6. Content Encryption with AES_CBC_HMAC_SHA2 5.2.6. Content Encryption with AES_CBC_HMAC_SHA2
This section defines the specifics of performing authenticated
encryption with the AES_CBC_HMAC_SHA2 algorithms.
The CEK is used as the secret key K.
The following "enc" (encryption algorithm) Header Parameter values The following "enc" (encryption algorithm) Header Parameter values
are used to indicate that the JWE Ciphertext and JWE Authentication are used to indicate that the JWE Ciphertext and JWE Authentication
Tag values have been computed using the corresponding algorithm: Tag values have been computed using the corresponding algorithm:
+---------------+---------------------------------------------------+ +---------------+---------------------------------------------------+
| enc Parameter | Content Encryption Algorithm | | enc Parameter | Content Encryption Algorithm |
| Value | | | Value | |
+---------------+---------------------------------------------------+ +---------------+---------------------------------------------------+
| A128CBC-HS256 | AES_128_CBC_HMAC_SHA_256 authenticated encryption | | A128CBC-HS256 | AES_128_CBC_HMAC_SHA_256 authenticated encryption |
| | algorithm, as defined in Section 5.2.3 | | | algorithm, as defined in Section 5.2.3 |
| A192CBC-HS384 | AES_192_CBC_HMAC_SHA_384 authenticated encryption | | A192CBC-HS384 | AES_192_CBC_HMAC_SHA_384 authenticated encryption |
| | algorithm, as defined in Section 5.2.4 | | | algorithm, as defined in Section 5.2.4 |
| A256CBC-HS512 | AES_256_CBC_HMAC_SHA_512 authenticated encryption | | A256CBC-HS512 | AES_256_CBC_HMAC_SHA_512 authenticated encryption |
| | algorithm, as defined in Section 5.2.5 | | | algorithm, as defined in Section 5.2.5 |
+---------------+---------------------------------------------------+ +---------------+---------------------------------------------------+
5.3. Content Encryption with AES GCM 5.3. Content Encryption with AES GCM
This section defines the specifics of encrypting the JWE Plaintext This section defines the specifics of performing authenticated
with Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM) encryption with Advanced Encryption Standard (AES) in Galois/Counter
[AES] [NIST.800-38D]. The "enc" Header Parameter values "A128GCM", Mode (GCM) [AES] [NIST.800-38D].
"A192GCM", or "A256GCM" are respectively used in this case.
The CEK is used as the encryption key. The CEK is used as the encryption key.
Use of an initialization vector of size 96 bits is REQUIRED with this Use of an initialization vector of size 96 bits is REQUIRED with this
algorithm. algorithm.
The 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
produced by the encryption. During decryption, the received JWE
Authentication Tag is used as the Authentication Tag value.
The following "enc" (encryption algorithm) Header Parameter values The following "enc" (encryption algorithm) Header Parameter values
are used to indicate that the JWE Ciphertext and JWE Authentication are used to indicate that the JWE Ciphertext and JWE Authentication
Tag values have been computed using the corresponding algorithm and Tag values have been computed using the corresponding algorithm and
key size: key size:
+---------------------+------------------------------+ +---------------------+------------------------------+
| enc Parameter Value | Content Encryption Algorithm | | enc Parameter Value | Content Encryption Algorithm |
+---------------------+------------------------------+ +---------------------+------------------------------+
| A128GCM | AES GCM using 128 bit key | | A128GCM | AES GCM using 128 bit key |
| A192GCM | AES GCM using 192 bit key | | A192GCM | AES GCM using 192 bit key |
skipping to change at page 51, line 39 skipping to change at page 51, line 39
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.
[JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
Encryption (JWE)", draft-ietf-jose-json-web-encryption draft-ietf-jose-json-web-encryption (work in progress),
(work in progress), March 2014. March 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),
March 2014. March 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), March 2014. in progress), March 2014.
[NIST.800-38A] [NIST.800-38A]
skipping to change at page 52, line 44 skipping to change at page 52, line 44
[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.
[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.
[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.
[RFC7158] Bray, T., "The JavaScript Object Notation (JSON) Data [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7158, March 2014. Interchange Format", RFC 7159, March 2014.
[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.
skipping to change at page 64, line 14 skipping to change at page 64, line 14
[I-D.miller-jose-jwe-protected-jwk], which the password-based [I-D.miller-jose-jwe-protected-jwk], which the password-based
encryption content of this draft is based upon. 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, Vladimir Dzhuvinov, Yaron Y. Goland, Dick Hardt, Jeff Medeiros, Vladimir Dzhuvinov, Yaron Y. Goland, Dick Hardt, Joe
Hodges, Edmund Jay, James Manger, Matt Miller, Tony Nadalin, Axel Hildebrand, Jeff Hodges, Edmund Jay, James Manger, Matt Miller, Tony
Nennker, John Panzer, Emmanuel Raviart, Nat Sakimura, Jim Schaad, Nadalin, Axel Nennker, John Panzer, Emmanuel Raviart, Eric Rescorla,
Hannes Tschofenig, and Sean Turner. 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 ]]
-24
o Replaced uses of the term "associated data" wherever it was used
to refer to a data value with "additional authenticated data",
since both terms were being used as synonyms, causing confusion.
o Updated the JSON reference to RFC 7159.
-23 -23
o No changes were made, other than to the version number and date. o No changes were made, other than to the version number and date.
-22 -22
o Corrected RFC 2119 terminology usage. o Corrected RFC 2119 terminology usage.
o Replaced references to draft-ietf-json-rfc4627bis with RFC 7158. o Replaced references to draft-ietf-json-rfc4627bis with RFC 7158.
 End of changes. 14 change blocks. 
30 lines changed or deleted 38 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/