draft-ietf-jose-json-web-signature-37.txt   draft-ietf-jose-json-web-signature-38.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: May 23, 2015 Ping Identity Expires: June 12, 2015 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
November 19, 2014 December 9, 2014
JSON Web Signature (JWS) JSON Web Signature (JWS)
draft-ietf-jose-json-web-signature-37 draft-ietf-jose-json-web-signature-38
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 May 23, 2015. This Internet-Draft will expire on June 12, 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 5, line 14 skipping to change at page 5, line 14
1. Introduction 1. Introduction
JSON Web Signature (JWS) represents content secured with digital JSON Web Signature (JWS) represents content secured with digital
signatures or Message Authentication Codes (MACs) using JavaScript signatures or Message Authentication Codes (MACs) using JavaScript
Object Notation (JSON) [RFC7159] based data structures. The JWS Object Notation (JSON) [RFC7159] based data structures. The JWS
cryptographic mechanisms provide integrity protection for an cryptographic mechanisms provide integrity protection for an
arbitrary sequence of octets. See Section 10.5 for a discussion on arbitrary sequence of octets. See Section 10.5 for a discussion on
the differences between Digital Signatures and MACs. the differences between Digital Signatures and MACs.
Two closely related serializations for JWS objects are defined. The Two closely related serializations for JWSs are defined. The JWS
JWS Compact Serialization is a compact, URL-safe representation Compact Serialization is a compact, URL-safe representation intended
intended for space constrained environments such as HTTP for space constrained environments such as HTTP Authorization headers
Authorization headers and URI query parameters. The JWS JSON and URI query parameters. The JWS JSON Serialization represents JWSs
Serialization represents JWS objects as JSON objects and enables as JSON objects and enables multiple signatures and/or MACs to be
multiple signatures and/or MACs to be applied to the same content. applied to the same content. Both share the same cryptographic
Both share the same cryptographic underpinnings. underpinnings.
Cryptographic algorithms and identifiers for use with this Cryptographic algorithms and identifiers for use with this
specification are described in the separate JSON Web Algorithms (JWA) specification are described in the separate JSON Web Algorithms (JWA)
[JWA] specification and an IANA registry defined by that [JWA] specification and an IANA registry defined by that
specification. Related encryption capabilities are described in the specification. Related encryption capabilities are described in the
separate JSON Web Encryption (JWE) [JWE] specification. separate JSON Web Encryption (JWE) [JWE] specification.
Names defined by this specification are short because a core goal is Names defined by this specification are short because a core goal is
for the resulting representations to be compact. for the resulting representations to be compact.
skipping to change at page 7, line 16 skipping to change at page 7, line 16
A representation of the JWS as a compact, URL-safe string. A representation of the JWS as a compact, URL-safe string.
JWS JSON Serialization JWS JSON Serialization
A representation of the JWS as a JSON object. Unlike the JWS A representation of the JWS as a JSON object. Unlike the JWS
Compact Serialization, the JWS JSON Serialization enables multiple Compact Serialization, the JWS JSON Serialization enables multiple
digital signatures and/or MACs to be applied to the same content. digital signatures and/or MACs to be applied to the same content.
This representation is neither optimized for compactness nor URL- This representation is neither optimized for compactness nor URL-
safe. safe.
Unsecured JWS Unsecured JWS
A JWS object that provides no integrity protection. Unsecured A JWS that provides no integrity protection. Unsecured JWSs use
JWSs use the "alg" value "none". the "alg" value "none".
Collision-Resistant Name Collision-Resistant Name
A name in a namespace that enables names to be allocated in a A name in a namespace that enables names to be allocated in a
manner such that they are highly unlikely to collide with other manner such that they are highly unlikely to collide with other
names. Examples of collision-resistant namespaces include: Domain names. Examples of collision-resistant namespaces include: Domain
Names, Object Identifiers (OIDs) as defined in the ITU-T X.660 and Names, Object Identifiers (OIDs) as defined in the ITU-T X.660 and
X.670 Recommendation series, and Universally Unique IDentifiers X.670 Recommendation series, and Universally Unique IDentifiers
(UUIDs) [RFC4122]. When using an administratively delegated (UUIDs) [RFC4122]. When using an administratively delegated
namespace, the definer of a name needs to take reasonable namespace, the definer of a name needs to take reasonable
precautions to ensure they are in control of the portion of the precautions to ensure they are in control of the portion of the
skipping to change at page 8, line 11 skipping to change at page 8, line 11
structures and base64url encoding. These JSON data structures MAY structures and base64url encoding. These JSON data structures MAY
contain white space and/or line breaks before or after any JSON contain white space and/or line breaks before or after any JSON
values or structural characters, in accordance with Section 2 of RFC values or structural characters, in accordance with Section 2 of RFC
7159 [RFC7159]. A JWS represents these logical values (each of which 7159 [RFC7159]. A JWS represents these logical values (each of which
is defined in Section 2): is defined in Section 2):
o JOSE Header o JOSE Header
o JWS Payload o JWS Payload
o JWS Signature o JWS Signature
For a JWS object, the JOSE Header members are the union of the For a JWS, the JOSE Header members are the union of the members of
members of these values (each of which is defined in Section 2): these values (each of which is defined in Section 2):
o JWS Protected Header o JWS Protected Header
o JWS Unprotected Header o JWS Unprotected Header
This document defines two serializations for JWS objects: a compact, This document defines two serializations for JWSs: a compact, URL-
URL-safe serialization called the JWS Compact Serialization and a safe serialization called the JWS Compact Serialization and a JSON
JSON serialization called the JWS JSON Serialization. In both 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, since JSON lacks a way to directly Signature are base64url encoded, since JSON lacks a way to directly
represent arbitrary octet sequences. represent arbitrary octet sequences.
3.1. JWS Compact Serialization Overview 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 is represented as the
concatenation: concatenation:
BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(UTF8(JWS Protected Header)) || '.' ||
BASE64URL(JWS Payload) || '.' || BASE64URL(JWS Payload) || '.' ||
BASE64URL(JWS Signature) BASE64URL(JWS Signature)
See Section 7.1 for more information about the JWS Compact See Section 7.1 for more information about the JWS Compact
Serialization. Serialization.
3.2. JWS JSON Serialization Overview 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 union of the members of the JWS members of the JOSE Header are the union of the members of the JWS
Protected Header and the JWS Unprotected Header values that are 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 is represented as a JSON object
combination of these four values: containing some or all of these four members:
BASE64URL(UTF8(JWS Protected Header)) "protected", with the value BASE64URL(UTF8(JWS Protected Header))
JWS Unprotected Header "header", with the value JWS Unprotected Header
BASE64URL(JWS Payload) "payload", with the value BASE64URL(JWS Payload)
BASE64URL(JWS Signature) "signature", with the value BASE64URL(JWS Signature)
The three base64url encoded result strings and the JWS Unprotected The three base64url encoded result strings and the JWS Unprotected
Header value are represented as members within a JSON object. The Header value are represented as members within a JSON object. The
inclusion of some of these values is OPTIONAL. The JWS JSON inclusion of some of these values is OPTIONAL. The JWS JSON
Serialization can also represent multiple signature and/or MAC 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.3. Example JWS 3.3. Example JWS
skipping to change at page 10, line 27 skipping to change at page 10, line 27
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
. .
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
See Appendix A for additional examples, including examples using the See Appendix A for additional examples, including examples using the
JWS JSON Serialization in Sections A.6 and A.7. JWS JSON Serialization in Sections A.6 and A.7.
4. JOSE Header 4. JOSE Header
For a JWS object, the members of the JSON object(s) representing the For a JWS, the members of the JSON object(s) representing the JOSE
JOSE Header describe the digital signature or MAC applied to the JWS Header describe the digital signature or MAC applied to the JWS
Protected Header and the JWS Payload and optionally additional Protected Header and the JWS Payload and optionally additional
properties of the JWS. The Header Parameter names within the JOSE properties of the JWS. The Header Parameter names within the JOSE
Header MUST be unique; JWS parsers MUST either reject JWSs with Header MUST be unique; JWS parsers MUST either reject JWSs with
duplicate Header Parameter names or use a JSON parser that returns duplicate Header Parameter names or use a JSON parser that returns
only the lexically last duplicate member name, as specified in only the lexically last duplicate member name, as specified in
Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript]. Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript].
Implementations are required to understand the specific Header Implementations are required to understand the specific Header
Parameters defined by this specification that are designated as "MUST Parameters defined by this specification that are designated as "MUST
be understood" and process them in the manner defined in this be understood" and process them in the manner defined in this
skipping to change at page 11, line 7 skipping to change at page 11, line 7
understood. Unless listed as a critical Header Parameter, per understood. Unless listed as a critical Header Parameter, per
Section 4.1.11, all Header Parameters not defined by this Section 4.1.11, all Header Parameters not defined by this
specification MUST be ignored when not understood. specification MUST be ignored when not understood.
There are three classes of Header Parameter names: Registered Header There are three classes of Header Parameter names: Registered 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. Registered Header Parameter Names 4.1. Registered Header Parameter Names
The following Header Parameter names for use in JWS objects are The following Header Parameter names for use in JWSs are registered
registered in the IANA JSON Web Signature and Encryption Header in the IANA JSON Web Signature and Encryption Header Parameters
Parameters registry defined in Section 9.1, with meanings as defined registry defined in Section 9.1, with meanings as defined below.
below.
As indicated by the common registry, JWSs and JWEs share a common As indicated by the common registry, JWSs and JWEs share a common
Header Parameter space; when a parameter is used by both Header Parameter space; when a parameter is used by both
specifications, its usage must be compatible between the specifications, its usage must be compatible between the
specifications. specifications.
4.1.1. "alg" (Algorithm) Header Parameter 4.1.1. "alg" (Algorithm) Header Parameter
The "alg" (algorithm) Header Parameter identifies the cryptographic The "alg" (algorithm) Header Parameter identifies the cryptographic
algorithm used to secure the JWS. The JWS Signature value is not algorithm used to secure the JWS. The JWS Signature value is not
skipping to change at page 12, line 48 skipping to change at page 12, line 48
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 RFC 5280 [RFC5280] and reject the the certificate chain according to RFC 5280 [RFC5280] and consider
signature if any validation failure occurs. Use of this Header the certificate or certificate chain to be invalid if any validation
Parameter is OPTIONAL. failure occurs. Use of this Header 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. Note that certificate thumbprints used to digitally sign the JWS. Note that certificate thumbprints
are also sometimes known as certificate fingerprints. Use of this are also sometimes known as certificate fingerprints. Use of this
skipping to change at page 13, line 27 skipping to change at page 13, line 27
The "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header The "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header
Parameter is a base64url encoded SHA-256 thumbprint (a.k.a. digest) Parameter is a base64url encoded SHA-256 thumbprint (a.k.a. digest)
of the DER encoding of the X.509 certificate [RFC5280] corresponding of the DER encoding of the X.509 certificate [RFC5280] corresponding
to the key used to digitally sign the JWS. Note that certificate to the key used to digitally sign the JWS. Note that certificate
thumbprints are also sometimes known as certificate fingerprints. thumbprints are also sometimes known as certificate fingerprints.
Use of this Header Parameter is OPTIONAL. Use of this Header Parameter is OPTIONAL.
4.1.9. "typ" (Type) Header Parameter 4.1.9. "typ" (Type) Header Parameter
The "typ" (type) Header Parameter is used by JWS applications to The "typ" (type) Header Parameter is used by JWS applications to
declare the MIME Media Type [IANA.MediaTypes] of this complete JWS declare the MIME Media Type [IANA.MediaTypes] of this complete JWS.
object. This is intended for use by the application when more than This is intended for use by the application when more than one kind
one kind of object could be present in an application data structure of object could be present in an application data structure that can
that can contain a JWS object; the application can use this value to contain a JWS; the application can use this value to disambiguate
disambiguate among the different kinds of objects that might be among the different kinds of objects that might be present. It will
present. It will typically not be used by applications when the kind typically not be used by applications when the kind of object is
of object is already known. This parameter is ignored by JWS already known. This parameter is ignored by JWS implementations; any
implementations; any processing of this parameter is performed by the processing of this parameter is performed by the JWS application.
JWS application. Use of this Header Parameter is OPTIONAL. Use of this Header Parameter is OPTIONAL.
Per RFC 2045 [RFC2045], all media type values, subtype values, and Per RFC 2045 [RFC2045], all media type values, subtype values, and
parameter names are case-insensitive. However, parameter values are parameter names are case-insensitive. However, parameter values are
case-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
producers omit an "application/" prefix of a media type value in a producers 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
skipping to change at page 15, line 44 skipping to change at page 15, line 44
names that are Private Names: names that are not Registered Header names that are Private Names: names that are not Registered Header
Parameter names Section 4.1 or Public Header Parameter names Parameter names Section 4.1 or Public Header Parameter names
Section 4.2. Unlike Public Header Parameter names, Private Header Section 4.2. Unlike Public Header Parameter names, Private Header
Parameter names are subject to collision and should be used with Parameter names are subject to collision and should be used with
caution. caution.
5. Producing and Consuming JWSs 5. Producing and Consuming JWSs
5.1. Message Signature or MAC Computation 5.1. Message Signature or MAC Computation
To create a JWS, one MUST perform these steps. The order of the To create a JWS, the following steps are performed. The order of the
steps is not significant in cases where there are no dependencies steps is not significant in cases where there are no dependencies
between the inputs and outputs of the steps. between the inputs and outputs of the steps.
1. Create the content to be used as the JWS Payload. 1. Create the content to be used as the JWS Payload.
2. Compute the encoded payload value BASE64URL(JWS Payload). 2. Compute the encoded payload value BASE64URL(JWS Payload).
3. Create the JSON object(s) containing the desired set of Header 3. Create the JSON object(s) containing the desired set of Header
Parameters, which together comprise the JOSE Header: if the JWS Parameters, which together comprise the JOSE Header: if the JWS
Compact Serialization is being used, the JWS Protected Header, or Compact Serialization is being used, the JWS Protected Header, or
skipping to change at page 16, line 41 skipping to change at page 16, line 41
performed. performed.
8. Create the desired serialized output. The JWS Compact 8. Create the desired serialized output. The JWS Compact
Serialization of this result is BASE64URL(UTF8(JWS Protected Serialization of this result is BASE64URL(UTF8(JWS Protected
Header)) || '.' || BASE64URL(JWS Payload) || '.' || BASE64URL(JWS Header)) || '.' || BASE64URL(JWS Payload) || '.' || BASE64URL(JWS
Signature). The JWS JSON Serialization is described in Signature). The JWS JSON Serialization is described in
Section 7.2. Section 7.2.
5.2. Message Signature or MAC Validation 5.2. Message Signature or MAC Validation
When validating a JWS, the following steps MUST be taken. The order When validating a JWS, the following steps are performed. The order
of the steps is not significant in cases where there are no of the steps is not significant in cases where there are no
dependencies between the inputs and outputs of the steps. If any of dependencies between the inputs and outputs of the steps. If any of
the listed steps fails, then the signature or MAC cannot be the listed steps fails, then the signature or MAC cannot be
validated. validated.
When there are multiple JWS Signature values, it is an application When there are multiple JWS Signature values, it is an application
decision which of the JWS Signature values must successfully validate decision which of the JWS Signature values must successfully validate
for the JWS to be accepted. In some cases, all must successfully for the JWS to be accepted. In some cases, all must successfully
validate or the JWS will be considered invalid. In other cases, only validate or the JWS will be considered invalid. In other cases, only
a specific JWS Signature value needs to be successfully validated. a specific JWS Signature value needs to be successfully validated.
skipping to change at page 19, line 48 skipping to change at page 19, line 48
(which is true of all algorithms except for "none") and the key used (which is true of all algorithms except for "none") and the key used
cannot be determined. cannot be determined.
The means of exchanging any shared symmetric keys used is outside the The means of exchanging any shared symmetric keys used is outside the
scope of this specification. scope of this specification.
Also, see Appendix D for notes on possible key selection algorithms. Also, see Appendix D for notes on possible key selection algorithms.
7. Serializations 7. Serializations
JWS objects use one of two serializations, the JWS Compact JWSs use one of two serializations: the JWS Compact Serialization or
Serialization or the JWS JSON Serialization. Applications using this the JWS JSON Serialization. Applications using this specification
specification need to specify what serialization and serialization need to specify what serialization and serialization features are
features are used for that application. For instance, applications used for that application. For instance, applications might specify
might specify that only the JWS JSON Serialization is used, that only that only the JWS JSON Serialization is used, that only JWS JSON
JWS JSON Serialization support for a single signature or MAC value is Serialization support for a single signature or MAC value is used, or
used, or that support for multiple signatures and/or MAC values is that support for multiple signatures and/or MAC values is used. JWS
used. JWS implementations only need to implement the features needed implementations only need to implement the features needed for the
for the applications they are designed to support. applications they are designed to support.
7.1. JWS Compact Serialization 7.1. JWS Compact Serialization
The JWS Compact Serialization represents digitally signed or MACed The JWS Compact Serialization represents digitally signed or MACed
content as a compact, URL-safe string. This string is: content as a compact, URL-safe string. This string is:
BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(UTF8(JWS Protected Header)) || '.' ||
BASE64URL(JWS Payload) || '.' || BASE64URL(JWS Payload) || '.' ||
BASE64URL(JWS Signature) BASE64URL(JWS Signature)
skipping to change at page 27, line 19 skipping to change at page 27, line 19
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 4.1.11 of [[ this document ]] o Specification Document(s): Section 4.1.11 of [[ this document ]]
9.2. Media Type Registration 9.2. Media Type Registration
9.2.1. Registry Contents 9.2.1. Registry Contents
This specification registers the "application/jose" Media Type This specification registers the "application/jose" Media Type
[RFC2046] in the MIME Media Types registry [IANA.MediaTypes] in the [RFC2046] in the MIME Media Types registry [IANA.MediaTypes] in the
manner described in RFC 6838 [RFC6838], which can be used to indicate manner described in RFC 6838 [RFC6838], which can be used to indicate
that the content is a JWS or JWE object using the JWS Compact that the content is a JWS or JWE using the JWS Compact Serialization
Serialization or the JWE Compact Serialization and the or the JWE Compact Serialization and the "application/jose+json"
"application/jose+json" Media Type in the MIME Media Types registry, Media Type in the MIME Media Types registry, which can be used to
which can be used to indicate that the content is a JWS or JWE object indicate that the content is a JWS or JWE using the JWS JSON
using the JWS JSON Serialization or the JWE JSON Serialization. Serialization or the JWE JSON Serialization.
o Type name: application o Type name: application
o Subtype name: jose o Subtype name: jose
o Required parameters: n/a o Required parameters: n/a
o Optional parameters: n/a o Optional parameters: n/a
o Encoding considerations: 8bit; application/jose values are encoded o Encoding considerations: 8bit; application/jose values are encoded
as a series of base64url encoded values (some of which may be the as a series of base64url encoded values (some of which may be the
empty string) each separated from the next by a single period empty string) each separated from the next by a single period
('.') character. ('.') character.
o Security considerations: See the Security Considerations section o Security considerations: See the Security Considerations section
skipping to change at page 32, line 13 skipping to change at page 32, line 13
SHA-256 certificate thumbprints. SHA-256 certificate thumbprints.
10.12. JSON Security Considerations 10.12. JSON Security Considerations
Strict JSON [RFC7159] validation is a security requirement. If Strict JSON [RFC7159] validation is a security requirement. If
malformed JSON is received, then the intent of the producer is malformed JSON is received, then the intent of the producer is
impossible to reliably discern. Ambiguous and potentially impossible to reliably discern. Ambiguous and potentially
exploitable situations could arise if the JSON parser used does not exploitable situations could arise if the JSON parser used does not
reject malformed JSON syntax. In particular, any JSON inputs not reject malformed JSON syntax. In particular, any JSON inputs not
conforming to the JSON-text syntax defined in RFC 7159 input MUST be conforming to the JSON-text syntax defined in RFC 7159 input MUST be
rejected in their entirety. rejected in their entirety by JSON parsers.
Section 4 of the JSON Data Interchange Format specification [RFC7159] Section 4 of the JSON Data Interchange Format specification [RFC7159]
states "The names within an object SHOULD be unique", whereas this states "The names within an object SHOULD be unique", whereas this
specification states that "Header Parameter names within this object specification states that "Header Parameter names within this object
MUST be unique; JWS parsers MUST either reject JWSs with duplicate MUST be unique; JWS parsers MUST either reject JWSs with duplicate
Header Parameter names or use a JSON parser that returns only the Header Parameter names or use a JSON parser that returns only the
lexically last duplicate member name, as specified in Section 15.12 lexically last duplicate member name, as specified in Section 15.12
(The JSON Object) of ECMAScript 5.1 [ECMAScript]". Thus, this (The JSON Object) of ECMAScript 5.1 [ECMAScript]". Thus, this
specification requires that the Section 4 "SHOULD" be treated as a specification requires that the Section 4 "SHOULD" be treated as a
"MUST" by producers and that it be either treated as a "MUST" or in "MUST" by producers and that it be either treated as a "MUST" or in
skipping to change at page 33, line 26 skipping to change at page 33, line 26
[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),
November 2014. December 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),
November 2014. December 2014.
[RFC20] Cerf, V., "ASCII format for Network Interchange", RFC 20, [RFC20] Cerf, V., "ASCII format for Network Interchange", RFC 20,
October 1969. October 1969.
[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
Extensions (MIME) Part Two: Media Types", RFC 2046, Extensions (MIME) Part Two: Media Types", RFC 2046,
skipping to change at page 34, line 51 skipping to change at page 34, line 51
Sheffer, Y., Holz, R., and P. Saint-Andre, Sheffer, Y., Holz, R., and P. Saint-Andre,
"Recommendations for Secure Use of TLS and DTLS", "Recommendations for Secure Use of TLS and DTLS",
draft-ietf-uta-tls-bcp-07 (work in progress), draft-ietf-uta-tls-bcp-07 (work in progress),
November 2014. November 2014.
[JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign",
September 2010. September 2010.
[JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
draft-ietf-jose-json-web-encryption (work in progress), draft-ietf-jose-json-web-encryption (work in progress),
November 2014. December 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), November 2014. progress), December 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- [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
Hashing for Message Authentication", RFC 2104, Hashing for Message Authentication", RFC 2104,
February 1997. February 1997.
[RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography
skipping to change at page 53, line 9 skipping to change at page 53, line 9
An example correspondence between unencoded and encoded values An example correspondence between unencoded and encoded values
follows. The octet sequence below encodes into the string below, follows. The octet sequence below encodes into the string below,
which when decoded, reproduces the octet sequence. which when decoded, reproduces the octet sequence.
3 236 255 224 193 3 236 255 224 193
A-z_4ME A-z_4ME
Appendix D. Notes on Key Selection Appendix D. Notes on Key Selection
This appendix describes a set of possible algorithms for selecting This appendix describes a set of possible algorithms for selecting
the key to be used to validate the digital signature or MAC of a JWS the key to be used to validate the digital signature or MAC of a JWS
object or for selecting the key to be used to decrypt a JWE object. or for selecting the key to be used to decrypt a JWE. This guidance
This guidance describes a family of possible algorithms, rather than describes a family of possible algorithms, rather than a single
a single algorithm, because in different contexts, not all the algorithm, because in different contexts, not all the sources of keys
sources of keys will be used, they can be tried in different orders, will be used, they can be tried in different orders, and sometimes
and sometimes not all the collected keys will be tried; hence, not all the collected keys will be tried; hence, different algorithms
different algorithms will be used in different application contexts. will be used in different application contexts.
The steps below are described for illustration purposes only; The steps below are described for illustration purposes only;
specific applications can and are likely to use different algorithms specific applications can and are likely to use different algorithms
or perform some of the steps in different orders. Specific or perform some of the steps in different orders. Specific
applications will frequently have a much simpler method of applications will frequently have a much simpler method of
determining the keys to use, as there may be one or two key selection determining the keys to use, as there may be one or two key selection
methods that are profiled for the application's use. This appendix methods that are profiled for the application's use. This appendix
supplements the normative information on key location in Section 6. supplements the normative information on key location in Section 6.
These algorithms include the following steps. Note that the steps These algorithms include the following steps. Note that the steps
skipping to change at page 54, line 27 skipping to change at page 54, line 27
applications, no ordering will be applied. applications, no ordering will be applied.
4. Make trust decisions about the keys. Signatures made with keys 4. Make trust decisions about the keys. Signatures made with keys
not meeting the application's trust criteria would not be not meeting the application's trust criteria would not be
accepted. Such criteria might include, but is not limited to the accepted. Such criteria might include, but is not limited to the
source of the key, whether the TLS certificate validates for keys source of the key, whether the TLS certificate validates for keys
retrieved from URLs, whether a key in an X.509 certificate is retrieved from URLs, whether a key in an X.509 certificate is
backed by a valid certificate chain, and other information known backed by a valid certificate chain, and other information known
by the application. by the application.
5. Attempt signature or MAC validation for a JWS object or 5. Attempt signature or MAC validation for a JWS or decryption of a
decryption of a JWE object with some or all of the collected and JWE with some or all of the collected and possibly filtered
possibly filtered and/or ordered keys. A limit on the number of and/or ordered keys. A limit on the number of keys to be tried
keys to be tried might be applied. This process will normally might be applied. This process will normally terminate following
terminate following a successful validation or decryption. a successful validation or decryption.
Note that it is reasonable for some applications to perform signature Note that it is reasonable for some applications to perform signature
or MAC validation prior to making a trust decision about a key, since or MAC validation prior to making a trust decision about a key, since
keys for which the validation fails need no trust decision. keys for which the validation fails need no trust decision.
Appendix E. Negative Test Case for "crit" Header Parameter Appendix E. Negative Test Case for "crit" Header Parameter
Conforming implementations must reject input containing critical Conforming implementations must reject input containing critical
extensions that are not understood or cannot be processed. The extensions that are not understood or cannot be processed. The
following JWS must be rejected by all implementations, because it following JWS must be rejected by all implementations, because it
skipping to change at page 55, line 22 skipping to change at page 55, line 22
The complete JWS that must be rejected is as follows (with line The complete JWS that must be rejected is as follows (with line
breaks for display purposes only): breaks for display purposes only):
eyJhbGciOiJub25lIiwNCiAiY3JpdCI6WyJodHRwOi8vZXhhbXBsZS5jb20vVU5ERU eyJhbGciOiJub25lIiwNCiAiY3JpdCI6WyJodHRwOi8vZXhhbXBsZS5jb20vVU5ERU
ZJTkVEIl0sDQogImh0dHA6Ly9leGFtcGxlLmNvbS9VTkRFRklORUQiOnRydWUNCn0. ZJTkVEIl0sDQogImh0dHA6Ly9leGFtcGxlLmNvbS9VTkRFRklORUQiOnRydWUNCn0.
RkFJTA. RkFJTA.
Appendix F. Detached Content Appendix F. Detached Content
In some contexts, it is useful integrity protect content that is not In some contexts, it is useful integrity protect content that is not
itself contained in a JWS object. One way to do this is create a JWS itself contained in a JWS. One way to do this is create a JWS in the
object in the normal fashion using a representation of the content as normal fashion using a representation of the content as the payload,
the payload, but then delete the payload representation from the JWS, but then delete the payload representation from the JWS, and send
and send this modified object to the recipient, rather than the JWS. this modified object to the recipient, rather than the JWS. When
When using the JWS Compact Serialization, the deletion is using the JWS Compact Serialization, the deletion is accomplished by
accomplished by replacing the second field (which contains replacing the second field (which contains BASE64URL(JWS Payload))
BASE64URL(JWS Payload)) value with the empty string; when using the value with the empty string; when using the JWS JSON Serialization,
JWS JSON Serialization, the deletion is accomplished by deleting the the deletion is accomplished by deleting the "payload" member. This
"payload" member. This method assumes that the recipient can method assumes that the recipient can reconstruct the exact payload
reconstruct the exact payload used in the JWS. To use the modified used in the JWS. To use the modified object, the recipient
object, the recipient reconstructs the JWS by re-inserting the reconstructs the JWS by re-inserting the payload representation into
payload representation into the modified object, and uses the the modified object, and uses the resulting JWS in the usual manner.
resulting JWS in the usual manner. Note that this method needs no Note that this method needs no support from JWS libraries, as
support from JWS libraries, as applications can use this method by applications can use this method by modifying the inputs and outputs
modifying the inputs and outputs of standard JWS libraries. of standard JWS libraries.
Appendix G. Acknowledgements Appendix G. 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. Applications [CanvasApp], all of which influenced this draft.
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.
skipping to change at page 56, line 21 skipping to change at page 56, line 21
Tschofenig, and Sean Turner. 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 ]]
-38
o Replaced uses of the phrases "JWS object" and "JWE object" with
"JWS" and "JWE".
o Added member names to the JWS JSON Serialization Overview.
o Applied other minor editorial improvements.
-37 -37
o Updated the TLS requirements language to only require o Updated the TLS requirements language to only require
implementations to support TLS when they support features using implementations to support TLS when they support features using
TLS. TLS.
o Updated the language about integrity protecting Header Parameters o Updated the language about integrity protecting Header Parameters
when used in a trust decision. when used in a trust decision.
o Restricted algorithm names to using only ASCII characters. o Restricted algorithm names to using only ASCII characters.
 End of changes. 28 change blocks. 
90 lines changed or deleted 98 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/