idnits 2.17.1 draft-ietf-jose-json-web-signature-29.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 -- The document date (June 20, 2014) is 3596 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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 1748 -- Looks like a reference, but probably isn't: '34' on line 1748 -- Looks like a reference, but probably isn't: '97' on line 1758 -- Looks like a reference, but probably isn't: '108' on line 1758 -- Looks like a reference, but probably isn't: '103' on line 1748 -- Looks like a reference, but probably isn't: '58' on line 1748 -- Looks like a reference, but probably isn't: '82' on line 1502 -- Looks like a reference, but probably isn't: '83' on line 1748 -- Looks like a reference, but probably isn't: '50' on line 1748 -- Looks like a reference, but probably isn't: '53' on line 1748 -- Looks like a reference, but probably isn't: '54' on line 1634 -- Looks like a reference, but probably isn't: '125' on line 1748 -- Looks like a reference, but probably isn't: '69' on line 1748 -- Looks like a reference, but probably isn't: '49' on line 1748 -- Looks like a reference, but probably isn't: '80' on line 1758 -- Looks like a reference, but probably isn't: '121' on line 1758 -- Looks like a reference, but probably isn't: '111' on line 1758 -- Looks like a reference, but probably isn't: '100' on line 1758 -- Looks like a reference, but probably isn't: '0' on line 2068 -- 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 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) Summary: 5 errors (**), 0 flaws (~~), 1 warning (==), 25 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: December 22, 2014 Ping Identity 6 N. Sakimura 7 NRI 8 June 20, 2014 10 JSON Web Signature (JWS) 11 draft-ietf-jose-json-web-signature-29 13 Abstract 15 JSON Web Signature (JWS) represents content secured with digital 16 signatures or Message Authentication Codes (MACs) using JavaScript 17 Object Notation (JSON) based data structures. Cryptographic 18 algorithms and identifiers for use with this specification are 19 described in the separate JSON Web Algorithms (JWA) specification and 20 an IANA registry defined by that specification. Related encryption 21 capabilities are described in the separate JSON Web Encryption (JWE) 22 specification. 24 Status of this Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on December 22, 2014. 41 Copyright Notice 43 Copyright (c) 2014 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 60 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 61 3. JSON Web Signature (JWS) Overview . . . . . . . . . . . . . . 6 62 3.1. Example JWS . . . . . . . . . . . . . . . . . . . . . . . 8 63 4. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . . . 9 64 4.1. Registered Header Parameter Names . . . . . . . . . . . . 9 65 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 10 66 4.1.2. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 10 67 4.1.3. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 10 68 4.1.4. "kid" (Key ID) Header Parameter . . . . . . . . . . . 11 69 4.1.5. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 11 70 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter . . . 11 71 4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header 72 Parameter . . . . . . . . . . . . . . . . . . . . . . 12 73 4.1.8. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) 74 Header Parameter . . . . . . . . . . . . . . . . . . . 12 75 4.1.9. "typ" (Type) Header Parameter . . . . . . . . . . . . 12 76 4.1.10. "cty" (Content Type) Header Parameter . . . . . . . . 13 77 4.1.11. "crit" (Critical) Header Parameter . . . . . . . . . . 13 78 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 14 79 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 14 80 5. Producing and Consuming JWSs . . . . . . . . . . . . . . . . . 14 81 5.1. Message Signature or MAC Computation . . . . . . . . . . . 14 82 5.2. Message Signature or MAC Validation . . . . . . . . . . . 15 83 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 16 84 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 17 85 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 17 86 7.1. JWS Compact Serialization . . . . . . . . . . . . . . . . 18 87 7.2. JWS JSON Serialization . . . . . . . . . . . . . . . . . . 18 88 8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 19 89 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 90 9.1. JSON Web Signature and Encryption Header Parameters 91 Registry . . . . . . . . . . . . . . . . . . . . . . . . . 21 92 9.1.1. Registration Template . . . . . . . . . . . . . . . . 21 93 9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 22 94 9.2. Media Type Registration . . . . . . . . . . . . . . . . . 23 95 9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 23 97 10. Security Considerations . . . . . . . . . . . . . . . . . . . 24 98 10.1. Key Entropy . . . . . . . . . . . . . . . . . . . . . . . 25 99 10.2. Chosen Plaintext Attacks . . . . . . . . . . . . . . . . . 25 100 10.3. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 25 101 10.4. Differences between Digital Signatures and MACs . . . . . 25 102 10.5. SHA-1 Certificate Thumbprints . . . . . . . . . . . . . . 26 103 10.6. JSON Security Considerations . . . . . . . . . . . . . . . 26 104 10.7. Unicode Comparison Security Considerations . . . . . . . . 27 105 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 27 106 11.1. Normative References . . . . . . . . . . . . . . . . . . . 27 107 11.2. Informative References . . . . . . . . . . . . . . . . . . 29 108 Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 29 109 A.1. Example JWS using HMAC SHA-256 . . . . . . . . . . . . . . 30 110 A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 30 111 A.1.2. Validating . . . . . . . . . . . . . . . . . . . . . . 32 112 A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 . . . . . . . . 32 113 A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 32 114 A.2.2. Validating . . . . . . . . . . . . . . . . . . . . . . 35 115 A.3. Example JWS using ECDSA P-256 SHA-256 . . . . . . . . . . 35 116 A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 35 117 A.3.2. Validating . . . . . . . . . . . . . . . . . . . . . . 37 118 A.4. Example JWS using ECDSA P-521 SHA-512 . . . . . . . . . . 38 119 A.4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 38 120 A.4.2. Validating . . . . . . . . . . . . . . . . . . . . . . 40 121 A.5. Example Plaintext JWS . . . . . . . . . . . . . . . . . . 40 122 A.6. Example JWS Using JWS JSON Serialization . . . . . . . . . 41 123 A.6.1. JWS Per-Signature Protected Headers . . . . . . . . . 41 124 A.6.2. JWS Per-Signature Unprotected Headers . . . . . . . . 42 125 A.6.3. Complete JOSE Header Values . . . . . . . . . . . . . 42 126 A.6.4. Complete JWS JSON Serialization Representation . . . . 42 127 Appendix B. "x5c" (X.509 Certificate Chain) Example . . . . . . . 43 128 Appendix C. Notes on implementing base64url encoding without 129 padding . . . . . . . . . . . . . . . . . . . . . . . 45 130 Appendix D. Notes on Key Selection . . . . . . . . . . . . . . . 46 131 Appendix E. Negative Test Case for "crit" Header Parameter . . . 47 132 Appendix F. Detached Content . . . . . . . . . . . . . . . . . . 48 133 Appendix G. Acknowledgements . . . . . . . . . . . . . . . . . . 48 134 Appendix H. Document History . . . . . . . . . . . . . . . . . . 49 135 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 58 137 1. Introduction 139 JSON Web Signature (JWS) represents content secured with digital 140 signatures or Message Authentication Codes (MACs) using JavaScript 141 Object Notation (JSON) [RFC7159] based data structures. The JWS 142 cryptographic mechanisms provide integrity protection for an 143 arbitrary sequence of octets. 145 Two closely related serializations for JWS objects are defined. The 146 JWS Compact Serialization is a compact, URL-safe representation 147 intended for space constrained environments such as HTTP 148 Authorization headers and URI query parameters. The JWS JSON 149 Serialization represents JWS objects as JSON objects and enables 150 multiple signatures and/or MACs to be applied to the same content. 151 Both share the same cryptographic underpinnings. 153 Cryptographic algorithms and identifiers for use with this 154 specification are described in the separate JSON Web Algorithms (JWA) 155 [JWA] specification and an IANA registry defined by that 156 specification. Related encryption capabilities are described in the 157 separate JSON Web Encryption (JWE) [JWE] specification. 159 Names defined by this specification are short because a core goal is 160 for the resulting representations to be compact. 162 1.1. Notational Conventions 164 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 165 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 166 "OPTIONAL" in this document are to be interpreted as described in Key 167 words for use in RFCs to Indicate Requirement Levels [RFC2119]. If 168 these words are used without being spelled in uppercase then they are 169 to be interpreted with their normal natural language meanings. 171 BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per 172 Section 2. 174 UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation 175 of STRING. 177 ASCII(STRING) denotes the octets of the ASCII [USASCII] 178 representation of STRING. 180 The concatenation of two values A and B is denoted as A || B. 182 2. Terminology 184 These terms are defined by this specification: 186 JSON Web Signature (JWS) 187 A data structure representing a digitally signed or MACed message. 189 JOSE Header 190 JSON object containing the parameters describing the cryptographic 191 operations and parameters employed. The members of the JOSE 192 Header are Header Parameters. 194 JWS Payload 195 The sequence of octets to be secured -- a.k.a., the message. The 196 payload can contain an arbitrary sequence of octets. 198 JWS Signature 199 Digital signature or MAC over the JWS Protected Header and the JWS 200 Payload. 202 Header Parameter 203 A name/value pair that is member of the JOSE Header. 205 JWS Protected Header 206 JSON object that contains the Header Parameters that are integrity 207 protected by the JWS Signature digital signature or MAC operation. 208 For the JWS Compact Serialization, this comprises the entire JOSE 209 Header. For the JWS JSON Serialization, this is one component of 210 the JOSE Header. 212 JWS Unprotected Header 213 JSON object that contains the Header Parameters that are not 214 integrity protected. This can only be present when using the JWS 215 JSON Serialization. 217 Base64url Encoding 218 Base64 encoding using the URL- and filename-safe character set 219 defined in Section 5 of RFC 4648 [RFC4648], with all trailing '=' 220 characters omitted (as permitted by Section 3.2) and without the 221 inclusion of any line breaks, white space, or other additional 222 characters. (See Appendix C for notes on implementing base64url 223 encoding without padding.) 225 JWS Signing Input 226 The input to the digital signature or MAC computation. Its value 227 is ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || 228 BASE64URL(JWS Payload)). 230 JWS Compact Serialization 231 A representation of the JWS as a compact, URL-safe string. 233 JWS JSON Serialization 234 A representation of the JWS as a JSON object. Unlike the JWS 235 Compact Serialization, the JWS JSON Serialization enables multiple 236 digital signatures and/or MACs to be applied to the same content. 237 This representation is neither optimized for compactness nor URL- 238 safe. 240 Plaintext JWS 241 A JWS object that provides no integrity protection. 243 Collision-Resistant Name 244 A name in a namespace that enables names to be allocated in a 245 manner such that they are highly unlikely to collide with other 246 names. Examples of collision-resistant namespaces include: Domain 247 Names, Object Identifiers (OIDs) as defined in the ITU-T X.660 and 248 X.670 Recommendation series, and Universally Unique IDentifiers 249 (UUIDs) [RFC4122]. When using an administratively delegated 250 namespace, the definer of a name needs to take reasonable 251 precautions to ensure they are in control of the portion of the 252 namespace they use to define the name. 254 StringOrURI 255 A JSON string value, with the additional requirement that while 256 arbitrary string values MAY be used, any value containing a ":" 257 character MUST be a URI [RFC3986]. StringOrURI values are 258 compared as case-sensitive strings with no transformations or 259 canonicalizations applied. 261 These terms defined by the JSON Web Encryption (JWE) [JWE] 262 specification are incorporated into this specification: "JSON Web 263 Encryption (JWE)" and "JWE Compact Serialization". 265 3. JSON Web Signature (JWS) Overview 267 JWS represents digitally signed or MACed content using JSON data 268 structures and base64url encoding. A JWS represents these logical 269 values: 271 JOSE Header 272 JSON object containing the parameters describing the cryptographic 273 operations and parameters employed. For a JWS object, the JOSE 274 Header members are the union of the members of the JWS Protected 275 Header and the JWS Unprotected Header, as described below. 277 JWS Payload 278 The sequence of octets to be secured -- a.k.a., the message. The 279 payload can contain an arbitrary sequence of octets. 281 JWS Signature 282 Digital signature or MAC over the JWS Protected Header and the JWS 283 Payload. 285 For a JWS object, the JOSE Header represents the combination of these 286 values: 288 JWS Protected Header 289 JSON object that contains the Header Parameters that are integrity 290 protected by the JWS Signature digital signature or MAC operation. 292 JWS Unprotected Header 293 JSON object that contains the Header Parameters that are not 294 integrity protected. 296 This document defines two serializations for JWS objects: a compact, 297 URL-safe serialization called the JWS Compact Serialization and a 298 JSON serialization called the JWS JSON Serialization. In both 299 serializations, the JWS Protected Header, JWS Payload, and JWS 300 Signature are base64url encoded for transmission, since JSON lacks a 301 way to directly represent octet sequences. 303 In the JWS Compact Serialization, no JWS Unprotected Header is used. 304 In this case, the JOSE Header and the JWS Protected Header are the 305 same. 307 In the JWS Compact Serialization, a JWS object is represented as the 308 combination of these three string values, 309 BASE64URL(UTF8(JWS Protected Header)), 310 BASE64URL(JWS Payload), and 311 BASE64URL(JWS Signature), 312 concatenated in that order, with the three strings being separated by 313 two period ('.') characters. 315 In the JWS JSON Serialization, one or both of the JWS Protected 316 Header and JWS Unprotected Header MUST be present. In this case, the 317 members of the JOSE Header are the combination of the members of the 318 JWS Protected Header and the JWS Unprotected Header values that are 319 present. 321 In the JWS JSON Serialization, a JWS object is represented as the 322 combination of these four values, 323 BASE64URL(UTF8(JWS Protected Header)), 324 JWS Unprotected Header, 325 BASE64URL(JWS Payload), and 326 BASE64URL(JWS Signature), 327 with the three base64url encoding result strings and the JWS 328 Unprotected Header value being represented as members within a JSON 329 object. The inclusion of some of these values is OPTIONAL. The JWS 330 JSON Serialization can also represent multiple signature and/or MAC 331 values, rather than just one. See Section 7.2 for more information 332 about the JWS JSON Serialization. 334 3.1. Example JWS 336 This section provides an example of a JWS. Its computation is 337 described in more detail in Appendix A.1, including specifying the 338 exact octet sequences representing the JSON values used and the key 339 value used. 341 The following example JWS Protected Header declares that the encoded 342 object is a JSON Web Token (JWT) [JWT] and the JWS Protected Header 343 and the JWS Payload are secured using the HMAC SHA-256 algorithm: 345 {"typ":"JWT", 346 "alg":"HS256"} 348 Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected 349 Header)) gives this value: 351 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 353 The UTF-8 representation of following JSON object is used as the JWS 354 Payload. (Note that the payload can be any content, and need not be 355 a representation of a JSON object.) 357 {"iss":"joe", 358 "exp":1300819380, 359 "http://example.com/is_root":true} 361 Encoding this JWS Payload as BASE64URL(JWS Payload) gives this value 362 (with line breaks for display purposes only): 364 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 365 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 367 Computing the HMAC of the JWS Signing Input ASCII(BASE64URL(UTF8(JWS 368 Protected Header)) || '.' || BASE64URL(JWS Payload)) with the HMAC 369 SHA-256 algorithm using the key specified in Appendix A.1 and 370 base64url encoding the result yields this BASE64URL(JWS Signature) 371 value: 373 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 375 Concatenating these values in the order Header.Payload.Signature with 376 period ('.') characters between the parts yields this complete JWS 377 representation using the JWS Compact Serialization (with line breaks 378 for display purposes only): 380 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 381 . 382 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 383 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 384 . 385 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 387 See Appendix A for additional examples. 389 4. JOSE Header 391 For a JWS object, the members of the JSON object(s) representing the 392 JOSE Header describe the digital signature or MAC applied to the JWS 393 Protected Header and the JWS Payload and optionally additional 394 properties of the JWS. The Header Parameter names within the JOSE 395 Header MUST be unique; recipients MUST either reject JWSs with 396 duplicate Header Parameter names or use a JSON parser that returns 397 only the lexically last duplicate member name, as specified in 398 Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript]. 400 Implementations are required to understand the specific Header 401 Parameters defined by this specification that are designated as "MUST 402 be understood" and process them in the manner defined in this 403 specification. All other Header Parameters defined by this 404 specification that are not so designated MUST be ignored when not 405 understood. Unless listed as a critical Header Parameter, per 406 Section 4.1.11, all Header Parameters not defined by this 407 specification MUST be ignored when not understood. 409 There are three classes of Header Parameter names: Registered Header 410 Parameter names, Public Header Parameter names, and Private Header 411 Parameter names. 413 4.1. Registered Header Parameter Names 415 The following Header Parameter names for use in JWS objects are 416 registered in the IANA JSON Web Signature and Encryption Header 417 Parameters registry defined in Section 9.1, with meanings as defined 418 below. 420 As indicated by the common registry, JWSs and JWEs share a common 421 Header Parameter space; when a parameter is used by both 422 specifications, its usage must be compatible between the 423 specifications. 425 4.1.1. "alg" (Algorithm) Header Parameter 427 The "alg" (algorithm) Header Parameter identifies the cryptographic 428 algorithm used to secure the JWS. The signature, MAC, or plaintext 429 value is not valid if the "alg" value does not represent a supported 430 algorithm, or if there is not a key for use with that algorithm 431 associated with the party that digitally signed or MACed the content. 432 "alg" values should either be registered in the IANA JSON Web 433 Signature and Encryption Algorithms registry defined in [JWA] or be a 434 value that contains a Collision-Resistant Name. The "alg" value is a 435 case-sensitive string containing a StringOrURI value. This Header 436 Parameter MUST be present and MUST be understood and processed by 437 implementations. 439 A list of defined "alg" values for this use can be found in the IANA 440 JSON Web Signature and Encryption Algorithms registry defined in 441 [JWA]; the initial contents of this registry are the values defined 442 in Section 3.1 of the JSON Web Algorithms (JWA) [JWA] specification. 444 4.1.2. "jku" (JWK Set URL) Header Parameter 446 The "jku" (JWK Set URL) Header Parameter is a URI [RFC3986] that 447 refers to a resource for a set of JSON-encoded public keys, one of 448 which corresponds to the key used to digitally sign the JWS. The 449 keys MUST be encoded as a JSON Web Key Set (JWK Set) [JWK]. The 450 protocol used to acquire the resource MUST provide integrity 451 protection; an HTTP GET request to retrieve the JWK Set MUST use TLS 452 [RFC2818] [RFC5246]; the identity of the server MUST be validated, as 453 per Section 6 of RFC 6125 [RFC6125]. Use of this Header Parameter is 454 OPTIONAL. 456 4.1.3. "jwk" (JSON Web Key) Header Parameter 458 The "jwk" (JSON Web Key) Header Parameter is the public key that 459 corresponds to the key used to digitally sign the JWS. This key is 460 represented as a JSON Web Key [JWK]. Use of this Header Parameter is 461 OPTIONAL. 463 4.1.4. "kid" (Key ID) Header Parameter 465 The "kid" (key ID) Header Parameter is a hint indicating which key 466 was used to secure the JWS. This parameter allows originators to 467 explicitly signal a change of key to recipients. The structure of 468 the "kid" value is unspecified. Its value MUST be a string. Use of 469 this Header Parameter is OPTIONAL. 471 When used with a JWK, the "kid" value is used to match a JWK "kid" 472 parameter value. 474 4.1.5. "x5u" (X.509 URL) Header Parameter 476 The "x5u" (X.509 URL) Header Parameter is a URI [RFC3986] that refers 477 to a resource for the X.509 public key certificate or certificate 478 chain [RFC5280] corresponding to the key used to digitally sign the 479 JWS. The identified resource MUST provide a representation of the 480 certificate or certificate chain that conforms to RFC 5280 [RFC5280] 481 in PEM encoded form [RFC1421]. The certificate containing the public 482 key corresponding to the key used to digitally sign the JWS MUST be 483 the first certificate. This MAY be followed by additional 484 certificates, with each subsequent certificate being the one used to 485 certify the previous one. The protocol used to acquire the resource 486 MUST provide integrity protection; an HTTP GET request to retrieve 487 the certificate MUST use TLS [RFC2818] [RFC5246]; the identity of the 488 server MUST be validated, as per Section 6 of RFC 6125 [RFC6125]. 489 Use of this Header Parameter is OPTIONAL. 491 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter 493 The "x5c" (X.509 Certificate Chain) Header Parameter contains the 494 X.509 public key certificate or certificate chain [RFC5280] 495 corresponding to the key used to digitally sign the JWS. The 496 certificate or certificate chain is represented as a JSON array of 497 certificate value strings. Each string in the array is a base64 498 encoded ([RFC4648] Section 4 -- not base64url encoded) DER 499 [ITU.X690.1994] PKIX certificate value. The certificate containing 500 the public key corresponding to the key used to digitally sign the 501 JWS MUST be the first certificate. This MAY be followed by 502 additional certificates, with each subsequent certificate being the 503 one used to certify the previous one. The recipient MUST validate 504 the certificate chain according to [RFC5280] and reject the signature 505 if any validation failure occurs. Use of this Header Parameter is 506 OPTIONAL. 508 See Appendix B for an example "x5c" value. 510 4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter 512 The "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter is a 513 base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER 514 encoding of the X.509 certificate [RFC5280] corresponding to the key 515 used to digitally sign the JWS. Use of this Header Parameter is 516 OPTIONAL. 518 4.1.8. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header 519 Parameter 521 The "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header 522 Parameter is a base64url encoded SHA-256 thumbprint (a.k.a. digest) 523 of the DER encoding of the X.509 certificate [RFC5280] corresponding 524 to the key used to digitally sign the JWS. Use of this Header 525 Parameter is OPTIONAL. 527 4.1.9. "typ" (Type) Header Parameter 529 The "typ" (type) Header Parameter is used by JWS applications to 530 declare the MIME Media Type [IANA.MediaTypes] of this complete JWS 531 object. This is intended for use by the application when more than 532 one kind of object could be present in an application data structure 533 that can contain a JWS object; the application can use this value to 534 disambiguate among the different kinds of objects that might be 535 present. It will typically not be used by applications when the kind 536 of object is already known. This parameter has no effect upon the 537 JWS processing. Use of this Header Parameter is OPTIONAL. 539 Per [RFC2045], all media type values, subtype values, and parameter 540 names are case-insensitive. However, parameter values are case- 541 sensitive unless otherwise specified for the specific parameter. 543 To keep messages compact in common situations, it is RECOMMENDED that 544 senders omit an "application/" prefix of a media type value in a 545 "typ" Header Parameter when no other '/' appears in the media type 546 value. A recipient using the media type value MUST treat it as if 547 "application/" were prepended to any "typ" value not containing a 548 '/'. For instance, a "typ" value of "example" SHOULD be used to 549 represent the "application/example" media type; whereas, the media 550 type "application/example;part="1/2"" cannot be shortened to 551 "example;part="1/2"". 553 The "typ" value "JOSE" can be used by applications to indicate that 554 this object is a JWS or JWE using the JWS Compact Serialization or 555 the JWE Compact Serialization. The "typ" value "JOSE+JSON" can be 556 used by applications to indicate that this object is a JWS or JWE 557 using the JWS JSON Serialization or the JWE JSON Serialization. 559 Other type values can also be used by applications. 561 4.1.10. "cty" (Content Type) Header Parameter 563 The "cty" (content type) Header Parameter is used by JWS applications 564 to declare the MIME Media Type [IANA.MediaTypes] of the secured 565 content (the payload). This is intended for use by the application 566 when more than one kind of object could be present in the JWS 567 payload; the application can use this value to disambiguate among the 568 different kinds of objects that might be present. It will typically 569 not be used by applications when the kind of object is already known. 570 This parameter has no effect upon the JWS processing. Use of this 571 Header Parameter is OPTIONAL. 573 Per [RFC2045], all media type values, subtype values, and parameter 574 names are case-insensitive. However, parameter values are case- 575 sensitive unless otherwise specified for the specific parameter. 577 To keep messages compact in common situations, it is RECOMMENDED that 578 senders omit an "application/" prefix of a media type value in a 579 "cty" Header Parameter when no other '/' appears in the media type 580 value. A recipient using the media type value MUST treat it as if 581 "application/" were prepended to any "cty" value not containing a 582 '/'. For instance, a "cty" value of "example" SHOULD be used to 583 represent the "application/example" media type; whereas, the media 584 type "application/example;part="1/2"" cannot be shortened to 585 "example;part="1/2"". 587 4.1.11. "crit" (Critical) Header Parameter 589 The "crit" (critical) Header Parameter indicates that extensions to 590 the initial RFC versions of [[ this specification ]] and [JWA] are 591 being used that MUST be understood and processed. Its value is an 592 array listing the Header Parameter names present in the JOSE Header 593 that use those extensions. If any of the listed extension Header 594 Parameters are not understood and supported by the receiver, it MUST 595 reject the JWS. Senders MUST NOT include Header Parameter names 596 defined by the initial RFC versions of [[ this specification ]] or 597 [JWA] for use with JWS, duplicate names, or names that do not occur 598 as Header Parameter names within the JOSE Header in the "crit" list. 599 Senders MUST NOT use the empty list "[]" as the "crit" value. 600 Recipients MAY reject the JWS if the critical list contains any 601 Header Parameter names defined by the initial RFC versions of [[ this 602 specification ]] or [JWA] for use with JWS, or any other constraints 603 on its use are violated. This Header Parameter MUST be integrity 604 protected, and therefore MUST occur only within the JWS Protected 605 Header, when used. Use of this Header Parameter is OPTIONAL. This 606 Header Parameter MUST be understood and processed by implementations. 608 An example use, along with a hypothetical "exp" (expiration-time) 609 field is: 611 {"alg":"ES256", 612 "crit":["exp"], 613 "exp":1363284000 614 } 616 4.2. Public Header Parameter Names 618 Additional Header Parameter names can be defined by those using JWSs. 619 However, in order to prevent collisions, any new Header Parameter 620 name should either be registered in the IANA JSON Web Signature and 621 Encryption Header Parameters registry defined in Section 9.1 or be a 622 Public Name: a value that contains a Collision-Resistant Name. In 623 each case, the definer of the name or value needs to take reasonable 624 precautions to make sure they are in control of the part of the 625 namespace they use to define the Header Parameter name. 627 New Header Parameters should be introduced sparingly, as they can 628 result in non-interoperable JWSs. 630 4.3. Private Header Parameter Names 632 A producer and consumer of a JWS may agree to use Header Parameter 633 names that are Private Names: names that are not Registered Header 634 Parameter names Section 4.1 or Public Header Parameter names 635 Section 4.2. Unlike Public Header Parameter names, Private Header 636 Parameter names are subject to collision and should be used with 637 caution. 639 5. Producing and Consuming JWSs 641 5.1. Message Signature or MAC Computation 643 To create a JWS, one MUST perform these steps. The order of the 644 steps is not significant in cases where there are no dependencies 645 between the inputs and outputs of the steps. 646 1. Create the content to be used as the JWS Payload. 647 2. Compute the encoded payload value BASE64URL(JWS Payload). 648 3. Create the JSON object(s) containing the desired set of Header 649 Parameters, which together comprise the JOSE Header: the JWS 650 Protected Header, and if the JWS JSON Serialization is being 651 used, the JWS Unprotected Header. 652 4. Compute the encoded header value BASE64URL(UTF8(JWS Protected 653 Header)). If the JWS Protected Header is not present (which can 654 only happen when using the JWS JSON Serialization and no 655 "protected" member is present), let this value be the empty 656 string. 657 5. Compute the JWS Signature in the manner defined for the 658 particular algorithm being used over the JWS Signing Input 659 ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || 660 BASE64URL(JWS Payload)). The "alg" (algorithm) Header Parameter 661 MUST be present in the JOSE Header, with the algorithm value 662 accurately representing the algorithm used to construct the JWS 663 Signature. 664 6. Compute the encoded signature value BASE64URL(JWS Signature). 665 7. These three encoded values are used in both the JWS Compact 666 Serialization and the JWS JSON Serialization representations. 667 8. If the JWS JSON Serialization is being used, repeat this process 668 (steps 3-7) for each digital signature or MAC operation being 669 performed. 670 9. Create the desired serialized output. The JWS Compact 671 Serialization of this result is BASE64URL(UTF8(JWS Protected 672 Header)) || '.' || BASE64URL(JWS Payload) || '.' || BASE64URL(JWS 673 Signature). The JWS JSON Serialization is described in 674 Section 7.2. 676 5.2. Message Signature or MAC Validation 678 When validating a JWS, the following steps MUST be taken. The order 679 of the steps is not significant in cases where there are no 680 dependencies between the inputs and outputs of the steps. If any of 681 the listed steps fails, then the signature or MAC cannot be 682 validated. 684 It is an application decision which signatures, MACs, or plaintext 685 values must successfully validate for the JWS to be accepted. In 686 some cases, all must successfully validate or the JWS will be 687 rejected. In other cases, only a specific signature, MAC, or 688 plaintext value needs to be successfully validated. However, in all 689 cases, at least one signature, MAC, or plaintext value MUST 690 successfully validate or the JWS MUST be rejected. 692 1. Parse the JWS representation to extract the serialized values 693 for the components of the JWS -- when using the JWS Compact 694 Serialization, the base64url encoded representations of the JWS 695 Protected Header, the JWS Payload, and the JWS Signature, and 696 when using the JWS JSON Serialization, also the unencoded JWS 697 Unprotected Header value. When using the JWS Compact 698 Serialization, the JWS Protected Header, the JWS Payload, and 699 the JWS Signature are represented as base64url encoded values in 700 that order, separated by two period ('.') characters. The JWS 701 JSON Serialization is described in Section 7.2. 703 2. The encoded representation of the JWS Protected Header MUST be 704 successfully base64url decoded following the restriction that no 705 padding characters have been used. 706 3. The resulting octet sequence MUST be a UTF-8 encoded 707 representation of a completely valid JSON object conforming to 708 [RFC7159], which is the JWS Protected Header. 709 4. If using the JWS Compact Serialization, let the JOSE Header be 710 the JWS Protected Header; otherwise, when using the JWS JSON 711 Serialization, let the JOSE Header be the union of the members 712 of the corresponding JWS Protected Header and JWS Unprotected 713 Header, all of which must be completely valid JSON objects. 714 5. The resulting JOSE Header MUST NOT contain duplicate Header 715 Parameter names. When using the JWS JSON Serialization, this 716 restriction includes that the same Header Parameter name also 717 MUST NOT occur in distinct JSON object values that together 718 comprise the JOSE Header. 719 6. Verify that the implementation understands and can process all 720 fields that it is required to support, whether required by this 721 specification, by the algorithm being used, or by the "crit" 722 Header Parameter value, and that the values of those parameters 723 are also understood and supported. 724 7. The encoded representation of the JWS Payload MUST be 725 successfully base64url decoded following the restriction that no 726 padding characters have been used. 727 8. The encoded representation of the JWS Signature MUST be 728 successfully base64url decoded following the restriction that no 729 padding characters have been used. 730 9. The JWS Signature MUST be successfully validated against the JWS 731 Signing Input ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' 732 || BASE64URL(JWS Payload)) in the manner defined for the 733 algorithm being used, which MUST be accurately represented by 734 the value of the "alg" (algorithm) Header Parameter, which MUST 735 be present. 736 10. If the JWS JSON Serialization is being used, repeat this process 737 (steps 4-9) for each digital signature or MAC value contained in 738 the representation. 740 5.3. String Comparison Rules 742 Processing a JWS inevitably requires comparing known strings to 743 members and values in a JSON object. For example, in checking what 744 the algorithm is, the Unicode string "alg" will be checked against 745 the member names in the JOSE Header to see if there is a matching 746 Header Parameter name. The same process is then used to determine if 747 the value of the "alg" Header Parameter represents a supported 748 algorithm. 750 Since the only string comparison operations that are performed are 751 equality and inequality, the same rules can be used for comparing 752 both member names and member values against known strings. The JSON 753 rules for doing member name comparison are described in Section 8.3 754 of [RFC7159]. 756 Also, see the JSON security considerations in Section 10.6 and the 757 Unicode security considerations in Section 10.7. 759 6. Key Identification 761 It is necessary for the recipient of a JWS to be able to determine 762 the key that was employed for the digital signature or MAC operation. 763 The key employed can be identified using the Header Parameter methods 764 described in Section 4.1 or can be identified using methods that are 765 outside the scope of this specification. Specifically, the Header 766 Parameters "jku", "jwk", "kid", "x5u", "x5c", "x5t", and "x5t#S256" 767 can be used to identify the key used. These Header Parameters MUST 768 be integrity protected if the information that they convey is to be 769 utilized in a trust decision. 771 The sender SHOULD include sufficient information in the Header 772 Parameters to identify the key used, unless the application uses 773 another means or convention to determine the key used. Validation of 774 the signature or MAC fails when the algorithm used requires a key 775 (which is true of all algorithms except for "none") and the key used 776 cannot be determined. 778 The means of exchanging any shared symmetric keys used is outside the 779 scope of this specification. 781 Also, see Appendix D for notes on possible key selection algorithms. 783 7. Serializations 785 JWS objects use one of two serializations, the JWS Compact 786 Serialization or the JWS JSON Serialization. Applications using this 787 specification need to specify what serialization and serialization 788 features are used for that application. For instance, applications 789 might specify that only the JWS JSON Serialization is used, that only 790 JWS JSON Serialization support for a single signature or MAC value is 791 used, or that support for multiple signatures and/or MAC values is 792 used. JWS implementations only need to implement the features needed 793 for the applications they are designed to support. 795 7.1. JWS Compact Serialization 797 The JWS Compact Serialization represents digitally signed or MACed 798 content as a compact URL-safe string. This string is 799 BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS 800 Payload) || '.' || BASE64URL(JWS Signature). Only one signature/MAC 801 is supported by the JWS Compact Serialization and it provides no 802 syntax to represent a JWS Unprotected Header value. 804 7.2. JWS JSON Serialization 806 The JWS JSON Serialization represents digitally signed or MACed 807 content as a JSON object. Content using the JWS JSON Serialization 808 can be secured with more than one digital signature and/or MAC 809 operation. This representation is neither optimized for compactness 810 nor URL-safe. 812 The following members are defined for use in top-level JSON objects 813 used for the JWS JSON Serialization: 814 payload 815 The "payload" member MUST be present and contain the value 816 BASE64URL(JWS Payload). 817 signatures 818 The "signatures" member value MUST be an array of JSON objects. 819 Each object represents a signature or MAC over the JWS Payload and 820 the JWS Protected Header. 822 The following members are defined for use in the JSON objects that 823 are elements of the "signatures" array: 824 protected 825 The "protected" member MUST be present and contain the value 826 BASE64URL(UTF8(JWS Protected Header)) when the JWS Protected 827 Header value is non-empty; otherwise, it MUST be absent. These 828 Header Parameter values are integrity protected. 829 header 830 The "header" member MUST be present and contain the value JWS 831 Unprotected Header when the JWS Unprotected Header value is non- 832 empty; otherwise, it MUST be absent. This value is represented as 833 an unencoded JSON object, rather than as a string. These Header 834 Parameter values are not integrity protected. 835 signature 836 The "signature" member MUST be present and contain the value 837 BASE64URL(JWS Signature). 839 At least one of the "protected" and "header" members MUST be present 840 for each signature/MAC computation so that an "alg" Header Parameter 841 value is conveyed. 843 Additional members can be present in both the JSON objects defined 844 above; if not understood by implementations encountering them, they 845 MUST be ignored. 847 The Header Parameter values used when creating or validating 848 individual signature or MAC values are the union of the two sets of 849 Header Parameter values that may be present: (1) the JWS Protected 850 Header represented in the "protected" member of the signature/MAC's 851 array element, and (2) the JWS Unprotected Header in the "header" 852 member of the signature/MAC's array element. The union of these sets 853 of Header Parameters comprises the JOSE Header. The Header Parameter 854 names in the two locations MUST be disjoint. 856 Each JWS Signature value is computed using the parameters of the 857 corresponding JOSE Header value in the same manner as for the JWS 858 Compact Serialization. This has the desirable property that each JWS 859 Signature value represented in the "signatures" array is identical to 860 the value that would have been computed for the same parameter in the 861 JWS Compact Serialization, provided that the JWS Protected Header 862 value for that signature/MAC computation (which represents the 863 integrity-protected Header Parameter values) matches that used in the 864 JWS Compact Serialization. 866 In summary, the syntax of a JWS using the JWS JSON Serialization is 867 as follows: 869 { 870 "payload":"", 871 "signatures":[ 872 {"protected":"", 873 "header":, 874 "signature":""}, 875 ... 876 {"protected":"", 877 "header":, 878 "signature":""}] 879 } 881 See Appendix A.6 for an example of computing a JWS using the JWS JSON 882 Serialization. 884 8. TLS Requirements 886 Implementations MUST support TLS. Which version(s) ought to be 887 implemented will vary over time, and depend on the widespread 888 deployment and known security vulnerabilities at the time of 889 implementation. At the time of this writing, TLS version 1.2 891 [RFC5246] is the most recent version. 893 To protect against information disclosure and tampering, 894 confidentiality protection MUST be applied using TLS with a 895 ciphersuite that provides confidentiality and integrity protection. 897 Whenever TLS is used, the identity of the service provider encoded in 898 the TLS server certificate MUST be verified using the procedures 899 described in Section 6 of RFC 6125 [RFC6125]. 901 9. IANA Considerations 903 The following registration procedure is used for all the registries 904 established by this specification. 906 Values are registered with a Specification Required [RFC5226] after a 907 two-week review period on the [TBD]@ietf.org mailing list, on the 908 advice of one or more Designated Experts. However, to allow for the 909 allocation of values prior to publication, the Designated Expert(s) 910 may approve registration once they are satisfied that such a 911 specification will be published. 913 Registration requests must be sent to the [TBD]@ietf.org mailing list 914 for review and comment, with an appropriate subject (e.g., "Request 915 for access token type: example"). [[ Note to the RFC Editor: The name 916 of the mailing list should be determined in consultation with the 917 IESG and IANA. Suggested name: jose-reg-review. ]] 919 Within the review period, the Designated Expert(s) will either 920 approve or deny the registration request, communicating this decision 921 to the review list and IANA. Denials should include an explanation 922 and, if applicable, suggestions as to how to make the request 923 successful. Registration requests that are undetermined for a period 924 longer than 21 days can be brought to the IESG's attention (using the 925 iesg@iesg.org mailing list) for resolution. 927 Criteria that should be applied by the Designated Expert(s) includes 928 determining whether the proposed registration duplicates existing 929 functionality, determining whether it is likely to be of general 930 applicability or whether it is useful only for a single application, 931 and whether the registration makes sense. 933 IANA must only accept registry updates from the Designated Expert(s) 934 and should direct all requests for registration to the review mailing 935 list. 937 It is suggested that multiple Designated Experts be appointed who are 938 able to represent the perspectives of different applications using 939 this specification, in order to enable broadly-informed review of 940 registration decisions. In cases where a registration decision could 941 be perceived as creating a conflict of interest for a particular 942 Expert, that Expert should defer to the judgment of the other 943 Expert(s). 945 9.1. JSON Web Signature and Encryption Header Parameters Registry 947 This specification establishes the IANA JSON Web Signature and 948 Encryption Header Parameters registry for Header Parameter names. 949 The registry records the Header Parameter name and a reference to the 950 specification that defines it. The same Header Parameter name can be 951 registered multiple times, provided that the parameter usage is 952 compatible between the specifications. Different registrations of 953 the same Header Parameter name will typically use different Header 954 Parameter Usage Location(s) values. 956 9.1.1. Registration Template 958 Header Parameter Name: 959 The name requested (e.g., "example"). Because a core goal of this 960 specification is for the resulting representations to be compact, 961 it is RECOMMENDED that the name be short -- not to exceed 8 962 characters without a compelling reason to do so. This name is 963 case-sensitive. Names may not match other registered names in a 964 case-insensitive manner unless the Designated Expert(s) state that 965 there is a compelling reason to allow an exception in this 966 particular case. 967 Header Parameter Description: 968 Brief description of the Header Parameter (e.g., "Example 969 description"). 970 Header Parameter Usage Location(s): 971 The Header Parameter usage locations, which should be one or more 972 of the values "JWS" or "JWE". 973 Change Controller: 974 For Standards Track RFCs, state "IESG". For others, give the name 975 of the responsible party. Other details (e.g., postal address, 976 email address, home page URI) may also be included. 977 Specification Document(s): 978 Reference to the document(s) that specify the parameter, 979 preferably including URI(s) that can be used to retrieve copies of 980 the document(s). An indication of the relevant sections may also 981 be included but is not required. 983 9.1.2. Initial Registry Contents 985 This specification registers the Header Parameter names defined in 986 Section 4.1 in this registry. 988 o Header Parameter Name: "alg" 989 o Header Parameter Description: Algorithm 990 o Header Parameter Usage Location(s): JWS 991 o Change Controller: IESG 992 o Specification Document(s): Section 4.1.1 of [[ this document ]] 994 o Header Parameter Name: "jku" 995 o Header Parameter Description: JWK Set URL 996 o Header Parameter Usage Location(s): JWS 997 o Change Controller: IESG 998 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1000 o Header Parameter Name: "jwk" 1001 o Header Parameter Description: JSON Web Key 1002 o Header Parameter Usage Location(s): JWS 1003 o Change Controller: IESG 1004 o Specification document(s): Section 4.1.3 of [[ this document ]] 1006 o Header Parameter Name: "kid" 1007 o Header Parameter Description: Key ID 1008 o Header Parameter Usage Location(s): JWS 1009 o Change Controller: IESG 1010 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1012 o Header Parameter Name: "x5u" 1013 o Header Parameter Description: X.509 URL 1014 o Header Parameter Usage Location(s): JWS 1015 o Change Controller: IESG 1016 o Specification Document(s): Section 4.1.5 of [[ this document ]] 1018 o Header Parameter Name: "x5c" 1019 o Header Parameter Description: X.509 Certificate Chain 1020 o Header Parameter Usage Location(s): JWS 1021 o Change Controller: IESG 1022 o Specification Document(s): Section 4.1.6 of [[ this document ]] 1024 o Header Parameter Name: "x5t" 1025 o Header Parameter Description: X.509 Certificate SHA-1 Thumbprint 1026 o Header Parameter Usage Location(s): JWS 1027 o Change Controller: IESG 1028 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1029 o Header Parameter Name: "x5t#S256" 1030 o Header Parameter Description: X.509 Certificate SHA-256 Thumbprint 1031 o Header Parameter Usage Location(s): JWS 1032 o Change Controller: IESG 1033 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1035 o Header Parameter Name: "typ" 1036 o Header Parameter Description: Type 1037 o Header Parameter Usage Location(s): JWS 1038 o Change Controller: IESG 1039 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1041 o Header Parameter Name: "cty" 1042 o Header Parameter Description: Content Type 1043 o Header Parameter Usage Location(s): JWS 1044 o Change Controller: IESG 1045 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1047 o Header Parameter Name: "crit" 1048 o Header Parameter Description: Critical 1049 o Header Parameter Usage Location(s): JWS 1050 o Change Controller: IESG 1051 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1053 9.2. Media Type Registration 1055 9.2.1. Registry Contents 1057 This specification registers the "application/jose" Media Type 1058 [RFC2046] in the MIME Media Types registry [IANA.MediaTypes], which 1059 can be used to indicate that the content is a JWS or JWE object using 1060 the JWS Compact Serialization or the JWE Compact Serialization and 1061 the "application/jose+json" Media Type in the MIME Media Types 1062 registry, which can be used to indicate that the content is a JWS or 1063 JWE object using the JWS JSON Serialization or the JWE JSON 1064 Serialization. 1066 o Type name: application 1067 o Subtype name: jose 1068 o Required parameters: n/a 1069 o Optional parameters: n/a 1070 o Encoding considerations: 8bit; application/jose values are encoded 1071 as a series of base64url encoded values (some of which may be the 1072 empty string) separated by period ('.') characters. 1073 o Security considerations: See the Security Considerations section 1074 of [[ this document ]] 1076 o Interoperability considerations: n/a 1077 o Published specification: [[ this document ]] 1078 o Applications that use this media type: OpenID Connect, Mozilla 1079 Persona, Salesforce, Google, Android, Windows Azure, Xbox One, and 1080 numerous others that use JWTs 1081 o Additional information: Magic number(s): n/a, File extension(s): 1082 n/a, Macintosh file type code(s): n/a 1083 o Person & email address to contact for further information: Michael 1084 B. Jones, mbj@microsoft.com 1085 o Intended usage: COMMON 1086 o Restrictions on usage: none 1087 o Author: Michael B. Jones, mbj@microsoft.com 1088 o Change Controller: IESG 1090 o Type name: application 1091 o Subtype name: jose+json 1092 o Required parameters: n/a 1093 o Optional parameters: n/a 1094 o Encoding considerations: 8bit; application/jose+json values are 1095 represented as a JSON Object; UTF-8 encoding SHOULD be employed 1096 for the JSON object. 1097 o Security considerations: See the Security Considerations section 1098 of [[ this document ]] 1099 o Interoperability considerations: n/a 1100 o Published specification: [[ this document ]] 1101 o Applications that use this media type: TBD 1102 o Additional information: Magic number(s): n/a, File extension(s): 1103 n/a, Macintosh file type code(s): n/a 1104 o Person & email address to contact for further information: Michael 1105 B. Jones, mbj@microsoft.com 1106 o Intended usage: COMMON 1107 o Restrictions on usage: none 1108 o Author: Michael B. Jones, mbj@microsoft.com 1109 o Change Controller: IESG 1111 10. Security Considerations 1113 All of the security issues faced by any cryptographic application 1114 must be faced by a JWS/JWE/JWK agent. Among these issues are 1115 protecting the user's asymmetric private and symmetric secret keys, 1116 preventing various attacks, and helping avoid mistakes such as 1117 inadvertently encrypting a message to the wrong recipient. The 1118 entire list of security considerations is beyond the scope of this 1119 document, but some significant concerns are listed here. 1121 All the security considerations in XML DSIG 2.0 1122 [W3C.NOTE-xmldsig-core2-20130411], also apply to this specification, 1123 other than those that are XML specific. Likewise, many of the best 1124 practices documented in XML Signature Best Practices 1125 [W3C.NOTE-xmldsig-bestpractices-20130411] also apply to this 1126 specification, other than those that are XML specific. 1128 10.1. Key Entropy 1130 Keys are only as strong as the amount of entropy used to generate 1131 them. A minimum of 128 bits of entropy should be used for all keys, 1132 and depending upon the application context, more may be required. In 1133 particular, it may be difficult to generate sufficiently random 1134 values in some browsers and application environments. 1136 10.2. Chosen Plaintext Attacks 1138 Creators of JWSs should not allow third parties to insert arbitrary 1139 content into the message without adding entropy not controlled by the 1140 third party. 1142 10.3. Timing Attacks 1144 When cryptographic algorithms are implemented in such a way that 1145 successful operations take a different amount of time than 1146 unsuccessful operations, attackers may be able to use the time 1147 difference to obtain information about the keys employed. Therefore, 1148 such timing differences must be avoided. 1150 10.4. Differences between Digital Signatures and MACs 1152 While MACs and digital signatures can both be used for integrity 1153 checking, there are some significant differences between the security 1154 properties that each of them provides. These need to be taken into 1155 consideration when designing protocols and selecting the algorithms 1156 to be used in protocols. 1158 Both signatures and MACs provide for integrity checking -- verifying 1159 that the message has not been modified since the integrity value was 1160 computed. However, MACs provide for origination identification only 1161 under specific circumstances. It can normally be assumed that a 1162 private key used for a signature is only in the hands of a single 1163 entity (although perhaps a distributed entity, in the case of 1164 replicated servers); however, a MAC key needs to be in the hands of 1165 all the entities that use it for integrity computation and checking. 1166 This means that origination can only be determined if a MAC key is 1167 known only to two entities and the receiver knows that it did not 1168 create the message. MAC validation cannot be used to prove 1169 origination to a third party. 1171 10.5. SHA-1 Certificate Thumbprints 1173 A SHA-1 hash is used when computing "x5t" (X.509 Certificate SHA-1 1174 Thumbprint) values, for compatibility reasons. Should an effective 1175 means of producing SHA-1 hash collisions be developed, and should an 1176 attacker wish to interfere with the use of a known certificate on a 1177 given system, this could be accomplished by creating another 1178 certificate whose SHA-1 hash value is the same and adding it to the 1179 certificate store used by the intended victim. A prerequisite to 1180 this attack succeeding is the attacker having write access to the 1181 intended victim's certificate store. 1183 Alternatively, the "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) 1184 Header Parameter could be used instead of "x5t". However, at the 1185 time of this writing, no development platform is known to support 1186 SHA-256 certificate thumbprints. 1188 10.6. JSON Security Considerations 1190 Strict JSON [RFC7159] validation is a security requirement. If 1191 malformed JSON is received, then the intent of the sender is 1192 impossible to reliably discern. Ambiguous and potentially 1193 exploitable situations could arise if the JSON parser used does not 1194 reject malformed JSON syntax. In particular, any JSON inputs not 1195 conforming to the JSON-text syntax defined in RFC 7159 input MUST be 1196 rejected in their entirety. 1198 Section 4 of the JSON Data Interchange Format specification [RFC7159] 1199 states "The names within an object SHOULD be unique", whereas this 1200 specification states that "Header Parameter names within this object 1201 MUST be unique; recipients MUST either reject JWSs with duplicate 1202 Header Parameter names or use a JSON parser that returns only the 1203 lexically last duplicate member name, as specified in Section 15.12 1204 (The JSON Object) of ECMAScript 5.1 [ECMAScript]". Thus, this 1205 specification requires that the Section 4 "SHOULD" be treated as a 1206 "MUST" by senders and that it be either treated as a "MUST" or in the 1207 manner specified in ECMAScript 5.1 by receivers. Ambiguous and 1208 potentially exploitable situations could arise if the JSON parser 1209 used does not enforce the uniqueness of member names or returns an 1210 unpredictable value for duplicate member names. 1212 Some JSON parsers might not reject input that contains extra 1213 significant characters after a valid input. For instance, the input 1214 "{"tag":"value"}ABCD" contains a valid JSON-text object followed by 1215 the extra characters "ABCD". Such input MUST be rejected in its 1216 entirety. 1218 10.7. Unicode Comparison Security Considerations 1220 Header Parameter names and algorithm names are Unicode strings. For 1221 security reasons, the representations of these names must be compared 1222 verbatim after performing any escape processing (as per Section 8.3 1223 of [RFC7159]). This means, for instance, that these JSON strings 1224 must compare as being equal ("sig", "\u0073ig"), whereas these must 1225 all compare as being not equal to the first set or to each other 1226 ("SIG", "Sig", "si\u0047"). 1228 JSON strings can contain characters outside the Unicode Basic 1229 Multilingual Plane. For instance, the G clef character (U+1D11E) may 1230 be represented in a JSON string as "\uD834\uDD1E". Ideally, JWS 1231 implementations SHOULD ensure that characters outside the Basic 1232 Multilingual Plane are preserved and compared correctly; 1233 alternatively, if this is not possible due to these characters 1234 exercising limitations present in the underlying JSON implementation, 1235 then input containing them MUST be rejected. 1237 11. References 1239 11.1. Normative References 1241 [ECMAScript] 1242 Ecma International, "ECMAScript Language Specification, 1243 5.1 Edition", ECMA 262, June 2011. 1245 [IANA.MediaTypes] 1246 Internet Assigned Numbers Authority (IANA), "MIME Media 1247 Types", 2005. 1249 [ITU.X690.1994] 1250 International Telecommunications Union, "Information 1251 Technology - ASN.1 encoding rules: Specification of Basic 1252 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1253 Distinguished Encoding Rules (DER)", ITU-T Recommendation 1254 X.690, 1994. 1256 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1257 draft-ietf-jose-json-web-algorithms (work in progress), 1258 June 2014. 1260 [JWK] Jones, M., "JSON Web Key (JWK)", 1261 draft-ietf-jose-json-web-key (work in progress), 1262 June 2014. 1264 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 1265 Mail: Part I: Message Encryption and Authentication 1266 Procedures", RFC 1421, February 1993. 1268 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1269 Extensions (MIME) Part One: Format of Internet Message 1270 Bodies", RFC 2045, November 1996. 1272 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1273 Extensions (MIME) Part Two: Media Types", RFC 2046, 1274 November 1996. 1276 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1277 Requirement Levels", BCP 14, RFC 2119, March 1997. 1279 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1281 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1282 10646", STD 63, RFC 3629, November 2003. 1284 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1285 Resource Identifier (URI): Generic Syntax", STD 66, 1286 RFC 3986, January 2005. 1288 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1289 Encodings", RFC 4648, October 2006. 1291 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1292 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1294 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1295 Housley, R., and W. Polk, "Internet X.509 Public Key 1296 Infrastructure Certificate and Certificate Revocation List 1297 (CRL) Profile", RFC 5280, May 2008. 1299 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1300 Verification of Domain-Based Application Service Identity 1301 within Internet Public Key Infrastructure Using X.509 1302 (PKIX) Certificates in the Context of Transport Layer 1303 Security (TLS)", RFC 6125, March 2011. 1305 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1306 Interchange Format", RFC 7159, March 2014. 1308 [USASCII] American National Standards Institute, "Coded Character 1309 Set -- 7-bit American Standard Code for Information 1310 Interchange", ANSI X3.4, 1986. 1312 11.2. Informative References 1314 [CanvasApp] 1315 Facebook, "Canvas Applications", 2010. 1317 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 1318 September 2010. 1320 [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 1321 draft-ietf-jose-json-web-encryption (work in progress), 1322 June 2014. 1324 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1325 (JWT)", draft-ietf-oauth-json-web-token (work in 1326 progress), June 2014. 1328 [MagicSignatures] 1329 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 1330 Signatures", January 2011. 1332 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1333 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1334 July 2005. 1336 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1337 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1338 May 2008. 1340 [W3C.NOTE-xmldsig-bestpractices-20130411] 1341 Hirsch, F. and P. Datta, "XML Signature Best Practices", 1342 World Wide Web Consortium Note NOTE-xmldsig-bestpractices- 1343 20130411, April 2013, . 1346 [W3C.NOTE-xmldsig-core2-20130411] 1347 Eastlake, D., Reagle, J., Solo, D., Hirsch, F., Roessler, 1348 T., Yiu, K., Datta, P., and S. Cantor, "XML Signature 1349 Syntax and Processing Version 2.0", World Wide Web 1350 Consortium Note NOTE-xmldsig-core2-20130411, April 2013, 1351 . 1353 Appendix A. JWS Examples 1355 This section provides several examples of JWSs. While the first 1356 three examples all represent JSON Web Tokens (JWTs) [JWT], the 1357 payload can be any octet sequence, as shown in Appendix A.4. 1359 A.1. Example JWS using HMAC SHA-256 1361 A.1.1. Encoding 1363 The following example JWS Protected Header declares that the data 1364 structure is a JSON Web Token (JWT) [JWT] and the JWS Signing Input 1365 is secured using the HMAC SHA-256 algorithm. 1367 {"typ":"JWT", 1368 "alg":"HS256"} 1370 To remove potential ambiguities in the representation of the JSON 1371 object above, the actual octet sequence representing UTF8(JWS 1372 Protected Header) used in this example is also included below. (Note 1373 that ambiguities can arise due to differing platform representations 1374 of line breaks (CRLF versus LF), differing spacing at the beginning 1375 and ends of lines, whether the last line has a terminating line break 1376 or not, and other causes. In the representation used in this 1377 example, the first line has no leading or trailing spaces, a CRLF 1378 line break (13, 10) occurs between the first and second lines, the 1379 second line has one leading space (32) and no trailing spaces, and 1380 the last line does not have a terminating line break.) The octets 1381 representing UTF8(JWS Protected Header) in this example (using JSON 1382 array notation) are: 1384 [123, 34, 116, 121, 112, 34, 58, 34, 74, 87, 84, 34, 44, 13, 10, 32, 1385 34, 97, 108, 103, 34, 58, 34, 72, 83, 50, 53, 54, 34, 125] 1387 Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected 1388 Header)) gives this value: 1390 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 1392 The JWS Payload used in this example is the octets of the UTF-8 1393 representation of the JSON object below. (Note that the payload can 1394 be any base64url encoded octet sequence, and need not be a base64url 1395 encoded JSON object.) 1397 {"iss":"joe", 1398 "exp":1300819380, 1399 "http://example.com/is_root":true} 1401 The following octet sequence, which is the UTF-8 representation used 1402 in this example for the JSON object above, is the JWS Payload: 1404 [123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10, 1405 32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56, 1406 48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97, 1407 109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111, 1408 111, 116, 34, 58, 116, 114, 117, 101, 125] 1410 Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected 1411 Header)) gives this value (with line breaks for display purposes 1412 only): 1414 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1415 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1417 Combining these as BASE64URL(UTF8(JWS Protected Header)) || '.' || 1418 BASE64URL(JWS Payload) gives this string (with line breaks for 1419 display purposes only): 1421 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 1422 . 1423 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1424 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1426 The resulting JWS Signing Input value, which is the ASCII 1427 representation of above string, is the following octet sequence 1428 (using JSON array notation): 1430 [101, 121, 74, 48, 101, 88, 65, 105, 79, 105, 74, 75, 86, 49, 81, 1431 105, 76, 65, 48, 75, 73, 67, 74, 104, 98, 71, 99, 105, 79, 105, 74, 1432 73, 85, 122, 73, 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 1433 77, 105, 79, 105, 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 1434 74, 108, 101, 72, 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 1435 107, 122, 79, 68, 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 1436 72, 65, 54, 76, 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 1437 109, 78, 118, 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 1438 106, 112, 48, 99, 110, 86, 108, 102, 81] 1440 HMACs are generated using keys. This example uses the symmetric key 1441 represented in JSON Web Key [JWK] format below (with line breaks 1442 within values for display purposes only): 1444 {"kty":"oct", 1445 "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75 1446 aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow" 1447 } 1449 Running the HMAC SHA-256 algorithm on the JWS Signing Input with this 1450 key yields this JWS Signature octet sequence: 1452 [116, 24, 223, 180, 151, 153, 224, 37, 79, 250, 96, 125, 216, 173, 1453 187, 186, 22, 212, 37, 77, 105, 214, 191, 240, 91, 88, 5, 88, 83, 1454 132, 141, 121] 1455 Encoding this JWS Signature as BASE64URL(JWS Signature) gives this 1456 value: 1458 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 1460 Concatenating these values in the order Header.Payload.Signature with 1461 period ('.') characters between the parts yields this complete JWS 1462 representation using the JWS Compact Serialization (with line breaks 1463 for display purposes only): 1465 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 1466 . 1467 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1468 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1469 . 1470 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 1472 A.1.2. Validating 1474 Since the "alg" Header Parameter is "HS256", we validate the HMAC 1475 SHA-256 value contained in the JWS Signature. 1477 To validate the HMAC value, we repeat the previous process of using 1478 the correct key and the JWS Signing Input (which is the initial 1479 substring of the JWS Compact Serialization representation up until 1480 but not including the second period character) as input to the HMAC 1481 SHA-256 function and then taking the output and determining if it 1482 matches the JWS Signature (which is base64url decoded from the value 1483 encoded in the JWS representation). If it matches exactly, the HMAC 1484 has been validated. 1486 A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 1488 A.2.1. Encoding 1490 The JWS Protected Header in this example is different from the 1491 previous example in two ways: First, because a different algorithm is 1492 being used, the "alg" value is different. Second, for illustration 1493 purposes only, the optional "typ" parameter is not used. (This 1494 difference is not related to the algorithm employed.) The JWS 1495 Protected Header used is: 1497 {"alg":"RS256"} 1499 The octets representing UTF8(JWS Protected Header) in this example 1500 (using JSON array notation) are: 1502 [123, 34, 97, 108, 103, 34, 58, 34, 82, 83, 50, 53, 54, 34, 125] 1503 Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected 1504 Header)) gives this value: 1506 eyJhbGciOiJSUzI1NiJ9 1508 The JWS Payload used in this example, which follows, is the same as 1509 in the previous example. Since the BASE64URL(JWS Payload) value will 1510 therefore be the same, its computation is not repeated here. 1512 {"iss":"joe", 1513 "exp":1300819380, 1514 "http://example.com/is_root":true} 1516 Combining these as BASE64URL(UTF8(JWS Protected Header)) || '.' || 1517 BASE64URL(JWS Payload) gives this string (with line breaks for 1518 display purposes only): 1520 eyJhbGciOiJSUzI1NiJ9 1521 . 1522 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1523 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1525 The resulting JWS Signing Input value, which is the ASCII 1526 representation of above string, is the following octet sequence: 1528 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 122, 73, 1529 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, 1530 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 74, 108, 101, 72, 1531 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 107, 122, 79, 68, 1532 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 72, 65, 54, 76, 1533 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 109, 78, 118, 1534 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48, 1535 99, 110, 86, 108, 102, 81] 1537 This example uses the RSA key represented in JSON Web Key [JWK] 1538 format below (with line breaks within values for display purposes 1539 only): 1541 {"kty":"RSA", 1542 "n":"ofgWCuLjybRlzo0tZWJjNiuSfb4p4fAkd_wWJcyQoTbji9k0l8W26mPddx 1543 HmfHQp-Vaw-4qPCJrcS2mJPMEzP1Pt0Bm4d4QlL-yRT-SFd2lZS-pCgNMs 1544 D1W_YpRPEwOWvG6b32690r2jZ47soMZo9wGzjb_7OMg0LOL-bSf63kpaSH 1545 SXndS5z5rexMdbBYUsLA9e-KXBdQOS-UTo7WTBEMa2R2CapHg665xsmtdV 1546 MTBQY4uDZlxvb3qCo5ZwKh9kG4LT6_I5IhlJH7aGhyxXFvUK-DWNmoudF8 1547 NAco9_h9iaGNj8q2ethFkMLs91kzk2PAcDTW9gb54h4FRWyuXpoQ", 1548 "e":"AQAB", 1549 "d":"Eq5xpGnNCivDflJsRQBXHx1hdR1k6Ulwe2JZD50LpXyWPEAeP88vLNO97I 1550 jlA7_GQ5sLKMgvfTeXZx9SE-7YwVol2NXOoAJe46sui395IW_GO-pWJ1O0 1551 BkTGoVEn2bKVRUCgu-GjBVaYLU6f3l9kJfFNS3E0QbVdxzubSu3Mkqzjkn 1552 439X0M_V51gfpRLI9JYanrC4D4qAdGcopV_0ZHHzQlBjudU2QvXt4ehNYT 1553 CBr6XCLQUShb1juUO1ZdiYoFaFQT5Tw8bGUl_x_jTj3ccPDVZFD9pIuhLh 1554 BOneufuBiB4cS98l2SR_RQyGWSeWjnczT0QU91p1DhOVRuOopznQ" 1555 } 1557 The RSA private key is then passed to the RSA signing function, which 1558 also takes the hash type, SHA-256, and the JWS Signing Input as 1559 inputs. The result of the digital signature is an octet sequence, 1560 which represents a big endian integer. In this example, it is: 1562 [112, 46, 33, 137, 67, 232, 143, 209, 30, 181, 216, 45, 191, 120, 69, 1563 243, 65, 6, 174, 27, 129, 255, 247, 115, 17, 22, 173, 209, 113, 125, 1564 131, 101, 109, 66, 10, 253, 60, 150, 238, 221, 115, 162, 102, 62, 81, 1565 102, 104, 123, 0, 11, 135, 34, 110, 1, 135, 237, 16, 115, 249, 69, 1566 229, 130, 173, 252, 239, 22, 216, 90, 121, 142, 232, 198, 109, 219, 1567 61, 184, 151, 91, 23, 208, 148, 2, 190, 237, 213, 217, 217, 112, 7, 1568 16, 141, 178, 129, 96, 213, 248, 4, 12, 167, 68, 87, 98, 184, 31, 1569 190, 127, 249, 217, 46, 10, 231, 111, 36, 242, 91, 51, 187, 230, 244, 1570 74, 230, 30, 177, 4, 10, 203, 32, 4, 77, 62, 249, 18, 142, 212, 1, 1571 48, 121, 91, 212, 189, 59, 65, 238, 202, 208, 102, 171, 101, 25, 129, 1572 253, 228, 141, 247, 127, 55, 45, 195, 139, 159, 175, 221, 59, 239, 1573 177, 139, 93, 163, 204, 60, 46, 176, 47, 158, 58, 65, 214, 18, 202, 1574 173, 21, 145, 18, 115, 160, 95, 35, 185, 232, 56, 250, 175, 132, 157, 1575 105, 132, 41, 239, 90, 30, 136, 121, 130, 54, 195, 212, 14, 96, 69, 1576 34, 165, 68, 200, 242, 122, 122, 45, 184, 6, 99, 209, 108, 247, 202, 1577 234, 86, 222, 64, 92, 178, 33, 90, 69, 178, 194, 85, 102, 181, 90, 1578 193, 167, 72, 160, 112, 223, 200, 163, 42, 70, 149, 67, 208, 25, 238, 1579 251, 71] 1581 Encoding the signature as BASE64URL(JWS Signature) produces this 1582 value (with line breaks for display purposes only): 1584 cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7 1585 AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4 1586 BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K 1587 0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqv 1588 hJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrB 1589 p0igcN_IoypGlUPQGe77Rw 1591 Concatenating these values in the order Header.Payload.Signature with 1592 period ('.') characters between the parts yields this complete JWS 1593 representation using the JWS Compact Serialization (with line breaks 1594 for display purposes only): 1596 eyJhbGciOiJSUzI1NiJ9 1597 . 1598 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1599 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1600 . 1601 cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7 1602 AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4 1603 BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K 1604 0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqv 1605 hJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrB 1606 p0igcN_IoypGlUPQGe77Rw 1608 A.2.2. Validating 1610 Since the "alg" Header Parameter is "RS256", we validate the RSASSA- 1611 PKCS-v1_5 SHA-256 digital signature contained in the JWS Signature. 1613 Validating the JWS Signature is a bit different from the previous 1614 example. We pass the public key (n, e), the JWS Signature (which is 1615 base64url decoded from the value encoded in the JWS representation), 1616 and the JWS Signing Input (which is the initial substring of the JWS 1617 Compact Serialization representation up until but not including the 1618 second period character) to an RSASSA-PKCS-v1_5 signature verifier 1619 that has been configured to use the SHA-256 hash function. 1621 A.3. Example JWS using ECDSA P-256 SHA-256 1623 A.3.1. Encoding 1625 The JWS Protected Header for this example differs from the previous 1626 example because a different algorithm is being used. The JWS 1627 Protected Header used is: 1629 {"alg":"ES256"} 1631 The octets representing UTF8(JWS Protected Header) in this example 1632 (using JSON array notation) are: 1634 [123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 50, 53, 54, 34, 125] 1636 Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected 1637 Header)) gives this value: 1639 eyJhbGciOiJFUzI1NiJ9 1641 The JWS Payload used in this example, which follows, is the same as 1642 in the previous examples. Since the BASE64URL(JWS Payload) value 1643 will therefore be the same, its computation is not repeated here. 1645 {"iss":"joe", 1646 "exp":1300819380, 1647 "http://example.com/is_root":true} 1649 Combining these as BASE64URL(UTF8(JWS Protected Header)) || '.' || 1650 BASE64URL(JWS Payload) gives this string (with line breaks for 1651 display purposes only): 1653 eyJhbGciOiJFUzI1NiJ9 1654 . 1655 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1656 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1658 The resulting JWS Signing Input value, which is the ASCII 1659 representation of above string, is the following octet sequence: 1661 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 70, 85, 122, 73, 1662 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, 1663 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 74, 108, 101, 72, 1664 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 107, 122, 79, 68, 1665 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 72, 65, 54, 76, 1666 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 109, 78, 118, 1667 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48, 1668 99, 110, 86, 108, 102, 81] 1670 This example uses the elliptic curve key represented in JSON Web Key 1671 [JWK] format below: 1673 {"kty":"EC", 1674 "crv":"P-256", 1675 "x":"f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU", 1676 "y":"x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0", 1677 "d":"jpsQnnGQmL-YBIffH1136cspYG6-0iY7X1fCE9-E9LI" 1678 } 1680 The ECDSA private part d is then passed to an ECDSA signing function, 1681 which also takes the curve type, P-256, the hash type, SHA-256, and 1682 the JWS Signing Input as inputs. The result of the digital signature 1683 is the EC point (R, S), where R and S are unsigned integers. In this 1684 example, the R and S values, given as octet sequences representing 1685 big endian integers are: 1687 +--------+----------------------------------------------------------+ 1688 | Result | Value | 1689 | Name | | 1690 +--------+----------------------------------------------------------+ 1691 | R | [14, 209, 33, 83, 121, 99, 108, 72, 60, 47, 127, 21, 88, | 1692 | | 7, 212, 2, 163, 178, 40, 3, 58, 249, 124, 126, 23, 129, | 1693 | | 154, 195, 22, 158, 166, 101] | 1694 | S | [197, 10, 7, 211, 140, 60, 112, 229, 216, 241, 45, 175, | 1695 | | 8, 74, 84, 128, 166, 101, 144, 197, 242, 147, 80, 154, | 1696 | | 143, 63, 127, 138, 131, 163, 84, 213] | 1697 +--------+----------------------------------------------------------+ 1699 The JWS Signature is the value R || S. Encoding the signature as 1700 BASE64URL(JWS Signature) produces this value (with line breaks for 1701 display purposes only): 1703 DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSA 1704 pmWQxfKTUJqPP3-Kg6NU1Q 1706 Concatenating these values in the order Header.Payload.Signature with 1707 period ('.') characters between the parts yields this complete JWS 1708 representation using the JWS Compact Serialization (with line breaks 1709 for display purposes only): 1711 eyJhbGciOiJFUzI1NiJ9 1712 . 1713 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1714 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1715 . 1716 DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSA 1717 pmWQxfKTUJqPP3-Kg6NU1Q 1719 A.3.2. Validating 1721 Since the "alg" Header Parameter is "ES256", we validate the ECDSA 1722 P-256 SHA-256 digital signature contained in the JWS Signature. 1724 Validating the JWS Signature is a bit different from the previous 1725 examples. We need to split the 64 member octet sequence of the JWS 1726 Signature (which is base64url decoded from the value encoded in the 1727 JWS representation) into two 32 octet sequences, the first 1728 representing R and the second S. We then pass the public key (x, y), 1729 the signature (R, S), and the JWS Signing Input (which is the initial 1730 substring of the JWS Compact Serialization representation up until 1731 but not including the second period character) to an ECDSA signature 1732 verifier that has been configured to use the P-256 curve with the 1733 SHA-256 hash function. 1735 A.4. Example JWS using ECDSA P-521 SHA-512 1737 A.4.1. Encoding 1739 The JWS Protected Header for this example differs from the previous 1740 example because different ECDSA curves and hash functions are used. 1741 The JWS Protected Header used is: 1743 {"alg":"ES512"} 1745 The octets representing UTF8(JWS Protected Header) in this example 1746 (using JSON array notation) are: 1748 [123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 53, 49, 50, 34, 125] 1750 Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected 1751 Header)) gives this value: 1753 eyJhbGciOiJFUzUxMiJ9 1755 The JWS Payload used in this example, is the ASCII string "Payload". 1756 The representation of this string is the octet sequence: 1758 [80, 97, 121, 108, 111, 97, 100] 1760 Encoding this JWS Payload as BASE64URL(JWS Payload) gives this value: 1762 UGF5bG9hZA 1764 Combining these as BASE64URL(UTF8(JWS Protected Header)) || '.' || 1765 BASE64URL(JWS Payload) gives this string: 1767 eyJhbGciOiJFUzUxMiJ9.UGF5bG9hZA 1769 The resulting JWS Signing Input value, which is the ASCII 1770 representation of above string, is the following octet sequence: 1772 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 70, 85, 122, 85, 1773 120, 77, 105, 74, 57, 46, 85, 71, 70, 53, 98, 71, 57, 104, 90, 65] 1775 This example uses the elliptic curve key represented in JSON Web Key 1776 [JWK] format below (with line breaks within values for display 1777 purposes only): 1779 {"kty":"EC", 1780 "crv":"P-521", 1781 "x":"AekpBQ8ST8a8VcfVOTNl353vSrDCLLJXmPk06wTjxrrjcBpXp5EOnYG_ 1782 NjFZ6OvLFV1jSfS9tsz4qUxcWceqwQGk", 1783 "y":"ADSmRA43Z1DSNx_RvcLI87cdL07l6jQyyBXMoxVg_l2Th-x3S1WDhjDl 1784 y79ajL4Kkd0AZMaZmh9ubmf63e3kyMj2", 1785 "d":"AY5pb7A0UFiB3RELSD64fTLOSV_jazdF7fLYyuTw8lOfRhWg6Y6rUrPA 1786 xerEzgdRhajnu0ferB0d53vM9mE15j2C" 1787 } 1789 The ECDSA private part d is then passed to an ECDSA signing function, 1790 which also takes the curve type, P-521, the hash type, SHA-512, and 1791 the JWS Signing Input as inputs. The result of the digital signature 1792 is the EC point (R, S), where R and S are unsigned integers. In this 1793 example, the R and S values, given as octet sequences representing 1794 big endian integers are: 1796 +--------+----------------------------------------------------------+ 1797 | Result | Value | 1798 | Name | | 1799 +--------+----------------------------------------------------------+ 1800 | R | [1, 220, 12, 129, 231, 171, 194, 209, 232, 135, 233, | 1801 | | 117, 247, 105, 122, 210, 26, 125, 192, 1, 217, 21, 82, | 1802 | | 91, 45, 240, 255, 83, 19, 34, 239, 71, 48, 157, 147, | 1803 | | 152, 105, 18, 53, 108, 163, 214, 68, 231, 62, 153, 150, | 1804 | | 106, 194, 164, 246, 72, 143, 138, 24, 50, 129, 223, 133, | 1805 | | 206, 209, 172, 63, 237, 119, 109] | 1806 | S | [0, 111, 6, 105, 44, 5, 41, 208, 128, 61, 152, 40, 92, | 1807 | | 61, 152, 4, 150, 66, 60, 69, 247, 196, 170, 81, 193, | 1808 | | 199, 78, 59, 194, 169, 16, 124, 9, 143, 42, 142, 131, | 1809 | | 48, 206, 238, 34, 175, 83, 203, 220, 159, 3, 107, 155, | 1810 | | 22, 27, 73, 111, 68, 68, 21, 238, 144, 229, 232, 148, | 1811 | | 188, 222, 59, 242, 103] | 1812 +--------+----------------------------------------------------------+ 1814 The JWS Signature is the value R || S. Encoding the signature as 1815 BASE64URL(JWS Signature) produces this value (with line breaks for 1816 display purposes only): 1818 AdwMgeerwtHoh-l192l60hp9wAHZFVJbLfD_UxMi70cwnZOYaRI1bKPWROc-mZZq 1819 wqT2SI-KGDKB34XO0aw_7XdtAG8GaSwFKdCAPZgoXD2YBJZCPEX3xKpRwcdOO8Kp 1820 EHwJjyqOgzDO7iKvU8vcnwNrmxYbSW9ERBXukOXolLzeO_Jn 1822 Concatenating these values in the order Header.Payload.Signature with 1823 period ('.') characters between the parts yields this complete JWS 1824 representation using the JWS Compact Serialization (with line breaks 1825 for display purposes only): 1827 eyJhbGciOiJFUzUxMiJ9 1828 . 1829 UGF5bG9hZA 1830 . 1831 AdwMgeerwtHoh-l192l60hp9wAHZFVJbLfD_UxMi70cwnZOYaRI1bKPWROc-mZZq 1832 wqT2SI-KGDKB34XO0aw_7XdtAG8GaSwFKdCAPZgoXD2YBJZCPEX3xKpRwcdOO8Kp 1833 EHwJjyqOgzDO7iKvU8vcnwNrmxYbSW9ERBXukOXolLzeO_Jn 1835 A.4.2. Validating 1837 Since the "alg" Header Parameter is "ES512", we validate the ECDSA 1838 P-521 SHA-512 digital signature contained in the JWS Signature. 1840 Validating this JWS Signature is very similar to the previous 1841 example. We need to split the 132 member octet sequence of the JWS 1842 Signature into two 66 octet sequences, the first representing R and 1843 the second S. We then pass the public key (x, y), the signature (R, 1844 S), and the JWS Signing Input to an ECDSA signature verifier that has 1845 been configured to use the P-521 curve with the SHA-512 hash 1846 function. 1848 A.5. Example Plaintext JWS 1850 The following example JWS Protected Header declares that the encoded 1851 object is a Plaintext JWS: 1853 {"alg":"none"} 1855 Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected 1856 Header)) gives this value: 1858 eyJhbGciOiJub25lIn0 1860 The JWS Payload used in this example, which follows, is the same as 1861 in the previous examples. Since the BASE64URL(JWS Payload) value 1862 will therefore be the same, its computation is not repeated here. 1864 {"iss":"joe", 1865 "exp":1300819380, 1866 "http://example.com/is_root":true} 1868 The JWS Signature is the empty octet string and BASE64URL(JWS 1869 Signature) is the empty string. 1871 Concatenating these parts in the order Header.Payload.Signature with 1872 period ('.') characters between the parts yields this complete JWS 1873 (with line breaks for display purposes only): 1875 eyJhbGciOiJub25lIn0 1876 . 1877 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1878 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1879 . 1881 A.6. Example JWS Using JWS JSON Serialization 1883 This section contains an example using the JWS JSON Serialization. 1884 This example demonstrates the capability for conveying multiple 1885 digital signatures and/or MACs for the same payload. 1887 The JWS Payload used in this example is the same as that used in the 1888 examples in Appendix A.2 and Appendix A.3 (with line breaks for 1889 display purposes only): 1891 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1892 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1894 Two digital signatures are used in this example: the first using 1895 RSASSA-PKCS-v1_5 SHA-256 and the second using ECDSA P-256 SHA-256. 1896 For the first, the JWS Protected Header and key are the same as in 1897 Appendix A.2, resulting in the same JWS Signature value; therefore, 1898 its computation is not repeated here. For the second, the JWS 1899 Protected Header and key are the same as in Appendix A.3, resulting 1900 in the same JWS Signature value; therefore, its computation is not 1901 repeated here. 1903 A.6.1. JWS Per-Signature Protected Headers 1905 The JWS Protected Header value used for the first signature is: 1907 {"alg":"RS256"} 1909 Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected 1910 Header)) gives this value: 1912 eyJhbGciOiJSUzI1NiJ9 1914 The JWS Protected Header value used for the second signature is: 1916 {"alg":"ES256"} 1918 Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected 1919 Header)) gives this value: 1921 eyJhbGciOiJFUzI1NiJ9 1923 A.6.2. JWS Per-Signature Unprotected Headers 1925 Key ID values are supplied for both keys using per-signature Header 1926 Parameters. The two values used to represent these Key IDs are: 1928 {"kid":"2010-12-29"} 1930 and 1932 {"kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"} 1934 A.6.3. Complete JOSE Header Values 1936 Combining the protected and unprotected header values supplied, the 1937 JOSE Header values used for the first and second signatures 1938 respectively are: 1940 {"alg":"RS256", 1941 "kid":"2010-12-29"} 1943 and 1945 {"alg":"ES256", 1946 "kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"} 1948 A.6.4. Complete JWS JSON Serialization Representation 1950 The complete JSON Web Signature JSON Serialization for these values 1951 is as follows (with line breaks within values for display purposes 1952 only): 1954 {"payload": 1955 "eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGF 1956 tcGxlLmNvbS9pc19yb290Ijp0cnVlfQ", 1957 "signatures":[ 1958 {"protected":"eyJhbGciOiJSUzI1NiJ9", 1959 "header": 1960 {"kid":"2010-12-29"}, 1961 "signature": 1962 "cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZ 1963 mh7AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjb 1964 KBYNX4BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHl 1965 b1L07Qe7K0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZES 1966 c6BfI7noOPqvhJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AX 1967 LIhWkWywlVmtVrBp0igcN_IoypGlUPQGe77Rw"}, 1968 {"protected":"eyJhbGciOiJFUzI1NiJ9", 1969 "header": 1970 {"kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"}, 1971 "signature": 1972 "DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8IS 1973 lSApmWQxfKTUJqPP3-Kg6NU1Q"}] 1974 } 1976 Appendix B. "x5c" (X.509 Certificate Chain) Example 1978 The JSON array below is an example of a certificate chain that could 1979 be used as the value of an "x5c" (X.509 Certificate Chain) Header 1980 Parameter, per Section 4.1.6. Note that since these strings contain 1981 base64 encoded (not base64url encoded) values, they are allowed to 1982 contain white space and line breaks. 1984 ["MIIE3jCCA8agAwIBAgICAwEwDQYJKoZIhvcNAQEFBQAwYzELMAkGA1UEBhMCVVM 1985 xITAfBgNVBAoTGFRoZSBHbyBEYWRkeSBHcm91cCwgSW5jLjExMC8GA1UECxMoR2 1986 8gRGFkZHkgQ2xhc3MgMiBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTAeFw0wNjExM 1987 TYwMTU0MzdaFw0yNjExMTYwMTU0MzdaMIHKMQswCQYDVQQGEwJVUzEQMA4GA1UE 1988 CBMHQXJpem9uYTETMBEGA1UEBxMKU2NvdHRzZGFsZTEaMBgGA1UEChMRR29EYWR 1989 keS5jb20sIEluYy4xMzAxBgNVBAsTKmh0dHA6Ly9jZXJ0aWZpY2F0ZXMuZ29kYW 1990 RkeS5jb20vcmVwb3NpdG9yeTEwMC4GA1UEAxMnR28gRGFkZHkgU2VjdXJlIENlc 1991 nRpZmljYXRpb24gQXV0aG9yaXR5MREwDwYDVQQFEwgwNzk2OTI4NzCCASIwDQYJ 1992 KoZIhvcNAQEBBQADggEPADCCAQoCggEBAMQt1RWMnCZM7DI161+4WQFapmGBWTt 1993 wY6vj3D3HKrjJM9N55DrtPDAjhI6zMBS2sofDPZVUBJ7fmd0LJR4h3mUpfjWoqV 1994 Tr9vcyOdQmVZWt7/v+WIbXnvQAjYwqDL1CBM6nPwT27oDyqu9SoWlm2r4arV3aL 1995 GbqGmu75RpRSgAvSMeYddi5Kcju+GZtCpyz8/x4fKL4o/K1w/O5epHBp+YlLpyo 1996 7RJlbmr2EkRTcDCVw5wrWCs9CHRK8r5RsL+H0EwnWGu1NcWdrxcx+AuP7q2BNgW 1997 JCJjPOq8lh8BJ6qf9Z/dFjpfMFDniNoW1fho3/Rb2cRGadDAW/hOUoz+EDU8CAw 1998 EAAaOCATIwggEuMB0GA1UdDgQWBBT9rGEyk2xF1uLuhV+auud2mWjM5zAfBgNVH 1999 SMEGDAWgBTSxLDSkdRMEXGzYcs9of7dqGrU4zASBgNVHRMBAf8ECDAGAQH/AgEA 2000 MDMGCCsGAQUFBwEBBCcwJTAjBggrBgEFBQcwAYYXaHR0cDovL29jc3AuZ29kYWR 2001 keS5jb20wRgYDVR0fBD8wPTA7oDmgN4Y1aHR0cDovL2NlcnRpZmljYXRlcy5nb2 2002 RhZGR5LmNvbS9yZXBvc2l0b3J5L2dkcm9vdC5jcmwwSwYDVR0gBEQwQjBABgRVH 2003 SAAMDgwNgYIKwYBBQUHAgEWKmh0dHA6Ly9jZXJ0aWZpY2F0ZXMuZ29kYWRkeS5j 2004 b20vcmVwb3NpdG9yeTAOBgNVHQ8BAf8EBAMCAQYwDQYJKoZIhvcNAQEFBQADggE 2005 BANKGwOy9+aG2Z+5mC6IGOgRQjhVyrEp0lVPLN8tESe8HkGsz2ZbwlFalEzAFPI 2006 UyIXvJxwqoJKSQ3kbTJSMUA2fCENZvD117esyfxVgqwcSeIaha86ykRvOe5GPLL 2007 5CkKSkB2XIsKd83ASe8T+5o0yGPwLPk9Qnt0hCqU7S+8MxZC9Y7lhyVJEnfzuz9 2008 p0iRFEUOOjZv2kWzRaJBydTXRE4+uXR21aITVSzGh6O1mawGhId/dQb8vxRMDsx 2009 uxN89txJx9OjxUUAiKEngHUuHqDTMBqLdElrRhjZkAzVvb3du6/KFUJheqwNTrZ 2010 EjYx8WnM25sgVjOuH0aBsXBTWVU+4=", 2011 "MIIE+zCCBGSgAwIBAgICAQ0wDQYJKoZIhvcNAQEFBQAwgbsxJDAiBgNVBAcTG1Z 2012 hbGlDZXJ0IFZhbGlkYXRpb24gTmV0d29yazEXMBUGA1UEChMOVmFsaUNlcnQsIE 2013 luYy4xNTAzBgNVBAsTLFZhbGlDZXJ0IENsYXNzIDIgUG9saWN5IFZhbGlkYXRpb 2014 24gQXV0aG9yaXR5MSEwHwYDVQQDExhodHRwOi8vd3d3LnZhbGljZXJ0LmNvbS8x 2015 IDAeBgkqhkiG9w0BCQEWEWluZm9AdmFsaWNlcnQuY29tMB4XDTA0MDYyOTE3MDY 2016 yMFoXDTI0MDYyOTE3MDYyMFowYzELMAkGA1UEBhMCVVMxITAfBgNVBAoTGFRoZS 2017 BHbyBEYWRkeSBHcm91cCwgSW5jLjExMC8GA1UECxMoR28gRGFkZHkgQ2xhc3MgM 2018 iBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTCCASAwDQYJKoZIhvcNAQEBBQADggEN 2019 ADCCAQgCggEBAN6d1+pXGEmhW+vXX0iG6r7d/+TvZxz0ZWizV3GgXne77ZtJ6XC 2020 APVYYYwhv2vLM0D9/AlQiVBDYsoHUwHU9S3/Hd8M+eKsaA7Ugay9qK7HFiH7Eux 2021 6wwdhFJ2+qN1j3hybX2C32qRe3H3I2TqYXP2WYktsqbl2i/ojgC95/5Y0V4evLO 2022 tXiEqITLdiOr18SPaAIBQi2XKVlOARFmR6jYGB0xUGlcmIbYsUfb18aQr4CUWWo 2023 riMYavx4A6lNf4DD+qta/KFApMoZFv6yyO9ecw3ud72a9nmYvLEHZ6IVDd2gWMZ 2024 Eewo+YihfukEHU1jPEX44dMX4/7VpkI+EdOqXG68CAQOjggHhMIIB3TAdBgNVHQ 2025 4EFgQU0sSw0pHUTBFxs2HLPaH+3ahq1OMwgdIGA1UdIwSByjCBx6GBwaSBvjCBu 2026 zEkMCIGA1UEBxMbVmFsaUNlcnQgVmFsaWRhdGlvbiBOZXR3b3JrMRcwFQYDVQQK 2027 Ew5WYWxpQ2VydCwgSW5jLjE1MDMGA1UECxMsVmFsaUNlcnQgQ2xhc3MgMiBQb2x 2028 pY3kgVmFsaWRhdGlvbiBBdXRob3JpdHkxITAfBgNVBAMTGGh0dHA6Ly93d3cudm 2029 FsaWNlcnQuY29tLzEgMB4GCSqGSIb3DQEJARYRaW5mb0B2YWxpY2VydC5jb22CA 2030 QEwDwYDVR0TAQH/BAUwAwEB/zAzBggrBgEFBQcBAQQnMCUwIwYIKwYBBQUHMAGG 2031 F2h0dHA6Ly9vY3NwLmdvZGFkZHkuY29tMEQGA1UdHwQ9MDswOaA3oDWGM2h0dHA 2032 6Ly9jZXJ0aWZpY2F0ZXMuZ29kYWRkeS5jb20vcmVwb3NpdG9yeS9yb290LmNybD 2033 BLBgNVHSAERDBCMEAGBFUdIAAwODA2BggrBgEFBQcCARYqaHR0cDovL2NlcnRpZ 2034 mljYXRlcy5nb2RhZGR5LmNvbS9yZXBvc2l0b3J5MA4GA1UdDwEB/wQEAwIBBjAN 2035 BgkqhkiG9w0BAQUFAAOBgQC1QPmnHfbq/qQaQlpE9xXUhUaJwL6e4+PrxeNYiY+ 2036 Sn1eocSxI0YGyeR+sBjUZsE4OWBsUs5iB0QQeyAfJg594RAoYC5jcdnplDQ1tgM 2037 QLARzLrUc+cb53S8wGd9D0VmsfSxOaFIqII6hR8INMqzW/Rn453HWkrugp++85j 2038 09VZw==", 2039 "MIIC5zCCAlACAQEwDQYJKoZIhvcNAQEFBQAwgbsxJDAiBgNVBAcTG1ZhbGlDZXJ 2040 0IFZhbGlkYXRpb24gTmV0d29yazEXMBUGA1UEChMOVmFsaUNlcnQsIEluYy4xNT 2041 AzBgNVBAsTLFZhbGlDZXJ0IENsYXNzIDIgUG9saWN5IFZhbGlkYXRpb24gQXV0a 2042 G9yaXR5MSEwHwYDVQQDExhodHRwOi8vd3d3LnZhbGljZXJ0LmNvbS8xIDAeBgkq 2043 hkiG9w0BCQEWEWluZm9AdmFsaWNlcnQuY29tMB4XDTk5MDYyNjAwMTk1NFoXDTE 2044 5MDYyNjAwMTk1NFowgbsxJDAiBgNVBAcTG1ZhbGlDZXJ0IFZhbGlkYXRpb24gTm 2045 V0d29yazEXMBUGA1UEChMOVmFsaUNlcnQsIEluYy4xNTAzBgNVBAsTLFZhbGlDZ 2046 XJ0IENsYXNzIDIgUG9saWN5IFZhbGlkYXRpb24gQXV0aG9yaXR5MSEwHwYDVQQD 2047 ExhodHRwOi8vd3d3LnZhbGljZXJ0LmNvbS8xIDAeBgkqhkiG9w0BCQEWEWluZm9 2048 AdmFsaWNlcnQuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDOOnHK5a 2049 vIWZJV16vYdA757tn2VUdZZUcOBVXc65g2PFxTXdMwzzjsvUGJ7SVCCSRrCl6zf 2050 N1SLUzm1NZ9WlmpZdRJEy0kTRxQb7XBhVQ7/nHk01xC+YDgkRoKWzk2Z/M/VXwb 2051 P7RfZHM047QSv4dk+NoS/zcnwbNDu+97bi5p9wIDAQABMA0GCSqGSIb3DQEBBQU 2052 AA4GBADt/UG9vUJSZSWI4OB9L+KXIPqeCgfYrx+jFzug6EILLGACOTb2oWH+heQ 2053 C1u+mNr0HZDzTuIYEZoDJJKPTEjlbVUjP9UNV+mWwD5MlM/Mtsq2azSiGM5bUMM 2054 j4QssxsodyamEwCW/POuZ6lcg5Ktz885hZo+L7tdEy8W9ViH0Pd"] 2056 Appendix C. Notes on implementing base64url encoding without padding 2058 This appendix describes how to implement base64url encoding and 2059 decoding functions without padding based upon standard base64 2060 encoding and decoding functions that do use padding. 2062 To be concrete, example C# code implementing these functions is shown 2063 below. Similar code could be used in other languages. 2065 static string base64urlencode(byte [] arg) 2066 { 2067 string s = Convert.ToBase64String(arg); // Regular base64 encoder 2068 s = s.Split('=')[0]; // Remove any trailing '='s 2069 s = s.Replace('+', '-'); // 62nd char of encoding 2070 s = s.Replace('/', '_'); // 63rd char of encoding 2071 return s; 2072 } 2074 static byte [] base64urldecode(string arg) 2075 { 2076 string s = arg; 2077 s = s.Replace('-', '+'); // 62nd char of encoding 2078 s = s.Replace('_', '/'); // 63rd char of encoding 2079 switch (s.Length % 4) // Pad with trailing '='s 2080 { 2081 case 0: break; // No pad chars in this case 2082 case 2: s += "=="; break; // Two pad chars 2083 case 3: s += "="; break; // One pad char 2084 default: throw new System.Exception( 2085 "Illegal base64url string!"); 2086 } 2087 return Convert.FromBase64String(s); // Standard base64 decoder 2088 } 2090 As per the example code above, the number of '=' padding characters 2091 that needs to be added to the end of a base64url encoded string 2092 without padding to turn it into one with padding is a deterministic 2093 function of the length of the encoded string. Specifically, if the 2094 length mod 4 is 0, no padding is added; if the length mod 4 is 2, two 2095 '=' padding characters are added; if the length mod 4 is 3, one '=' 2096 padding character is added; if the length mod 4 is 1, the input is 2097 malformed. 2099 An example correspondence between unencoded and encoded values 2100 follows. The octet sequence below encodes into the string below, 2101 which when decoded, reproduces the octet sequence. 2102 3 236 255 224 193 2103 A-z_4ME 2105 Appendix D. Notes on Key Selection 2107 This appendix describes a set of possible algorithms for selecting 2108 the key to be used to validate the digital signature or MAC of a JWS 2109 object or for selecting the key to be used to decrypt a JWE object. 2110 This guidance describes a family of possible algorithms, rather than 2111 a single algorithm, because in different contexts, not all the 2112 sources of keys will be used, they can be tried in different orders, 2113 and sometimes not all the collected keys will be tried; hence, 2114 different algorithms will be used in different application contexts. 2116 The steps below are described for illustration purposes only; 2117 specific applications can and are likely to use different algorithms 2118 or perform some of the steps in different orders. Specific 2119 applications will frequently have a much simpler method of 2120 determining the keys to use, as there may be one or two key selection 2121 methods that are profiled for the application's use. This appendix 2122 supplements the normative information on key location in Section 6. 2124 These algorithms include the following steps. Note that the steps 2125 can be performed in any order and do not need to be treated as 2126 distinct. For example, keys can be tried as soon as they are found, 2127 rather than collecting all the keys before trying any. 2129 1. Collect the set of potentially applicable keys. Sources of keys 2130 may include: 2132 * Keys supplied by the application protocol being used. 2134 * Keys referenced by the "jku" (JWK Set URL) Header Parameter. 2136 * The key provided by the "jwk" (JSON Web Key) Header Parameter. 2138 * The key referenced by the "x5u" (X.509 URL) Header Parameter. 2140 * The key provided by the "x5c" (X.509 Certificate Chain) Header 2141 Parameter. 2143 * Other applicable keys available to the application. 2145 The order for collecting and trying keys from different key 2146 sources is typically application dependent. For example, 2147 frequently all keys from a one set of locations, such as local 2148 caches, will be tried before collecting and trying keys from 2149 other locations. 2151 2. Filter the set of collected keys. For instance, some 2152 applications will use only keys referenced by "kid" (key ID) or 2153 "x5t" (X.509 certificate SHA-1 thumbprint) parameters. If the 2154 application uses the "alg" (algorithm), "use" (public key use), 2155 or "key_ops" (key operations) parameters, keys with keys with 2156 inappropriate values of those parameters would be excluded. 2157 Additionally, keys might be filtered to include or exclude keys 2158 with certain other member values in an application specific 2159 manner. For some applications, no filtering will be applied. 2161 3. Order the set of collected keys. For instance, keys referenced 2162 by "kid" (Key ID) or "x5t" (X.509 Certificate SHA-1 Thumbprint) 2163 parameters might be tried before keys with neither of these 2164 values. Likewise, keys with certain member values might be 2165 ordered before keys with other member values. For some 2166 applications, no ordering will be applied. 2168 4. Make trust decisions about the keys. Signatures made with keys 2169 not meeting the application's trust criteria would not be 2170 accepted. Such criteria might include, but is not limited to the 2171 source of the key, whether the TLS certificate validates for keys 2172 retrieved from URLs, whether a key in an X.509 certificate is 2173 backed by a valid certificate chain, and other information known 2174 by the application. 2176 5. Attempt signature or MAC validation for a JWS object or 2177 decryption of a JWE object with some or all of the collected and 2178 possibly filtered and/or ordered keys. A limit on the number of 2179 keys to be tried might be applied. This process will normally 2180 terminate following a successful validation or decryption. 2182 Note that it is reasonable for some applications to perform signature 2183 or MAC validation prior to making a trust decision about a key, since 2184 keys for which the validation fails need no trust decision. 2186 Appendix E. Negative Test Case for "crit" Header Parameter 2188 Conforming implementations must reject input containing critical 2189 extensions that are not understood or cannot be processed. The 2190 following JWS must be rejected by all implementations, because it 2191 uses an extension Header Parameter name 2192 "http://example.invalid/UNDEFINED" that they do not understand. Any 2193 other similar input, in which the use of the value 2194 "http://example.invalid/UNDEFINED" is substituted for any other 2195 Header Parameter name not understood by the implementation, must also 2196 be rejected. 2198 The JWS Protected Header value for this JWS is: 2200 {"alg":"none", 2201 "crit":["http://example.invalid/UNDEFINED"], 2202 "http://example.invalid/UNDEFINED":true 2203 } 2205 The complete JWS that must be rejected is as follows (with line 2206 breaks for display purposes only): 2208 eyJhbGciOiJub25lIiwNCiAiY3JpdCI6WyJodHRwOi8vZXhhbXBsZS5jb20vVU5ERU 2209 ZJTkVEIl0sDQogImh0dHA6Ly9leGFtcGxlLmNvbS9VTkRFRklORUQiOnRydWUNCn0. 2210 RkFJTA. 2212 Appendix F. Detached Content 2214 In some contexts, it is useful integrity protect content that is not 2215 itself contained in a JWS object. One way to do this is create a JWS 2216 object in the normal fashion using a representation of the content as 2217 the payload, but then delete the payload representation from the JWS, 2218 and send this modified object to the recipient, rather than the JWS. 2219 When using the JWS Compact Serialization, the deletion is 2220 accomplished by replacing the second field (which contains 2221 BASE64URL(JWS Payload)) value with the empty string; when using the 2222 JWS JSON Serialization, the deletion is accomplished by deleting the 2223 "payload" member. This method assumes that the recipient can 2224 reconstruct the exact payload used in the JWS. To use the modified 2225 object, the recipient reconstructs the JWS by re-inserting the 2226 payload representation into the modified object, and uses the 2227 resulting JWS in the usual manner. Note that this method needs no 2228 support from JWS libraries, as applications can use this method by 2229 modifying the inputs and outputs of standard JWS libraries. 2231 Appendix G. Acknowledgements 2233 Solutions for signing JSON content were previously explored by Magic 2234 Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas 2235 Applications [CanvasApp], all of which influenced this draft. 2237 Thanks to Axel Nennker for his early implementation and feedback on 2238 the JWS and JWE specifications. 2240 This specification is the work of the JOSE Working Group, which 2241 includes dozens of active and dedicated participants. In particular, 2242 the following individuals contributed ideas, feedback, and wording 2243 that influenced this specification: 2245 Dirk Balfanz, Richard Barnes, Brian Campbell, Breno de Medeiros, Dick 2246 Hardt, Joe Hildebrand, Jeff Hodges, Edmund Jay, Yaron Y. Goland, Ben 2247 Laurie, James Manger, Matt Miller, Tony Nadalin, Hideki Nara, Axel 2248 Nennker, John Panzer, Emmanuel Raviart, Eric Rescorla, Jim Schaad, 2249 Paul Tarjan, Hannes Tschofenig, and Sean Turner. 2251 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2252 Sean Turner, Stephen Farrell, and Kathleen Moriarty served as 2253 Security area directors during the creation of this specification. 2255 Appendix H. Document History 2257 [[ to be removed by the RFC Editor before publication as an RFC ]] 2259 -29 2261 o Replaced the terms JWS Header, JWE Header, and JWT Header with a 2262 single JOSE Header term defined in the JWS specification. This 2263 also enabled a single Header Parameter definition to be used and 2264 reduced other areas of duplication between specifications. 2266 -28 2268 o Revised the introduction to the Security Considerations section. 2269 Also introduced additional subsection headings for security 2270 considerations items and also moved a security consideration item 2271 here from the JWA draft. 2273 o Added text about when applications typically would and would not 2274 use "typ" and "cty" header parameters. 2276 -27 2278 o Added the "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) header 2279 parameter. 2281 o Stated that any JSON inputs not conforming to the JSON-text syntax 2282 defined in RFC 7159 input MUST be rejected in their entirety. 2284 o Simplified the TLS requirements. 2286 -26 2288 o Referenced Section 6 of RFC 6125 for TLS server certificate 2289 identity validation. 2291 o Described potential sources of ambiguity in representing the JSON 2292 objects used in the examples. The octets of the actual UTF-8 2293 representations of the JSON objects used in the examples are 2294 included to remove these ambiguities. 2296 o Added a small amount of additional explanatory text to the 2297 signature validation examples to aid implementers. 2299 o Noted that octet sequences are depicted using JSON array notation. 2301 o Updated references, including to W3C specifications. 2303 -25 2305 o No changes were made, other than to the version number and date. 2307 -24 2309 o Updated the JSON reference to RFC 7159. 2311 -23 2313 o Clarified that the base64url encoding includes no line breaks, 2314 white space, or other additional characters. 2316 -22 2318 o Corrected RFC 2119 terminology usage. 2320 o Replaced references to draft-ietf-json-rfc4627bis with RFC 7158. 2322 -21 2324 o Applied review comments to the appendix "Notes on Key Selection", 2325 addressing issue #93. 2327 o Changed some references from being normative to informative, 2328 addressing issue #90. 2330 o Applied review comments to the JSON Serialization section, 2331 addressing issue #121. 2333 -20 2335 o Made terminology definitions more consistent, addressing issue 2336 #165. 2338 o Restructured the JSON Serialization section to call out the 2339 parameters used in hanging lists, addressing issue #121. 2341 o Described key filtering and refined other aspects of the text in 2342 the appendix "Notes on Key Selection", addressing issue #93. 2344 o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis, 2345 addressing issue #90. 2347 -19 2349 o Added the appendix "Notes on Validation Key Selection", addressing 2350 issue #93. 2352 o Reordered the key selection parameters. 2354 -18 2356 o Updated the mandatory-to-implement (MTI) language to say that 2357 applications using this specification need to specify what 2358 serialization and serialization features are used for that 2359 application, addressing issue #119. 2361 o Changes to address editorial and minor issues #25, #89, #97, #110, 2362 #114, #115, #116, #117, #120, and #184. 2364 o Added and used Header Parameter Description registry field. 2366 -17 2368 o Refined the "typ" and "cty" definitions to always be MIME Media 2369 Types, with the omission of "application/" prefixes recommended 2370 for brevity, addressing issue #50. 2372 o Updated the mandatory-to-implement (MTI) language to say that 2373 general-purpose implementations must implement the single 2374 signature/MAC value case for both serializations whereas special- 2375 purpose implementations can implement just one serialization if 2376 that meets the needs of the use cases the implementation is 2377 designed for, addressing issue #119. 2379 o Explicitly named all the logical components of a JWS and defined 2380 the processing rules and serializations in terms of those 2381 components, addressing issues #60, #61, and #62. 2383 o Replaced verbose repetitive phases such as "base64url encode the 2384 octets of the UTF-8 representation of X" with mathematical 2385 notation such as "BASE64URL(UTF8(X))". 2387 o Terms used in multiple documents are now defined in one place and 2388 incorporated by reference. Some lightly used or obvious terms 2389 were also removed. This addresses issue #58. 2391 -16 2393 o Changes to address editorial and minor issues #50, #98, #99, #102, 2394 #104, #106, #107, #111, and #112. 2396 -15 2398 o Clarified that it is an application decision which signatures, 2399 MACs, or plaintext values must successfully validate for the JWS 2400 to be accepted, addressing issue #35. 2402 o Corrected editorial error in "ES512" example. 2404 o Changes to address editorial and minor issues #34, #96, #100, 2405 #101, #104, #105, and #106. 2407 -14 2409 o Stated that the "signature" parameter is to be omitted in the JWS 2410 JSON Serialization when its value would be empty (which is only 2411 the case for a Plaintext JWS). 2413 -13 2415 o Made all header parameter values be per-signature/MAC, addressing 2416 issue #24. 2418 -12 2420 o Clarified that the "typ" and "cty" header parameters are used in 2421 an application-specific manner and have no effect upon the JWS 2422 processing. 2424 o Replaced the MIME types "application/jws+json" and 2425 "application/jws" with "application/jose+json" and 2426 "application/jose". 2428 o Stated that recipients MUST either reject JWSs with duplicate 2429 Header Parameter Names or use a JSON parser that returns only the 2430 lexically last duplicate member name. 2432 o Added a Serializations section with parallel treatment of the JWS 2433 Compact Serialization and the JWS JSON Serialization and also 2434 moved the former Implementation Considerations content there. 2436 -11 2438 o Added Key Identification section. 2440 o For the JWS JSON Serialization, enable header parameter values to 2441 be specified in any of three parameters: the "protected" member 2442 that is integrity protected and shared among all recipients, the 2443 "unprotected" member that is not integrity protected and shared 2444 among all recipients, and the "header" member that is not 2445 integrity protected and specific to a particular recipient. (This 2446 does not affect the JWS Compact Serialization, in which all header 2447 parameter values are in a single integrity protected JWE Header 2448 value.) 2450 o Removed suggested compact serialization for multiple digital 2451 signatures and/or MACs. 2453 o Changed the MIME type name "application/jws-js" to 2454 "application/jws+json", addressing issue #22. 2456 o Tightened the description of the "crit" (critical) header 2457 parameter. 2459 o Added a negative test case for the "crit" header parameter 2461 -10 2463 o Added an appendix suggesting a possible compact serialization for 2464 JWSs with multiple digital signatures and/or MACs. 2466 -09 2468 o Added JWS JSON Serialization, as specified by 2469 draft-jones-jose-jws-json-serialization-04. 2471 o Registered "application/jws-js" MIME type and "JWS-JS" typ header 2472 parameter value. 2474 o Defined that the default action for header parameters that are not 2475 understood is to ignore them unless specifically designated as 2476 "MUST be understood" or included in the new "crit" (critical) 2477 header parameter list. This addressed issue #6. 2479 o Changed term "JWS Secured Input" to "JWS Signing Input". 2481 o Changed from using the term "byte" to "octet" when referring to 8 2482 bit values. 2484 o Changed member name from "recipients" to "signatures" in the JWS 2485 JSON Serialization. 2487 o Added complete values using the JWS Compact Serialization for all 2488 examples. 2490 -08 2492 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2493 Tschofenig. Many of these simplified the terminology used. 2495 o Clarified statements of the form "This header parameter is 2496 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2498 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2499 Web Signature and Encryption Header Parameters registry. 2501 o Added seriesInfo information to Internet Draft references. 2503 -07 2505 o Updated references. 2507 -06 2509 o Changed "x5c" (X.509 Certificate Chain) representation from being 2510 a single string to being an array of strings, each containing a 2511 single base64 encoded DER certificate value, representing elements 2512 of the certificate chain. 2514 o Applied changes made by the RFC Editor to RFC 6749's registry 2515 language to this specification. 2517 -05 2519 o Added statement that "StringOrURI values are compared as case- 2520 sensitive strings with no transformations or canonicalizations 2521 applied". 2523 o Indented artwork elements to better distinguish them from the body 2524 text. 2526 -04 2528 o Completed JSON Security Considerations section, including 2529 considerations about rejecting input with duplicate member names. 2531 o Completed security considerations on the use of a SHA-1 hash when 2532 computing "x5t" (x.509 certificate thumbprint) values. 2534 o Refer to the registries as the primary sources of defined values 2535 and then secondarily reference the sections defining the initial 2536 contents of the registries. 2538 o Normatively reference XML DSIG 2.0 for its security 2539 considerations. 2541 o Added this language to Registration Templates: "This name is case 2542 sensitive. Names that match other registered names in a case 2543 insensitive manner SHOULD NOT be accepted." 2545 o Reference draft-jones-jose-jws-json-serialization instead of 2546 draft-jones-json-web-signature-json-serialization. 2548 o Described additional open issues. 2550 o Applied editorial suggestions. 2552 -03 2554 o Added the "cty" (content type) header parameter for declaring type 2555 information about the secured content, as opposed to the "typ" 2556 (type) header parameter, which declares type information about 2557 this object. 2559 o Added "Collision Resistant Namespace" to the terminology section. 2561 o Reference ITU.X690.1994 for DER encoding. 2563 o Added an example JWS using ECDSA P-521 SHA-512. This has 2564 particular illustrative value because of the use of the 521 bit 2565 integers in the key and signature values. This is also an example 2566 in which the payload is not a base64url encoded JSON object. 2568 o Added an example "x5c" value. 2570 o No longer say "the UTF-8 representation of the JWS Secured Input 2571 (which is the same as the ASCII representation)". Just call it 2572 "the ASCII representation of the JWS Secured Input". 2574 o Added Registration Template sections for defined registries. 2576 o Added Registry Contents sections to populate registry values. 2578 o Changed name of the JSON Web Signature and Encryption "typ" Values 2579 registry to be the JSON Web Signature and Encryption Type Values 2580 registry, since it is used for more than just values of the "typ" 2581 parameter. 2583 o Moved registries JSON Web Signature and Encryption Header 2584 Parameters and JSON Web Signature and Encryption Type Values to 2585 the JWS specification. 2587 o Numerous editorial improvements. 2589 -02 2591 o Clarified that it is an error when a "kid" value is included and 2592 no matching key is found. 2594 o Removed assumption that "kid" (key ID) can only refer to an 2595 asymmetric key. 2597 o Clarified that JWSs with duplicate Header Parameter Names MUST be 2598 rejected. 2600 o Clarified the relationship between "typ" header parameter values 2601 and MIME types. 2603 o Registered application/jws MIME type and "JWS" typ header 2604 parameter value. 2606 o Simplified JWK terminology to get replace the "JWK Key Object" and 2607 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2608 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2609 between single keys and sets of keys. As part of this change, the 2610 Header Parameter Name for a public key value was changed from 2611 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2613 o Added suggestion on defining additional header parameters such as 2614 "x5t#S256" in the future for certificate thumbprints using hash 2615 algorithms other than SHA-1. 2617 o Specify RFC 2818 server identity validation, rather than RFC 6125 2618 (paralleling the same decision in the OAuth specs). 2620 o Generalized language to refer to Message Authentication Codes 2621 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2622 unless in a context specific to HMAC algorithms. 2624 o Reformatted to give each header parameter its own section heading. 2626 -01 2628 o Moved definition of Plaintext JWSs (using "alg":"none") here from 2629 the JWT specification since this functionality is likely to be 2630 useful in more contexts that just for JWTs. 2632 o Added "jpk" and "x5c" header parameters for including JWK public 2633 keys and X.509 certificate chains directly in the header. 2635 o Clarified that this specification is defining the JWS Compact 2636 Serialization. Referenced the new JWS-JS spec, which defines the 2637 JWS JSON Serialization. 2639 o Added text "New header parameters should be introduced sparingly 2640 since an implementation that does not understand a parameter MUST 2641 reject the JWS". 2643 o Clarified that the order of the creation and validation steps is 2644 not significant in cases where there are no dependencies between 2645 the inputs and outputs of the steps. 2647 o Changed "no canonicalization is performed" to "no canonicalization 2648 need be performed". 2650 o Corrected the Magic Signatures reference. 2652 o Made other editorial improvements suggested by JOSE working group 2653 participants. 2655 -00 2657 o Created the initial IETF draft based upon 2658 draft-jones-json-web-signature-04 with no normative changes. 2660 o Changed terminology to no longer call both digital signatures and 2661 HMACs "signatures". 2663 Authors' Addresses 2665 Michael B. Jones 2666 Microsoft 2668 Email: mbj@microsoft.com 2669 URI: http://self-issued.info/ 2671 John Bradley 2672 Ping Identity 2674 Email: ve7jtb@ve7jtb.com 2675 URI: http://www.thread-safe.com/ 2677 Nat Sakimura 2678 Nomura Research Institute 2680 Email: n-sakimura@nri.co.jp 2681 URI: http://nat.sakimura.org/