draft-ietf-jose-json-web-signature-29.txt   draft-ietf-jose-json-web-signature-30.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: December 22, 2014 Ping Identity Expires: January 2, 2015 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
June 20, 2014 July 1, 2014
JSON Web Signature (JWS) JSON Web Signature (JWS)
draft-ietf-jose-json-web-signature-29 draft-ietf-jose-json-web-signature-30
Abstract Abstract
JSON Web Signature (JWS) represents content secured with digital JSON Web Signature (JWS) represents content secured with digital
signatures or Message Authentication Codes (MACs) using JavaScript signatures or Message Authentication Codes (MACs) using JavaScript
Object Notation (JSON) based data structures. Cryptographic Object Notation (JSON) based data structures. Cryptographic
algorithms and identifiers for use with this specification are algorithms and identifiers for use with this specification are
described in the separate JSON Web Algorithms (JWA) specification and described in the separate JSON Web Algorithms (JWA) specification and
an IANA registry defined by that specification. Related encryption an IANA registry defined by that specification. Related encryption
capabilities are described in the separate JSON Web Encryption (JWE) capabilities are described in the separate JSON Web Encryption (JWE)
skipping to change at page 1, line 40 skipping to change at page 1, line 40
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 22, 2014. This Internet-Draft will expire on January 2, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 17 skipping to change at page 2, line 17
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
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
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. JSON Web Signature (JWS) Overview . . . . . . . . . . . . . . 6 3. JSON Web Signature (JWS) Overview . . . . . . . . . . . . . . 6
3.1. Example JWS . . . . . . . . . . . . . . . . . . . . . . . 8 3.1. JWS Compact Serialization Overview . . . . . . . . . . . . 7
3.2. JWS JSON Serialization Overview . . . . . . . . . . . . . 7
3.3. Example JWS . . . . . . . . . . . . . . . . . . . . . . . 8
4. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . . . 9 4. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.1. Registered Header Parameter Names . . . . . . . . . . . . 9 4.1. Registered Header Parameter Names . . . . . . . . . . . . 10
4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 10 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 10
4.1.2. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 10 4.1.2. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 10
4.1.3. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 10 4.1.3. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 10
4.1.4. "kid" (Key ID) Header Parameter . . . . . . . . . . . 11 4.1.4. "kid" (Key ID) Header Parameter . . . . . . . . . . . 11
4.1.5. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 11 4.1.5. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 11
4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter . . . 11 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter . . . 11
4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header 4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header
Parameter . . . . . . . . . . . . . . . . . . . . . . 12 Parameter . . . . . . . . . . . . . . . . . . . . . . 12
4.1.8. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) 4.1.8. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint)
Header Parameter . . . . . . . . . . . . . . . . . . . 12 Header Parameter . . . . . . . . . . . . . . . . . . . 12
skipping to change at page 3, line 16 skipping to change at page 3, line 18
10.1. Key Entropy . . . . . . . . . . . . . . . . . . . . . . . 25 10.1. Key Entropy . . . . . . . . . . . . . . . . . . . . . . . 25
10.2. Chosen Plaintext Attacks . . . . . . . . . . . . . . . . . 25 10.2. Chosen Plaintext Attacks . . . . . . . . . . . . . . . . . 25
10.3. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 25 10.3. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 25
10.4. Differences between Digital Signatures and MACs . . . . . 25 10.4. Differences between Digital Signatures and MACs . . . . . 25
10.5. SHA-1 Certificate Thumbprints . . . . . . . . . . . . . . 26 10.5. SHA-1 Certificate Thumbprints . . . . . . . . . . . . . . 26
10.6. JSON Security Considerations . . . . . . . . . . . . . . . 26 10.6. JSON Security Considerations . . . . . . . . . . . . . . . 26
10.7. Unicode Comparison Security Considerations . . . . . . . . 27 10.7. Unicode Comparison Security Considerations . . . . . . . . 27
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 27 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 27
11.1. Normative References . . . . . . . . . . . . . . . . . . . 27 11.1. Normative References . . . . . . . . . . . . . . . . . . . 27
11.2. Informative References . . . . . . . . . . . . . . . . . . 29 11.2. Informative References . . . . . . . . . . . . . . . . . . 29
Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 29 Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 30
A.1. Example JWS using HMAC SHA-256 . . . . . . . . . . . . . . 30 A.1. Example JWS using HMAC SHA-256 . . . . . . . . . . . . . . 30
A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 30 A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 30
A.1.2. Validating . . . . . . . . . . . . . . . . . . . . . . 32 A.1.2. Validating . . . . . . . . . . . . . . . . . . . . . . 32
A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 . . . . . . . . 32 A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 . . . . . . . . 32
A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 32 A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 32
A.2.2. Validating . . . . . . . . . . . . . . . . . . . . . . 35 A.2.2. Validating . . . . . . . . . . . . . . . . . . . . . . 35
A.3. Example JWS using ECDSA P-256 SHA-256 . . . . . . . . . . 35 A.3. Example JWS using ECDSA P-256 SHA-256 . . . . . . . . . . 35
A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 35 A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 35
A.3.2. Validating . . . . . . . . . . . . . . . . . . . . . . 37 A.3.2. Validating . . . . . . . . . . . . . . . . . . . . . . 37
A.4. Example JWS using ECDSA P-521 SHA-512 . . . . . . . . . . 38 A.4. Example JWS using ECDSA P-521 SHA-512 . . . . . . . . . . 38
skipping to change at page 7, line 31 skipping to change at page 7, line 31
JSON object that contains the Header Parameters that are not JSON object that contains the Header Parameters that are not
integrity protected. integrity protected.
This document defines two serializations for JWS objects: a compact, This document defines two serializations for JWS objects: a compact,
URL-safe serialization called the JWS Compact Serialization and a URL-safe serialization called the JWS Compact Serialization and a
JSON serialization called the JWS JSON Serialization. In both JSON serialization called the JWS JSON Serialization. In both
serializations, the JWS Protected Header, JWS Payload, and JWS serializations, the JWS Protected Header, JWS Payload, and JWS
Signature are base64url encoded for transmission, since JSON lacks a Signature are base64url encoded for transmission, since JSON lacks a
way to directly represent octet sequences. way to directly represent octet sequences.
3.1. JWS Compact Serialization Overview
In the JWS Compact Serialization, no JWS Unprotected Header is used. In the JWS Compact Serialization, no JWS Unprotected Header is used.
In this case, the JOSE Header and the JWS Protected Header are the In this case, the JOSE Header and the JWS Protected Header are the
same. same.
In the JWS Compact Serialization, a JWS object is represented as the In the JWS Compact Serialization, a JWS object is represented as the
combination of these three string values, combination of these three string values,
BASE64URL(UTF8(JWS Protected Header)), BASE64URL(UTF8(JWS Protected Header)),
BASE64URL(JWS Payload), and BASE64URL(JWS Payload), and
BASE64URL(JWS Signature), BASE64URL(JWS Signature),
concatenated in that order, with the three strings being separated by concatenated in that order, with the three strings being separated by
two period ('.') characters. two period ('.') characters.
3.2. JWS JSON Serialization Overview
In the JWS JSON Serialization, one or both of the JWS Protected In the JWS JSON Serialization, one or both of the JWS Protected
Header and JWS Unprotected Header MUST be present. In this case, the Header and JWS Unprotected Header MUST be present. In this case, the
members of the JOSE Header are the combination of the members of the members of the JOSE Header are the combination of the members of the
JWS Protected Header and the JWS Unprotected Header values that are JWS Protected Header and the JWS Unprotected Header values that are
present. present.
In the JWS JSON Serialization, a JWS object is represented as the In the JWS JSON Serialization, a JWS object is represented as the
combination of these four values, combination of these four values,
BASE64URL(UTF8(JWS Protected Header)), BASE64URL(UTF8(JWS Protected Header)),
JWS Unprotected Header, JWS Unprotected Header,
BASE64URL(JWS Payload), and BASE64URL(JWS Payload), and
BASE64URL(JWS Signature), BASE64URL(JWS Signature),
with the three base64url encoding result strings and the JWS with the three base64url encoding result strings and the JWS
Unprotected Header value being represented as members within a JSON Unprotected Header value being represented as members within a JSON
object. The inclusion of some of these values is OPTIONAL. The JWS object. The inclusion of some of these values is OPTIONAL. The JWS
JSON Serialization can also represent multiple signature and/or MAC JSON Serialization can also represent multiple signature and/or MAC
values, rather than just one. See Section 7.2 for more information values, rather than just one. See Section 7.2 for more information
about the JWS JSON Serialization. about the JWS JSON Serialization.
3.1. Example JWS 3.3. Example JWS
This section provides an example of a JWS. Its computation is This section provides an example of a JWS. Its computation is
described in more detail in Appendix A.1, including specifying the described in more detail in Appendix A.1, including specifying the
exact octet sequences representing the JSON values used and the key exact octet sequences representing the JSON values used and the key
value used. value used.
The following example JWS Protected Header declares that the encoded The following example JWS Protected Header declares that the encoded
object is a JSON Web Token (JWT) [JWT] and the JWS Protected Header object is a JSON Web Token (JWT) [JWT] and the JWS Protected Header
and the JWS Payload are secured using the HMAC SHA-256 algorithm: and the JWS Payload are secured using the HMAC SHA-256 [RFC2104, SHS]
algorithm:
{"typ":"JWT", {"typ":"JWT",
"alg":"HS256"} "alg":"HS256"}
Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected
Header)) gives this value: Header)) gives this value:
eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
The UTF-8 representation of following JSON object is used as the JWS The UTF-8 representation of following JSON object is used as the JWS
skipping to change at page 10, line 38 skipping to change at page 10, line 44
in Section 3.1 of the JSON Web Algorithms (JWA) [JWA] specification. in Section 3.1 of the JSON Web Algorithms (JWA) [JWA] specification.
4.1.2. "jku" (JWK Set URL) Header Parameter 4.1.2. "jku" (JWK Set URL) Header Parameter
The "jku" (JWK Set URL) Header Parameter is a URI [RFC3986] that The "jku" (JWK Set URL) Header Parameter is a URI [RFC3986] that
refers to a resource for a set of JSON-encoded public keys, one of refers to a resource for a set of JSON-encoded public keys, one of
which corresponds to the key used to digitally sign the JWS. The which corresponds to the key used to digitally sign the JWS. The
keys MUST be encoded as a JSON Web Key Set (JWK Set) [JWK]. The keys MUST be encoded as a JSON Web Key Set (JWK Set) [JWK]. The
protocol used to acquire the resource MUST provide integrity protocol used to acquire the resource MUST provide integrity
protection; an HTTP GET request to retrieve the JWK Set MUST use TLS protection; an HTTP GET request to retrieve the JWK Set MUST use TLS
[RFC2818] [RFC5246]; the identity of the server MUST be validated, as [RFC2818, RFC5246]; the identity of the server MUST be validated, as
per Section 6 of RFC 6125 [RFC6125]. Use of this Header Parameter is per Section 6 of RFC 6125 [RFC6125]. Use of this Header Parameter is
OPTIONAL. OPTIONAL.
4.1.3. "jwk" (JSON Web Key) Header Parameter 4.1.3. "jwk" (JSON Web Key) Header Parameter
The "jwk" (JSON Web Key) Header Parameter is the public key that The "jwk" (JSON Web Key) Header Parameter is the public key that
corresponds to the key used to digitally sign the JWS. This key is corresponds to the key used to digitally sign the JWS. This key is
represented as a JSON Web Key [JWK]. Use of this Header Parameter is represented as a JSON Web Key [JWK]. Use of this Header Parameter is
OPTIONAL. OPTIONAL.
skipping to change at page 11, line 29 skipping to change at page 11, line 30
to a resource for the X.509 public key certificate or certificate to a resource for the X.509 public key certificate or certificate
chain [RFC5280] corresponding to the key used to digitally sign the chain [RFC5280] corresponding to the key used to digitally sign the
JWS. The identified resource MUST provide a representation of the JWS. The identified resource MUST provide a representation of the
certificate or certificate chain that conforms to RFC 5280 [RFC5280] certificate or certificate chain that conforms to RFC 5280 [RFC5280]
in PEM encoded form [RFC1421]. The certificate containing the public in PEM encoded form [RFC1421]. The certificate containing the public
key corresponding to the key used to digitally sign the JWS MUST be key corresponding to the key used to digitally sign the JWS MUST be
the first certificate. This MAY be followed by additional the first certificate. This MAY be followed by additional
certificates, with each subsequent certificate being the one used to certificates, with each subsequent certificate being the one used to
certify the previous one. The protocol used to acquire the resource certify the previous one. The protocol used to acquire the resource
MUST provide integrity protection; an HTTP GET request to retrieve MUST provide integrity protection; an HTTP GET request to retrieve
the certificate MUST use TLS [RFC2818] [RFC5246]; the identity of the the certificate MUST use TLS [RFC2818, RFC5246]; the identity of the
server MUST be validated, as per Section 6 of RFC 6125 [RFC6125]. server MUST be validated, as per Section 6 of RFC 6125 [RFC6125].
Use of this Header Parameter is OPTIONAL. Use of this Header Parameter is OPTIONAL.
4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter
The "x5c" (X.509 Certificate Chain) Header Parameter contains the The "x5c" (X.509 Certificate Chain) Header Parameter contains the
X.509 public key certificate or certificate chain [RFC5280] X.509 public key certificate or certificate chain [RFC5280]
corresponding to the key used to digitally sign the JWS. The corresponding to the key used to digitally sign the JWS. The
certificate or certificate chain is represented as a JSON array of certificate or certificate chain is represented as a JSON array of
certificate value strings. Each string in the array is a base64 certificate value strings. Each string in the array is a base64
encoded ([RFC4648] Section 4 -- not base64url encoded) DER encoded ([RFC4648] Section 4 -- not base64url encoded) DER
[ITU.X690.1994] PKIX certificate value. The certificate containing [ITU.X690.1994] PKIX certificate value. The certificate containing
the public key corresponding to the key used to digitally sign the the public key corresponding to the key used to digitally sign the
JWS MUST be the first certificate. This MAY be followed by JWS MUST be the first certificate. This MAY be followed by
additional certificates, with each subsequent certificate being the additional certificates, with each subsequent certificate being the
one used to certify the previous one. The recipient MUST validate one used to certify the previous one. The recipient MUST validate
the certificate chain according to [RFC5280] and reject the signature the certificate chain according to RFC 5280 [RFC5280] and reject the
if any validation failure occurs. Use of this Header Parameter is signature if any validation failure occurs. Use of this Header
OPTIONAL. Parameter is OPTIONAL.
See Appendix B for an example "x5c" value. See Appendix B for an example "x5c" value.
4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter 4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter
The "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter is a The "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter is a
base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER
encoding of the X.509 certificate [RFC5280] corresponding to the key encoding of the X.509 certificate [RFC5280] corresponding to the key
used to digitally sign the JWS. Use of this Header Parameter is used to digitally sign the JWS. Use of this Header Parameter is
OPTIONAL. OPTIONAL.
skipping to change at page 12, line 34 skipping to change at page 12, line 34
The "typ" (type) Header Parameter is used by JWS applications to The "typ" (type) Header Parameter is used by JWS applications to
declare the MIME Media Type [IANA.MediaTypes] of this complete JWS declare the MIME Media Type [IANA.MediaTypes] of this complete JWS
object. This is intended for use by the application when more than object. This is intended for use by the application when more than
one kind of object could be present in an application data structure one kind of object could be present in an application data structure
that can contain a JWS object; the application can use this value to that can contain a JWS object; the application can use this value to
disambiguate among the different kinds of objects that might be disambiguate among the different kinds of objects that might be
present. It will typically not be used by applications when the kind present. It will typically not be used by applications when the kind
of object is already known. This parameter has no effect upon the of object is already known. This parameter has no effect upon the
JWS processing. Use of this Header Parameter is OPTIONAL. JWS processing. Use of this Header Parameter is OPTIONAL.
Per [RFC2045], all media type values, subtype values, and parameter Per RFC 2045 [RFC2045], all media type values, subtype values, and
names are case-insensitive. However, parameter values are case- parameter names are case-insensitive. However, parameter values are
sensitive unless otherwise specified for the specific parameter. case-sensitive unless otherwise specified for the specific parameter.
To keep messages compact in common situations, it is RECOMMENDED that To keep messages compact in common situations, it is RECOMMENDED that
senders omit an "application/" prefix of a media type value in a senders omit an "application/" prefix of a media type value in a
"typ" Header Parameter when no other '/' appears in the media type "typ" Header Parameter when no other '/' appears in the media type
value. A recipient using the media type value MUST treat it as if value. A recipient using the media type value MUST treat it as if
"application/" were prepended to any "typ" value not containing a "application/" were prepended to any "typ" value not containing a
'/'. For instance, a "typ" value of "example" SHOULD be used to '/'. For instance, a "typ" value of "example" SHOULD be used to
represent the "application/example" media type; whereas, the media represent the "application/example" media type; whereas, the media
type "application/example;part="1/2"" cannot be shortened to type "application/example;part="1/2"" cannot be shortened to
"example;part="1/2"". "example;part="1/2"".
skipping to change at page 13, line 19 skipping to change at page 13, line 19
The "cty" (content type) Header Parameter is used by JWS applications The "cty" (content type) Header Parameter is used by JWS applications
to declare the MIME Media Type [IANA.MediaTypes] of the secured to declare the MIME Media Type [IANA.MediaTypes] of the secured
content (the payload). This is intended for use by the application content (the payload). This is intended for use by the application
when more than one kind of object could be present in the JWS when more than one kind of object could be present in the JWS
payload; the application can use this value to disambiguate among the payload; the application can use this value to disambiguate among the
different kinds of objects that might be present. It will typically different kinds of objects that might be present. It will typically
not be used by applications when the kind of object is already known. not be used by applications when the kind of object is already known.
This parameter has no effect upon the JWS processing. Use of this This parameter has no effect upon the JWS processing. Use of this
Header Parameter is OPTIONAL. Header Parameter is OPTIONAL.
Per [RFC2045], all media type values, subtype values, and parameter Per RFC 2045 [RFC2045], all media type values, subtype values, and
names are case-insensitive. However, parameter values are case- parameter names are case-insensitive. However, parameter values are
sensitive unless otherwise specified for the specific parameter. case-sensitive unless otherwise specified for the specific parameter.
To keep messages compact in common situations, it is RECOMMENDED that To keep messages compact in common situations, it is RECOMMENDED that
senders omit an "application/" prefix of a media type value in a senders omit an "application/" prefix of a media type value in a
"cty" Header Parameter when no other '/' appears in the media type "cty" Header Parameter when no other '/' appears in the media type
value. A recipient using the media type value MUST treat it as if value. A recipient using the media type value MUST treat it as if
"application/" were prepended to any "cty" value not containing a "application/" were prepended to any "cty" value not containing a
'/'. For instance, a "cty" value of "example" SHOULD be used to '/'. For instance, a "cty" value of "example" SHOULD be used to
represent the "application/example" media type; whereas, the media represent the "application/example" media type; whereas, the media
type "application/example;part="1/2"" cannot be shortened to type "application/example;part="1/2"" cannot be shortened to
"example;part="1/2"". "example;part="1/2"".
skipping to change at page 15, line 42 skipping to change at page 15, line 42
It is an application decision which signatures, MACs, or plaintext It is an application decision which signatures, MACs, or plaintext
values must successfully validate for the JWS to be accepted. In values must successfully validate for the JWS to be accepted. In
some cases, all must successfully validate or the JWS will be some cases, all must successfully validate or the JWS will be
rejected. In other cases, only a specific signature, MAC, or rejected. In other cases, only a specific signature, MAC, or
plaintext value needs to be successfully validated. However, in all plaintext value needs to be successfully validated. However, in all
cases, at least one signature, MAC, or plaintext value MUST cases, at least one signature, MAC, or plaintext value MUST
successfully validate or the JWS MUST be rejected. successfully validate or the JWS MUST be rejected.
1. Parse the JWS representation to extract the serialized values 1. Parse the JWS representation to extract the serialized values
for the components of the JWS -- when using the JWS Compact for the components of the JWS. When using the JWS Compact
Serialization, the base64url encoded representations of the JWS Serialization, these components are the base64url encoded
Protected Header, the JWS Payload, and the JWS Signature, and representations of the JWS Protected Header, the JWS Payload,
when using the JWS JSON Serialization, also the unencoded JWS and the JWS Signature, and when using the JWS JSON
Serialization, these components also include the unencoded JWS
Unprotected Header value. When using the JWS Compact Unprotected Header value. When using the JWS Compact
Serialization, the JWS Protected Header, the JWS Payload, and Serialization, the JWS Protected Header, the JWS Payload, and
the JWS Signature are represented as base64url encoded values in the JWS Signature are represented as base64url encoded values in
that order, separated by two period ('.') characters. The JWS that order, separated by two period ('.') characters. The JWS
JSON Serialization is described in Section 7.2. JSON Serialization is described in Section 7.2.
2. The encoded representation of the JWS Protected Header MUST be 2. The encoded representation of the JWS Protected Header MUST be
successfully base64url decoded following the restriction that no successfully base64url decoded following the restriction that no
padding characters have been used. padding characters have been used.
3. The resulting octet sequence MUST be a UTF-8 encoded 3. The resulting octet sequence MUST be a UTF-8 encoded
representation of a completely valid JSON object conforming to representation of a completely valid JSON object conforming to
[RFC7159], which is the JWS Protected Header. RFC 7159 [RFC7159], which is the JWS Protected Header.
4. If using the JWS Compact Serialization, let the JOSE Header be 4. If using the JWS Compact Serialization, let the JOSE Header be
the JWS Protected Header; otherwise, when using the JWS JSON the JWS Protected Header. Otherwise, when using the JWS JSON
Serialization, let the JOSE Header be the union of the members Serialization, let the JOSE Header be the union of the members
of the corresponding JWS Protected Header and JWS Unprotected of the corresponding JWS Protected Header and JWS Unprotected
Header, all of which must be completely valid JSON objects. Header, all of which must be completely valid JSON objects.
5. The resulting JOSE Header MUST NOT contain duplicate Header 5. The resulting JOSE Header MUST NOT contain duplicate Header
Parameter names. When using the JWS JSON Serialization, this Parameter names. When using the JWS JSON Serialization, this
restriction includes that the same Header Parameter name also restriction includes that the same Header Parameter name also
MUST NOT occur in distinct JSON object values that together MUST NOT occur in distinct JSON object values that together
comprise the JOSE Header. comprise the JOSE Header.
6. Verify that the implementation understands and can process all 6. Verify that the implementation understands and can process all
fields that it is required to support, whether required by this fields that it is required to support, whether required by this
skipping to change at page 17, line 7 skipping to change at page 17, line 7
the algorithm is, the Unicode string "alg" will be checked against the algorithm is, the Unicode string "alg" will be checked against
the member names in the JOSE Header to see if there is a matching the member names in the JOSE Header to see if there is a matching
Header Parameter name. The same process is then used to determine if Header Parameter name. The same process is then used to determine if
the value of the "alg" Header Parameter represents a supported the value of the "alg" Header Parameter represents a supported
algorithm. algorithm.
Since the only string comparison operations that are performed are Since the only string comparison operations that are performed are
equality and inequality, the same rules can be used for comparing equality and inequality, the same rules can be used for comparing
both member names and member values against known strings. The JSON both member names and member values against known strings. The JSON
rules for doing member name comparison are described in Section 8.3 rules for doing member name comparison are described in Section 8.3
of [RFC7159]. of RFC 7159 [RFC7159].
Also, see the JSON security considerations in Section 10.6 and the Also, see the JSON security considerations in Section 10.6 and the
Unicode security considerations in Section 10.7. Unicode security considerations in Section 10.7.
6. Key Identification 6. Key Identification
It is necessary for the recipient of a JWS to be able to determine It is necessary for the recipient of a JWS to be able to determine
the key that was employed for the digital signature or MAC operation. the key that was employed for the digital signature or MAC operation.
The key employed can be identified using the Header Parameter methods The key employed can be identified using the Header Parameter methods
described in Section 4.1 or can be identified using methods that are described in Section 4.1 or can be identified using methods that are
skipping to change at page 20, line 20 skipping to change at page 20, line 20
Whenever TLS is used, the identity of the service provider encoded in Whenever TLS is used, the identity of the service provider encoded in
the TLS server certificate MUST be verified using the procedures the TLS server certificate MUST be verified using the procedures
described in Section 6 of RFC 6125 [RFC6125]. described in Section 6 of RFC 6125 [RFC6125].
9. IANA Considerations 9. IANA Considerations
The following registration procedure is used for all the registries The following registration procedure is used for all the registries
established by this specification. established by this specification.
Values are registered with a Specification Required [RFC5226] after a Values are registered on a Specification Required [RFC5226] basis
two-week review period on the [TBD]@ietf.org mailing list, on the after a two-week review period on the [TBD]@ietf.org mailing list, on
advice of one or more Designated Experts. However, to allow for the the advice of one or more Designated Experts. However, to allow for
allocation of values prior to publication, the Designated Expert(s) the allocation of values prior to publication, the Designated
may approve registration once they are satisfied that such a Expert(s) may approve registration once they are satisfied that such
specification will be published. a specification will be published.
Registration requests must be sent to the [TBD]@ietf.org mailing list Registration requests must be sent to the [TBD]@ietf.org mailing list
for review and comment, with an appropriate subject (e.g., "Request for review and comment, with an appropriate subject (e.g., "Request
for access token type: example"). [[ Note to the RFC Editor: The name for access token type: example"). [[ Note to the RFC Editor: The name
of the mailing list should be determined in consultation with the of the mailing list should be determined in consultation with the
IESG and IANA. Suggested name: jose-reg-review. ]] IESG and IANA. Suggested name: jose-reg-review. ]]
Within the review period, the Designated Expert(s) will either Within the review period, the Designated Expert(s) will either
approve or deny the registration request, communicating this decision approve or deny the registration request, communicating this decision
to the review list and IANA. Denials should include an explanation to the review list and IANA. Denials should include an explanation
skipping to change at page 24, line 42 skipping to change at page 24, line 42
n/a, Macintosh file type code(s): n/a n/a, Macintosh file type code(s): n/a
o Person & email address to contact for further information: Michael o Person & email address to contact for further information: Michael
B. Jones, mbj@microsoft.com B. Jones, mbj@microsoft.com
o Intended usage: COMMON o Intended usage: COMMON
o Restrictions on usage: none o Restrictions on usage: none
o Author: Michael B. Jones, mbj@microsoft.com o Author: Michael B. Jones, mbj@microsoft.com
o Change Controller: IESG o Change Controller: IESG
10. Security Considerations 10. Security Considerations
All of the security issues faced by any cryptographic application All of the security issues that are pertinent to any cryptographic
must be faced by a JWS/JWE/JWK agent. Among these issues are application must be addressed by JWS/JWE/JWK agents. Among these
protecting the user's asymmetric private and symmetric secret keys, issues are protecting the user's asymmetric private and symmetric
preventing various attacks, and helping avoid mistakes such as secret keys, preventing various attacks, and helping avoid mistakes
inadvertently encrypting a message to the wrong recipient. The such as inadvertently encrypting a message to the wrong recipient.
entire list of security considerations is beyond the scope of this The entire list of security considerations is beyond the scope of
document, but some significant concerns are listed here. this document, but some significant considerations are listed here.
All the security considerations in XML DSIG 2.0 All the security considerations in XML DSIG 2.0
[W3C.NOTE-xmldsig-core2-20130411], also apply to this specification, [W3C.NOTE-xmldsig-core2-20130411], also apply to this specification,
other than those that are XML specific. Likewise, many of the best other than those that are XML specific. Likewise, many of the best
practices documented in XML Signature Best Practices practices documented in XML Signature Best Practices
[W3C.NOTE-xmldsig-bestpractices-20130411] also apply to this [W3C.NOTE-xmldsig-bestpractices-20130411] also apply to this
specification, other than those that are XML specific. specification, other than those that are XML specific.
10.1. Key Entropy 10.1. Key Entropy
skipping to change at page 27, line 10 skipping to change at page 27, line 10
significant characters after a valid input. For instance, the input significant characters after a valid input. For instance, the input
"{"tag":"value"}ABCD" contains a valid JSON-text object followed by "{"tag":"value"}ABCD" contains a valid JSON-text object followed by
the extra characters "ABCD". Such input MUST be rejected in its the extra characters "ABCD". Such input MUST be rejected in its
entirety. entirety.
10.7. Unicode Comparison Security Considerations 10.7. Unicode Comparison Security Considerations
Header Parameter names and algorithm names are Unicode strings. For Header Parameter names and algorithm names are Unicode strings. For
security reasons, the representations of these names must be compared security reasons, the representations of these names must be compared
verbatim after performing any escape processing (as per Section 8.3 verbatim after performing any escape processing (as per Section 8.3
of [RFC7159]). This means, for instance, that these JSON strings of RFC 7159 [RFC7159]). This means, for instance, that these JSON
must compare as being equal ("sig", "\u0073ig"), whereas these must strings must compare as being equal ("sig", "\u0073ig"), whereas
all compare as being not equal to the first set or to each other these must all compare as being not equal to the first set or to each
("SIG", "Sig", "si\u0047"). other ("SIG", "Sig", "si\u0047").
JSON strings can contain characters outside the Unicode Basic JSON strings can 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.
skipping to change at page 27, line 45 skipping to change at page 27, line 45
[ITU.X690.1994] [ITU.X690.1994]
International Telecommunications Union, "Information International Telecommunications Union, "Information
Technology - ASN.1 encoding rules: Specification of Basic Technology - ASN.1 encoding rules: Specification of Basic
Encoding Rules (BER), Canonical Encoding Rules (CER) and Encoding Rules (BER), Canonical Encoding Rules (CER) and
Distinguished Encoding Rules (DER)", ITU-T Recommendation Distinguished Encoding Rules (DER)", ITU-T Recommendation
X.690, 1994. X.690, 1994.
[JWA] Jones, M., "JSON Web Algorithms (JWA)", [JWA] Jones, M., "JSON Web Algorithms (JWA)",
draft-ietf-jose-json-web-algorithms (work in progress), draft-ietf-jose-json-web-algorithms (work in progress),
June 2014. July 2014.
[JWK] Jones, M., "JSON Web Key (JWK)", [JWK] Jones, M., "JSON Web Key (JWK)",
draft-ietf-jose-json-web-key (work in progress), draft-ietf-jose-json-web-key (work in progress),
June 2014. July 2014.
[RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic
Mail: Part I: Message Encryption and Authentication Mail: Part I: Message Encryption and Authentication
Procedures", RFC 1421, February 1993. Procedures", RFC 1421, February 1993.
[RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part One: Format of Internet Message Extensions (MIME) Part One: Format of Internet Message
Bodies", RFC 2045, November 1996. Bodies", RFC 2045, November 1996.
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
skipping to change at page 29, line 15 skipping to change at page 29, line 15
11.2. Informative References 11.2. Informative References
[CanvasApp] [CanvasApp]
Facebook, "Canvas Applications", 2010. Facebook, "Canvas Applications", 2010.
[JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign",
September 2010. September 2010.
[JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
draft-ietf-jose-json-web-encryption (work in progress), draft-ietf-jose-json-web-encryption (work in progress),
June 2014. July 2014.
[JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", draft-ietf-oauth-json-web-token (work in (JWT)", draft-ietf-oauth-json-web-token (work in
progress), June 2014. progress), July 2014.
[MagicSignatures] [MagicSignatures]
Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic
Signatures", January 2011. Signatures", January 2011.
[RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
Hashing for Message Authentication", RFC 2104,
February 1997.
[RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally
Unique IDentifier (UUID) URN Namespace", RFC 4122, Unique IDentifier (UUID) URN Namespace", RFC 4122,
July 2005. July 2005.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226, IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008. May 2008.
[SHS] National Institute of Standards and Technology, "Secure
Hash Standard (SHS)", FIPS PUB 180-3, October 2008.
[W3C.NOTE-xmldsig-bestpractices-20130411] [W3C.NOTE-xmldsig-bestpractices-20130411]
Hirsch, F. and P. Datta, "XML Signature Best Practices", Hirsch, F. and P. Datta, "XML Signature Best Practices",
World Wide Web Consortium Note NOTE-xmldsig-bestpractices- World Wide Web Consortium Note NOTE-xmldsig-bestpractices-
20130411, April 2013, <http://www.w3.org/TR/2013/ 20130411, April 2013, <http://www.w3.org/TR/2013/
NOTE-xmldsig-bestpractices-20130411/>. NOTE-xmldsig-bestpractices-20130411/>.
[W3C.NOTE-xmldsig-core2-20130411] [W3C.NOTE-xmldsig-core2-20130411]
Eastlake, D., Reagle, J., Solo, D., Hirsch, F., Roessler, Eastlake, D., Reagle, J., Solo, D., Hirsch, F., Roessler,
T., Yiu, K., Datta, P., and S. Cantor, "XML Signature T., Yiu, K., Datta, P., and S. Cantor, "XML Signature
Syntax and Processing Version 2.0", World Wide Web Syntax and Processing Version 2.0", World Wide Web
skipping to change at page 49, line 15 skipping to change at page 49, line 15
Thanks to Axel Nennker for his early implementation and feedback on Thanks to Axel Nennker for his early implementation and feedback on
the JWS and JWE specifications. the JWS and JWE specifications.
This specification is the work of the JOSE Working Group, which This specification is the work of the JOSE Working Group, which
includes dozens of active and dedicated participants. In particular, includes dozens of active and dedicated participants. In particular,
the following individuals contributed ideas, feedback, and wording the following individuals contributed ideas, feedback, and wording
that influenced this specification: that influenced this specification:
Dirk Balfanz, Richard Barnes, Brian Campbell, Breno de Medeiros, Dick Dirk Balfanz, Richard Barnes, Brian Campbell, Breno de Medeiros, Dick
Hardt, Joe Hildebrand, Jeff Hodges, Edmund Jay, Yaron Y. Goland, Ben Hardt, Joe Hildebrand, Jeff Hodges, Edmund Jay, Yaron Y. Goland, Ben
Laurie, James Manger, Matt Miller, Tony Nadalin, Hideki Nara, Axel Laurie, James Manger, Matt Miller, Kathleen Moriarty, Tony Nadalin,
Nennker, John Panzer, Emmanuel Raviart, Eric Rescorla, Jim Schaad, Hideki Nara, Axel Nennker, John Panzer, Emmanuel Raviart, Eric
Paul Tarjan, Hannes Tschofenig, and Sean Turner. Rescorla, Jim Schaad, Paul Tarjan, Hannes Tschofenig, and Sean
Turner.
Jim Schaad and Karen O'Donoghue chaired the JOSE working group and Jim Schaad and Karen O'Donoghue chaired the JOSE working group and
Sean Turner, Stephen Farrell, and Kathleen Moriarty served as Sean Turner, Stephen Farrell, and Kathleen Moriarty served as
Security area directors during the creation of this specification. Security area directors during the creation of this specification.
Appendix H. Document History Appendix H. Document History
[[ to be removed by the RFC Editor before publication as an RFC ]] [[ to be removed by the RFC Editor before publication as an RFC ]]
-30
o Added subsection headings within the Overview section for the two
serializations.
o Added references and cleaned up the reference syntax in a few
places.
o Applied minor wording changes to the Security Considerations
section and made other local editorial improvements.
-29 -29
o Replaced the terms JWS Header, JWE Header, and JWT Header with a o Replaced the terms JWS Header, JWE Header, and JWT Header with a
single JOSE Header term defined in the JWS specification. This single JOSE Header term defined in the JWS specification. This
also enabled a single Header Parameter definition to be used and also enabled a single Header Parameter definition to be used and
reduced other areas of duplication between specifications. reduced other areas of duplication between specifications.
-28 -28
o Revised the introduction to the Security Considerations section. o Revised the introduction to the Security Considerations section.
 End of changes. 31 change blocks. 
51 lines changed or deleted 78 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/