draft-ietf-jose-json-web-signature-15.txt   draft-ietf-jose-json-web-signature-16.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: March 7, 2014 Ping Identity Expires: March 19, 2014 Ping Identity
N. Sakimura N. Sakimura
NRI NRI
September 3, 2013 September 15, 2013
JSON Web Signature (JWS) JSON Web Signature (JWS)
draft-ietf-jose-json-web-signature-15 draft-ietf-jose-json-web-signature-16
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 March 7, 2014. This Internet-Draft will expire on March 19, 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 19 skipping to change at page 2, line 19
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 . . . . . . . . . . . . . . . . . . . . . . . . . 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. Registered 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 SHA-1 Thumbprint) Header
Parameter . . . . . . . . . . . . . . . . . . . . . . 9 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 . . . . . . . . . . . . 10 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 . . . . . . . . . . . . . . . . . . . . . . . . . 19 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 . . . . . . . . . . . . . . 20
8.2. JSON Web Signature and Encryption Type Values Registry . . 20 8.2. JSON Web Signature and Encryption Type Values Registry . . 21
8.2.1. Registration Template . . . . . . . . . . . . . . . . 21 8.2.1. Registration Template . . . . . . . . . . . . . . . . 21
8.2.2. Initial Registry Contents . . . . . . . . . . . . . . 21 8.2.2. Initial Registry Contents . . . . . . . . . . . . . . 22
8.3. Media Type Registration . . . . . . . . . . . . . . . . . 22 8.3. Media Type Registration . . . . . . . . . . . . . . . . . 22
8.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 22 8.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 22
9. Security Considerations . . . . . . . . . . . . . . . . . . . 23 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 . . . . . . . . . . . . . . . 25
9.3. Unicode Comparison Security Considerations . . . . . . . . 24 9.3. Unicode Comparison Security Considerations . . . . . . . . 25
9.4. TLS Requirements . . . . . . . . . . . . . . . . . . . . . 25 9.4. TLS Requirements . . . . . . . . . . . . . . . . . . . . . 26
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26
10.1. Normative References . . . . . . . . . . . . . . . . . . . 25 10.1. Normative References . . . . . . . . . . . . . . . . . . . 26
10.2. Informative References . . . . . . . . . . . . . . . . . . 27 10.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. Decoding . . . . . . . . . . . . . . . . . . . . . . . 30 A.1.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 31
A.1.3. Validating . . . . . . . . . . . . . . . . . . . . . . 30 A.1.3. 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 . . . . . . . . . . . . . . . . . . . . . . . 30 A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 31
A.2.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 33 A.2.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 34
A.2.3. Validating . . . . . . . . . . . . . . . . . . . . . . 33 A.2.3. Validating . . . . . . . . . . . . . . . . . . . . . . 34
A.3. Example JWS using ECDSA P-256 SHA-256 . . . . . . . . . . 34 A.3. Example JWS using ECDSA P-256 SHA-256 . . . . . . . . . . 34
A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 34 A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 34
A.3.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 36 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 . . . . . . . . . . 37
A.4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 36 A.4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 37
A.4.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 38 A.4.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 39
A.4.3. Validating . . . . . . . . . . . . . . . . . . . . . . 39 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 . . . . . . . . 41 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 . . . . . . . 42 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 . . . . . . . . . . . . . . . . . . . . . . . 44 padding . . . . . . . . . . . . . . . . . . . . . . . 44
skipping to change at page 4, line 35 skipping to change at page 4, line 35
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", "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]. If these words are
used without being spelled in uppercase then they are to be
interpreted with their normal natural language meanings.
2. Terminology 2. Terminology
JSON Web Signature (JWS) A data structure representing a digitally JSON Web Signature (JWS) A data structure representing a digitally
signed or MACed message. The structure represents three values: signed or MACed message. The structure represents three values:
the JWS Header, the JWS Payload, and the JWS Signature. the JWS Header, the JWS Payload, and the JWS Signature.
JSON Text Object A UTF-8 [RFC3629] encoded text string representing JSON Text Object A UTF-8 [RFC3629] encoded text string representing
a JSON object; the syntax of JSON objects is defined in Section a JSON object; the syntax of JSON objects is defined in Section
2.2 of [RFC4627]. 2.2 of [RFC4627].
skipping to change at page 6, line 5 skipping to change at page 6, line 12
strings being separated by two period ('.') characters. This strings being separated by two period ('.') characters. This
representation is compact and URL-safe. representation is compact and URL-safe.
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 Name A name in a namespace that enables names to
allocated in a manner such that they are highly unlikely to be allocated in a manner such that they are highly unlikely to
collide with other names. Examples of Collision Resistant collide with other names. Examples of collision resistant
Namespaces include: Domain Names, Object Identifiers (OIDs) as namespaces include: Domain Names, Object Identifiers (OIDs) as
defined in the ITU-T X.660 and X.670 Recommendation series, and defined in the ITU-T X.660 and X.670 Recommendation series, and
Universally Unique IDentifiers (UUIDs) [RFC4122]. When using an Universally Unique IDentifiers (UUIDs) [RFC4122]. When using an
administratively delegated namespace, the definer of a name needs administratively delegated namespace, the definer of a name needs
to take reasonable precautions to ensure they are in control of to take reasonable precautions to ensure they are in control of
the portion of the namespace they use to define the name. the portion of the namespace they use to define the name.
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
skipping to change at page 6, line 39 skipping to change at page 6, line 46
period ('.') characters. A JSON Serialization for this information period ('.') characters. A JSON Serialization for this information
is also defined in Section 7.2. is also defined in Section 7.2.
The JWS Header describes the signature or MAC method and parameters The JWS Header describes the signature or MAC method and parameters
employed. The JWS Payload is the message content to be secured. The employed. The JWS Payload is the message content to be secured. The
JWS Signature ensures the integrity of both the JWS Protected Header JWS Signature ensures the integrity of both the JWS Protected Header
and the JWS Payload. and the JWS Payload.
3.1. Example JWS 3.1. Example JWS
This section provides an example of a JWS. Its computation is
described in more detail in Appendix A.1, including specifying the
exact octet sequences representing the JSON values used and the key
value used.
The following example JWS Header declares that the encoded object is The following example JWS Header declares that the encoded object is
a JSON Web Token (JWT) [JWT] and the JWS Header and the JWS Payload a JSON Web Token (JWT) [JWT] and the JWS Header and the JWS Payload
are secured using the HMAC SHA-256 algorithm: are secured using the HMAC SHA-256 algorithm:
{"typ":"JWT", {"typ":"JWT",
"alg":"HS256"} "alg":"HS256"}
Base64url encoding the octets of the UTF-8 representation of the JWS Base64url encoding the octets of the UTF-8 representation of the JWS
Header yields this Encoded JWS Header value: Header yields this Encoded JWS Header value:
eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
The following is an example of a JSON object that can be used as a The UTF-8 representation of following JSON object is used as the JWS
JWS Payload. (Note that the payload can be any content, and need not Payload. (Note that the payload can be any content, and need not be
be a representation of a JSON object.) a representation of a JSON object.)
{"iss":"joe", {"iss":"joe",
"exp":1300819380, "exp":1300819380,
"http://example.com/is_root":true} "http://example.com/is_root":true}
The following octet sequence, which is the UTF-8 representation of
the JSON object above, is the JWS Payload:
[123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10,
32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56,
48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97,
109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111,
111, 116, 34, 58, 116, 114, 117, 101, 125]
Base64url encoding the JWS Payload yields this Encoded JWS Payload Base64url encoding the JWS Payload yields this Encoded JWS Payload
(with line breaks for display purposes only): (with line breaks for display purposes only):
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
Computing the HMAC of the octets of the ASCII [USASCII] Computing the HMAC of the octets of the ASCII [USASCII]
representation of the JWS Signing Input (the concatenation of the representation of the JWS Signing Input (the concatenation of the
Encoded JWS Header, a period ('.') character, and the Encoded JWS Encoded JWS Header, a period ('.') character, and the Encoded JWS
Payload) with the HMAC SHA-256 algorithm using the key specified in Payload) with the HMAC SHA-256 algorithm using the key specified in
skipping to change at page 7, line 47 skipping to change at page 7, line 50
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
This computation is illustrated in more detail in Appendix A.1. See See Appendix A for additional examples.
Appendix A for additional examples.
4. JWS Header 4. JWS Header
The members of the JSON object(s) representing the JWS Header The members of the JSON object(s) representing the JWS Header
describe the digital signature or MAC applied to the Encoded JWS describe the digital signature or MAC applied to the Encoded JWS
Header and the Encoded JWS Payload and optionally additional Header and the Encoded JWS Payload and optionally additional
properties of the JWS. The Header Parameter Names within the JWS properties of the JWS. The Header Parameter Names within the JWS
Header MUST be unique; recipients MUST either reject JWSs with Header MUST be unique; recipients 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 8, line 25 skipping to change at page 8, line 25
Implementations are required to understand the specific header Implementations are required to understand the specific header
parameters defined by this specification that are designated as "MUST parameters defined by this specification that are designated as "MUST
be understood" and process them in the manner defined in this be understood" and process them in the manner defined in this
specification. All other header parameters defined by this specification. All other header parameters defined by this
specification that are not so designated MUST be ignored when not specification that are not so designated MUST be ignored when not
understood. Unless listed as a critical header parameter, per understood. Unless listed as a critical header parameter, per
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: Registered Header
Parameter Names, Public Header Parameter Names, and Private Header Parameter Names, Public Header Parameter Names, and Private Header
Parameter Names. Parameter Names.
4.1. Reserved Header Parameter Names 4.1. Registered Header Parameter Names
The following Header Parameter Names are reserved with meanings as The following Header Parameter Names are registered in the IANA JSON
defined below. Web Signature and Encryption Header Parameters registry defined in
Section 8.1, with meanings as defined below.
Additional reserved Header Parameter Names can be defined via the As indicated by the common registry, JWSs and JWEs share a common
IANA JSON Web Signature and Encryption Header Parameters registry header parameter space; when a parameter is used by both
Section 8.1. As indicated by the common registry, JWSs and JWEs specifications, its usage must be compatible between the
share a common header parameter space; when a parameter is used by
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 the cryptographic The "alg" (algorithm) header parameter identifies the cryptographic
algorithm used to secure the JWS. The signature, MAC, or plaintext algorithm used to secure the JWS. The signature, MAC, or plaintext
value is not valid if the "alg" value does not represent a supported value is not valid if the "alg" value does not represent a supported
algorithm, or if there is not a key for use with that algorithm algorithm, or if there is not a key for use with that algorithm
associated with the party that digitally signed or MACed the content. associated with the party that digitally signed or MACed the content.
"alg" values SHOULD either be registered in the IANA JSON Web "alg" values SHOULD either be registered in the IANA JSON Web
Signature and Encryption Algorithms registry [JWA] or be a value that Signature and Encryption Algorithms registry defined in [JWA] or be a
contains a Collision Resistant Namespace. The "alg" value is a case value that contains a Collision Resistant Name. The "alg" value is a
sensitive string containing a StringOrURI value. Use of this header case sensitive string containing a StringOrURI value. Use of this
parameter is REQUIRED. This header parameter MUST be understood by header parameter is REQUIRED. This header parameter MUST be
implementations. understood and processed by 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 defined in [JWA]; the
contents of this registry are the values defined in Section 3.1 of initial contents of this registry are the values defined in Section
the JSON Web Algorithms (JWA) [JWA] specification. 3.1 of 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
refers to a resource for a set of JSON-encoded public keys, one of refers to a resource for a set of JSON-encoded public keys, one of
which corresponds to the key used to digitally sign the JWS. The which corresponds to the key used to digitally sign the JWS. The
keys MUST be encoded as a JSON Web Key Set (JWK Set) [JWK]. The keys MUST be encoded as a JSON Web Key Set (JWK Set) [JWK]. The
protocol used to acquire the resource MUST provide integrity protocol used to acquire the resource MUST provide integrity
protection; an HTTP GET request to retrieve the JWK Set MUST use TLS protection; an HTTP GET request to retrieve the JWK Set MUST use TLS
[RFC2818] [RFC5246]; the identity of the server MUST be validated, as [RFC2818] [RFC5246]; the identity of the server MUST be validated, as
skipping to change at page 9, line 47 skipping to change at page 9, line 46
in PEM encoded form [RFC1421]. The certificate containing the public in PEM encoded form [RFC1421]. The certificate containing the public
key corresponding to the key used to digitally sign the JWS MUST be key corresponding to the key used to digitally sign the JWS MUST be
the first certificate. This MAY be followed by additional the first certificate. This MAY be followed by additional
certificates, with each subsequent certificate being the one used to certificates, with each subsequent certificate being the one used to
certify the previous one. The protocol used to acquire the resource certify the previous one. The protocol used to acquire the resource
MUST provide integrity protection; an HTTP GET request to retrieve MUST provide integrity protection; an HTTP GET request to retrieve
the certificate MUST use TLS [RFC2818] [RFC5246]; the identity of the the certificate MUST use TLS [RFC2818] [RFC5246]; the identity of the
server MUST be validated, as per Section 3.1 of HTTP Over TLS server MUST be validated, as per Section 3.1 of HTTP Over TLS
[RFC2818]. Use of this header parameter is OPTIONAL. [RFC2818]. Use of this header parameter is OPTIONAL.
4.1.5. "x5t" (X.509 Certificate Thumbprint) Header Parameter 4.1.5. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter
The "x5t" (X.509 Certificate Thumbprint) header parameter is a The "x5t" (X.509 Certificate SHA-1 Thumbprint) header parameter is a
base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER
encoding of the X.509 certificate [RFC5280] corresponding to the key encoding of the X.509 certificate [RFC5280] corresponding to the key
used to digitally sign the JWS. Use of this header parameter is used to digitally sign the JWS. Use of this header parameter is
OPTIONAL. OPTIONAL.
If, in the future, certificate thumbprints need to be computed using If, in the future, certificate thumbprints need to be computed using
hash functions other than SHA-1, it is suggested that additional hash functions other than SHA-1, it is suggested that additional
related header parameters be defined for that purpose. For example, related header parameters be defined for that purpose. For example,
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 by registering it in using SHA-256) header parameter could be defined by registering it in
the IANA JSON Web Signature and Encryption Header Parameters registry the IANA JSON Web Signature and Encryption Header Parameters registry
Section 8.1. defined in Section 8.1.
4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter
The "x5c" (X.509 Certificate Chain) header parameter contains the The "x5c" (X.509 Certificate Chain) header parameter contains the
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
skipping to change at page 10, line 49 skipping to change at page 10, line 47
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
the "kid" value is unspecified. Its value MUST be a string. Use of the "kid" value is unspecified. Its value MUST be a string. Use of
this header parameter is OPTIONAL. this header parameter is OPTIONAL.
When used with a JWK, the "kid" value can be used to match a JWK When used with a JWK, the "kid" value can be used to match a JWK
"kid" parameter value. "kid" parameter value.
4.1.8. "typ" (Type) Header Parameter 4.1.8. "typ" (Type) Header Parameter
The "typ" (type) header parameter MAY be used to declare the type of The "typ" (type) header parameter is used to declare the type of this
this complete JWS object in an application-specific manner in complete JWS object in an application-specific manner in contexts
contexts where this is useful to the application. This parameter has where this is useful to the application. This parameter has no
no effect upon the JWS processing. The type value "JOSE" MAY be used effect upon the JWS processing. The type value "JOSE" can be used by
by applications to indicate that this object is a JWS or JWE using applications to indicate that this object is a JWS or JWE using the
the JWS Compact Serialization or the JWE Compact Serialization. The JWS Compact Serialization or the JWE Compact Serialization. The type
type value "JOSE+JSON" MAY be used by applications to indicate that value "JOSE+JSON" can be used by applications to indicate that this
this object is a JWS or JWE using the JWS JSON Serialization or the object is a JWS or JWE using the JWS JSON Serialization or the JWE
JWE JSON Serialization. Other type values MAY be used, and if not JSON Serialization. Other type values can also be used by
understood, SHOULD be ignored. The "typ" value is a case sensitive applications. The "typ" value is a case sensitive string. Use of
string. Use of this header parameter is OPTIONAL. this header parameter is OPTIONAL.
MIME Media Type [RFC2046] values MAY be used as "typ" values. MIME Media Type [RFC2046] values MAY be used as "typ" values. When
MIME Media Type values are used, it is RECOMMENDED that they be
spelled using the exact character case used in the MIME Media Types
registry [IANA.MediaTypes], since this field is case sensitive,
whereas MIME Media Type values are case insensitive.
"typ" values SHOULD either be registered in the IANA JSON Web "typ" values SHOULD either be registered in the IANA JSON Web
Signature and Encryption Type Values registry Section 8.2 or be a Signature and Encryption Type Values registry defined in Section 8.2
value that contains a Collision Resistant Namespace. or be a value that contains a Collision Resistant Name.
4.1.9. "cty" (Content Type) Header Parameter 4.1.9. "cty" (Content Type) Header Parameter
The "cty" (content type) header parameter MAY be used to declare the The "cty" (content type) header parameter is used to declare the type
type of the secured content (the payload) in an application-specific of the secured content (the payload) in an application-specific
manner in contexts where this is useful to the application. This manner in contexts where this is useful to the application. This
parameter has no effect upon the JWS processing. Content type values parameter has no effect upon the JWS processing. The "cty" value is
that are not understood SHOULD be ignored. The "cty" value is a case a case sensitive string. Use of this header parameter is OPTIONAL.
sensitive string. Use of this header parameter is OPTIONAL.
The values used for the "cty" header parameter come from the same The values used for the "cty" header parameter come from the same
value space as the "typ" header parameter, with the same rules value space as the "typ" header parameter, with the same rules
applying. applying.
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
[[ this specification ]] are being used that MUST be understood and [[ this specification ]] are being used that MUST be understood and
processed. Its value is an array listing the header parameter names processed. Its value is an array listing the header parameter names
skipping to change at page 11, line 50 skipping to change at page 11, line 50
include header parameter names defined by [[ this specification ]] or include header parameter names defined by [[ this specification ]] or
by [JWA] for use with JWS, duplicate names, or names that do not by [JWA] for use with JWS, duplicate names, or names that do not
occur as header parameter names within the JWS Header in the "crit" occur as header parameter names within the JWS Header in the "crit"
list. Senders MUST not use the empty list "[]" as the "crit" value. list. 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 [[ this specification ]] or by header parameter names defined by [[ this specification ]] or by
[JWA] for use with JWS, or any other constraints on its use are [JWA] for use with JWS, or any other constraints on its use are
violated. This header parameter MUST be integrity protected, and violated. This header parameter MUST be integrity protected, and
therefore MUST occur only with the JWS Protected Header, when used. therefore MUST occur only with the JWS Protected Header, when used.
Use of this header parameter is OPTIONAL. This header parameter MUST Use of this header parameter is OPTIONAL. This header parameter MUST
be understood by implementations. 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:
{"alg":"ES256", {"alg":"ES256",
"crit":["exp"], "crit":["exp"],
"exp":1363284000 "exp":1363284000
} }
4.2. Public Header Parameter Names 4.2. Public Header Parameter Names
Additional Header Parameter Names can be defined by those using JWSs. Additional Header Parameter Names can be defined by those using JWSs.
However, in order to prevent collisions, any new Header Parameter However, in order to prevent collisions, any new Header Parameter
Name SHOULD either be registered in the IANA JSON Web Signature and Name SHOULD either be registered in the IANA JSON Web Signature and
Encryption Header Parameters registry Section 8.1 or be a Public Encryption Header Parameters registry defined in Section 8.1 or be a
Name: a value that contains a Collision Resistant Namespace. In each Public Name: a value that contains a Collision Resistant Name. In
case, the definer of the name or value needs to take reasonable each case, the definer of the name or value needs to take reasonable
precautions to make sure they are in control of the part of the precautions to make sure they are in control of the part of the
namespace they use to define the Header Parameter Name. namespace they use to define the Header Parameter Name.
New header parameters should be introduced sparingly, as they can New header parameters should be introduced sparingly, as they can
result in non-interoperable JWSs. result in non-interoperable JWSs.
4.3. Private Header Parameter Names 4.3. Private Header Parameter Names
A producer and consumer of a JWS may agree to use Header Parameter A producer and consumer of a JWS may agree to use Header Parameter
Names that are Private Names: names that are not Reserved Names Names that are Private Names: names that are not Registered Header
Section 4.1 or Public Names Section 4.2. Unlike Public Names, Parameter Names Section 4.1 or Public Header Parameter Names
Private Names are subject to collision and should be used with Section 4.2. Unlike Public Header Parameter Names, Private Header
Parameter Names are subject to collision and should be used with
caution. caution.
5. Producing and Consuming JWSs 5. Producing and Consuming JWSs
5.1. Message Signing or MACing 5.1. Message Signing or MACing
To create a JWS, one MUST perform these steps. The order of the To create a JWS, one MUST perform these steps. The order of the
steps is not significant in cases where there are no dependencies steps is not significant in cases where there are no dependencies
between the inputs and outputs of the steps. between the inputs and outputs of the steps.
skipping to change at page 15, line 49 skipping to change at page 15, line 49
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. These header parameters MUST be integrity to identify the key used. These header parameters MUST be integrity
protected if the information about the key that they convey is to be protected if the information that they convey is to be utilized in a
considered trusted. trust decision.
The sender SHOULD include sufficient information in the Header The sender SHOULD include sufficient information in the Header
Parameters to identify the key used, unless the application uses Parameters to identify the key used, unless the application uses
another means or convention to determine the key used. Validation of another means or convention to determine the key used. Validation of
the signature or MAC fails when the algorithm used requires a key 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 (which is true of all algorithms except for "none") and the key used
cannot be determined. cannot be determined.
The means of exchanging any shared symmetric keys used is outside the The means of exchanging any shared symmetric keys used is outside the
scope of this specification. scope of this specification.
skipping to change at page 18, line 40 skipping to change at page 18, line 40
Values are registered with a Specification Required [RFC5226] after a Values are registered with a Specification Required [RFC5226] after a
two-week review period on the [TBD]@ietf.org mailing list, on the two-week review period on the [TBD]@ietf.org mailing list, on the
advice of one or more Designated Experts. However, to allow for the advice of one or more Designated Experts. However, to allow for the
allocation of values prior to publication, the Designated Expert(s) allocation of values prior to publication, the Designated Expert(s)
may approve registration once they are satisfied that such a may approve registration once they are satisfied that such a
specification will be published. specification will be published.
Registration requests must be sent to the [TBD]@ietf.org mailing list Registration requests must be sent to the [TBD]@ietf.org mailing list
for review and comment, with an appropriate subject (e.g., "Request for review and comment, with an appropriate subject (e.g., "Request
for access token type: example"). [[ Note to RFC-EDITOR: The name of for access token type: example"). [[ Note to the RFC Editor: The name
the mailing list should be determined in consultation with the IESG of the mailing list should be determined in consultation with the
and IANA. Suggested name: jose-reg-review. ]] 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. successful. Registration requests that are undetermined for a period
longer than 21 days can be brought to the IESG's attention (using the
iesg@iesg.org mailing list) for resolution.
Criteria that should be applied by the Designated Expert(s) includes
determining whether the proposed registration duplicates existing
functionality, determining whether it is likely to be of general
applicability or whether it is useful only for a single application,
and whether the registration makes sense.
IANA must only accept registry updates from the Designated Expert(s) IANA must only accept registry updates from the Designated Expert(s)
and should direct all requests for registration to the review mailing and should direct all requests for registration to the review mailing
list. list.
It is suggested that multiple Designated Experts be appointed who are
able to represent the perspectives of different applications using
this specification, in order to enable broadly-informed review of
registration decisions. In cases where a registration decision could
be perceived as creating a conflict of interest for a particular
Expert, that Expert should defer to the judgment of the other
Expert(s).
8.1. JSON Web Signature and Encryption Header Parameters Registry 8.1. JSON Web Signature and Encryption Header Parameters Registry
This specification establishes the IANA JSON Web Signature and This specification establishes the IANA JSON Web Signature and
Encryption Header Parameters registry for reserved JWS and JWE Header Encryption Header Parameters registry for JWS and JWE Header
Parameter Names. The registry records the reserved Header Parameter Parameter Names. The registry records the Header Parameter Name and
Name and a reference to the specification that defines it. The same a reference to the specification that defines it. The same Header
Header Parameter Name MAY be registered multiple times, provided that Parameter Name MAY be registered multiple times, provided that the
the parameter usage is compatible between the specifications. parameter usage is compatible between the specifications. Different
Different registrations of the same Header Parameter Name will registrations of the same Header Parameter Name will typically use
typically use different Header Parameter Usage Location(s) values. different Header Parameter Usage Location(s) values.
8.1.1. Registration Template 8.1.1. Registration Template
Header Parameter Name: Header Parameter Name:
The name requested (e.g., "example"). This name is case The name requested (e.g., "example"). Because a core goal of this
sensitive. Names that match other registered names in a case specification is for the resulting representations to be compact,
insensitive manner SHOULD NOT be accepted. it is RECOMMENDED that the name be short -- not to exceed 8
characters without a compelling reason to do so. This name is
case sensitive. Names may not match other registered names in a
case insensitive manner unless the Designated Expert(s) state that
there is a compelling reason to allow an exception in this
particular case.
Header Parameter Usage Location(s): Header Parameter Usage Location(s):
The header parameter usage locations, which should be one or more The header parameter usage locations, which should be one or more
of the values "JWS" or "JWE". of the values "JWS" or "JWE".
Change Controller: Change Controller:
For Standards Track RFCs, state "IETF". For others, give the name For Standards Track RFCs, state "IESG". For others, give the name
of the responsible party. Other details (e.g., postal address, of the responsible party. Other details (e.g., postal address,
email address, home page URI) may also be included. email address, home page URI) may also be included.
Specification Document(s): Specification Document(s):
Reference to the document(s) that specify the parameter, Reference to the document(s) that specify the parameter,
preferably including URI(s) that can be used to retrieve copies of preferably including URI(s) that can be used to retrieve copies of
the document(s). An indication of the relevant sections may also the document(s). An indication of the relevant sections may also
be included but is not required. be included but is not required.
8.1.2. Initial Registry Contents 8.1.2. Initial Registry Contents
This specification registers the Header Parameter Names defined in This specification registers the Header Parameter Names defined in
Section 4.1 in this registry. Section 4.1 in this registry.
o Header Parameter Name: "alg" o Header Parameter Name: "alg"
o Header Parameter Usage Location(s): JWS o Header Parameter Usage Location(s): JWS
o Change Controller: IETF o Change Controller: IESG
o Specification Document(s): Section 4.1.1 of [[ this document ]] o Specification Document(s): Section 4.1.1 of [[ this document ]]
o Header Parameter Name: "jku" o Header Parameter Name: "jku"
o Header Parameter Usage Location(s): JWS o Header Parameter Usage Location(s): JWS
o Change Controller: IETF o Change Controller: IESG
o Specification Document(s): Section 4.1.2 of [[ this document ]] o Specification Document(s): Section 4.1.2 of [[ this document ]]
o Header Parameter Name: "jwk" o Header Parameter Name: "jwk"
o Header Parameter Usage Location(s): JWS o Header Parameter Usage Location(s): JWS
o Change Controller: IETF o Change Controller: IESG
o Specification document(s): Section 4.1.3 of [[ this document ]] o Specification document(s): Section 4.1.3 of [[ this document ]]
o Header Parameter Name: "x5u" o Header Parameter Name: "x5u"
o Header Parameter Usage Location(s): JWS o Header Parameter Usage Location(s): JWS
o Change Controller: IETF o Change Controller: IESG
o Specification Document(s): Section 4.1.4 of [[ this document ]] o Specification Document(s): Section 4.1.4 of [[ this document ]]
o Header Parameter Name: "x5t" o Header Parameter Name: "x5t"
o Header Parameter Usage Location(s): JWS o Header Parameter Usage Location(s): JWS
o Change Controller: IETF o Change Controller: IESG
o Specification Document(s): Section 4.1.5 of [[ this document ]] o Specification Document(s): Section 4.1.5 of [[ this document ]]
o Header Parameter Name: "x5c" o Header Parameter Name: "x5c"
o Header Parameter Usage Location(s): JWS o Header Parameter Usage Location(s): JWS
o Change Controller: IETF o Change Controller: IESG
o Specification Document(s): Section 4.1.6 of [[ this document ]] o Specification Document(s): Section 4.1.6 of [[ this document ]]
o Header Parameter Name: "kid" o Header Parameter Name: "kid"
o Header Parameter Usage Location(s): JWS o Header Parameter Usage Location(s): JWS
o Change Controller: IETF o Change Controller: IESG
o Specification Document(s): Section 4.1.7 of [[ this document ]] o Specification Document(s): Section 4.1.7 of [[ this document ]]
o Header Parameter Name: "typ" o Header Parameter Name: "typ"
o Header Parameter Usage Location(s): JWS o Header Parameter Usage Location(s): JWS
o Change Controller: IETF o Change Controller: IESG
o Specification Document(s): Section 4.1.8 of [[ this document ]] o Specification Document(s): Section 4.1.8 of [[ this document ]]
o Header Parameter Name: "cty" o Header Parameter Name: "cty"
o Header Parameter Usage Location(s): JWS o Header Parameter Usage Location(s): JWS
o Change Controller: IETF o Change Controller: IESG
o Specification Document(s): Section 4.1.9 of [[ this document ]] o Specification Document(s): Section 4.1.9 of [[ this document ]]
o Header Parameter Name: "crit" o Header Parameter Name: "crit"
o Header Parameter Usage Location(s): JWS o Header Parameter Usage Location(s): JWS
o Change Controller: IETF o Change Controller: IESG
o Specification Document(s): Section 4.1.10 of [[ this document ]] o Specification Document(s): Section 4.1.10 of [[ this document ]]
8.2. JSON Web Signature and Encryption Type Values Registry 8.2. JSON Web Signature and Encryption Type Values Registry
This specification establishes the IANA JSON Web Signature and This specification establishes the IANA JSON Web Signature and
Encryption Type Values registry for values of the JWS and JWE "typ" Encryption Type Values registry for values of the JWS and JWE "typ"
(type) header parameter. It is RECOMMENDED that all registered "typ" (type) header parameter. It is RECOMMENDED that all registered "typ"
values also include a MIME Media Type [RFC2046] value that the values also include a MIME Media Type [RFC2046] value that the
registered value is a short name for. The registry records the "typ" registered value is a short name for. The registry records the "typ"
value, the MIME type value that it is an abbreviation for (if any), value, the MIME type value that it is an abbreviation for (if any),
and a reference to the specification that defines it. and a reference to the specification that defines it.
MIME Media Type [RFC2046] values MUST NOT be directly registered as MIME Media Type [RFC2046] values MUST NOT be directly registered as
new "typ" values; rather, new "typ" values MAY be registered as short "typ" values; rather, "typ" values MAY be registered as short names
names for MIME types. for MIME types.
8.2.1. Registration Template 8.2.1. Registration Template
"typ" Header Parameter Value: "typ" Header Parameter Value:
The name requested (e.g., "example"). This name is case The name requested (e.g., "example"). Because a core goal of this
sensitive. Names that match other registered names in a case specification is for the resulting representations to be compact,
insensitive manner SHOULD NOT be accepted. it is RECOMMENDED that the name be short -- not to exceed 8
characters without a compelling reason to do so. This name is
case sensitive. Names may not match other registered names in a
case insensitive manner unless the Designated Expert(s) state that
there is a compelling reason to allow an exception in this
particular case.
Abbreviation for MIME Type: Abbreviation for MIME Type:
The MIME type that this name is an abbreviation for (e.g., The MIME type that this name is an abbreviation for (e.g.,
"application/example"). "application/example").
Change Controller: Change Controller:
For Standards Track RFCs, state "IETF". For others, give the name For Standards Track RFCs, state "IESG". For others, give the name
of the responsible party. Other details (e.g., postal address, of the responsible party. Other details (e.g., postal address,
email address, home page URI) may also be included. email address, home page URI) may also be included.
Specification Document(s): Specification Document(s):
Reference to the document(s) that specify the parameter, Reference to the document(s) that specify the parameter,
preferably including URI(s) that can be used to retrieve copies of preferably including URI(s) that can be used to retrieve copies of
the document(s). An indication of the relevant sections may also the document(s). An indication of the relevant sections may also
be included but is not required. be included but is not required.
8.2.2. Initial Registry Contents 8.2.2. Initial Registry Contents
This specification registers the "JOSE" and "JOSE+JSON" type values This specification registers the "JOSE" and "JOSE+JSON" type values
in this registry: in this registry:
o "typ" Header Parameter Value: "JOSE" o "typ" Header Parameter Value: "JOSE"
o Abbreviation for MIME type: application/jose o Abbreviation for MIME type: application/jose
o Change Controller: IETF o Change Controller: IESG
o Specification Document(s): Section 4.1.8 of [[ this document ]] o Specification Document(s): Section 4.1.8 of [[ this document ]]
o "typ" Header Parameter Value: "JOSE+JSON" o "typ" Header Parameter Value: "JOSE+JSON"
o Abbreviation for MIME type: application/jose+json o Abbreviation for MIME type: application/jose+json
o Change Controller: IETF o Change Controller: IESG
o Specification Document(s): Section 4.1.8 of [[ this document ]] o Specification Document(s): Section 4.1.8 of [[ this document ]]
8.3. Media Type Registration 8.3. Media Type Registration
8.3.1. Registry Contents 8.3.1. Registry Contents
This specification registers the "application/jose" Media Type This specification registers the "application/jose" Media Type
[RFC2046] in the MIME Media Type registry [RFC4288], which can be [RFC2046] in the MIME Media Types registry [IANA.MediaTypes], which
used to indicate that the content is a JWS or JWE object using the can be used to indicate that the content is a JWS or JWE object using
JWS Compact Serialization or the JWE Compact Serialization and the the JWS Compact Serialization or the JWE Compact Serialization and
"application/jose+json" Media Type in the MIME Media Type registry, the "application/jose+json" Media Type in the MIME Media Types
which can be used to indicate that the content is a JWS or JWE object registry, which can be used to indicate that the content is a JWS or
using the JWS JSON Serialization or the JWE JSON Serialization. JWE object using the JWS JSON Serialization or the JWE JSON
Serialization.
o Type name: application o Type name: application
o Subtype name: jose o Subtype name: jose
o Required parameters: n/a o Required parameters: n/a
o Optional parameters: n/a o Optional parameters: n/a
o Encoding considerations: application/jose values are encoded as a o Encoding considerations: 8bit; application/jose values are encoded
series of base64url encoded values (some of which may be the empty as a series of base64url encoded values (some of which may be the
string) separated by period ('.') characters. empty string) separated by period ('.') characters.
o Security considerations: See the Security Considerations section o Security considerations: See the Security Considerations section
of [[ this document ]] of [[ this document ]]
o Interoperability considerations: n/a o Interoperability considerations: n/a
o Published specification: [[ this document ]] o Published specification: [[ this document ]]
o Applications that use this media type: OpenID Connect, Mozilla o Applications that use this media type: OpenID Connect, Mozilla
Persona, Salesforce, Google, numerous others that use signed JWTs Persona, Salesforce, Google, numerous others that use signed JWTs
o Additional information: Magic number(s): n/a, File extension(s): o Additional information: Magic number(s): n/a, File extension(s):
n/a, Macintosh file type code(s): n/a n/a, Macintosh file type code(s): n/a
o Person & email address to contact for further information: Michael o Person & email address to contact for further information: Michael
B. Jones, mbj@microsoft.com B. Jones, mbj@microsoft.com
o Intended usage: COMMON o Intended usage: COMMON
o Restrictions on usage: none o Restrictions on usage: none
o Author: Michael B. Jones, mbj@microsoft.com o Author: Michael B. Jones, mbj@microsoft.com
o Change Controller: IETF o Change Controller: IESG
o Type name: application o Type name: application
o Subtype name: jose+json o Subtype name: jose+json
o Required parameters: n/a o Required parameters: n/a
o Optional parameters: n/a o Optional parameters: n/a
o Encoding considerations: application/jose+json values are o Encoding considerations: 8bit; application/jose+json values are
represented as a JSON Object; UTF-8 encoding SHOULD be employed represented as a JSON Object; UTF-8 encoding SHOULD be employed
for the JSON object. for the JSON object.
o Security considerations: See the Security Considerations section o Security considerations: See the Security Considerations section
of [[ this document ]] of [[ this document ]]
o Interoperability considerations: n/a o Interoperability considerations: n/a
o Published specification: [[ this document ]] o Published specification: [[ this document ]]
o Applications that use this media type: TBD o Applications that use this media type: TBD
o Additional information: Magic number(s): n/a, File extension(s): o Additional information: Magic number(s): n/a, File extension(s):
n/a, Macintosh file type code(s): n/a n/a, Macintosh file type code(s): n/a
o Person & email address to contact for further information: Michael o Person & email address to contact for further information: Michael
B. Jones, mbj@microsoft.com B. Jones, mbj@microsoft.com
o Intended usage: COMMON o Intended usage: COMMON
o Restrictions on usage: none o Restrictions on usage: none
o Author: Michael B. Jones, mbj@microsoft.com o Author: Michael B. Jones, mbj@microsoft.com
o Change Controller: IETF o Change Controller: IESG
9. Security Considerations 9. Security Considerations
9.1. Cryptographic Security Considerations 9.1. Cryptographic Security Considerations
All of the security issues faced by any cryptographic application All of the security issues faced by any cryptographic application
must be faced by a JWS/JWE/JWK agent. Among these issues are must be faced by a JWS/JWE/JWK agent. Among these issues are
protecting the user's private and symmetric keys, preventing various protecting the user's private and symmetric keys, preventing various
attacks, and helping the user avoid mistakes such as inadvertently attacks, and helping the user avoid mistakes such as inadvertently
encrypting a message for the wrong recipient. The entire list of encrypting a message for the wrong recipient. The entire list of
skipping to change at page 25, line 45 skipping to change at page 26, line 31
performed, per RFC 6125 [RFC6125]. performed, per RFC 6125 [RFC6125].
10. References 10. References
10.1. Normative References 10.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.
[IANA.MediaTypes]
Internet Assigned Numbers Authority (IANA), "MIME Media
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),
September 2013. September 2013.
skipping to change at page 26, line 36 skipping to change at page 27, line 25
[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.
[RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and
Registration Procedures", RFC 4288, December 2005.
[RFC4627] Crockford, D., "The application/json Media Type for [RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006. JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, October 2006. Encodings", RFC 4648, October 2006.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226, IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008. May 2008.
skipping to change at page 30, line 33 skipping to change at page 31, line 24
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
sequence containing the UTF-8 representation of the JWS Header is sequence containing the UTF-8 representation of the JWS Header is
decoded into the JWS Header string. decoded into the JWS Header string.
A.1.3. Validating A.1.3. Validating
Next we validate the decoded results. Since the "alg" parameter in Next we validate the decoded results. Since the "alg" parameter in
the header is "HS256", we validate the HMAC SHA-256 value contained the header is "HS256", we validate the HMAC SHA-256 value contained
in the JWS Signature. If any of the validation steps fail, the JWS in the JWS Signature.
MUST be rejected.
First, we validate that the JWS Header string is legal JSON. First, we validate that the JWS Header string is legal JSON.
To validate the HMAC value, we repeat the previous process of using To validate the HMAC value, we repeat the previous process of using
the correct key and the ASCII representation of the JWS Signing Input the correct key and the ASCII representation of the JWS Signing Input
as input to the HMAC SHA-256 function and then taking the output and as input to the HMAC SHA-256 function and then taking the output and
determining if it matches the JWS Signature. If it matches exactly, determining if it matches the JWS Signature. If it matches exactly,
the HMAC has been validated. the HMAC has been validated.
A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256
skipping to change at page 33, line 41 skipping to change at page 34, line 29
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
sequence containing the UTF-8 representation of the JWS Header is sequence containing the UTF-8 representation of the JWS Header is
decoded into the JWS Header string. decoded into the JWS Header string.
A.2.3. Validating A.2.3. Validating
Since the "alg" parameter in the header is "RS256", we validate the Since the "alg" parameter in the header is "RS256", we validate the
RSASSA-PKCS-v1_5 SHA-256 digital signature contained in the JWS RSASSA-PKCS-v1_5 SHA-256 digital signature contained in the JWS
Signature. If any of the validation steps fail, the JWS MUST be Signature.
rejected.
First, we validate that the JWS Header string is legal JSON. First, we validate that the JWS Header string is legal JSON.
Validating the JWS Signature is a little different from the previous Validating the JWS Signature is a little different from the previous
example. First, we base64url decode the Encoded JWS Signature to example. First, we base64url decode the Encoded JWS Signature to
produce a digital signature S to check. We then pass (n, e), S and produce a digital signature S to check. We then pass (n, e), S and
the octets of the ASCII representation of the JWS Signing Input to an the octets of the ASCII representation of the JWS Signing Input to an
RSASSA-PKCS-v1_5 signature verifier that has been configured to use RSASSA-PKCS-v1_5 signature verifier that has been configured to use
the SHA-256 hash function. the SHA-256 hash function.
skipping to change at page 36, line 17 skipping to change at page 37, line 4
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
sequence containing the UTF-8 representation of the JWS Header is sequence containing the UTF-8 representation of the JWS Header is
decoded into the JWS Header string. decoded into the JWS Header string.
A.3.3. Validating A.3.3. Validating
Since the "alg" parameter in the header is "ES256", we validate the Since the "alg" parameter in the header is "ES256", we validate the
ECDSA P-256 SHA-256 digital signature contained in the JWS Signature. ECDSA P-256 SHA-256 digital signature contained in the JWS Signature.
If any of the validation steps fail, the JWS MUST be rejected.
First, we validate that the JWS Header string is legal JSON. First, we validate that the JWS Header string is legal JSON.
Validating the JWS Signature is a little different from the first Validating the JWS Signature is a little different from the first
example. First, we base64url decode the Encoded JWS Signature as in example. First, we base64url decode the Encoded JWS Signature as in
the previous examples but we then need to split the 64 member octet the previous examples but we then need to split the 64 member octet
sequence that must result into two 32 octet sequences, the first R sequence that must result into two 32 octet sequences, the first R
and the second S. We then pass (x, y), (R, S) and the octets of the and the second S. We then pass (x, y), (R, S) and the octets of the
ASCII representation of the JWS Signing Input to an ECDSA signature ASCII representation of the JWS Signing Input to an ECDSA signature
verifier that has been configured to use the P-256 curve with the verifier that has been configured to use the P-256 curve with the
SHA-256 hash function. SHA-256 hash function.
As explained in Section 3.4 of the JSON Web Algorithms (JWA) [JWA]
specification, the use of the K value in ECDSA means that we cannot
validate the correctness of the digital signature in the same way we
validated the correctness of the HMAC. Instead, implementations MUST
use an ECDSA validator to validate the digital signature.
A.4. Example JWS using ECDSA P-521 SHA-512 A.4. Example JWS using ECDSA P-521 SHA-512
A.4.1. Encoding A.4.1. Encoding
The JWS Header for this example differs from the previous example The JWS Header for this example differs from the previous example
because different ECDSA curves and hash functions are used. The JWS because different ECDSA curves and hash functions are used. The JWS
Header used is: Header used is:
{"alg":"ES512"} {"alg":"ES512"}
skipping to change at page 39, line 9 skipping to change at page 39, line 31
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
sequence containing the UTF-8 representation of the JWS Header is sequence containing the UTF-8 representation of the JWS Header is
decoded into the JWS Header string. decoded into the JWS Header string.
A.4.3. Validating A.4.3. Validating
Since the "alg" parameter in the header is "ES512", we validate the Since the "alg" parameter in the header is "ES512", we validate the
ECDSA P-521 SHA-512 digital signature contained in the JWS Signature. ECDSA P-521 SHA-512 digital signature contained in the JWS Signature.
If any of the validation steps fail, the JWS MUST be rejected.
First, we validate that the JWS Header string is legal JSON. First, we validate that the JWS Header string is legal JSON.
Validating the JWS Signature is similar to the previous example. Validating the JWS Signature is similar to the previous example.
First, we base64url decode the Encoded JWS Signature as in the First, we base64url decode the Encoded JWS Signature as in the
previous examples but we then need to split the 132 member octet previous examples but we then need to split the 132 member octet
sequence that must result into two 66 octet sequences, the first R sequence that must result into two 66 octet sequences, the first R
and the second S. We then pass (x, y), (R, S) and the octets of the and the second S. We then pass (x, y), (R, S) and the octets of the
ASCII representation of the JWS Signing Input to an ECDSA signature ASCII representation of the JWS Signing Input to an ECDSA signature
verifier that has been configured to use the P-521 curve with the verifier that has been configured to use the P-521 curve with the
SHA-512 hash function. SHA-512 hash function.
As explained in Section 3.4 of the JSON Web Algorithms (JWA) [JWA]
specification, the use of the K value in ECDSA means that we cannot
validate the correctness of the digital signature in the same way we
validated the correctness of the HMAC. Instead, implementations MUST
use an ECDSA validator to validate the digital signature.
A.5. Example Plaintext JWS A.5. Example Plaintext JWS
The following example JWS Header declares that the encoded object is The following example JWS Header declares that the encoded object is
a Plaintext JWS: a Plaintext JWS:
{"alg":"none"} {"alg":"none"}
Base64url encoding the octets of the UTF-8 representation of the JWS Base64url encoding the octets of the UTF-8 representation of the JWS
Header yields this Encoded JWS Header: Header yields this Encoded JWS Header:
skipping to change at page 41, line 12 skipping to change at page 41, line 26
eyJhbGciOiJFUzI1NiJ9 eyJhbGciOiJFUzI1NiJ9
A.6.2. JWS Per-Signature Unprotected Headers A.6.2. JWS Per-Signature Unprotected Headers
Key ID values are supplied for both keys using per-signature header Key ID values are supplied for both keys using per-signature header
parameters. The two values used to represent these Key IDs are: parameters. The two values used to represent these Key IDs are:
{"kid":"2010-12-29"} {"kid":"2010-12-29"}
and: and
{"kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"} {"kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"}
A.6.3. Complete JWS Header Values A.6.3. Complete JWS Header Values
Combining the protected and unprotected header values supplied, the Combining the protected and unprotected header values supplied, the
JWS Header values used for the first and second signatures JWS Header values used for the first and second signatures
respectively are: respectively are:
{"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 JSON Web Signature JSON Serialization for these values
is as follows (with line breaks for display purposes only): is as follows (with line breaks for display purposes only):
{"payload": {"payload":
skipping to change at page 46, line 19 skipping to change at page 46, line 19
Laurie, James Manger, Matt Miller, Tony Nadalin, Axel Nennker, John Laurie, James Manger, Matt Miller, Tony Nadalin, Axel Nennker, John
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 ]]
-16
o Changes to address editorial and minor issues #50, #98, #99, #102,
#104, #106, #107, #111, and #112.
-15 -15
o Clarified that it is an application decision which signatures, o Clarified that it is an application decision which signatures,
MACs, or plaintext values must successfully validate for the JWS MACs, or plaintext values must successfully validate for the JWS
to be accepted, addressing issue #35. to be accepted, addressing issue #35.
o Corrected editorial error in "ES512" example. o Corrected editorial error in "ES512" example.
o Changes to address editorial and minor issues #34, #96, #100, o Changes to address editorial and minor issues #34, #96, #100,
 End of changes. 73 change blocks. 
163 lines changed or deleted 179 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/