draft-ietf-jose-json-web-signature-21.txt   draft-ietf-jose-json-web-signature-22.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: August 18, 2014 Ping Identity Expires: September 3, 2014 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
February 14, 2014 March 2, 2014
JSON Web Signature (JWS) JSON Web Signature (JWS)
draft-ietf-jose-json-web-signature-21 draft-ietf-jose-json-web-signature-22
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 August 18, 2014. This Internet-Draft will expire on September 3, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 17 skipping to change at page 2, line 17
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. JSON Web Signature (JWS) Overview . . . . . . . . . . . . . . 6 3. JSON Web Signature (JWS) Overview . . . . . . . . . . . . . . 6
3.1. Example JWS . . . . . . . . . . . . . . . . . . . . . . . 7 3.1. Example JWS . . . . . . . . . . . . . . . . . . . . . . . 8
4. JWS Header . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4. JWS Header . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.1. Registered Header Parameter Names . . . . . . . . . . . . 9 4.1. Registered Header Parameter Names . . . . . . . . . . . . 9
4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 9 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 10
4.1.2. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 10 4.1.2. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 10
4.1.3. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 10 4.1.3. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 10
4.1.4. "kid" (Key ID) Header Parameter . . . . . . . . . . . 10 4.1.4. "kid" (Key ID) Header Parameter . . . . . . . . . . . 10
4.1.5. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 10 4.1.5. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 11
4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter . . . 11 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter . . . 11
4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header 4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header
Parameter . . . . . . . . . . . . . . . . . . . . . . 11 Parameter . . . . . . . . . . . . . . . . . . . . . . 11
4.1.8. "typ" (Type) Header Parameter . . . . . . . . . . . . 11 4.1.8. "typ" (Type) Header Parameter . . . . . . . . . . . . 12
4.1.9. "cty" (Content Type) Header Parameter . . . . . . . . 12 4.1.9. "cty" (Content Type) Header Parameter . . . . . . . . 12
4.1.10. "crit" (Critical) Header Parameter . . . . . . . . . . 12 4.1.10. "crit" (Critical) Header Parameter . . . . . . . . . . 13
4.2. Public Header Parameter Names . . . . . . . . . . . . . . 13 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 13
4.3. Private Header Parameter Names . . . . . . . . . . . . . . 13 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 14
5. Producing and Consuming JWSs . . . . . . . . . . . . . . . . . 13 5. Producing and Consuming JWSs . . . . . . . . . . . . . . . . . 14
5.1. Message Signature or MAC Computation . . . . . . . . . . . 13 5.1. Message Signature or MAC Computation . . . . . . . . . . . 14
5.2. Message Signature or MAC Validation . . . . . . . . . . . 14 5.2. Message Signature or MAC Validation . . . . . . . . . . . 15
5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 16 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 16
6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 16 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 16
7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 16 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 17
7.1. JWS Compact Serialization . . . . . . . . . . . . . . . . 17 7.1. JWS Compact Serialization . . . . . . . . . . . . . . . . 17
7.2. JWS JSON Serialization . . . . . . . . . . . . . . . . . . 17 7.2. JWS JSON Serialization . . . . . . . . . . . . . . . . . . 17
8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 19 8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 19
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19
9.1. JSON Web Signature and Encryption Header Parameters 9.1. JSON Web Signature and Encryption Header Parameters
Registry . . . . . . . . . . . . . . . . . . . . . . . . . 20 Registry . . . . . . . . . . . . . . . . . . . . . . . . . 20
9.1.1. Registration Template . . . . . . . . . . . . . . . . 20 9.1.1. Registration Template . . . . . . . . . . . . . . . . 21
9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 21 9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 21
9.2. Media Type Registration . . . . . . . . . . . . . . . . . 22 9.2. Media Type Registration . . . . . . . . . . . . . . . . . 23
9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 22 9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 23
10. Security Considerations . . . . . . . . . . . . . . . . . . . 23 10. Security Considerations . . . . . . . . . . . . . . . . . . . 24
10.1. Cryptographic Security Considerations . . . . . . . . . . 23 10.1. Cryptographic Security Considerations . . . . . . . . . . 24
10.2. JSON Security Considerations . . . . . . . . . . . . . . . 24 10.2. JSON Security Considerations . . . . . . . . . . . . . . . 25
10.3. Unicode Comparison Security Considerations . . . . . . . . 25 10.3. Unicode Comparison Security Considerations . . . . . . . . 26
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26
11.1. Normative References . . . . . . . . . . . . . . . . . . . 26 11.1. Normative References . . . . . . . . . . . . . . . . . . . 26
11.2. Informative References . . . . . . . . . . . . . . . . . . 27 11.2. Informative References . . . . . . . . . . . . . . . . . . 28
Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 28 Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 28
A.1. Example JWS using HMAC SHA-256 . . . . . . . . . . . . . . 28 A.1. Example JWS using HMAC SHA-256 . . . . . . . . . . . . . . 29
A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 28 A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 29
A.1.2. Validating . . . . . . . . . . . . . . . . . . . . . . 30 A.1.2. Validating . . . . . . . . . . . . . . . . . . . . . . 31
A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 . . . . . . . . 30 A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 . . . . . . . . 31
A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 31 A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 31
A.2.2. Validating . . . . . . . . . . . . . . . . . . . . . . 33 A.2.2. Validating . . . . . . . . . . . . . . . . . . . . . . 33
A.3. Example JWS using ECDSA P-256 SHA-256 . . . . . . . . . . 33 A.3. Example JWS using ECDSA P-256 SHA-256 . . . . . . . . . . 34
A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 33 A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 34
A.3.2. Validating . . . . . . . . . . . . . . . . . . . . . . 35 A.3.2. Validating . . . . . . . . . . . . . . . . . . . . . . 36
A.4. Example JWS using ECDSA P-521 SHA-512 . . . . . . . . . . 36 A.4. Example JWS using ECDSA P-521 SHA-512 . . . . . . . . . . 36
A.4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 36 A.4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 36
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 . . . . . . . . . 40
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 . . . . 41
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 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 . . . 46
Appendix F. Detached Content . . . . . . . . . . . . . . . . . . 46 Appendix F. Detached Content . . . . . . . . . . . . . . . . . . 46
Appendix G. Acknowledgements . . . . . . . . . . . . . . . . . . 46 Appendix G. Acknowledgements . . . . . . . . . . . . . . . . . . 47
Appendix H. Document History . . . . . . . . . . . . . . . . . . 47 Appendix H. Document History . . . . . . . . . . . . . . . . . . 47
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 54 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) [I-D.ietf-json-rfc4627bis] based data Object Notation (JSON) [RFC7158] based data structures. The JWS
structures. The JWS cryptographic mechanisms provide integrity cryptographic mechanisms provide integrity protection for an
protection for an arbitrary sequence of octets. 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 4, line 33 skipping to change at page 4, line 33
[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.
1.1. Notational Conventions 1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
document are to be interpreted as described in Key words for use in "OPTIONAL" in this document are to be interpreted as described in Key
RFCs to Indicate Requirement Levels [RFC2119]. If these words are words for use in RFCs to Indicate Requirement Levels [RFC2119]. If
used without being spelled in uppercase then they are to be these words are used without being spelled in uppercase then they are
interpreted with their normal natural language meanings. to be interpreted with their normal natural language meanings.
BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per
Section 2. Section 2.
UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation
of STRING. of STRING.
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)
signed or MACed message. A data structure representing a digitally signed or MACed message.
JWS Header JSON object containing the parameters describing the JWS Header
cryptographic operations and parameters employed. The JWS Header JSON object containing the parameters describing the cryptographic
members are the union of the members of the JWS Protected Header operations and parameters employed. The JWS Header members are
and the JWS Unprotected Header. The members of the JWS Header are the union of the members of the JWS Protected Header and the JWS
Header Parameters. 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
message. The payload can contain an arbitrary sequence of octets. 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
and the JWS Payload. Digital signature or MAC over the JWS Protected Header and the JWS
Payload.
Header Parameter A name/value pair that is member of the JWS Header. Header Parameter
A name/value pair that is member of the JWS Header.
JWS Protected Header JSON object that contains the JWS Header JWS Protected Header
Parameters that are integrity protected by the JWS Signature JSON object that contains the JWS Header Parameters that are
digital signature or MAC operation. For the JWS Compact integrity protected by the JWS Signature digital signature or MAC
Serialization, this comprises the entire JWS Header. For the JWS operation. For the JWS Compact Serialization, this comprises the
JSON Serialization, this is one component of the JWS Header. entire JWS Header. For the JWS JSON Serialization, this is one
component of the JWS Header.
JWS Unprotected Header JSON object that contains the JWS Header JWS Unprotected Header
Parameters that are not integrity protected. This can only be JSON object that contains the JWS Header Parameters that are not
present when using the JWS JSON Serialization. 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
character set defined in Section 5 of RFC 4648 [RFC4648], with all Base64 encoding using the URL- and filename-safe character set
trailing '=' characters omitted (as permitted by Section 3.2). defined in Section 5 of RFC 4648 [RFC4648], with all trailing '='
(See Appendix C for notes on implementing base64url encoding characters omitted (as permitted by Section 3.2). (See Appendix C
without padding.) for notes on implementing base64url encoding without padding.)
JWS Signing Input The input to the digital signature or MAC JWS Signing Input
computation. Its value is ASCII(BASE64URL(UTF8(JWS Protected The input to the digital signature or MAC computation. Its value
Header)) || '.' || BASE64URL(JWS Payload)). is ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' ||
BASE64URL(JWS Payload)).
JWS Compact Serialization A representation of the JWS as a compact, JWS Compact Serialization
URL-safe string. A representation of the JWS as a compact, URL-safe string.
JWS JSON Serialization A representation of the JWS as a JSON object. JWS JSON Serialization
Unlike the JWS Compact Serialization, the JWS JSON Serialization A representation of the JWS as a JSON object. Unlike the JWS
enables multiple digital signatures and/or MACs to be applied to Compact Serialization, the JWS JSON Serialization enables multiple
the same content. This representation is neither optimized for digital signatures and/or MACs to be applied to the same content.
compactness nor URL-safe. This representation is neither optimized for compactness nor URL-
safe.
Collision-Resistant Name A name in a namespace that enables names to Collision-Resistant Name
be allocated in a manner such that they are highly unlikely to A name in a namespace that enables names to be allocated in a
collide with other names. Examples of collision-resistant manner such that they are highly unlikely to collide with other
namespaces include: Domain Names, Object Identifiers (OIDs) as names. Examples of collision-resistant namespaces include: Domain
defined in the ITU-T X.660 and X.670 Recommendation series, and Names, Object Identifiers (OIDs) as defined in the ITU-T X.660 and
Universally Unique IDentifiers (UUIDs) [RFC4122]. When using an X.670 Recommendation series, and Universally Unique IDentifiers
administratively delegated namespace, the definer of a name needs (UUIDs) [RFC4122]. When using an administratively delegated
to take reasonable precautions to ensure they are in control of namespace, the definer of a name needs to take reasonable
the portion of the namespace they use to define the name. precautions to ensure they are in control of the portion of the
namespace they use to define the name.
StringOrURI A JSON string value, with the additional requirement StringOrURI
that while arbitrary string values MAY be used, any value A JSON string value, with the additional requirement that while
containing a ":" character MUST be a URI [RFC3986]. StringOrURI arbitrary string values MAY be used, any value containing a ":"
values are compared as case-sensitive strings with no character MUST be a URI [RFC3986]. StringOrURI values are
transformations or canonicalizations applied. compared as case-sensitive strings with no 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
cryptographic operations and parameters employed. The JWS Header JSON object containing the parameters describing the cryptographic
members are the union of the members of the JWS Protected Header operations and parameters employed. The JWS Header members are
and the JWS Unprotected Header, as described below. the union of the members of the JWS Protected Header and the JWS
Unprotected Header, as described below.
JWS Payload The sequence of octets to be secured -- a.k.a., the JWS Payload
message. The payload can contain an arbitrary sequence of octets. 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
and the JWS Payload. Digital signature or MAC over the JWS Protected Header and the JWS
Payload.
The JWS Header represents the combination of these values: The JWS Header represents the combination of these values:
JWS Protected Header JSON object that contains the JWS Header JWS Protected Header
Parameters that are integrity protected by the JWS Signature JSON object that contains the JWS Header Parameters that are
digital signature or MAC operation. integrity protected by the JWS Signature digital signature or MAC
operation.
JWS Unprotected Header JSON object that contains the JWS Header JWS Unprotected Header
Parameters that are not integrity protected. JSON object that contains the JWS Header Parameters that are not
integrity protected.
This document defines two serializations for JWS objects: a compact, This document defines two serializations for JWS objects: a compact,
URL-safe serialization called the JWS Compact Serialization and a URL-safe serialization called the JWS Compact Serialization and a
JSON serialization called the JWS JSON Serialization. In both JSON serialization called the JWS JSON Serialization. In both
serializations, the JWS Protected Header, JWS Payload, and JWS serializations, the JWS Protected Header, JWS Payload, and JWS
Signature are base64url encoded for transmission, since JSON lacks a Signature are base64url encoded for transmission, since JSON lacks a
way to directly represent octet sequences. way to directly represent octet sequences.
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 12, line 49 skipping to change at page 13, line 18
"example;part="1/2"". "example;part="1/2"".
4.1.10. "crit" (Critical) Header Parameter 4.1.10. "crit" (Critical) Header Parameter
The "crit" (critical) Header Parameter indicates that extensions to The "crit" (critical) Header Parameter indicates that extensions to
the initial RFC versions of [[ this specification ]] and [JWA] are the initial RFC versions of [[ this specification ]] and [JWA] are
being used that MUST be understood and processed. Its value is an being used that MUST be understood and processed. Its value is an
array listing the Header Parameter names present in the JWS Header array listing the Header Parameter names present in the JWS Header
that use those extensions. If any of the listed extension Header that use those extensions. If any of the listed extension Header
Parameters are not understood and supported by the receiver, it MUST Parameters are not understood and supported by the receiver, it MUST
reject the JWS. Senders must not include Header Parameter names reject the JWS. Senders MUST NOT include Header Parameter names
defined by the initial RFC versions of [[ this specification ]] or defined by the initial RFC versions of [[ this specification ]] or
[JWA] for use with JWS, duplicate names, or names that do not occur [JWA] for use with JWS, duplicate names, or names that do not occur
as Header Parameter names within the JWS Header in the "crit" list. as Header Parameter names within the JWS Header in the "crit" list.
Senders MUST not use the empty list "[]" as the "crit" value. Senders MUST NOT use the empty list "[]" as the "crit" value.
Recipients MAY reject the JWS if the critical list contains any Recipients MAY reject the JWS if the critical list contains any
Header Parameter names defined by the initial RFC versions of [[ this Header Parameter names defined by the initial RFC versions of [[ this
specification ]] or [JWA] for use with JWS, or any other constraints specification ]] or [JWA] for use with JWS, or any other constraints
on its use are violated. This Header Parameter MUST be integrity on its use are violated. This Header Parameter MUST be integrity
protected, and therefore MUST occur only within the JWS Protected protected, and therefore MUST occur only within the JWS Protected
Header, when used. Use of this Header Parameter is OPTIONAL. This Header, when used. Use of this Header Parameter is OPTIONAL. This
Header Parameter MUST be understood and processed by implementations. Header Parameter MUST be understood and processed by implementations.
An example use, along with a hypothetical "exp" (expiration-time) An example use, along with a hypothetical "exp" (expiration-time)
field is: field is:
skipping to change at page 15, line 20 skipping to change at page 15, line 36
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
[I-D.ietf-json-rfc4627bis], which is the JWS Protected Header. [RFC7158], 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 16, line 19 skipping to change at page 16, line 35
the algorithm is, the Unicode string "alg" will be checked against the algorithm is, the Unicode string "alg" will be checked against
the member names in the JWS Header to see if there is a matching the member names in the JWS Header to see if there is a matching
Header Parameter name. The same process is then used to determine if Header Parameter name. The same process is then used to determine if
the value of the "alg" Header Parameter represents a supported the value of the "alg" Header Parameter represents a supported
algorithm. algorithm.
Since the only string comparison operations that are performed are Since the only string comparison operations that are performed are
equality and inequality, the same rules can be used for comparing equality and inequality, the same rules can be used for comparing
both member names and member values against known strings. The JSON both member names and member values against known strings. The JSON
rules for doing member name comparison are described in Section 8.3 rules for doing member name comparison are described in Section 8.3
of [I-D.ietf-json-rfc4627bis]. of [RFC7158].
Also, see the JSON security considerations in Section 10.2 and the Also, see the JSON security considerations in Section 10.2 and the
Unicode security considerations in Section 10.3. Unicode security considerations in Section 10.3.
6. Key Identification 6. Key Identification
It is necessary for the recipient of a JWS to be able to determine It is necessary for the recipient of a JWS to be able to determine
the key that was employed for the digital signature or MAC operation. the key that was employed for the digital signature or MAC operation.
The key employed can be identified using the Header Parameter methods The key employed can be identified using the Header Parameter methods
described in Section 4.1 or can be identified using methods that are described in Section 4.1 or can be identified using methods that are
skipping to change at page 17, line 32 skipping to change at page 18, line 4
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. Content using the JWS JSON Serialization content as a JSON object. Content using the JWS JSON Serialization
can be secured with more than one digital signature and/or MAC can be secured with more than one digital signature and/or MAC
operation. This representation is neither optimized for compactness operation. This representation is neither optimized for compactness
nor URL-safe. nor URL-safe.
The following members are defined for use in top-level JSON objects The following members are defined for use in top-level JSON objects
used for the JWS JSON Serialization: used for the JWS JSON Serialization:
payload The "payload" member MUST be present and contain the value
payload
The "payload" member MUST be present and contain the value
BASE64URL(JWS Payload). BASE64URL(JWS Payload).
signatures The "signatures" member value MUST be an array of JSON signatures
objects. Each object represents a signature or MAC over the JWS The "signatures" member value MUST be an array of JSON objects.
Payload and the JWS Protected Header. Each object represents a signature or MAC over the JWS Payload and
the JWS Protected Header.
The following members are defined for use in the JSON objects that The following members are defined for use in the JSON objects that
are elements of the "signatures" array: are elements of the "signatures" array:
protected The "protected" member MUST be present and contain the protected
value BASE64URL(UTF8(JWS Protected Header)) when the JWS Protected The "protected" member MUST be present and contain the value
BASE64URL(UTF8(JWS Protected Header)) when the JWS Protected
Header value is non-empty; otherwise, it MUST be absent. These Header value is non-empty; otherwise, it MUST be absent. These
Header Parameter values are integrity protected. Header Parameter values are integrity protected.
header The "header" member MUST be present and contain the value JWS header
The "header" member MUST be present and contain the value JWS
Unprotected Header when the JWS Unprotected Header value is non- Unprotected Header when the JWS Unprotected Header value is non-
empty; otherwise, it MUST be absent. This value is represented as empty; otherwise, it MUST be absent. This value is represented as
an unencoded JSON object, rather than as a string. These Header an unencoded JSON object, rather than as a string. These Header
Parameter values are not integrity protected. Parameter values are not integrity protected.
signature
signature The "signature" member MUST be present and contain the The "signature" member MUST be present and contain the value
value BASE64URL(JWS Signature). BASE64URL(JWS Signature).
At least one of the "protected" and "header" members MUST be present At least one of the "protected" and "header" members MUST be present
for each signature/MAC computation so that an "alg" Header Parameter for each signature/MAC computation so that an "alg" Header Parameter
value is conveyed. value is conveyed.
Additional members can be present in both the JSON objects defined Additional members can be present in both the JSON objects defined
above; if not understood by implementations encountering them, they above; if not understood by implementations encountering them, they
MUST be ignored. MUST be ignored.
The Header Parameter values used when creating or validating The Header Parameter values used when creating or validating
skipping to change at page 19, line 13 skipping to change at page 19, line 34
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
deployment, and might not be readily available in implementation deployment, and might not be readily available in implementation
toolkits. TLS version 1.0 [RFC2246] is the most widely deployed toolkits.
version, and will give the broadest interoperability.
To protect against information disclosure and tampering, To protect against information disclosure and tampering,
confidentiality protection MUST be applied using TLS with a confidentiality protection MUST be applied using TLS with a
ciphersuite that provides confidentiality and integrity protection. ciphersuite that provides confidentiality and integrity protection.
Whenever TLS is used, a TLS server certificate check MUST be Whenever TLS is used, a TLS server certificate check MUST be
performed, per RFC 6125 [RFC6125]. performed, per RFC 6125 [RFC6125].
9. IANA Considerations 9. IANA Considerations
skipping to change at page 25, line 6 skipping to change at page 25, line 30
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 4 of the JSON Data Interchange Format specification Section 4 of the JSON Data Interchange Format specification [RFC7158]
[I-D.ietf-json-rfc4627bis] states "The names within an object SHOULD states "The names within an object SHOULD be unique", whereas this
be unique", whereas this specification states that "Header Parameter specification states that "Header Parameter names within this object
names within this object MUST be unique; recipients MUST either MUST be unique; recipients MUST either reject JWSs with duplicate
reject JWSs with duplicate Header Parameter names or use a JSON Header Parameter names or use a JSON parser that returns only the
parser that returns only the lexically last duplicate member name, as lexically last duplicate member name, as specified in Section 15.12
specified in Section 15.12 (The JSON Object) of ECMAScript 5.1 (The JSON Object) of ECMAScript 5.1 [ECMAScript]". Thus, this
[ECMAScript]". Thus, this specification requires that the Section 4 specification requires that the Section 4 "SHOULD" be treated as a
"SHOULD" be treated as a "MUST" by senders and that it be either "MUST" by senders and that it be either treated as a "MUST" or in the
treated as a "MUST" or in the manner specified in ECMAScript 5.1 by manner specified in ECMAScript 5.1 by receivers. Ambiguous and
receivers. Ambiguous and potentially exploitable situations could potentially exploitable situations could arise if the JSON parser
arise if the JSON parser used does not enforce the uniqueness of used does not enforce the uniqueness of member names or returns an
member names or returns an unpredictable value for duplicate member unpredictable value for duplicate member names.
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 Section 8.3 verbatim after performing any escape processing (as per Section 8.3
of [I-D.ietf-json-rfc4627bis]). This means, for instance, that these of [RFC7158]). This means, for instance, that these JSON strings
JSON strings must compare as being equal ("sig", "\u0073ig"), whereas must compare as being equal ("sig", "\u0073ig"), whereas these must
these must all compare as being not equal to the first set or to each all compare as being not equal to the first set or to each other
other ("SIG", "Sig", "si\u0047"). ("SIG", "Sig", "si\u0047").
JSON strings can contain characters outside the Unicode Basic JSON strings can contain characters outside the Unicode Basic
Multilingual Plane. For instance, the G clef character (U+1D11E) may Multilingual Plane. For instance, the G clef character (U+1D11E) may
be represented in a JSON string as "\uD834\uDD1E". Ideally, JWS be represented in a JSON string as "\uD834\uDD1E". Ideally, JWS
implementations SHOULD ensure that characters outside the Basic implementations SHOULD ensure that characters outside the Basic
Multilingual Plane are preserved and compared correctly; Multilingual Plane are preserved and compared correctly;
alternatively, if this is not possible due to these characters alternatively, if this is not possible due to these characters
exercising limitations present in the underlying JSON implementation, exercising limitations present in the underlying JSON implementation,
then input containing them MUST be rejected. then input containing them MUST be rejected.
skipping to change at page 26, line 4 skipping to change at page 26, line 25
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]
Bray, T., "The JSON Data Interchange Format",
draft-ietf-json-rfc4627bis-10 (work in progress),
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),
February 2014. March 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),
February 2014. March 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
Extensions (MIME) Part Two: Media Types", RFC 2046, Extensions (MIME) Part Two: Media Types", RFC 2046,
November 1996. November 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
RFC 2246, January 1999.
[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.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
skipping to change at page 27, line 31 skipping to change at page 27, line 44
Housley, R., and W. Polk, "Internet X.509 Public Key Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation List Infrastructure Certificate and Certificate Revocation List
(CRL) Profile", RFC 5280, May 2008. (CRL) Profile", RFC 5280, May 2008.
[RFC6125] Saint-Andre, P. and J. Hodges, "Representation and [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and
Verification of Domain-Based Application Service Identity Verification of Domain-Based Application Service Identity
within Internet Public Key Infrastructure Using X.509 within Internet Public Key Infrastructure Using X.509
(PKIX) Certificates in the Context of Transport Layer (PKIX) Certificates in the Context of Transport Layer
Security (TLS)", RFC 6125, March 2011. Security (TLS)", RFC 6125, March 2011.
[RFC7158] Bray, T., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7158, March 2014.
[USASCII] American National Standards Institute, "Coded Character [USASCII] American National Standards Institute, "Coded Character
Set -- 7-bit American Standard Code for Information Set -- 7-bit American Standard Code for Information
Interchange", ANSI X3.4, 1986. Interchange", ANSI X3.4, 1986.
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), February 2014. (work in progress), March 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), February 2014. progress), March 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.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
skipping to change at page 47, line 27 skipping to change at page 47, line 33
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 ]]
-22
o Corrected RFC 2119 terminology usage.
o Replaced references to draft-ietf-json-rfc4627bis with RFC 7158.
-21 -21
o Applied review comments to the appendix "Notes on Key Selection", o Applied review comments to the appendix "Notes on Key Selection",
addressing issue #93. addressing issue #93.
o Changed some references from being normative to informative, o Changed some references from being normative to informative,
addressing issue #90. addressing issue #90.
o Applied review comments to the JSON Serialization section, o Applied review comments to the JSON Serialization section,
addressing issue #121. addressing issue #121.
 End of changes. 61 change blocks. 
150 lines changed or deleted 170 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/