draft-ietf-jose-json-web-signature-14.txt   draft-ietf-jose-json-web-signature-15.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: January 30, 2014 Ping Identity Expires: March 7, 2014 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
July 29, 2013 September 3, 2013
JSON Web Signature (JWS) JSON Web Signature (JWS)
draft-ietf-jose-json-web-signature-14 draft-ietf-jose-json-web-signature-15
Abstract Abstract
JSON Web Signature (JWS) is a means of representing content secured JSON Web Signature (JWS) represents content secured with digital
with digital signatures or Message Authentication Codes (MACs) using signatures or Message Authentication Codes (MACs) using JavaScript
JavaScript Object Notation (JSON) based data structures. Object Notation (JSON) based data structures. Cryptographic
Cryptographic algorithms and identifiers for use with this algorithms and identifiers for use with this specification are
specification are described in the separate JSON Web Algorithms (JWA) described in the separate JSON Web Algorithms (JWA) specification and
specification. Related encryption capabilities are described in the an IANA registry defined by that specification. Related encryption
separate JSON Web Encryption (JWE) specification. capabilities are described in the separate JSON Web Encryption (JWE)
specification.
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
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 January 30, 2014. This Internet-Draft will expire on March 7, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2013 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 24 skipping to change at page 2, line 25
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. JSON Web Signature (JWS) Overview . . . . . . . . . . . . . . 6 3. JSON Web Signature (JWS) Overview . . . . . . . . . . . . . . 6
3.1. Example JWS . . . . . . . . . . . . . . . . . . . . . . . 6 3.1. Example JWS . . . . . . . . . . . . . . . . . . . . . . . 6
4. JWS Header . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4. JWS Header . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.1. Reserved Header Parameter Names . . . . . . . . . . . . . 8 4.1. Reserved Header Parameter Names . . . . . . . . . . . . . 8
4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 8 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 8
4.1.2. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 9 4.1.2. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 9
4.1.3. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 9 4.1.3. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 9
4.1.4. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 9 4.1.4. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 9
4.1.5. "x5t" (X.509 Certificate Thumbprint) Header 4.1.5. "x5t" (X.509 Certificate Thumbprint) Header
Parameter . . . . . . . . . . . . . . . . . . . . . . 10 Parameter . . . . . . . . . . . . . . . . . . . . . . 9
4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter . . . 10 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter . . . 10
4.1.7. "kid" (Key ID) Header Parameter . . . . . . . . . . . 10 4.1.7. "kid" (Key ID) Header Parameter . . . . . . . . . . . 10
4.1.8. "typ" (Type) Header Parameter . . . . . . . . . . . . 11 4.1.8. "typ" (Type) Header Parameter . . . . . . . . . . . . 10
4.1.9. "cty" (Content Type) Header Parameter . . . . . . . . 11 4.1.9. "cty" (Content Type) Header Parameter . . . . . . . . 11
4.1.10. "crit" (Critical) Header Parameter . . . . . . . . . . 11 4.1.10. "crit" (Critical) Header Parameter . . . . . . . . . . 11
4.2. Public Header Parameter Names . . . . . . . . . . . . . . 12 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 12
4.3. Private Header Parameter Names . . . . . . . . . . . . . . 12 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 12
5. Producing and Consuming JWSs . . . . . . . . . . . . . . . . . 12 5. Producing and Consuming JWSs . . . . . . . . . . . . . . . . . 12
5.1. Message Signing or MACing . . . . . . . . . . . . . . . . 12 5.1. Message Signing or MACing . . . . . . . . . . . . . . . . 12
5.2. Message Signature or MAC Validation . . . . . . . . . . . 13 5.2. Message Signature or MAC Validation . . . . . . . . . . . 13
5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 15 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 15
6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 15 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 15
7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 16 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 16
7.1. JWS Compact Serialization . . . . . . . . . . . . . . . . 16 7.1. JWS Compact Serialization . . . . . . . . . . . . . . . . 16
7.2. JWS JSON Serialization . . . . . . . . . . . . . . . . . . 16 7.2. JWS JSON Serialization . . . . . . . . . . . . . . . . . . 16
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18
8.1. JSON Web Signature and Encryption Header Parameters 8.1. JSON Web Signature and Encryption Header Parameters
Registry . . . . . . . . . . . . . . . . . . . . . . . . . 18 Registry . . . . . . . . . . . . . . . . . . . . . . . . . 19
8.1.1. Registration Template . . . . . . . . . . . . . . . . 19 8.1.1. Registration Template . . . . . . . . . . . . . . . . 19
8.1.2. Initial Registry Contents . . . . . . . . . . . . . . 19 8.1.2. Initial Registry Contents . . . . . . . . . . . . . . 19
8.2. JSON Web Signature and Encryption Type Values Registry . . 20 8.2. JSON Web Signature and Encryption Type Values Registry . . 20
8.2.1. Registration Template . . . . . . . . . . . . . . . . 20 8.2.1. Registration Template . . . . . . . . . . . . . . . . 21
8.2.2. Initial Registry Contents . . . . . . . . . . . . . . 21 8.2.2. Initial Registry Contents . . . . . . . . . . . . . . 21
8.3. Media Type Registration . . . . . . . . . . . . . . . . . 21 8.3. Media Type Registration . . . . . . . . . . . . . . . . . 22
8.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 21 8.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 22
9. Security Considerations . . . . . . . . . . . . . . . . . . . 22
9. Security Considerations . . . . . . . . . . . . . . . . . . . 23
9.1. Cryptographic Security Considerations . . . . . . . . . . 23 9.1. Cryptographic Security Considerations . . . . . . . . . . 23
9.2. JSON Security Considerations . . . . . . . . . . . . . . . 24 9.2. JSON Security Considerations . . . . . . . . . . . . . . . 24
9.3. Unicode Comparison Security Considerations . . . . . . . . 24 9.3. Unicode Comparison Security Considerations . . . . . . . . 24
9.4. TLS Requirements . . . . . . . . . . . . . . . . . . . . . 25 9.4. TLS Requirements . . . . . . . . . . . . . . . . . . . . . 25
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25
10.1. Normative References . . . . . . . . . . . . . . . . . . . 25 10.1. Normative References . . . . . . . . . . . . . . . . . . . 25
10.2. Informative References . . . . . . . . . . . . . . . . . . 27 10.2. Informative References . . . . . . . . . . . . . . . . . . 27
Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 27 Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 28
A.1. Example JWS using HMAC SHA-256 . . . . . . . . . . . . . . 28 A.1. Example JWS using HMAC SHA-256 . . . . . . . . . . . . . . 28
A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 28 A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 28
A.1.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 30 A.1.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 30
A.1.3. Validating . . . . . . . . . . . . . . . . . . . . . . 30 A.1.3. Validating . . . . . . . . . . . . . . . . . . . . . . 30
A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 . . . . . . . . 30 A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 . . . . . . . . 30
A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 30 A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 30
A.2.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 33 A.2.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 33
A.2.3. Validating . . . . . . . . . . . . . . . . . . . . . . 33 A.2.3. 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. Decoding . . . . . . . . . . . . . . . . . . . . . . . 35 A.3.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 36
A.3.3. Validating . . . . . . . . . . . . . . . . . . . . . . 36 A.3.3. 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. Decoding . . . . . . . . . . . . . . . . . . . . . . . 38 A.4.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 38
A.4.3. Validating . . . . . . . . . . . . . . . . . . . . . . 38 A.4.3. Validating . . . . . . . . . . . . . . . . . . . . . . 39
A.5. Example Plaintext JWS . . . . . . . . . . . . . . . . . . 39 A.5. Example Plaintext JWS . . . . . . . . . . . . . . . . . . 39
A.6. Example JWS Using JWS JSON Serialization . . . . . . . . . 40 A.6. Example JWS Using JWS JSON Serialization . . . . . . . . . 40
A.6.1. JWS Per-Signature Protected Headers . . . . . . . . . 40 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 . . . . . . . . 41
A.6.3. Complete JWS Header Values . . . . . . . . . . . . . . 41 A.6.3. Complete JWS Header Values . . . . . . . . . . . . . . 41
A.6.4. Complete JWS JSON Serialization Representation . . . . 41 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 . . . . . . . 42
Appendix C. Notes on implementing base64url encoding without Appendix C. Notes on implementing base64url encoding without
padding . . . . . . . . . . . . . . . . . . . . . . . 43 padding . . . . . . . . . . . . . . . . . . . . . . . 44
Appendix D. Negative Test Case for "crit" Header Parameter . . . 44 Appendix D. Negative Test Case for "crit" Header Parameter . . . 45
Appendix E. Acknowledgements . . . . . . . . . . . . . . . . . . 45 Appendix E. Acknowledgements . . . . . . . . . . . . . . . . . . 45
Appendix F. Document History . . . . . . . . . . . . . . . . . . 45 Appendix F. Document History . . . . . . . . . . . . . . . . . . 46
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 51 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 52
1. Introduction 1. Introduction
JSON Web Signature (JWS) is a means of representing content secured JSON Web Signature (JWS) represents content secured with digital
with digital signatures or Message Authentication Codes (MACs) using signatures or Message Authentication Codes (MACs) using JavaScript
JavaScript Object Notation (JSON) [RFC4627] based data structures. Object Notation (JSON) [RFC4627] based data structures. The JWS
The JWS cryptographic mechanisms provide integrity protection for cryptographic mechanisms provide integrity protection for an
arbitrary sequences of octets. arbitrary sequence of octets.
Two closely related representations 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
specification are described in the separate JSON Web Algorithms (JWA) specification are described in the separate JSON Web Algorithms (JWA)
[JWA] specification. Related encryption capabilities are described [JWA] specification and an IANA registry defined by that
in the separate JSON Web Encryption (JWE) [JWE] specification. specification. Related encryption capabilities are described in the
separate JSON Web Encryption (JWE) [JWE] specification.
Names defined by this specification are short because a core goal is
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", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in Key words for use in document are to be interpreted as described in Key words for use in
RFCs to Indicate Requirement Levels [RFC2119]. RFCs to Indicate Requirement Levels [RFC2119].
2. Terminology 2. Terminology
skipping to change at page 5, line 22 skipping to change at page 5, line 25
the JWS Header that is integrity protected. For the JWS Compact the JWS Header that is integrity protected. 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. Header Parameter A name/value pair that is member of the JWS Header.
Header Parameter Name The name of a member of the JWS Header. Header Parameter Name The name of a member of the JWS Header.
Header Parameter Value The value of a member of the JWS Header. Header Parameter Value The value of a member of the JWS Header.
Base64url Encoding The URL- and filename-safe Base64 encoding Base64url Encoding Base64 encoding using the URL- and filename-safe
described in RFC 4648 [RFC4648], Section 5, with the (non URL- character set defined in Section 5 of RFC 4648 [RFC4648], with all
safe) '=' padding 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.)
Encoded JWS Header Base64url encoding of the JWS Protected Header. Encoded JWS Header Base64url encoding of the JWS Protected Header.
Encoded JWS Payload Base64url encoding of the JWS Payload. Encoded JWS Payload Base64url encoding of the JWS Payload.
Encoded JWS Signature Base64url encoding of the JWS Signature. Encoded JWS Signature Base64url encoding of the JWS Signature.
JWS Signing Input The concatenation of the Encoded JWS Header, a JWS Signing Input The concatenation of the Encoded JWS Header, a
skipping to change at page 6, line 7 skipping to change at page 6, line 7
JWS JSON Serialization A representation of the JWS as a JSON JWS JSON Serialization A representation of the JWS as a JSON
structure containing JWS Header, Encoded JWS Payload, and Encoded structure containing JWS Header, Encoded JWS Payload, and Encoded
JWS Signature values. Unlike the JWS Compact Serialization, the JWS Signature values. Unlike the JWS Compact Serialization, the
JWS JSON Serialization enables multiple digital signatures and/or JWS JSON Serialization enables multiple digital signatures and/or
MACs to be applied to the same content. This representation is MACs to be applied to the same content. This representation is
neither compact nor URL-safe. neither compact nor URL-safe.
Collision Resistant Namespace A namespace that allows names to be Collision Resistant Namespace A namespace that allows names to be
allocated in a manner such that they are highly unlikely to allocated in a manner such that they are highly unlikely to
collide with other names. For instance, collision resistance can collide with other names. Examples of Collision Resistant
be achieved through administrative delegation of portions of the Namespaces include: Domain Names, Object Identifiers (OIDs) as
namespace or through use of collision-resistant name allocation defined in the ITU-T X.660 and X.670 Recommendation series, and
functions. Examples of Collision Resistant Namespaces include: Universally Unique IDentifiers (UUIDs) [RFC4122]. When using an
Domain Names, Object Identifiers (OIDs) as defined in the ITU-T administratively delegated namespace, the definer of a name needs
X.660 and X.670 Recommendation series, and Universally Unique to take reasonable precautions to ensure they are in control of
IDentifiers (UUIDs) [RFC4122]. When using an administratively the portion of the namespace they use to define the name.
delegated namespace, the definer of a name needs to take
reasonable 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 A JSON string value, with the additional requirement
that while arbitrary string values MAY be used, any value that while arbitrary string values MAY be used, any value
containing a ":" character MUST be a URI [RFC3986]. StringOrURI containing a ":" character MUST be a URI [RFC3986]. StringOrURI
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
skipping to change at page 8, line 32 skipping to change at page 8, line 32
Section 4.1.10, all header parameters not defined by this Section 4.1.10, all header parameters not defined by this
specification MUST be ignored when not understood. specification MUST be ignored when not understood.
There are three classes of Header Parameter Names: Reserved Header There are three classes of Header Parameter Names: Reserved Header
Parameter Names, Public Header Parameter Names, and Private Header Parameter Names, Public Header Parameter Names, and Private Header
Parameter Names. Parameter Names.
4.1. Reserved Header Parameter Names 4.1. Reserved Header Parameter Names
The following Header Parameter Names are reserved with meanings as The following Header Parameter Names are reserved with meanings as
defined below. All the names are short because a core goal of this defined below.
specification is for the resulting representations using the JWS
Compact Serialization to be compact.
Additional reserved Header Parameter Names can be defined via the Additional reserved Header Parameter Names can be defined via the
IANA JSON Web Signature and Encryption Header Parameters registry IANA JSON Web Signature and Encryption Header Parameters registry
Section 8.1. As indicated by the common registry, JWSs and JWEs Section 8.1. As indicated by the common registry, JWSs and JWEs
share a common header parameter space; when a parameter is used by share a common header parameter space; when a parameter is used by
both specifications, its usage must be compatible between the both specifications, its usage must be compatible between the
specifications. specifications.
4.1.1. "alg" (Algorithm) Header Parameter 4.1.1. "alg" (Algorithm) Header Parameter
The "alg" (algorithm) header parameter identifies a cryptographic The "alg" (algorithm) header parameter identifies the cryptographic
algorithm used to secure the JWS. The recipient MUST reject the JWS algorithm used to secure the JWS. The signature, MAC, or plaintext
if the "alg" value does not represent a supported algorithm, or if value is not valid if the "alg" value does not represent a supported
there is not a key for use with that algorithm associated with the algorithm, or if there is not a key for use with that algorithm
party that digitally signed or MACed the content. "alg" values SHOULD associated with the party that digitally signed or MACed the content.
either be registered in the IANA JSON Web Signature and Encryption "alg" values SHOULD either be registered in the IANA JSON Web
Algorithms registry [JWA] or be a value that contains a Collision Signature and Encryption Algorithms registry [JWA] or be a value that
Resistant Namespace. The "alg" value is a case sensitive string contains a Collision Resistant Namespace. The "alg" value is a case
containing a StringOrURI value. Use of this header parameter is sensitive string containing a StringOrURI value. Use of this header
REQUIRED. This header parameter MUST be understood by parameter is REQUIRED. This header parameter MUST be understood by
implementations. implementations.
A list of defined "alg" values can be found in the IANA JSON Web A list of defined "alg" values can be found in the IANA JSON Web
Signature and Encryption Algorithms registry [JWA]; the initial Signature and Encryption Algorithms registry [JWA]; the initial
contents of this registry are the values defined in Section 3.1 of contents of this registry are the values defined in Section 3.1 of
the JSON Web Algorithms (JWA) [JWA] specification. the JSON Web Algorithms (JWA) [JWA] specification.
4.1.2. "jku" (JWK Set URL) Header Parameter 4.1.2. "jku" (JWK Set URL) Header Parameter
The "jku" (JWK Set URL) header parameter is a URI [RFC3986] that The "jku" (JWK Set URL) header parameter is a URI [RFC3986] that
skipping to change at page 10, line 34 skipping to change at page 10, line 28
X.509 public key certificate or certificate chain [RFC5280] X.509 public key certificate or certificate chain [RFC5280]
corresponding to the key used to digitally sign the JWS. The corresponding to the key used to digitally sign the JWS. The
certificate or certificate chain is represented as a JSON array of certificate or certificate chain is represented as a JSON array of
certificate value strings. Each string in the array is a base64 certificate value strings. Each string in the array is a base64
encoded ([RFC4648] Section 4 -- not base64url encoded) DER encoded ([RFC4648] Section 4 -- not base64url encoded) DER
[ITU.X690.1994] PKIX certificate value. The certificate containing [ITU.X690.1994] PKIX certificate value. The certificate containing
the public key corresponding to the key used to digitally sign the the public key corresponding to the key used to digitally sign the
JWS MUST be the first certificate. This MAY be followed by JWS MUST be the first certificate. This MAY be followed by
additional certificates, with each subsequent certificate being the additional certificates, with each subsequent certificate being the
one used to certify the previous one. The recipient MUST verify the one used to certify the previous one. The recipient MUST verify the
certificate chain according to [RFC5280] and reject the JWS if any certificate chain according to [RFC5280] and reject the signature if
validation failure occurs. Use of this header parameter is OPTIONAL. any validation failure occurs. Use of this header parameter is
OPTIONAL.
See Appendix B for an example "x5c" value. See Appendix B for an example "x5c" value.
4.1.7. "kid" (Key ID) Header Parameter 4.1.7. "kid" (Key ID) Header Parameter
The "kid" (key ID) header parameter is a hint indicating which key The "kid" (key ID) header parameter is a hint indicating which key
was used to secure the JWS. This parameter allows originators to was used to secure the JWS. This parameter allows originators to
explicitly signal a change of key to recipients. Should the explicitly signal a change of key to recipients. Should the
recipient be unable to locate a key corresponding to the "kid" value, recipient be unable to locate a key corresponding to the "kid" value,
they SHOULD treat that condition as an error. The interpretation of they SHOULD treat that condition as an error. The interpretation of
skipping to change at page 13, line 46 skipping to change at page 13, line 41
JWS Header, the Encoded JWS Payload, and the Encoded JWS JWS Header, the Encoded JWS Payload, and the Encoded JWS
Signature in that order, with the three strings being separated Signature in that order, with the three strings being separated
by two period ('.') characters. The JWS JSON Serialization is by two period ('.') characters. The JWS JSON Serialization is
described in Section 7.2. described in 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
dependencies between the inputs and outputs of the steps. If any of dependencies between the inputs and outputs of the steps. If any of
the listed steps fails, then the JWS MUST be rejected. the listed steps fails, then the signature or MAC cannot be
validated.
It is an application decision which signatures, MACs, or plaintext
values must successfully validate for the JWS to be accepted. In
some cases, all must successfully validate or the JWS will be
rejected. In other cases, only a specific signature, MAC, or
plaintext value needs to be successfully validated. However, in all
cases, at least one signature, MAC, or plaintext value MUST
successfully validate or the JWS MUST be rejected.
1. Parse the serialized input to determine the values of the JWS 1. Parse the serialized input to determine the values of the JWS
Header, the Encoded JWS Payload, and the Encoded JWS Signature. Header, the Encoded JWS Payload, and the Encoded JWS Signature.
When using the JWS Compact Serialization, the Encoded JWS When using the JWS Compact Serialization, the Encoded JWS
Header, the Encoded JWS Payload, and the Encoded JWS Signature Header, the Encoded JWS Payload, and the Encoded JWS Signature
are represented as text strings in that order, separated by two are represented as text strings in that order, separated by two
period ('.') characters. The JWS JSON Serialization is period ('.') characters. The JWS JSON Serialization is
described in Section 7.2. described in Section 7.2.
2. The Encoded JWS Header MUST be successfully base64url decoded 2. The Encoded JWS Header MUST be successfully base64url decoded
skipping to change at page 15, line 43 skipping to change at page 15, line 48
Unicode security considerations in Section 9.3. Unicode security considerations in Section 9.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
outside the scope of this specification. Specifically, the Header outside the scope of this specification. Specifically, the Header
Parameters "jku", "jwk", "x5u", "x5t", "x5c", and "kid" can be used Parameters "jku", "jwk", "x5u", "x5t", "x5c", and "kid" can be used
to identify the key used. The sender SHOULD include sufficient to identify the key used. These header parameters MUST be integrity
information in the Header Parameters to identify the key used, unless protected if the information about the key that they convey is to be
the application uses another means or convention to determine the key considered trusted.
used. Recipients MUST reject the input when the algorithm used
requires a key (which is true of all algorithms except for "none") The sender SHOULD include sufficient information in the Header
and the key used cannot be determined. Parameters to identify the key used, unless the application uses
another means or convention to determine the key used. Validation of
the signature or MAC fails when the algorithm used requires a key
(which is true of all algorithms except for "none") and the key used
cannot be determined.
The means of exchanging any shared symmetric keys used is outside the
scope of this specification.
7. Serializations 7. Serializations
JWS objects use one of two serializations, the JWS Compact JWS objects use one of two serializations, the JWS Compact
Serialization or the JWS JSON Serialization. The JWS Compact Serialization or the JWS JSON Serialization. The JWS Compact
Serialization is mandatory to implement. Implementation of the JWS Serialization is mandatory to implement. Implementation of the JWS
JSON Serialization is OPTIONAL. JSON Serialization is OPTIONAL.
7.1. JWS Compact Serialization 7.1. JWS Compact Serialization
skipping to change at page 25, line 42 skipping to change at page 26, line 7
[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),
July 2013. September 2013.
[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),
July 2013. September 2013.
[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.
[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
skipping to change at page 27, line 25 skipping to change at page 27, line 37
10.2. Informative References 10.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), July 2013. (work in progress), September 2013.
[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), July 2013. progress), July 2013.
[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
skipping to change at page 38, line 27 skipping to change at page 38, line 38
wqT2SI-KGDKB34XO0aw_7XdtAG8GaSwFKdCAPZgoXD2YBJZCPEX3xKpRwcdOO8Kp wqT2SI-KGDKB34XO0aw_7XdtAG8GaSwFKdCAPZgoXD2YBJZCPEX3xKpRwcdOO8Kp
EHwJjyqOgzDO7iKvU8vcnwNrmxYbSW9ERBXukOXolLzeO_Jn EHwJjyqOgzDO7iKvU8vcnwNrmxYbSW9ERBXukOXolLzeO_Jn
Concatenating these values in the order Header.Payload.Signature with Concatenating these values 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
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):
eyJhbGciOiJFUzUxMiJ9 eyJhbGciOiJFUzUxMiJ9
. .
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt UGF5bG9hZA
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
. .
AdwMgeerwtHoh-l192l60hp9wAHZFVJbLfD_UxMi70cwnZOYaRI1bKPWROc-mZZq AdwMgeerwtHoh-l192l60hp9wAHZFVJbLfD_UxMi70cwnZOYaRI1bKPWROc-mZZq
wqT2SI-KGDKB34XO0aw_7XdtAG8GaSwFKdCAPZgoXD2YBJZCPEX3xKpRwcdOO8Kp wqT2SI-KGDKB34XO0aw_7XdtAG8GaSwFKdCAPZgoXD2YBJZCPEX3xKpRwcdOO8Kp
EHwJjyqOgzDO7iKvU8vcnwNrmxYbSW9ERBXukOXolLzeO_Jn EHwJjyqOgzDO7iKvU8vcnwNrmxYbSW9ERBXukOXolLzeO_Jn
A.4.2. Decoding A.4.2. Decoding
Decoding the JWS requires base64url decoding the Encoded JWS Header, Decoding the JWS requires base64url decoding the Encoded JWS Header,
Encoded JWS Payload, and Encoded JWS Signature to produce the JWS Encoded JWS Payload, and Encoded JWS Signature to produce the JWS
Header, JWS Payload, and JWS Signature octet sequences. The octet Header, JWS Payload, and JWS Signature octet sequences. The octet
skipping to change at page 46, line 4 skipping to change at page 46, line 20
Panzer, Emmanuel Raviart, Eric Rescorla, Jim Schaad, Paul Tarjan, Panzer, Emmanuel Raviart, Eric Rescorla, Jim Schaad, Paul Tarjan,
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 F. Document History Appendix F. 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 ]]
-15
o Clarified that it is an application decision which signatures,
MACs, or plaintext values must successfully validate for the JWS
to be accepted, addressing issue #35.
o Corrected editorial error in "ES512" example.
o Changes to address editorial and minor issues #34, #96, #100,
#101, #104, #105, and #106.
-14 -14
o Stated that the "signature" parameter is to be omitted in the JWS o Stated that the "signature" parameter is to be omitted in the JWS
JSON Serialization when its value would be empty (which is only JSON Serialization when its value would be empty (which is only
the case for a Plaintext JWS). the case for a Plaintext JWS).
-13 -13
o Made all header parameter values be per-signature/MAC, addressing o Made all header parameter values be per-signature/MAC, addressing
issue #24. issue #24.
 End of changes. 32 change blocks. 
77 lines changed or deleted 106 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/