draft-ietf-jose-json-web-signature-35.txt   draft-ietf-jose-json-web-signature-36.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: April 20, 2015 Ping Identity Expires: April 27, 2015 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
October 17, 2014 October 24, 2014
JSON Web Signature (JWS) JSON Web Signature (JWS)
draft-ietf-jose-json-web-signature-35 draft-ietf-jose-json-web-signature-36
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 April 20, 2015. This Internet-Draft will expire on April 27, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
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
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 5
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6
3. JSON Web Signature (JWS) Overview . . . . . . . . . . . . . . 6 3. JSON Web Signature (JWS) Overview . . . . . . . . . . . . . . 7
3.1. JWS Compact Serialization Overview . . . . . . . . . . . 7 3.1. JWS Compact Serialization Overview . . . . . . . . . . . 8
3.2. JWS JSON Serialization Overview . . . . . . . . . . . . . 7 3.2. JWS JSON Serialization Overview . . . . . . . . . . . . . 8
3.3. Example JWS . . . . . . . . . . . . . . . . . . . . . . . 8 3.3. Example JWS . . . . . . . . . . . . . . . . . . . . . . . 9
4. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . . . 9 4. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.1. Registered Header Parameter Names . . . . . . . . . . . . 9 4.1. Registered Header Parameter Names . . . . . . . . . . . . 11
4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 10 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 11
4.1.2. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 10 4.1.2. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 11
4.1.3. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 10 4.1.3. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 11
4.1.4. "kid" (Key ID) Header Parameter . . . . . . . . . . . 10 4.1.4. "kid" (Key ID) Header Parameter . . . . . . . . . . . 12
4.1.5. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 11 4.1.5. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 12
4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter . . . 11 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter . . . 12
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 . . . . . . . . . . . . . . . . . . . . . . 13
4.1.8. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) 4.1.8. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint)
Header Parameter . . . . . . . . . . . . . . . . . . . 12 Header Parameter . . . . . . . . . . . . . . . . . . . 13
4.1.9. "typ" (Type) Header Parameter . . . . . . . . . . . . 12 4.1.9. "typ" (Type) Header Parameter . . . . . . . . . . . . 13
4.1.10. "cty" (Content Type) Header Parameter . . . . . . . . 13 4.1.10. "cty" (Content Type) Header Parameter . . . . . . . . 14
4.1.11. "crit" (Critical) Header Parameter . . . . . . . . . . 13 4.1.11. "crit" (Critical) Header Parameter . . . . . . . . . . 14
4.2. Public Header Parameter Names . . . . . . . . . . . . . . 14 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 15
4.3. Private Header Parameter Names . . . . . . . . . . . . . 14 4.3. Private Header Parameter Names . . . . . . . . . . . . . 15
5. Producing and Consuming JWSs . . . . . . . . . . . . . . . . . 14 5. Producing and Consuming JWSs . . . . . . . . . . . . . . . . . 15
5.1. Message Signature or MAC Computation . . . . . . . . . . 14 5.1. Message Signature or MAC Computation . . . . . . . . . . 15
5.2. Message Signature or MAC Validation . . . . . . . . . . . 15 5.2. Message Signature or MAC Validation . . . . . . . . . . . 16
5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 17 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 18
6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 18 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 19
7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 18 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 19
7.1. JWS Compact Serialization . . . . . . . . . . . . . . . . 19 7.1. JWS Compact Serialization . . . . . . . . . . . . . . . . 20
7.2. JWS JSON Serialization . . . . . . . . . . . . . . . . . 19 7.2. JWS JSON Serialization . . . . . . . . . . . . . . . . . 20
8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 21 7.2.1. General JWS JSON Serialization Syntax . . . . . . . . 20
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 7.2.2. Flattened JWS JSON Serialization Syntax . . . . . . . 22
8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 23
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23
9.1. JSON Web Signature and Encryption Header Parameters 9.1. JSON Web Signature and Encryption Header Parameters
Registry . . . . . . . . . . . . . . . . . . . . . . . . 22 Registry . . . . . . . . . . . . . . . . . . . . . . . . 24
9.1.1. Registration Template . . . . . . . . . . . . . . . . 23
9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 23
9.2. Media Type Registration . . . . . . . . . . . . . . . . . 25 9.1.1. Registration Template . . . . . . . . . . . . . . . . 25
9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 25 9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 25
10. Security Considerations . . . . . . . . . . . . . . . . . . . 26 9.2. Media Type Registration . . . . . . . . . . . . . . . . . 27
10.1. Key Entropy and Random Values . . . . . . . . . . . . . . 26 9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 27
10.2. Key Protection . . . . . . . . . . . . . . . . . . . . . 27 10. Security Considerations . . . . . . . . . . . . . . . . . . . 28
10.3. Key Origin Authentication . . . . . . . . . . . . . . . . 27 10.1. Key Entropy and Random Values . . . . . . . . . . . . . . 28
10.4. Cryptographic Agility . . . . . . . . . . . . . . . . . . 27 10.2. Key Protection . . . . . . . . . . . . . . . . . . . . . 29
10.5. Differences between Digital Signatures and MACs . . . . . 27 10.3. Key Origin Authentication . . . . . . . . . . . . . . . . 29
10.6. Algorithm Validation . . . . . . . . . . . . . . . . . . 28 10.4. Cryptographic Agility . . . . . . . . . . . . . . . . . . 29
10.7. Algorithm Protection . . . . . . . . . . . . . . . . . . 28 10.5. Differences between Digital Signatures and MACs . . . . . 29
10.8. Chosen Plaintext Attacks . . . . . . . . . . . . . . . . 29 10.6. Algorithm Validation . . . . . . . . . . . . . . . . . . 30
10.9. Timing Attacks . . . . . . . . . . . . . . . . . . . . . 29 10.7. Algorithm Protection . . . . . . . . . . . . . . . . . . 30
10.10. Replay Protection . . . . . . . . . . . . . . . . . . . . 29 10.8. Chosen Plaintext Attacks . . . . . . . . . . . . . . . . 31
10.11. SHA-1 Certificate Thumbprints . . . . . . . . . . . . . . 29 10.9. Timing Attacks . . . . . . . . . . . . . . . . . . . . . 31
10.12. JSON Security Considerations . . . . . . . . . . . . . . 30 10.10. Replay Protection . . . . . . . . . . . . . . . . . . . . 31
10.13. Unicode Comparison Security Considerations . . . . . . . 30 10.11. SHA-1 Certificate Thumbprints . . . . . . . . . . . . . . 31
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 31 10.12. JSON Security Considerations . . . . . . . . . . . . . . 32
11.1. Normative References . . . . . . . . . . . . . . . . . . 31 10.13. Unicode Comparison Security Considerations . . . . . . . 32
11.2. Informative References . . . . . . . . . . . . . . . . . 32 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 34 11.1. Normative References . . . . . . . . . . . . . . . . . . 33
A.1. Example JWS using HMAC SHA-256 . . . . . . . . . . . . . 34 11.2. Informative References . . . . . . . . . . . . . . . . . 34
A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 34 Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 36
A.1.2. Validating . . . . . . . . . . . . . . . . . . . . . . 36 A.1. Example JWS using HMAC SHA-256 . . . . . . . . . . . . . 36
A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 . . . . . . . 36 A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 36
A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 37 A.1.2. Validating . . . . . . . . . . . . . . . . . . . . . . 38
A.2.2. Validating . . . . . . . . . . . . . . . . . . . . . . 39 A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 . . . . . . . 38
A.3. Example JWS using ECDSA P-256 SHA-256 . . . . . . . . . . 39 A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 39
A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 39 A.2.2. Validating . . . . . . . . . . . . . . . . . . . . . . 41
A.3.2. Validating . . . . . . . . . . . . . . . . . . . . . . 41 A.3. Example JWS using ECDSA P-256 SHA-256 . . . . . . . . . . 41
A.4. Example JWS using ECDSA P-521 SHA-512 . . . . . . . . . . 42 A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 41
A.4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 42 A.3.2. Validating . . . . . . . . . . . . . . . . . . . . . . 43
A.4.2. Validating . . . . . . . . . . . . . . . . . . . . . . 44 A.4. Example JWS using ECDSA P-521 SHA-512 . . . . . . . . . . 44
A.5. Example Unsecured JWS . . . . . . . . . . . . . . . . . . 44 A.4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 44
A.6. Example JWS Using JWS JSON Serialization . . . . . . . . 45 A.4.2. Validating . . . . . . . . . . . . . . . . . . . . . . 46
A.6.1. JWS Per-Signature Protected Headers . . . . . . . . . 45 A.5. Example Unsecured JWS . . . . . . . . . . . . . . . . . . 46
A.6.2. JWS Per-Signature Unprotected Headers . . . . . . . . 46 A.6. Example JWS using General JWS JSON Serialization . . . . 47
A.6.3. Complete JOSE Header Values . . . . . . . . . . . . . 46 A.6.1. JWS Per-Signature Protected Headers . . . . . . . . . 47
A.6.4. Complete JWS JSON Serialization Representation . . . . 46 A.6.2. JWS Per-Signature Unprotected Headers . . . . . . . . 48
Appendix B. "x5c" (X.509 Certificate Chain) Example . . . . . . . 47 A.6.3. Complete JOSE Header Values . . . . . . . . . . . . . 48
A.6.4. Complete JWS JSON Serialization Representation . . . . 48
A.7. Example JWS using Flattened JWS JSON Serialization . . . 49
Appendix B. "x5c" (X.509 Certificate Chain) Example . . . . . . . 50
Appendix C. Notes on implementing base64url encoding without Appendix C. Notes on implementing base64url encoding without
padding . . . . . . . . . . . . . . . . . . . . . . . 49 padding . . . . . . . . . . . . . . . . . . . . . . . 51
Appendix D. Notes on Key Selection . . . . . . . . . . . . . . . 50 Appendix D. Notes on Key Selection . . . . . . . . . . . . . . . 52
Appendix E. Negative Test Case for "crit" Header Parameter . . . 51 Appendix E. Negative Test Case for "crit" Header Parameter . . . 54
Appendix F. Detached Content . . . . . . . . . . . . . . . . . . 52 Appendix F. Detached Content . . . . . . . . . . . . . . . . . . 55
Appendix G. Acknowledgements . . . . . . . . . . . . . . . . . . 52 Appendix G. Acknowledgements . . . . . . . . . . . . . . . . . . 55
Appendix H. Document History . . . . . . . . . . . . . . . . . . 53 Appendix H. Document History . . . . . . . . . . . . . . . . . . 56
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 63 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 66
1. Introduction 1. Introduction
JSON Web Signature (JWS) represents content secured with digital JSON Web Signature (JWS) represents content secured with digital
signatures or Message Authentication Codes (MACs) using JavaScript signatures or Message Authentication Codes (MACs) using JavaScript
Object Notation (JSON) [RFC7159] based data structures. The JWS Object Notation (JSON) [RFC7159] based data structures. The JWS
cryptographic mechanisms provide integrity protection for an cryptographic mechanisms provide integrity protection for an
arbitrary sequence of octets. See Section 10.5 for a discussion on arbitrary sequence of octets. See Section 10.5 for a discussion on
the differences between Digital Signatures and MACs. the differences between Digital Signatures and MACs.
skipping to change at page 6, line 50 skipping to change at page 7, line 50
Serialization". Serialization".
These terms defined by the Internet Security Glossary, Version 2 These terms defined by the Internet Security Glossary, Version 2
[RFC4949] are incorporated into this specification: "Digital [RFC4949] are incorporated into this specification: "Digital
Signature" and "Message Authentication Code (MAC)". Signature" and "Message Authentication Code (MAC)".
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. These JSON data structures MAY structures and base64url encoding. These JSON data structures MAY
contain white space and/or line breaks. A JWS represents these contain white space and/or line breaks before or after any JSON
logical values (each of which is defined in Section 2): values or structural characters, in accordance with Section 2 of RFC
7159 [RFC7159]. A JWS represents these logical values (each of which
is defined in Section 2):
o JOSE Header o JOSE Header
o JWS Payload o JWS Payload
o JWS Signature o JWS Signature
For a JWS object, the JOSE Header members are the union of the For a JWS object, the JOSE Header members are the union of the
members of these values (each of which is defined in Section 2): members of these values (each of which is defined in Section 2):
o JWS Protected Header o JWS Protected Header
o JWS Unprotected Header o JWS Unprotected Header
skipping to change at page 9, line 19 skipping to change at page 10, line 22
representation using the JWS Compact Serialization (with line breaks representation using the JWS Compact Serialization (with line breaks
for display purposes only): for display purposes only):
eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
. .
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
. .
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
See Appendix A for additional examples, including an example using See Appendix A for additional examples, including examples using the
the JWS JSON Serialization in Appendix A.6. JWS JSON Serialization in Sections A.6 and A.7.
4. JOSE Header 4. JOSE Header
For a JWS object, the members of the JSON object(s) representing the For a JWS object, the members of the JSON object(s) representing the
JOSE Header describe the digital signature or MAC applied to the JWS JOSE Header describe the digital signature or MAC applied to the JWS
Protected Header and the JWS Payload and optionally additional Protected Header and the JWS Payload and optionally additional
properties of the JWS. The Header Parameter names within the JOSE properties of the JWS. The Header Parameter names within the JOSE
Header MUST be unique; JWS parsers MUST either reject JWSs with Header MUST be unique; JWS parsers MUST either reject JWSs with
duplicate Header Parameter names or use a JSON parser that returns duplicate Header Parameter names or use a JSON parser that returns
only the lexically last duplicate member name, as specified in only the lexically last duplicate member name, as specified in
skipping to change at page 19, line 21 skipping to change at page 20, line 24
BASE64URL(JWS Payload) || '.' || BASE64URL(JWS Payload) || '.' ||
BASE64URL(JWS Signature) BASE64URL(JWS Signature)
Only one signature/MAC is supported by the JWS Compact Serialization Only one signature/MAC is supported by the JWS Compact Serialization
and it provides no syntax to represent a JWS Unprotected Header and it provides no syntax to represent a JWS Unprotected Header
value. 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. Content using the JWS JSON Serialization content as a JSON object. This representation is neither optimized
can be secured with more than one digital signature and/or MAC for compactness nor URL-safe.
operation. This representation is neither optimized for compactness
nor URL-safe. Two closely related syntaxes are defined for the JWS JSON
Serialization: a fully general syntax, with which content can be
secured with more than one digital signature and/or MAC operation,
and a flattened syntax, which is optimized for the single digital
signature or MAC case.
7.2.1. General JWS JSON Serialization Syntax
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 fully general JWS JSON Serialization syntax:
payload payload
The "payload" member MUST be present and contain the value The "payload" member MUST be present and contain the value
BASE64URL(JWS Payload). BASE64URL(JWS Payload).
signatures signatures
The "signatures" member value MUST be an array of JSON objects. The "signatures" member value MUST be an array of JSON objects.
Each object represents a signature or MAC over the JWS Payload and Each object represents a signature or MAC over the JWS Payload and
the JWS Protected Header. the JWS Protected Header.
skipping to change at page 20, line 33 skipping to change at page 21, line 46
of Header Parameters comprises the JOSE Header. The Header Parameter of Header Parameters comprises the JOSE Header. The Header Parameter
names in the two locations MUST be disjoint. names in the two locations MUST be disjoint.
Each JWS Signature value is computed using the parameters of the Each JWS Signature value is computed using the parameters of the
corresponding JOSE Header value in the same manner as for the JWS corresponding JOSE Header value in the same manner as for the JWS
Compact Serialization. This has the desirable property that each JWS Compact Serialization. This has the desirable property that each JWS
Signature value represented in the "signatures" array is identical to Signature value represented in the "signatures" array is identical to
the value that would have been computed for the same parameter in the the value that would have been computed for the same parameter in the
JWS Compact Serialization, provided that the JWS Protected Header JWS Compact Serialization, provided that the JWS Protected Header
value for that signature/MAC computation (which represents the value for that signature/MAC computation (which represents the
integrity-protected Header Parameter values) matches that used in the integrity protected Header Parameter values) matches that used in the
JWS Compact Serialization. JWS Compact Serialization.
In summary, the syntax of a JWS using the JWS JSON Serialization is In summary, the syntax of a JWS using the general JWS JSON
as follows: Serialization is as follows:
{ {
"payload":"<payload contents>", "payload":"<payload contents>",
"signatures":[ "signatures":[
{"protected":"<integrity-protected header 1 contents>", {"protected":"<integrity-protected header 1 contents>",
"header":<non-integrity-protected header 1 contents>, "header":<non-integrity-protected header 1 contents>,
"signature":"<signature 1 contents>"}, "signature":"<signature 1 contents>"},
... ...
{"protected":"<integrity-protected header N contents>", {"protected":"<integrity-protected header N contents>",
"header":<non-integrity-protected header N contents>, "header":<non-integrity-protected header N contents>,
"signature":"<signature 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 JWS using the general JWS JSON
Serialization. Serialization syntax.
7.2.2. Flattened JWS JSON Serialization Syntax
The flattened JWS JSON Serialization syntax is based upon the general
syntax, but flattens it, optimizing it for the single digital
signature/MAC case. It flattens it by removing the "signatures"
member and instead placing those members defined for use in the
"signatures" array (the "protected", "header", and "signature"
members) in the top-level JSON object (at the same level as the
"payload" member).
The "signatures" member MUST NOT be present when using this syntax.
Other than this syntax difference, JWS JSON Serialization objects
using the flattened syntax are processed identically to those using
the general syntax.
In summary, the syntax of a JWS using the flattened JWS JSON
Serialization is as follows:
{
"payload":"<payload contents>",
"protected":"<integrity-protected header contents>",
"header":<non-integrity-protected header contents>,
"signature":"<signature contents>"
}
See Appendix A.7 for an example JWS using the flattened JWS JSON
Serialization syntax.
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. [RFC5246] is the most recent version.
To protect against information disclosure and tampering, To protect against information disclosure and tampering,
skipping to change at page 21, line 33 skipping to change at page 23, line 33
the TLS server certificate MUST be verified using the procedures the TLS server certificate MUST be verified using the procedures
described in Section 6 of RFC 6125 [RFC6125]. TLS is used by the described in Section 6 of RFC 6125 [RFC6125]. TLS is used by the
"jku" and "x5u" Header Parameters defined by this specification. "jku" and "x5u" Header Parameters defined by this specification.
9. IANA Considerations 9. IANA Considerations
The following registration procedure is used for all the registries The following registration procedure is used for all the registries
established by this specification. established by this specification.
Values are registered on a Specification Required [RFC5226] basis Values are registered on a Specification Required [RFC5226] basis
after a three-week review period on the [TBD]@ietf.org mailing list, after a three-week review period on the jose-reg-review@ietf.org
on the advice of one or more Designated Experts. However, to allow mailing list, on the advice of one or more Designated Experts.
for the allocation of values prior to publication, the Designated However, to allow for the allocation of values prior to publication,
Expert(s) may approve registration once they are satisfied that such the Designated Expert(s) may approve registration once they are
a specification will be published. satisfied that such a specification will be published.
Registration requests must be sent to the [TBD]@ietf.org mailing list Registration requests must be sent to the jose-reg-review@ietf.org
for review and comment, with an appropriate subject (e.g., "Request mailing list for review and comment, with an appropriate subject
for access token type: example"). [[ Note to the RFC Editor: The name (e.g., "Request for access token type: example").
of the mailing list should be determined in consultation with the
IESG and IANA. Suggested name: jose-reg-review. ]]
Within the review period, the Designated Expert(s) will either Within the review period, the Designated Expert(s) will either
approve or deny the registration request, communicating this decision approve or deny the registration request, communicating this decision
to the review list and IANA. Denials should include an explanation to the review list and IANA. Denials should include an explanation
and, if applicable, suggestions as to how to make the request and, if applicable, suggestions as to how to make the request
successful. Registration requests that are undetermined for a period successful. Registration requests that are undetermined for a period
longer than 21 days can be brought to the IESG's attention (using the longer than 21 days can be brought to the IESG's attention (using the
iesg@ietf.org mailing list) for resolution. iesg@ietf.org mailing list) for resolution.
Criteria that should be applied by the Designated Expert(s) includes Criteria that should be applied by the Designated Expert(s) includes
skipping to change at page 29, line 32 skipping to change at page 31, line 32
When cryptographic algorithms are implemented in such a way that When cryptographic algorithms are implemented in such a way that
successful operations take a different amount of time than successful operations take a different amount of time than
unsuccessful operations, attackers may be able to use the time unsuccessful operations, attackers may be able to use the time
difference to obtain information about the keys employed. Therefore, difference to obtain information about the keys employed. Therefore,
such timing differences must be avoided. such timing differences must be avoided.
10.10. Replay Protection 10.10. Replay Protection
While not directly in scope for this specification, note that While not directly in scope for this specification, note that
applications using JWS (or JWE) objects can thwart replay attacks by applications using JWS (or JWE) objects can thwart replay attacks by
including a unique message identifier as integrity-protected content including a unique message identifier as integrity protected content
in the JWS (or JWE) message and having the recipient verify that the in the JWS (or JWE) message and having the recipient verify that the
message has not been previously received or acted upon. message has not been previously received or acted upon.
10.11. SHA-1 Certificate Thumbprints 10.11. SHA-1 Certificate Thumbprints
A SHA-1 hash is used when computing "x5t" (X.509 Certificate SHA-1 A SHA-1 hash is used when computing "x5t" (X.509 Certificate SHA-1
Thumbprint) values, for compatibility reasons. Should an effective Thumbprint) values, for compatibility reasons. Should an effective
means of producing SHA-1 hash collisions be developed, and should an means of producing SHA-1 hash collisions be developed, and should an
attacker wish to interfere with the use of a known certificate on a attacker wish to interfere with the use of a known certificate on a
given system, this could be accomplished by creating another given system, this could be accomplished by creating another
skipping to change at page 32, line 43 skipping to change at page 34, line 43
Interchange Format", RFC 7159, March 2014. Interchange Format", RFC 7159, March 2014.
11.2. Informative References 11.2. Informative References
[CanvasApp] [CanvasApp]
Facebook, "Canvas Applications", 2010. Facebook, "Canvas Applications", 2010.
[I-D.ietf-uta-tls-bcp] [I-D.ietf-uta-tls-bcp]
Sheffer, Y., Holz, R., and P. Saint-Andre, Sheffer, Y., Holz, R., and P. Saint-Andre,
"Recommendations for Secure Use of TLS and DTLS", "Recommendations for Secure Use of TLS and DTLS",
draft-ietf-uta-tls-bcp-05 (work in progress), draft-ietf-uta-tls-bcp-06 (work in progress),
October 2014. October 2014.
[JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign",
September 2010. September 2010.
[JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
draft-ietf-jose-json-web-encryption (work in progress), draft-ietf-jose-json-web-encryption (work in progress),
October 2014. October 2014.
[JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
skipping to change at page 45, line 13 skipping to change at page 47, line 13
Concatenating these parts in the order Header.Payload.Signature with Concatenating these parts in the order Header.Payload.Signature with
period ('.') characters between the parts yields this complete JWS period ('.') characters between the parts yields this complete JWS
(with line breaks for display purposes only): (with line breaks for display purposes only):
eyJhbGciOiJub25lIn0 eyJhbGciOiJub25lIn0
. .
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
. .
A.6. Example JWS Using JWS JSON Serialization A.6. Example JWS using General JWS JSON Serialization
This section contains an example using the JWS JSON Serialization. This section contains an example using the general JWS JSON
This example demonstrates the capability for conveying multiple Serialization syntax. This example demonstrates the capability for
digital signatures and/or MACs for the same payload. conveying multiple digital signatures and/or MACs for the same
payload.
The JWS Payload used in this example is the same as that used in the The JWS Payload used in this example is the same as that used in the
examples in Appendix A.2 and Appendix A.3 (with line breaks for examples in Appendix A.2 and Appendix A.3 (with line breaks for
display purposes only): display purposes only):
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
Two digital signatures are used in this example: the first using Two digital signatures are used in this example: the first using
RSASSA-PKCS-v1_5 SHA-256 and the second using ECDSA P-256 SHA-256. RSASSA-PKCS-v1_5 SHA-256 and the second using ECDSA P-256 SHA-256.
skipping to change at page 46, line 34 skipping to change at page 48, line 35
{"alg":"RS256", {"alg":"RS256",
"kid":"2010-12-29"} "kid":"2010-12-29"}
and and
{"alg":"ES256", {"alg":"ES256",
"kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"} "kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"}
A.6.4. Complete JWS JSON Serialization Representation A.6.4. Complete JWS JSON Serialization Representation
The complete JSON Web Signature JSON Serialization for these values The complete JWS JSON Serialization for these values is as follows
is as follows (with line breaks within values for display purposes (with line breaks within values for display purposes only):
only):
{"payload": {
"payload":
"eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGF "eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGF
tcGxlLmNvbS9pc19yb290Ijp0cnVlfQ", tcGxlLmNvbS9pc19yb290Ijp0cnVlfQ",
"signatures":[ "signatures":[
{"protected":"eyJhbGciOiJSUzI1NiJ9", {"protected":"eyJhbGciOiJSUzI1NiJ9",
"header": "header":
{"kid":"2010-12-29"}, {"kid":"2010-12-29"},
"signature": "signature":
"cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZ "cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZ
mh7AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjb mh7AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjb
KBYNX4BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHl KBYNX4BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHl
skipping to change at page 47, line 27 skipping to change at page 49, line 28
c6BfI7noOPqvhJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AX c6BfI7noOPqvhJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AX
LIhWkWywlVmtVrBp0igcN_IoypGlUPQGe77Rw"}, LIhWkWywlVmtVrBp0igcN_IoypGlUPQGe77Rw"},
{"protected":"eyJhbGciOiJFUzI1NiJ9", {"protected":"eyJhbGciOiJFUzI1NiJ9",
"header": "header":
{"kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"}, {"kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"},
"signature": "signature":
"DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8IS "DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8IS
lSApmWQxfKTUJqPP3-Kg6NU1Q"}] lSApmWQxfKTUJqPP3-Kg6NU1Q"}]
} }
A.7. Example JWS using Flattened JWS JSON Serialization
This section contains an example using the flattened JWS JSON
Serialization syntax. This example demonstrates the capability for
conveying a single digital signature or MAC in a flattened JSON
structure.
The values in this example are the same as those in the second
signature of the previous example in Appendix A.6.
The complete JWS JSON Serialization for these values is as follows
(with line breaks within values for display purposes only):
{
"payload":
"eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGF
tcGxlLmNvbS9pc19yb290Ijp0cnVlfQ",
"protected":"eyJhbGciOiJFUzI1NiJ9",
"header":
{"kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"},
"signature":
"DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8IS
lSApmWQxfKTUJqPP3-Kg6NU1Q"
}
Appendix B. "x5c" (X.509 Certificate Chain) Example Appendix B. "x5c" (X.509 Certificate Chain) Example
The JSON array below is an example of a certificate chain that could The JSON array below is an example of a certificate chain that could
be used as the value of an "x5c" (X.509 Certificate Chain) Header be used as the value of an "x5c" (X.509 Certificate Chain) Header
Parameter, per Section 4.1.6. Note that since these strings contain Parameter, per Section 4.1.6. Note that since these strings contain
base64 encoded (not base64url encoded) values, they are allowed to base64 encoded (not base64url encoded) values, they are allowed to
contain white space and line breaks. contain white space and line breaks.
["MIIE3jCCA8agAwIBAgICAwEwDQYJKoZIhvcNAQEFBQAwYzELMAkGA1UEBhMCVVM ["MIIE3jCCA8agAwIBAgICAwEwDQYJKoZIhvcNAQEFBQAwYzELMAkGA1UEBhMCVVM
xITAfBgNVBAoTGFRoZSBHbyBEYWRkeSBHcm91cCwgSW5jLjExMC8GA1UECxMoR2 xITAfBgNVBAoTGFRoZSBHbyBEYWRkeSBHcm91cCwgSW5jLjExMC8GA1UECxMoR2
skipping to change at page 53, line 29 skipping to change at page 56, line 14
Tschofenig, and Sean Turner. Tschofenig, and Sean Turner.
Jim Schaad and Karen O'Donoghue chaired the JOSE working group and Jim Schaad and Karen O'Donoghue chaired the JOSE working group and
Sean Turner, Stephen Farrell, and Kathleen Moriarty served as Sean Turner, Stephen Farrell, and Kathleen Moriarty served as
Security area directors during the creation of this specification. Security area directors during the creation of this specification.
Appendix H. Document History Appendix H. Document History
[[ to be removed by the RFC Editor before publication as an RFC ]] [[ to be removed by the RFC Editor before publication as an RFC ]]
-36
o Defined a flattened JWS JSON Serialization syntax, which is
optimized for the single digital signature or MAC case.
o Clarified where white space and line breaks may occur in JSON
objects by referencing Section 2 of RFC 7159.
o Specified that registration reviews occur on the
jose-reg-review@ietf.org mailing list.
-35 -35
o Addressed AppsDir reviews by Ray Polk. o Addressed AppsDir reviews by Ray Polk.
o Used real values for examples in the IANA Registration Template. o Used real values for examples in the IANA Registration Template.
-34 -34
o Addressed IESG review comments by Alissa Cooper, Pete Resnick, o Addressed IESG review comments by Alissa Cooper, Pete Resnick,
Richard Barnes, Ted Lemon, and Stephen Farrell. Richard Barnes, Ted Lemon, and Stephen Farrell.
 End of changes. 27 change blocks. 
119 lines changed or deleted 193 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/