draft-ietf-jose-json-web-signature-25.txt   draft-ietf-jose-json-web-signature-26.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: October 2, 2014 Ping Identity Expires: November 1, 2014 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
March 31, 2014 April 30, 2014
JSON Web Signature (JWS) JSON Web Signature (JWS)
draft-ietf-jose-json-web-signature-25 draft-ietf-jose-json-web-signature-26
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 October 2, 2014. This Internet-Draft will expire on November 1, 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 3, line 15 skipping to change at page 3, line 15
10.3. Unicode Comparison Security Considerations . . . . . . . . 26 10.3. Unicode Comparison Security Considerations . . . . . . . . 26
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26
11.1. Normative References . . . . . . . . . . . . . . . . . . . 26 11.1. Normative References . . . . . . . . . . . . . . . . . . . 26
11.2. Informative References . . . . . . . . . . . . . . . . . . 28 11.2. Informative References . . . . . . . . . . . . . . . . . . 28
Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 28 Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 28
A.1. Example JWS using HMAC SHA-256 . . . . . . . . . . . . . . 29 A.1. Example JWS using HMAC SHA-256 . . . . . . . . . . . . . . 29
A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 29 A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 29
A.1.2. Validating . . . . . . . . . . . . . . . . . . . . . . 31 A.1.2. Validating . . . . . . . . . . . . . . . . . . . . . . 31
A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 . . . . . . . . 31 A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 . . . . . . . . 31
A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 31 A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 31
A.2.2. Validating . . . . . . . . . . . . . . . . . . . . . . 33 A.2.2. Validating . . . . . . . . . . . . . . . . . . . . . . 34
A.3. Example JWS using ECDSA P-256 SHA-256 . . . . . . . . . . 34 A.3. Example JWS using ECDSA P-256 SHA-256 . . . . . . . . . . 34
A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 34 A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 34
A.3.2. Validating . . . . . . . . . . . . . . . . . . . . . . 36 A.3.2. Validating . . . . . . . . . . . . . . . . . . . . . . 36
A.4. Example JWS using ECDSA P-521 SHA-512 . . . . . . . . . . 36 A.4. Example JWS using ECDSA P-521 SHA-512 . . . . . . . . . . 37
A.4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 36 A.4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 37
A.4.2. Validating . . . . . . . . . . . . . . . . . . . . . . 38 A.4.2. Validating . . . . . . . . . . . . . . . . . . . . . . 39
A.5. Example Plaintext JWS . . . . . . . . . . . . . . . . . . 38 A.5. Example Plaintext JWS . . . . . . . . . . . . . . . . . . 39
A.6. Example JWS Using JWS JSON Serialization . . . . . . . . . 39 A.6. Example JWS Using JWS JSON Serialization . . . . . . . . . 40
A.6.1. JWS Per-Signature Protected Headers . . . . . . . . . 40 A.6.1. JWS Per-Signature Protected Headers . . . . . . . . . 40
A.6.2. JWS Per-Signature Unprotected Headers . . . . . . . . 40 A.6.2. JWS Per-Signature Unprotected Headers . . . . . . . . 41
A.6.3. Complete JWS Header Values . . . . . . . . . . . . . . 40 A.6.3. Complete JWS Header Values . . . . . . . . . . . . . . 41
A.6.4. Complete JWS JSON Serialization Representation . . . . 41 A.6.4. Complete JWS JSON Serialization Representation . . . . 41
Appendix B. "x5c" (X.509 Certificate Chain) Example . . . . . . . 41 Appendix B. "x5c" (X.509 Certificate Chain) Example . . . . . . . 42
Appendix C. Notes on implementing base64url encoding without Appendix C. Notes on implementing base64url encoding without
padding . . . . . . . . . . . . . . . . . . . . . . . 43 padding . . . . . . . . . . . . . . . . . . . . . . . 44
Appendix D. Notes on Key Selection . . . . . . . . . . . . . . . 44 Appendix D. Notes on Key Selection . . . . . . . . . . . . . . . 45
Appendix E. Negative Test Case for "crit" Header Parameter . . . 46 Appendix E. Negative Test Case for "crit" Header Parameter . . . 46
Appendix F. Detached Content . . . . . . . . . . . . . . . . . . 46 Appendix F. Detached Content . . . . . . . . . . . . . . . . . . 47
Appendix G. Acknowledgements . . . . . . . . . . . . . . . . . . 47 Appendix G. Acknowledgements . . . . . . . . . . . . . . . . . . 47
Appendix H. Document History . . . . . . . . . . . . . . . . . . 47 Appendix H. Document History . . . . . . . . . . . . . . . . . . 48
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 55 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 56
1. Introduction 1. Introduction
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) [RFC7159] based data structures. The JWS Object Notation (JSON) [RFC7159] based data structures. The JWS
cryptographic mechanisms provide integrity protection for an cryptographic mechanisms provide integrity protection for an
arbitrary sequence of octets. arbitrary sequence of octets.
Two closely related serializations for JWS objects are defined. The Two closely related serializations for JWS objects are defined. The
skipping to change at page 10, line 33 skipping to change at page 10, line 33
4.1.2. "jku" (JWK Set URL) Header Parameter 4.1.2. "jku" (JWK Set URL) Header Parameter
The "jku" (JWK Set URL) Header Parameter is a URI [RFC3986] that The "jku" (JWK Set URL) Header Parameter is a URI [RFC3986] that
refers to a resource for a set of JSON-encoded public keys, one of refers to a resource for a set of JSON-encoded public keys, one of
which corresponds to the key used to digitally sign the JWS. The which corresponds to the key used to digitally sign the JWS. The
keys MUST be encoded as a JSON Web Key Set (JWK Set) [JWK]. The keys MUST be encoded as a JSON Web Key Set (JWK Set) [JWK]. The
protocol used to acquire the resource MUST provide integrity protocol used to acquire the resource MUST provide integrity
protection; an HTTP GET request to retrieve the JWK Set MUST use TLS protection; an HTTP GET request to retrieve the JWK Set MUST use TLS
[RFC2818] [RFC5246]; the identity of the server MUST be validated, as [RFC2818] [RFC5246]; the identity of the server MUST be validated, as
per Section 3.1 of HTTP Over TLS [RFC2818]. Use of this Header per Section 6 of RFC 6125 [RFC6125]. Use of this Header Parameter is
Parameter is OPTIONAL. OPTIONAL.
4.1.3. "jwk" (JSON Web Key) Header Parameter 4.1.3. "jwk" (JSON Web Key) Header Parameter
The "jwk" (JSON Web Key) Header Parameter is the public key that The "jwk" (JSON Web Key) Header Parameter is the public key that
corresponds to the key used to digitally sign the JWS. This key is corresponds to the key used to digitally sign the JWS. This key is
represented as a JSON Web Key [JWK]. Use of this Header Parameter is represented as a JSON Web Key [JWK]. Use of this Header Parameter is
OPTIONAL. OPTIONAL.
4.1.4. "kid" (Key ID) Header Parameter 4.1.4. "kid" (Key ID) Header Parameter
skipping to change at page 11, line 19 skipping to change at page 11, line 19
chain [RFC5280] corresponding to the key used to digitally sign the chain [RFC5280] corresponding to the key used to digitally sign the
JWS. The identified resource MUST provide a representation of the JWS. The identified resource MUST provide a representation of the
certificate or certificate chain that conforms to RFC 5280 [RFC5280] certificate or certificate chain that conforms to RFC 5280 [RFC5280]
in PEM encoded form [RFC1421]. The certificate containing the public in PEM encoded form [RFC1421]. The certificate containing the public
key corresponding to the key used to digitally sign the JWS MUST be key corresponding to the key used to digitally sign the JWS MUST be
the first certificate. This MAY be followed by additional the first certificate. This MAY be followed by additional
certificates, with each subsequent certificate being the one used to certificates, with each subsequent certificate being the one used to
certify the previous one. The protocol used to acquire the resource certify the previous one. The protocol used to acquire the resource
MUST provide integrity protection; an HTTP GET request to retrieve MUST provide integrity protection; an HTTP GET request to retrieve
the certificate MUST use TLS [RFC2818] [RFC5246]; the identity of the the certificate MUST use TLS [RFC2818] [RFC5246]; the identity of the
server MUST be validated, as per Section 3.1 of HTTP Over TLS server MUST be validated, as per Section 6 of RFC 6125 [RFC6125].
[RFC2818]. Use of this Header Parameter is OPTIONAL. Use of this Header Parameter is OPTIONAL.
4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter
The "x5c" (X.509 Certificate Chain) Header Parameter contains the The "x5c" (X.509 Certificate Chain) Header Parameter contains the
X.509 public key certificate or certificate chain [RFC5280] X.509 public key certificate or certificate chain [RFC5280]
corresponding to the key used to digitally sign the JWS. The corresponding to the key used to digitally sign the JWS. The
certificate or certificate chain is represented as a JSON array of certificate or certificate chain is represented as a JSON array of
certificate value strings. Each string in the array is a base64 certificate value strings. Each string in the array is a base64
encoded ([RFC4648] Section 4 -- not base64url encoded) DER encoded ([RFC4648] Section 4 -- not base64url encoded) DER
[ITU.X690.1994] PKIX certificate value. The certificate containing [ITU.X690.1994] PKIX certificate value. The certificate containing
skipping to change at page 19, line 40 skipping to change at page 19, line 40
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, but has very limited actual [RFC5246] is the most recent version, but has very limited actual
deployment, and might not be readily available in implementation deployment, and might not be readily available in implementation
toolkits. toolkits.
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.
Whenever TLS is used, a TLS server certificate check MUST be Whenever TLS is used, the identity of the service provider encoded in
performed, per RFC 6125 [RFC6125]. the TLS server certificate MUST be verified using the procedures
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 with a Specification Required [RFC5226] after a Values are registered with a Specification Required [RFC5226] after a
two-week review period on the [TBD]@ietf.org mailing list, on the two-week review period on the [TBD]@ietf.org mailing list, on the
advice of one or more Designated Experts. However, to allow for the advice of one or more Designated Experts. However, to allow for the
allocation of values prior to publication, the Designated Expert(s) allocation of values prior to publication, the Designated Expert(s)
skipping to change at page 24, line 28 skipping to change at page 24, line 28
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 concerns are listed here. some significant concerns are listed here.
All the security considerations in XML DSIG 2.0 All the security considerations in XML DSIG 2.0
[W3C.CR-xmldsig-core2-20120124], also apply to this specification, [W3C.NOTE-xmldsig-core2-20130411], also apply to this specification,
other than those that are XML specific. Likewise, many of the best other than those that are XML specific. Likewise, many of the best
practices documented in XML Signature Best Practices practices documented in XML Signature Best Practices
[W3C.WD-xmldsig-bestpractices-20110809] also apply to this [W3C.NOTE-xmldsig-bestpractices-20130411] also apply to this
specification, other than those that are XML specific. specification, other than those that are XML specific.
Keys are only as strong as the amount of entropy used to generate Keys are only as strong as the amount of entropy used to generate
them. A minimum of 128 bits of entropy should be used for all keys, them. A minimum of 128 bits of entropy should be used for all keys,
and depending upon the application context, more may be required. In and depending upon the application context, more may be required. In
particular, it may be difficult to generate sufficiently random particular, it may be difficult to generate sufficiently random
values in some browsers and application environments. values in some browsers and application environments.
Creators of JWSs should not allow third parties to insert arbitrary Creators of JWSs should not allow third parties to insert arbitrary
content into the message without adding entropy not controlled by the content into the message without adding entropy not controlled by the
skipping to change at page 26, line 45 skipping to change at page 26, line 45
[ITU.X690.1994] [ITU.X690.1994]
International Telecommunications Union, "Information International Telecommunications Union, "Information
Technology - ASN.1 encoding rules: Specification of Basic Technology - ASN.1 encoding rules: Specification of Basic
Encoding Rules (BER), Canonical Encoding Rules (CER) and Encoding Rules (BER), Canonical Encoding Rules (CER) and
Distinguished Encoding Rules (DER)", ITU-T Recommendation Distinguished Encoding Rules (DER)", ITU-T Recommendation
X.690, 1994. X.690, 1994.
[JWA] Jones, M., "JSON Web Algorithms (JWA)", [JWA] Jones, M., "JSON Web Algorithms (JWA)",
draft-ietf-jose-json-web-algorithms (work in progress), draft-ietf-jose-json-web-algorithms (work in progress),
March 2014. April 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. April 2014.
[RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic
Mail: Part I: Message Encryption and Authentication Mail: Part I: Message Encryption and Authentication
Procedures", RFC 1421, February 1993. Procedures", RFC 1421, February 1993.
[RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part One: Format of Internet Message Extensions (MIME) Part One: Format of Internet Message
Bodies", RFC 2045, November 1996. Bodies", RFC 2045, November 1996.
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
skipping to change at page 28, line 15 skipping to change at page 28, line 15
11.2. Informative References 11.2. Informative References
[CanvasApp] [CanvasApp]
Facebook, "Canvas Applications", 2010. Facebook, "Canvas Applications", 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.
[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),
March 2014. April 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), March 2014. progress), April 2014.
[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.
[RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally
Unique IDentifier (UUID) URN Namespace", RFC 4122, Unique IDentifier (UUID) URN Namespace", RFC 4122,
July 2005. July 2005.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226, IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008. May 2008.
[W3C.CR-xmldsig-core2-20120124] [W3C.NOTE-xmldsig-bestpractices-20130411]
Cantor, S., Roessler, T., Eastlake, D., Yiu, K., Reagle, Hirsch, F. and P. Datta, "XML Signature Best Practices",
J., Solo, D., Datta, P., and F. Hirsch, "XML Signature World Wide Web Consortium Note NOTE-xmldsig-bestpractices-
Syntax and Processing Version 2.0", World Wide Web 20130411, April 2013, <http://www.w3.org/TR/2013/
Consortium CR CR-xmldsig-core2-20120124, January 2012, NOTE-xmldsig-bestpractices-20130411/>.
<http://www.w3.org/TR/2012/CR-xmldsig-core2-20120124>.
[W3C.WD-xmldsig-bestpractices-20110809] [W3C.NOTE-xmldsig-core2-20130411]
Datta, P. and F. Hirsch, "XML Signature Best Practices", Eastlake, D., Reagle, J., Solo, D., Hirsch, F., Roessler,
World Wide Web Consortium WD WD-xmldsig-bestpractices- T., Yiu, K., Datta, P., and S. Cantor, "XML Signature
20110809, August 2011, <http://www.w3.org/TR/2011/ Syntax and Processing Version 2.0", World Wide Web
WD-xmldsig-bestpractices-20110809>. Consortium Note NOTE-xmldsig-core2-20130411, April 2013,
<http://www.w3.org/TR/2013/NOTE-xmldsig-core2-20130411/>.
Appendix A. JWS Examples Appendix A. JWS Examples
This section provides several examples of JWSs. While the first This section provides several examples of JWSs. While the first
three examples all represent JSON Web Tokens (JWTs) [JWT], the three examples all represent JSON Web Tokens (JWTs) [JWT], the
payload can be any octet sequence, as shown in Appendix A.4. payload can be any octet sequence, as shown in Appendix A.4.
A.1. Example JWS using HMAC SHA-256 A.1. Example JWS using HMAC SHA-256
A.1.1. Encoding A.1.1. Encoding
The following example JWS Protected Header declares that the data The following example JWS Protected Header declares that the data
structure is a JSON Web Token (JWT) [JWT] and the JWS Signing Input structure is a JSON Web Token (JWT) [JWT] and the JWS Signing Input
is secured using the HMAC SHA-256 algorithm. is secured using the HMAC SHA-256 algorithm.
{"typ":"JWT", {"typ":"JWT",
"alg":"HS256"} "alg":"HS256"}
The octets representing UTF8(JWS Protected Header) in this case are: To remove potential ambiguities in the representation of the JSON
object above, the actual octet sequence representing UTF8(JWS
Protected Header) used in this example is also included below. (Note
that ambiguities can arise due to differing platform representations
of line breaks (CRLF versus LF), differing spacing at the beginning
and ends of lines, whether the last line has a terminating line break
or not, and other causes. In the representation used in this
example, the first line has no leading or trailing spaces, a CRLF
line break (13, 10) occurs between the first and second lines, the
second line has one leading space (32) and no trailing spaces, and
the last line does not have a terminating line break.) The octets
representing UTF8(JWS Protected Header) in this example (using JSON
array notation) are:
[123, 34, 116, 121, 112, 34, 58, 34, 74, 87, 84, 34, 44, 13, 10, 32, [123, 34, 116, 121, 112, 34, 58, 34, 74, 87, 84, 34, 44, 13, 10, 32,
34, 97, 108, 103, 34, 58, 34, 72, 83, 50, 53, 54, 34, 125] 34, 97, 108, 103, 34, 58, 34, 72, 83, 50, 53, 54, 34, 125]
Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected
Header)) gives this value: Header)) gives this value:
eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
The JWS Payload used in this example is the octets of the UTF-8 The JWS Payload used in this example is the octets of the UTF-8
representation of the JSON object below. (Note that the payload can representation of the JSON object below. (Note that the payload can
be any base64url encoded octet sequence, and need not be a base64url be any base64url encoded octet sequence, and need not be a base64url
encoded JSON object.) encoded JSON object.)
{"iss":"joe", {"iss":"joe",
"exp":1300819380, "exp":1300819380,
"http://example.com/is_root":true} "http://example.com/is_root":true}
The following octet sequence, which is the UTF-8 representation of The following octet sequence, which is the UTF-8 representation used
the JSON object above, is the JWS Payload: in this example for the JSON object above, is the JWS Payload:
[123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10, [123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10,
32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56, 32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56,
48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97, 48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97,
109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111, 109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111,
111, 116, 34, 58, 116, 114, 117, 101, 125] 111, 116, 34, 58, 116, 114, 117, 101, 125]
Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected
Header)) gives this value (with line breaks for display purposes Header)) gives this value (with line breaks for display purposes
only): only):
skipping to change at page 30, line 12 skipping to change at page 30, line 24
Combining these as BASE64URL(UTF8(JWS Protected Header)) || '.' || Combining these as BASE64URL(UTF8(JWS Protected Header)) || '.' ||
BASE64URL(JWS Payload) gives this string (with line breaks for BASE64URL(JWS Payload) gives this string (with line breaks for
display purposes only): display purposes only):
eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
. .
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
The resulting JWS Signing Input value, which is the ASCII The resulting JWS Signing Input value, which is the ASCII
representation of above string, is the following octet sequence: representation of above string, is the following octet sequence
(using JSON array notation):
[101, 121, 74, 48, 101, 88, 65, 105, 79, 105, 74, 75, 86, 49, 81, [101, 121, 74, 48, 101, 88, 65, 105, 79, 105, 74, 75, 86, 49, 81,
105, 76, 65, 48, 75, 73, 67, 74, 104, 98, 71, 99, 105, 79, 105, 74, 105, 76, 65, 48, 75, 73, 67, 74, 104, 98, 71, 99, 105, 79, 105, 74,
73, 85, 122, 73, 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 73, 85, 122, 73, 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51,
77, 105, 79, 105, 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 77, 105, 79, 105, 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67,
74, 108, 101, 72, 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 74, 108, 101, 72, 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84,
107, 122, 79, 68, 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 107, 122, 79, 68, 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100,
72, 65, 54, 76, 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 72, 65, 54, 76, 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76,
109, 78, 118, 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 109, 78, 118, 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73,
106, 112, 48, 99, 110, 86, 108, 102, 81] 106, 112, 48, 99, 110, 86, 108, 102, 81]
skipping to change at page 31, line 18 skipping to change at page 31, line 27
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
. .
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
A.1.2. Validating A.1.2. Validating
Since the "alg" Header Parameter is "HS256", we validate the HMAC Since the "alg" Header Parameter is "HS256", we validate the HMAC
SHA-256 value contained in the JWS Signature. SHA-256 value contained in the JWS Signature.
To validate the HMAC value, we repeat the previous process of using To validate the HMAC value, we repeat the previous process of using
the correct key and the JWS Signing Input as input to the HMAC SHA- the correct key and the JWS Signing Input (which is the initial
256 function and then taking the output and determining if it matches substring of the JWS Compact Serialization representation up until
the JWS Signature. If it matches exactly, the HMAC has been but not including the second period character) as input to the HMAC
validated. SHA-256 function and then taking the output and determining if it
matches the JWS Signature (which is base64url decoded from the value
encoded in the JWS representation). If it matches exactly, the HMAC
has been validated.
A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256
A.2.1. Encoding A.2.1. Encoding
The JWS Protected Header in this example is different from the The JWS Protected Header in this example is different from the
previous example in two ways: First, because a different algorithm is previous example in two ways: First, because a different algorithm is
being used, the "alg" value is different. Second, for illustration being used, the "alg" value is different. Second, for illustration
purposes only, the optional "typ" parameter is not used. (This purposes only, the optional "typ" parameter is not used. (This
difference is not related to the algorithm employed.) The JWS difference is not related to the algorithm employed.) The JWS
Protected Header used is: Protected Header used is:
{"alg":"RS256"} {"alg":"RS256"}
The octets representing UTF8(JWS Protected Header) in this case are: The octets representing UTF8(JWS Protected Header) in this example
(using JSON array notation) are:
[123, 34, 97, 108, 103, 34, 58, 34, 82, 83, 50, 53, 54, 34, 125] [123, 34, 97, 108, 103, 34, 58, 34, 82, 83, 50, 53, 54, 34, 125]
Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected
Header)) gives this value: Header)) gives this value:
eyJhbGciOiJSUzI1NiJ9 eyJhbGciOiJSUzI1NiJ9
The JWS Payload used in this example, which follows, is the same as The JWS Payload used in this example, which follows, is the same as
in the previous example. Since the BASE64URL(JWS Payload) value will in the previous example. Since the BASE64URL(JWS Payload) value will
therefore be the same, its computation is not repeated here. therefore be the same, its computation is not repeated here.
{"iss":"joe", {"iss":"joe",
skipping to change at page 34, line 5 skipping to change at page 34, line 28
BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K
0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqv 0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqv
hJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrB hJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrB
p0igcN_IoypGlUPQGe77Rw p0igcN_IoypGlUPQGe77Rw
A.2.2. Validating A.2.2. Validating
Since the "alg" Header Parameter is "RS256", we validate the RSASSA- Since the "alg" Header Parameter is "RS256", we validate the RSASSA-
PKCS-v1_5 SHA-256 digital signature contained in the JWS Signature. PKCS-v1_5 SHA-256 digital signature contained in the JWS Signature.
Validating the JWS Signature is a little different from the previous Validating the JWS Signature is a bit different from the previous
example. We pass (n, e), JWS Signature, and the JWS Signing Input to example. We pass the public key (n, e), the JWS Signature (which is
an RSASSA-PKCS-v1_5 signature verifier that has been configured to base64url decoded from the value encoded in the JWS representation),
use the SHA-256 hash function. and the JWS Signing Input (which is the initial substring of the JWS
Compact Serialization representation up until but not including the
second period character) to an RSASSA-PKCS-v1_5 signature verifier
that has been configured to use the SHA-256 hash function.
A.3. Example JWS using ECDSA P-256 SHA-256 A.3. Example JWS using ECDSA P-256 SHA-256
A.3.1. Encoding A.3.1. Encoding
The JWS Protected Header for this example differs from the previous The JWS Protected Header for this example differs from the previous
example because a different algorithm is being used. The JWS example because a different algorithm is being used. The JWS
Protected Header used is: Protected Header used is:
{"alg":"ES256"} {"alg":"ES256"}
The octets representing UTF8(JWS Protected Header) in this case are: The octets representing UTF8(JWS Protected Header) in this example
(using JSON array notation) are:
[123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 50, 53, 54, 34, 125] [123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 50, 53, 54, 34, 125]
Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected
Header)) gives this value: Header)) gives this value:
eyJhbGciOiJFUzI1NiJ9 eyJhbGciOiJFUzI1NiJ9
The JWS Payload used in this example, which follows, is the same as The JWS Payload used in this example, which follows, is the same as
in the previous examples. Since the BASE64URL(JWS Payload) value in the previous examples. Since the BASE64URL(JWS Payload) value
skipping to change at page 36, line 18 skipping to change at page 36, line 43
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
. .
DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSA DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSA
pmWQxfKTUJqPP3-Kg6NU1Q pmWQxfKTUJqPP3-Kg6NU1Q
A.3.2. Validating A.3.2. Validating
Since the "alg" Header Parameter is "ES256", we validate the ECDSA Since the "alg" Header Parameter is "ES256", we validate the ECDSA
P-256 SHA-256 digital signature contained in the JWS Signature. P-256 SHA-256 digital signature contained in the JWS Signature.
Validating the JWS Signature is a little different from the first Validating the JWS Signature is a bit different from the previous
example. We need to split the 64 member octet sequence of the JWS examples. We need to split the 64 member octet sequence of the JWS
Signature into two 32 octet sequences, the first R and the second S. Signature (which is base64url decoded from the value encoded in the
We then pass (x, y), (R, S) and the JWS Signing Input to an ECDSA JWS representation) into two 32 octet sequences, the first
signature verifier that has been configured to use the P-256 curve representing R and the second S. We then pass the public key (x, y),
with the SHA-256 hash function. the signature (R, S), and the JWS Signing Input (which is the initial
substring of the JWS Compact Serialization representation up until
but not including the second period character) to an ECDSA signature
verifier that has been configured to use the P-256 curve with the
SHA-256 hash function.
A.4. Example JWS using ECDSA P-521 SHA-512 A.4. Example JWS using ECDSA P-521 SHA-512
A.4.1. Encoding A.4.1. Encoding
The JWS Protected Header for this example differs from the previous The JWS Protected Header for this example differs from the previous
example because different ECDSA curves and hash functions are used. example because different ECDSA curves and hash functions are used.
The JWS Protected Header used is: The JWS Protected Header used is:
{"alg":"ES512"} {"alg":"ES512"}
The octets representing UTF8(JWS Protected Header) in this case are: The octets representing UTF8(JWS Protected Header) in this example
(using JSON array notation) are:
[123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 53, 49, 50, 34, 125] [123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 53, 49, 50, 34, 125]
Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected
Header)) gives this value: Header)) gives this value:
eyJhbGciOiJFUzUxMiJ9 eyJhbGciOiJFUzUxMiJ9
The JWS Payload used in this example, is the ASCII string "Payload". The JWS Payload used in this example, is the ASCII string "Payload".
The representation of this string is the octet sequence: The representation of this string is the octet sequence:
skipping to change at page 38, line 38 skipping to change at page 39, line 18
. .
AdwMgeerwtHoh-l192l60hp9wAHZFVJbLfD_UxMi70cwnZOYaRI1bKPWROc-mZZq AdwMgeerwtHoh-l192l60hp9wAHZFVJbLfD_UxMi70cwnZOYaRI1bKPWROc-mZZq
wqT2SI-KGDKB34XO0aw_7XdtAG8GaSwFKdCAPZgoXD2YBJZCPEX3xKpRwcdOO8Kp wqT2SI-KGDKB34XO0aw_7XdtAG8GaSwFKdCAPZgoXD2YBJZCPEX3xKpRwcdOO8Kp
EHwJjyqOgzDO7iKvU8vcnwNrmxYbSW9ERBXukOXolLzeO_Jn EHwJjyqOgzDO7iKvU8vcnwNrmxYbSW9ERBXukOXolLzeO_Jn
A.4.2. Validating A.4.2. Validating
Since the "alg" Header Parameter is "ES512", we validate the ECDSA Since the "alg" Header Parameter is "ES512", we validate the ECDSA
P-521 SHA-512 digital signature contained in the JWS Signature. P-521 SHA-512 digital signature contained in the JWS Signature.
Validating the JWS Signature is similar to the previous example. We Validating this JWS Signature is very similar to the previous
need to split the 132 member octet sequence of the JWS Signature into example. We need to split the 132 member octet sequence of the JWS
two 66 octet sequences, the first R and the second S. We then pass Signature into two 66 octet sequences, the first representing R and
(x, y), (R, S) and the JWS Signing Input to an ECDSA signature the second S. We then pass the public key (x, y), the signature (R,
verifier that has been configured to use the P-521 curve with the S), and the JWS Signing Input to an ECDSA signature verifier that has
SHA-512 hash function. been configured to use the P-521 curve with the SHA-512 hash
function.
A.5. Example Plaintext JWS A.5. Example Plaintext JWS
The following example JWS Protected Header declares that the encoded The following example JWS Protected Header declares that the encoded
object is a Plaintext JWS: object is a Plaintext JWS:
{"alg":"none"} {"alg":"none"}
Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected
Header)) gives this value: Header)) gives this value:
skipping to change at page 47, line 26 skipping to change at page 48, line 20
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, Edmund Jay, Yaron Y. Goland, Ben
Laurie, James Manger, Matt Miller, Tony Nadalin, Hideki Nara, Axel Laurie, James Manger, Matt Miller, Tony Nadalin, Hideki Nara, Axel
Nennker, John Panzer, Emmanuel Raviart, Eric Rescorla, Jim Schaad, Nennker, John Panzer, Emmanuel Raviart, Eric Rescorla, Jim Schaad,
Paul Tarjan, Hannes Tschofenig, and Sean Turner. Paul Tarjan, 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, Stephen Farrell, and Kathleen Moriarty served as
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 ]]
-26
o Referenced Section 6 of RFC 6125 for TLS server certificate
identity validation.
o Described potential sources of ambiguity in representing the JSON
objects used in the examples. The octets of the actual UTF-8
representations of the JSON objects used in the examples are
included to remove these ambiguities.
o Added a small amount of additional explanatory text to the
signature validation examples to aid implementers.
o Noted that octet sequences are depicted using JSON array notation.
o Updated references, including to W3C specifications.
-25 -25
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.
-24 -24
o Updated the JSON reference to RFC 7159. o Updated the JSON reference to RFC 7159.
-23 -23
skipping to change at page 52, line 29 skipping to change at page 53, line 37
o Completed JSON Security Considerations section, including o Completed JSON Security Considerations section, including
considerations about rejecting input with duplicate member names. considerations about rejecting input with duplicate member names.
o Completed security considerations on the use of a SHA-1 hash when o Completed security considerations on the use of a SHA-1 hash when
computing "x5t" (x.509 certificate thumbprint) values. computing "x5t" (x.509 certificate thumbprint) values.
o Refer to the registries as the primary sources of defined values o Refer to the registries as the primary sources of defined values
and then secondarily reference the sections defining the initial and then secondarily reference the sections defining the initial
contents of the registries. contents of the registries.
o Normatively reference XML DSIG 2.0 [W3C.CR-xmldsig-core2-20120124] o Normatively reference XML DSIG 2.0 for its security
for its security considerations. considerations.
o Added this language to Registration Templates: "This name is case o Added this language to Registration Templates: "This name is case
sensitive. Names that match other registered names in a case sensitive. Names that match other registered names in a case
insensitive manner SHOULD NOT be accepted." insensitive manner SHOULD NOT be accepted."
o Reference draft-jones-jose-jws-json-serialization instead of o Reference draft-jones-jose-jws-json-serialization instead of
draft-jones-json-web-signature-json-serialization. draft-jones-json-web-signature-json-serialization.
o Described additional open issues. o Described additional open issues.
 End of changes. 36 change blocks. 
73 lines changed or deleted 117 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/