draft-ietf-jose-json-web-signature-00.txt   draft-ietf-jose-json-web-signature-01.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: July 19, 2012 independent Expires: September 13, 2012 independent
N. Sakimura N. Sakimura
Nomura Research Institute Nomura Research Institute
January 16, 2012 March 12, 2012
JSON Web Signature (JWS) JSON Web Signature (JWS)
draft-ietf-jose-json-web-signature-00 draft-ietf-jose-json-web-signature-01
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 Hash-based Message Authentication Codes
(HMACs) using JSON data structures. Cryptographic algorithms and (HMACs) using JSON data structures. Cryptographic algorithms and
identifiers used with this specification are enumerated in the identifiers used with this specification are enumerated in the
separate JSON Web Algorithms (JWA) specification. Related encryption separate JSON Web Algorithms (JWA) specification. Related encryption
capabilities are described in the separate JSON Web Encryption (JWE) capabilities are described in the separate JSON Web Encryption (JWE)
specification. specification.
skipping to change at page 1, line 45 skipping to change at page 1, line 45
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 July 19, 2012. This Internet-Draft will expire on September 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 2, line 24 skipping to change at page 3, line 13
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 . . . . . . . . . . . . . 6
4.2. Public Header Parameter Names . . . . . . . . . . . . . . 10 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 11
4.3. Private Header Parameter Names . . . . . . . . . . . . . . 10 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 11
5. Rules for Creating and Validating a JWS . . . . . . . . . . . 10 5. Rules for Creating and Validating a JWS . . . . . . . . . . . 11
6. Securing JWSs with Cryptographic Algorithms . . . . . . . . . 12 6. Securing JWSs with Cryptographic Algorithms . . . . . . . . . 13
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
8. Security Considerations . . . . . . . . . . . . . . . . . . . 13 8. Security Considerations . . . . . . . . . . . . . . . . . . . 14
8.1. Unicode Comparison Security Issues . . . . . . . . . . . . 13 8.1. Unicode Comparison Security Issues . . . . . . . . . . . . 15
9. Open Issues and Things To Be Done (TBD) . . . . . . . . . . . 14 9. Open Issues and Things To Be Done (TBD) . . . . . . . . . . . 15
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16
10.1. Normative References . . . . . . . . . . . . . . . . . . . 15 10.1. Normative References . . . . . . . . . . . . . . . . . . . 16
10.2. Informative References . . . . . . . . . . . . . . . . . . 16 10.2. Informative References . . . . . . . . . . . . . . . . . . 18
Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 16 Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 18
A.1. JWS using HMAC SHA-256 . . . . . . . . . . . . . . . . . . 17 A.1. JWS using HMAC SHA-256 . . . . . . . . . . . . . . . . . . 18
A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 17 A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 18
A.1.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 18 A.1.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 20
A.1.3. Validating . . . . . . . . . . . . . . . . . . . . . . 19 A.1.3. Validating . . . . . . . . . . . . . . . . . . . . . . 20
A.2. JWS using RSA SHA-256 . . . . . . . . . . . . . . . . . . 19 A.2. JWS using RSA SHA-256 . . . . . . . . . . . . . . . . . . 20
A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 19 A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 20
A.2.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 22 A.2.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 24
A.2.3. Validating . . . . . . . . . . . . . . . . . . . . . . 22 A.2.3. Validating . . . . . . . . . . . . . . . . . . . . . . 24
A.3. JWS using ECDSA P-256 SHA-256 . . . . . . . . . . . . . . 23 A.3. JWS using ECDSA P-256 SHA-256 . . . . . . . . . . . . . . 25
A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 23 A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 25
A.3.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 25 A.3.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 27
A.3.3. Validating . . . . . . . . . . . . . . . . . . . . . . 25 A.3.3. Validating . . . . . . . . . . . . . . . . . . . . . . 27
A.4. Example Plaintext JWS . . . . . . . . . . . . . . . . . . 27
Appendix B. Notes on implementing base64url encoding without Appendix B. Notes on implementing base64url encoding without
padding . . . . . . . . . . . . . . . . . . . . . . . 25 padding . . . . . . . . . . . . . . . . . . . . . . . 28
Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 26 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 29
Appendix D. Document History . . . . . . . . . . . . . . . . . . 27 Appendix D. Document History . . . . . . . . . . . . . . . . . . 29
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 27 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 Hash-based Message Authentication
Codes (HMACs) intended for space constrained environments such as Codes (HMACs) intended for space constrained environments such as
HTTP Authorization headers and URI query parameters. It represents HTTP Authorization headers and URI query parameters. It represents
this content using JSON [RFC4627] data structures. The JWS digital this content using JSON [RFC4627] data structures. The JWS digital
signature and HMAC mechanisms are independent of the type of content signature and HMAC mechanisms are independent of the type of content
being secured, allowing arbitrary content to be secured. being secured, allowing arbitrary content to be secured.
skipping to change at page 5, line 5 skipping to change at page 5, line 5
JWS Secured Input The concatenation of the Encoded JWS Header, a JWS Secured Input The concatenation of the Encoded JWS Header, a
period ('.') character, and the Encoded JWS Payload. period ('.') character, and the Encoded JWS Payload.
Header Parameter Names The names of the members within the JSON Header Parameter Names The names of the members within the JSON
object represented in a JWS Header. object represented in a JWS Header.
Header Parameter Values The values of the members within the JSON Header Parameter Values The values of the members within the JSON
object represented in a JWS Header. object represented in a JWS Header.
JWS Compact Serialization A representation of the JWS as the
concatenation of the Encoded JWS Header, the Encoded JWS Payload,
and the Encoded JWS Signature in that order, with the three
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.)
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 HMACed 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.
The three parts are base64url-encoded for transmission, and typically In the Compact Serialization, the three parts are base64url-encoded
represented as the concatenation of the encoded strings in that for transmission, and represented as the concatenation of the encoded
order, with the three strings being separated by period ('.') strings in that order, with the three strings being separated by
characters. period ('.') characters. (A JSON Serialization for this information
is defined in the separate JSON Web Signature JSON Serialization
(JWS-JS) [JWS-JS] specification.)
The JWS Header describes the signature or HMAC method and parameters The JWS Header describes the signature or HMAC 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
skipping to change at page 7, line 5 skipping to change at page 7, line 6
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. All the names are
short because a core goal of JWSs is for the representations to be short because a core goal of JWSs is for the representations to be
compact. compact.
+-----------+--------+-------------+--------------------------------+ +-----------+--------+----------------+-----------------------------+
| Header | JSON | Header | Header Parameter Semantics | | Header | JSON | Header | Header Parameter Semantics |
| Parameter | Value | Parameter | | | Parameter | Value | Parameter | |
| Name | Type | Syntax | | | Name | Type | Syntax | |
+-----------+--------+-------------+--------------------------------+ +-----------+--------+----------------+-----------------------------+
| alg | string | StringOrURI | The "alg" (algorithm) header | | alg | string | StringOrURI | The "alg" (algorithm) |
| | | | parameter identifies the | | | | | header parameter identifies |
| | | | cryptographic algorithm used | | | | | the cryptographic algorithm |
| | | | to secure the JWS. A list of | | | | | used to secure the JWS. A |
| | | | defined "alg" values is | | | | | list of defined "alg" |
| | | | presented in Section 3, Table | | | | | values is presented in |
| | | | 1 of the JSON Web Algorithms | | | | | Section 3, Table 1 of the |
| | | | (JWA) [JWA] specification. | | | | | JSON Web Algorithms (JWA) |
| | | | The processing of the "alg" | | | | | [JWA] specification. The |
| | | | header parameter requires that | | | | | processing of the "alg" |
| | | | the value MUST be one that is | | | | | header parameter requires |
| | | | both supported and for which | | | | | that the value MUST be one |
| | | | there exists a key for use | | | | | that is both supported and |
| | | | with that algorithm associated | | | | | for which there exists a |
| | | | with the party that digitally | | | | | key for use with that |
| | | | signed or HMACed the content. | | | | | algorithm associated with |
| | | | The "alg" parameter value is | | | | | the party that digitally |
| | | | case sensitive. This header | | | | | signed or HMACed the |
| | | | parameter is REQUIRED. | | | | | content. The "alg" |
| typ | string | String | The "typ" (type) header | | | | | parameter value is case |
| | | | parameter is used to declare | | | | | sensitive. This header |
| | | | the type of the secured | | | | | parameter is REQUIRED. |
| | | | content. The "typ" value is | | jku | string | URL | The "jku" (JSON Web Key |
| | | | case sensitive. This header | | | | | URL) header parameter is an |
| | | | parameter is OPTIONAL. | | | | | absolute URL that refers to |
| jku | string | URL | The "jku" (JSON Web Key URL) | | | | | a resource for a set of |
| | | | header parameter is an | | | | | JSON-encoded public keys, |
| | | | absolute URL that refers to a | | | | | one of which corresponds to |
| | | | resource for a set of | | | | | the key that was used to |
| | | | JSON-encoded public keys, one | | | | | digitally sign the JWS. |
| | | | of which corresponds to the | | | | | The keys MUST be encoded as |
| | | | key that was used to digitally | | | | | described in the JSON Web |
| | | | sign the JWS. The keys MUST | | | | | Key (JWK) [JWK] |
| | | | be encoded as described in the | | | | | specification. The |
| | | | JSON Web Key (JWK) [JWK] | | | | | protocol used to acquire |
| | | | specification. The protocol | | | | | the resource MUST provide |
| | | | used to acquire the resource | | | | | integrity protection. An |
| | | | MUST provide integrity | | | | | HTTP GET request to |
| | | | protection. An HTTP GET | | | | | retrieve the certificate |
| | | | request to retrieve the | | | | | MUST use TLS RFC 2818 |
| | | | certificate MUST use TLS RFC | | | | | [RFC2818] RFC 5246 |
| | | | 2818 [RFC2818] RFC 5246 | | | | | [RFC5246] with server |
| | | | [RFC5246] with server | | | | | authentication RFC 6125 |
| | | | authentication RFC 6125 | | | | | [RFC6125]. This header |
| | | | [RFC6125]. This header | | | | | parameter is OPTIONAL. |
| | | | parameter is OPTIONAL. | | kid | string | String | The "kid" (key ID) header |
| kid | string | String | The "kid" (key ID) header | | | | | parameter is a hint |
| | | | parameter is a hint indicating | | | | | indicating which specific |
| | | | which specific key owned by | | | | | key owned by the signer |
| | | | the signer should be used to | | | | | should be used to validate |
| | | | validate the digital | | | | | the digital signature. |
| | | | signature. This allows | | | | | This allows signers to |
| | | | signers to explicitly signal a | | | | | explicitly signal a change |
| | | | change of key to recipients. | | | | | of key to recipients. The |
| | | | The interpretation of the | | | | | interpretation of the |
| | | | contents of the "kid" | | | | | contents of the "kid" |
| | | | parameter is unspecified. | | | | | parameter is unspecified. |
| | | | This header parameter is | | | | | This header parameter is |
| | | | OPTIONAL. | | | | | OPTIONAL. |
| x5u | string | URL | The "x5u" (X.509 URL) header | | jpk | object | JWK Key Object | The "jpk" (JSON Public Key) |
| | | | parameter is an absolute URL | | | | | header parameter is a |
| | | | that refers to a resource for | | | | | public key that corresponds |
| | | | the X.509 public key | | | | | to the key that was used to |
| | | | certificate or certificate | | | | | digitally sign the JWS. |
| | | | chain corresponding to the key | | | | | This key is represented in |
| | | | used to digitally sign the | | | | | the same manner as a JSON |
| | | | JWS. The identified resource | | | | | Web Key [JWK] JWK Key |
| | | | MUST provide a representation | | | | | Object value. This header |
| | | | of the certificate or | | | | | parameter is OPTIONAL. |
| | | | certificate chain that | | x5u | string | URL | The "x5u" (X.509 URL) |
| | | | conforms to RFC 5280 [RFC5280] | | | | | header parameter is an |
| | | | in PEM encoded form RFC 1421 | | | | | absolute URL that refers to |
| | | | [RFC1421]. The protocol used | | | | | a resource for the X.509 |
| | | | to acquire the resource MUST | | | | | public key certificate or |
| | | | provide integrity protection. | | | | | certificate chain |
| | | | An HTTP GET request to | | | | | corresponding to the key |
| | | | retrieve the certificate MUST | | | | | used to digitally sign the |
| | | | use TLS RFC 2818 [RFC2818] RFC | | | | | JWS. The identified |
| | | | 5246 [RFC5246] with server | | | | | resource MUST provide a |
| | | | authentication RFC 6125 | | | | | representation of the |
| | | | [RFC6125]. This header | | | | | certificate or certificate |
| | | | parameter is OPTIONAL. | | | | | chain that conforms to RFC |
| x5t | string | String | The "x5t" (x.509 certificate | | | | | 5280 [RFC5280] in PEM |
| | | | thumbprint) header parameter | | | | | encoded form RFC 1421 |
| | | | provides a base64url encoded | | | | | [RFC1421]. The certificate |
| | | | SHA-1 thumbprint (a.k.a. | | | | | containing the public key |
| | | | digest) of the DER encoding of | | | | | of the entity signing the |
| | | | an X.509 certificate that can | | | | | JWS MUST be the first |
| | | | be used to match the | | | | | certificate. This MAY be |
| | | | certificate. This header | | | | | followed by additional |
| | | | parameter is OPTIONAL. | | | | | 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 Table 1: Reserved Header Parameter Definitions
Additional reserved header parameter names MAY be defined via the Additional reserved header parameter names MAY be defined via the
IANA JSON Web Signature Header Parameters registry, as per Section 7. IANA JSON Web Signature Header Parameters registry, as per Section 7.
The syntax values used above are defined as follows: The syntax values used above are defined as follows:
+-------------+-----------------------------------------------------+ +----------------+--------------------------------------------------+
| Syntax Name | Syntax Definition | | Syntax Name | Syntax Definition |
+-------------+-----------------------------------------------------+ +----------------+--------------------------------------------------+
| IntDate | The number of seconds from 1970-01-01T0:0:0Z as | | IntDate | The number of seconds from 1970-01-01T0:0:0Z as |
| | measured in UTC until the desired date/time. See | | | measured in UTC until the desired date/time. |
| | RFC 3339 [RFC3339] for details regarding date/times | | | See RFC 3339 [RFC3339] for details regarding |
| | in general and UTC in particular. | | | date/times in general and UTC in particular. |
| String | Any string value MAY be used. | | String | Any string value MAY be used. |
| StringOrURI | Any string value MAY be used but a value containing | | StringOrURI | Any string value MAY be used but a value |
| | a ":" character MUST be a URI as defined in RFC | | | containing a ":" character MUST be a URI as |
| | 3986 [RFC3986]. | | | defined in RFC 3986 [RFC3986]. |
| URL | A URL as defined in RFC 1738 [RFC1738]. | | URL | A URL as defined in RFC 1738 [RFC1738]. |
+-------------+-----------------------------------------------------+ | ArrayOfStrings | An array of string values. |
+----------------+--------------------------------------------------+
Table 2: Header Parameter Syntax Definitions Table 2: Header Parameter Syntax Definitions
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 or algorithm value SHOULD either be defined in the IANA JSON Web
Signature Header Parameters registry or be defined as a URI that Signature Header Parameters registry or be defined as a URI that
contains a collision resistant namespace. In each case, the definer contains a collision resistant namespace. In each case, the definer
of the name or value needs to take reasonable precautions to make of the name or value needs to take reasonable precautions to make
sure they are in control of the part of the namespace they use to sure they are in control of the part of the namespace they use to
define the header parameter name. define the header parameter name.
New header parameters should be introduced sparingly, as they can New header parameters should be introduced sparingly since an
result in non-interoperable JWSs. implementation that does not understand a parameter MUST reject the
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 New header parameters should be introduced sparingly, as they can
result in non-interoperable JWSs. 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: To create a JWS, one MUST perform these steps. The order of the
steps is not significant in cases where there are no dependencies
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.
3. Create a JWS Header containing the desired set of header 3. Create a JWS Header containing the desired set of header
parameters. Note that white space is explicitly allowed in the parameters. Note that white space is explicitly allowed in the
representation and no canonicalization is 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. (Note that if the JWS
represents a JWT, this corresponds to the portion of the JWT represents a JWT, this corresponds to the portion of the JWT
representation preceding the second period character.) The "alg" representation preceding the second period character.) The "alg"
(algorithm) header parameter MUST be present in the JSON Header, (algorithm) header parameter MUST be present in the JSON Header,
with the algorithm value accurately representing the algorithm with the algorithm value accurately representing the algorithm
used to construct the JWS Signature. 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.
When validating a JWS, the following steps MUST be taken. If any of 7. The three encoded parts, taken together, are the result. The
Compact Serialization of this result is the concatenation of the
Encoded JWS Header, the Encoded JWS Payload, and the Encoded JWS
Signature in that order, with the three strings being separated
by period ('.') characters.
When validating a JWS, the following steps MUST be taken. The order
of the steps is not significant in cases where there are no
dependencies between the inputs and outputs of the steps. If any of
the listed steps fails, then the JWS MUST be rejected. the listed steps fails, then the JWS MUST be rejected.
1. The Encoded JWS Header MUST be successfully base64url decoded 1. Parse the three parts of the input (which are separated by period
characters when using the JWS Compact Serialization) into the
Encoded JWS Header, the Encoded JWS Payload, and the Encoded JWS
Signature.
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.
2. The JWS Header MUST be completely valid JSON syntax conforming to 3. The JWS Header MUST be completely valid JSON syntax conforming to
RFC 4627 [RFC4627]. RFC 4627 [RFC4627].
3. The JWS Header MUST be validated to only include parameters and 4. The JWS Header MUST be validated to only include parameters and
values whose syntax and semantics are both understood and values whose syntax and semantics are both understood and
supported. supported.
4. 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.
5. 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.
6. The JWS Signature MUST be successfully validated against the JWS 7. The JWS Signature MUST be successfully validated against the JWS
Header and JWS Payload in the manner defined for the algorithm Secured Input (the concatenation of the Encoded JWS Header, a
being used, which MUST be accurately represented by the value of period ('.') character, and the Encoded JWS Payload) in the
the "alg" (algorithm) header parameter, which MUST be present. manner defined for the algorithm being used, which MUST be
accurately represented by the value of the "alg" (algorithm)
header parameter, which MUST be present.
Processing a JWS inevitably requires comparing known strings to Processing a JWS inevitably requires comparing known strings to
values in the header. For example, in checking what the algorithm values in the header. For example, in checking what the algorithm
is, the Unicode string encoding "alg" will be checked against the is, the Unicode string encoding "alg" will be checked against the
member names in the JWS Header to see if there is a matching header member names in the JWS Header to see if there is a matching header
parameter name. A similar process occurs when determining if the parameter name. A similar process occurs when determining if the
value of the "alg" header parameter represents a supported algorithm. value of the "alg" header parameter represents a supported algorithm.
Comparisons between JSON strings and other Unicode strings MUST be Comparisons between JSON strings and other Unicode strings MUST be
performed as specified below: performed as specified below:
skipping to change at page 14, line 15 skipping to change at page 15, line 31
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 Clarify the optional ability to provide type information in the o EDITORIAL: Give each header parameter definition its own section.
JWS header. Specifically, clarify the intended use of the "typ" This will let them appear in the index, will give space for
Header Parameter, whether it conveys syntax or semantics, and examples when needed, and will get rid of the way-too-cramped
indeed, whether this is the right approach. Also clarify the tables.
relationship between these type values and MIME [RFC2045] types.
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. o Clarify the semantics of the "kid" (key ID) header parameter.
Open issues include: What happens if a "kid" header is received Open issues include: What happens if a "kid" header is received
with an unrecognized value? Is that an error? Should it be with an unrecognized value? Is that an error? Should it be
treated as if it's empty? What happens if the header has a treated as if it's empty? What happens if the header has a
recognized value but the value doesn't match the key associated recognized value but the value doesn't match the key associated
with that value, but it does match another key that is associated with that value, but it does match another key that is associated
with the issuer? Is that an error? with the issuer? Is that an error?
o Consider whether a key type parameter should also be introduced. o Consider whether a key type parameter should also be introduced.
o Add Security Considerations text on timing attacks.
o It would be good to have a confirmation method element so it could o It would be good to have a confirmation method element so it could
be used with holder-of-key. be used with holder-of-key.
o Consider whether to add parameters for directly including keys in o EDITORIAL: Think about how to best describe the concept currently
the header, either as JWK Key Objects, or X.509 cert values, or described as "the bytes of the UTF-8 representation of". Possible
both. 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 Consider whether to add version numbers. 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 Think about how to best describe the concept currently described o Add Security Considerations text on timing attacks.
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 Finish the Security Considerations section. o Finish the Security Considerations section.
o Add an example in which the payload is not a base64url encoded o EDITORIAL: Add an example in which the payload is not a base64url
JSON object. encoded JSON object.
10. References 10. References
10.1. Normative References 10.1. Normative References
[JWA] Jones, M., "JSON Web Algorithms (JWA)", January 2012. [JWA] Jones, M., "JSON Web Algorithms (JWA)", March 2012.
[JWK] Jones, M., "JSON Web Key (JWK)", January 2012. [JWK] Jones, M., "JSON Web Key (JWK)", March 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 [RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform
Resource Locators (URL)", RFC 1738, December 1994. 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
skipping to change at page 16, line 32 skipping to change at page 18, line 14
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)", January 2012. Encryption (JWE)", March 2012.
[JWS-JS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
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)",
December 2011. March 2012.
[MagicSignatures] [MagicSignatures]
Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic
Signatures", August 2010. Signatures", January 2011.
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. Note that white space is using the HMAC SHA-256 algorithm.
explicitly allowed in JWS Header strings and no canonicalization is
performed before encoding.
{"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 characters for 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 this UTF-8 representation yields this Encoded JWS
skipping to change at page 25, line 33 skipping to change at page 27, line 33
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 UTF-8 representation of
the JWS Secured Input to an ECDSA signature verifier that has been the JWS Secured Input 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.3 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
The following example JWS Header declares that the encoded object is
a Plaintext JWS:
{"alg":"none"}
Base64url encoding the bytes of the UTF-8 representation of the JWS
Header yields this Encoded JWS Header:
eyJhbGciOiJub25lIn0
The JWS Payload used in this example, which follows, is the same as
in the previous examples. Since the Encoded JWS Payload will
therefore be the same, its computation is not repeated here.
{"iss":"joe",
"exp":1300819380,
"http://example.com/is_root":true}
The Encoded JWS Signature is the empty string.
Concatenating these parts in the order Header.Payload.Signature with
period characters between the parts yields this complete JWS (with
line breaks for display purposes only):
eyJhbGciOiJub25lIn0
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
Appendix B. Notes on implementing base64url encoding without padding Appendix B. Notes on implementing base64url encoding without padding
This appendix describes how to implement base64url encoding and This appendix describes how to implement base64url encoding and
decoding functions without padding based upon standard base64 decoding functions without padding based upon standard base64
encoding and decoding functions that do use padding. encoding and decoding functions that do use padding.
To be concrete, example C# code implementing these functions is shown To be concrete, example C# code implementing these functions is shown
below. Similar code could be used in other languages. below. Similar code could be used in other languages.
static string base64urlencode(byte [] arg) static string base64urlencode(byte [] arg)
{ {
string s = Convert.ToBase64String(arg); // Standard base64 encoder string s = Convert.ToBase64String(arg); // Standard base64 encoder
s = s.Split('=')[0]; // Remove any trailing '='s s = s.Split('=')[0]; // Remove any trailing '='s
s = s.Replace('+', '-'); // 62nd char of encoding s = s.Replace('+', '-'); // 62nd char of encoding
s = s.Replace('/', '_'); // 63rd char of encoding s = s.Replace('/', '_'); // 63rd char of encoding
return s; return s;
} }
static byte [] base64urldecode(string arg) static byte [] base64urldecode(string arg)
skipping to change at page 27, line 7 skipping to change at page 29, line 23
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
-01
o Moved definition of Plaintext JWSs (using "alg":"none") here from
the JWT specification since this functionality is likely to be
useful in more contexts that just for JWTs.
o Added "jpk" and "x5c" header parameters for including JWK public
keys and X.509 certificate chains directly in the header.
o Clarified that this specification is defining the JWS Compact
Serialization. Referenced the new JWS-JS spec, which defines the
JWS JSON Serialization.
o Added text "New header parameters should be introduced sparingly
since an implementation that does not understand a parameter MUST
reject the JWS".
o Clarified that the order of the creation and validation steps is
not significant in cases where there are no dependencies between
the inputs and outputs of the steps.
o Changed "no canonicalization is performed" to "no canonicalization
need be performed".
o Corrected the Magic Signatures reference.
o Made other editorial improvements suggested by JOSE working group
participants.
-00 -00
o Created the initial IETF draft based upon o Created the initial IETF draft based upon
draft-jones-json-web-signature-04 with no normative changes. draft-jones-json-web-signature-04 with no normative changes.
o Changed terminology to no longer call both digital signatures and o Changed terminology to no longer call both digital signatures and
HMACs "signatures". HMACs "signatures".
Authors' Addresses Authors' Addresses
 End of changes. 35 change blocks. 
190 lines changed or deleted 348 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/