draft-ietf-jose-json-web-signature-19.txt   draft-ietf-jose-json-web-signature-20.txt 
JOSE Working Group M. Jones JOSE Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track J. Bradley Intended status: Standards Track J. Bradley
Expires: July 2, 2014 Ping Identity Expires: July 24, 2014 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
December 29, 2013 January 20, 2014
JSON Web Signature (JWS) JSON Web Signature (JWS)
draft-ietf-jose-json-web-signature-19 draft-ietf-jose-json-web-signature-20
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 July 2, 2014. This Internet-Draft will expire on July 24, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2013 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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
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
skipping to change at page 3, line 31 skipping to change at page 3, line 31
A.4.2. Validating . . . . . . . . . . . . . . . . . . . . . . 38 A.4.2. Validating . . . . . . . . . . . . . . . . . . . . . . 38
A.5. Example Plaintext JWS . . . . . . . . . . . . . . . . . . 38 A.5. Example Plaintext JWS . . . . . . . . . . . . . . . . . . 38
A.6. Example JWS Using JWS JSON Serialization . . . . . . . . . 39 A.6. Example JWS Using JWS JSON Serialization . . . . . . . . . 39
A.6.1. JWS Per-Signature Protected Headers . . . . . . . . . 39 A.6.1. JWS Per-Signature Protected Headers . . . . . . . . . 39
A.6.2. JWS Per-Signature Unprotected Headers . . . . . . . . 40 A.6.2. JWS Per-Signature Unprotected Headers . . . . . . . . 40
A.6.3. Complete JWS Header Values . . . . . . . . . . . . . . 40 A.6.3. Complete JWS Header Values . . . . . . . . . . . . . . 40
A.6.4. Complete JWS JSON Serialization Representation . . . . 40 A.6.4. Complete JWS JSON Serialization Representation . . . . 40
Appendix B. "x5c" (X.509 Certificate Chain) Example . . . . . . . 41 Appendix B. "x5c" (X.509 Certificate Chain) Example . . . . . . . 41
Appendix C. Notes on implementing base64url encoding without Appendix C. Notes on implementing base64url encoding without
padding . . . . . . . . . . . . . . . . . . . . . . . 43 padding . . . . . . . . . . . . . . . . . . . . . . . 43
Appendix D. Notes on Validation Key Selection . . . . . . . . . . 44 Appendix D. Notes on Key Selection . . . . . . . . . . . . . . . 44
Appendix E. Negative Test Case for "crit" Header Parameter . . . 45 Appendix E. Negative Test Case for "crit" Header Parameter . . . 45
Appendix F. Detached Content . . . . . . . . . . . . . . . . . . 45 Appendix F. Detached Content . . . . . . . . . . . . . . . . . . 46
Appendix G. Acknowledgements . . . . . . . . . . . . . . . . . . 46 Appendix G. Acknowledgements . . . . . . . . . . . . . . . . . . 46
Appendix H. Document History . . . . . . . . . . . . . . . . . . 46 Appendix H. Document History . . . . . . . . . . . . . . . . . . 47
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 53 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 54
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) [RFC4627] based data structures. The JWS Object Notation (JSON) [I-D.ietf-json-rfc4627bis] based data
cryptographic mechanisms provide integrity protection for an structures. The JWS cryptographic mechanisms provide integrity
arbitrary sequence of octets. protection for an arbitrary sequence of octets.
Two closely related serializations for JWS objects are defined. The Two closely related serializations for JWS objects are defined. The
JWS Compact Serialization is a compact, URL-safe representation JWS Compact Serialization is a compact, URL-safe representation
intended for space constrained environments such as HTTP intended for space constrained environments such as HTTP
Authorization headers and URI query parameters. The JWS JSON Authorization headers and URI query parameters. The JWS JSON
Serialization represents JWS objects as JSON objects and enables Serialization represents JWS objects as JSON objects and enables
multiple signatures and/or MACs to be applied to the same content. multiple signatures and/or MACs to be applied to the same content.
Both share the same cryptographic underpinnings. Both share the same cryptographic underpinnings.
Cryptographic algorithms and identifiers for use with this Cryptographic algorithms and identifiers for use with this
skipping to change at page 5, line 10 skipping to change at page 5, line 10
ASCII(STRING) denotes the octets of the ASCII [USASCII] ASCII(STRING) denotes the octets of the ASCII [USASCII]
representation of STRING. representation of STRING.
The concatenation of two values A and B is denoted as A || B. The concatenation of two values A and B is denoted as A || B.
2. Terminology 2. Terminology
JSON Web Signature (JWS) A data structure representing a digitally JSON Web Signature (JWS) A data structure representing a digitally
signed or MACed message. signed or MACed message.
JWS Header A JSON object (or JSON objects, when using the JWS JSON JWS Header JSON object containing the parameters describing the
Serialization) that describes the digital signature or MAC cryptographic operations and parameters employed. The JWS Header
operation applied to create the JWS Signature value. The members members are the union of the members of the JWS Protected Header
of the JWS Header object(s) are Header Parameters. and the JWS Unprotected Header. The members of the JWS Header are
Header Parameters.
JWS Payload The sequence of octets to be secured -- a.k.a., the JWS Payload The sequence of octets to be secured -- a.k.a., the
message. The payload can contain an arbitrary sequence of octets. message. The payload can contain an arbitrary sequence of octets.
JWS Signature A sequence of octets containing the cryptographic JWS Signature Digital signature or MAC over the JWS Protected Header
material that ensures the integrity of the JWS Protected Header and the JWS Payload.
and the JWS Payload. The JWS Signature value is a digital
signature or MAC value calculated over the JWS Signing Input using
the parameters specified in the JWS Header.
JWS Protected Header A JSON object that contains the portion of the Header Parameter A name/value pair that is member of the JWS Header.
JWS Header that is integrity protected. For the JWS Compact
JWS Protected Header JSON object that contains the JWS Header
Parameters that are integrity protected by the JWS Signature
digital signature or MAC operation. For the JWS Compact
Serialization, this comprises the entire JWS Header. For the JWS Serialization, this comprises the entire JWS Header. For the JWS
JSON Serialization, this is one component of the JWS Header. JSON Serialization, this is one component of the JWS Header.
Header Parameter A name/value pair that is member of the JWS Header. JWS Unprotected Header JSON object that contains the JWS Header
Parameters that are not integrity protected. This can only be
present when using the JWS JSON Serialization.
Base64url Encoding Base64 encoding using the URL- and filename-safe Base64url Encoding Base64 encoding using the URL- and filename-safe
character set defined in Section 5 of RFC 4648 [RFC4648], with all character set defined in Section 5 of RFC 4648 [RFC4648], with all
trailing '=' characters omitted (as permitted by Section 3.2). trailing '=' characters omitted (as permitted by Section 3.2).
(See Appendix C for notes on implementing base64url encoding (See Appendix C for notes on implementing base64url encoding
without padding.) without padding.)
JWS Signing Input The input to the digital signature or MAC JWS Signing Input The input to the digital signature or MAC
computation. Its value is ASCII(BASE64URL(UTF8(JWS Protected computation. Its value is ASCII(BASE64URL(UTF8(JWS Protected
Header)) || '.' || BASE64URL(JWS Payload)). Header)) || '.' || BASE64URL(JWS Payload)).
JWS Compact Serialization A representation of the JWS as a compact, JWS Compact Serialization A representation of the JWS as a compact,
URL-safe string. URL-safe string.
JWS JSON Serialization A representation of the JWS as a JSON object. JWS JSON Serialization A representation of the JWS as a JSON object.
Unlike the JWS Compact Serialization, the JWS JSON Serialization Unlike the JWS Compact Serialization, the JWS JSON Serialization
enables multiple digital signatures and/or MACs to be applied to enables multiple digital signatures and/or MACs to be applied to
the same content. This representation is neither compact nor URL- the same content. This representation is neither optimized for
safe. compactness nor URL-safe.
Collision-Resistant Name A name in a namespace that enables names to Collision-Resistant Name A name in a namespace that enables names to
be allocated in a manner such that they are highly unlikely to be allocated in a manner such that they are highly unlikely to
collide with other names. Examples of collision-resistant collide with other names. Examples of collision-resistant
namespaces include: Domain Names, Object Identifiers (OIDs) as namespaces include: Domain Names, Object Identifiers (OIDs) as
defined in the ITU-T X.660 and X.670 Recommendation series, and defined in the ITU-T X.660 and X.670 Recommendation series, and
Universally Unique IDentifiers (UUIDs) [RFC4122]. When using an Universally Unique IDentifiers (UUIDs) [RFC4122]. When using an
administratively delegated namespace, the definer of a name needs administratively delegated namespace, the definer of a name needs
to take reasonable precautions to ensure they are in control of to take reasonable precautions to ensure they are in control of
the portion of the namespace they use to define the name. the portion of the namespace they use to define the name.
skipping to change at page 6, line 28 skipping to change at page 6, line 28
values are compared as case-sensitive strings with no values are compared as case-sensitive strings with no
transformations or canonicalizations applied. transformations or canonicalizations applied.
3. JSON Web Signature (JWS) Overview 3. JSON Web Signature (JWS) Overview
JWS represents digitally signed or MACed content using JSON data JWS represents digitally signed or MACed content using JSON data
structures and base64url encoding. A JWS represents these logical structures and base64url encoding. A JWS represents these logical
values: values:
JWS Header JSON object containing the parameters describing the JWS Header JSON object containing the parameters describing the
cryptographic operations and parameters employed. The JWE Header cryptographic operations and parameters employed. The JWS Header
members are the union of the members of the JWS Protected Header members are the union of the members of the JWS Protected Header
and the JWS Unprotected Header, as described below. and the JWS Unprotected Header, as described below.
JWS Payload Message content to be secured. JWS Payload The sequence of octets to be secured -- a.k.a., the
message. The payload can contain an arbitrary sequence of octets.
JWS Signature Digital signature or MAC over the JWS Protected Header JWS Signature Digital signature or MAC over the JWS Protected Header
and the JWS Payload. and the JWS Payload.
The JWS Header represents the combination of these logical values: The JWS Header represents the combination of these values:
JWS Protected Header JSON object containing some of the parameters JWS Protected Header JSON object that contains the JWS Header
describing the cryptographic operations and parameters employed. Parameters that are integrity protected by the JWS Signature
This value is integrity protected in the digital signature or MAC digital signature or MAC operation.
calculation of the JWS Signature.
JWS Unprotected Header JSON object containing some of the parameters JWS Unprotected Header JSON object that contains the JWS Header
describing the cryptographic operations and parameters employed. Parameters that are not integrity protected.
This value is not integrity protected in the digital signature or
MAC calculation of the JWS Signature.
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.
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 JWS Header and the JWS Protected Header are the In this case, the JWS Header and the JWS Protected Header are the
skipping to change at page 14, line 27 skipping to change at page 14, line 27
particular algorithm being used over the JWS Signing Input particular algorithm being used over the JWS Signing Input
ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' ||
BASE64URL(JWS Payload)). The "alg" (algorithm) Header Parameter BASE64URL(JWS Payload)). The "alg" (algorithm) Header Parameter
MUST be present in the JWS Header, with the algorithm value MUST be present in the JWS Header, with the algorithm value
accurately representing the algorithm used to construct the JWS accurately representing the algorithm used to construct the JWS
Signature. Signature.
6. Compute the encoded signature value BASE64URL(JWS Signature). 6. Compute the encoded signature value BASE64URL(JWS Signature).
7. These three encoded values are used in both the JWS Compact 7. These three encoded values are used in both the JWS Compact
Serialization and the JWS JSON Serialization representations. Serialization and the JWS JSON Serialization representations.
8. If the JWS JSON Serialization is being used, repeat this process 8. If the JWS JSON Serialization is being used, repeat this process
(steps 3-7) for each digital signature or MAC value being (steps 3-7) for each digital signature or MAC operation being
applied. performed.
9. Create the desired serialized output. The JWS Compact 9. 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 MUST be taken. 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
skipping to change at page 15, line 20 skipping to change at page 15, line 20
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
RFC 4627 [RFC4627], which is the JWS Protected Header. [I-D.ietf-json-rfc4627bis], which is the JWS Protected Header.
4. If using the JWS Compact Serialization, let the JWS Header be 4. If using the JWS Compact Serialization, let the JWS 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 JWS Header be the union of the members of Serialization, let the JWS Header be the union of the members of
the corresponding JWS Protected Header and JWS Unprotected 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 JWS Header MUST NOT contain duplicate Header 5. The resulting JWS 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 JWS Header. comprise the JWS Header.
skipping to change at page 17, line 25 skipping to change at page 17, line 25
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(JWS BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS
Payload) || '.' || BASE64URL(JWS Signature). Only one signature/MAC Payload) || '.' || BASE64URL(JWS Signature). Only one signature/MAC
is supported by the JWS Compact Serialization and it provides no is supported by the JWS Compact Serialization and it provides no
syntax to represent a JWS Unprotected Header value. syntax to represent a JWS Unprotected Header value.
7.2. JWS JSON Serialization 7.2. JWS JSON Serialization
The JWS JSON Serialization represents digitally signed or MACed The JWS JSON Serialization represents digitally signed or MACed
content as a JSON object. Unlike the JWS Compact Serialization, content as a JSON object. Content using the JWS JSON Serialization
content using the JWS JSON Serialization can be secured with more can be secured with more than one digital signature and/or MAC
than one digital signature and/or MAC value. operation. This representation is neither optimized for compactness
nor URL-safe.
The representation is closely related to that used in the JWS Compact The following members are defined for use in top-level JSON objects
Serialization, with the following differences for the JWS JSON used for the JWS JSON Serialization:
Serialization: payload The value BASE64URL(JWS Payload) is stored in the "payload"
o Values in the JWS JSON Serialization are represented as members of
a JSON object, rather than as base64url encoded strings separated
by period ('.') characters. (However binary values and values
that are integrity protected are still base64url encoded.)
o The value BASE64URL(JWS Payload) is stored in the "payload"
member. member.
o There can be multiple signature and/or MAC values, rather than signatures A JSON array in the "signatures" member is used to hold
just one. A JSON array in the "signatures" member is used to hold
values that are specific to a particular signature or MAC values that are specific to a particular signature or MAC
computation, with one array element per signature/MAC represented. computation, with one array element per signature/MAC represented.
These array elements are JSON objects. These array elements are JSON objects, as specified below.
o Each value BASE64URL(JWS Signature), if non-empty, is stored in
the "signature" member of a JSON object that is an element of the
"signatures" array.
o Each value BASE64URL(UTF8(JWS Protected Header)), if non-empty, is
stored in the "protected" member of the corresponding element of
the "signatures" array.
o Each JWS Unprotected Header value, if non-empty, is stored in the
"header" member of the corresponding element of the "signatures"
array. If present, a JWS Unprotected Header value is represented
as an unencoded JSON object, rather than as a string.
o The Header Parameter values used when creating or validating
individual signature or MAC values are the union of the two sets
of Header Parameter values that may be present: (1) the JWS
Protected Header values represented in the "protected" member of
the signature/MAC's array element, and (2) the JWS Unprotected
Header values in the "header" member of the signature/MAC's array
element. The union of these sets of Header Parameters comprises
the JWS Header. The Header Parameter names in the two locations
MUST be disjoint.
The syntax of a JWS using the JWS JSON Serialization is as follows: The following members are defined for use in the JSON objects that
are elements of the "signatures" array:
protected Each value BASE64URL(UTF8(JWS Protected Header)), if non-
empty, is stored in the "protected" member.
header Each JWS Unprotected Header value, if non-empty, is stored in
the "header" member. If present, a JWS Unprotected Header value
is represented as an unencoded JSON object, rather than as a
string.
signature Each value BASE64URL(JWS Signature) is stored in the
"signature" member.
{ Of these members of the two JSON objects defined above, only the
"payload":"<payload contents>" "payload", "signatures", and "signature" members MUST be present. At
"signatures":[ least one of the "protected" and "header" members MUST be present for
{"protected":<integrity-protected header 1 contents>", each signature/MAC computation so that an "alg" Header Parameter
"header":"<non-integrity-protected header 1 contents>", value is conveyed.
"signature":"<signature 1 contents>"},
...
{"protected":<integrity-protected header N contents>",
"header":"<non-integrity-protected header N contents>",
"signature":"<signature N contents>"}],
}
Of these members, only the "payload", "signatures", and "signature" Additional members can be present in both the JSON objects defined
members MUST be present. At least one of the "protected" and above; if not understood by implementations encountering them, they
"header" members MUST be present for each signature/MAC computation MUST be ignored.
so that an "alg" Header Parameter value is conveyed.
The Header Parameter values used when creating or validating
individual signature or MAC values are the union of the two sets of
Header Parameter values that may be present: (1) the JWS Protected
Header values represented in the "protected" member of the signature/
MAC's array element, and (2) the JWS Unprotected Header values in the
"header" member of the signature/MAC's array element. The union of
these sets of Header Parameters comprises the JWS Header. The Header
Parameter names in the two locations MUST be disjoint.
The contents of the JWS Payload and JWS Signature values are exactly The contents of the JWS Payload and JWS Signature values are exactly
as defined in the rest of this specification. They are interpreted as defined in the rest of this specification. They are interpreted
and validated in the same manner, with each corresponding JWS and validated in the same manner, with each corresponding JWS
Signature and set of Header Parameter values being created and Signature and set of Header Parameter values being created and
validated together. The JWS Header values used are the union of the validated together.
Header Parameters in the corresponding JWS Protected Header and JWS
Unprotected Header values, as described earlier.
Each JWS Signature value is computed on the JWS Signing Input using Each JWS Signature value is computed on the JWS Signing Input using
the parameters of the corresponding JWS Header value in the same the parameters of the corresponding JWS Header value in the same
manner as for the JWS Compact Serialization. This has the desirable manner as for the JWS Compact Serialization. This has the desirable
property that each JWS Signature value represented in the property that each JWS Signature value represented in the
"signatures" array is identical to the value that would have been "signatures" array is identical to the value that would have been
computed for the same parameter in the JWS Compact Serialization, computed for the same parameter in the JWS Compact Serialization,
provided that the JWS Protected Header value for that signature/MAC provided that the JWS Protected Header value for that signature/MAC
computation (which represents the integrity-protected Header computation (which represents the integrity-protected Header
Parameter values) matches that used in the JWS Compact Serialization. Parameter values) matches that used in the JWS Compact Serialization.
In summary, the syntax of a JWS using the JWS JSON Serialization is
as follows:
{
"payload":"<payload contents>",
"signatures":[
{"protected":"<integrity-protected header 1 contents>",
"header":<non-integrity-protected header 1 contents>,
"signature":"<signature 1 contents>"},
...
{"protected":"<integrity-protected header N contents>",
"header":<non-integrity-protected header N contents>,
"signature":"<signature N contents>"}]
}
See Appendix A.6 for an example of computing a JWS using the JWS JSON See Appendix A.6 for an example of computing a JWS using the JWS JSON
Serialization. Serialization.
8. TLS Requirements 8. TLS Requirements
Implementations MUST support TLS. Which version(s) ought to be Implementations MUST support TLS. Which version(s) ought to be
implemented will vary over time, and depend on the widespread implemented will vary over time, and depend on the widespread
deployment and known security vulnerabilities at the time of deployment and known security vulnerabilities at the time of
implementation. At the time of this writing, TLS version 1.2 implementation. At the time of this writing, TLS version 1.2
[RFC5246] is the most recent version, but has very limited actual [RFC5246] is the most recent version, but has very limited actual
skipping to change at page 25, line 12 skipping to change at page 25, line 12
it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint
using SHA-256) Header Parameter could be defined and used. using SHA-256) Header Parameter could be defined and used.
10.2. JSON Security Considerations 10.2. JSON Security Considerations
Strict JSON validation is a security requirement. If malformed JSON Strict JSON validation is a security requirement. If malformed JSON
is received, then the intent of the sender is impossible to reliably is received, then the intent of the sender is impossible to reliably
discern. Ambiguous and potentially exploitable situations could discern. Ambiguous and potentially exploitable situations could
arise if the JSON parser used does not reject malformed JSON syntax. arise if the JSON parser used does not reject malformed JSON syntax.
Section 2.2 of the JavaScript Object Notation (JSON) specification Section 4 of the JSON Data Interchange Format specification
[RFC4627] states "The names within an object SHOULD be unique", [I-D.ietf-json-rfc4627bis] states "The names within an object SHOULD
whereas this specification states that "Header Parameter names within be unique", whereas this specification states that "Header Parameter
this object MUST be unique; recipients MUST either reject JWSs with names within this object MUST be unique; recipients MUST either
duplicate Header Parameter names or use a JSON parser that returns reject JWSs with duplicate Header Parameter names or use a JSON
only the lexically last duplicate member name, as specified in parser that returns only the lexically last duplicate member name, as
Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript]". specified in Section 15.12 (The JSON Object) of ECMAScript 5.1
Thus, this specification requires that the Section 2.2 "SHOULD" be [ECMAScript]". Thus, this specification requires that the Section 4
treated as a "MUST" by senders and that it be either treated as a "SHOULD" be treated as a "MUST" by senders and that it be either
"MUST" or in the manner specified in ECMAScript 5.1 by receivers. treated as a "MUST" or in the manner specified in ECMAScript 5.1 by
Ambiguous and potentially exploitable situations could arise if the receivers. Ambiguous and potentially exploitable situations could
JSON parser used does not enforce the uniqueness of member names or arise if the JSON parser used does not enforce the uniqueness of
returns an unpredictable value for duplicate member names. member names or returns an unpredictable value for duplicate member
names.
Some JSON parsers might not reject input that contains extra Some JSON parsers might not reject input that contains extra
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 object followed by the "{"tag":"value"}ABCD" contains a valid JSON object followed by the
extra characters "ABCD". Such input MUST be rejected in its extra characters "ABCD". Such input MUST be rejected in its
entirety. entirety.
10.3. Unicode Comparison Security Considerations 10.3. 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 RFC 4627 verbatim after performing any escape processing (as per Section 8.3
[RFC4627], Section 2.5). This means, for instance, that these JSON of [I-D.ietf-json-rfc4627bis]). This means, for instance, that these
strings must compare as being equal ("sig", "\u0073ig"), whereas JSON strings must compare as being equal ("sig", "\u0073ig"), whereas
these must all compare as being not equal to the first set or to each these must all compare as being not equal to the first set or to each
other ("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,
skipping to change at page 26, line 4 skipping to change at page 26, line 6
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.
11. References 11. References
11.1. Normative References 11.1. Normative References
[ECMAScript] [ECMAScript]
Ecma International, "ECMAScript Language Specification, Ecma International, "ECMAScript Language Specification,
5.1 Edition", ECMA 262, June 2011. 5.1 Edition", ECMA 262, June 2011.
[I-D.ietf-json-rfc4627bis] [I-D.ietf-json-rfc4627bis]
Bray, T., "The JSON Data Interchange Format", Bray, T., "The JSON Data Interchange Format",
draft-ietf-json-rfc4627bis-07 (work in progress), draft-ietf-json-rfc4627bis-10 (work in progress),
November 2013. December 2013.
[IANA.MediaTypes] [IANA.MediaTypes]
Internet Assigned Numbers Authority (IANA), "MIME Media Internet Assigned Numbers Authority (IANA), "MIME Media
Types", 2005. Types", 2005.
[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),
December 2013. January 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),
December 2013. January 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 27, line 14 skipping to change at page 27, line 15
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003. 10646", STD 63, RFC 3629, November 2003.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005. RFC 3986, January 2005.
[RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, October 2006. Encodings", RFC 4648, October 2006.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an [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.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008. (TLS) Protocol Version 1.2", RFC 5246, August 2008.
skipping to change at page 28, line 10 skipping to change at page 28, line 8
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., Rescorla, E., and J. Hildebrand, "JSON Web [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web
Encryption (JWE)", draft-ietf-jose-json-web-encryption Encryption (JWE)", draft-ietf-jose-json-web-encryption
(work in progress), December 2013. (work in progress), January 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), December 2013. progress), January 2014.
[MagicSignatures] [MagicSignatures]
Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic
Signatures", January 2011. Signatures", January 2011.
[RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally
Unique IDentifier (UUID) URN Namespace", RFC 4122, Unique IDentifier (UUID) URN Namespace", RFC 4122,
July 2005. July 2005.
[W3C.CR-xmldsig-core2-20120124] [W3C.CR-xmldsig-core2-20120124]
skipping to change at page 44, line 13 skipping to change at page 44, line 13
'=' padding characters are added; if the length mod 4 is 3, one '=' '=' padding characters are added; if the length mod 4 is 3, one '='
padding character is added; if the length mod 4 is 1, the input is padding character is added; if the length mod 4 is 1, the input is
malformed. malformed.
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 Validation 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. These algorithms are described for illustration purposes object or for selecting the key to be used to decrypt a JWE object.
This guidance describes a family of possible algorithms, rather than
a single algorithm, because in different contexts, not all the
sources of keys will be used, they can be tried in different orders,
and sometimes not all the collected keys will be tried; hence,
different algorithms will be used in different application contexts.
These algorithms use some or all of the steps described below; the
order and inclusion of the steps does not mean that they need to be
performed in this order or that they are all required in all
contexts. The steps below are described for illustration purposes
only; specific applications can and are likely to use different only; specific applications can and are likely to use different
algorithms. This supplements the normative information on key algorithms. Specific applications will frequently have a much
simpler method of 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 supplements the normative information on key
location in Section 6. location in Section 6.
The gist of these algorithms is to collect a set of keys from known Algorithm steps may include:
applicable sources of keys and then to use them to attempt to
validate the digital signature or MAC value of a JWS. Potential
sources of keys include:
o Keys supplied by the application protocol being used.
o Keys referenced by the "jku" (JWK Set URL) Header Parameter. 1. Collect a set of potentially applicable keys. Sources of keys
may include:
o The key provided by the "jwk" (JSON Web Key) Header Parameter. * Keys supplied by the application protocol being used.
o The keys referenced by the "kid" (Key ID) Header Parameter. * Keys referenced by the "jku" (JWK Set URL) Header Parameter.
o Keys referenced by the "x5u" (X.509 URL) Header Parameter. * The key provided by the "jwk" (JSON Web Key) Header Parameter.
o The key provided by the "x5c" (X.509 Certificate Chain) Header * Keys referenced by the "x5u" (X.509 URL) Header Parameter.
Parameter.
o The key referenced by the "x5t" (X.509 Certificate SHA-1 * The key provided by the "x5c" (X.509 Certificate Chain) Header
Thumbprint) Header Parameter. Parameter.
o Other applicable keys available to the application. * Other applicable keys available to the application.
In some cases, the list of collected keys will be ordered in a 2. Order the set of collected keys. For instance, keys referenced
particular way. For instance, keys referenced by the "kid" or "x5t" by "kid" (Key ID) or "x5t" (X.509 Certificate SHA-1 Thumbprint)
parameters might be used before other keys. parameters might be tried before other keys. Likewise, keys with
certain "kty" (Key Type) values, "alg" (Algorithm) values, or
other member values might be ordered before keys with other "kty"
values, "alg" values, or other member values.
Finally, signature or MAC validation will be tried with some or all 3. Filter the set of collected keys. For instance, only keys
of the collected and possibly ordered keys. This process will referenced by "kid" (key ID) or "x5t" (X.509 certificate SHA-1
normally terminate following a successful validation. thumbprint) parameters might be tried by the application. Keys
with an invalid certificate chain would typically be excluded.
Keys with inappropriate "alg" (algorithm), "use" (public key
use), or "key_ops" (key operations) values would likewise
typically be excluded. Keys might be filtered to include or
exclude keys with certain "kty" (key type) values or other member
values. A limit on the number of keys to be tried might also be
applied.
This guidance identifies a set of algorithms, rather than a single 4. Attempt signature or MAC validation for a JWS object or
algorithm, because in different contexts, not all the sources of keys decryption of a JWE object with some or all of the collected and
will be used, they can be tried in different orders, and sometimes possibly ordered and/or filtered keys. This process will
not all the collected keys will be tried. normally terminate following a successful validation or
decryption.
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
uses an extension Header Parameter name uses an extension Header Parameter name
"http://example.invalid/UNDEFINED" that they do not understand. Any "http://example.invalid/UNDEFINED" that they do not understand. Any
other similar input, in which the use of the value other similar input, in which the use of the value
"http://example.invalid/UNDEFINED" is substituted for any other "http://example.invalid/UNDEFINED" is substituted for any other
skipping to change at page 46, line 38 skipping to change at page 47, line 13
Hannes Tschofenig, and Sean Turner. Hannes Tschofenig, and Sean Turner.
Jim Schaad and Karen O'Donoghue chaired the JOSE working group and Jim Schaad and Karen O'Donoghue chaired the JOSE working group and
Sean Turner and Stephen Farrell served as Security area directors Sean Turner and Stephen Farrell served as Security area directors
during the creation of this specification. 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 ]]
-20
o Made terminology definitions more consistent, addressing issue
#165.
o Restructured the JSON Serialization section to call out the
parameters used in hanging lists, addressing issue #121.
o Described key filtering and refined other aspects of the text in
the appendix "Notes on Key Selection", addressing issue #93.
o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis,
addressing issue #90.
-19 -19
o Added the appendix "Notes on Validation Key Selection", addressing o Added the appendix "Notes on Validation Key Selection", addressing
issue #93. issue #93.
o Reordered the key selection parameters. o Reordered the key selection parameters.
-18 -18
o Updated the mandatory-to-implement (MTI) language to say that o Updated the mandatory-to-implement (MTI) language to say that
 End of changes. 54 change blocks. 
145 lines changed or deleted 178 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/