draft-ietf-jose-json-web-signature-01.txt   draft-ietf-jose-json-web-signature-02.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: September 13, 2012 independent Expires: November 13, 2012 Ping Identity
N. Sakimura N. Sakimura
Nomura Research Institute NRI
March 12, 2012 May 12, 2012
JSON Web Signature (JWS) JSON Web Signature (JWS)
draft-ietf-jose-json-web-signature-01 draft-ietf-jose-json-web-signature-02
Abstract Abstract
JSON Web Signature (JWS) is a means of representing content secured JSON Web Signature (JWS) is a means of representing content secured
with digital signatures or Hash-based Message Authentication Codes with digital signatures or Message Authentication Codes (MACs) using
(HMACs) using JSON data structures. Cryptographic algorithms and JSON data structures. Cryptographic algorithms and identifiers used
identifiers used with this specification are enumerated in the with this specification are enumerated in the separate JSON Web
separate JSON Web Algorithms (JWA) specification. Related encryption Algorithms (JWA) specification. Related encryption capabilities are
capabilities are described in the separate JSON Web Encryption (JWE) described in the separate JSON Web Encryption (JWE) specification.
specification.
Requirements Language Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119]. document are to be interpreted as described in RFC 2119 [RFC2119].
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
skipping to change at page 1, line 45 skipping to change at page 1, line 44
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 13, 2012. This Internet-Draft will expire on November 13, 2012.
Copyright Notice Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the Copyright (c) 2012 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 12 skipping to change at page 2, line 22
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. JSON Web Signature (JWS) Overview . . . . . . . . . . . . . . 5 3. JSON Web Signature (JWS) Overview . . . . . . . . . . . . . . 5
3.1. Example JWS . . . . . . . . . . . . . . . . . . . . . . . 5 3.1. Example JWS . . . . . . . . . . . . . . . . . . . . . . . 5
4. JWS Header . . . . . . . . . . . . . . . . . . . . . . . . . . 6 4. JWS Header . . . . . . . . . . . . . . . . . . . . . . . . . . 6
4.1. Reserved Header Parameter Names . . . . . . . . . . . . . 6 4.1. Reserved Header Parameter Names . . . . . . . . . . . . . 7
4.2. Public Header Parameter Names . . . . . . . . . . . . . . 11 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 7
4.3. Private Header Parameter Names . . . . . . . . . . . . . . 11 4.1.2. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 7
5. Rules for Creating and Validating a JWS . . . . . . . . . . . 11 4.1.3. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 7
6. Securing JWSs with Cryptographic Algorithms . . . . . . . . . 13 4.1.4. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 8
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 4.1.5. "x5t" (X.509 Certificate Thumbprint) Header
Parameter . . . . . . . . . . . . . . . . . . . . . . 8
4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter . . . 8
4.1.7. "kid" (Key ID) Header Parameter . . . . . . . . . . . 9
4.1.8. "typ" (Type) Header Parameter . . . . . . . . . . . . 9
4.2. Public Header Parameter Names . . . . . . . . . . . . . . 9
4.3. Private Header Parameter Names . . . . . . . . . . . . . . 9
5. Rules for Creating and Validating a JWS . . . . . . . . . . . 10
6. Securing JWSs with Cryptographic Algorithms . . . . . . . . . 12
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
7.1. Registration of application/jws MIME Media Type . . . . . 12
7.2. Registration of "JWS" Type Value . . . . . . . . . . . . . 13
8. Security Considerations . . . . . . . . . . . . . . . . . . . 14 8. Security Considerations . . . . . . . . . . . . . . . . . . . 14
8.1. Unicode Comparison Security Issues . . . . . . . . . . . . 15 8.1. Cryptographic Security Considerations . . . . . . . . . . 14
8.2. JSON Security Considerations . . . . . . . . . . . . . . . 14
8.3. Unicode Comparison Security Considerations . . . . . . . . 15
9. Open Issues and Things To Be Done (TBD) . . . . . . . . . . . 15 9. Open Issues and Things To Be Done (TBD) . . . . . . . . . . . 15
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15
10.1. Normative References . . . . . . . . . . . . . . . . . . . 16 10.1. Normative References . . . . . . . . . . . . . . . . . . . 15
10.2. Informative References . . . . . . . . . . . . . . . . . . 18 10.2. Informative References . . . . . . . . . . . . . . . . . . 16
Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 18 Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 17
A.1. JWS using HMAC SHA-256 . . . . . . . . . . . . . . . . . . 18 A.1. JWS using HMAC SHA-256 . . . . . . . . . . . . . . . . . . 17
A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 18 A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 17
A.1.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 20 A.1.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 19
A.1.3. Validating . . . . . . . . . . . . . . . . . . . . . . 20 A.1.3. Validating . . . . . . . . . . . . . . . . . . . . . . 19
A.2. JWS using RSA SHA-256 . . . . . . . . . . . . . . . . . . 20
A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 20 A.2. JWS using RSA SHA-256 . . . . . . . . . . . . . . . . . . 19
A.2.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 24 A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 19
A.2.3. Validating . . . . . . . . . . . . . . . . . . . . . . 24 A.2.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 23
A.3. JWS using ECDSA P-256 SHA-256 . . . . . . . . . . . . . . 25 A.2.3. Validating . . . . . . . . . . . . . . . . . . . . . . 23
A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 25 A.3. JWS using ECDSA P-256 SHA-256 . . . . . . . . . . . . . . 24
A.3.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 27 A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 24
A.3.3. Validating . . . . . . . . . . . . . . . . . . . . . . 27 A.3.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 26
A.4. Example Plaintext JWS . . . . . . . . . . . . . . . . . . 27 A.3.3. Validating . . . . . . . . . . . . . . . . . . . . . . 26
A.4. Example Plaintext JWS . . . . . . . . . . . . . . . . . . 26
Appendix B. Notes on implementing base64url encoding without Appendix B. Notes on implementing base64url encoding without
padding . . . . . . . . . . . . . . . . . . . . . . . 28 padding . . . . . . . . . . . . . . . . . . . . . . . 27
Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 29 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 28
Appendix D. Document History . . . . . . . . . . . . . . . . . . 29 Appendix D. Document History . . . . . . . . . . . . . . . . . . 28
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30
1. Introduction 1. Introduction
JSON Web Signature (JWS) is a compact format for representing content JSON Web Signature (JWS) is a compact format for representing content
secured with digital signatures or Hash-based Message Authentication secured with digital signatures or Message Authentication Codes
Codes (HMACs) intended for space constrained environments such as (MACs) intended for space constrained environments such as HTTP
HTTP Authorization headers and URI query parameters. It represents Authorization headers and URI query parameters. It represents this
this content using JSON [RFC4627] data structures. The JWS digital content using JSON [RFC4627] data structures. The JWS digital
signature and HMAC mechanisms are independent of the type of content signature and MAC mechanisms are independent of the type of content
being secured, allowing arbitrary content to be secured. being secured, allowing arbitrary content to be secured.
Cryptographic algorithms and identifiers used with this specification Cryptographic algorithms and identifiers used with this specification
are enumerated in the separate JSON Web Algorithms (JWA) [JWA] are enumerated in the separate JSON Web Algorithms (JWA) [JWA]
specification. Related encryption capabilities are described in the specification. Related encryption capabilities are described in the
separate JSON Web Encryption (JWE) [JWE] specification. separate JSON Web Encryption (JWE) [JWE] specification.
2. Terminology 2. Terminology
JSON Web Signature (JWS) A data structure cryptographically securing JSON Web Signature (JWS) A data structure cryptographically securing
a JWS Header and a JWS Payload with a JWS Signature value. a JWS Header and a JWS Payload with a JWS Signature value.
JWS Header A string representing a JSON object that describes the JWS Header A string representing a JSON object that describes the
digital signature or HMAC applied to the JWS Header and the JWS digital signature or MAC operation applied to create the JWS
Payload to create the JWS Signature value. Signature value.
JWS Payload The bytes to be secured - a.k.a., the message. JWS Payload The bytes to be secured - a.k.a., the message. The
payload can contain an arbitrary sequence of bytes.
JWS Signature A byte array containing the cryptographic material JWS Signature A byte array containing the cryptographic material
that secures the contents of the JWS Header and the JWS Payload. that secures the contents of the JWS Header and the JWS Payload.
Encoded JWS Header Base64url encoding of the bytes of the UTF-8 RFC Encoded JWS Header Base64url encoding of the bytes of the UTF-8 RFC
3629 [RFC3629] representation of the JWS Header. 3629 [RFC3629] representation of the JWS Header.
Encoded JWS Payload Base64url encoding of the JWS Payload. Encoded JWS Payload Base64url encoding of the JWS Payload.
Encoded JWS Signature Base64url encoding of the JWS Signature. Encoded JWS Signature Base64url encoding of the JWS Signature.
skipping to change at page 5, line 17 skipping to change at page 5, line 17
and the Encoded JWS Signature in that order, with the three and the Encoded JWS Signature in that order, with the three
strings being separated by period ('.') characters. strings being separated by period ('.') characters.
Base64url Encoding For the purposes of this specification, this term Base64url Encoding For the purposes of this specification, this term
always refers to the URL- and filename-safe Base64 encoding always refers to the URL- and filename-safe Base64 encoding
described in RFC 4648 [RFC4648], Section 5, with the (non URL- described in RFC 4648 [RFC4648], Section 5, with the (non URL-
safe) '=' padding characters omitted, as permitted by Section 3.2. safe) '=' padding characters omitted, as permitted by Section 3.2.
(See Appendix B for notes on implementing base64url encoding (See Appendix B for notes on implementing base64url encoding
without padding.) without padding.)
StringOrURI A JSON string value, with the additional requirement
that while arbitrary string values MAY be used, any value
containing a ":" character MUST be a URI as defined in RFC 3986
[RFC3986].
3. JSON Web Signature (JWS) Overview 3. JSON Web Signature (JWS) Overview
JWS represents digitally signed or HMACed content using JSON data JWS represents digitally signed or MACed content using JSON data
structures and base64url encoding. The representation consists of structures and base64url encoding. The representation consists of
three parts: the JWS Header, the JWS Payload, and the JWS Signature. three parts: the JWS Header, the JWS Payload, and the JWS Signature.
In the Compact Serialization, the three parts are base64url-encoded In the Compact Serialization, the three parts are base64url-encoded
for transmission, and represented as the concatenation of the encoded for transmission, and represented as the concatenation of the encoded
strings in that order, with the three strings being separated by strings in that order, with the three strings being separated by
period ('.') characters. (A JSON Serialization for this information period ('.') characters. (A JSON Serialization for this information
is defined in the separate JSON Web Signature JSON Serialization is defined in the separate JSON Web Signature JSON Serialization
(JWS-JS) [JWS-JS] specification.) (JWS-JS) [JWS-JS] specification.)
The JWS Header describes the signature or HMAC method and parameters The JWS Header describes the signature or MAC method and parameters
employed. The JWS Payload is the message content to be secured. The employed. The JWS Payload is the message content to be secured. The
JWS Signature ensures the integrity of both the JWS Header and the JWS Signature ensures the integrity of both the JWS Header and the
JWS Payload. JWS Payload.
3.1. Example JWS 3.1. Example JWS
The following example JWS Header declares that the encoded object is The following example JWS Header declares that the encoded object is
a JSON Web Token (JWT) [JWT] and the JWS Header and the JWS Payload a JSON Web Token (JWT) [JWT] and the JWS Header and the JWS Payload
are secured using the HMAC SHA-256 algorithm: are secured using the HMAC SHA-256 algorithm:
{"typ":"JWT", {"typ":"JWT",
skipping to change at page 6, line 11 skipping to change at page 6, line 16
{"iss":"joe", {"iss":"joe",
"exp":1300819380, "exp":1300819380,
"http://example.com/is_root":true} "http://example.com/is_root":true}
Base64url encoding the bytes of the UTF-8 representation of the JSON Base64url encoding the bytes of the UTF-8 representation of the JSON
object yields the following Encoded JWS Payload (with line breaks for object yields the following Encoded JWS Payload (with line breaks for
display purposes only): display purposes only):
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
Computing the HMAC of the UTF-8 representation of the JWS Secured Computing the HMAC of the bytes of the UTF-8 representation of the
Input (the concatenation of the Encoded JWS Header, a period ('.') JWS Secured Input (the concatenation of the Encoded JWS Header, a
character, and the Encoded JWS Payload) with the HMAC SHA-256 period ('.') character, and the Encoded JWS Payload) (which is the
algorithm and base64url encoding the result, as per Appendix A.1, same as the ASCII representation) with the HMAC SHA-256 algorithm
yields this Encoded JWS Signature value: using the key specified in Appendix A.1 and base64url encoding the
result yields this Encoded JWS Signature value:
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
Concatenating these parts in the order Header.Payload.Signature with Concatenating these parts in the order Header.Payload.Signature with
period characters between the parts yields this complete JWS period characters between the parts yields this complete JWS
representation (with line breaks for display purposes only): representation (with line breaks for display purposes only):
eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
. .
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
. .
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
This computation is illustrated in more detail in Appendix A.1. This computation is illustrated in more detail in Appendix A.1.
4. JWS Header 4. JWS Header
The members of the JSON object represented by the JWS Header describe The members of the JSON object represented by the JWS Header describe
the digital signature or HMAC applied to the Encoded JWS Header and the digital signature or MAC applied to the Encoded JWS Header and
the Encoded JWS Payload and optionally additional properties of the the Encoded JWS Payload and optionally additional properties of the
JWS. The Header Parameter Names within this object MUST be unique. JWS. The Header Parameter Names within this object MUST be unique;
JWSs with duplicate Header Parameter Names MUST be rejected.
Implementations MUST understand the entire contents of the header; Implementations MUST understand the entire contents of the header;
otherwise, the JWS MUST be rejected. otherwise, the JWS MUST be rejected.
The JWS Header MUST contain an "alg" (algorithm) parameter, the value
of which is a string that unambiguously identifies the algorithm used
to secure the JWS Header and the JWS Payload to produce the JWS
Signature.
There are three classes of Header Parameter Names: Reserved Header There are three classes of Header Parameter Names: Reserved Header
Parameter Names, Public Header Parameter Names, and Private Header Parameter Names, Public Header Parameter Names, and Private Header
Parameter Names. Parameter Names.
4.1. Reserved Header Parameter Names 4.1. Reserved Header Parameter Names
The following header parameter names are reserved. All the names are The following header parameter names are reserved with meanings as
short because a core goal of JWSs is for the representations to be defined below. All the names are short because a core goal of JWSs
compact. is for the representations to be compact.
+-----------+--------+----------------+-----------------------------+ Additional reserved header parameter names MAY be defined via the
| Header | JSON | Header | Header Parameter Semantics | IANA JSON Web Signature and Encryption Header Parameters registry
| Parameter | Value | Parameter | | [JWA]. As indicated by the common registry, JWSs and JWEs share a
| Name | Type | Syntax | | common header parameter space; when a parameter is used by both
+-----------+--------+----------------+-----------------------------+ specifications, its usage must be compatible between the
| alg | string | StringOrURI | The "alg" (algorithm) | specifications.
| | | | header parameter identifies |
| | | | the cryptographic algorithm |
| | | | used to secure the JWS. A |
| | | | list of defined "alg" |
| | | | values is presented in |
| | | | Section 3, Table 1 of the |
| | | | JSON Web Algorithms (JWA) |
| | | | [JWA] specification. The |
| | | | processing of the "alg" |
| | | | header parameter requires |
| | | | that the value MUST be one |
| | | | that is both supported and |
| | | | for which there exists a |
| | | | key for use with that |
| | | | algorithm associated with |
| | | | the party that digitally |
| | | | signed or HMACed the |
| | | | content. The "alg" |
| | | | parameter value is case |
| | | | sensitive. This header |
| | | | parameter is REQUIRED. |
| jku | string | URL | The "jku" (JSON Web Key |
| | | | URL) header parameter is an |
| | | | absolute URL that refers to |
| | | | a resource for a set of |
| | | | JSON-encoded public keys, |
| | | | one of which corresponds to |
| | | | the key that was used to |
| | | | digitally sign the JWS. |
| | | | The keys MUST be encoded as |
| | | | described in the JSON Web |
| | | | Key (JWK) [JWK] |
| | | | specification. The |
| | | | protocol used to acquire |
| | | | the resource MUST provide |
| | | | integrity protection. An |
| | | | HTTP GET request to |
| | | | retrieve the certificate |
| | | | MUST use TLS RFC 2818 |
| | | | [RFC2818] RFC 5246 |
| | | | [RFC5246] with server |
| | | | authentication RFC 6125 |
| | | | [RFC6125]. This header |
| | | | parameter is OPTIONAL. |
| kid | string | String | The "kid" (key ID) header |
| | | | parameter is a hint |
| | | | indicating which specific |
| | | | key owned by the signer |
| | | | should be used to validate |
| | | | the digital signature. |
| | | | This allows signers to |
| | | | explicitly signal a change |
| | | | of key to recipients. The |
| | | | interpretation of the |
| | | | contents of the "kid" |
| | | | parameter is unspecified. |
| | | | This header parameter is |
| | | | OPTIONAL. |
| jpk | object | JWK Key Object | The "jpk" (JSON Public Key) |
| | | | header parameter is a |
| | | | public key that corresponds |
| | | | to the key that was used to |
| | | | digitally sign the JWS. |
| | | | This key is represented in |
| | | | the same manner as a JSON |
| | | | Web Key [JWK] JWK Key |
| | | | Object value. This header |
| | | | parameter is OPTIONAL. |
| x5u | string | URL | The "x5u" (X.509 URL) |
| | | | header parameter is an |
| | | | absolute URL that refers to |
| | | | a resource for the X.509 |
| | | | public key certificate or |
| | | | certificate chain |
| | | | corresponding to the key |
| | | | used to digitally sign the |
| | | | JWS. The identified |
| | | | resource MUST provide a |
| | | | representation of the |
| | | | certificate or certificate |
| | | | chain that conforms to RFC |
| | | | 5280 [RFC5280] in PEM |
| | | | encoded form RFC 1421 |
| | | | [RFC1421]. The certificate |
| | | | containing the public key |
| | | | of the entity signing the |
| | | | JWS MUST be the first |
| | | | certificate. This MAY be |
| | | | followed by additional |
| | | | certificates, with each |
| | | | subsequent certificate |
| | | | being the one used to |
| | | | certify the previous one. |
| | | | The protocol used to |
| | | | acquire the resource MUST |
| | | | provide integrity |
| | | | protection. An HTTP GET |
| | | | request to retrieve the |
| | | | certificate MUST use TLS |
| | | | RFC 2818 [RFC2818] RFC 5246 |
| | | | [RFC5246] with server |
| | | | authentication RFC 6125 |
| | | | [RFC6125]. This header |
| | | | parameter is OPTIONAL. |
| x5t | string | String | The "x5t" (x.509 |
| | | | certificate thumbprint) |
| | | | header parameter provides a |
| | | | base64url encoded SHA-1 |
| | | | thumbprint (a.k.a. digest) |
| | | | of the DER encoding of an |
| | | | X.509 certificate that can |
| | | | be used to match the |
| | | | certificate. This header |
| | | | parameter is OPTIONAL. |
| x5c | array | ArrayOfStrings | The "x5c" (x.509 |
| | | | certificate chain) header |
| | | | parameter contains the |
| | | | X.509 public key |
| | | | certificate or certificate |
| | | | chain corresponding to the |
| | | | key used to digitally sign |
| | | | the JWS. The certificate |
| | | | or certificate chain is |
| | | | represented as an array of |
| | | | certificate values. Each |
| | | | value is a base64-encoded |
| | | | (not base64url encoded) |
| | | | DER/BER PKIX certificate |
| | | | value. The certificate |
| | | | containing the public key |
| | | | of the entity signing the |
| | | | JWS MUST be the first |
| | | | certificate. This MAY be |
| | | | followed by additional |
| | | | certificates, with each |
| | | | subsequent certificate |
| | | | being the one used to |
| | | | certify the previous one. |
| | | | The recipient MUST verify |
| | | | the certificate chain |
| | | | according to [RFC5280] and |
| | | | reject the JWS if any |
| | | | validation failure occurs. |
| | | | This header parameter is |
| | | | OPTIONAL. |
| typ | string | String | The "typ" (type) header |
| | | | parameter is used to |
| | | | declare the type of the |
| | | | secured content. The "typ" |
| | | | value is case sensitive. |
| | | | This header parameter is |
| | | | OPTIONAL. |
+-----------+--------+----------------+-----------------------------+
Table 1: Reserved Header Parameter Definitions 4.1.1. "alg" (Algorithm) Header Parameter
Additional reserved header parameter names MAY be defined via the The "alg" (algorithm) header parameter identifies the cryptographic
IANA JSON Web Signature Header Parameters registry, as per Section 7. algorithm used to secure the JWS. A list of defined "alg" values for
The syntax values used above are defined as follows: use with JWS is presented in Section 3.1 of the JSON Web Algorithms
(JWA) [JWA] specification. The processing of the "alg" header
parameter requires that the value MUST be one that is both supported
and for which there exists a key for use with that algorithm
associated with the party that digitally signed or MACed the content.
The "alg" value is case sensitive. Its value MUST be a string
containing a StringOrURI value. This header parameter is REQUIRED.
+----------------+--------------------------------------------------+ "alg" values SHOULD either be defined in the IANA JSON Web Signature
| Syntax Name | Syntax Definition | and Encryption Algorithms registry [JWA] or be a URI that contains a
+----------------+--------------------------------------------------+ collision resistant namespace.
| IntDate | The number of seconds from 1970-01-01T0:0:0Z as |
| | measured in UTC until the desired date/time. |
| | See RFC 3339 [RFC3339] for details regarding |
| | date/times in general and UTC in particular. |
| String | Any string value MAY be used. |
| StringOrURI | Any string value MAY be used but a value |
| | containing a ":" character MUST be a URI as |
| | defined in RFC 3986 [RFC3986]. |
| URL | A URL as defined in RFC 1738 [RFC1738]. |
| ArrayOfStrings | An array of string values. |
+----------------+--------------------------------------------------+
Table 2: Header Parameter Syntax Definitions 4.1.2. "jku" (JWK Set URL) Header Parameter
The "jku" (JWK Set URL) header parameter is an absolute URL that
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
keys MUST be encoded as a JSON Web Key Set (JWK Set) as defined in
the JSON Web Key (JWK) [JWK] specification. The protocol used to
acquire the resource MUST provide integrity protection; an HTTP GET
request to retrieve the certificate MUST use TLS RFC 2818 [RFC2818]
RFC 5246 [RFC5246]; the identity of the server MUST be validated, as
per Section 3.1 of HTTP Over TLS [RFC2818]. This header parameter is
OPTIONAL.
4.1.3. "jwk" (JSON Web Key) Header Parameter
The "jwk" (JSON Web Key) header parameter is a public key that
corresponds to the key used to digitally sign the JWS. This key is
represented as a JSON Web Key [JWK]. This header parameter is
OPTIONAL.
4.1.4. "x5u" (X.509 URL) Header Parameter
The "x5u" (X.509 URL) header parameter is an absolute URL that refers
to a resource for the X.509 public key certificate or certificate
chain corresponding to the key used to digitally sign the JWS. The
identified resource MUST provide a representation of the certificate
or certificate chain that conforms to RFC 5280 [RFC5280] in PEM
encoded form RFC 1421 [RFC1421]. The certificate containing the
public key of the entity that digitally signed the JWS MUST be the
first certificate. This MAY be followed by additional certificates,
with each subsequent certificate being the one used to certify the
previous one. The protocol used to acquire the resource MUST provide
integrity protection; an HTTP GET request to retrieve the certificate
MUST use TLS RFC 2818 [RFC2818] RFC 5246 [RFC5246]; the identity of
the server MUST be validated, as per Section 3.1 of HTTP Over TLS
[RFC2818]. This header parameter is OPTIONAL.
4.1.5. "x5t" (X.509 Certificate Thumbprint) Header Parameter
The "x5t" (X.509 Certificate Thumbprint) header parameter provides a
base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER
encoding of the X.509 certificate corresponding to the key used to
digitally sign the JWS. This header parameter is OPTIONAL.
If, in the future, certificate thumbprints need to be computed using
hash functions other than SHA-1, it is suggested that additional
related header parameters be defined for that purpose. For example,
it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint
using SHA-256) header parameter could be defined by registering it in
the IANA JSON Web Signature and Encryption Header Parameters registry
[JWA].
4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter
The "x5c" (X.509 Certificate Chain) header parameter contains the
X.509 public key certificate or certificate chain corresponding to
the key used to digitally sign the JWS. The certificate or
certificate chain is represented as an array of certificate values.
Each value is a base64-encoded (not base64url encoded) DER/BER PKIX
certificate value. The certificate containing the public key of the
entity that digitally signed the JWS MUST be the first certificate.
This MAY be followed by additional certificates, with each subsequent
certificate being the one used to certify the previous one. The
recipient MUST verify the certificate chain according to [RFC5280]
and reject the JWS if any validation failure occurs. This header
parameter is OPTIONAL.
4.1.7. "kid" (Key ID) Header Parameter
The "kid" (key ID) header parameter is a hint indicating which key
was used to secure the JWS. This allows originators to explicitly
signal a change of key to recipients. Should the recipient be unable
to locate a key corresponding to the "kid" value, they SHOULD treat
that condition as an error. The interpretation of the contents of
the "kid" parameter is unspecified. Its value MUST be a string.
This header parameter is OPTIONAL.
4.1.8. "typ" (Type) Header Parameter
The "typ" (type) header parameter is used to declare the type of the
secured content. The type value "JWS" MAY be used to indicate that
the secured content is a JWS. The "typ" value is case sensitive.
Its value MUST be a string. This header parameter is OPTIONAL.
MIME Media Type RFC 2045 [RFC2045] values MAY be used as "typ"
values.
"typ" values SHOULD either be defined in the IANA JSON Web Signature
and Encryption "typ" Values registry [JWA] or be a URI that contains
a collision resistant namespace.
4.2. Public Header Parameter Names 4.2. Public Header Parameter Names
Additional header parameter names can be defined by those using JWSs. Additional header parameter names can be defined by those using JWSs.
However, in order to prevent collisions, any new header parameter However, in order to prevent collisions, any new header parameter
name or algorithm value SHOULD either be defined in the IANA JSON Web name SHOULD either be defined in the IANA JSON Web Signature and
Signature Header Parameters registry or be defined as a URI that Encryption Header Parameters registry [JWA] or be a URI that contains
contains a collision resistant namespace. In each case, the definer a collision resistant namespace. In each case, the definer of the
of the name or value needs to take reasonable precautions to make name or value needs to take reasonable precautions to make sure they
sure they are in control of the part of the namespace they use to are in control of the part of the namespace they use to define the
define the header parameter name. header parameter name.
New header parameters should be introduced sparingly since an New header parameters should be introduced sparingly, as they can
implementation that does not understand a parameter MUST reject the result in non-interoperable JWSs.
JWS.
4.3. Private Header Parameter Names 4.3. Private Header Parameter Names
A producer and consumer of a JWS may agree to any header parameter A producer and consumer of a JWS may agree to any header parameter
name that is not a Reserved Name Section 4.1 or a Public Name name that is not a Reserved Name Section 4.1 or a Public Name
Section 4.2. Unlike Public Names, these private names are subject to Section 4.2. Unlike Public Names, these private names are subject to
collision and should be used with caution. collision and should be used with caution.
New header parameters should be introduced sparingly, as they can
result in non-interoperable JWSs.
5. Rules for Creating and Validating a JWS 5. Rules for Creating and Validating a JWS
To create a JWS, one MUST perform these steps. The order of the To create a JWS, one MUST perform these steps. The order of the
steps is not significant in cases where there are no dependencies steps is not significant in cases where there are no dependencies
between the inputs and outputs of the steps. between the inputs and outputs of the steps.
1. Create the content to be used as the JWS Payload. 1. Create the content to be used as the JWS Payload.
2. Base64url encode the bytes of the JWS Payload. This encoding 2. Base64url encode the bytes of the JWS Payload. This encoding
becomes the Encoded JWS Payload. becomes the Encoded JWS Payload.
skipping to change at page 12, line 21 skipping to change at page 10, line 27
parameters. Note that white space is explicitly allowed in the parameters. Note that white space is explicitly allowed in the
representation and no canonicalization need be performed before representation and no canonicalization need be performed before
encoding. encoding.
4. Base64url encode the bytes of the UTF-8 representation of the JWS 4. Base64url encode the bytes of the UTF-8 representation of the JWS
Header to create the Encoded JWS Header. Header to create the Encoded JWS Header.
5. Compute the JWS Signature in the manner defined for the 5. Compute the JWS Signature in the manner defined for the
particular algorithm being used. The JWS Secured Input is always particular algorithm being used. The JWS Secured Input is always
the concatenation of the Encoded JWS Header, a period ('.') the concatenation of the Encoded JWS Header, a period ('.')
character, and the Encoded JWS Payload. (Note that if the JWS character, and the Encoded JWS Payload. The "alg" (algorithm)
represents a JWT, this corresponds to the portion of the JWT header parameter MUST be present in the JSON Header, with the
representation preceding the second period character.) The "alg" algorithm value accurately representing the algorithm used to
(algorithm) header parameter MUST be present in the JSON Header, construct the JWS Signature.
with the algorithm value accurately representing the algorithm
used to construct the JWS Signature.
6. Base64url encode the representation of the JWS Signature to 6. Base64url encode the representation of the JWS Signature to
create the Encoded JWS Signature. create the Encoded JWS Signature.
7. The three encoded parts, taken together, are the result. The 7. The three encoded parts, taken together, are the result. The
Compact Serialization of this result is the concatenation of the Compact Serialization of this result is the concatenation of the
Encoded JWS Header, the Encoded JWS Payload, and the Encoded JWS Encoded JWS Header, the Encoded JWS Payload, and the Encoded JWS
Signature in that order, with the three strings being separated Signature in that order, with the three strings being separated
by period ('.') characters. by period ('.') characters.
skipping to change at page 12, line 51 skipping to change at page 11, line 6
1. Parse the three parts of the input (which are separated by period 1. Parse the three parts of the input (which are separated by period
characters when using the JWS Compact Serialization) into the characters when using the JWS Compact Serialization) into the
Encoded JWS Header, the Encoded JWS Payload, and the Encoded JWS Encoded JWS Header, the Encoded JWS Payload, and the Encoded JWS
Signature. Signature.
2. The Encoded JWS Header MUST be successfully base64url decoded 2. The Encoded JWS Header MUST be successfully base64url decoded
following the restriction given in this specification that no following the restriction given in this specification that no
padding characters have been used. padding characters have been used.
3. The JWS Header MUST be completely valid JSON syntax conforming to 3. The resulting JWS Header MUST be completely valid JSON syntax
RFC 4627 [RFC4627]. conforming to RFC 4627 [RFC4627].
4. The JWS Header MUST be validated to only include parameters and 4. The resulting JWS Header MUST be validated to only include
values whose syntax and semantics are both understood and parameters and values whose syntax and semantics are both
supported. understood and supported.
5. The Encoded JWS Payload MUST be successfully base64url decoded 5. The Encoded JWS Payload MUST be successfully base64url decoded
following the restriction given in this specification that no following the restriction given in this specification that no
padding characters have been used. padding characters have been used.
6. The Encoded JWS Signature MUST be successfully base64url decoded 6. The Encoded JWS Signature MUST be successfully base64url decoded
following the restriction given in this specification that no following the restriction given in this specification that no
padding characters have been used. padding characters have been used.
7. The JWS Signature MUST be successfully validated against the JWS 7. The JWS Signature MUST be successfully validated against the JWS
skipping to change at page 13, line 46 skipping to change at page 12, line 7
2. Unicode Normalization [USA15] MUST NOT be applied at any point to 2. Unicode Normalization [USA15] MUST NOT be applied at any point to
either the JSON string or to the string it is to be compared either the JSON string or to the string it is to be compared
against. against.
3. Comparisons between the two strings MUST be performed as a 3. Comparisons between the two strings MUST be performed as a
Unicode code point to code point equality comparison. Unicode code point to code point equality comparison.
6. Securing JWSs with Cryptographic Algorithms 6. Securing JWSs with Cryptographic Algorithms
JWS uses cryptographic algorithms to digitally sign or HMAC the JWS uses cryptographic algorithms to digitally sign or MAC the
contents of the JWS Header and the JWS Payload. The JSON Web contents of the JWS Header and the JWS Payload. The JSON Web
Algorithms (JWA) [JWA] specification enumerates a set of Algorithms (JWA) [JWA] specification enumerates a set of
cryptographic algorithms and identifiers to be used with this cryptographic algorithms and identifiers to be used with this
specification. Specifically, Section 3, Table 1 enumerates a set of specification. Specifically, Section 3.1 enumerates a set of "alg"
"alg" (algorithm) header parameter values intended for use this (algorithm) header parameter values intended for use this
specification. It also describes the semantics and operations that specification. It also describes the semantics and operations that
are specific to these algorithms and algorithm families. are specific to these algorithms and algorithm families.
Public keys employed for digital signing can be identified using the Public keys employed for digital signing can be identified using the
Header Parameter methods described in Section 4.1 or can be Header Parameter methods described in Section 4.1 or can be
distributed using methods that are outside the scope of this distributed using methods that are outside the scope of this
specification. specification.
7. IANA Considerations 7. IANA Considerations
This specification calls for: 7.1. Registration of application/jws MIME Media Type
o A new IANA registry entitled "JSON Web Signature Header This specification registers the "application/jws" MIME Media Type
Parameters" for reserved header parameter names is defined in RFC 2045 [RFC2045].
Section 4.1. Inclusion in the registry is RFC Required in the RFC
5226 [RFC5226] sense for reserved JWS header parameter names that Type name:
are intended to be interoperable between implementations. The application
registry will just record the reserved header parameter name and a
pointer to the RFC that defines it. This specification defines Subtype name:
inclusion of the header parameter names defined in Table 1. jws
Required parameters:
n/a
Optional parameters:
n/a
Encoding considerations:
n/a
Security considerations:
See the Security Considerations section of this document
Interoperability considerations:
n/a
Published specification:
[[ this document ]]
Applications that use this media type:
OpenID Connect
Additional information:
Magic number(s): n/a
File extension(s): n/a
Macintosh file type code(s): n/a
Person & email address to contact for further information:
Michael B. Jones
mbj@microsoft.com
Intended usage:
COMMON
Restrictions on usage:
none
Author:
Michael B. Jones
mbj@microsoft.com
Change controller:
IETF
7.2. Registration of "JWS" Type Value
This specification registers the following "typ" header parameter
value in the JSON Web Signature and Encryption "typ" Values registry
established by the JSON Web Algorithms (JWA) [JWA] specification:
"typ" header parameter value:
"JWS"
Abbreviation for MIME type:
application/jws
Change controller:
IETF
Description:
[[ this document ]]
8. Security Considerations 8. Security Considerations
TBD: Lots of work to do here. We need to remember to look into any 8.1. Cryptographic Security Considerations
issues relating to security and JSON parsing. One wonders just how
secure most JSON parsing libraries are. Were they ever hardened for
security scenarios? If not, what kind of holes does that open up?
Also, we need to walk through the JSON standard and see what kind of
issues we have especially around comparison of names. For instance,
comparisons of header parameter names and other parameters must occur
after they are unescaped. Need to also put in text about: Importance
of keeping secrets secret. Rotating keys. Strengths and weaknesses
of the different algorithms.
TBD: Need to put in text about why strict JSON validation is All the security considerations in XML DSIG 2.0
necessary. Basically, that if malformed JSON is received then the [W3C.CR-xmldsig-core2-20120124], also apply to this specification,
intent of the sender is impossible to reliably discern. One example other than those that are XML specific. Likewise, many of the best
of malformed JSON that MUST be rejected is an object in which the practices documented in XML Signature Best Practices
same member name occurs multiple times. [W3C.WD-xmldsig-bestpractices-20110809] also apply to this
specification, other than those that are XML specific.
TBD: Write security considerations about the implications of using a Keys are only as strong as the amount of entropy used to generate
SHA-1 hash (for compatibility reasons) for the "x5t" (x.509 them. A minimum of 128 bits of entropy should be used for all keys,
certificate thumbprint). and depending upon the application context, more may be required.
When utilizing TLS to retrieve information, the authority providing When utilizing TLS to retrieve information, the authority providing
the resource MUST be authenticated and the information retrieved MUST the resource MUST be authenticated and the information retrieved MUST
be free from modification. be free from modification.
8.1. Unicode Comparison Security Issues When cryptographic algorithms are implemented in such a way that
successful operations take a different amount of time than
unsuccessful operations, attackers may be able to use the time
difference to obtain information about the keys employed. Therefore,
such timing differences must be avoided.
Header parameter names in JWSs are Unicode strings. For security TBD: We need to also put in text about: Importance of keeping secrets
reasons, the representations of these names must be compared verbatim secret. Rotating keys. Strengths and weaknesses of the different
after performing any escape processing (as per RFC 4627 [RFC4627], algorithms.
Section 2.5).
This means, for instance, that these JSON strings must compare as TBD: Write security considerations about the implications of using a
being equal ("sig", "\u0073ig"), whereas these must all compare as SHA-1 hash (for compatibility reasons) for the "x5t" (x.509
being not equal to the first set or to each other ("SIG", "Sig", certificate thumbprint).
"si\u0047").
TBD: We need a section on generating randomness in browsers; it's
easy to screw up.
8.2. JSON Security Considerations
TBD: We need to look into any issues relating to security and JSON
parsing. One wonders just how secure most JSON parsing libraries
are. Were they ever hardened for security scenarios? If not, what
kind of holes does that open up? We need to put in text about why
strict JSON validation is necessary - basically, that if malformed
JSON is received then the intent of the sender is impossible to
reliably discern.
8.3. Unicode Comparison Security Considerations
Header parameter names and algorithm names are Unicode strings. For
security reasons, the representations of these names must be compared
verbatim after performing any escape processing (as per RFC 4627
[RFC4627], Section 2.5). This means, for instance, that these JSON
strings must compare as being equal ("sig", "\u0073ig"), whereas
these must all compare as being not equal to the first set or to each
other ("SIG", "Sig", "si\u0047").
JSON strings MAY contain characters outside the Unicode Basic JSON strings MAY contain characters outside the Unicode Basic
Multilingual Plane. For instance, the G clef character (U+1D11E) may Multilingual Plane. For instance, the G clef character (U+1D11E) may
be represented in a JSON string as "\uD834\uDD1E". Ideally, JWS be represented in a JSON string as "\uD834\uDD1E". Ideally, JWS
implementations SHOULD ensure that characters outside the Basic implementations SHOULD ensure that characters outside the Basic
Multilingual Plane are preserved and compared correctly; Multilingual Plane are preserved and compared correctly;
alternatively, if this is not possible due to these characters alternatively, if this is not possible due to these characters
exercising limitations present in the underlying JSON implementation, exercising limitations present in the underlying JSON implementation,
then input containing them MUST be rejected. then input containing them MUST be rejected.
9. Open Issues and Things To Be Done (TBD) 9. Open Issues and Things To Be Done (TBD)
The following items remain to be done in this draft: The following items remain to be done in this draft:
o EDITORIAL: Give each header parameter definition its own section. o Add an example in which the payload is not a base64url encoded
This will let them appear in the index, will give space for JSON object.
examples when needed, and will get rid of the way-too-cramped
tables.
o Describe the relationship between the JWS, JWE, and JWT header
parameters. In particular, point out that the set of "alg" values
defined by each must be compatible and non-overlapping.
o Combine the JWS and JWE "alg" parameter registries and possibly
also the header parameter registries.
o Clarify the intended use of the "typ" Header Parameter across the
JWS, JWE, and JWT specifications. Decide whether a registry of
"typ" values is appropriate.
o Add normative text that requires rejecting headers in which member
names occur multiple times, as apparently this is legal JSON.
o Clarify the semantics of the "kid" (key ID) header parameter.
Open issues include: What happens if a "kid" header is received
with an unrecognized value? Is that an error? Should it be
treated as if it's empty? What happens if the header has a
recognized value but the value doesn't match the key associated
with that value, but it does match another key that is associated
with the issuer? Is that an error?
o Consider whether a key type parameter should also be introduced.
o It would be good to have a confirmation method element so it could
be used with holder-of-key.
o EDITORIAL: Think about how to best describe the concept currently
described as "the bytes of the UTF-8 representation of". Possible
terms to use instead of "bytes of" include "byte sequence", "octet
series", and "octet sequence". Also consider whether we want to
add an overall clarifying statement somewhere in each spec
something like "every place we say 'the UTF-8 representation of
X', we mean 'the bytes of the UTF-8 representation of X'". That
would potentially allow us to omit the "the bytes of" part
everywhere else.
o Write a note in the Security Considerations section about how
"x5t" (x.509 certificate thumbprint) should be deprecated because
of known problems with SHA-1.
o Add Security Considerations text on timing attacks.
o Finish the Security Considerations section. o Finish the Security Considerations section.
o EDITORIAL: Add an example in which the payload is not a base64url
encoded JSON object.
10. References 10. References
10.1. Normative References 10.1. Normative References
[JWA] Jones, M., "JSON Web Algorithms (JWA)", March 2012. [JWA] Jones, M., "JSON Web Algorithms (JWA)", May 2012.
[JWK] Jones, M., "JSON Web Key (JWK)", March 2012. [JWK] Jones, M., "JSON Web Key (JWK)", May 2012.
[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.
[RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform
Resource Locators (URL)", RFC 1738, December 1994.
[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.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
[RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
Internet: Timestamps", RFC 3339, July 2002.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003. 10646", STD 63, RFC 3629, November 2003.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005. RFC 3986, January 2005.
[RFC4627] Crockford, D., "The application/json Media Type for [RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006. JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, October 2006. Encodings", RFC 4648, October 2006.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008. (TLS) Protocol Version 1.2", RFC 5246, August 2008.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, "Internet X.509 Public Key Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation List Infrastructure Certificate and Certificate Revocation List
(CRL) Profile", RFC 5280, May 2008. (CRL) Profile", RFC 5280, May 2008.
[RFC6125] Saint-Andre, P. and J. Hodges, "Representation and
Verification of Domain-Based Application Service Identity
within Internet Public Key Infrastructure Using X.509
(PKIX) Certificates in the Context of Transport Layer
Security (TLS)", RFC 6125, March 2011.
[USA15] Davis, M., Whistler, K., and M. Duerst, "Unicode [USA15] Davis, M., Whistler, K., and M. Duerst, "Unicode
Normalization Forms", Unicode Standard Annex 15, 09 2009. Normalization Forms", Unicode Standard Annex 15, 09 2009.
10.2. Informative References 10.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., Rescorla, E., and J. Hildebrand, "JSON Web [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web
Encryption (JWE)", March 2012. Encryption (JWE)", May 2012.
[JWS-JS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [JWS-JS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature JSON Serialization (JWS-JS)", March 2012. Signature JSON Serialization (JWS-JS)", March 2012.
[JWT] Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, [JWT] Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer,
J., Sakimura, N., and P. Tarjan, "JSON Web Token (JWT)", J., Sakimura, N., and P. Tarjan, "JSON Web Token (JWT)",
March 2012. May 2012.
[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.
[W3C.CR-xmldsig-core2-20120124]
Eastlake, D., Reagle, J., Yiu, K., Solo, D., Datta, P.,
Hirsch, F., Cantor, S., and T. Roessler, "XML Signature
Syntax and Processing Version 2.0", World Wide Web
Consortium CR CR-xmldsig-core2-20120124, January 2012,
<http://www.w3.org/TR/2012/CR-xmldsig-core2-20120124>.
[W3C.WD-xmldsig-bestpractices-20110809]
Datta, P. and F. Hirsch, "XML Signature Best Practices",
World Wide Web Consortium WD WD-xmldsig-bestpractices-
20110809, August 2011, <http://www.w3.org/TR/2011/
WD-xmldsig-bestpractices-20110809>.
Appendix A. JWS Examples Appendix A. JWS Examples
This section provides several examples of JWSs. While these examples This section provides several examples of JWSs. While these examples
all represent JSON Web Tokens (JWTs) [JWT], the payload can be any all represent JSON Web Tokens (JWTs) [JWT], the payload can be any
base64url encoded content. base64url encoded content.
A.1. JWS using HMAC SHA-256 A.1. JWS using HMAC SHA-256
A.1.1. Encoding A.1.1. Encoding
The following example JWS Header declares that the data structure is The following example JWS Header declares that the data structure is
a JSON Web Token (JWT) [JWT] and the JWS Secured Input is secured a JSON Web Token (JWT) [JWT] and the JWS Secured Input is secured
using the HMAC SHA-256 algorithm. using the HMAC SHA-256 algorithm.
{"typ":"JWT", {"typ":"JWT",
"alg":"HS256"} "alg":"HS256"}
The following byte array contains the UTF-8 characters for the JWS The following byte array contains the UTF-8 representation of the JWS
Header: Header:
[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]
Base64url encoding this UTF-8 representation yields this Encoded JWS Base64url encoding these bytes yields this Encoded JWS Header value:
Header value:
eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
The JWS Payload used in this example follows. (Note that the payload
can be any base64url encoded content, and need not be a base64url The JWS Payload used in this example is the bytes of the UTF-8
encoded JSON object.) representation of the JSON object below. (Note that the payload can
be any base64url encoded sequence of bytes, and need not be a
base64url 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 byte array contains the UTF-8 characters for the JWS The following byte array, which is the UTF-8 representation of the
Payload: 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]
Base64url encoding the above yields the Encoded JWS Payload value Base64url encoding the above yields the Encoded JWS Payload value
(with line breaks for display purposes only): (with line breaks for display purposes only):
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
Concatenating the Encoded JWS Header, a period character, and the Concatenating the Encoded JWS Header, a period character, and the
Encoded JWS Payload yields this JWS Secured Input value (with line Encoded JWS Payload yields this JWS Secured Input value (with line
breaks for display purposes only): breaks for display purposes only):
eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
. .
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
The UTF-8 representation of the JWS Secured Input is the following The UTF-8 representation of the JWS Secured Input (which is the same
byte array: as the ASCII representation) is the following byte array:
[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]
HMACs are generated using keys. This example uses the key HMACs are generated using keys. This example uses the key
represented by the following byte array: represented by the following byte array:
[3, 35, 53, 75, 43, 15, 165, 188, 131, 126, 6, 101, 119, 123, 166, [3, 35, 53, 75, 43, 15, 165, 188, 131, 126, 6, 101, 119, 123, 166,
143, 90, 179, 40, 230, 240, 84, 201, 40, 169, 15, 132, 178, 210, 80, 143, 90, 179, 40, 230, 240, 84, 201, 40, 169, 15, 132, 178, 210, 80,
46, 191, 211, 251, 90, 146, 210, 6, 71, 239, 150, 138, 180, 195, 119, 46, 191, 211, 251, 90, 146, 210, 6, 71, 239, 150, 138, 180, 195, 119,
98, 61, 34, 61, 46, 33, 114, 5, 46, 79, 8, 192, 205, 154, 245, 103, 98, 61, 34, 61, 46, 33, 114, 5, 46, 79, 8, 192, 205, 154, 245, 103,
208, 128, 163] 208, 128, 163]
Running the HMAC SHA-256 algorithm on the UTF-8 representation of the Running the HMAC SHA-256 algorithm on the bytes of the UTF-8
JWS Secured Input with this key yields the following byte array: representation of the JWS Secured Input (which is the same as the
ASCII representation) with this key yields the following byte array:
[116, 24, 223, 180, 151, 153, 224, 37, 79, 250, 96, 125, 216, 173, [116, 24, 223, 180, 151, 153, 224, 37, 79, 250, 96, 125, 216, 173,
187, 186, 22, 212, 37, 77, 105, 214, 191, 240, 91, 88, 5, 88, 83, 187, 186, 22, 212, 37, 77, 105, 214, 191, 240, 91, 88, 5, 88, 83,
132, 141, 121] 132, 141, 121]
Base64url encoding the above HMAC output yields the Encoded JWS Base64url encoding the above HMAC output yields the Encoded JWS
Signature value: Signature value:
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
A.1.2. Decoding A.1.2. Decoding
Decoding the JWS first requires removing the base64url encoding from Decoding the JWS first requires removing the base64url encoding from
the Encoded JWS Header, the Encoded JWS Payload, and the Encoded JWS the Encoded JWS Header, the Encoded JWS Payload, and the Encoded JWS
Signature. We base64url decode the inputs and turn them into the Signature. We base64url decode the inputs and turn them into the
corresponding byte arrays. We translate the header input byte array corresponding byte arrays. We decode the Encoded JWS Header byte
containing UTF-8 encoded characters into the JWS Header string. array containing the UTF-8 representation of the JWS Header into the
JWS Header string.
A.1.3. Validating A.1.3. Validating
Next we validate the decoded results. Since the "alg" parameter in Next we validate the decoded results. Since the "alg" parameter in
the header is "HS256", we validate the HMAC SHA-256 value contained the header is "HS256", we validate the HMAC SHA-256 value contained
in the JWS Signature. If any of the validation steps fail, the JWS in the JWS Signature. If any of the validation steps fail, the JWS
MUST be rejected. MUST be rejected.
First, we validate that the JWS Header string is legal JSON. First, we validate that the JWS Header string is legal JSON.
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 UTF-8 representation of the JWS Secured Input the correct key and the UTF-8 representation of the JWS Secured Input
as input to a SHA-256 HMAC function and then taking the output and (which is the same as the ASCII representation) as input to the HMAC
determining if it matches the JWS Signature. If it matches exactly, SHA-256 function and then taking the output and determining if it
the HMAC has been validated. matches the JWS Signature. If it matches exactly, the HMAC has been
validated.
A.2. JWS using RSA SHA-256 A.2. JWS using RSA SHA-256
A.2.1. Encoding A.2.1. Encoding
The JWS Header in this example is different from the previous example The JWS Header in this example is different from the previous example
in two ways: First, because a different algorithm is being used, the in two ways: First, because a different algorithm is being used, the
"alg" value is different. Second, for illustration purposes only, "alg" value is different. Second, for illustration purposes only,
the optional "typ" parameter is not used. (This difference is not the optional "typ" parameter is not used. (This difference is not
related to the algorithm employed.) The JWS Header used is: related to the algorithm employed.) The JWS Header used is:
{"alg":"RS256"} {"alg":"RS256"}
The following byte array contains the UTF-8 characters for the JWS
The following byte array contains the UTF-8 representation of the JWS
Header: Header:
[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]
Base64url encoding these bytes yields this Encoded JWS Header value:
Base64url encoding this UTF-8 representation yields this Encoded JWS
Header 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 Encoded JWS Payload will in the previous example. Since the Encoded JWS Payload 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",
"exp":1300819380, "exp":1300819380,
"http://example.com/is_root":true} "http://example.com/is_root":true}
Concatenating the Encoded JWS Header, a period character, and the Concatenating the Encoded JWS Header, a period character, and the
Encoded JWS Payload yields this JWS Secured Input value (with line Encoded JWS Payload yields this JWS Secured Input value (with line
breaks for display purposes only): breaks for display purposes only):
eyJhbGciOiJSUzI1NiJ9 eyJhbGciOiJSUzI1NiJ9
. .
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
The UTF-8 representation of the JWS Secured Input is the following The UTF-8 representation of the JWS Secured Input (which is the same
byte array: as the ASCII representation) is the following byte array:
[101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 122, 73, [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 122, 73,
49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, 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, 74, 108, 101, 72, 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, 107, 122, 79, 68, 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, 72, 65, 54, 76, 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, 109, 78, 118, 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, 106, 112, 48, 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48,
99, 110, 86, 108, 102, 81] 99, 110, 86, 108, 102, 81]
skipping to change at page 23, line 30 skipping to change at page 22, line 30
| | 93, 137, 138, 5, 104, 84, 19, 229, 60, 60, 108, 101, | | | 93, 137, 138, 5, 104, 84, 19, 229, 60, 60, 108, 101, |
| | 37, 255, 31, 227, 78, 61, 220, 112, 240, 213, 100, | | | 37, 255, 31, 227, 78, 61, 220, 112, 240, 213, 100, |
| | 80, 253, 164, 139, 161, 46, 16, 78, 157, 235, 159, | | | 80, 253, 164, 139, 161, 46, 16, 78, 157, 235, 159, |
| | 184, 24, 129, 225, 196, 189, 242, 93, 146, 71, 244, | | | 184, 24, 129, 225, 196, 189, 242, 93, 146, 71, 244, |
| | 80, 200, 101, 146, 121, 104, 231, 115, 52, 244, 65, | | | 80, 200, 101, 146, 121, 104, 231, 115, 52, 244, 65, |
| | 79, 117, 167, 80, 225, 57, 84, 110, 58, 138, 115, | | | 79, 117, 167, 80, 225, 57, 84, 110, 58, 138, 115, |
| | 157] | | | 157] |
+-----------+-------------------------------------------------------+ +-----------+-------------------------------------------------------+
The RSA private key (n, d) is then passed to the RSA signing The RSA private key (n, d) is then passed to the RSA signing
function, which also takes the hash type, SHA-256, and the UTF-8 function, which also takes the hash type, SHA-256, and the bytes of
representation of the JWS Secured Input as inputs. The result of the the UTF-8 representation of the JWS Secured Input (which is the same
digital signature is a byte array S, which represents a big endian as the ASCII representation) as inputs. The result of the digital
integer. In this example, S is: signature is a byte array S, which represents a big endian integer.
In this example, S is:
+--------+----------------------------------------------------------+ +--------+----------------------------------------------------------+
| Result | Value | | Result | Value |
| Name | | | Name | |
+--------+----------------------------------------------------------+ +--------+----------------------------------------------------------+
| S | [112, 46, 33, 137, 67, 232, 143, 209, 30, 181, 216, 45, | | S | [112, 46, 33, 137, 67, 232, 143, 209, 30, 181, 216, 45, |
| | 191, 120, 69, 243, 65, 6, 174, 27, 129, 255, 247, 115, | | | 191, 120, 69, 243, 65, 6, 174, 27, 129, 255, 247, 115, |
| | 17, 22, 173, 209, 113, 125, 131, 101, 109, 66, 10, 253, | | | 17, 22, 173, 209, 113, 125, 131, 101, 109, 66, 10, 253, |
| | 60, 150, 238, 221, 115, 162, 102, 62, 81, 102, 104, 123, | | | 60, 150, 238, 221, 115, 162, 102, 62, 81, 102, 104, 123, |
| | 0, 11, 135, 34, 110, 1, 135, 237, 16, 115, 249, 69, 229, | | | 0, 11, 135, 34, 110, 1, 135, 237, 16, 115, 249, 69, 229, |
skipping to change at page 25, line 10 skipping to change at page 24, line 10
Since the "alg" parameter in the header is "RS256", we validate the Since the "alg" parameter in the header is "RS256", we validate the
RSA SHA-256 digital signature contained in the JWS Signature. If any RSA SHA-256 digital signature contained in the JWS Signature. If any
of the validation steps fail, the JWS MUST be rejected. of the validation steps fail, the JWS MUST be rejected.
First, we validate that the JWS Header string is legal JSON. First, we validate that the JWS Header string is legal JSON.
Validating the JWS Signature is a little different from the previous Validating the JWS Signature is a little different from the previous
example. First, we base64url decode the Encoded JWS Signature to example. First, we base64url decode the Encoded JWS Signature to
produce a digital signature S to check. We then pass (n, e), S and produce a digital signature S to check. We then pass (n, e), S and
the UTF-8 representation of the JWS Secured Input to an RSA signature the bytes of the UTF-8 representation of the JWS Secured Input (which
verifier that has been configured to use the SHA-256 hash function. is the same as the ASCII representation) to an RSA signature verifier
that has been configured to use the SHA-256 hash function.
A.3. JWS using ECDSA P-256 SHA-256 A.3. JWS using ECDSA P-256 SHA-256
A.3.1. Encoding A.3.1. Encoding
The JWS Header for this example differs from the previous example The JWS Header for this example differs from the previous example
because a different algorithm is being used. The JWS Header used is: because a different algorithm is being used. The JWS Header used is:
{"alg":"ES256"} {"alg":"ES256"}
The following byte array contains the UTF-8 characters for the JWS The following byte array contains the UTF-8 representation of the JWS
Header: Header:
[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]
Base64url encoding this UTF-8 representation yields this Encoded JWS Base64url encoding these bytes yields this Encoded JWS Header value:
Header 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 Encoded JWS Payload will in the previous examples. Since the Encoded JWS Payload 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",
"exp":1300819380, "exp":1300819380,
"http://example.com/is_root":true} "http://example.com/is_root":true}
Concatenating the Encoded JWS Header, a period character, and the Concatenating the Encoded JWS Header, a period character, and the
Encoded JWS Payload yields this JWS Secured Input value (with line Encoded JWS Payload yields this JWS Secured Input value (with line
breaks for display purposes only): breaks for display purposes only):
eyJhbGciOiJFUzI1NiJ9 eyJhbGciOiJFUzI1NiJ9
. .
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
The UTF-8 representation of the JWS Secured Input is the following The UTF-8 representation of the JWS Secured Input (which is the same
byte array: as the ASCII representation) is the following byte array:
[101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 70, 85, 122, 73, [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 70, 85, 122, 73,
49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, 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, 74, 108, 101, 72, 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, 107, 122, 79, 68, 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, 72, 65, 54, 76, 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, 109, 78, 118, 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, 106, 112, 48, 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48,
99, 110, 86, 108, 102, 81] 99, 110, 86, 108, 102, 81]
skipping to change at page 26, line 29 skipping to change at page 25, line 29
| y | [199, 241, 68, 205, 27, 189, 155, 126, 135, 44, 223, | | y | [199, 241, 68, 205, 27, 189, 155, 126, 135, 44, 223, |
| | 237, 185, 238, 185, 244, 179, 105, 93, 110, 169, 11, | | | 237, 185, 238, 185, 244, 179, 105, 93, 110, 169, 11, |
| | 36, 173, 138, 70, 35, 40, 133, 136, 229, 173] | | | 36, 173, 138, 70, 35, 40, 133, 136, 229, 173] |
| d | [142, 155, 16, 158, 113, 144, 152, 191, 152, 4, 135, | | d | [142, 155, 16, 158, 113, 144, 152, 191, 152, 4, 135, |
| | 223, 31, 93, 119, 233, 203, 41, 96, 110, 190, 210, | | | 223, 31, 93, 119, 233, 203, 41, 96, 110, 190, 210, |
| | 38, 59, 95, 87, 194, 19, 223, 132, 244, 178] | | | 38, 59, 95, 87, 194, 19, 223, 132, 244, 178] |
+-----------+-------------------------------------------------------+ +-----------+-------------------------------------------------------+
The ECDSA private part d is then passed to an ECDSA signing function, The ECDSA private part d is then passed to an ECDSA signing function,
which also takes the curve type, P-256, the hash type, SHA-256, and which also takes the curve type, P-256, the hash type, SHA-256, and
the UTF-8 representation of the JWS Secured Input as inputs. The the bytes of the UTF-8 representation of the JWS Secured Input (which
result of the digital signature is the EC point (R, S), where R and S is the same as the ASCII representation) as inputs. The result of
are unsigned integers. In this example, the R and S values, given as the digital signature is the EC point (R, S), where R and S are
unsigned integers. In this example, the R and S values, given as
byte arrays representing big endian integers are: byte arrays representing big endian integers are:
+--------+----------------------------------------------------------+ +--------+----------------------------------------------------------+
| Result | Value | | Result | Value |
| Name | | | Name | |
+--------+----------------------------------------------------------+ +--------+----------------------------------------------------------+
| R | [14, 209, 33, 83, 121, 99, 108, 72, 60, 47, 127, 21, 88, | | R | [14, 209, 33, 83, 121, 99, 108, 72, 60, 47, 127, 21, 88, |
| | 7, 212, 2, 163, 178, 40, 3, 58, 249, 124, 126, 23, 129, | | | 7, 212, 2, 163, 178, 40, 3, 58, 249, 124, 126, 23, 129, |
| | 154, 195, 22, 158, 166, 101] | | | 154, 195, 22, 158, 166, 101] |
| S | [197, 10, 7, 211, 140, 60, 112, 229, 216, 241, 45, 175, | | S | [197, 10, 7, 211, 140, 60, 112, 229, 216, 241, 45, 175, |
skipping to change at page 27, line 23 skipping to change at page 26, line 23
Since the "alg" parameter in the header is "ES256", we validate the Since the "alg" parameter in the header is "ES256", we validate the
ECDSA P-256 SHA-256 digital signature contained in the JWS Signature. ECDSA P-256 SHA-256 digital signature contained in the JWS Signature.
If any of the validation steps fail, the JWS MUST be rejected. If any of the validation steps fail, the JWS MUST be rejected.
First, we validate that the JWS Header string is legal JSON. First, we validate that the JWS Header string is legal JSON.
Validating the JWS Signature is a little different from the first Validating the JWS Signature is a little different from the first
example. First, we base64url decode the Encoded JWS Signature as in example. First, we base64url decode the Encoded JWS Signature as in
the previous examples but we then need to split the 64 member byte the previous examples but we then need to split the 64 member byte
array that must result into two 32 byte arrays, the first R and the array that must result into two 32 byte arrays, the first R and the
second S. We then pass (x, y), (R, S) and the UTF-8 representation of second S. We then pass (x, y), (R, S) and the bytes of the UTF-8
the JWS Secured Input to an ECDSA signature verifier that has been representation of the JWS Secured Input (which is the same as the
ASCII representation) to an ECDSA signature verifier that has been
configured to use the P-256 curve with the SHA-256 hash function. configured to use the P-256 curve with the SHA-256 hash function.
As explained in Section 3.3 of the JSON Web Algorithms (JWA) [JWA] As explained in Section 3.4 of the JSON Web Algorithms (JWA) [JWA]
specification, the use of the k value in ECDSA means that we cannot specification, the use of the k value in ECDSA means that we cannot
validate the correctness of the digital signature in the same way we validate the correctness of the digital signature in the same way we
validated the correctness of the HMAC. Instead, implementations MUST validated the correctness of the HMAC. Instead, implementations MUST
use an ECDSA validator to validate the digital signature. use an ECDSA validator to validate the digital signature.
A.4. Example Plaintext JWS A.4. Example Plaintext JWS
The following example JWS Header declares that the encoded object is The following example JWS Header declares that the encoded object is
a Plaintext JWS: a Plaintext JWS:
{"alg":"none"} {"alg":"none"}
skipping to change at page 29, line 23 skipping to change at page 28, line 24
Appendix C. Acknowledgements Appendix C. Acknowledgements
Solutions for signing JSON content were previously explored by Magic Solutions for signing JSON content were previously explored by Magic
Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas
Applications [CanvasApp], all of which influenced this draft. Dirk Applications [CanvasApp], all of which influenced this draft. Dirk
Balfanz, Yaron Y. Goland, John Panzer, and Paul Tarjan all made Balfanz, Yaron Y. Goland, John Panzer, and Paul Tarjan all made
significant contributions to the design of this specification. significant contributions to the design of this specification.
Appendix D. Document History Appendix D. Document History
-02
o Clarified that it is an error when a "kid" value is included and
no matching key is found.
o Removed assumption that "kid" (key ID) can only refer to an
asymmetric key.
o Clarified that JWSs with duplicate Header Parameter Names MUST be
rejected.
o Clarified the relationship between "typ" header parameter values
and MIME types.
o Registered application/jws MIME type and "JWS" typ header
parameter value.
o Simplified JWK terminology to get replace the "JWK Key Object" and
"JWK Container Object" terms with simply "JSON Web Key (JWK)" and
"JSON Web Key Set (JWK Set)" and to eliminate potential confusion
between single keys and sets of keys. As part of this change, the
header parameter name for a public key value was changed from
"jpk" (JSON Public Key) to "jwk" (JSON Web Key).
o Added suggestion on defining additional header parameters such as
"x5t#S256" in the future for certificate thumbprints using hash
algorithms other than SHA-1.
o Specify RFC 2818 server identity validation, rather than RFC 6125
(paralleling the same decision in the OAuth specs).
o Generalized language to refer to Message Authentication Codes
(MACs) rather than Hash-based Message Authentication Codes (HMACs)
unless in a context specific to HMAC algorithms.
o Reformatted to give each header parameter its own section heading.
-01 -01
o Moved definition of Plaintext JWSs (using "alg":"none") here from o Moved definition of Plaintext JWSs (using "alg":"none") here from
the JWT specification since this functionality is likely to be the JWT specification since this functionality is likely to be
useful in more contexts that just for JWTs. useful in more contexts that just for JWTs.
o Added "jpk" and "x5c" header parameters for including JWK public o Added "jpk" and "x5c" header parameters for including JWK public
keys and X.509 certificate chains directly in the header. keys and X.509 certificate chains directly in the header.
o Clarified that this specification is defining the JWS Compact o Clarified that this specification is defining the JWS Compact
skipping to change at page 30, line 25 skipping to change at page 30, line 14
Authors' Addresses Authors' Addresses
Michael B. Jones Michael B. Jones
Microsoft Microsoft
Email: mbj@microsoft.com Email: mbj@microsoft.com
URI: http://self-issued.info/ URI: http://self-issued.info/
John Bradley John Bradley
independent Ping Identity
Email: ve7jtb@ve7jtb.com Email: ve7jtb@ve7jtb.com
Nat Sakimura Nat Sakimura
Nomura Research Institute Nomura Research Institute
Email: n-sakimura@nri.co.jp Email: n-sakimura@nri.co.jp
 End of changes. 73 change blocks. 
414 lines changed or deleted 425 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/