draft-ietf-jose-json-web-algorithms-37.txt   draft-ietf-jose-json-web-algorithms-38.txt 
JOSE Working Group M. Jones JOSE Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track November 19, 2014 Intended status: Standards Track December 9, 2014
Expires: May 23, 2015 Expires: June 12, 2015
JSON Web Algorithms (JWA) JSON Web Algorithms (JWA)
draft-ietf-jose-json-web-algorithms-37 draft-ietf-jose-json-web-algorithms-38
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 May 23, 2015. This Internet-Draft will expire on June 12, 2015.
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 12, line 8 skipping to change at page 12, line 8
using MGF1 as the mask generation function with SHA-256. using MGF1 as the mask generation function with SHA-256.
Signing and validation with the RSASSA-PSS SHA-384 and RSASSA-PSS Signing and validation with the RSASSA-PSS SHA-384 and RSASSA-PSS
SHA-512 algorithms is performed identically to the procedure for SHA-512 algorithms is performed identically to the procedure for
RSASSA-PSS SHA-256 -- just using the alternative hash algorithm in RSASSA-PSS SHA-256 -- just using the alternative hash algorithm in
both roles. both roles.
3.6. Using the Algorithm "none" 3.6. Using the Algorithm "none"
JWSs MAY also be created that do not provide integrity protection. JWSs MAY also be created that do not provide integrity protection.
Such a JWS is called an Unsecured JWS. An Unsecured JWS MUST use the Such a JWS is called an Unsecured JWS. An Unsecured JWS uses the
"alg" value "none", and is formatted identically to other JWSs, but "alg" value "none" and is formatted identically to other JWSs, but
MUST use the empty octet sequence as its JWS Signature value. MUST use the empty octet sequence as its JWS Signature value.
Recipients MUST verify that the JWS Signature value is the empty Recipients MUST verify that the JWS Signature value is the empty
octet sequence. octet sequence.
Implementations that support Unsecured JWS objects MUST NOT accept Implementations that support Unsecured JWSs MUST NOT accept such
such objects as valid unless the application specifies that it is objects as valid unless the application specifies that it is
acceptable for a specific object to not be integrity protected. acceptable for a specific object to not be integrity protected.
Implementations MUST NOT accept Unsecured JWS objects by default. In Implementations MUST NOT accept Unsecured JWSs by default. In order
order to mitigate downgrade attacks, applications MUST NOT signal to mitigate downgrade attacks, applications MUST NOT signal
acceptance of Unsecured JWS objects at a global level, and SHOULD acceptance of Unsecured JWSs at a global level, and SHOULD signal
signal acceptance on a per-object basis. See Section 8.5 for acceptance on a per-object basis. See Section 8.5 for security
security considerations associated with using this algorithm. considerations associated with using this algorithm.
4. Cryptographic Algorithms for Key Management 4. Cryptographic Algorithms for Key Management
JWE uses cryptographic algorithms to encrypt or determine the Content JWE uses cryptographic algorithms to encrypt or determine the Content
Encryption Key (CEK). Encryption Key (CEK).
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.
skipping to change at page 19, line 18 skipping to change at page 19, line 18
integer. integer.
SuppPrivInfo SuppPrivInfo
This is set to the empty octet sequence. This is set to the empty octet sequence.
Applications need to specify how the "apu" and "apv" parameters are Applications need to specify how the "apu" and "apv" parameters are
used for that application. The "apu" and "apv" values MUST be used for that application. The "apu" and "apv" values MUST be
distinct, when used. Applications wishing to conform to distinct, when used. Applications wishing to conform to
[NIST.800-56A] need to provide values that meet the requirements of [NIST.800-56A] need to provide values that meet the requirements of
that document, e.g., by using values that identify the producer and that document, e.g., by using values that identify the producer and
recipient. Alternatively, applications MAY conduct key derivation in consumer. Alternatively, applications MAY conduct key derivation in
a manner similar to The Diffie-Hellman Key Agreement Method a manner similar to The Diffie-Hellman Key Agreement Method
[RFC2631]: In that case, the "apu" field MAY either be omitted or [RFC2631]: In that case, the "apu" field MAY either be omitted or
represent a random 512-bit value (analogous to PartyAInfo in represent a random 512-bit value (analogous to PartyAInfo in
Ephemeral-Static mode in RFC 2631) and the "apv" field SHOULD NOT be Ephemeral-Static mode in RFC 2631) and the "apv" field SHOULD NOT be
present. present.
See Appendix C for an example key agreement computation using this See Appendix C for an example key agreement computation using this
method. method.
4.7. Key Encryption with AES GCM 4.7. Key Encryption with AES GCM
skipping to change at page 32, line 16 skipping to change at page 32, line 16
The "oth" (other primes info) member contains an array of information The "oth" (other primes info) member contains an array of information
about any third and subsequent primes, should they exist. When only about any third and subsequent primes, should they exist. When only
two primes have been used (the normal case), this parameter MUST be two primes have been used (the normal case), this parameter MUST be
omitted. When three or more primes have been used, the number of omitted. When three or more primes have been used, the number of
array elements MUST be the number of primes used minus two. For more array elements MUST be the number of primes used minus two. For more
information on this case, see the description of the OtherPrimeInfo information on this case, see the description of the OtherPrimeInfo
parameters in Section A.1.2 of RFC 3447 [RFC3447], upon which the parameters in Section A.1.2 of RFC 3447 [RFC3447], upon which the
following parameters are modelled. If the consumer of a JWK does not following parameters are modelled. If the consumer of a JWK does not
support private keys with more than two primes and it encounters a support private keys with more than two primes and it encounters a
private key that includes the "oth" parameter, then it MUST either private key that includes the "oth" parameter, then it MUST NOT use
reject the key or ignore all the private key parameters other than the key. Each array element MUST be an object with the following
"d". Each array element MUST be an object with the following
members: members:
6.3.2.7.1. "r" (Prime Factor) 6.3.2.7.1. "r" (Prime Factor)
The "r" (prime factor) parameter within an "oth" array member The "r" (prime factor) parameter within an "oth" array member
represents the value of a subsequent prime factor. It is represented represents the value of a subsequent prime factor. It is represented
as a Base64urlUInt encoded value. as a Base64urlUInt encoded value.
6.3.2.7.2. "d" (Factor CRT Exponent) 6.3.2.7.2. "d" (Factor CRT Exponent)
skipping to change at page 50, line 24 skipping to change at page 50, line 24
This security consideration does not apply to the composite AES-CBC This security consideration does not apply to the composite AES-CBC
HMAC SHA-2 or AES Key Wrap algorithms. HMAC SHA-2 or AES Key Wrap algorithms.
8.5. Unsecured JWS Security Considerations 8.5. Unsecured JWS Security Considerations
Unsecured JWSs (JWSs that use the "alg" value "none") provide no Unsecured JWSs (JWSs that use the "alg" value "none") provide no
integrity protection. Thus, they must only be used in contexts in integrity protection. Thus, they must only be used in contexts in
which the payload is secured by means other than a digital signature which the payload is secured by means other than a digital signature
or MAC value, or need not be secured. or MAC value, or need not be secured.
An example means of preventing accepting Unsecured JWS objects by An example means of preventing accepting Unsecured JWSs by default is
default is for the "verify" method of a hypothetical JWS software for the "verify" method of a hypothetical JWS software library to
library to have a Boolean "acceptUnsecured" parameter that indicates have a Boolean "acceptUnsecured" parameter that indicates "none" is
"none" is an acceptable "alg" value. As another example, the an acceptable "alg" value. As another example, the "verify" method
"verify" method might take a list of algorithms that are acceptable might take a list of algorithms that are acceptable to the
to the application as a parameter and would reject Unsecured JWS application as a parameter and would reject Unsecured JWS values if
values if "none" is not in that list. "none" is not in that list.
The following example illustrates the reasons for not accepting The following example illustrates the reasons for not accepting
Unsecured JWS objects at a global level. Suppose an application Unsecured JWSs at a global level. Suppose an application accepts
accepts JWS objects over two channels, (1) HTTP and (2) HTTPS with JWSs over two channels, (1) HTTP and (2) HTTPS with client
client authentication. It requires a JWS signature on objects authentication. It requires a JWS signature on objects received over
received over HTTP, but accepts Unsecured JWS objects over HTTPS. If HTTP, but accepts Unsecured JWSs over HTTPS. If the application were
the application were to globally indicate that "none" is acceptable, to globally indicate that "none" is acceptable, then an attacker
then an attacker could provide it with an Unsecured JWS object over could provide it with an Unsecured JWS over HTTP and still have that
HTTP and still have that object successfully validate. Instead, the object successfully validate. Instead, the application needs to
application needs to indicate acceptance of "none" for each object indicate acceptance of "none" for each object received over HTTPS
received over HTTPS (e.g., by setting "acceptUnsecured" to "true" for (e.g., by setting "acceptUnsecured" to "true" for the first
the first hypothetical JWS software library above), but not for each hypothetical JWS software library above), but not for each object
object received over HTTP. received over HTTP.
8.6. Denial of Service Attacks 8.6. Denial of Service Attacks
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
supply content using keys that would result in excessive supply content using 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. Implementations should set and mandated in this specification. Implementations should set and
skipping to change at page 53, line 15 skipping to change at page 53, line 15
[Boneh99] "Twenty years of attacks on the RSA cryptosystem", Notices [Boneh99] "Twenty years of attacks on the RSA cryptosystem", Notices
of the American Mathematical Society (AMS), Vol. 46, No. of the American Mathematical Society (AMS), Vol. 46, No.
2, pp. 203-213 http://crypto.stanford.edu/~dabo/pubs/ 2, pp. 203-213 http://crypto.stanford.edu/~dabo/pubs/
papers/RSA-survey.pdf, 1999. papers/RSA-survey.pdf, 1999.
[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. and J. Hildebrand, "JSON Web Encryption (JWE)", [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
draft-ietf-jose-json-web-encryption (work in progress), draft-ietf-jose-json-web-encryption (work in progress),
November 2014. December 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),
November 2014. December 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), November 2014. in progress), December 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 55, line 4 skipping to change at page 55, line 4
10.2. Informative References 10.2. Informative References
[CanvasApp] [CanvasApp]
Facebook, "Canvas Applications", 2010. Facebook, "Canvas Applications", 2010.
[I-D.ietf-precis-saslprepbis] [I-D.ietf-precis-saslprepbis]
Saint-Andre, P. and A. Melnikov, "Preparation, Saint-Andre, P. and A. Melnikov, "Preparation,
Enforcement, and Comparison of Internationalized Strings Enforcement, and Comparison of Internationalized Strings
Representing Usernames and Passwords", Representing Usernames and Passwords",
draft-ietf-precis-saslprepbis-09 (work in progress), draft-ietf-precis-saslprepbis-12 (work in progress),
October 2014. December 2014.
[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-05 (work in progress), draft-mcgrew-aead-aes-cbc-hmac-sha2-05 (work in progress),
July 2014. July 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)
skipping to change at page 63, line 13 skipping to change at page 63, line 13
2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5
Appendix C. Example ECDH-ES Key Agreement Computation Appendix C. Example ECDH-ES Key Agreement Computation
This example uses ECDH-ES Key Agreement and the Concat KDF to derive This example uses ECDH-ES Key Agreement and the Concat KDF to derive
the Content Encryption Key (CEK) in the manner described in the Content Encryption Key (CEK) in the manner described in
Section 4.6. In this example, the ECDH-ES Direct Key Agreement mode Section 4.6. In this example, the ECDH-ES Direct Key Agreement mode
("alg" value "ECDH-ES") is used to produce an agreed upon key for AES ("alg" value "ECDH-ES") is used to produce an agreed upon key for AES
GCM with a 128 bit key ("enc" value "A128GCM"). GCM with a 128 bit key ("enc" value "A128GCM").
In this example, a sender Alice is encrypting content to a recipient In this example, a producer Alice is encrypting content to a consumer
Bob. The sender (Alice) generates an ephemeral key for the key Bob. The producer (Alice) generates an ephemeral key for the key
agreement computation. Alice's ephemeral key (in JWK format) used agreement computation. Alice's ephemeral key (in JWK format) used
for the key agreement computation in this example (including the for the key agreement computation in this example (including the
private part) is: private part) is:
{"kty":"EC", {"kty":"EC",
"crv":"P-256", "crv":"P-256",
"x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0", "x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0",
"y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps", "y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps",
"d":"0_NxaRPUMQoAJt50Gz8YiTr8gRTwyEaCumd-MToTmIo" "d":"0_NxaRPUMQoAJt50Gz8YiTr8gRTwyEaCumd-MToTmIo"
} }
The recipient's (Bob's) key (in JWK format) used for the key The consumer's (Bob's) key (in JWK format) used for the key agreement
agreement computation in this example (including the private part) computation in this example (including the private part) is:
is:
{"kty":"EC", {"kty":"EC",
"crv":"P-256", "crv":"P-256",
"x":"weNJy2HscCSM6AEDTDg04biOvhFhyyWvOHQfeF_PxMQ", "x":"weNJy2HscCSM6AEDTDg04biOvhFhyyWvOHQfeF_PxMQ",
"y":"e8lnCO-AlStT-NJVX-crhB7QRYhiix03illJOVAOyck", "y":"e8lnCO-AlStT-NJVX-crhB7QRYhiix03illJOVAOyck",
"d":"VEmDZpDXXK8p8N0Cndsxs924q6nS1RXFASRl6BfUqdw" "d":"VEmDZpDXXK8p8N0Cndsxs924q6nS1RXFASRl6BfUqdw"
} }
Header Parameter values used in this example are as follows. In this Header Parameter values used in this example are as follows. In this
example, the "apu" (agreement PartyUInfo) parameter value is the example, the "apu" (agreement PartyUInfo) parameter value is the
base64url encoding of the UTF-8 string "Alice" and the "apv" base64url encoding of the UTF-8 string "Alice" and the "apv"
(agreement PartyVInfo) parameter value is the base64url encoding of (agreement PartyVInfo) parameter value is the base64url encoding of
the UTF-8 string "Bob". The "epk" parameter is used to communicate the UTF-8 string "Bob". The "epk" parameter is used to communicate
the sender's (Alice's) ephemeral public key value to the recipient the producer's (Alice's) ephemeral public key value to the consumer
(Bob). (Bob).
{"alg":"ECDH-ES", {"alg":"ECDH-ES",
"enc":"A128GCM", "enc":"A128GCM",
"apu":"QWxpY2U", "apu":"QWxpY2U",
"apv":"Qm9i", "apv":"Qm9i",
"epk": "epk":
{"kty":"EC", {"kty":"EC",
"crv":"P-256", "crv":"P-256",
"x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0", "x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0",
skipping to change at page 66, line 29 skipping to change at page 66, line 29
Jim Schaad, Hannes Tschofenig, and Sean Turner. 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, Stephen Farrell, and Kathleen Moriarty served as Sean Turner, Stephen Farrell, and Kathleen Moriarty served as
Security area directors during the creation of this specification. Security area directors 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 ]]
-38
o Require discarding private keys with an "oth" parameter when the
implementation does not support private keys with more than two
primes.
o Replaced uses of the phrases "JWS object" and "JWE object" with
"JWS" and "JWE".
-37 -37
o Restricted algorithm names to using only ASCII characters. o Restricted algorithm names to using only ASCII characters.
o Added language about ignoring private keys with an "oth" parameter o Added language about ignoring private keys with an "oth" parameter
when the implementation does not support private keys with more when the implementation does not support private keys with more
than two primes. than two primes.
o Updated the example IANA registration request subject line. o Updated the example IANA registration request subject line.
 End of changes. 18 change blocks. 
46 lines changed or deleted 53 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/