draft-ietf-jose-json-web-signature-32.txt   draft-ietf-jose-json-web-signature-33.txt 
JOSE Working Group M. Jones JOSE Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track J. Bradley Intended status: Standards Track J. Bradley
Expires: March 27, 2015 Ping Identity Expires: March 29, 2015 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
September 23, 2014 September 25, 2014
JSON Web Signature (JWS) JSON Web Signature (JWS)
draft-ietf-jose-json-web-signature-32 draft-ietf-jose-json-web-signature-33
Abstract Abstract
JSON Web Signature (JWS) represents content secured with digital JSON Web Signature (JWS) represents content secured with digital
signatures or Message Authentication Codes (MACs) using JavaScript signatures or Message Authentication Codes (MACs) using JavaScript
Object Notation (JSON) based data structures. Cryptographic Object Notation (JSON) based data structures. Cryptographic
algorithms and identifiers for use with this specification are algorithms and identifiers for use with this specification are
described in the separate JSON Web Algorithms (JWA) specification and described in the separate JSON Web Algorithms (JWA) specification and
an IANA registry defined by that specification. Related encryption an IANA registry defined by that specification. Related encryption
capabilities are described in the separate JSON Web Encryption (JWE) capabilities are described in the separate JSON Web Encryption (JWE)
skipping to change at page 1, line 40 skipping to change at page 1, line 40
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 March 27, 2015. This Internet-Draft will expire on March 29, 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 2, line 31 skipping to change at page 2, line 31
4.1. Registered Header Parameter Names . . . . . . . . . . . . 9 4.1. Registered Header Parameter Names . . . . . . . . . . . . 9
4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 10 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 10
4.1.2. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 10 4.1.2. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 10
4.1.3. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 10 4.1.3. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 10
4.1.4. "kid" (Key ID) Header Parameter . . . . . . . . . . . 10 4.1.4. "kid" (Key ID) Header Parameter . . . . . . . . . . . 10
4.1.5. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 11 4.1.5. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 11
4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter . . . 11 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter . . . 11
4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header 4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header
Parameter . . . . . . . . . . . . . . . . . . . . . . 11 Parameter . . . . . . . . . . . . . . . . . . . . . . 11
4.1.8. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) 4.1.8. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint)
Header Parameter . . . . . . . . . . . . . . . . . . . 11 Header Parameter . . . . . . . . . . . . . . . . . . . 12
4.1.9. "typ" (Type) Header Parameter . . . . . . . . . . . . 12 4.1.9. "typ" (Type) Header Parameter . . . . . . . . . . . . 12
4.1.10. "cty" (Content Type) Header Parameter . . . . . . . . 12 4.1.10. "cty" (Content Type) Header Parameter . . . . . . . . 12
4.1.11. "crit" (Critical) Header Parameter . . . . . . . . . . 13 4.1.11. "crit" (Critical) Header Parameter . . . . . . . . . . 13
4.2. Public Header Parameter Names . . . . . . . . . . . . . . 14 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 14
4.3. Private Header Parameter Names . . . . . . . . . . . . . 14 4.3. Private Header Parameter Names . . . . . . . . . . . . . 14
5. Producing and Consuming JWSs . . . . . . . . . . . . . . . . . 14 5. Producing and Consuming JWSs . . . . . . . . . . . . . . . . . 14
5.1. Message Signature or MAC Computation . . . . . . . . . . 14 5.1. Message Signature or MAC Computation . . . . . . . . . . 14
5.2. Message Signature or MAC Validation . . . . . . . . . . . 15 5.2. Message Signature or MAC Validation . . . . . . . . . . . 15
5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 16 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 17
6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 17 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 17
7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 17 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 17
7.1. JWS Compact Serialization . . . . . . . . . . . . . . . . 18 7.1. JWS Compact Serialization . . . . . . . . . . . . . . . . 18
7.2. JWS JSON Serialization . . . . . . . . . . . . . . . . . 18 7.2. JWS JSON Serialization . . . . . . . . . . . . . . . . . 18
8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 20 8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 20
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20
9.1. JSON Web Signature and Encryption Header Parameters 9.1. JSON Web Signature and Encryption Header Parameters
Registry . . . . . . . . . . . . . . . . . . . . . . . . 21 Registry . . . . . . . . . . . . . . . . . . . . . . . . 21
9.1.1. Registration Template . . . . . . . . . . . . . . . . 22 9.1.1. Registration Template . . . . . . . . . . . . . . . . 22
9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 22 9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 22
skipping to change at page 3, line 25 skipping to change at page 3, line 25
10.8. Chosen Plaintext Attacks . . . . . . . . . . . . . . . . 28 10.8. Chosen Plaintext Attacks . . . . . . . . . . . . . . . . 28
10.9. Timing Attacks . . . . . . . . . . . . . . . . . . . . . 28 10.9. Timing Attacks . . . . . . . . . . . . . . . . . . . . . 28
10.10. Replay Protection . . . . . . . . . . . . . . . . . . . . 28 10.10. Replay Protection . . . . . . . . . . . . . . . . . . . . 28
10.11. SHA-1 Certificate Thumbprints . . . . . . . . . . . . . . 28 10.11. SHA-1 Certificate Thumbprints . . . . . . . . . . . . . . 28
10.12. JSON Security Considerations . . . . . . . . . . . . . . 28 10.12. JSON Security Considerations . . . . . . . . . . . . . . 28
10.13. Unicode Comparison Security Considerations . . . . . . . 29 10.13. Unicode Comparison Security Considerations . . . . . . . 29
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 30 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 30
11.1. Normative References . . . . . . . . . . . . . . . . . . 30 11.1. Normative References . . . . . . . . . . . . . . . . . . 30
11.2. Informative References . . . . . . . . . . . . . . . . . 31 11.2. Informative References . . . . . . . . . . . . . . . . . 31
Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 32 Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 32
A.1. Example JWS using HMAC SHA-256 . . . . . . . . . . . . . 32 A.1. Example JWS using HMAC SHA-256 . . . . . . . . . . . . . 33
A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 33 A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 33
A.1.2. Validating . . . . . . . . . . . . . . . . . . . . . . 35 A.1.2. Validating . . . . . . . . . . . . . . . . . . . . . . 35
A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 . . . . . . . 35 A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 . . . . . . . 35
A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 35 A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 35
A.2.2. Validating . . . . . . . . . . . . . . . . . . . . . . 38 A.2.2. Validating . . . . . . . . . . . . . . . . . . . . . . 38
A.3. Example JWS using ECDSA P-256 SHA-256 . . . . . . . . . . 38 A.3. Example JWS using ECDSA P-256 SHA-256 . . . . . . . . . . 38
A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 38 A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 38
A.3.2. Validating . . . . . . . . . . . . . . . . . . . . . . 40 A.3.2. Validating . . . . . . . . . . . . . . . . . . . . . . 40
A.4. Example JWS using ECDSA P-521 SHA-512 . . . . . . . . . . 41 A.4. Example JWS using ECDSA P-521 SHA-512 . . . . . . . . . . 41
A.4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 41 A.4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 41
skipping to change at page 11, line 46 skipping to change at page 11, line 46
signature if any validation failure occurs. Use of this Header signature if any validation failure occurs. Use of this Header
Parameter is OPTIONAL. Parameter is OPTIONAL.
See Appendix B for an example "x5c" value. See Appendix B for an example "x5c" value.
4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter 4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter
The "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter is a The "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter is a
base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER
encoding of the X.509 certificate [RFC5280] corresponding to the key encoding of the X.509 certificate [RFC5280] corresponding to the key
used to digitally sign the JWS. Use of this Header Parameter is used to digitally sign the JWS. Note that certificate thumbprints
OPTIONAL. are also sometimes known as certificate fingerprints. Use of this
Header Parameter is OPTIONAL.
4.1.8. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header 4.1.8. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header
Parameter Parameter
The "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header The "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header
Parameter is a base64url encoded SHA-256 thumbprint (a.k.a. digest) Parameter is a base64url encoded SHA-256 thumbprint (a.k.a. digest)
of the DER encoding of the X.509 certificate [RFC5280] corresponding of the DER encoding of the X.509 certificate [RFC5280] corresponding
to the key used to digitally sign the JWS. Use of this Header to the key used to digitally sign the JWS. Note that certificate
Parameter is OPTIONAL. thumbprints are also sometimes known as certificate fingerprints.
Use of this Header Parameter is OPTIONAL.
4.1.9. "typ" (Type) Header Parameter 4.1.9. "typ" (Type) Header Parameter
The "typ" (type) Header Parameter is used by JWS applications to The "typ" (type) Header Parameter is used by JWS applications to
declare the MIME Media Type [IANA.MediaTypes] of this complete JWS declare the MIME Media Type [IANA.MediaTypes] of this complete JWS
object. This is intended for use by the application when more than object. This is intended for use by the application when more than
one kind of object could be present in an application data structure one kind of object could be present in an application data structure
that can contain a JWS object; the application can use this value to that can contain a JWS object; the application can use this value to
disambiguate among the different kinds of objects that might be disambiguate among the different kinds of objects that might be
present. It will typically not be used by applications when the kind present. It will typically not be used by applications when the kind
skipping to change at page 20, line 36 skipping to change at page 20, line 36
implemented will vary over time, and depend on the widespread implemented will vary over time, and depend on the widespread
deployment and known security vulnerabilities at the time of deployment and known security vulnerabilities at the time of
implementation. At the time of this writing, TLS version 1.2 implementation. At the time of this writing, TLS version 1.2
[RFC5246] is the most recent version. [RFC5246] is the most recent version.
To protect against information disclosure and tampering, To protect against information disclosure and tampering,
confidentiality protection MUST be applied using TLS with a confidentiality protection MUST be applied using TLS with a
ciphersuite that provides confidentiality and integrity protection. ciphersuite that provides confidentiality and integrity protection.
See current publications by the IETF TLS working group, including RFC See current publications by the IETF TLS working group, including RFC
6176 [RFC6176], for guidance on the ciphersuites currently considered 6176 [RFC6176], for guidance on the ciphersuites currently considered
to be appropriate for use. to be appropriate for use. Also, see Recommendations for Secure Use
of TLS and DTLS [I-D.ietf-uta-tls-bcp] for recommendations on
improving the security of software and services using TLS.
Whenever TLS is used, the identity of the service provider encoded in Whenever TLS is used, the identity of the service provider encoded in
the TLS server certificate MUST be verified using the procedures the TLS server certificate MUST be verified using the procedures
described in Section 6 of RFC 6125 [RFC6125]. described in Section 6 of RFC 6125 [RFC6125].
9. IANA Considerations 9. IANA Considerations
The following registration procedure is used for all the registries The following registration procedure is used for all the registries
established by this specification. established by this specification.
Values are registered on a Specification Required [RFC5226] basis Values are registered on a Specification Required [RFC5226] basis
after a two-week review period on the [TBD]@ietf.org mailing list, on after a three-week review period on the [TBD]@ietf.org mailing list,
the advice of one or more Designated Experts. However, to allow for on the advice of one or more Designated Experts. However, to allow
the allocation of values prior to publication, the Designated for the allocation of values prior to publication, the Designated
Expert(s) may approve registration once they are satisfied that such Expert(s) may approve registration once they are satisfied that such
a specification will be published. a specification will be published.
Registration requests must be sent to the [TBD]@ietf.org mailing list Registration requests must be sent to the [TBD]@ietf.org mailing list
for review and comment, with an appropriate subject (e.g., "Request for review and comment, with an appropriate subject (e.g., "Request
for access token type: example"). [[ Note to the RFC Editor: The name for access token type: example"). [[ Note to the RFC Editor: The name
of the mailing list should be determined in consultation with the of the mailing list should be determined in consultation with the
IESG and IANA. Suggested name: jose-reg-review. ]] IESG and IANA. Suggested name: jose-reg-review. ]]
Within the review period, the Designated Expert(s) will either Within the review period, the Designated Expert(s) will either
skipping to change at page 31, line 37 skipping to change at page 31, line 37
[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.
11.2. Informative References 11.2. Informative References
[CanvasApp] [CanvasApp]
Facebook, "Canvas Applications", 2010. Facebook, "Canvas Applications", 2010.
[I-D.ietf-uta-tls-bcp]
Sheffer, Y., Holz, R., and P. Saint-Andre,
"Recommendations for Secure Use of TLS and DTLS",
draft-ietf-uta-tls-bcp-03 (work in progress),
September 2014.
[JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign",
September 2010. September 2010.
[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),
September 2014. September 2014.
[JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", draft-ietf-oauth-json-web-token (work in (JWT)", draft-ietf-oauth-json-web-token (work in
progress), September 2014. progress), September 2014.
skipping to change at page 52, line 14 skipping to change at page 52, line 14
Thanks to Axel Nennker for his early implementation and feedback on Thanks to Axel Nennker for his early implementation and feedback on
the JWS and JWE specifications. the JWS and JWE specifications.
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, Brian Campbell, Breno de Medeiros, Dick Dirk Balfanz, Richard Barnes, Brian Campbell, Breno de Medeiros, Dick
Hardt, Joe Hildebrand, Jeff Hodges, Edmund Jay, Yaron Y. Goland, Ben Hardt, Joe Hildebrand, Jeff Hodges, Russ Housley, Edmund Jay, Tero
Laurie, James Manger, Matt Miller, Kathleen Moriarty, Tony Nadalin, Kivinen, Yaron Y. Goland, Ben Laurie, James Manger, Matt Miller,
Hideki Nara, Axel Nennker, John Panzer, Emmanuel Raviart, Eric Kathleen Moriarty, Tony Nadalin, Hideki Nara, Axel Nennker, John
Rescorla, Jim Schaad, Paul Tarjan, Hannes Tschofenig, and Sean Panzer, Emmanuel Raviart, Eric Rescorla, Jim Schaad, Paul Tarjan,
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, 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 H. Document History Appendix H. 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 ]]
-33
o Noted that certificate thumbprints are also sometimes known as
certificate fingerprints.
o Added an informative reference to draft-ietf-uta-tls-bcp for
recommendations on improving the security of software and services
using TLS.
o Changed the registration review period to three weeks.
o Acknowledged additional contributors.
-32 -32
o Addressed Gen-ART review comments by Russ Housley. o Addressed Gen-ART review comments by Russ Housley.
o Addressed secdir review comments by Tero Kivinen, Stephen Kent, o Addressed secdir review comments by Tero Kivinen, Stephen Kent,
and Scott Kelly. and Scott Kelly.
o Replaced the term Plaintext JWS with Unsecured JWS. o Replaced the term Plaintext JWS with Unsecured JWS.
-31 -31
 End of changes. 14 change blocks. 
20 lines changed or deleted 43 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/