idnits 2.17.1 draft-ietf-jose-json-web-signature-14.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The "crit" (critical) header parameter indicates that extensions to [[ this specification ]] are being used that MUST be understood and processed. Its value is an array listing the header parameter names defined by those extensions that are used in the JWS Header. If any of the listed extension header parameters are not understood and supported by the receiver, it MUST reject the JWS. Senders MUST NOT include header parameter names defined by [[ this specification ]] or 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" list. Senders MUST not use the empty list "[]" as the "crit" value. Recipients MAY reject the JWS if the critical list contains any header parameter names defined by [[ this specification ]] or by [JWA] for use with JWS, or any other constraints on its use are violated. This header parameter MUST be integrity protected, and therefore MUST occur only with the JWS Protected Header, when used. Use of this header parameter is OPTIONAL. This header parameter MUST be understood by implementations. -- The document date (July 29, 2013) is 3924 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '123' on line 1677 -- Looks like a reference, but probably isn't: '34' on line 1677 -- Looks like a reference, but probably isn't: '97' on line 1686 -- Looks like a reference, but probably isn't: '108' on line 1686 -- Looks like a reference, but probably isn't: '103' on line 1677 -- Looks like a reference, but probably isn't: '58' on line 1677 -- Looks like a reference, but probably isn't: '82' on line 1405 -- Looks like a reference, but probably isn't: '83' on line 1677 -- Looks like a reference, but probably isn't: '50' on line 1677 -- Looks like a reference, but probably isn't: '53' on line 1677 -- Looks like a reference, but probably isn't: '54' on line 1548 -- Looks like a reference, but probably isn't: '125' on line 1677 -- Looks like a reference, but probably isn't: '69' on line 1677 -- Looks like a reference, but probably isn't: '49' on line 1677 -- Looks like a reference, but probably isn't: '80' on line 1686 -- Looks like a reference, but probably isn't: '121' on line 1686 -- Looks like a reference, but probably isn't: '111' on line 1686 -- Looks like a reference, but probably isn't: '100' on line 1686 -- Looks like a reference, but probably isn't: '0' on line 2012 -- Possible downref: Non-RFC (?) normative reference: ref. 'ECMAScript' -- Possible downref: Non-RFC (?) normative reference: ref. 'ITU.X690.1994' ** Downref: Normative reference to an Historic RFC: RFC 1421 ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 4288 (Obsoleted by RFC 6838) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) -- Possible downref: Non-RFC (?) normative reference: ref. 'USA15' -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' Summary: 8 errors (**), 0 flaws (~~), 2 warnings (==), 24 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JOSE Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track J. Bradley 5 Expires: January 30, 2014 Ping Identity 6 N. Sakimura 7 NRI 8 July 29, 2013 10 JSON Web Signature (JWS) 11 draft-ietf-jose-json-web-signature-14 13 Abstract 15 JSON Web Signature (JWS) is a means of representing content secured 16 with digital signatures or Message Authentication Codes (MACs) using 17 JavaScript Object Notation (JSON) based data structures. 18 Cryptographic algorithms and identifiers for use with this 19 specification are described in the separate JSON Web Algorithms (JWA) 20 specification. Related encryption capabilities are described in the 21 separate JSON Web Encryption (JWE) specification. 23 Status of this Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on January 30, 2014. 40 Copyright Notice 42 Copyright (c) 2013 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 3. JSON Web Signature (JWS) Overview . . . . . . . . . . . . . . 6 61 3.1. Example JWS . . . . . . . . . . . . . . . . . . . . . . . 6 62 4. JWS Header . . . . . . . . . . . . . . . . . . . . . . . . . . 8 63 4.1. Reserved Header Parameter Names . . . . . . . . . . . . . 8 64 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 8 65 4.1.2. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 9 66 4.1.3. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 9 67 4.1.4. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 9 68 4.1.5. "x5t" (X.509 Certificate Thumbprint) Header 69 Parameter . . . . . . . . . . . . . . . . . . . . . . 10 70 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter . . . 10 71 4.1.7. "kid" (Key ID) Header Parameter . . . . . . . . . . . 10 72 4.1.8. "typ" (Type) Header Parameter . . . . . . . . . . . . 11 73 4.1.9. "cty" (Content Type) Header Parameter . . . . . . . . 11 74 4.1.10. "crit" (Critical) Header Parameter . . . . . . . . . . 11 75 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 12 76 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 12 77 5. Producing and Consuming JWSs . . . . . . . . . . . . . . . . . 12 78 5.1. Message Signing or MACing . . . . . . . . . . . . . . . . 12 79 5.2. Message Signature or MAC Validation . . . . . . . . . . . 13 80 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 15 81 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 15 82 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 16 83 7.1. JWS Compact Serialization . . . . . . . . . . . . . . . . 16 84 7.2. JWS JSON Serialization . . . . . . . . . . . . . . . . . . 16 85 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 86 8.1. JSON Web Signature and Encryption Header Parameters 87 Registry . . . . . . . . . . . . . . . . . . . . . . . . . 18 88 8.1.1. Registration Template . . . . . . . . . . . . . . . . 19 89 8.1.2. Initial Registry Contents . . . . . . . . . . . . . . 19 90 8.2. JSON Web Signature and Encryption Type Values Registry . . 20 91 8.2.1. Registration Template . . . . . . . . . . . . . . . . 20 92 8.2.2. Initial Registry Contents . . . . . . . . . . . . . . 21 93 8.3. Media Type Registration . . . . . . . . . . . . . . . . . 21 94 8.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 21 95 9. Security Considerations . . . . . . . . . . . . . . . . . . . 22 96 9.1. Cryptographic Security Considerations . . . . . . . . . . 23 97 9.2. JSON Security Considerations . . . . . . . . . . . . . . . 24 98 9.3. Unicode Comparison Security Considerations . . . . . . . . 24 99 9.4. TLS Requirements . . . . . . . . . . . . . . . . . . . . . 25 100 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25 101 10.1. Normative References . . . . . . . . . . . . . . . . . . . 25 102 10.2. Informative References . . . . . . . . . . . . . . . . . . 27 103 Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 27 104 A.1. Example JWS using HMAC SHA-256 . . . . . . . . . . . . . . 28 105 A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 28 106 A.1.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 30 107 A.1.3. Validating . . . . . . . . . . . . . . . . . . . . . . 30 108 A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 . . . . . . . . 30 109 A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 30 110 A.2.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 33 111 A.2.3. Validating . . . . . . . . . . . . . . . . . . . . . . 33 112 A.3. Example JWS using ECDSA P-256 SHA-256 . . . . . . . . . . 33 113 A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 33 114 A.3.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 35 115 A.3.3. Validating . . . . . . . . . . . . . . . . . . . . . . 36 116 A.4. Example JWS using ECDSA P-521 SHA-512 . . . . . . . . . . 36 117 A.4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 36 118 A.4.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 38 119 A.4.3. Validating . . . . . . . . . . . . . . . . . . . . . . 38 120 A.5. Example Plaintext JWS . . . . . . . . . . . . . . . . . . 39 121 A.6. Example JWS Using JWS JSON Serialization . . . . . . . . . 40 122 A.6.1. JWS Per-Signature Protected Headers . . . . . . . . . 40 123 A.6.2. JWS Per-Signature Unprotected Headers . . . . . . . . 40 124 A.6.3. Complete JWS Header Values . . . . . . . . . . . . . . 41 125 A.6.4. Complete JWS JSON Serialization Representation . . . . 41 126 Appendix B. "x5c" (X.509 Certificate Chain) Example . . . . . . . 41 127 Appendix C. Notes on implementing base64url encoding without 128 padding . . . . . . . . . . . . . . . . . . . . . . . 43 129 Appendix D. Negative Test Case for "crit" Header Parameter . . . 44 130 Appendix E. Acknowledgements . . . . . . . . . . . . . . . . . . 45 131 Appendix F. Document History . . . . . . . . . . . . . . . . . . 45 132 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 51 134 1. Introduction 136 JSON Web Signature (JWS) is a means of representing content secured 137 with digital signatures or Message Authentication Codes (MACs) using 138 JavaScript Object Notation (JSON) [RFC4627] based data structures. 139 The JWS cryptographic mechanisms provide integrity protection for 140 arbitrary sequences of octets. 142 Two closely related representations for JWS objects are defined. The 143 JWS Compact Serialization is a compact, URL-safe representation 144 intended for space constrained environments such as HTTP 145 Authorization headers and URI query parameters. The JWS JSON 146 Serialization represents JWS objects as JSON objects and enables 147 multiple signatures and/or MACs to be applied to the same content. 148 Both share the same cryptographic underpinnings. 150 Cryptographic algorithms and identifiers for use with this 151 specification are described in the separate JSON Web Algorithms (JWA) 152 [JWA] specification. Related encryption capabilities are described 153 in the separate JSON Web Encryption (JWE) [JWE] specification. 155 1.1. Notational Conventions 157 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 158 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 159 document are to be interpreted as described in Key words for use in 160 RFCs to Indicate Requirement Levels [RFC2119]. 162 2. Terminology 164 JSON Web Signature (JWS) A data structure representing a digitally 165 signed or MACed message. The structure represents three values: 166 the JWS Header, the JWS Payload, and the JWS Signature. 168 JSON Text Object A UTF-8 [RFC3629] encoded text string representing 169 a JSON object; the syntax of JSON objects is defined in Section 170 2.2 of [RFC4627]. 172 JWS Header A JSON Text Object (or JSON Text Objects, when using the 173 JWS JSON Serialization) that describes the digital signature or 174 MAC operation applied to create the JWS Signature value. The 175 members of the JWS Header object(s) are Header Parameters. 177 JWS Payload The sequence of octets to be secured -- a.k.a., the 178 message. The payload can contain an arbitrary sequence of octets. 180 JWS Signature A sequence of octets containing the cryptographic 181 material that ensures the integrity of the JWS Protected Header 182 and the JWS Payload. The JWS Signature value is a digital 183 signature or MAC value calculated over the JWS Signing Input using 184 the parameters specified in the JWS Header. 186 JWS Protected Header A JSON Text Object that contains the portion of 187 the JWS Header that is integrity protected. For the JWS Compact 188 Serialization, this comprises the entire JWS Header. For the JWS 189 JSON Serialization, this is one component of the JWS Header. 191 Header Parameter A name/value pair that is member of the JWS Header. 193 Header Parameter Name The name of a member of the JWS Header. 195 Header Parameter Value The value of a member of the JWS Header. 197 Base64url Encoding The URL- and filename-safe Base64 encoding 198 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 199 safe) '=' padding characters omitted, as permitted by Section 3.2. 200 (See Appendix C for notes on implementing base64url encoding 201 without padding.) 203 Encoded JWS Header Base64url encoding of the JWS Protected Header. 205 Encoded JWS Payload Base64url encoding of the JWS Payload. 207 Encoded JWS Signature Base64url encoding of the JWS Signature. 209 JWS Signing Input The concatenation of the Encoded JWS Header, a 210 period ('.') character, and the Encoded JWS Payload. 212 JWS Compact Serialization A representation of the JWS as the 213 concatenation of the Encoded JWS Header, the Encoded JWS Payload, 214 and the Encoded JWS Signature in that order, with the three 215 strings being separated by two period ('.') characters. This 216 representation is compact and URL-safe. 218 JWS JSON Serialization A representation of the JWS as a JSON 219 structure containing JWS Header, Encoded JWS Payload, and Encoded 220 JWS Signature values. Unlike the JWS Compact Serialization, the 221 JWS JSON Serialization enables multiple digital signatures and/or 222 MACs to be applied to the same content. This representation is 223 neither compact nor URL-safe. 225 Collision Resistant Namespace A namespace that allows names to be 226 allocated in a manner such that they are highly unlikely to 227 collide with other names. For instance, collision resistance can 228 be achieved through administrative delegation of portions of the 229 namespace or through use of collision-resistant name allocation 230 functions. Examples of Collision Resistant Namespaces include: 231 Domain Names, Object Identifiers (OIDs) as defined in the ITU-T 232 X.660 and X.670 Recommendation series, and Universally Unique 233 IDentifiers (UUIDs) [RFC4122]. When using an administratively 234 delegated namespace, the definer of a name needs to take 235 reasonable precautions to ensure they are in control of the 236 portion of the namespace they use to define the name. 238 StringOrURI A JSON string value, with the additional requirement 239 that while arbitrary string values MAY be used, any value 240 containing a ":" character MUST be a URI [RFC3986]. StringOrURI 241 values are compared as case-sensitive strings with no 242 transformations or canonicalizations applied. 244 3. JSON Web Signature (JWS) Overview 246 JWS represents digitally signed or MACed content using JSON data 247 structures and base64url encoding. Three values are represented in a 248 JWS: the JWS Header, the JWS Payload, and the JWS Signature. In the 249 Compact Serialization, the three values are base64url-encoded for 250 transmission, and represented as the concatenation of the encoded 251 strings in that order, with the three strings being separated by two 252 period ('.') characters. A JSON Serialization for this information 253 is also defined in Section 7.2. 255 The JWS Header describes the signature or MAC method and parameters 256 employed. The JWS Payload is the message content to be secured. The 257 JWS Signature ensures the integrity of both the JWS Protected Header 258 and the JWS Payload. 260 3.1. Example JWS 262 The following example JWS Header declares that the encoded object is 263 a JSON Web Token (JWT) [JWT] and the JWS Header and the JWS Payload 264 are secured using the HMAC SHA-256 algorithm: 266 {"typ":"JWT", 267 "alg":"HS256"} 269 Base64url encoding the octets of the UTF-8 representation of the JWS 270 Header yields this Encoded JWS Header value: 272 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 274 The following is an example of a JSON object that can be used as a 275 JWS Payload. (Note that the payload can be any content, and need not 276 be a representation of a JSON object.) 278 {"iss":"joe", 279 "exp":1300819380, 280 "http://example.com/is_root":true} 282 The following octet sequence, which is the UTF-8 representation of 283 the JSON object above, is the JWS Payload: 285 [123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10, 286 32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56, 287 48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97, 288 109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111, 289 111, 116, 34, 58, 116, 114, 117, 101, 125] 291 Base64url encoding the JWS Payload yields this Encoded JWS Payload 292 (with line breaks for display purposes only): 294 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 295 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 297 Computing the HMAC of the octets of the ASCII [USASCII] 298 representation of the JWS Signing Input (the concatenation of the 299 Encoded JWS Header, a period ('.') character, and the Encoded JWS 300 Payload) with the HMAC SHA-256 algorithm using the key specified in 301 Appendix A.1 and base64url encoding the result yields this Encoded 302 JWS Signature value: 304 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 306 Concatenating these values in the order Header.Payload.Signature with 307 period ('.') characters between the parts yields this complete JWS 308 representation using the JWS Compact Serialization (with line breaks 309 for display purposes only): 311 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 312 . 313 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 314 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 315 . 316 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 318 This computation is illustrated in more detail in Appendix A.1. See 319 Appendix A for additional examples. 321 4. JWS Header 323 The members of the JSON object(s) representing the JWS Header 324 describe the digital signature or MAC applied to the Encoded JWS 325 Header and the Encoded JWS Payload and optionally additional 326 properties of the JWS. The Header Parameter Names within the JWS 327 Header MUST be unique; recipients MUST either reject JWSs with 328 duplicate Header Parameter Names or use a JSON parser that returns 329 only the lexically last duplicate member name, as specified in 330 Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript]. 332 Implementations are required to understand the specific header 333 parameters defined by this specification that are designated as "MUST 334 be understood" and process them in the manner defined in this 335 specification. All other header parameters defined by this 336 specification that are not so designated MUST be ignored when not 337 understood. Unless listed as a critical header parameter, per 338 Section 4.1.10, all header parameters not defined by this 339 specification MUST be ignored when not understood. 341 There are three classes of Header Parameter Names: Reserved Header 342 Parameter Names, Public Header Parameter Names, and Private Header 343 Parameter Names. 345 4.1. Reserved Header Parameter Names 347 The following Header Parameter Names are reserved with meanings as 348 defined below. All the names are short because a core goal of this 349 specification is for the resulting representations using the JWS 350 Compact Serialization to be compact. 352 Additional reserved Header Parameter Names can be defined via the 353 IANA JSON Web Signature and Encryption Header Parameters registry 354 Section 8.1. As indicated by the common registry, JWSs and JWEs 355 share a common header parameter space; when a parameter is used by 356 both specifications, its usage must be compatible between the 357 specifications. 359 4.1.1. "alg" (Algorithm) Header Parameter 361 The "alg" (algorithm) header parameter identifies a cryptographic 362 algorithm used to secure the JWS. The recipient MUST reject the JWS 363 if the "alg" value does not represent a supported algorithm, or if 364 there is not a key for use with that algorithm associated with the 365 party that digitally signed or MACed the content. "alg" values SHOULD 366 either be registered in the IANA JSON Web Signature and Encryption 367 Algorithms registry [JWA] or be a value that contains a Collision 368 Resistant Namespace. The "alg" value is a case sensitive string 369 containing a StringOrURI value. Use of this header parameter is 370 REQUIRED. This header parameter MUST be understood by 371 implementations. 373 A list of defined "alg" values can be found in the IANA JSON Web 374 Signature and Encryption Algorithms registry [JWA]; the initial 375 contents of this registry are the values defined in Section 3.1 of 376 the JSON Web Algorithms (JWA) [JWA] specification. 378 4.1.2. "jku" (JWK Set URL) Header Parameter 380 The "jku" (JWK Set URL) header parameter is a URI [RFC3986] that 381 refers to a resource for a set of JSON-encoded public keys, one of 382 which corresponds to the key used to digitally sign the JWS. The 383 keys MUST be encoded as a JSON Web Key Set (JWK Set) [JWK]. The 384 protocol used to acquire the resource MUST provide integrity 385 protection; an HTTP GET request to retrieve the JWK Set MUST use TLS 386 [RFC2818] [RFC5246]; the identity of the server MUST be validated, as 387 per Section 3.1 of HTTP Over TLS [RFC2818]. Use of this header 388 parameter is OPTIONAL. 390 4.1.3. "jwk" (JSON Web Key) Header Parameter 392 The "jwk" (JSON Web Key) header parameter is the public key that 393 corresponds to the key used to digitally sign the JWS. This key is 394 represented as a JSON Web Key [JWK]. Use of this header parameter is 395 OPTIONAL. 397 4.1.4. "x5u" (X.509 URL) Header Parameter 399 The "x5u" (X.509 URL) header parameter is a URI [RFC3986] that refers 400 to a resource for the X.509 public key certificate or certificate 401 chain [RFC5280] corresponding to the key used to digitally sign the 402 JWS. The identified resource MUST provide a representation of the 403 certificate or certificate chain that conforms to RFC 5280 [RFC5280] 404 in PEM encoded form [RFC1421]. The certificate containing the public 405 key corresponding to the key used to digitally sign the JWS MUST be 406 the first certificate. This MAY be followed by additional 407 certificates, with each subsequent certificate being the one used to 408 certify the previous one. The protocol used to acquire the resource 409 MUST provide integrity protection; an HTTP GET request to retrieve 410 the certificate MUST use TLS [RFC2818] [RFC5246]; the identity of the 411 server MUST be validated, as per Section 3.1 of HTTP Over TLS 412 [RFC2818]. Use of this header parameter is OPTIONAL. 414 4.1.5. "x5t" (X.509 Certificate Thumbprint) Header Parameter 416 The "x5t" (X.509 Certificate Thumbprint) header parameter is a 417 base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER 418 encoding of the X.509 certificate [RFC5280] corresponding to the key 419 used to digitally sign the JWS. Use of this header parameter is 420 OPTIONAL. 422 If, in the future, certificate thumbprints need to be computed using 423 hash functions other than SHA-1, it is suggested that additional 424 related header parameters be defined for that purpose. For example, 425 it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint 426 using SHA-256) header parameter could be defined by registering it in 427 the IANA JSON Web Signature and Encryption Header Parameters registry 428 Section 8.1. 430 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter 432 The "x5c" (X.509 Certificate Chain) header parameter contains the 433 X.509 public key certificate or certificate chain [RFC5280] 434 corresponding to the key used to digitally sign the JWS. The 435 certificate or certificate chain is represented as a JSON array of 436 certificate value strings. Each string in the array is a base64 437 encoded ([RFC4648] Section 4 -- not base64url encoded) DER 438 [ITU.X690.1994] PKIX certificate value. The certificate containing 439 the public key corresponding to the key used to digitally sign the 440 JWS MUST be the first certificate. This MAY be followed by 441 additional certificates, with each subsequent certificate being the 442 one used to certify the previous one. The recipient MUST verify the 443 certificate chain according to [RFC5280] and reject the JWS if any 444 validation failure occurs. Use of this header parameter is OPTIONAL. 446 See Appendix B for an example "x5c" value. 448 4.1.7. "kid" (Key ID) Header Parameter 450 The "kid" (key ID) header parameter is a hint indicating which key 451 was used to secure the JWS. This parameter allows originators to 452 explicitly signal a change of key to recipients. Should the 453 recipient be unable to locate a key corresponding to the "kid" value, 454 they SHOULD treat that condition as an error. The interpretation of 455 the "kid" value is unspecified. Its value MUST be a string. Use of 456 this header parameter is OPTIONAL. 458 When used with a JWK, the "kid" value can be used to match a JWK 459 "kid" parameter value. 461 4.1.8. "typ" (Type) Header Parameter 463 The "typ" (type) header parameter MAY be used to declare the type of 464 this complete JWS object in an application-specific manner in 465 contexts where this is useful to the application. This parameter has 466 no effect upon the JWS processing. The type value "JOSE" MAY be used 467 by applications to indicate that this object is a JWS or JWE using 468 the JWS Compact Serialization or the JWE Compact Serialization. The 469 type value "JOSE+JSON" MAY be used by applications to indicate that 470 this object is a JWS or JWE using the JWS JSON Serialization or the 471 JWE JSON Serialization. Other type values MAY be used, and if not 472 understood, SHOULD be ignored. The "typ" value is a case sensitive 473 string. Use of this header parameter is OPTIONAL. 475 MIME Media Type [RFC2046] values MAY be used as "typ" values. 477 "typ" values SHOULD either be registered in the IANA JSON Web 478 Signature and Encryption Type Values registry Section 8.2 or be a 479 value that contains a Collision Resistant Namespace. 481 4.1.9. "cty" (Content Type) Header Parameter 483 The "cty" (content type) header parameter MAY be used to declare the 484 type of the secured content (the payload) in an application-specific 485 manner in contexts where this is useful to the application. This 486 parameter has no effect upon the JWS processing. Content type values 487 that are not understood SHOULD be ignored. The "cty" value is a case 488 sensitive string. Use of this header parameter is OPTIONAL. 490 The values used for the "cty" header parameter come from the same 491 value space as the "typ" header parameter, with the same rules 492 applying. 494 4.1.10. "crit" (Critical) Header Parameter 496 The "crit" (critical) header parameter indicates that extensions to 497 [[ this specification ]] are being used that MUST be understood and 498 processed. Its value is an array listing the header parameter names 499 defined by those extensions that are used in the JWS Header. If any 500 of the listed extension header parameters are not understood and 501 supported by the receiver, it MUST reject the JWS. Senders MUST NOT 502 include header parameter names defined by [[ this specification ]] or 503 by [JWA] for use with JWS, duplicate names, or names that do not 504 occur as header parameter names within the JWS Header in the "crit" 505 list. Senders MUST not use the empty list "[]" as the "crit" value. 506 Recipients MAY reject the JWS if the critical list contains any 507 header parameter names defined by [[ this specification ]] or by 508 [JWA] for use with JWS, or any other constraints on its use are 509 violated. This header parameter MUST be integrity protected, and 510 therefore MUST occur only with the JWS Protected Header, when used. 511 Use of this header parameter is OPTIONAL. This header parameter MUST 512 be understood by implementations. 514 An example use, along with a hypothetical "exp" (expiration-time) 515 field is: 517 {"alg":"ES256", 518 "crit":["exp"], 519 "exp":1363284000 520 } 522 4.2. Public Header Parameter Names 524 Additional Header Parameter Names can be defined by those using JWSs. 525 However, in order to prevent collisions, any new Header Parameter 526 Name SHOULD either be registered in the IANA JSON Web Signature and 527 Encryption Header Parameters registry Section 8.1 or be a Public 528 Name: a value that contains a Collision Resistant Namespace. In each 529 case, the definer of the name or value needs to take reasonable 530 precautions to make sure they are in control of the part of the 531 namespace they use to define the Header Parameter Name. 533 New header parameters should be introduced sparingly, as they can 534 result in non-interoperable JWSs. 536 4.3. Private Header Parameter Names 538 A producer and consumer of a JWS may agree to use Header Parameter 539 Names that are Private Names: names that are not Reserved Names 540 Section 4.1 or Public Names Section 4.2. Unlike Public Names, 541 Private Names are subject to collision and should be used with 542 caution. 544 5. Producing and Consuming JWSs 546 5.1. Message Signing or MACing 548 To create a JWS, one MUST perform these steps. The order of the 549 steps is not significant in cases where there are no dependencies 550 between the inputs and outputs of the steps. 552 1. Create the content to be used as the JWS Payload. 554 2. Base64url encode the octets of the JWS Payload. This encoding 555 becomes the Encoded JWS Payload. 557 3. Create a JWS Header containing the desired set of header 558 parameters. Note that white space is explicitly allowed in the 559 representation and no canonicalization need be performed before 560 encoding. 562 4. Base64url encode the octets of the UTF-8 representation of the 563 JWS Protected Header to create the Encoded JWS Header. If the 564 JWS Protected Header is not present (which can only happen when 565 using the JWS JSON Serialization and no "protected" member is 566 present), let the Encoded JWS Header be the empty string. 568 5. Compute the JWS Signature in the manner defined for the 569 particular algorithm being used over the JWS Signing Input (the 570 concatenation of the Encoded JWS Header, a period ('.') 571 character, and the Encoded JWS Payload). The "alg" (algorithm) 572 header parameter MUST be present in the JWS Header, with the 573 algorithm value accurately representing the algorithm used to 574 construct the JWS Signature. 576 6. Base64url encode the representation of the JWS Signature to 577 create the Encoded JWS Signature. 579 7. The three encoded parts are result values used in both the JWS 580 Compact Serialization and the JWS JSON Serialization 581 representations. 583 8. If the JWS JSON Serialization is being used, repeat this process 584 for each digital signature or MAC value being applied. 586 9. Create the desired serialized output. The JWS Compact 587 Serialization of this result is the concatenation of the Encoded 588 JWS Header, the Encoded JWS Payload, and the Encoded JWS 589 Signature in that order, with the three strings being separated 590 by two period ('.') characters. The JWS JSON Serialization is 591 described in Section 7.2. 593 5.2. Message Signature or MAC Validation 595 When validating a JWS, the following steps MUST be taken. The order 596 of the steps is not significant in cases where there are no 597 dependencies between the inputs and outputs of the steps. If any of 598 the listed steps fails, then the JWS MUST be rejected. 600 1. Parse the serialized input to determine the values of the JWS 601 Header, the Encoded JWS Payload, and the Encoded JWS Signature. 602 When using the JWS Compact Serialization, the Encoded JWS 603 Header, the Encoded JWS Payload, and the Encoded JWS Signature 604 are represented as text strings in that order, separated by two 605 period ('.') characters. The JWS JSON Serialization is 606 described in Section 7.2. 608 2. The Encoded JWS Header MUST be successfully base64url decoded 609 following the restriction given in this specification that no 610 padding characters have been used. 612 3. Let the JWS Protected Header value be the result of base64url 613 decoding the Encoded JWS Header. 615 4. The resulting JWS Protected Header MUST be a completely valid 616 JSON object conforming to RFC 4627 [RFC4627]. 618 5. If using the JWS Compact Serialization, let the JWS Header be 619 the JWS Protected Header; otherwise, when using the JWS JSON 620 Serialization, let the JWS Header be the union of the members of 621 the corresponding "protected" and "header" header parameter 622 values, all of which must be completely valid JSON objects. 624 6. The resulting JWS Header MUST NOT contain duplicate Header 625 Parameter Names. When using the JWS JSON Serialization, this 626 restriction includes that the same Header Parameter Name also 627 MUST NOT occur in distinct JSON Text Object values that together 628 comprise the JWS Header. 630 7. The resulting JWS Header MUST be validated to only include 631 parameters and values whose syntax and semantics are both 632 understood and supported or that are specified as being ignored 633 when not understood. 635 8. The Encoded JWS Payload MUST be successfully base64url decoded 636 following the restriction given in this specification that no 637 padding characters have been used. 639 9. The Encoded JWS Signature MUST be successfully base64url decoded 640 following the restriction given in this specification that no 641 padding characters have been used. 643 10. The JWS Signature MUST be successfully validated against the JWS 644 Signing Input (the concatenation of the Encoded JWS Header, a 645 period ('.') character, and the Encoded JWS Payload) in the 646 manner defined for the algorithm being used, which MUST be 647 accurately represented by the value of the "alg" (algorithm) 648 header parameter, which MUST be present. 650 11. If the JWS JSON Serialization is being used, repeat this process 651 for each digital signature or MAC value contained in the 652 representation. 654 5.3. String Comparison Rules 656 Processing a JWS inevitably requires comparing known strings to 657 values in JSON objects. For example, in checking what the algorithm 658 is, the Unicode string encoding "alg" will be checked against the 659 member names in the JWS Header to see if there is a matching Header 660 Parameter Name. A similar process occurs when determining if the 661 value of the "alg" header parameter represents a supported algorithm. 663 Comparisons between JSON strings and other Unicode strings MUST be 664 performed as specified below: 666 1. Remove any JSON escaping from the input JSON string and convert 667 the string into a sequence of Unicode code points. 669 2. Likewise, convert the string to be compared against into a 670 sequence of Unicode code points. 672 3. Unicode Normalization [USA15] MUST NOT be applied at any point to 673 either the JSON string or to the string it is to be compared 674 against. 676 4. Comparisons between the two strings MUST be performed as a 677 Unicode code point to code point equality comparison. (Note that 678 values that originally used different Unicode encodings (UTF-8, 679 UTF-16, etc.) may result in the same code point values.) 681 Also, see the JSON security considerations in Section 9.2 and the 682 Unicode security considerations in Section 9.3. 684 6. Key Identification 686 It is necessary for the recipient of a JWS to be able to determine 687 the key that was employed for the digital signature or MAC operation. 688 The key employed can be identified using the Header Parameter methods 689 described in Section 4.1 or can be identified using methods that are 690 outside the scope of this specification. Specifically, the Header 691 Parameters "jku", "jwk", "x5u", "x5t", "x5c", and "kid" can be used 692 to identify the key used. The sender SHOULD include sufficient 693 information in the Header Parameters to identify the key used, unless 694 the application uses another means or convention to determine the key 695 used. Recipients MUST reject the input when the algorithm used 696 requires a key (which is true of all algorithms except for "none") 697 and the key used cannot be determined. 699 7. Serializations 701 JWS objects use one of two serializations, the JWS Compact 702 Serialization or the JWS JSON Serialization. The JWS Compact 703 Serialization is mandatory to implement. Implementation of the JWS 704 JSON Serialization is OPTIONAL. 706 7.1. JWS Compact Serialization 708 The JWS Compact Serialization represents digitally signed or MACed 709 content as a compact URL-safe string. This string is the 710 concatenation of the Encoded JWS Header, the Encoded JWS Payload, and 711 the Encoded JWS Signature in that order, with the three strings being 712 separated by two period ('.') characters. Only one signature/MAC is 713 supported by the JWS Compact Serialization. 715 7.2. JWS JSON Serialization 717 The JWS JSON Serialization represents digitally signed or MACed 718 content as a JSON object. Unlike the JWS Compact Serialization, 719 content using the JWS JSON Serialization can be secured with more 720 than one digital signature and/or MAC value. 722 The representation is closely related to that used in the JWS Compact 723 Serialization, with the following differences for the JWS JSON 724 Serialization: 726 o Values in the JWS JSON Serialization are represented as members of 727 a JSON object, rather than as base64url encoded strings separated 728 by period ('.') characters. (However binary values and values 729 that are integrity protected are still base64url encoded.) 731 o The Encoded JWS Payload value is stored in the "payload" member. 733 o There can be multiple signature and/or MAC values, rather than 734 just one. A JSON array in the "signatures" member is used to hold 735 values that are specific to a particular signature or MAC 736 computation, with one array element per signature/MAC represented. 737 These array elements are JSON objects. 739 o Each Encoded JWS Signature value, if non-empty, is stored in the 740 "signature" member of a JSON object that is an element of the 741 "signatures" array. 743 o Each Encoded JWS Header value, which is a base64url encoded set of 744 header parameter values that are included in the signature/MAC 745 computation, if non-empty, is stored in the "protected" member of 746 the corresponding element of the "signatures" array. 748 o Unlike the JWS Compact Serialization, in the JWS JSON 749 Serialization there can also be header parameter values that are 750 not included in the signature/MAC computation. If present, 751 unprotected header parameter values are represented as an 752 unencoded JSON Text Object in the "header" member of the 753 corresponding element of the "signatures" array. 755 o The header parameter values used when creating or validating 756 individual signature or MAC values are the union of the two sets 757 of header parameter values that may be present: (1) the integrity- 758 protected per-signature/MAC values represented in the "protected" 759 member of the signature/MAC's array element, and (2) the non- 760 integrity-protected per-signature/MAC values in the "header" 761 member of the signature/MAC's array element. The union of these 762 sets of header parameters comprises the JWS Header. The header 763 parameter names in the two locations MUST be disjoint. 765 The syntax of a JWS using the JWS JSON Serialization is as follows: 767 { 768 "payload":"" 769 "signatures":[ 770 {"protected":", 771 "header":"", 772 "signature":""}, 773 ... 774 {"protected":", 775 "header":"", 776 "signature":""}], 777 } 779 Of these members, only the "payload", "signatures", and "signature" 780 members MUST be present. At least one of the "protected" and 781 "header" members MUST be present for each signature/MAC computation 782 so that an "alg" header parameter value is conveyed. 784 The contents of the Encoded JWS Payload and Encoded JWS Signature 785 values are exactly as defined in the rest of this specification. 786 They are interpreted and validated in the same manner, with each 787 corresponding Encoded JWS Signature and set of header parameter 788 values being created and validated together. The JWS Header values 789 used are the union of the header parameters in the corresponding 790 "protected" and "header" members, as described earlier. 792 Each JWS Signature value is computed on the JWS Signing Input using 793 the parameters of the corresponding JWS Header value in the same 794 manner as for the JWS Compact Serialization. This has the desirable 795 property that each Encoded JWS Signature value in the "signatures" 796 array is identical to the value that would have been computed for the 797 same parameter in the JWS Compact Serialization, provided that the 798 Encoded JWS Header value for that signature/MAC computation (which 799 represents the integrity-protected header parameter values) matches 800 that used in the JWS Compact Serialization. 802 See Appendix A.6 for an example of computing a JWS using the JWS JSON 803 Serialization. 805 8. IANA Considerations 807 The following registration procedure is used for all the registries 808 established by this specification. 810 Values are registered with a Specification Required [RFC5226] after a 811 two-week review period on the [TBD]@ietf.org mailing list, on the 812 advice of one or more Designated Experts. However, to allow for the 813 allocation of values prior to publication, the Designated Expert(s) 814 may approve registration once they are satisfied that such a 815 specification will be published. 817 Registration requests must be sent to the [TBD]@ietf.org mailing list 818 for review and comment, with an appropriate subject (e.g., "Request 819 for access token type: example"). [[ Note to RFC-EDITOR: The name of 820 the mailing list should be determined in consultation with the IESG 821 and IANA. Suggested name: jose-reg-review. ]] 823 Within the review period, the Designated Expert(s) will either 824 approve or deny the registration request, communicating this decision 825 to the review list and IANA. Denials should include an explanation 826 and, if applicable, suggestions as to how to make the request 827 successful. 829 IANA must only accept registry updates from the Designated Expert(s) 830 and should direct all requests for registration to the review mailing 831 list. 833 8.1. JSON Web Signature and Encryption Header Parameters Registry 835 This specification establishes the IANA JSON Web Signature and 836 Encryption Header Parameters registry for reserved JWS and JWE Header 837 Parameter Names. The registry records the reserved Header Parameter 838 Name and a reference to the specification that defines it. The same 839 Header Parameter Name MAY be registered multiple times, provided that 840 the parameter usage is compatible between the specifications. 841 Different registrations of the same Header Parameter Name will 842 typically use different Header Parameter Usage Location(s) values. 844 8.1.1. Registration Template 846 Header Parameter Name: 847 The name requested (e.g., "example"). This name is case 848 sensitive. Names that match other registered names in a case 849 insensitive manner SHOULD NOT be accepted. 851 Header Parameter Usage Location(s): 852 The header parameter usage locations, which should be one or more 853 of the values "JWS" or "JWE". 855 Change Controller: 856 For Standards Track RFCs, state "IETF". For others, give the name 857 of the responsible party. Other details (e.g., postal address, 858 email address, home page URI) may also be included. 860 Specification Document(s): 861 Reference to the document(s) that specify the parameter, 862 preferably including URI(s) that can be used to retrieve copies of 863 the document(s). An indication of the relevant sections may also 864 be included but is not required. 866 8.1.2. Initial Registry Contents 868 This specification registers the Header Parameter Names defined in 869 Section 4.1 in this registry. 871 o Header Parameter Name: "alg" 872 o Header Parameter Usage Location(s): JWS 873 o Change Controller: IETF 874 o Specification Document(s): Section 4.1.1 of [[ this document ]] 876 o Header Parameter Name: "jku" 877 o Header Parameter Usage Location(s): JWS 878 o Change Controller: IETF 879 o Specification Document(s): Section 4.1.2 of [[ this document ]] 881 o Header Parameter Name: "jwk" 882 o Header Parameter Usage Location(s): JWS 883 o Change Controller: IETF 884 o Specification document(s): Section 4.1.3 of [[ this document ]] 886 o Header Parameter Name: "x5u" 887 o Header Parameter Usage Location(s): JWS 888 o Change Controller: IETF 889 o Specification Document(s): Section 4.1.4 of [[ this document ]] 890 o Header Parameter Name: "x5t" 891 o Header Parameter Usage Location(s): JWS 892 o Change Controller: IETF 893 o Specification Document(s): Section 4.1.5 of [[ this document ]] 895 o Header Parameter Name: "x5c" 896 o Header Parameter Usage Location(s): JWS 897 o Change Controller: IETF 898 o Specification Document(s): Section 4.1.6 of [[ this document ]] 900 o Header Parameter Name: "kid" 901 o Header Parameter Usage Location(s): JWS 902 o Change Controller: IETF 903 o Specification Document(s): Section 4.1.7 of [[ this document ]] 905 o Header Parameter Name: "typ" 906 o Header Parameter Usage Location(s): JWS 907 o Change Controller: IETF 908 o Specification Document(s): Section 4.1.8 of [[ this document ]] 910 o Header Parameter Name: "cty" 911 o Header Parameter Usage Location(s): JWS 912 o Change Controller: IETF 913 o Specification Document(s): Section 4.1.9 of [[ this document ]] 915 o Header Parameter Name: "crit" 916 o Header Parameter Usage Location(s): JWS 917 o Change Controller: IETF 918 o Specification Document(s): Section 4.1.10 of [[ this document ]] 920 8.2. JSON Web Signature and Encryption Type Values Registry 922 This specification establishes the IANA JSON Web Signature and 923 Encryption Type Values registry for values of the JWS and JWE "typ" 924 (type) header parameter. It is RECOMMENDED that all registered "typ" 925 values also include a MIME Media Type [RFC2046] value that the 926 registered value is a short name for. The registry records the "typ" 927 value, the MIME type value that it is an abbreviation for (if any), 928 and a reference to the specification that defines it. 930 MIME Media Type [RFC2046] values MUST NOT be directly registered as 931 new "typ" values; rather, new "typ" values MAY be registered as short 932 names for MIME types. 934 8.2.1. Registration Template 935 "typ" Header Parameter Value: 936 The name requested (e.g., "example"). This name is case 937 sensitive. Names that match other registered names in a case 938 insensitive manner SHOULD NOT be accepted. 940 Abbreviation for MIME Type: 941 The MIME type that this name is an abbreviation for (e.g., 942 "application/example"). 944 Change Controller: 945 For Standards Track RFCs, state "IETF". For others, give the name 946 of the responsible party. Other details (e.g., postal address, 947 email address, home page URI) may also be included. 949 Specification Document(s): 950 Reference to the document(s) that specify the parameter, 951 preferably including URI(s) that can be used to retrieve copies of 952 the document(s). An indication of the relevant sections may also 953 be included but is not required. 955 8.2.2. Initial Registry Contents 957 This specification registers the "JOSE" and "JOSE+JSON" type values 958 in this registry: 960 o "typ" Header Parameter Value: "JOSE" 961 o Abbreviation for MIME type: application/jose 962 o Change Controller: IETF 963 o Specification Document(s): Section 4.1.8 of [[ this document ]] 965 o "typ" Header Parameter Value: "JOSE+JSON" 966 o Abbreviation for MIME type: application/jose+json 967 o Change Controller: IETF 968 o Specification Document(s): Section 4.1.8 of [[ this document ]] 970 8.3. Media Type Registration 972 8.3.1. Registry Contents 974 This specification registers the "application/jose" Media Type 975 [RFC2046] in the MIME Media Type registry [RFC4288], which can be 976 used to indicate that the content is a JWS or JWE object using the 977 JWS Compact Serialization or the JWE Compact Serialization and the 978 "application/jose+json" Media Type in the MIME Media Type registry, 979 which can be used to indicate that the content is a JWS or JWE object 980 using the JWS JSON Serialization or the JWE JSON Serialization. 982 o Type name: application 983 o Subtype name: jose 984 o Required parameters: n/a 985 o Optional parameters: n/a 986 o Encoding considerations: application/jose values are encoded as a 987 series of base64url encoded values (some of which may be the empty 988 string) separated by period ('.') characters. 989 o Security considerations: See the Security Considerations section 990 of [[ this document ]] 991 o Interoperability considerations: n/a 992 o Published specification: [[ this document ]] 993 o Applications that use this media type: OpenID Connect, Mozilla 994 Persona, Salesforce, Google, numerous others that use signed JWTs 995 o Additional information: Magic number(s): n/a, File extension(s): 996 n/a, Macintosh file type code(s): n/a 997 o Person & email address to contact for further information: Michael 998 B. Jones, mbj@microsoft.com 999 o Intended usage: COMMON 1000 o Restrictions on usage: none 1001 o Author: Michael B. Jones, mbj@microsoft.com 1002 o Change Controller: IETF 1004 o Type name: application 1005 o Subtype name: jose+json 1006 o Required parameters: n/a 1007 o Optional parameters: n/a 1008 o Encoding considerations: application/jose+json values are 1009 represented as a JSON Object; UTF-8 encoding SHOULD be employed 1010 for the JSON object. 1011 o Security considerations: See the Security Considerations section 1012 of [[ this document ]] 1013 o Interoperability considerations: n/a 1014 o Published specification: [[ this document ]] 1015 o Applications that use this media type: TBD 1016 o Additional information: Magic number(s): n/a, File extension(s): 1017 n/a, Macintosh file type code(s): n/a 1018 o Person & email address to contact for further information: Michael 1019 B. Jones, mbj@microsoft.com 1020 o Intended usage: COMMON 1021 o Restrictions on usage: none 1022 o Author: Michael B. Jones, mbj@microsoft.com 1023 o Change Controller: IETF 1025 9. Security Considerations 1026 9.1. Cryptographic Security Considerations 1028 All of the security issues faced by any cryptographic application 1029 must be faced by a JWS/JWE/JWK agent. Among these issues are 1030 protecting the user's private and symmetric keys, preventing various 1031 attacks, and helping the user avoid mistakes such as inadvertently 1032 encrypting a message for the wrong recipient. The entire list of 1033 security considerations is beyond the scope of this document, but 1034 some significant concerns are listed here. 1036 All the security considerations in XML DSIG 2.0 1037 [W3C.CR-xmldsig-core2-20120124], also apply to this specification, 1038 other than those that are XML specific. Likewise, many of the best 1039 practices documented in XML Signature Best Practices 1040 [W3C.WD-xmldsig-bestpractices-20110809] also apply to this 1041 specification, other than those that are XML specific. 1043 Keys are only as strong as the amount of entropy used to generate 1044 them. A minimum of 128 bits of entropy should be used for all keys, 1045 and depending upon the application context, more may be required. In 1046 particular, it may be difficult to generate sufficiently random 1047 values in some browsers and application environments. 1049 Creators of JWSs should not allow third parties to insert arbitrary 1050 content into the message without adding entropy not controlled by the 1051 third party. 1053 When utilizing TLS to retrieve information, the authority providing 1054 the resource MUST be authenticated and the information retrieved MUST 1055 be free from modification. 1057 When cryptographic algorithms are implemented in such a way that 1058 successful operations take a different amount of time than 1059 unsuccessful operations, attackers may be able to use the time 1060 difference to obtain information about the keys employed. Therefore, 1061 such timing differences must be avoided. 1063 A SHA-1 hash is used when computing "x5t" (x.509 certificate 1064 thumbprint) values, for compatibility reasons. Should an effective 1065 means of producing SHA-1 hash collisions be developed, and should an 1066 attacker wish to interfere with the use of a known certificate on a 1067 given system, this could be accomplished by creating another 1068 certificate whose SHA-1 hash value is the same and adding it to the 1069 certificate store used by the intended victim. A prerequisite to 1070 this attack succeeding is the attacker having write access to the 1071 intended victim's certificate store. 1073 If, in the future, certificate thumbprints need to be computed using 1074 hash functions other than SHA-1, it is suggested that additional 1075 related header parameters be defined for that purpose. For example, 1076 it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint 1077 using SHA-256) header parameter could be defined and used. 1079 9.2. JSON Security Considerations 1081 Strict JSON validation is a security requirement. If malformed JSON 1082 is received, then the intent of the sender is impossible to reliably 1083 discern. Ambiguous and potentially exploitable situations could 1084 arise if the JSON parser used does not reject malformed JSON syntax. 1086 Section 2.2 of the JavaScript Object Notation (JSON) specification 1087 [RFC4627] states "The names within an object SHOULD be unique", 1088 whereas this specification states that "Header Parameter Names within 1089 this object MUST be unique; recipients MUST either reject JWSs with 1090 duplicate Header Parameter Names or use a JSON parser that returns 1091 only the lexically last duplicate member name, as specified in 1092 Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript]". 1093 Thus, this specification requires that the Section 2.2 "SHOULD" be 1094 treated as a "MUST" by senders and that it be either treated as a 1095 "MUST" or in the manner specified in ECMAScript 5.1 by receivers. 1096 Ambiguous and potentially exploitable situations could arise if the 1097 JSON parser used does not enforce the uniqueness of member names or 1098 returns an unpredictable value for duplicate member names. 1100 Some JSON parsers might not reject input that contains extra 1101 significant characters after a valid input. For instance, the input 1102 "{"tag":"value"}ABCD" contains a valid JSON object followed by the 1103 extra characters "ABCD". Such input MUST be rejected in its 1104 entirety. 1106 9.3. Unicode Comparison Security Considerations 1108 Header Parameter Names and algorithm names are Unicode strings. For 1109 security reasons, the representations of these names must be compared 1110 verbatim after performing any escape processing (as per RFC 4627 1111 [RFC4627], Section 2.5). This means, for instance, that these JSON 1112 strings must compare as being equal ("sig", "\u0073ig"), whereas 1113 these must all compare as being not equal to the first set or to each 1114 other ("SIG", "Sig", "si\u0047"). 1116 JSON strings can contain characters outside the Unicode Basic 1117 Multilingual Plane. For instance, the G clef character (U+1D11E) may 1118 be represented in a JSON string as "\uD834\uDD1E". Ideally, JWS 1119 implementations SHOULD ensure that characters outside the Basic 1120 Multilingual Plane are preserved and compared correctly; 1121 alternatively, if this is not possible due to these characters 1122 exercising limitations present in the underlying JSON implementation, 1123 then input containing them MUST be rejected. 1125 9.4. TLS Requirements 1127 Implementations MUST support TLS. Which version(s) ought to be 1128 implemented will vary over time, and depend on the widespread 1129 deployment and known security vulnerabilities at the time of 1130 implementation. At the time of this writing, TLS version 1.2 1131 [RFC5246] is the most recent version, but has very limited actual 1132 deployment, and might not be readily available in implementation 1133 toolkits. TLS version 1.0 [RFC2246] is the most widely deployed 1134 version, and will give the broadest interoperability. 1136 To protect against information disclosure and tampering, 1137 confidentiality protection MUST be applied using TLS with a 1138 ciphersuite that provides confidentiality and integrity protection. 1140 Whenever TLS is used, a TLS server certificate check MUST be 1141 performed, per RFC 6125 [RFC6125]. 1143 10. References 1145 10.1. Normative References 1147 [ECMAScript] 1148 Ecma International, "ECMAScript Language Specification, 1149 5.1 Edition", ECMA 262, June 2011. 1151 [ITU.X690.1994] 1152 International Telecommunications Union, "Information 1153 Technology - ASN.1 encoding rules: Specification of Basic 1154 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1155 Distinguished Encoding Rules (DER)", ITU-T Recommendation 1156 X.690, 1994. 1158 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1159 draft-ietf-jose-json-web-algorithms (work in progress), 1160 July 2013. 1162 [JWK] Jones, M., "JSON Web Key (JWK)", 1163 draft-ietf-jose-json-web-key (work in progress), 1164 July 2013. 1166 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 1167 Mail: Part I: Message Encryption and Authentication 1168 Procedures", RFC 1421, February 1993. 1170 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1171 Extensions (MIME) Part Two: Media Types", RFC 2046, 1172 November 1996. 1174 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1175 Requirement Levels", BCP 14, RFC 2119, March 1997. 1177 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 1178 RFC 2246, January 1999. 1180 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1182 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1183 10646", STD 63, RFC 3629, November 2003. 1185 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1186 Resource Identifier (URI): Generic Syntax", STD 66, 1187 RFC 3986, January 2005. 1189 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 1190 Registration Procedures", RFC 4288, December 2005. 1192 [RFC4627] Crockford, D., "The application/json Media Type for 1193 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1195 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1196 Encodings", RFC 4648, October 2006. 1198 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1199 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1200 May 2008. 1202 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1203 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1205 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1206 Housley, R., and W. Polk, "Internet X.509 Public Key 1207 Infrastructure Certificate and Certificate Revocation List 1208 (CRL) Profile", RFC 5280, May 2008. 1210 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1211 Verification of Domain-Based Application Service Identity 1212 within Internet Public Key Infrastructure Using X.509 1213 (PKIX) Certificates in the Context of Transport Layer 1214 Security (TLS)", RFC 6125, March 2011. 1216 [USA15] Davis, M., Whistler, K., and M. Deurst, "Unicode 1217 Normalization Forms", Unicode Standard Annex 15, 09 2009. 1219 [USASCII] American National Standards Institute, "Coded Character 1220 Set -- 7-bit American Standard Code for Information 1221 Interchange", ANSI X3.4, 1986. 1223 [W3C.WD-xmldsig-bestpractices-20110809] 1224 Datta, P. and F. Hirsch, "XML Signature Best Practices", 1225 World Wide Web Consortium WD WD-xmldsig-bestpractices- 1226 20110809, August 2011, . 1229 10.2. Informative References 1231 [CanvasApp] 1232 Facebook, "Canvas Applications", 2010. 1234 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 1235 September 2010. 1237 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 1238 Encryption (JWE)", draft-ietf-jose-json-web-encryption 1239 (work in progress), July 2013. 1241 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1242 (JWT)", draft-ietf-oauth-json-web-token (work in 1243 progress), July 2013. 1245 [MagicSignatures] 1246 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 1247 Signatures", January 2011. 1249 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1250 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1251 July 2005. 1253 [W3C.CR-xmldsig-core2-20120124] 1254 Eastlake, D., Reagle, J., Yiu, K., Solo, D., Datta, P., 1255 Hirsch, F., Cantor, S., and T. Roessler, "XML Signature 1256 Syntax and Processing Version 2.0", World Wide Web 1257 Consortium CR CR-xmldsig-core2-20120124, January 2012, 1258 . 1260 Appendix A. JWS Examples 1262 This section provides several examples of JWSs. While the first 1263 three examples all represent JSON Web Tokens (JWTs) [JWT], the 1264 payload can be any octet sequence, as shown in Appendix A.4. 1266 A.1. Example JWS using HMAC SHA-256 1268 A.1.1. Encoding 1270 The following example JWS Header declares that the data structure is 1271 a JSON Web Token (JWT) [JWT] and the JWS Signing Input is secured 1272 using the HMAC SHA-256 algorithm. 1274 {"typ":"JWT", 1275 "alg":"HS256"} 1277 The following octet sequence contains the UTF-8 representation of the 1278 JWS Header: 1280 [123, 34, 116, 121, 112, 34, 58, 34, 74, 87, 84, 34, 44, 13, 10, 32, 1281 34, 97, 108, 103, 34, 58, 34, 72, 83, 50, 53, 54, 34, 125] 1283 Base64url encoding these octets yields this Encoded JWS Header value: 1285 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 1287 The JWS Payload used in this example is the octets of the UTF-8 1288 representation of the JSON object below. (Note that the payload can 1289 be any base64url encoded octet sequence, and need not be a base64url 1290 encoded JSON object.) 1292 {"iss":"joe", 1293 "exp":1300819380, 1294 "http://example.com/is_root":true} 1296 The following octet sequence, which is the UTF-8 representation of 1297 the JSON object above, is the JWS Payload: 1299 [123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10, 1300 32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56, 1301 48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97, 1302 109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111, 1303 111, 116, 34, 58, 116, 114, 117, 101, 125] 1305 Base64url encoding the JWS Payload yields this Encoded JWS Payload 1306 value (with line breaks for display purposes only): 1308 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1309 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1311 Concatenating the Encoded JWS Header, a period ('.') character, and 1312 the Encoded JWS Payload yields this JWS Signing Input value (with 1313 line breaks for display purposes only): 1315 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 1316 . 1317 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1318 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1320 The ASCII representation of the JWS Signing Input is the following 1321 octet sequence: 1323 [101, 121, 74, 48, 101, 88, 65, 105, 79, 105, 74, 75, 86, 49, 81, 1324 105, 76, 65, 48, 75, 73, 67, 74, 104, 98, 71, 99, 105, 79, 105, 74, 1325 73, 85, 122, 73, 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 1326 77, 105, 79, 105, 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 1327 74, 108, 101, 72, 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 1328 107, 122, 79, 68, 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 1329 72, 65, 54, 76, 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 1330 109, 78, 118, 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 1331 106, 112, 48, 99, 110, 86, 108, 102, 81] 1333 HMACs are generated using keys. This example uses the symmetric key 1334 represented in JSON Web Key [JWK] format below (with line breaks for 1335 display purposes only): 1337 {"kty":"oct", 1338 "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75 1339 aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow" 1340 } 1342 Running the HMAC SHA-256 algorithm on the octets of the ASCII 1343 representation of the JWS Signing Input with this key yields this 1344 octet sequence: 1346 [116, 24, 223, 180, 151, 153, 224, 37, 79, 250, 96, 125, 216, 173, 1347 187, 186, 22, 212, 37, 77, 105, 214, 191, 240, 91, 88, 5, 88, 83, 1348 132, 141, 121] 1350 Base64url encoding the above HMAC output yields this Encoded JWS 1351 Signature value: 1353 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 1355 Concatenating these values in the order Header.Payload.Signature with 1356 period ('.') characters between the parts yields this complete JWS 1357 representation using the JWS Compact Serialization (with line breaks 1358 for display purposes only): 1360 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 1361 . 1362 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1363 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1364 . 1365 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 1367 A.1.2. Decoding 1369 Decoding the JWS requires base64url decoding the Encoded JWS Header, 1370 Encoded JWS Payload, and Encoded JWS Signature to produce the JWS 1371 Header, JWS Payload, and JWS Signature octet sequences. The octet 1372 sequence containing the UTF-8 representation of the JWS Header is 1373 decoded into the JWS Header string. 1375 A.1.3. Validating 1377 Next we validate the decoded results. Since the "alg" parameter in 1378 the header is "HS256", we validate the HMAC SHA-256 value contained 1379 in the JWS Signature. If any of the validation steps fail, the JWS 1380 MUST be rejected. 1382 First, we validate that the JWS Header string is legal JSON. 1384 To validate the HMAC value, we repeat the previous process of using 1385 the correct key and the ASCII representation of the JWS Signing Input 1386 as input to the HMAC SHA-256 function and then taking the output and 1387 determining if it matches the JWS Signature. If it matches exactly, 1388 the HMAC has been validated. 1390 A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 1392 A.2.1. Encoding 1394 The JWS Header in this example is different from the previous example 1395 in two ways: First, because a different algorithm is being used, the 1396 "alg" value is different. Second, for illustration purposes only, 1397 the optional "typ" parameter is not used. (This difference is not 1398 related to the algorithm employed.) The JWS Header used is: 1400 {"alg":"RS256"} 1402 The following octet sequence contains the UTF-8 representation of the 1403 JWS Header: 1405 [123, 34, 97, 108, 103, 34, 58, 34, 82, 83, 50, 53, 54, 34, 125] 1407 Base64url encoding these octets yields this Encoded JWS Header value: 1409 eyJhbGciOiJSUzI1NiJ9 1411 The JWS Payload used in this example, which follows, is the same as 1412 in the previous example. Since the Encoded JWS Payload will 1413 therefore be the same, its computation is not repeated here. 1415 {"iss":"joe", 1416 "exp":1300819380, 1417 "http://example.com/is_root":true} 1419 Concatenating the Encoded JWS Header, a period ('.') character, and 1420 the Encoded JWS Payload yields this JWS Signing Input value (with 1421 line breaks for display purposes only): 1423 eyJhbGciOiJSUzI1NiJ9 1424 . 1425 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1426 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1428 The ASCII representation of the JWS Signing Input is the following 1429 octet sequence: 1431 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 122, 73, 1432 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, 1433 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 74, 108, 101, 72, 1434 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 107, 122, 79, 68, 1435 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 72, 65, 54, 76, 1436 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 109, 78, 118, 1437 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48, 1438 99, 110, 86, 108, 102, 81] 1440 This example uses the RSA key represented in JSON Web Key [JWK] 1441 format below (with line breaks for display purposes only): 1443 {"kty":"RSA", 1444 "n":"ofgWCuLjybRlzo0tZWJjNiuSfb4p4fAkd_wWJcyQoTbji9k0l8W26mPddx 1445 HmfHQp-Vaw-4qPCJrcS2mJPMEzP1Pt0Bm4d4QlL-yRT-SFd2lZS-pCgNMs 1446 D1W_YpRPEwOWvG6b32690r2jZ47soMZo9wGzjb_7OMg0LOL-bSf63kpaSH 1447 SXndS5z5rexMdbBYUsLA9e-KXBdQOS-UTo7WTBEMa2R2CapHg665xsmtdV 1448 MTBQY4uDZlxvb3qCo5ZwKh9kG4LT6_I5IhlJH7aGhyxXFvUK-DWNmoudF8 1449 NAco9_h9iaGNj8q2ethFkMLs91kzk2PAcDTW9gb54h4FRWyuXpoQ", 1450 "e":"AQAB", 1451 "d":"Eq5xpGnNCivDflJsRQBXHx1hdR1k6Ulwe2JZD50LpXyWPEAeP88vLNO97I 1452 jlA7_GQ5sLKMgvfTeXZx9SE-7YwVol2NXOoAJe46sui395IW_GO-pWJ1O0 1453 BkTGoVEn2bKVRUCgu-GjBVaYLU6f3l9kJfFNS3E0QbVdxzubSu3Mkqzjkn 1454 439X0M_V51gfpRLI9JYanrC4D4qAdGcopV_0ZHHzQlBjudU2QvXt4ehNYT 1455 CBr6XCLQUShb1juUO1ZdiYoFaFQT5Tw8bGUl_x_jTj3ccPDVZFD9pIuhLh 1456 BOneufuBiB4cS98l2SR_RQyGWSeWjnczT0QU91p1DhOVRuOopznQ" 1458 } 1460 The RSA private key is then passed to the RSA signing function, which 1461 also takes the hash type, SHA-256, and the octets of the ASCII 1462 representation of the JWS Signing Input as inputs. The result of the 1463 digital signature is an octet sequence, which represents a big endian 1464 integer. In this example, it is: 1466 [112, 46, 33, 137, 67, 232, 143, 209, 30, 181, 216, 45, 191, 120, 69, 1467 243, 65, 6, 174, 27, 129, 255, 247, 115, 17, 22, 173, 209, 113, 125, 1468 131, 101, 109, 66, 10, 253, 60, 150, 238, 221, 115, 162, 102, 62, 81, 1469 102, 104, 123, 0, 11, 135, 34, 110, 1, 135, 237, 16, 115, 249, 69, 1470 229, 130, 173, 252, 239, 22, 216, 90, 121, 142, 232, 198, 109, 219, 1471 61, 184, 151, 91, 23, 208, 148, 2, 190, 237, 213, 217, 217, 112, 7, 1472 16, 141, 178, 129, 96, 213, 248, 4, 12, 167, 68, 87, 98, 184, 31, 1473 190, 127, 249, 217, 46, 10, 231, 111, 36, 242, 91, 51, 187, 230, 244, 1474 74, 230, 30, 177, 4, 10, 203, 32, 4, 77, 62, 249, 18, 142, 212, 1, 1475 48, 121, 91, 212, 189, 59, 65, 238, 202, 208, 102, 171, 101, 25, 129, 1476 253, 228, 141, 247, 127, 55, 45, 195, 139, 159, 175, 221, 59, 239, 1477 177, 139, 93, 163, 204, 60, 46, 176, 47, 158, 58, 65, 214, 18, 202, 1478 173, 21, 145, 18, 115, 160, 95, 35, 185, 232, 56, 250, 175, 132, 157, 1479 105, 132, 41, 239, 90, 30, 136, 121, 130, 54, 195, 212, 14, 96, 69, 1480 34, 165, 68, 200, 242, 122, 122, 45, 184, 6, 99, 209, 108, 247, 202, 1481 234, 86, 222, 64, 92, 178, 33, 90, 69, 178, 194, 85, 102, 181, 90, 1482 193, 167, 72, 160, 112, 223, 200, 163, 42, 70, 149, 67, 208, 25, 238, 1483 251, 71] 1485 Base64url encoding the digital signature produces this value for the 1486 Encoded JWS Signature (with line breaks for display purposes only): 1488 cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7 1489 AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4 1490 BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K 1491 0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqv 1492 hJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrB 1493 p0igcN_IoypGlUPQGe77Rw 1495 Concatenating these values in the order Header.Payload.Signature with 1496 period ('.') characters between the parts yields this complete JWS 1497 representation using the JWS Compact Serialization (with line breaks 1498 for display purposes only): 1500 eyJhbGciOiJSUzI1NiJ9 1501 . 1502 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1503 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1504 . 1505 cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7 1506 AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4 1507 BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K 1508 0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqv 1509 hJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrB 1510 p0igcN_IoypGlUPQGe77Rw 1512 A.2.2. Decoding 1514 Decoding the JWS requires base64url decoding the Encoded JWS Header, 1515 Encoded JWS Payload, and Encoded JWS Signature to produce the JWS 1516 Header, JWS Payload, and JWS Signature octet sequences. The octet 1517 sequence containing the UTF-8 representation of the JWS Header is 1518 decoded into the JWS Header string. 1520 A.2.3. Validating 1522 Since the "alg" parameter in the header is "RS256", we validate the 1523 RSASSA-PKCS-v1_5 SHA-256 digital signature contained in the JWS 1524 Signature. If any of the validation steps fail, the JWS MUST be 1525 rejected. 1527 First, we validate that the JWS Header string is legal JSON. 1529 Validating the JWS Signature is a little different from the previous 1530 example. First, we base64url decode the Encoded JWS Signature to 1531 produce a digital signature S to check. We then pass (n, e), S and 1532 the octets of the ASCII representation of the JWS Signing Input to an 1533 RSASSA-PKCS-v1_5 signature verifier that has been configured to use 1534 the SHA-256 hash function. 1536 A.3. Example JWS using ECDSA P-256 SHA-256 1538 A.3.1. Encoding 1540 The JWS Header for this example differs from the previous example 1541 because a different algorithm is being used. The JWS Header used is: 1543 {"alg":"ES256"} 1545 The following octet sequence contains the UTF-8 representation of the 1546 JWS Header: 1548 [123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 50, 53, 54, 34, 125] 1550 Base64url encoding these octets yields this Encoded JWS Header value: 1552 eyJhbGciOiJFUzI1NiJ9 1554 The JWS Payload used in this example, which follows, is the same as 1555 in the previous examples. Since the Encoded JWS Payload will 1556 therefore be the same, its computation is not repeated here. 1558 {"iss":"joe", 1559 "exp":1300819380, 1560 "http://example.com/is_root":true} 1562 Concatenating the Encoded JWS Header, a period ('.') character, and 1563 the Encoded JWS Payload yields this JWS Signing Input value (with 1564 line breaks for display purposes only): 1566 eyJhbGciOiJFUzI1NiJ9 1567 . 1568 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1569 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1571 The ASCII representation of the JWS Signing Input is the following 1572 octet sequence: 1574 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 70, 85, 122, 73, 1575 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, 1576 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 74, 108, 101, 72, 1577 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 107, 122, 79, 68, 1578 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 72, 65, 54, 76, 1579 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 109, 78, 118, 1580 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48, 1581 99, 110, 86, 108, 102, 81] 1583 This example uses the elliptic curve key represented in JSON Web Key 1584 [JWK] format below: 1586 {"kty":"EC", 1587 "crv":"P-256", 1588 "x":"f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU", 1589 "y":"x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0", 1590 "d":"jpsQnnGQmL-YBIffH1136cspYG6-0iY7X1fCE9-E9LI" 1591 } 1593 The ECDSA private part d is then passed to an ECDSA signing function, 1594 which also takes the curve type, P-256, the hash type, SHA-256, and 1595 the octets of the ASCII representation of the JWS Signing Input as 1596 inputs. The result of the digital signature is the EC point (R, S), 1597 where R and S are unsigned integers. In this example, the R and S 1598 values, given as octet sequences representing big endian integers 1599 are: 1601 +--------+----------------------------------------------------------+ 1602 | Result | Value | 1603 | Name | | 1604 +--------+----------------------------------------------------------+ 1605 | R | [14, 209, 33, 83, 121, 99, 108, 72, 60, 47, 127, 21, 88, | 1606 | | 7, 212, 2, 163, 178, 40, 3, 58, 249, 124, 126, 23, 129, | 1607 | | 154, 195, 22, 158, 166, 101] | 1608 | S | [197, 10, 7, 211, 140, 60, 112, 229, 216, 241, 45, 175, | 1609 | | 8, 74, 84, 128, 166, 101, 144, 197, 242, 147, 80, 154, | 1610 | | 143, 63, 127, 138, 131, 163, 84, 213] | 1611 +--------+----------------------------------------------------------+ 1613 Concatenating the S array to the end of the R array and base64url 1614 encoding the result produces this value for the Encoded JWS Signature 1615 (with line breaks for display purposes only): 1617 DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSA 1618 pmWQxfKTUJqPP3-Kg6NU1Q 1620 Concatenating these values in the order Header.Payload.Signature with 1621 period ('.') characters between the parts yields this complete JWS 1622 representation using the JWS Compact Serialization (with line breaks 1623 for display purposes only): 1625 eyJhbGciOiJFUzI1NiJ9 1626 . 1627 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1628 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1629 . 1630 DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSA 1631 pmWQxfKTUJqPP3-Kg6NU1Q 1633 A.3.2. Decoding 1635 Decoding the JWS requires base64url decoding the Encoded JWS Header, 1636 Encoded JWS Payload, and Encoded JWS Signature to produce the JWS 1637 Header, JWS Payload, and JWS Signature octet sequences. The octet 1638 sequence containing the UTF-8 representation of the JWS Header is 1639 decoded into the JWS Header string. 1641 A.3.3. Validating 1643 Since the "alg" parameter in the header is "ES256", we validate the 1644 ECDSA P-256 SHA-256 digital signature contained in the JWS Signature. 1645 If any of the validation steps fail, the JWS MUST be rejected. 1647 First, we validate that the JWS Header string is legal JSON. 1649 Validating the JWS Signature is a little different from the first 1650 example. First, we base64url decode the Encoded JWS Signature as in 1651 the previous examples but we then need to split the 64 member octet 1652 sequence that must result into two 32 octet sequences, the first R 1653 and the second S. We then pass (x, y), (R, S) and the octets of the 1654 ASCII representation of the JWS Signing Input to an ECDSA signature 1655 verifier that has been configured to use the P-256 curve with the 1656 SHA-256 hash function. 1658 As explained in Section 3.4 of the JSON Web Algorithms (JWA) [JWA] 1659 specification, the use of the K value in ECDSA means that we cannot 1660 validate the correctness of the digital signature in the same way we 1661 validated the correctness of the HMAC. Instead, implementations MUST 1662 use an ECDSA validator to validate the digital signature. 1664 A.4. Example JWS using ECDSA P-521 SHA-512 1666 A.4.1. Encoding 1668 The JWS Header for this example differs from the previous example 1669 because different ECDSA curves and hash functions are used. The JWS 1670 Header used is: 1672 {"alg":"ES512"} 1674 The following octet sequence contains the UTF-8 representation of the 1675 JWS Header: 1677 [123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 53, 49, 50, 34, 125] 1679 Base64url encoding these octets yields this Encoded JWS Header value: 1681 eyJhbGciOiJFUzUxMiJ9 1683 The JWS Payload used in this example, is the ASCII string "Payload". 1684 The representation of this string is the octet sequence: 1686 [80, 97, 121, 108, 111, 97, 100] 1688 Base64url encoding these octets yields this Encoded JWS Payload 1689 value: 1691 UGF5bG9hZA 1693 Concatenating the Encoded JWS Header, a period ('.') character, and 1694 the Encoded JWS Payload yields this JWS Signing Input value: 1696 eyJhbGciOiJFUzUxMiJ9.UGF5bG9hZA 1698 The ASCII representation of the JWS Signing Input is the following 1699 octet sequence: 1701 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 70, 85, 122, 85, 1702 120, 77, 105, 74, 57, 46, 85, 71, 70, 53, 98, 71, 57, 104, 90, 65] 1704 This example uses the elliptic curve key represented in JSON Web Key 1705 [JWK] format below (with line breaks for display purposes only): 1707 {"kty":"EC", 1708 "crv":"P-521", 1709 "x":"AekpBQ8ST8a8VcfVOTNl353vSrDCLLJXmPk06wTjxrrjcBpXp5EOnYG_ 1710 NjFZ6OvLFV1jSfS9tsz4qUxcWceqwQGk", 1711 "y":"ADSmRA43Z1DSNx_RvcLI87cdL07l6jQyyBXMoxVg_l2Th-x3S1WDhjDl 1712 y79ajL4Kkd0AZMaZmh9ubmf63e3kyMj2", 1713 "d":"AY5pb7A0UFiB3RELSD64fTLOSV_jazdF7fLYyuTw8lOfRhWg6Y6rUrPA 1714 xerEzgdRhajnu0ferB0d53vM9mE15j2C" 1715 } 1717 The ECDSA private part d is then passed to an ECDSA signing function, 1718 which also takes the curve type, P-521, the hash type, SHA-512, and 1719 the octets of the ASCII representation of the JWS Signing Input as 1720 inputs. The result of the digital signature is the EC point (R, S), 1721 where R and S are unsigned integers. In this example, the R and S 1722 values, given as octet sequences representing big endian integers 1723 are: 1725 +--------+----------------------------------------------------------+ 1726 | Result | Value | 1727 | Name | | 1728 +--------+----------------------------------------------------------+ 1729 | R | [1, 220, 12, 129, 231, 171, 194, 209, 232, 135, 233, | 1730 | | 117, 247, 105, 122, 210, 26, 125, 192, 1, 217, 21, 82, | 1731 | | 91, 45, 240, 255, 83, 19, 34, 239, 71, 48, 157, 147, | 1732 | | 152, 105, 18, 53, 108, 163, 214, 68, 231, 62, 153, 150, | 1733 | | 106, 194, 164, 246, 72, 143, 138, 24, 50, 129, 223, 133, | 1734 | | 206, 209, 172, 63, 237, 119, 109] | 1735 | S | [0, 111, 6, 105, 44, 5, 41, 208, 128, 61, 152, 40, 92, | 1736 | | 61, 152, 4, 150, 66, 60, 69, 247, 196, 170, 81, 193, | 1737 | | 199, 78, 59, 194, 169, 16, 124, 9, 143, 42, 142, 131, | 1738 | | 48, 206, 238, 34, 175, 83, 203, 220, 159, 3, 107, 155, | 1739 | | 22, 27, 73, 111, 68, 68, 21, 238, 144, 229, 232, 148, | 1740 | | 188, 222, 59, 242, 103] | 1741 +--------+----------------------------------------------------------+ 1743 Concatenating the S array to the end of the R array and base64url 1744 encoding the result produces this value for the Encoded JWS Signature 1745 (with line breaks for display purposes only): 1747 AdwMgeerwtHoh-l192l60hp9wAHZFVJbLfD_UxMi70cwnZOYaRI1bKPWROc-mZZq 1748 wqT2SI-KGDKB34XO0aw_7XdtAG8GaSwFKdCAPZgoXD2YBJZCPEX3xKpRwcdOO8Kp 1749 EHwJjyqOgzDO7iKvU8vcnwNrmxYbSW9ERBXukOXolLzeO_Jn 1751 Concatenating these values in the order Header.Payload.Signature with 1752 period ('.') characters between the parts yields this complete JWS 1753 representation using the JWS Compact Serialization (with line breaks 1754 for display purposes only): 1756 eyJhbGciOiJFUzUxMiJ9 1757 . 1758 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1759 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1760 . 1761 AdwMgeerwtHoh-l192l60hp9wAHZFVJbLfD_UxMi70cwnZOYaRI1bKPWROc-mZZq 1762 wqT2SI-KGDKB34XO0aw_7XdtAG8GaSwFKdCAPZgoXD2YBJZCPEX3xKpRwcdOO8Kp 1763 EHwJjyqOgzDO7iKvU8vcnwNrmxYbSW9ERBXukOXolLzeO_Jn 1765 A.4.2. Decoding 1767 Decoding the JWS requires base64url decoding the Encoded JWS Header, 1768 Encoded JWS Payload, and Encoded JWS Signature to produce the JWS 1769 Header, JWS Payload, and JWS Signature octet sequences. The octet 1770 sequence containing the UTF-8 representation of the JWS Header is 1771 decoded into the JWS Header string. 1773 A.4.3. Validating 1775 Since the "alg" parameter in the header is "ES512", we validate the 1776 ECDSA P-521 SHA-512 digital signature contained in the JWS Signature. 1777 If any of the validation steps fail, the JWS MUST be rejected. 1779 First, we validate that the JWS Header string is legal JSON. 1781 Validating the JWS Signature is similar to the previous example. 1782 First, we base64url decode the Encoded JWS Signature as in the 1783 previous examples but we then need to split the 132 member octet 1784 sequence that must result into two 66 octet sequences, the first R 1785 and the second S. We then pass (x, y), (R, S) and the octets of the 1786 ASCII representation of the JWS Signing Input to an ECDSA signature 1787 verifier that has been configured to use the P-521 curve with the 1788 SHA-512 hash function. 1790 As explained in Section 3.4 of the JSON Web Algorithms (JWA) [JWA] 1791 specification, the use of the K value in ECDSA means that we cannot 1792 validate the correctness of the digital signature in the same way we 1793 validated the correctness of the HMAC. Instead, implementations MUST 1794 use an ECDSA validator to validate the digital signature. 1796 A.5. Example Plaintext JWS 1798 The following example JWS Header declares that the encoded object is 1799 a Plaintext JWS: 1801 {"alg":"none"} 1803 Base64url encoding the octets of the UTF-8 representation of the JWS 1804 Header yields this Encoded JWS Header: 1806 eyJhbGciOiJub25lIn0 1808 The JWS Payload used in this example, which follows, is the same as 1809 in the previous examples. Since the Encoded JWS Payload will 1810 therefore be the same, its computation is not repeated here. 1812 {"iss":"joe", 1813 "exp":1300819380, 1814 "http://example.com/is_root":true} 1816 The Encoded JWS Signature is the empty string. 1818 Concatenating these parts in the order Header.Payload.Signature with 1819 period ('.') characters between the parts yields this complete JWS 1820 (with line breaks for display purposes only): 1822 eyJhbGciOiJub25lIn0 1823 . 1824 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1825 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1826 . 1828 A.6. Example JWS Using JWS JSON Serialization 1830 This section contains an example using the JWS JSON Serialization. 1831 This example demonstrates the capability for conveying multiple 1832 digital signatures and/or MACs for the same payload. 1834 The Encoded JWS Payload used in this example is the same as that used 1835 in the examples in Appendix A.2 and Appendix A.3 (with line breaks 1836 for display purposes only): 1838 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1839 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1841 Two digital signatures are used in this example: the first using 1842 RSASSA-PKCS-v1_5 SHA-256 and the second using ECDSA P-256 SHA-256. 1843 For the first, the JWS Protected Header and key are the same as in 1844 Appendix A.2, resulting in the same JWS Signature value; therefore, 1845 its computation is not repeated here. For the second, the JWS 1846 Protected Header and key are the same as in Appendix A.3, resulting 1847 in the same JWS Signature value; therefore, its computation is not 1848 repeated here. 1850 A.6.1. JWS Per-Signature Protected Headers 1852 The JWS Protected Header value used for the first signature is: 1854 {"alg":"RS256"} 1856 Base64url encoding these octets yields this Encoded JWS Header value: 1858 eyJhbGciOiJSUzI1NiJ9 1860 The JWS Protected Header value used for the second signature is: 1862 {"alg":"ES256"} 1864 Base64url encoding these octets yields this Encoded JWS Header value: 1866 eyJhbGciOiJFUzI1NiJ9 1868 A.6.2. JWS Per-Signature Unprotected Headers 1870 Key ID values are supplied for both keys using per-signature header 1871 parameters. The two values used to represent these Key IDs are: 1873 {"kid":"2010-12-29"} 1875 and: 1877 {"kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"} 1879 A.6.3. Complete JWS Header Values 1881 Combining the protected and unprotected header values supplied, the 1882 JWS Header values used for the first and second signatures 1883 respectively are: 1885 {"alg":"RS256", 1886 "kid":"2010-12-29"} 1888 and: 1890 {"alg":"ES256", 1891 "kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"} 1893 A.6.4. Complete JWS JSON Serialization Representation 1895 The complete JSON Web Signature JSON Serialization for these values 1896 is as follows (with line breaks for display purposes only): 1898 {"payload": 1899 "eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGF 1900 tcGxlLmNvbS9pc19yb290Ijp0cnVlfQ", 1901 "signatures":[ 1902 {"protected":"eyJhbGciOiJSUzI1NiJ9", 1903 "header": 1904 {"kid":"2010-12-29"}, 1905 "signature": 1906 "cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZ 1907 mh7AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjb 1908 KBYNX4BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHl 1909 b1L07Qe7K0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZES 1910 c6BfI7noOPqvhJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AX 1911 LIhWkWywlVmtVrBp0igcN_IoypGlUPQGe77Rw"}, 1912 {"protected":"eyJhbGciOiJFUzI1NiJ9", 1913 "header": 1914 {"kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"}, 1915 "signature": 1916 "DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8IS 1917 lSApmWQxfKTUJqPP3-Kg6NU1Q"}] 1918 } 1920 Appendix B. "x5c" (X.509 Certificate Chain) Example 1922 The JSON array below is an example of a certificate chain that could 1923 be used as the value of an "x5c" (X.509 Certificate Chain) header 1924 parameter, per Section 4.1.6. Note that since these strings contain 1925 base64 encoded (not base64url encoded) values, they are allowed to 1926 contain white space and line breaks. 1928 ["MIIE3jCCA8agAwIBAgICAwEwDQYJKoZIhvcNAQEFBQAwYzELMAkGA1UEBhMCVVM 1929 xITAfBgNVBAoTGFRoZSBHbyBEYWRkeSBHcm91cCwgSW5jLjExMC8GA1UECxMoR2 1930 8gRGFkZHkgQ2xhc3MgMiBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTAeFw0wNjExM 1931 TYwMTU0MzdaFw0yNjExMTYwMTU0MzdaMIHKMQswCQYDVQQGEwJVUzEQMA4GA1UE 1932 CBMHQXJpem9uYTETMBEGA1UEBxMKU2NvdHRzZGFsZTEaMBgGA1UEChMRR29EYWR 1933 keS5jb20sIEluYy4xMzAxBgNVBAsTKmh0dHA6Ly9jZXJ0aWZpY2F0ZXMuZ29kYW 1934 RkeS5jb20vcmVwb3NpdG9yeTEwMC4GA1UEAxMnR28gRGFkZHkgU2VjdXJlIENlc 1935 nRpZmljYXRpb24gQXV0aG9yaXR5MREwDwYDVQQFEwgwNzk2OTI4NzCCASIwDQYJ 1936 KoZIhvcNAQEBBQADggEPADCCAQoCggEBAMQt1RWMnCZM7DI161+4WQFapmGBWTt 1937 wY6vj3D3HKrjJM9N55DrtPDAjhI6zMBS2sofDPZVUBJ7fmd0LJR4h3mUpfjWoqV 1938 Tr9vcyOdQmVZWt7/v+WIbXnvQAjYwqDL1CBM6nPwT27oDyqu9SoWlm2r4arV3aL 1939 GbqGmu75RpRSgAvSMeYddi5Kcju+GZtCpyz8/x4fKL4o/K1w/O5epHBp+YlLpyo 1940 7RJlbmr2EkRTcDCVw5wrWCs9CHRK8r5RsL+H0EwnWGu1NcWdrxcx+AuP7q2BNgW 1941 JCJjPOq8lh8BJ6qf9Z/dFjpfMFDniNoW1fho3/Rb2cRGadDAW/hOUoz+EDU8CAw 1942 EAAaOCATIwggEuMB0GA1UdDgQWBBT9rGEyk2xF1uLuhV+auud2mWjM5zAfBgNVH 1943 SMEGDAWgBTSxLDSkdRMEXGzYcs9of7dqGrU4zASBgNVHRMBAf8ECDAGAQH/AgEA 1944 MDMGCCsGAQUFBwEBBCcwJTAjBggrBgEFBQcwAYYXaHR0cDovL29jc3AuZ29kYWR 1945 keS5jb20wRgYDVR0fBD8wPTA7oDmgN4Y1aHR0cDovL2NlcnRpZmljYXRlcy5nb2 1946 RhZGR5LmNvbS9yZXBvc2l0b3J5L2dkcm9vdC5jcmwwSwYDVR0gBEQwQjBABgRVH 1947 SAAMDgwNgYIKwYBBQUHAgEWKmh0dHA6Ly9jZXJ0aWZpY2F0ZXMuZ29kYWRkeS5j 1948 b20vcmVwb3NpdG9yeTAOBgNVHQ8BAf8EBAMCAQYwDQYJKoZIhvcNAQEFBQADggE 1949 BANKGwOy9+aG2Z+5mC6IGOgRQjhVyrEp0lVPLN8tESe8HkGsz2ZbwlFalEzAFPI 1950 UyIXvJxwqoJKSQ3kbTJSMUA2fCENZvD117esyfxVgqwcSeIaha86ykRvOe5GPLL 1951 5CkKSkB2XIsKd83ASe8T+5o0yGPwLPk9Qnt0hCqU7S+8MxZC9Y7lhyVJEnfzuz9 1952 p0iRFEUOOjZv2kWzRaJBydTXRE4+uXR21aITVSzGh6O1mawGhId/dQb8vxRMDsx 1953 uxN89txJx9OjxUUAiKEngHUuHqDTMBqLdElrRhjZkAzVvb3du6/KFUJheqwNTrZ 1954 EjYx8WnM25sgVjOuH0aBsXBTWVU+4=", 1955 "MIIE+zCCBGSgAwIBAgICAQ0wDQYJKoZIhvcNAQEFBQAwgbsxJDAiBgNVBAcTG1Z 1956 hbGlDZXJ0IFZhbGlkYXRpb24gTmV0d29yazEXMBUGA1UEChMOVmFsaUNlcnQsIE 1957 luYy4xNTAzBgNVBAsTLFZhbGlDZXJ0IENsYXNzIDIgUG9saWN5IFZhbGlkYXRpb 1958 24gQXV0aG9yaXR5MSEwHwYDVQQDExhodHRwOi8vd3d3LnZhbGljZXJ0LmNvbS8x 1959 IDAeBgkqhkiG9w0BCQEWEWluZm9AdmFsaWNlcnQuY29tMB4XDTA0MDYyOTE3MDY 1960 yMFoXDTI0MDYyOTE3MDYyMFowYzELMAkGA1UEBhMCVVMxITAfBgNVBAoTGFRoZS 1961 BHbyBEYWRkeSBHcm91cCwgSW5jLjExMC8GA1UECxMoR28gRGFkZHkgQ2xhc3MgM 1962 iBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTCCASAwDQYJKoZIhvcNAQEBBQADggEN 1963 ADCCAQgCggEBAN6d1+pXGEmhW+vXX0iG6r7d/+TvZxz0ZWizV3GgXne77ZtJ6XC 1964 APVYYYwhv2vLM0D9/AlQiVBDYsoHUwHU9S3/Hd8M+eKsaA7Ugay9qK7HFiH7Eux 1965 6wwdhFJ2+qN1j3hybX2C32qRe3H3I2TqYXP2WYktsqbl2i/ojgC95/5Y0V4evLO 1966 tXiEqITLdiOr18SPaAIBQi2XKVlOARFmR6jYGB0xUGlcmIbYsUfb18aQr4CUWWo 1967 riMYavx4A6lNf4DD+qta/KFApMoZFv6yyO9ecw3ud72a9nmYvLEHZ6IVDd2gWMZ 1968 Eewo+YihfukEHU1jPEX44dMX4/7VpkI+EdOqXG68CAQOjggHhMIIB3TAdBgNVHQ 1969 4EFgQU0sSw0pHUTBFxs2HLPaH+3ahq1OMwgdIGA1UdIwSByjCBx6GBwaSBvjCBu 1970 zEkMCIGA1UEBxMbVmFsaUNlcnQgVmFsaWRhdGlvbiBOZXR3b3JrMRcwFQYDVQQK 1971 Ew5WYWxpQ2VydCwgSW5jLjE1MDMGA1UECxMsVmFsaUNlcnQgQ2xhc3MgMiBQb2x 1972 pY3kgVmFsaWRhdGlvbiBBdXRob3JpdHkxITAfBgNVBAMTGGh0dHA6Ly93d3cudm 1973 FsaWNlcnQuY29tLzEgMB4GCSqGSIb3DQEJARYRaW5mb0B2YWxpY2VydC5jb22CA 1974 QEwDwYDVR0TAQH/BAUwAwEB/zAzBggrBgEFBQcBAQQnMCUwIwYIKwYBBQUHMAGG 1975 F2h0dHA6Ly9vY3NwLmdvZGFkZHkuY29tMEQGA1UdHwQ9MDswOaA3oDWGM2h0dHA 1976 6Ly9jZXJ0aWZpY2F0ZXMuZ29kYWRkeS5jb20vcmVwb3NpdG9yeS9yb290LmNybD 1977 BLBgNVHSAERDBCMEAGBFUdIAAwODA2BggrBgEFBQcCARYqaHR0cDovL2NlcnRpZ 1978 mljYXRlcy5nb2RhZGR5LmNvbS9yZXBvc2l0b3J5MA4GA1UdDwEB/wQEAwIBBjAN 1979 BgkqhkiG9w0BAQUFAAOBgQC1QPmnHfbq/qQaQlpE9xXUhUaJwL6e4+PrxeNYiY+ 1980 Sn1eocSxI0YGyeR+sBjUZsE4OWBsUs5iB0QQeyAfJg594RAoYC5jcdnplDQ1tgM 1981 QLARzLrUc+cb53S8wGd9D0VmsfSxOaFIqII6hR8INMqzW/Rn453HWkrugp++85j 1982 09VZw==", 1983 "MIIC5zCCAlACAQEwDQYJKoZIhvcNAQEFBQAwgbsxJDAiBgNVBAcTG1ZhbGlDZXJ 1984 0IFZhbGlkYXRpb24gTmV0d29yazEXMBUGA1UEChMOVmFsaUNlcnQsIEluYy4xNT 1985 AzBgNVBAsTLFZhbGlDZXJ0IENsYXNzIDIgUG9saWN5IFZhbGlkYXRpb24gQXV0a 1986 G9yaXR5MSEwHwYDVQQDExhodHRwOi8vd3d3LnZhbGljZXJ0LmNvbS8xIDAeBgkq 1987 hkiG9w0BCQEWEWluZm9AdmFsaWNlcnQuY29tMB4XDTk5MDYyNjAwMTk1NFoXDTE 1988 5MDYyNjAwMTk1NFowgbsxJDAiBgNVBAcTG1ZhbGlDZXJ0IFZhbGlkYXRpb24gTm 1989 V0d29yazEXMBUGA1UEChMOVmFsaUNlcnQsIEluYy4xNTAzBgNVBAsTLFZhbGlDZ 1990 XJ0IENsYXNzIDIgUG9saWN5IFZhbGlkYXRpb24gQXV0aG9yaXR5MSEwHwYDVQQD 1991 ExhodHRwOi8vd3d3LnZhbGljZXJ0LmNvbS8xIDAeBgkqhkiG9w0BCQEWEWluZm9 1992 AdmFsaWNlcnQuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDOOnHK5a 1993 vIWZJV16vYdA757tn2VUdZZUcOBVXc65g2PFxTXdMwzzjsvUGJ7SVCCSRrCl6zf 1994 N1SLUzm1NZ9WlmpZdRJEy0kTRxQb7XBhVQ7/nHk01xC+YDgkRoKWzk2Z/M/VXwb 1995 P7RfZHM047QSv4dk+NoS/zcnwbNDu+97bi5p9wIDAQABMA0GCSqGSIb3DQEBBQU 1996 AA4GBADt/UG9vUJSZSWI4OB9L+KXIPqeCgfYrx+jFzug6EILLGACOTb2oWH+heQ 1997 C1u+mNr0HZDzTuIYEZoDJJKPTEjlbVUjP9UNV+mWwD5MlM/Mtsq2azSiGM5bUMM 1998 j4QssxsodyamEwCW/POuZ6lcg5Ktz885hZo+L7tdEy8W9ViH0Pd"] 2000 Appendix C. Notes on implementing base64url encoding without padding 2002 This appendix describes how to implement base64url encoding and 2003 decoding functions without padding based upon standard base64 2004 encoding and decoding functions that do use padding. 2006 To be concrete, example C# code implementing these functions is shown 2007 below. Similar code could be used in other languages. 2009 static string base64urlencode(byte [] arg) 2010 { 2011 string s = Convert.ToBase64String(arg); // Regular base64 encoder 2012 s = s.Split('=')[0]; // Remove any trailing '='s 2013 s = s.Replace('+', '-'); // 62nd char of encoding 2014 s = s.Replace('/', '_'); // 63rd char of encoding 2015 return s; 2016 } 2018 static byte [] base64urldecode(string arg) 2019 { 2020 string s = arg; 2021 s = s.Replace('-', '+'); // 62nd char of encoding 2022 s = s.Replace('_', '/'); // 63rd char of encoding 2023 switch (s.Length % 4) // Pad with trailing '='s 2024 { 2025 case 0: break; // No pad chars in this case 2026 case 2: s += "=="; break; // Two pad chars 2027 case 3: s += "="; break; // One pad char 2028 default: throw new System.Exception( 2029 "Illegal base64url string!"); 2030 } 2031 return Convert.FromBase64String(s); // Standard base64 decoder 2032 } 2034 As per the example code above, the number of '=' padding characters 2035 that needs to be added to the end of a base64url encoded string 2036 without padding to turn it into one with padding is a deterministic 2037 function of the length of the encoded string. Specifically, if the 2038 length mod 4 is 0, no padding is added; if the length mod 4 is 2, two 2039 '=' padding characters are added; if the length mod 4 is 3, one '=' 2040 padding character is added; if the length mod 4 is 1, the input is 2041 malformed. 2043 An example correspondence between unencoded and encoded values 2044 follows. The octet sequence below encodes into the string below, 2045 which when decoded, reproduces the octet sequence. 2046 3 236 255 224 193 2047 A-z_4ME 2049 Appendix D. Negative Test Case for "crit" Header Parameter 2051 Conforming implementations must reject input containing critical 2052 extensions that are not understood or cannot be processed. The 2053 following JWS must be rejected by all implementations, because it 2054 uses an extension header parameter name 2055 "http://example.invalid/UNDEFINED" that they do not understand. Any 2056 other similar input, in which the use of the value 2057 "http://example.invalid/UNDEFINED" is substituted for any other 2058 header parameter name not understood by the implementation, must also 2059 be rejected. 2061 The JWS Header value for this JWS is: 2063 {"alg":"none", 2064 "crit":["http://example.invalid/UNDEFINED"], 2065 "http://example.invalid/UNDEFINED":true 2066 } 2068 The complete JWS that must be rejected is as follows (with line 2069 breaks for display purposes only): 2071 eyJhbGciOiJub25lIiwNCiAiY3JpdCI6WyJodHRwOi8vZXhhbXBsZS5jb20vVU5ERU 2072 ZJTkVEIl0sDQogImh0dHA6Ly9leGFtcGxlLmNvbS9VTkRFRklORUQiOnRydWUNCn0. 2073 RkFJTA. 2075 Appendix E. Acknowledgements 2077 Solutions for signing JSON content were previously explored by Magic 2078 Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas 2079 Applications [CanvasApp], all of which influenced this draft. 2081 Thanks to Axel Nennker for his early implementation and feedback on 2082 the JWS and JWE specifications. 2084 This specification is the work of the JOSE Working Group, which 2085 includes dozens of active and dedicated participants. In particular, 2086 the following individuals contributed ideas, feedback, and wording 2087 that influenced this specification: 2089 Dirk Balfanz, Richard Barnes, Brian Campbell, Breno de Medeiros, Dick 2090 Hardt, Joe Hildebrand, Jeff Hodges, Edmund Jay, Yaron Y. Goland, Ben 2091 Laurie, James Manger, Matt Miller, Tony Nadalin, Axel Nennker, John 2092 Panzer, Emmanuel Raviart, Eric Rescorla, Jim Schaad, Paul Tarjan, 2093 Hannes Tschofenig, and Sean Turner. 2095 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2096 Sean Turner and Stephen Farrell served as Security area directors 2097 during the creation of this specification. 2099 Appendix F. Document History 2101 [[ to be removed by the RFC editor before publication as an RFC ]] 2102 -14 2104 o Stated that the "signature" parameter is to be omitted in the JWS 2105 JSON Serialization when its value would be empty (which is only 2106 the case for a Plaintext JWS). 2108 -13 2110 o Made all header parameter values be per-signature/MAC, addressing 2111 issue #24. 2113 -12 2115 o Clarified that the "typ" and "cty" header parameters are used in 2116 an application-specific manner and have no effect upon the JWS 2117 processing. 2119 o Replaced the MIME types "application/jws+json" and 2120 "application/jws" with "application/jose+json" and 2121 "application/jose". 2123 o Stated that recipients MUST either reject JWSs with duplicate 2124 Header Parameter Names or use a JSON parser that returns only the 2125 lexically last duplicate member name. 2127 o Added a Serializations section with parallel treatment of the JWS 2128 Compact Serialization and the JWS JSON Serialization and also 2129 moved the former Implementation Considerations content there. 2131 -11 2133 o Added Key Identification section. 2135 o For the JWS JSON Serialization, enable header parameter values to 2136 be specified in any of three parameters: the "protected" member 2137 that is integrity protected and shared among all recipients, the 2138 "unprotected" member that is not integrity protected and shared 2139 among all recipients, and the "header" member that is not 2140 integrity protected and specific to a particular recipient. (This 2141 does not affect the JWS Compact Serialization, in which all header 2142 parameter values are in a single integrity protected JWE Header 2143 value.) 2145 o Removed suggested compact serialization for multiple digital 2146 signatures and/or MACs. 2148 o Changed the MIME type name "application/jws-js" to 2149 "application/jws+json", addressing issue #22. 2151 o Tightened the description of the "crit" (critical) header 2152 parameter. 2154 o Added a negative test case for the "crit" header parameter 2156 -10 2158 o Added an appendix suggesting a possible compact serialization for 2159 JWSs with multiple digital signatures and/or MACs. 2161 -09 2163 o Added JWS JSON Serialization, as specified by 2164 draft-jones-jose-jws-json-serialization-04. 2166 o Registered "application/jws-js" MIME type and "JWS-JS" typ header 2167 parameter value. 2169 o Defined that the default action for header parameters that are not 2170 understood is to ignore them unless specifically designated as 2171 "MUST be understood" or included in the new "crit" (critical) 2172 header parameter list. This addressed issue #6. 2174 o Changed term "JWS Secured Input" to "JWS Signing Input". 2176 o Changed from using the term "byte" to "octet" when referring to 8 2177 bit values. 2179 o Changed member name from "recipients" to "signatures" in the JWS 2180 JSON Serialization. 2182 o Added complete values using the JWS Compact Serialization for all 2183 examples. 2185 -08 2187 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2188 Tschofenig. Many of these simplified the terminology used. 2190 o Clarified statements of the form "This header parameter is 2191 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2193 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2194 Web Signature and Encryption Header Parameters registry. 2196 o Added seriesInfo information to Internet Draft references. 2198 -07 2199 o Updated references. 2201 -06 2203 o Changed "x5c" (X.509 Certificate Chain) representation from being 2204 a single string to being an array of strings, each containing a 2205 single base64 encoded DER certificate value, representing elements 2206 of the certificate chain. 2208 o Applied changes made by the RFC Editor to RFC 6749's registry 2209 language to this specification. 2211 -05 2213 o Added statement that "StringOrURI values are compared as case- 2214 sensitive strings with no transformations or canonicalizations 2215 applied". 2217 o Indented artwork elements to better distinguish them from the body 2218 text. 2220 -04 2222 o Completed JSON Security Considerations section, including 2223 considerations about rejecting input with duplicate member names. 2225 o Completed security considerations on the use of a SHA-1 hash when 2226 computing "x5t" (x.509 certificate thumbprint) values. 2228 o Refer to the registries as the primary sources of defined values 2229 and then secondarily reference the sections defining the initial 2230 contents of the registries. 2232 o Normatively reference XML DSIG 2.0 [W3C.CR-xmldsig-core2-20120124] 2233 for its security considerations. 2235 o Added this language to Registration Templates: "This name is case 2236 sensitive. Names that match other registered names in a case 2237 insensitive manner SHOULD NOT be accepted." 2239 o Reference draft-jones-jose-jws-json-serialization instead of 2240 draft-jones-json-web-signature-json-serialization. 2242 o Described additional open issues. 2244 o Applied editorial suggestions. 2246 -03 2247 o Added the "cty" (content type) header parameter for declaring type 2248 information about the secured content, as opposed to the "typ" 2249 (type) header parameter, which declares type information about 2250 this object. 2252 o Added "Collision Resistant Namespace" to the terminology section. 2254 o Reference ITU.X690.1994 for DER encoding. 2256 o Added an example JWS using ECDSA P-521 SHA-512. This has 2257 particular illustrative value because of the use of the 521 bit 2258 integers in the key and signature values. This is also an example 2259 in which the payload is not a base64url encoded JSON object. 2261 o Added an example "x5c" value. 2263 o No longer say "the UTF-8 representation of the JWS Secured Input 2264 (which is the same as the ASCII representation)". Just call it 2265 "the ASCII representation of the JWS Secured Input". 2267 o Added Registration Template sections for defined registries. 2269 o Added Registry Contents sections to populate registry values. 2271 o Changed name of the JSON Web Signature and Encryption "typ" Values 2272 registry to be the JSON Web Signature and Encryption Type Values 2273 registry, since it is used for more than just values of the "typ" 2274 parameter. 2276 o Moved registries JSON Web Signature and Encryption Header 2277 Parameters and JSON Web Signature and Encryption Type Values to 2278 the JWS specification. 2280 o Numerous editorial improvements. 2282 -02 2284 o Clarified that it is an error when a "kid" value is included and 2285 no matching key is found. 2287 o Removed assumption that "kid" (key ID) can only refer to an 2288 asymmetric key. 2290 o Clarified that JWSs with duplicate Header Parameter Names MUST be 2291 rejected. 2293 o Clarified the relationship between "typ" header parameter values 2294 and MIME types. 2296 o Registered application/jws MIME type and "JWS" typ header 2297 parameter value. 2299 o Simplified JWK terminology to get replace the "JWK Key Object" and 2300 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2301 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2302 between single keys and sets of keys. As part of this change, the 2303 Header Parameter Name for a public key value was changed from 2304 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2306 o Added suggestion on defining additional header parameters such as 2307 "x5t#S256" in the future for certificate thumbprints using hash 2308 algorithms other than SHA-1. 2310 o Specify RFC 2818 server identity validation, rather than RFC 6125 2311 (paralleling the same decision in the OAuth specs). 2313 o Generalized language to refer to Message Authentication Codes 2314 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2315 unless in a context specific to HMAC algorithms. 2317 o Reformatted to give each header parameter its own section heading. 2319 -01 2321 o Moved definition of Plaintext JWSs (using "alg":"none") here from 2322 the JWT specification since this functionality is likely to be 2323 useful in more contexts that just for JWTs. 2325 o Added "jpk" and "x5c" header parameters for including JWK public 2326 keys and X.509 certificate chains directly in the header. 2328 o Clarified that this specification is defining the JWS Compact 2329 Serialization. Referenced the new JWS-JS spec, which defines the 2330 JWS JSON Serialization. 2332 o Added text "New header parameters should be introduced sparingly 2333 since an implementation that does not understand a parameter MUST 2334 reject the JWS". 2336 o Clarified that the order of the creation and validation steps is 2337 not significant in cases where there are no dependencies between 2338 the inputs and outputs of the steps. 2340 o Changed "no canonicalization is performed" to "no canonicalization 2341 need be performed". 2343 o Corrected the Magic Signatures reference. 2345 o Made other editorial improvements suggested by JOSE working group 2346 participants. 2348 -00 2350 o Created the initial IETF draft based upon 2351 draft-jones-json-web-signature-04 with no normative changes. 2353 o Changed terminology to no longer call both digital signatures and 2354 HMACs "signatures". 2356 Authors' Addresses 2358 Michael B. Jones 2359 Microsoft 2361 Email: mbj@microsoft.com 2362 URI: http://self-issued.info/ 2364 John Bradley 2365 Ping Identity 2367 Email: ve7jtb@ve7jtb.com 2369 Nat Sakimura 2370 Nomura Research Institute 2372 Email: n-sakimura@nri.co.jp