idnits 2.17.1 draft-ietf-jose-json-web-signature-38.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 (December 9, 2014) is 3425 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 2024 -- Looks like a reference, but probably isn't: '34' on line 2024 -- Looks like a reference, but probably isn't: '97' on line 2034 -- Looks like a reference, but probably isn't: '108' on line 2034 -- Looks like a reference, but probably isn't: '103' on line 2024 -- Looks like a reference, but probably isn't: '58' on line 2024 -- Looks like a reference, but probably isn't: '82' on line 1762 -- Looks like a reference, but probably isn't: '83' on line 2024 -- Looks like a reference, but probably isn't: '50' on line 2024 -- Looks like a reference, but probably isn't: '53' on line 2024 -- Looks like a reference, but probably isn't: '54' on line 1910 -- Looks like a reference, but probably isn't: '125' on line 2024 -- Looks like a reference, but probably isn't: '69' on line 2024 -- Looks like a reference, but probably isn't: '49' on line 2024 -- Looks like a reference, but probably isn't: '80' on line 2034 -- Looks like a reference, but probably isn't: '121' on line 2034 -- Looks like a reference, but probably isn't: '111' on line 2034 -- Looks like a reference, but probably isn't: '100' on line 2034 -- Looks like a reference, but probably isn't: '0' on line 2370 -- Possible downref: Non-RFC (?) normative reference: ref. 'ECMAScript' -- Possible downref: Non-RFC (?) normative reference: ref. 'ITU.X690.1994' ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Downref: Normative reference to an Informational RFC: RFC 4949 ** 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) == Outdated reference: A later version (-11) exists of draft-ietf-uta-tls-bcp-07 -- Obsolete informational reference (is this intentional?): RFC 3447 (Obsoleted by RFC 8017) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) Summary: 5 errors (**), 0 flaws (~~), 2 warnings (==), 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: June 12, 2015 Ping Identity 6 N. Sakimura 7 NRI 8 December 9, 2014 10 JSON Web Signature (JWS) 11 draft-ietf-jose-json-web-signature-38 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 June 12, 2015. 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 . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 5 60 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 3. JSON Web Signature (JWS) Overview . . . . . . . . . . . . . . 7 62 3.1. JWS Compact Serialization Overview . . . . . . . . . . . 8 63 3.2. JWS JSON Serialization Overview . . . . . . . . . . . . . 8 64 3.3. Example JWS . . . . . . . . . . . . . . . . . . . . . . . 9 65 4. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . . . 10 66 4.1. Registered Header Parameter Names . . . . . . . . . . . . 11 67 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 11 68 4.1.2. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 11 69 4.1.3. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 11 70 4.1.4. "kid" (Key ID) Header Parameter . . . . . . . . . . . 12 71 4.1.5. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 12 72 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter . . . 12 73 4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header 74 Parameter . . . . . . . . . . . . . . . . . . . . . . 13 75 4.1.8. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) 76 Header Parameter . . . . . . . . . . . . . . . . . . . 13 77 4.1.9. "typ" (Type) Header Parameter . . . . . . . . . . . . 13 78 4.1.10. "cty" (Content Type) Header Parameter . . . . . . . . 14 79 4.1.11. "crit" (Critical) Header Parameter . . . . . . . . . . 14 80 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 15 81 4.3. Private Header Parameter Names . . . . . . . . . . . . . 15 82 5. Producing and Consuming JWSs . . . . . . . . . . . . . . . . . 15 83 5.1. Message Signature or MAC Computation . . . . . . . . . . 15 84 5.2. Message Signature or MAC Validation . . . . . . . . . . . 16 85 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 18 86 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 19 87 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 19 88 7.1. JWS Compact Serialization . . . . . . . . . . . . . . . . 20 89 7.2. JWS JSON Serialization . . . . . . . . . . . . . . . . . 20 90 7.2.1. General JWS JSON Serialization Syntax . . . . . . . . 20 91 7.2.2. Flattened JWS JSON Serialization Syntax . . . . . . . 22 92 8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 23 93 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 94 9.1. JSON Web Signature and Encryption Header Parameters 95 Registry . . . . . . . . . . . . . . . . . . . . . . . . 24 97 9.1.1. Registration Template . . . . . . . . . . . . . . . . 25 98 9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 25 99 9.2. Media Type Registration . . . . . . . . . . . . . . . . . 27 100 9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 27 101 10. Security Considerations . . . . . . . . . . . . . . . . . . . 28 102 10.1. Key Entropy and Random Values . . . . . . . . . . . . . . 28 103 10.2. Key Protection . . . . . . . . . . . . . . . . . . . . . 29 104 10.3. Key Origin Authentication . . . . . . . . . . . . . . . . 29 105 10.4. Cryptographic Agility . . . . . . . . . . . . . . . . . . 29 106 10.5. Differences between Digital Signatures and MACs . . . . . 29 107 10.6. Algorithm Validation . . . . . . . . . . . . . . . . . . 30 108 10.7. Algorithm Protection . . . . . . . . . . . . . . . . . . 30 109 10.8. Chosen Plaintext Attacks . . . . . . . . . . . . . . . . 31 110 10.9. Timing Attacks . . . . . . . . . . . . . . . . . . . . . 31 111 10.10. Replay Protection . . . . . . . . . . . . . . . . . . . . 31 112 10.11. SHA-1 Certificate Thumbprints . . . . . . . . . . . . . . 31 113 10.12. JSON Security Considerations . . . . . . . . . . . . . . 32 114 10.13. Unicode Comparison Security Considerations . . . . . . . 32 115 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 33 116 11.1. Normative References . . . . . . . . . . . . . . . . . . 33 117 11.2. Informative References . . . . . . . . . . . . . . . . . 34 118 Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 36 119 A.1. Example JWS using HMAC SHA-256 . . . . . . . . . . . . . 36 120 A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 36 121 A.1.2. Validating . . . . . . . . . . . . . . . . . . . . . . 38 122 A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 . . . . . . . 38 123 A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 39 124 A.2.2. Validating . . . . . . . . . . . . . . . . . . . . . . 41 125 A.3. Example JWS using ECDSA P-256 SHA-256 . . . . . . . . . . 42 126 A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 42 127 A.3.2. Validating . . . . . . . . . . . . . . . . . . . . . . 44 128 A.4. Example JWS using ECDSA P-521 SHA-512 . . . . . . . . . . 44 129 A.4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 44 130 A.4.2. Validating . . . . . . . . . . . . . . . . . . . . . . 46 131 A.5. Example Unsecured JWS . . . . . . . . . . . . . . . . . . 46 132 A.6. Example JWS using General JWS JSON Serialization . . . . 47 133 A.6.1. JWS Per-Signature Protected Headers . . . . . . . . . 48 134 A.6.2. JWS Per-Signature Unprotected Headers . . . . . . . . 48 135 A.6.3. Complete JOSE Header Values . . . . . . . . . . . . . 48 136 A.6.4. Complete JWS JSON Serialization Representation . . . . 49 137 A.7. Example JWS using Flattened JWS JSON Serialization . . . 49 138 Appendix B. "x5c" (X.509 Certificate Chain) Example . . . . . . . 50 139 Appendix C. Notes on implementing base64url encoding without 140 padding . . . . . . . . . . . . . . . . . . . . . . . 52 141 Appendix D. Notes on Key Selection . . . . . . . . . . . . . . . 53 142 Appendix E. Negative Test Case for "crit" Header Parameter . . . 54 143 Appendix F. Detached Content . . . . . . . . . . . . . . . . . . 55 144 Appendix G. Acknowledgements . . . . . . . . . . . . . . . . . . 55 145 Appendix H. Document History . . . . . . . . . . . . . . . . . . 56 146 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 66 148 1. Introduction 150 JSON Web Signature (JWS) represents content secured with digital 151 signatures or Message Authentication Codes (MACs) using JavaScript 152 Object Notation (JSON) [RFC7159] based data structures. The JWS 153 cryptographic mechanisms provide integrity protection for an 154 arbitrary sequence of octets. See Section 10.5 for a discussion on 155 the differences between Digital Signatures and MACs. 157 Two closely related serializations for JWSs are defined. The JWS 158 Compact Serialization is a compact, URL-safe representation intended 159 for space constrained environments such as HTTP Authorization headers 160 and URI query parameters. The JWS JSON Serialization represents JWSs 161 as JSON objects and enables multiple signatures and/or MACs to be 162 applied to the same content. Both share the same cryptographic 163 underpinnings. 165 Cryptographic algorithms and identifiers for use with this 166 specification are described in the separate JSON Web Algorithms (JWA) 167 [JWA] specification and an IANA registry defined by that 168 specification. Related encryption capabilities are described in the 169 separate JSON Web Encryption (JWE) [JWE] specification. 171 Names defined by this specification are short because a core goal is 172 for the resulting representations to be compact. 174 1.1. Notational Conventions 176 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 177 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 178 "OPTIONAL" in this document are to be interpreted as described in Key 179 words for use in RFCs to Indicate Requirement Levels [RFC2119]. If 180 these words are used without being spelled in uppercase then they are 181 to be interpreted with their normal natural language meanings. 183 BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per 184 Section 2. 186 UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation 187 of STRING. 189 ASCII(STRING) denotes the octets of the ASCII [RFC20] representation 190 of STRING. 192 The concatenation of two values A and B is denoted as A || B. 194 2. Terminology 196 These terms are defined by this specification: 198 JSON Web Signature (JWS) 199 A data structure representing a digitally signed or MACed message. 201 JOSE Header 202 JSON object containing the parameters describing the cryptographic 203 operations and parameters employed. The JOSE Header is comprised 204 of a set of Header Parameters. 206 JWS Payload 207 The sequence of octets to be secured -- a.k.a., the message. The 208 payload can contain an arbitrary sequence of octets. 210 JWS Signature 211 Digital signature or MAC over the JWS Protected Header and the JWS 212 Payload. 214 Header Parameter 215 A name/value pair that is member of the JOSE Header. 217 JWS Protected Header 218 JSON object that contains the Header Parameters that are integrity 219 protected by the JWS Signature digital signature or MAC operation. 220 For the JWS Compact Serialization, this comprises the entire JOSE 221 Header. For the JWS JSON Serialization, this is one component of 222 the JOSE Header. 224 JWS Unprotected Header 225 JSON object that contains the Header Parameters that are not 226 integrity protected. This can only be present when using the JWS 227 JSON Serialization. 229 Base64url Encoding 230 Base64 encoding using the URL- and filename-safe character set 231 defined in Section 5 of RFC 4648 [RFC4648], with all trailing '=' 232 characters omitted (as permitted by Section 3.2) and without the 233 inclusion of any line breaks, white space, or other additional 234 characters. Note that the base64url encoding of the empty octet 235 sequence is the empty string. (See Appendix C for notes on 236 implementing base64url encoding without padding.) 238 JWS Signing Input 239 The input to the digital signature or MAC computation. Its value 240 is ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || 241 BASE64URL(JWS Payload)). 243 JWS Compact Serialization 244 A representation of the JWS as a compact, URL-safe string. 246 JWS JSON Serialization 247 A representation of the JWS as a JSON object. Unlike the JWS 248 Compact Serialization, the JWS JSON Serialization enables multiple 249 digital signatures and/or MACs to be applied to the same content. 250 This representation is neither optimized for compactness nor URL- 251 safe. 253 Unsecured JWS 254 A JWS that provides no integrity protection. Unsecured JWSs use 255 the "alg" value "none". 257 Collision-Resistant Name 258 A name in a namespace that enables names to be allocated in a 259 manner such that they are highly unlikely to collide with other 260 names. Examples of collision-resistant namespaces include: Domain 261 Names, Object Identifiers (OIDs) as defined in the ITU-T X.660 and 262 X.670 Recommendation series, and Universally Unique IDentifiers 263 (UUIDs) [RFC4122]. When using an administratively delegated 264 namespace, the definer of a name needs to take reasonable 265 precautions to ensure they are in control of the portion of the 266 namespace they use to define the name. 268 StringOrURI 269 A JSON string value, with the additional requirement that while 270 arbitrary string values MAY be used, any value containing a ":" 271 character MUST be a URI [RFC3986]. StringOrURI values are 272 compared as case-sensitive strings with no transformations or 273 canonicalizations applied. 275 These terms defined by the JSON Web Encryption (JWE) [JWE] 276 specification are incorporated into this specification: "JSON Web 277 Encryption (JWE)", "JWE Compact Serialization", and "JWE JSON 278 Serialization". 280 These terms defined by the Internet Security Glossary, Version 2 281 [RFC4949] are incorporated into this specification: "Digital 282 Signature" and "Message Authentication Code (MAC)". 284 3. JSON Web Signature (JWS) Overview 286 JWS represents digitally signed or MACed content using JSON data 287 structures and base64url encoding. These JSON data structures MAY 288 contain white space and/or line breaks before or after any JSON 289 values or structural characters, in accordance with Section 2 of RFC 290 7159 [RFC7159]. A JWS represents these logical values (each of which 291 is defined in Section 2): 293 o JOSE Header 294 o JWS Payload 295 o JWS Signature 297 For a JWS, the JOSE Header members are the union of the members of 298 these values (each of which is defined in Section 2): 300 o JWS Protected Header 301 o JWS Unprotected Header 303 This document defines two serializations for JWSs: a compact, URL- 304 safe serialization called the JWS Compact Serialization and a JSON 305 serialization called the JWS JSON Serialization. In both 306 serializations, the JWS Protected Header, JWS Payload, and JWS 307 Signature are base64url encoded, since JSON lacks a way to directly 308 represent arbitrary octet sequences. 310 3.1. JWS Compact Serialization Overview 312 In the JWS Compact Serialization, no JWS Unprotected Header is used. 313 In this case, the JOSE Header and the JWS Protected Header are the 314 same. 316 In the JWS Compact Serialization, a JWS is represented as the 317 concatenation: 319 BASE64URL(UTF8(JWS Protected Header)) || '.' || 320 BASE64URL(JWS Payload) || '.' || 321 BASE64URL(JWS Signature) 323 See Section 7.1 for more information about the JWS Compact 324 Serialization. 326 3.2. JWS JSON Serialization Overview 328 In the JWS JSON Serialization, one or both of the JWS Protected 329 Header and JWS Unprotected Header MUST be present. In this case, the 330 members of the JOSE Header are the union of the members of the JWS 331 Protected Header and the JWS Unprotected Header values that are 332 present. 334 In the JWS JSON Serialization, a JWS is represented as a JSON object 335 containing some or all of these four members: 337 "protected", with the value BASE64URL(UTF8(JWS Protected Header)) 338 "header", with the value JWS Unprotected Header 339 "payload", with the value BASE64URL(JWS Payload) 340 "signature", with the value BASE64URL(JWS Signature) 342 The three base64url encoded result strings and the JWS Unprotected 343 Header value are represented as members within a JSON object. The 344 inclusion of some of these values is OPTIONAL. The JWS JSON 345 Serialization can also represent multiple signature and/or MAC 346 values, rather than just one. See Section 7.2 for more information 347 about the JWS JSON Serialization. 349 3.3. Example JWS 351 This section provides an example of a JWS. Its computation is 352 described in more detail in Appendix A.1, including specifying the 353 exact octet sequences representing the JSON values used and the key 354 value used. 356 The following example JWS Protected Header declares that the encoded 357 object is a JSON Web Token (JWT) [JWT] and the JWS Protected Header 358 and the JWS Payload are secured using the HMAC SHA-256 [RFC2104, SHS] 359 algorithm: 361 {"typ":"JWT", 362 "alg":"HS256"} 364 Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected 365 Header)) gives this value: 367 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 369 The UTF-8 representation of following JSON object is used as the JWS 370 Payload. (Note that the payload can be any content, and need not be 371 a representation of a JSON object.) 373 {"iss":"joe", 374 "exp":1300819380, 375 "http://example.com/is_root":true} 377 Encoding this JWS Payload as BASE64URL(JWS Payload) gives this value 378 (with line breaks for display purposes only): 380 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 381 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 383 Computing the HMAC of the JWS Signing Input ASCII(BASE64URL(UTF8(JWS 384 Protected Header)) || '.' || BASE64URL(JWS Payload)) with the HMAC 385 SHA-256 algorithm using the key specified in Appendix A.1 and 386 base64url encoding the result yields this BASE64URL(JWS Signature) 387 value: 389 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 391 Concatenating these values in the order Header.Payload.Signature with 392 period ('.') characters between the parts yields this complete JWS 393 representation using the JWS Compact Serialization (with line breaks 394 for display purposes only): 396 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 397 . 398 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 399 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 400 . 401 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 403 See Appendix A for additional examples, including examples using the 404 JWS JSON Serialization in Sections A.6 and A.7. 406 4. JOSE Header 408 For a JWS, the members of the JSON object(s) representing the JOSE 409 Header describe the digital signature or MAC applied to the JWS 410 Protected Header and the JWS Payload and optionally additional 411 properties of the JWS. The Header Parameter names within the JOSE 412 Header MUST be unique; JWS parsers MUST either reject JWSs with 413 duplicate Header Parameter names or use a JSON parser that returns 414 only the lexically last duplicate member name, as specified in 415 Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript]. 417 Implementations are required to understand the specific Header 418 Parameters defined by this specification that are designated as "MUST 419 be understood" and process them in the manner defined in this 420 specification. All other Header Parameters defined by this 421 specification that are not so designated MUST be ignored when not 422 understood. Unless listed as a critical Header Parameter, per 423 Section 4.1.11, all Header Parameters not defined by this 424 specification MUST be ignored when not understood. 426 There are three classes of Header Parameter names: Registered Header 427 Parameter names, Public Header Parameter names, and Private Header 428 Parameter names. 430 4.1. Registered Header Parameter Names 432 The following Header Parameter names for use in JWSs are registered 433 in the IANA JSON Web Signature and Encryption Header Parameters 434 registry defined in Section 9.1, with meanings as defined below. 436 As indicated by the common registry, JWSs and JWEs share a common 437 Header Parameter space; when a parameter is used by both 438 specifications, its usage must be compatible between the 439 specifications. 441 4.1.1. "alg" (Algorithm) Header Parameter 443 The "alg" (algorithm) Header Parameter identifies the cryptographic 444 algorithm used to secure the JWS. The JWS Signature value is not 445 valid if the "alg" value does not represent a supported algorithm, or 446 if there is not a key for use with that algorithm associated with the 447 party that digitally signed or MACed the content. "alg" values should 448 either be registered in the IANA JSON Web Signature and Encryption 449 Algorithms registry defined in [JWA] or be a value that contains a 450 Collision-Resistant Name. The "alg" value is a case-sensitive ASCII 451 string containing a StringOrURI value. This Header Parameter MUST be 452 present and MUST be understood and processed by implementations. 454 A list of defined "alg" values for this use can be found in the IANA 455 JSON Web Signature and Encryption Algorithms registry defined in 456 [JWA]; the initial contents of this registry are the values defined 457 in Section 3.1 of the JSON Web Algorithms (JWA) [JWA] specification. 459 4.1.2. "jku" (JWK Set URL) Header Parameter 461 The "jku" (JWK Set URL) Header Parameter is a URI [RFC3986] that 462 refers to a resource for a set of JSON-encoded public keys, one of 463 which corresponds to the key used to digitally sign the JWS. The 464 keys MUST be encoded as a JSON Web Key Set (JWK Set) [JWK]. The 465 protocol used to acquire the resource MUST provide integrity 466 protection; an HTTP GET request to retrieve the JWK Set MUST use TLS 467 [RFC2818, RFC5246]; the identity of the server MUST be validated, as 468 per Section 6 of RFC 6125 [RFC6125]. Also, see Section 8 on TLS 469 requirements. Use of this Header Parameter is OPTIONAL. 471 4.1.3. "jwk" (JSON Web Key) Header Parameter 473 The "jwk" (JSON Web Key) Header Parameter is the public key that 474 corresponds to the key used to digitally sign the JWS. This key is 475 represented as a JSON Web Key [JWK]. Use of this Header Parameter is 476 OPTIONAL. 478 4.1.4. "kid" (Key ID) Header Parameter 480 The "kid" (key ID) Header Parameter is a hint indicating which key 481 was used to secure the JWS. This parameter allows originators to 482 explicitly signal a change of key to recipients. The structure of 483 the "kid" value is unspecified. Its value MUST be a case-sensitive 484 string. Use of this Header Parameter is OPTIONAL. 486 When used with a JWK, the "kid" value is used to match a JWK "kid" 487 parameter value. 489 4.1.5. "x5u" (X.509 URL) Header Parameter 491 The "x5u" (X.509 URL) Header Parameter is a URI [RFC3986] that refers 492 to a resource for the X.509 public key certificate or certificate 493 chain [RFC5280] corresponding to the key used to digitally sign the 494 JWS. The identified resource MUST provide a representation of the 495 certificate or certificate chain that conforms to RFC 5280 [RFC5280] 496 in PEM encoded form, with each certificate delimited as specified in 497 Section 6.1 of RFC 4945 [RFC4945]. The certificate containing the 498 public key corresponding to the key used to digitally sign the JWS 499 MUST be the first certificate. This MAY be followed by additional 500 certificates, with each subsequent certificate being the one used to 501 certify the previous one. The protocol used to acquire the resource 502 MUST provide integrity protection; an HTTP GET request to retrieve 503 the certificate MUST use TLS [RFC2818, RFC5246]; the identity of the 504 server MUST be validated, as per Section 6 of RFC 6125 [RFC6125]. 505 Also, see Section 8 on TLS requirements. Use of this Header 506 Parameter is OPTIONAL. 508 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter 510 The "x5c" (X.509 Certificate Chain) Header Parameter contains the 511 X.509 public key certificate or certificate chain [RFC5280] 512 corresponding to the key used to digitally sign the JWS. The 513 certificate or certificate chain is represented as a JSON array of 514 certificate value strings. Each string in the array is a base64 515 encoded ([RFC4648] Section 4 -- not base64url encoded) DER 516 [ITU.X690.1994] PKIX certificate value. The certificate containing 517 the public key corresponding to the key used to digitally sign the 518 JWS MUST be the first certificate. This MAY be followed by 519 additional certificates, with each subsequent certificate being the 520 one used to certify the previous one. The recipient MUST validate 521 the certificate chain according to RFC 5280 [RFC5280] and consider 522 the certificate or certificate chain to be invalid if any validation 523 failure occurs. Use of this Header Parameter is OPTIONAL. 525 See Appendix B for an example "x5c" value. 527 4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter 529 The "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter is a 530 base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER 531 encoding of the X.509 certificate [RFC5280] corresponding to the key 532 used to digitally sign the JWS. Note that certificate thumbprints 533 are also sometimes known as certificate fingerprints. Use of this 534 Header Parameter is OPTIONAL. 536 4.1.8. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header 537 Parameter 539 The "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header 540 Parameter is a base64url encoded SHA-256 thumbprint (a.k.a. digest) 541 of the DER encoding of the X.509 certificate [RFC5280] corresponding 542 to the key used to digitally sign the JWS. Note that certificate 543 thumbprints are also sometimes known as certificate fingerprints. 544 Use of this Header Parameter is OPTIONAL. 546 4.1.9. "typ" (Type) Header Parameter 548 The "typ" (type) Header Parameter is used by JWS applications to 549 declare the MIME Media Type [IANA.MediaTypes] of this complete JWS. 550 This is intended for use by the application when more than one kind 551 of object could be present in an application data structure that can 552 contain a JWS; the application can use this value to disambiguate 553 among the different kinds of objects that might be present. It will 554 typically not be used by applications when the kind of object is 555 already known. This parameter is ignored by JWS implementations; any 556 processing of this parameter is performed by the JWS application. 557 Use of this Header Parameter is OPTIONAL. 559 Per RFC 2045 [RFC2045], all media type values, subtype values, and 560 parameter names are case-insensitive. However, parameter values are 561 case-sensitive unless otherwise specified for the specific parameter. 563 To keep messages compact in common situations, it is RECOMMENDED that 564 producers omit an "application/" prefix of a media type value in a 565 "typ" Header Parameter when no other '/' appears in the media type 566 value. A recipient using the media type value MUST treat it as if 567 "application/" were prepended to any "typ" value not containing a 568 '/'. For instance, a "typ" value of "example" SHOULD be used to 569 represent the "application/example" media type; whereas, the media 570 type "application/example;part="1/2"" cannot be shortened to 571 "example;part="1/2"". 573 The "typ" value "JOSE" can be used by applications to indicate that 574 this object is a JWS or JWE using the JWS Compact Serialization or 575 the JWE Compact Serialization. The "typ" value "JOSE+JSON" can be 576 used by applications to indicate that this object is a JWS or JWE 577 using the JWS JSON Serialization or the JWE JSON Serialization. 578 Other type values can also be used by applications. 580 4.1.10. "cty" (Content Type) Header Parameter 582 The "cty" (content type) Header Parameter is used by JWS applications 583 to declare the MIME Media Type [IANA.MediaTypes] of the secured 584 content (the payload). This is intended for use by the application 585 when more than one kind of object could be present in the JWS 586 payload; the application can use this value to disambiguate among the 587 different kinds of objects that might be present. It will typically 588 not be used by applications when the kind of object is already known. 589 This parameter is ignored by JWS implementations; any processing of 590 this parameter is performed by the JWS application. Use of this 591 Header Parameter is OPTIONAL. 593 Per RFC 2045 [RFC2045], all media type values, subtype values, and 594 parameter names are case-insensitive. However, parameter values are 595 case-sensitive unless otherwise specified for the specific parameter. 597 To keep messages compact in common situations, it is RECOMMENDED that 598 producers omit an "application/" prefix of a media type value in a 599 "cty" Header Parameter when no other '/' appears in the media type 600 value. A recipient using the media type value MUST treat it as if 601 "application/" were prepended to any "cty" value not containing a 602 '/'. For instance, a "cty" value of "example" SHOULD be used to 603 represent the "application/example" media type; whereas, the media 604 type "application/example;part="1/2"" cannot be shortened to 605 "example;part="1/2"". 607 4.1.11. "crit" (Critical) Header Parameter 609 The "crit" (critical) Header Parameter indicates that extensions to 610 the initial RFC versions of [[ this specification ]] and [JWA] are 611 being used that MUST be understood and processed. Its value is an 612 array listing the Header Parameter names present in the JOSE Header 613 that use those extensions. If any of the listed extension Header 614 Parameters are not understood and supported by the recipient, it MUST 615 reject the JWS. Producers MUST NOT include Header Parameter names 616 defined by the initial RFC versions of [[ this specification ]] or 617 [JWA] for use with JWS, duplicate names, or names that do not occur 618 as Header Parameter names within the JOSE Header in the "crit" list. 619 Producers MUST NOT use the empty list "[]" as the "crit" value. 620 Recipients MAY reject the JWS if the critical list contains any 621 Header Parameter names defined by the initial RFC versions of [[ this 622 specification ]] or [JWA] for use with JWS, or any other constraints 623 on its use are violated. When used, this Header Parameter MUST be 624 integrity protected; therefore, it MUST occur only within the JWS 625 Protected Header. Use of this Header Parameter is OPTIONAL. This 626 Header Parameter MUST be understood and processed by implementations. 628 An example use, along with a hypothetical "exp" (expiration-time) 629 field is: 631 {"alg":"ES256", 632 "crit":["exp"], 633 "exp":1363284000 634 } 636 4.2. Public Header Parameter Names 638 Additional Header Parameter names can be defined by those using JWSs. 639 However, in order to prevent collisions, any new Header Parameter 640 name should either be registered in the IANA JSON Web Signature and 641 Encryption Header Parameters registry defined in Section 9.1 or be a 642 Public Name: a value that contains a Collision-Resistant Name. In 643 each case, the definer of the name or value needs to take reasonable 644 precautions to make sure they are in control of the part of the 645 namespace they use to define the Header Parameter name. 647 New Header Parameters should be introduced sparingly, as they can 648 result in non-interoperable JWSs. 650 4.3. Private Header Parameter Names 652 A producer and consumer of a JWS may agree to use Header Parameter 653 names that are Private Names: names that are not Registered Header 654 Parameter names Section 4.1 or Public Header Parameter names 655 Section 4.2. Unlike Public Header Parameter names, Private Header 656 Parameter names are subject to collision and should be used with 657 caution. 659 5. Producing and Consuming JWSs 661 5.1. Message Signature or MAC Computation 663 To create a JWS, the following steps are performed. The order of the 664 steps is not significant in cases where there are no dependencies 665 between the inputs and outputs of the steps. 667 1. Create the content to be used as the JWS Payload. 669 2. Compute the encoded payload value BASE64URL(JWS Payload). 671 3. Create the JSON object(s) containing the desired set of Header 672 Parameters, which together comprise the JOSE Header: if the JWS 673 Compact Serialization is being used, the JWS Protected Header, or 674 if the JWS JSON Serialization is being used, the JWS Protected 675 Header and/or the JWS Unprotected Header. 677 4. Compute the encoded header value BASE64URL(UTF8(JWS Protected 678 Header)). If the JWS Protected Header is not present (which can 679 only happen when using the JWS JSON Serialization and no 680 "protected" member is present), let this value be the empty 681 string. 683 5. Compute the JWS Signature in the manner defined for the 684 particular algorithm being used over the JWS Signing Input 685 ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || 686 BASE64URL(JWS Payload)). The "alg" (algorithm) Header Parameter 687 MUST be present in the JOSE Header, with the algorithm value 688 accurately representing the algorithm used to construct the JWS 689 Signature. 691 6. Compute the encoded signature value BASE64URL(JWS Signature). 693 7. If the JWS JSON Serialization is being used, repeat this process 694 (steps 3-6) for each digital signature or MAC operation being 695 performed. 697 8. Create the desired serialized output. The JWS Compact 698 Serialization of this result is BASE64URL(UTF8(JWS Protected 699 Header)) || '.' || BASE64URL(JWS Payload) || '.' || BASE64URL(JWS 700 Signature). The JWS JSON Serialization is described in 701 Section 7.2. 703 5.2. Message Signature or MAC Validation 705 When validating a JWS, the following steps are performed. The order 706 of the steps is not significant in cases where there are no 707 dependencies between the inputs and outputs of the steps. If any of 708 the listed steps fails, then the signature or MAC cannot be 709 validated. 711 When there are multiple JWS Signature values, it is an application 712 decision which of the JWS Signature values must successfully validate 713 for the JWS to be accepted. In some cases, all must successfully 714 validate or the JWS will be considered invalid. In other cases, only 715 a specific JWS Signature value needs to be successfully validated. 716 However, in all cases, at least one JWS Signature value MUST 717 successfully validate or the JWS MUST be considered invalid. 719 1. Parse the JWS representation to extract the serialized values 720 for the components of the JWS. When using the JWS Compact 721 Serialization, these components are the base64url encoded 722 representations of the JWS Protected Header, the JWS Payload, 723 and the JWS Signature, and when using the JWS JSON 724 Serialization, these components also include the unencoded JWS 725 Unprotected Header value. When using the JWS Compact 726 Serialization, the JWS Protected Header, the JWS Payload, and 727 the JWS Signature are represented as base64url encoded values in 728 that order, with each value being separated from the next by a 729 single period ('.') character, resulting in exactly two 730 delimiting period characters being used. The JWS JSON 731 Serialization is described in Section 7.2. 733 2. Base64url decode the encoded representation of the JWS Protected 734 Header, following the restriction that no line breaks, white 735 space, or other additional characters have been used. 737 3. Verify that the resulting octet sequence is a UTF-8 encoded 738 representation of a completely valid JSON object conforming to 739 RFC 7159 [RFC7159]; let the JWS Protected Header be this JSON 740 object. 742 4. If using the JWS Compact Serialization, let the JOSE Header be 743 the JWS Protected Header. Otherwise, when using the JWS JSON 744 Serialization, let the JOSE Header be the union of the members 745 of the corresponding JWS Protected Header and JWS Unprotected 746 Header, all of which must be completely valid JSON objects. 747 During this step, verify that the resulting JOSE Header does not 748 contain duplicate Header Parameter names. When using the JWS 749 JSON Serialization, this restriction includes that the same 750 Header Parameter name also MUST NOT occur in distinct JSON 751 object values that together comprise the JOSE Header. 753 5. Verify that the implementation understands and can process all 754 fields that it is required to support, whether required by this 755 specification, by the algorithm being used, or by the "crit" 756 Header Parameter value, and that the values of those parameters 757 are also understood and supported. 759 6. Base64url decode the encoded representation of the JWS Payload, 760 following the restriction that no line breaks, white space, or 761 other additional characters have been used. 763 7. Base64url decode the encoded representation of the JWS 764 Signature, following the restriction that no line breaks, white 765 space, or other additional characters have been used. 767 8. Validate the JWS Signature against the JWS Signing Input 768 ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || 769 BASE64URL(JWS Payload)) in the manner defined for the algorithm 770 being used, which MUST be accurately represented by the value of 771 the "alg" (algorithm) Header Parameter, which MUST be present. 772 See Section 10.6 for security considerations on algorithm 773 validation. Record whether the validation succeeded or not. 775 9. If the JWS JSON Serialization is being used, repeat this process 776 (steps 4-8) for each digital signature or MAC value contained in 777 the representation. 779 10. If none of the validations in step 9 succeeded, then the JWS 780 MUST be considered invalid. Otherwise, in the JWS JSON 781 Serialization case, return a result to the application 782 indicating which of the validations succeeded and failed. In 783 the JWS Compact Serialization case, the result can simply 784 indicate whether or not the JWS was successfully validated. 786 Finally, note that it is an application decision which algorithms may 787 be used in a given context. Even if a JWS can be successfully 788 validated, unless the algorithm(s) used in the JWS are acceptable to 789 the application, it SHOULD consider the JWS to be invalid. 791 5.3. String Comparison Rules 793 Processing a JWS inevitably requires comparing known strings to 794 members and values in JSON objects. For example, in checking what 795 the algorithm is, the Unicode string "alg" will be checked against 796 the member names in the JOSE Header to see if there is a matching 797 Header Parameter name. The same process is then used to determine if 798 the value of the "alg" Header Parameter represents a supported 799 algorithm. 801 The JSON rules for doing member name comparison are described in 802 Section 8.3 of RFC 7159 [RFC7159]. Since the only string comparison 803 operations that are performed are equality and inequality, the same 804 rules can be used for comparing both member names and member values 805 against known strings. 807 These comparison rules MUST be used for all JSON string comparisons 808 except in cases where the definition of the member explicitly calls 809 out that a different comparison rule is to be used for that member 810 value. Only the "typ" and "cty" member values defined in this 811 specification do not use these comparison rules. 813 Some applications may include case-insensitive information in a case- 814 sensitive value, such as including a DNS name as part of a "kid" (key 815 ID) value. In those cases, the application may need to define a 816 convention for the canonical case to use for representing the case- 817 insensitive portions, such as lowercasing them, if more than one 818 party might need to produce the same value so that they can be 819 compared. (However if all other parties consume whatever value the 820 producing party emitted verbatim without attempting to compare it to 821 an independently produced value, then the case used by the producer 822 will not matter.) 824 Also, see the JSON security considerations in Section 10.12 and the 825 Unicode security considerations in Section 10.13. 827 6. Key Identification 829 It is necessary for the recipient of a JWS to be able to determine 830 the key that was employed for the digital signature or MAC operation. 831 The key employed can be identified using the Header Parameter methods 832 described in Section 4.1 or can be identified using methods that are 833 outside the scope of this specification. Specifically, the Header 834 Parameters "jku", "jwk", "kid", "x5u", "x5c", "x5t", and "x5t#S256" 835 can be used to identify the key used. These Header Parameters MUST 836 be integrity protected if the information that they convey is to be 837 utilized in a trust decision; however, if the only information used 838 in the trust decision is a key, these parameters need not be 839 integrity protected, since changing them in a way that causes a 840 different key to be used will cause the validation to fail. 842 The producer SHOULD include sufficient information in the Header 843 Parameters to identify the key used, unless the application uses 844 another means or convention to determine the key used. Validation of 845 the signature or MAC fails when the algorithm used requires a key 846 (which is true of all algorithms except for "none") and the key used 847 cannot be determined. 849 The means of exchanging any shared symmetric keys used is outside the 850 scope of this specification. 852 Also, see Appendix D for notes on possible key selection algorithms. 854 7. Serializations 856 JWSs use one of two serializations: the JWS Compact Serialization or 857 the JWS JSON Serialization. Applications using this specification 858 need to specify what serialization and serialization features are 859 used for that application. For instance, applications might specify 860 that only the JWS JSON Serialization is used, that only JWS JSON 861 Serialization support for a single signature or MAC value is used, or 862 that support for multiple signatures and/or MAC values is used. JWS 863 implementations only need to implement the features needed for the 864 applications they are designed to support. 866 7.1. JWS Compact Serialization 868 The JWS Compact Serialization represents digitally signed or MACed 869 content as a compact, URL-safe string. This string is: 871 BASE64URL(UTF8(JWS Protected Header)) || '.' || 872 BASE64URL(JWS Payload) || '.' || 873 BASE64URL(JWS Signature) 875 Only one signature/MAC is supported by the JWS Compact Serialization 876 and it provides no syntax to represent a JWS Unprotected Header 877 value. 879 7.2. JWS JSON Serialization 881 The JWS JSON Serialization represents digitally signed or MACed 882 content as a JSON object. This representation is neither optimized 883 for compactness nor URL-safe. 885 Two closely related syntaxes are defined for the JWS JSON 886 Serialization: a fully general syntax, with which content can be 887 secured with more than one digital signature and/or MAC operation, 888 and a flattened syntax, which is optimized for the single digital 889 signature or MAC case. 891 7.2.1. General JWS JSON Serialization Syntax 893 The following members are defined for use in top-level JSON objects 894 used for the fully general JWS JSON Serialization syntax: 896 payload 897 The "payload" member MUST be present and contain the value 898 BASE64URL(JWS Payload). 900 signatures 901 The "signatures" member value MUST be an array of JSON objects. 902 Each object represents a signature or MAC over the JWS Payload and 903 the JWS Protected Header. 905 The following members are defined for use in the JSON objects that 906 are elements of the "signatures" array: 908 protected 909 The "protected" member MUST be present and contain the value 910 BASE64URL(UTF8(JWS Protected Header)) when the JWS Protected 911 Header value is non-empty; otherwise, it MUST be absent. These 912 Header Parameter values are integrity protected. 914 header 915 The "header" member MUST be present and contain the value JWS 916 Unprotected Header when the JWS Unprotected Header value is non- 917 empty; otherwise, it MUST be absent. This value is represented as 918 an unencoded JSON object, rather than as a string. These Header 919 Parameter values are not integrity protected. 921 signature 922 The "signature" member MUST be present and contain the value 923 BASE64URL(JWS Signature). 925 At least one of the "protected" and "header" members MUST be present 926 for each signature/MAC computation so that an "alg" Header Parameter 927 value is conveyed. 929 Additional members can be present in both the JSON objects defined 930 above; if not understood by implementations encountering them, they 931 MUST be ignored. 933 The Header Parameter values used when creating or validating 934 individual signature or MAC values are the union of the two sets of 935 Header Parameter values that may be present: (1) the JWS Protected 936 Header represented in the "protected" member of the signature/MAC's 937 array element, and (2) the JWS Unprotected Header in the "header" 938 member of the signature/MAC's array element. The union of these sets 939 of Header Parameters comprises the JOSE Header. The Header Parameter 940 names in the two locations MUST be disjoint. 942 Each JWS Signature value is computed using the parameters of the 943 corresponding JOSE Header value in the same manner as for the JWS 944 Compact Serialization. This has the desirable property that each JWS 945 Signature value represented in the "signatures" array is identical to 946 the value that would have been computed for the same parameter in the 947 JWS Compact Serialization, provided that the JWS Protected Header 948 value for that signature/MAC computation (which represents the 949 integrity protected Header Parameter values) matches that used in the 950 JWS Compact Serialization. 952 In summary, the syntax of a JWS using the general JWS JSON 953 Serialization is as follows: 955 { 956 "payload":"", 957 "signatures":[ 958 {"protected":"", 959 "header":, 960 "signature":""}, 961 ... 962 {"protected":"", 963 "header":, 964 "signature":""}] 965 } 967 See Appendix A.6 for an example JWS using the general JWS JSON 968 Serialization syntax. 970 7.2.2. Flattened JWS JSON Serialization Syntax 972 The flattened JWS JSON Serialization syntax is based upon the general 973 syntax, but flattens it, optimizing it for the single digital 974 signature/MAC case. It flattens it by removing the "signatures" 975 member and instead placing those members defined for use in the 976 "signatures" array (the "protected", "header", and "signature" 977 members) in the top-level JSON object (at the same level as the 978 "payload" member). 980 The "signatures" member MUST NOT be present when using this syntax. 981 Other than this syntax difference, JWS JSON Serialization objects 982 using the flattened syntax are processed identically to those using 983 the general syntax. 985 In summary, the syntax of a JWS using the flattened JWS JSON 986 Serialization is as follows: 988 { 989 "payload":"", 990 "protected":"", 991 "header":, 992 "signature":"" 993 } 995 See Appendix A.7 for an example JWS using the flattened JWS JSON 996 Serialization syntax. 998 8. TLS Requirements 1000 Implementations supporting the "jku" and/or "x5u" Header Parameters 1001 MUST support TLS. Which TLS version(s) ought to be implemented will 1002 vary over time, and depend on the widespread deployment and known 1003 security vulnerabilities at the time of implementation. At the time 1004 of this writing, TLS version 1.2 [RFC5246] is the most recent 1005 version. 1007 To protect against information disclosure and tampering, 1008 confidentiality protection MUST be applied using TLS with a 1009 ciphersuite that provides confidentiality and integrity protection. 1010 See current publications by the IETF TLS working group, including RFC 1011 6176 [RFC6176], for guidance on the ciphersuites currently considered 1012 to be appropriate for use. Also, see Recommendations for Secure Use 1013 of TLS and DTLS [I-D.ietf-uta-tls-bcp] for recommendations on 1014 improving the security of software and services using TLS. 1016 Whenever TLS is used, the identity of the service provider encoded in 1017 the TLS server certificate MUST be verified using the procedures 1018 described in Section 6 of RFC 6125 [RFC6125]. 1020 9. IANA Considerations 1022 The following registration procedure is used for all the registries 1023 established by this specification. 1025 Values are registered on a Specification Required [RFC5226] basis 1026 after a three-week review period on the jose-reg-review@ietf.org 1027 mailing list, on the advice of one or more Designated Experts. 1028 However, to allow for the allocation of values prior to publication, 1029 the Designated Expert(s) may approve registration once they are 1030 satisfied that such a specification will be published. 1032 Registration requests must be sent to the jose-reg-review@ietf.org 1033 mailing list for review and comment, with an appropriate subject 1034 (e.g., "Request to register header parameter: example"). 1036 Within the review period, the Designated Expert(s) will either 1037 approve or deny the registration request, communicating this decision 1038 to the review list and IANA. Denials should include an explanation 1039 and, if applicable, suggestions as to how to make the request 1040 successful. Registration requests that are undetermined for a period 1041 longer than 21 days can be brought to the IESG's attention (using the 1042 iesg@ietf.org mailing list) for resolution. 1044 Criteria that should be applied by the Designated Expert(s) includes 1045 determining whether the proposed registration duplicates existing 1046 functionality, determining whether it is likely to be of general 1047 applicability or whether it is useful only for a single application, 1048 and whether the registration description is clear. 1050 IANA must only accept registry updates from the Designated Expert(s) 1051 and should direct all requests for registration to the review mailing 1052 list. 1054 It is suggested that multiple Designated Experts be appointed who are 1055 able to represent the perspectives of different applications using 1056 this specification, in order to enable broadly-informed review of 1057 registration decisions. In cases where a registration decision could 1058 be perceived as creating a conflict of interest for a particular 1059 Expert, that Expert should defer to the judgment of the other 1060 Expert(s). 1062 [[ Note to the RFC Editor and IANA: Pearl Liang of ICANN had 1063 requested that the draft supply the following proposed registry 1064 description information. It is to be used for all registries 1065 established by this specification. 1067 o Protocol Category: JSON Object Signing and Encryption (JOSE) 1069 o Registry Location: http://www.iana.org/assignments/jose 1071 o Webpage Title: (same as the protocol category) 1073 o Registry Name: (same as the section title, but excluding the word 1074 "Registry", for example "JSON Web Signature and Encryption Header 1075 Parameters") 1077 ]] 1079 9.1. JSON Web Signature and Encryption Header Parameters Registry 1081 This specification establishes the IANA JSON Web Signature and 1082 Encryption Header Parameters registry for Header Parameter names. 1083 The registry records the Header Parameter name and a reference to the 1084 specification that defines it. The same Header Parameter name can be 1085 registered multiple times, provided that the parameter usage is 1086 compatible between the specifications. Different registrations of 1087 the same Header Parameter name will typically use different Header 1088 Parameter Usage Location(s) values. 1090 9.1.1. Registration Template 1092 Header Parameter Name: 1093 The name requested (e.g., "kid"). Because a core goal of this 1094 specification is for the resulting representations to be compact, 1095 it is RECOMMENDED that the name be short -- not to exceed 8 1096 characters without a compelling reason to do so. This name is 1097 case-sensitive. Names may not match other registered names in a 1098 case-insensitive manner unless the Designated Expert(s) state that 1099 there is a compelling reason to allow an exception in this 1100 particular case. 1102 Header Parameter Description: 1103 Brief description of the Header Parameter (e.g., "Key ID"). 1105 Header Parameter Usage Location(s): 1106 The Header Parameter usage locations, which should be one or more 1107 of the values "JWS" or "JWE". 1109 Change Controller: 1110 For Standards Track RFCs, state "IESG". For others, give the name 1111 of the responsible party. Other details (e.g., postal address, 1112 email address, home page URI) may also be included. 1114 Specification Document(s): 1115 Reference to the document(s) that specify the parameter, 1116 preferably including URI(s) that can be used to retrieve copies of 1117 the document(s). An indication of the relevant sections may also 1118 be included but is not required. 1120 9.1.2. Initial Registry Contents 1122 This specification registers the Header Parameter names defined in 1123 Section 4.1 in this registry. 1125 o Header Parameter Name: "alg" 1126 o Header Parameter Description: Algorithm 1127 o Header Parameter Usage Location(s): JWS 1128 o Change Controller: IESG 1129 o Specification Document(s): Section 4.1.1 of [[ this document ]] 1131 o Header Parameter Name: "jku" 1132 o Header Parameter Description: JWK Set URL 1133 o Header Parameter Usage Location(s): JWS 1134 o Change Controller: IESG 1135 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1136 o Header Parameter Name: "jwk" 1137 o Header Parameter Description: JSON Web Key 1138 o Header Parameter Usage Location(s): JWS 1139 o Change Controller: IESG 1140 o Specification document(s): Section 4.1.3 of [[ this document ]] 1142 o Header Parameter Name: "kid" 1143 o Header Parameter Description: Key ID 1144 o Header Parameter Usage Location(s): JWS 1145 o Change Controller: IESG 1146 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1148 o Header Parameter Name: "x5u" 1149 o Header Parameter Description: X.509 URL 1150 o Header Parameter Usage Location(s): JWS 1151 o Change Controller: IESG 1152 o Specification Document(s): Section 4.1.5 of [[ this document ]] 1154 o Header Parameter Name: "x5c" 1155 o Header Parameter Description: X.509 Certificate Chain 1156 o Header Parameter Usage Location(s): JWS 1157 o Change Controller: IESG 1158 o Specification Document(s): Section 4.1.6 of [[ this document ]] 1160 o Header Parameter Name: "x5t" 1161 o Header Parameter Description: X.509 Certificate SHA-1 Thumbprint 1162 o Header Parameter Usage Location(s): JWS 1163 o Change Controller: IESG 1164 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1166 o Header Parameter Name: "x5t#S256" 1167 o Header Parameter Description: X.509 Certificate SHA-256 Thumbprint 1168 o Header Parameter Usage Location(s): JWS 1169 o Change Controller: IESG 1170 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1172 o Header Parameter Name: "typ" 1173 o Header Parameter Description: Type 1174 o Header Parameter Usage Location(s): JWS 1175 o Change Controller: IESG 1176 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1178 o Header Parameter Name: "cty" 1179 o Header Parameter Description: Content Type 1180 o Header Parameter Usage Location(s): JWS 1181 o Change Controller: IESG 1182 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1184 o Header Parameter Name: "crit" 1185 o Header Parameter Description: Critical 1186 o Header Parameter Usage Location(s): JWS 1187 o Change Controller: IESG 1188 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1190 9.2. Media Type Registration 1192 9.2.1. Registry Contents 1194 This specification registers the "application/jose" Media Type 1195 [RFC2046] in the MIME Media Types registry [IANA.MediaTypes] in the 1196 manner described in RFC 6838 [RFC6838], which can be used to indicate 1197 that the content is a JWS or JWE using the JWS Compact Serialization 1198 or the JWE Compact Serialization and the "application/jose+json" 1199 Media Type in the MIME Media Types registry, which can be used to 1200 indicate that the content is a JWS or JWE using the JWS JSON 1201 Serialization or the JWE JSON Serialization. 1203 o Type name: application 1204 o Subtype name: jose 1205 o Required parameters: n/a 1206 o Optional parameters: n/a 1207 o Encoding considerations: 8bit; application/jose values are encoded 1208 as a series of base64url encoded values (some of which may be the 1209 empty string) each separated from the next by a single period 1210 ('.') character. 1211 o Security considerations: See the Security Considerations section 1212 of [[ this document ]] 1213 o Interoperability considerations: n/a 1214 o Published specification: [[ this document ]] 1215 o Applications that use this media type: OpenID Connect, Mozilla 1216 Persona, Salesforce, Google, Android, Windows Azure, Xbox One, 1217 Amazon Web Services, and numerous others that use JWTs 1218 o Fragment identifier considerations: n/a 1219 o Additional information: Magic number(s): n/a, File extension(s): 1220 n/a, Macintosh file type code(s): n/a 1221 o Person & email address to contact for further information: Michael 1222 B. Jones, mbj@microsoft.com 1223 o Intended usage: COMMON 1224 o Restrictions on usage: none 1225 o Author: Michael B. Jones, mbj@microsoft.com 1226 o Change Controller: IESG 1227 o Provisional registration? No 1228 o Type name: application 1229 o Subtype name: jose+json 1230 o Required parameters: n/a 1231 o Optional parameters: n/a 1232 o Encoding considerations: 8bit; application/jose+json values are 1233 represented as a JSON Object; UTF-8 encoding SHOULD be employed 1234 for the JSON object. 1235 o Security considerations: See the Security Considerations section 1236 of [[ this document ]] 1237 o Interoperability considerations: n/a 1238 o Published specification: [[ this document ]] 1239 o Applications that use this media type: TBD 1240 o Fragment identifier considerations: n/a 1241 o Additional information: Magic number(s): n/a, File extension(s): 1242 n/a, Macintosh file type code(s): n/a 1243 o Person & email address to contact for further information: Michael 1244 B. Jones, mbj@microsoft.com 1245 o Intended usage: COMMON 1246 o Restrictions on usage: none 1247 o Author: Michael B. Jones, mbj@microsoft.com 1248 o Change Controller: IESG 1249 o Provisional registration? No 1251 10. Security Considerations 1253 All of the security issues that are pertinent to any cryptographic 1254 application must be addressed by JWS/JWE/JWK agents. Among these 1255 issues are protecting the user's asymmetric private and symmetric 1256 secret keys and employing countermeasures to various attacks. 1258 All the security considerations in XML DSIG 2.0 1259 [W3C.NOTE-xmldsig-core2-20130411], also apply to this specification, 1260 other than those that are XML specific. Likewise, many of the best 1261 practices documented in XML Signature Best Practices 1262 [W3C.NOTE-xmldsig-bestpractices-20130411] also apply to this 1263 specification, other than those that are XML specific. 1265 10.1. Key Entropy and Random Values 1267 Keys are only as strong as the amount of entropy used to generate 1268 them. A minimum of 128 bits of entropy should be used for all keys, 1269 and depending upon the application context, more may be required. 1271 Implementations must randomly generate public/private key pairs, 1272 message authentication (MAC) keys, and padding values. The use of 1273 inadequate pseudo-random number generators (PRNGs) to generate 1274 cryptographic keys can result in little or no security. An attacker 1275 may find it much easier to reproduce the PRNG environment that 1276 produced the keys, searching the resulting small set of 1277 possibilities, rather than brute force searching the whole key space. 1278 The generation of quality random numbers is difficult. RFC 4086 1279 [RFC4086] offers important guidance in this area. 1281 10.2. Key Protection 1283 Implementations must protect the signer's private key. Compromise of 1284 the signer's private key permits an attacker to masquerade as the 1285 signer. 1287 Implementations must protect the message authentication (MAC) key. 1288 Compromise of the MAC key may result in undetectable modification of 1289 the authenticated content. 1291 10.3. Key Origin Authentication 1293 The key management technique employed to obtain public keys must 1294 authenticate the origin of the key; otherwise, it is unknown what 1295 party signed the message. 1297 Likewise, the key management technique employed to distribute MAC 1298 keys must provide data origin authentication; otherwise, the contents 1299 are delivered with integrity from an unknown source. 1301 10.4. Cryptographic Agility 1303 See Section 8.1 of [JWA] for security considerations on cryptographic 1304 agility. 1306 10.5. Differences between Digital Signatures and MACs 1308 While MACs and digital signatures can both be used for integrity 1309 checking, there are some significant differences between the security 1310 properties that each of them provides. These need to be taken into 1311 consideration when designing protocols and selecting the algorithms 1312 to be used in protocols. 1314 Both signatures and MACs provide for integrity checking -- verifying 1315 that the message has not been modified since the integrity value was 1316 computed. However, MACs provide for origination identification only 1317 under specific circumstances. It can normally be assumed that a 1318 private key used for a signature is only in the hands of a single 1319 entity (although perhaps a distributed entity, in the case of 1320 replicated servers); however, a MAC key needs to be in the hands of 1321 all the entities that use it for integrity computation and checking. 1322 Validation of a MAC only provides corroboration that the message was 1323 generated by one of the parties that knows the symmetric MAC key. 1324 This means that origination can only be determined if a MAC key is 1325 known only to two entities and the recipient knows that it did not 1326 create the message. MAC validation cannot be used to prove 1327 origination to a third party. 1329 10.6. Algorithm Validation 1331 The digital signature representations for some algorithms include 1332 information about the algorithm used inside the signature value. For 1333 instance, signatures produced with RSASSA-PKCS-v1_5 [RFC3447] encode 1334 the hash function used and many libraries actually use the hash 1335 algorithm specified inside the signature when validating the 1336 signature. When using such libraries, as part of the algorithm 1337 validation performed, implementations MUST ensure that the algorithm 1338 information encoded in the signature corresponds to that specified 1339 with the "alg" Header Parameter. If this is not done, an attacker 1340 could claim to have used a strong hash algorithm while actually using 1341 a weak one represented in the signature value. 1343 10.7. Algorithm Protection 1345 In some usages of JWS, there is a risk of algorithm substitution 1346 attacks, in which an attacker can use an existing digital signature 1347 value with a different signature algorithm to make it appear that a 1348 signer has signed something that it has not. These attacks have been 1349 discussed in detail in the context of CMS [RFC6211]. This risk 1350 arises when all of the following are true: 1352 o Verifiers of a signature support multiple algorithms. 1354 o Given an existing signature, an attacker can find another payload 1355 that produces the same signature value with a different algorithm. 1357 o The payload crafted by the attacker is valid in the application 1358 context. 1360 There are several ways for an application to mitigate algorithm 1361 substitution attacks: 1363 o Use only digital signature algorithms that are not vulnerable to 1364 substitution attacks. Substitution attacks are only feasible if 1365 an attacker can compute pre-images for a hash function accepted by 1366 the recipient. All JWA-defined signature algorithms use SHA-2 1367 hashes, for which there are no known pre-image attacks, as of the 1368 time of this writing. 1370 o Require that the "alg" Header Parameter be carried in the 1371 protected header. (This is always the case when using the JWS 1372 Compact Serialization and is the approach taken by CMS [RFC6211].) 1374 o Include a field containing the algorithm in the application 1375 payload, and require that it be matched with the "alg" Header 1376 Parameter during verification. (This is the approach taken by 1377 PKIX [RFC5280].) 1379 10.8. Chosen Plaintext Attacks 1381 Creators of JWSs should not allow third parties to insert arbitrary 1382 content into the message without adding entropy not controlled by the 1383 third party. 1385 10.9. Timing Attacks 1387 When cryptographic algorithms are implemented in such a way that 1388 successful operations take a different amount of time than 1389 unsuccessful operations, attackers may be able to use the time 1390 difference to obtain information about the keys employed. Therefore, 1391 such timing differences must be avoided. 1393 10.10. Replay Protection 1395 While not directly in scope for this specification, note that 1396 applications using JWS (or JWE) objects can thwart replay attacks by 1397 including a unique message identifier as integrity protected content 1398 in the JWS (or JWE) message and having the recipient verify that the 1399 message has not been previously received or acted upon. 1401 10.11. SHA-1 Certificate Thumbprints 1403 A SHA-1 hash is used when computing "x5t" (X.509 Certificate SHA-1 1404 Thumbprint) values, for compatibility reasons. Should an effective 1405 means of producing SHA-1 hash collisions be developed, and should an 1406 attacker wish to interfere with the use of a known certificate on a 1407 given system, this could be accomplished by creating another 1408 certificate whose SHA-1 hash value is the same and adding it to the 1409 certificate store used by the intended victim. A prerequisite to 1410 this attack succeeding is the attacker having write access to the 1411 intended victim's certificate store. 1413 Alternatively, the "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) 1414 Header Parameter could be used instead of "x5t". However, at the 1415 time of this writing, no development platform is known to support 1416 SHA-256 certificate thumbprints. 1418 10.12. JSON Security Considerations 1420 Strict JSON [RFC7159] validation is a security requirement. If 1421 malformed JSON is received, then the intent of the producer is 1422 impossible to reliably discern. Ambiguous and potentially 1423 exploitable situations could arise if the JSON parser used does not 1424 reject malformed JSON syntax. In particular, any JSON inputs not 1425 conforming to the JSON-text syntax defined in RFC 7159 input MUST be 1426 rejected in their entirety by JSON parsers. 1428 Section 4 of the JSON Data Interchange Format specification [RFC7159] 1429 states "The names within an object SHOULD be unique", whereas this 1430 specification states that "Header Parameter names within this object 1431 MUST be unique; JWS parsers MUST either reject JWSs with duplicate 1432 Header Parameter names or use a JSON parser that returns only the 1433 lexically last duplicate member name, as specified in Section 15.12 1434 (The JSON Object) of ECMAScript 5.1 [ECMAScript]". Thus, this 1435 specification requires that the Section 4 "SHOULD" be treated as a 1436 "MUST" by producers and that it be either treated as a "MUST" or in 1437 the manner specified in ECMAScript 5.1 by consumers. Ambiguous and 1438 potentially exploitable situations could arise if the JSON parser 1439 used does not enforce the uniqueness of member names or returns an 1440 unpredictable value for duplicate member names. 1442 Some JSON parsers might not reject input that contains extra 1443 significant characters after a valid input. For instance, the input 1444 "{"tag":"value"}ABCD" contains a valid JSON-text object followed by 1445 the extra characters "ABCD". Such input MUST be rejected in its 1446 entirety. 1448 10.13. Unicode Comparison Security Considerations 1450 Header Parameter names and algorithm names are Unicode strings. For 1451 security reasons, the representations of these names must be compared 1452 verbatim after performing any escape processing (as per Section 8.3 1453 of RFC 7159 [RFC7159]). This means, for instance, that these JSON 1454 strings must compare as being equal ("sig", "\u0073ig"), whereas 1455 these must all compare as being not equal to the first set or to each 1456 other ("SIG", "Sig", "si\u0047"). 1458 JSON strings can contain characters outside the Unicode Basic 1459 Multilingual Plane. For instance, the G clef character (U+1D11E) may 1460 be represented in a JSON string as "\uD834\uDD1E". Ideally, JWS 1461 implementations SHOULD ensure that characters outside the Basic 1462 Multilingual Plane are preserved and compared correctly; 1463 alternatively, if this is not possible due to these characters 1464 exercising limitations present in the underlying JSON implementation, 1465 then input containing them MUST be rejected. 1467 11. References 1469 11.1. Normative References 1471 [ECMAScript] 1472 Ecma International, "ECMAScript Language Specification, 1473 5.1 Edition", ECMA 262, June 2011. 1475 [IANA.MediaTypes] 1476 Internet Assigned Numbers Authority (IANA), "MIME Media 1477 Types", 2005. 1479 [ITU.X690.1994] 1480 International Telecommunications Union, "Information 1481 Technology - ASN.1 encoding rules: Specification of Basic 1482 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1483 Distinguished Encoding Rules (DER)", ITU-T Recommendation 1484 X.690, 1994. 1486 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1487 draft-ietf-jose-json-web-algorithms (work in progress), 1488 December 2014. 1490 [JWK] Jones, M., "JSON Web Key (JWK)", 1491 draft-ietf-jose-json-web-key (work in progress), 1492 December 2014. 1494 [RFC20] Cerf, V., "ASCII format for Network Interchange", RFC 20, 1495 October 1969. 1497 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1498 Extensions (MIME) Part One: Format of Internet Message 1499 Bodies", RFC 2045, November 1996. 1501 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1502 Extensions (MIME) Part Two: Media Types", RFC 2046, 1503 November 1996. 1505 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1506 Requirement Levels", BCP 14, RFC 2119, March 1997. 1508 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1510 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1511 10646", STD 63, RFC 3629, November 2003. 1513 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1514 Resource Identifier (URI): Generic Syntax", STD 66, 1515 RFC 3986, January 2005. 1517 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1518 Encodings", RFC 4648, October 2006. 1520 [RFC4945] Korver, B., "The Internet IP Security PKI Profile of 1521 IKEv1/ISAKMP, IKEv2, and PKIX", RFC 4945, August 2007. 1523 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1524 RFC 4949, August 2007. 1526 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1527 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1529 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1530 Housley, R., and W. Polk, "Internet X.509 Public Key 1531 Infrastructure Certificate and Certificate Revocation List 1532 (CRL) Profile", RFC 5280, May 2008. 1534 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1535 Verification of Domain-Based Application Service Identity 1536 within Internet Public Key Infrastructure Using X.509 1537 (PKIX) Certificates in the Context of Transport Layer 1538 Security (TLS)", RFC 6125, March 2011. 1540 [RFC6176] Turner, S. and T. Polk, "Prohibiting Secure Sockets Layer 1541 (SSL) Version 2.0", RFC 6176, March 2011. 1543 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1544 Interchange Format", RFC 7159, March 2014. 1546 11.2. Informative References 1548 [CanvasApp] 1549 Facebook, "Canvas Applications", 2010. 1551 [I-D.ietf-uta-tls-bcp] 1552 Sheffer, Y., Holz, R., and P. Saint-Andre, 1553 "Recommendations for Secure Use of TLS and DTLS", 1554 draft-ietf-uta-tls-bcp-07 (work in progress), 1555 November 2014. 1557 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 1558 September 2010. 1560 [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 1561 draft-ietf-jose-json-web-encryption (work in progress), 1562 December 2014. 1564 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1565 (JWT)", draft-ietf-oauth-json-web-token (work in 1566 progress), December 2014. 1568 [MagicSignatures] 1569 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 1570 Signatures", January 2011. 1572 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1573 Hashing for Message Authentication", RFC 2104, 1574 February 1997. 1576 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1577 Standards (PKCS) #1: RSA Cryptography Specifications 1578 Version 2.1", RFC 3447, February 2003. 1580 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1581 Requirements for Security", BCP 106, RFC 4086, June 2005. 1583 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1584 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1585 July 2005. 1587 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1588 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1589 May 2008. 1591 [RFC6211] Schaad, J., "Cryptographic Message Syntax (CMS) Algorithm 1592 Identifier Protection Attribute", RFC 6211, April 2011. 1594 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1595 Specifications and Registration Procedures", BCP 13, 1596 RFC 6838, January 2013. 1598 [SHS] National Institute of Standards and Technology, "Secure 1599 Hash Standard (SHS)", FIPS PUB 180-4, March 2012. 1601 [W3C.NOTE-xmldsig-bestpractices-20130411] 1602 Hirsch, F. and P. Datta, "XML Signature Best Practices", 1603 World Wide Web Consortium Note NOTE-xmldsig-bestpractices- 1604 20130411, April 2013, . 1607 [W3C.NOTE-xmldsig-core2-20130411] 1608 Eastlake, D., Reagle, J., Solo, D., Hirsch, F., Roessler, 1609 T., Yiu, K., Datta, P., and S. Cantor, "XML Signature 1610 Syntax and Processing Version 2.0", World Wide Web 1611 Consortium Note NOTE-xmldsig-core2-20130411, April 2013, 1612 . 1614 Appendix A. JWS Examples 1616 This section provides several examples of JWSs. While the first 1617 three examples all represent JSON Web Tokens (JWTs) [JWT], the 1618 payload can be any octet sequence, as shown in Appendix A.4. 1620 A.1. Example JWS using HMAC SHA-256 1622 A.1.1. Encoding 1624 The following example JWS Protected Header declares that the data 1625 structure is a JSON Web Token (JWT) [JWT] and the JWS Signing Input 1626 is secured using the HMAC SHA-256 algorithm. 1628 {"typ":"JWT", 1629 "alg":"HS256"} 1631 To remove potential ambiguities in the representation of the JSON 1632 object above, the actual octet sequence representing UTF8(JWS 1633 Protected Header) used in this example is also included below. (Note 1634 that ambiguities can arise due to differing platform representations 1635 of line breaks (CRLF versus LF), differing spacing at the beginning 1636 and ends of lines, whether the last line has a terminating line break 1637 or not, and other causes. In the representation used in this 1638 example, the first line has no leading or trailing spaces, a CRLF 1639 line break (13, 10) occurs between the first and second lines, the 1640 second line has one leading space (32) and no trailing spaces, and 1641 the last line does not have a terminating line break.) The octets 1642 representing UTF8(JWS Protected Header) in this example (using JSON 1643 array notation) are: 1645 [123, 34, 116, 121, 112, 34, 58, 34, 74, 87, 84, 34, 44, 13, 10, 32, 1646 34, 97, 108, 103, 34, 58, 34, 72, 83, 50, 53, 54, 34, 125] 1648 Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected 1649 Header)) gives this value: 1651 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 1653 The JWS Payload used in this example is the octets of the UTF-8 1654 representation of the JSON object below. (Note that the payload can 1655 be any base64url encoded octet sequence, and need not be a base64url 1656 encoded JSON object.) 1657 {"iss":"joe", 1658 "exp":1300819380, 1659 "http://example.com/is_root":true} 1661 The following octet sequence, which is the UTF-8 representation used 1662 in this example for the JSON object above, is the JWS Payload: 1664 [123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10, 1665 32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56, 1666 48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97, 1667 109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111, 1668 111, 116, 34, 58, 116, 114, 117, 101, 125] 1670 Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected 1671 Header)) gives this value (with line breaks for display purposes 1672 only): 1674 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1675 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1677 Combining these as BASE64URL(UTF8(JWS Protected Header)) || '.' || 1678 BASE64URL(JWS Payload) gives this string (with line breaks for 1679 display purposes only): 1681 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 1682 . 1683 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1684 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1686 The resulting JWS Signing Input value, which is the ASCII 1687 representation of above string, is the following octet sequence 1688 (using JSON array notation): 1690 [101, 121, 74, 48, 101, 88, 65, 105, 79, 105, 74, 75, 86, 49, 81, 1691 105, 76, 65, 48, 75, 73, 67, 74, 104, 98, 71, 99, 105, 79, 105, 74, 1692 73, 85, 122, 73, 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 1693 77, 105, 79, 105, 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 1694 74, 108, 101, 72, 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 1695 107, 122, 79, 68, 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 1696 72, 65, 54, 76, 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 1697 109, 78, 118, 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 1698 106, 112, 48, 99, 110, 86, 108, 102, 81] 1700 HMACs are generated using keys. This example uses the symmetric key 1701 represented in JSON Web Key [JWK] format below (with line breaks 1702 within values for display purposes only): 1704 {"kty":"oct", 1705 "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75 1706 aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow" 1707 } 1709 Running the HMAC SHA-256 algorithm on the JWS Signing Input with this 1710 key yields this JWS Signature octet sequence: 1712 [116, 24, 223, 180, 151, 153, 224, 37, 79, 250, 96, 125, 216, 173, 1713 187, 186, 22, 212, 37, 77, 105, 214, 191, 240, 91, 88, 5, 88, 83, 1714 132, 141, 121] 1716 Encoding this JWS Signature as BASE64URL(JWS Signature) gives this 1717 value: 1719 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 1721 Concatenating these values in the order Header.Payload.Signature with 1722 period ('.') characters between the parts yields this complete JWS 1723 representation using the JWS Compact Serialization (with line breaks 1724 for display purposes only): 1726 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 1727 . 1728 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1729 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1730 . 1731 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 1733 A.1.2. Validating 1735 Since the "alg" Header Parameter is "HS256", we validate the HMAC 1736 SHA-256 value contained in the JWS Signature. 1738 To validate the HMAC value, we repeat the previous process of using 1739 the correct key and the JWS Signing Input (which is the initial 1740 substring of the JWS Compact Serialization representation up until 1741 but not including the second period character) as input to the HMAC 1742 SHA-256 function and then taking the output and determining if it 1743 matches the JWS Signature (which is base64url decoded from the value 1744 encoded in the JWS representation). If it matches exactly, the HMAC 1745 has been validated. 1747 A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 1748 A.2.1. Encoding 1750 The JWS Protected Header in this example is different from the 1751 previous example in two ways: First, because a different algorithm is 1752 being used, the "alg" value is different. Second, for illustration 1753 purposes only, the optional "typ" parameter is not used. (This 1754 difference is not related to the algorithm employed.) The JWS 1755 Protected Header used is: 1757 {"alg":"RS256"} 1759 The octets representing UTF8(JWS Protected Header) in this example 1760 (using JSON array notation) are: 1762 [123, 34, 97, 108, 103, 34, 58, 34, 82, 83, 50, 53, 54, 34, 125] 1764 Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected 1765 Header)) gives this value: 1767 eyJhbGciOiJSUzI1NiJ9 1769 The JWS Payload used in this example, which follows, is the same as 1770 in the previous example. Since the BASE64URL(JWS Payload) value will 1771 therefore be the same, its computation is not repeated here. 1773 {"iss":"joe", 1774 "exp":1300819380, 1775 "http://example.com/is_root":true} 1777 Combining these as BASE64URL(UTF8(JWS Protected Header)) || '.' || 1778 BASE64URL(JWS Payload) gives this string (with line breaks for 1779 display purposes only): 1781 eyJhbGciOiJSUzI1NiJ9 1782 . 1783 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1784 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1786 The resulting JWS Signing Input value, which is the ASCII 1787 representation of above string, is the following octet sequence: 1789 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 122, 73, 1790 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, 1791 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 74, 108, 101, 72, 1792 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 107, 122, 79, 68, 1793 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 72, 65, 54, 76, 1794 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 109, 78, 118, 1795 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48, 1796 99, 110, 86, 108, 102, 81] 1798 This example uses the RSA key represented in JSON Web Key [JWK] 1799 format below (with line breaks within values for display purposes 1800 only): 1802 {"kty":"RSA", 1803 "n":"ofgWCuLjybRlzo0tZWJjNiuSfb4p4fAkd_wWJcyQoTbji9k0l8W26mPddx 1804 HmfHQp-Vaw-4qPCJrcS2mJPMEzP1Pt0Bm4d4QlL-yRT-SFd2lZS-pCgNMs 1805 D1W_YpRPEwOWvG6b32690r2jZ47soMZo9wGzjb_7OMg0LOL-bSf63kpaSH 1806 SXndS5z5rexMdbBYUsLA9e-KXBdQOS-UTo7WTBEMa2R2CapHg665xsmtdV 1807 MTBQY4uDZlxvb3qCo5ZwKh9kG4LT6_I5IhlJH7aGhyxXFvUK-DWNmoudF8 1808 NAco9_h9iaGNj8q2ethFkMLs91kzk2PAcDTW9gb54h4FRWyuXpoQ", 1809 "e":"AQAB", 1810 "d":"Eq5xpGnNCivDflJsRQBXHx1hdR1k6Ulwe2JZD50LpXyWPEAeP88vLNO97I 1811 jlA7_GQ5sLKMgvfTeXZx9SE-7YwVol2NXOoAJe46sui395IW_GO-pWJ1O0 1812 BkTGoVEn2bKVRUCgu-GjBVaYLU6f3l9kJfFNS3E0QbVdxzubSu3Mkqzjkn 1813 439X0M_V51gfpRLI9JYanrC4D4qAdGcopV_0ZHHzQlBjudU2QvXt4ehNYT 1814 CBr6XCLQUShb1juUO1ZdiYoFaFQT5Tw8bGUl_x_jTj3ccPDVZFD9pIuhLh 1815 BOneufuBiB4cS98l2SR_RQyGWSeWjnczT0QU91p1DhOVRuOopznQ", 1816 "p":"4BzEEOtIpmVdVEZNCqS7baC4crd0pqnRH_5IB3jw3bcxGn6QLvnEtfdUdi 1817 YrqBdss1l58BQ3KhooKeQTa9AB0Hw_Py5PJdTJNPY8cQn7ouZ2KKDcmnPG 1818 BY5t7yLc1QlQ5xHdwW1VhvKn-nXqhJTBgIPgtldC-KDV5z-y2XDwGUc", 1819 "q":"uQPEfgmVtjL0Uyyx88GZFF1fOunH3-7cepKmtH4pxhtCoHqpWmT8YAmZxa 1820 ewHgHAjLYsp1ZSe7zFYHj7C6ul7TjeLQeZD_YwD66t62wDmpe_HlB-TnBA 1821 -njbglfIsRLtXlnDzQkv5dTltRJ11BKBBypeeF6689rjcJIDEz9RWdc", 1822 "dp":"BwKfV3Akq5_MFZDFZCnW-wzl-CCo83WoZvnLQwCTeDv8uzluRSnm71I3Q 1823 CLdhrqE2e9YkxvuxdBfpT_PI7Yz-FOKnu1R6HsJeDCjn12Sk3vmAktV2zb 1824 34MCdy7cpdTh_YVr7tss2u6vneTwrA86rZtu5Mbr1C1XsmvkxHQAdYo0", 1825 "dq":"h_96-mK1R_7glhsum81dZxjTnYynPbZpHziZjeeHcXYsXaaMwkOlODsWa 1826 7I9xXDoRwbKgB719rrmI2oKr6N3Do9U0ajaHF-NKJnwgjMd2w9cjz3_-ky 1827 NlxAr2v4IKhGNpmM5iIgOS1VZnOZ68m6_pbLBSp3nssTdlqvd0tIiTHU", 1828 "qi":"IYd7DHOhrWvxkwPQsRM2tOgrjbcrfvtQJipd-DlcxyVuuM9sQLdgjVk2o 1829 y26F0EmpScGLq2MowX7fhd_QJQ3ydy5cY7YIBi87w93IKLEdfnbJtoOPLU 1830 W0ITrJReOgo1cq9SbsxYawBgfp_gh6A5603k2-ZQwVK0JKSHuLFkuQ3U" 1831 } 1833 The RSA private key is then passed to the RSA signing function, which 1834 also takes the hash type, SHA-256, and the JWS Signing Input as 1835 inputs. The result of the digital signature is an octet sequence, 1836 which represents a big endian integer. In this example, it is: 1838 [112, 46, 33, 137, 67, 232, 143, 209, 30, 181, 216, 45, 191, 120, 69, 1839 243, 65, 6, 174, 27, 129, 255, 247, 115, 17, 22, 173, 209, 113, 125, 1840 131, 101, 109, 66, 10, 253, 60, 150, 238, 221, 115, 162, 102, 62, 81, 1841 102, 104, 123, 0, 11, 135, 34, 110, 1, 135, 237, 16, 115, 249, 69, 1842 229, 130, 173, 252, 239, 22, 216, 90, 121, 142, 232, 198, 109, 219, 1843 61, 184, 151, 91, 23, 208, 148, 2, 190, 237, 213, 217, 217, 112, 7, 1844 16, 141, 178, 129, 96, 213, 248, 4, 12, 167, 68, 87, 98, 184, 31, 1845 190, 127, 249, 217, 46, 10, 231, 111, 36, 242, 91, 51, 187, 230, 244, 1846 74, 230, 30, 177, 4, 10, 203, 32, 4, 77, 62, 249, 18, 142, 212, 1, 1847 48, 121, 91, 212, 189, 59, 65, 238, 202, 208, 102, 171, 101, 25, 129, 1848 253, 228, 141, 247, 127, 55, 45, 195, 139, 159, 175, 221, 59, 239, 1849 177, 139, 93, 163, 204, 60, 46, 176, 47, 158, 58, 65, 214, 18, 202, 1850 173, 21, 145, 18, 115, 160, 95, 35, 185, 232, 56, 250, 175, 132, 157, 1851 105, 132, 41, 239, 90, 30, 136, 121, 130, 54, 195, 212, 14, 96, 69, 1852 34, 165, 68, 200, 242, 122, 122, 45, 184, 6, 99, 209, 108, 247, 202, 1853 234, 86, 222, 64, 92, 178, 33, 90, 69, 178, 194, 85, 102, 181, 90, 1854 193, 167, 72, 160, 112, 223, 200, 163, 42, 70, 149, 67, 208, 25, 238, 1855 251, 71] 1857 Encoding the signature as BASE64URL(JWS Signature) produces this 1858 value (with line breaks for display purposes only): 1860 cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7 1861 AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4 1862 BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K 1863 0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqv 1864 hJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrB 1865 p0igcN_IoypGlUPQGe77Rw 1867 Concatenating these values in the order Header.Payload.Signature with 1868 period ('.') characters between the parts yields this complete JWS 1869 representation using the JWS Compact Serialization (with line breaks 1870 for display purposes only): 1872 eyJhbGciOiJSUzI1NiJ9 1873 . 1874 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1875 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1876 . 1877 cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7 1878 AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4 1879 BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K 1880 0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqv 1881 hJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrB 1882 p0igcN_IoypGlUPQGe77Rw 1884 A.2.2. Validating 1886 Since the "alg" Header Parameter is "RS256", we validate the RSASSA- 1887 PKCS-v1_5 SHA-256 digital signature contained in the JWS Signature. 1889 Validating the JWS Signature is a bit different from the previous 1890 example. We pass the public key (n, e), the JWS Signature (which is 1891 base64url decoded from the value encoded in the JWS representation), 1892 and the JWS Signing Input (which is the initial substring of the JWS 1893 Compact Serialization representation up until but not including the 1894 second period character) to an RSASSA-PKCS-v1_5 signature verifier 1895 that has been configured to use the SHA-256 hash function. 1897 A.3. Example JWS using ECDSA P-256 SHA-256 1899 A.3.1. Encoding 1901 The JWS Protected Header for this example differs from the previous 1902 example because a different algorithm is being used. The JWS 1903 Protected Header used is: 1905 {"alg":"ES256"} 1907 The octets representing UTF8(JWS Protected Header) in this example 1908 (using JSON array notation) are: 1910 [123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 50, 53, 54, 34, 125] 1912 Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected 1913 Header)) gives this value: 1915 eyJhbGciOiJFUzI1NiJ9 1917 The JWS Payload used in this example, which follows, is the same as 1918 in the previous examples. Since the BASE64URL(JWS Payload) value 1919 will therefore be the same, its computation is not repeated here. 1921 {"iss":"joe", 1922 "exp":1300819380, 1923 "http://example.com/is_root":true} 1925 Combining these as BASE64URL(UTF8(JWS Protected Header)) || '.' || 1926 BASE64URL(JWS Payload) gives this string (with line breaks for 1927 display purposes only): 1929 eyJhbGciOiJFUzI1NiJ9 1930 . 1931 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1932 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1934 The resulting JWS Signing Input value, which is the ASCII 1935 representation of above string, is the following octet sequence: 1937 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 70, 85, 122, 73, 1938 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, 1939 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 74, 108, 101, 72, 1940 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 107, 122, 79, 68, 1941 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 72, 65, 54, 76, 1942 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 109, 78, 118, 1943 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48, 1944 99, 110, 86, 108, 102, 81] 1946 This example uses the elliptic curve key represented in JSON Web Key 1947 [JWK] format below: 1949 {"kty":"EC", 1950 "crv":"P-256", 1951 "x":"f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU", 1952 "y":"x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0", 1953 "d":"jpsQnnGQmL-YBIffH1136cspYG6-0iY7X1fCE9-E9LI" 1954 } 1956 The ECDSA private part d is then passed to an ECDSA signing function, 1957 which also takes the curve type, P-256, the hash type, SHA-256, and 1958 the JWS Signing Input as inputs. The result of the digital signature 1959 is the EC point (R, S), where R and S are unsigned integers. In this 1960 example, the R and S values, given as octet sequences representing 1961 big endian integers are: 1963 +--------+----------------------------------------------------------+ 1964 | Result | Value | 1965 | Name | | 1966 +--------+----------------------------------------------------------+ 1967 | R | [14, 209, 33, 83, 121, 99, 108, 72, 60, 47, 127, 21, 88, | 1968 | | 7, 212, 2, 163, 178, 40, 3, 58, 249, 124, 126, 23, 129, | 1969 | | 154, 195, 22, 158, 166, 101] | 1970 | S | [197, 10, 7, 211, 140, 60, 112, 229, 216, 241, 45, 175, | 1971 | | 8, 74, 84, 128, 166, 101, 144, 197, 242, 147, 80, 154, | 1972 | | 143, 63, 127, 138, 131, 163, 84, 213] | 1973 +--------+----------------------------------------------------------+ 1975 The JWS Signature is the value R || S. Encoding the signature as 1976 BASE64URL(JWS Signature) produces this value (with line breaks for 1977 display purposes only): 1979 DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSA 1980 pmWQxfKTUJqPP3-Kg6NU1Q 1982 Concatenating these values in the order Header.Payload.Signature with 1983 period ('.') characters between the parts yields this complete JWS 1984 representation using the JWS Compact Serialization (with line breaks 1985 for display purposes only): 1987 eyJhbGciOiJFUzI1NiJ9 1988 . 1989 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1990 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1991 . 1992 DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSA 1993 pmWQxfKTUJqPP3-Kg6NU1Q 1995 A.3.2. Validating 1997 Since the "alg" Header Parameter is "ES256", we validate the ECDSA 1998 P-256 SHA-256 digital signature contained in the JWS Signature. 2000 Validating the JWS Signature is a bit different from the previous 2001 examples. We need to split the 64 member octet sequence of the JWS 2002 Signature (which is base64url decoded from the value encoded in the 2003 JWS representation) into two 32 octet sequences, the first 2004 representing R and the second S. We then pass the public key (x, y), 2005 the signature (R, S), and the JWS Signing Input (which is the initial 2006 substring of the JWS Compact Serialization representation up until 2007 but not including the second period character) to an ECDSA signature 2008 verifier that has been configured to use the P-256 curve with the 2009 SHA-256 hash function. 2011 A.4. Example JWS using ECDSA P-521 SHA-512 2013 A.4.1. Encoding 2015 The JWS Protected Header for this example differs from the previous 2016 example because different ECDSA curves and hash functions are used. 2017 The JWS Protected Header used is: 2019 {"alg":"ES512"} 2021 The octets representing UTF8(JWS Protected Header) in this example 2022 (using JSON array notation) are: 2024 [123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 53, 49, 50, 34, 125] 2026 Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected 2027 Header)) gives this value: 2029 eyJhbGciOiJFUzUxMiJ9 2031 The JWS Payload used in this example, is the ASCII string "Payload". 2032 The representation of this string is the octet sequence: 2034 [80, 97, 121, 108, 111, 97, 100] 2035 Encoding this JWS Payload as BASE64URL(JWS Payload) gives this value: 2037 UGF5bG9hZA 2039 Combining these as BASE64URL(UTF8(JWS Protected Header)) || '.' || 2040 BASE64URL(JWS Payload) gives this string: 2042 eyJhbGciOiJFUzUxMiJ9.UGF5bG9hZA 2044 The resulting JWS Signing Input value, which is the ASCII 2045 representation of above string, is the following octet sequence: 2047 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 70, 85, 122, 85, 2048 120, 77, 105, 74, 57, 46, 85, 71, 70, 53, 98, 71, 57, 104, 90, 65] 2050 This example uses the elliptic curve key represented in JSON Web Key 2051 [JWK] format below (with line breaks within values for display 2052 purposes only): 2054 {"kty":"EC", 2055 "crv":"P-521", 2056 "x":"AekpBQ8ST8a8VcfVOTNl353vSrDCLLJXmPk06wTjxrrjcBpXp5EOnYG_ 2057 NjFZ6OvLFV1jSfS9tsz4qUxcWceqwQGk", 2058 "y":"ADSmRA43Z1DSNx_RvcLI87cdL07l6jQyyBXMoxVg_l2Th-x3S1WDhjDl 2059 y79ajL4Kkd0AZMaZmh9ubmf63e3kyMj2", 2060 "d":"AY5pb7A0UFiB3RELSD64fTLOSV_jazdF7fLYyuTw8lOfRhWg6Y6rUrPA 2061 xerEzgdRhajnu0ferB0d53vM9mE15j2C" 2062 } 2064 The ECDSA private part d is then passed to an ECDSA signing function, 2065 which also takes the curve type, P-521, the hash type, SHA-512, and 2066 the JWS Signing Input as inputs. The result of the digital signature 2067 is the EC point (R, S), where R and S are unsigned integers. In this 2068 example, the R and S values, given as octet sequences representing 2069 big endian integers are: 2071 +--------+----------------------------------------------------------+ 2072 | Result | Value | 2073 | Name | | 2074 +--------+----------------------------------------------------------+ 2075 | R | [1, 220, 12, 129, 231, 171, 194, 209, 232, 135, 233, | 2076 | | 117, 247, 105, 122, 210, 26, 125, 192, 1, 217, 21, 82, | 2077 | | 91, 45, 240, 255, 83, 19, 34, 239, 71, 48, 157, 147, | 2078 | | 152, 105, 18, 53, 108, 163, 214, 68, 231, 62, 153, 150, | 2079 | | 106, 194, 164, 246, 72, 143, 138, 24, 50, 129, 223, 133, | 2080 | | 206, 209, 172, 63, 237, 119, 109] | 2081 | S | [0, 111, 6, 105, 44, 5, 41, 208, 128, 61, 152, 40, 92, | 2082 | | 61, 152, 4, 150, 66, 60, 69, 247, 196, 170, 81, 193, | 2083 | | 199, 78, 59, 194, 169, 16, 124, 9, 143, 42, 142, 131, | 2084 | | 48, 206, 238, 34, 175, 83, 203, 220, 159, 3, 107, 155, | 2085 | | 22, 27, 73, 111, 68, 68, 21, 238, 144, 229, 232, 148, | 2086 | | 188, 222, 59, 242, 103] | 2087 +--------+----------------------------------------------------------+ 2089 The JWS Signature is the value R || S. Encoding the signature as 2090 BASE64URL(JWS Signature) produces this value (with line breaks for 2091 display purposes only): 2093 AdwMgeerwtHoh-l192l60hp9wAHZFVJbLfD_UxMi70cwnZOYaRI1bKPWROc-mZZq 2094 wqT2SI-KGDKB34XO0aw_7XdtAG8GaSwFKdCAPZgoXD2YBJZCPEX3xKpRwcdOO8Kp 2095 EHwJjyqOgzDO7iKvU8vcnwNrmxYbSW9ERBXukOXolLzeO_Jn 2097 Concatenating these values in the order Header.Payload.Signature with 2098 period ('.') characters between the parts yields this complete JWS 2099 representation using the JWS Compact Serialization (with line breaks 2100 for display purposes only): 2102 eyJhbGciOiJFUzUxMiJ9 2103 . 2104 UGF5bG9hZA 2105 . 2106 AdwMgeerwtHoh-l192l60hp9wAHZFVJbLfD_UxMi70cwnZOYaRI1bKPWROc-mZZq 2107 wqT2SI-KGDKB34XO0aw_7XdtAG8GaSwFKdCAPZgoXD2YBJZCPEX3xKpRwcdOO8Kp 2108 EHwJjyqOgzDO7iKvU8vcnwNrmxYbSW9ERBXukOXolLzeO_Jn 2110 A.4.2. Validating 2112 Since the "alg" Header Parameter is "ES512", we validate the ECDSA 2113 P-521 SHA-512 digital signature contained in the JWS Signature. 2115 Validating this JWS Signature is very similar to the previous 2116 example. We need to split the 132 member octet sequence of the JWS 2117 Signature into two 66 octet sequences, the first representing R and 2118 the second S. We then pass the public key (x, y), the signature (R, 2119 S), and the JWS Signing Input to an ECDSA signature verifier that has 2120 been configured to use the P-521 curve with the SHA-512 hash 2121 function. 2123 A.5. Example Unsecured JWS 2125 The following example JWS Protected Header declares that the encoded 2126 object is an Unsecured JWS: 2128 {"alg":"none"} 2130 Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected 2131 Header)) gives this value: 2133 eyJhbGciOiJub25lIn0 2135 The JWS Payload used in this example, which follows, is the same as 2136 in the previous examples. Since the BASE64URL(JWS Payload) value 2137 will therefore be the same, its computation is not repeated here. 2139 {"iss":"joe", 2140 "exp":1300819380, 2141 "http://example.com/is_root":true} 2143 The JWS Signature is the empty octet string and BASE64URL(JWS 2144 Signature) is the empty string. 2146 Concatenating these parts in the order Header.Payload.Signature with 2147 period ('.') characters between the parts yields this complete JWS 2148 (with line breaks for display purposes only): 2150 eyJhbGciOiJub25lIn0 2151 . 2152 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 2153 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 2154 . 2156 A.6. Example JWS using General JWS JSON Serialization 2158 This section contains an example using the general JWS JSON 2159 Serialization syntax. This example demonstrates the capability for 2160 conveying multiple digital signatures and/or MACs for the same 2161 payload. 2163 The JWS Payload used in this example is the same as that used in the 2164 examples in Appendix A.2 and Appendix A.3 (with line breaks for 2165 display purposes only): 2167 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 2168 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 2170 Two digital signatures are used in this example: the first using 2171 RSASSA-PKCS-v1_5 SHA-256 and the second using ECDSA P-256 SHA-256. 2172 For the first, the JWS Protected Header and key are the same as in 2173 Appendix A.2, resulting in the same JWS Signature value; therefore, 2174 its computation is not repeated here. For the second, the JWS 2175 Protected Header and key are the same as in Appendix A.3, resulting 2176 in the same JWS Signature value; therefore, its computation is not 2177 repeated here. 2179 A.6.1. JWS Per-Signature Protected Headers 2181 The JWS Protected Header value used for the first signature is: 2183 {"alg":"RS256"} 2185 Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected 2186 Header)) gives this value: 2188 eyJhbGciOiJSUzI1NiJ9 2190 The JWS Protected Header value used for the second signature is: 2192 {"alg":"ES256"} 2194 Encoding this JWS Protected Header as BASE64URL(UTF8(JWS Protected 2195 Header)) gives this value: 2197 eyJhbGciOiJFUzI1NiJ9 2199 A.6.2. JWS Per-Signature Unprotected Headers 2201 Key ID values are supplied for both keys using per-signature Header 2202 Parameters. The two values used to represent these Key IDs are: 2204 {"kid":"2010-12-29"} 2206 and 2208 {"kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"} 2210 A.6.3. Complete JOSE Header Values 2212 Combining the protected and unprotected header values supplied, the 2213 JOSE Header values used for the first and second signatures 2214 respectively are: 2216 {"alg":"RS256", 2217 "kid":"2010-12-29"} 2219 and 2221 {"alg":"ES256", 2222 "kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"} 2224 A.6.4. Complete JWS JSON Serialization Representation 2226 The complete JWS JSON Serialization for these values is as follows 2227 (with line breaks within values for display purposes only): 2229 { 2230 "payload": 2231 "eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGF 2232 tcGxlLmNvbS9pc19yb290Ijp0cnVlfQ", 2233 "signatures":[ 2234 {"protected":"eyJhbGciOiJSUzI1NiJ9", 2235 "header": 2236 {"kid":"2010-12-29"}, 2237 "signature": 2238 "cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZ 2239 mh7AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjb 2240 KBYNX4BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHl 2241 b1L07Qe7K0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZES 2242 c6BfI7noOPqvhJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AX 2243 LIhWkWywlVmtVrBp0igcN_IoypGlUPQGe77Rw"}, 2244 {"protected":"eyJhbGciOiJFUzI1NiJ9", 2245 "header": 2246 {"kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"}, 2247 "signature": 2248 "DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8IS 2249 lSApmWQxfKTUJqPP3-Kg6NU1Q"}] 2250 } 2252 A.7. Example JWS using Flattened JWS JSON Serialization 2254 This section contains an example using the flattened JWS JSON 2255 Serialization syntax. This example demonstrates the capability for 2256 conveying a single digital signature or MAC in a flattened JSON 2257 structure. 2259 The values in this example are the same as those in the second 2260 signature of the previous example in Appendix A.6. 2262 The complete JWS JSON Serialization for these values is as follows 2263 (with line breaks within values for display purposes only): 2265 { 2266 "payload": 2267 "eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGF 2268 tcGxlLmNvbS9pc19yb290Ijp0cnVlfQ", 2269 "protected":"eyJhbGciOiJFUzI1NiJ9", 2270 "header": 2271 {"kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"}, 2272 "signature": 2273 "DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8IS 2274 lSApmWQxfKTUJqPP3-Kg6NU1Q" 2275 } 2277 Appendix B. "x5c" (X.509 Certificate Chain) Example 2279 The JSON array below is an example of a certificate chain that could 2280 be used as the value of an "x5c" (X.509 Certificate Chain) Header 2281 Parameter, per Section 4.1.6. Note that since these strings contain 2282 base64 encoded (not base64url encoded) values, they are allowed to 2283 contain white space and line breaks. 2285 ["MIIE3jCCA8agAwIBAgICAwEwDQYJKoZIhvcNAQEFBQAwYzELMAkGA1UEBhMCVVM 2286 xITAfBgNVBAoTGFRoZSBHbyBEYWRkeSBHcm91cCwgSW5jLjExMC8GA1UECxMoR2 2287 8gRGFkZHkgQ2xhc3MgMiBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTAeFw0wNjExM 2288 TYwMTU0MzdaFw0yNjExMTYwMTU0MzdaMIHKMQswCQYDVQQGEwJVUzEQMA4GA1UE 2289 CBMHQXJpem9uYTETMBEGA1UEBxMKU2NvdHRzZGFsZTEaMBgGA1UEChMRR29EYWR 2290 keS5jb20sIEluYy4xMzAxBgNVBAsTKmh0dHA6Ly9jZXJ0aWZpY2F0ZXMuZ29kYW 2291 RkeS5jb20vcmVwb3NpdG9yeTEwMC4GA1UEAxMnR28gRGFkZHkgU2VjdXJlIENlc 2292 nRpZmljYXRpb24gQXV0aG9yaXR5MREwDwYDVQQFEwgwNzk2OTI4NzCCASIwDQYJ 2293 KoZIhvcNAQEBBQADggEPADCCAQoCggEBAMQt1RWMnCZM7DI161+4WQFapmGBWTt 2294 wY6vj3D3HKrjJM9N55DrtPDAjhI6zMBS2sofDPZVUBJ7fmd0LJR4h3mUpfjWoqV 2295 Tr9vcyOdQmVZWt7/v+WIbXnvQAjYwqDL1CBM6nPwT27oDyqu9SoWlm2r4arV3aL 2296 GbqGmu75RpRSgAvSMeYddi5Kcju+GZtCpyz8/x4fKL4o/K1w/O5epHBp+YlLpyo 2297 7RJlbmr2EkRTcDCVw5wrWCs9CHRK8r5RsL+H0EwnWGu1NcWdrxcx+AuP7q2BNgW 2298 JCJjPOq8lh8BJ6qf9Z/dFjpfMFDniNoW1fho3/Rb2cRGadDAW/hOUoz+EDU8CAw 2299 EAAaOCATIwggEuMB0GA1UdDgQWBBT9rGEyk2xF1uLuhV+auud2mWjM5zAfBgNVH 2300 SMEGDAWgBTSxLDSkdRMEXGzYcs9of7dqGrU4zASBgNVHRMBAf8ECDAGAQH/AgEA 2301 MDMGCCsGAQUFBwEBBCcwJTAjBggrBgEFBQcwAYYXaHR0cDovL29jc3AuZ29kYWR 2302 keS5jb20wRgYDVR0fBD8wPTA7oDmgN4Y1aHR0cDovL2NlcnRpZmljYXRlcy5nb2 2303 RhZGR5LmNvbS9yZXBvc2l0b3J5L2dkcm9vdC5jcmwwSwYDVR0gBEQwQjBABgRVH 2304 SAAMDgwNgYIKwYBBQUHAgEWKmh0dHA6Ly9jZXJ0aWZpY2F0ZXMuZ29kYWRkeS5j 2305 b20vcmVwb3NpdG9yeTAOBgNVHQ8BAf8EBAMCAQYwDQYJKoZIhvcNAQEFBQADggE 2306 BANKGwOy9+aG2Z+5mC6IGOgRQjhVyrEp0lVPLN8tESe8HkGsz2ZbwlFalEzAFPI 2307 UyIXvJxwqoJKSQ3kbTJSMUA2fCENZvD117esyfxVgqwcSeIaha86ykRvOe5GPLL 2308 5CkKSkB2XIsKd83ASe8T+5o0yGPwLPk9Qnt0hCqU7S+8MxZC9Y7lhyVJEnfzuz9 2309 p0iRFEUOOjZv2kWzRaJBydTXRE4+uXR21aITVSzGh6O1mawGhId/dQb8vxRMDsx 2310 uxN89txJx9OjxUUAiKEngHUuHqDTMBqLdElrRhjZkAzVvb3du6/KFUJheqwNTrZ 2311 EjYx8WnM25sgVjOuH0aBsXBTWVU+4=", 2313 "MIIE+zCCBGSgAwIBAgICAQ0wDQYJKoZIhvcNAQEFBQAwgbsxJDAiBgNVBAcTG1Z 2314 hbGlDZXJ0IFZhbGlkYXRpb24gTmV0d29yazEXMBUGA1UEChMOVmFsaUNlcnQsIE 2315 luYy4xNTAzBgNVBAsTLFZhbGlDZXJ0IENsYXNzIDIgUG9saWN5IFZhbGlkYXRpb 2316 24gQXV0aG9yaXR5MSEwHwYDVQQDExhodHRwOi8vd3d3LnZhbGljZXJ0LmNvbS8x 2317 IDAeBgkqhkiG9w0BCQEWEWluZm9AdmFsaWNlcnQuY29tMB4XDTA0MDYyOTE3MDY 2318 yMFoXDTI0MDYyOTE3MDYyMFowYzELMAkGA1UEBhMCVVMxITAfBgNVBAoTGFRoZS 2319 BHbyBEYWRkeSBHcm91cCwgSW5jLjExMC8GA1UECxMoR28gRGFkZHkgQ2xhc3MgM 2320 iBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTCCASAwDQYJKoZIhvcNAQEBBQADggEN 2321 ADCCAQgCggEBAN6d1+pXGEmhW+vXX0iG6r7d/+TvZxz0ZWizV3GgXne77ZtJ6XC 2322 APVYYYwhv2vLM0D9/AlQiVBDYsoHUwHU9S3/Hd8M+eKsaA7Ugay9qK7HFiH7Eux 2323 6wwdhFJ2+qN1j3hybX2C32qRe3H3I2TqYXP2WYktsqbl2i/ojgC95/5Y0V4evLO 2324 tXiEqITLdiOr18SPaAIBQi2XKVlOARFmR6jYGB0xUGlcmIbYsUfb18aQr4CUWWo 2325 riMYavx4A6lNf4DD+qta/KFApMoZFv6yyO9ecw3ud72a9nmYvLEHZ6IVDd2gWMZ 2326 Eewo+YihfukEHU1jPEX44dMX4/7VpkI+EdOqXG68CAQOjggHhMIIB3TAdBgNVHQ 2327 4EFgQU0sSw0pHUTBFxs2HLPaH+3ahq1OMwgdIGA1UdIwSByjCBx6GBwaSBvjCBu 2328 zEkMCIGA1UEBxMbVmFsaUNlcnQgVmFsaWRhdGlvbiBOZXR3b3JrMRcwFQYDVQQK 2329 Ew5WYWxpQ2VydCwgSW5jLjE1MDMGA1UECxMsVmFsaUNlcnQgQ2xhc3MgMiBQb2x 2330 pY3kgVmFsaWRhdGlvbiBBdXRob3JpdHkxITAfBgNVBAMTGGh0dHA6Ly93d3cudm 2331 FsaWNlcnQuY29tLzEgMB4GCSqGSIb3DQEJARYRaW5mb0B2YWxpY2VydC5jb22CA 2332 QEwDwYDVR0TAQH/BAUwAwEB/zAzBggrBgEFBQcBAQQnMCUwIwYIKwYBBQUHMAGG 2333 F2h0dHA6Ly9vY3NwLmdvZGFkZHkuY29tMEQGA1UdHwQ9MDswOaA3oDWGM2h0dHA 2334 6Ly9jZXJ0aWZpY2F0ZXMuZ29kYWRkeS5jb20vcmVwb3NpdG9yeS9yb290LmNybD 2335 BLBgNVHSAERDBCMEAGBFUdIAAwODA2BggrBgEFBQcCARYqaHR0cDovL2NlcnRpZ 2336 mljYXRlcy5nb2RhZGR5LmNvbS9yZXBvc2l0b3J5MA4GA1UdDwEB/wQEAwIBBjAN 2337 BgkqhkiG9w0BAQUFAAOBgQC1QPmnHfbq/qQaQlpE9xXUhUaJwL6e4+PrxeNYiY+ 2338 Sn1eocSxI0YGyeR+sBjUZsE4OWBsUs5iB0QQeyAfJg594RAoYC5jcdnplDQ1tgM 2339 QLARzLrUc+cb53S8wGd9D0VmsfSxOaFIqII6hR8INMqzW/Rn453HWkrugp++85j 2340 09VZw==", 2341 "MIIC5zCCAlACAQEwDQYJKoZIhvcNAQEFBQAwgbsxJDAiBgNVBAcTG1ZhbGlDZXJ 2342 0IFZhbGlkYXRpb24gTmV0d29yazEXMBUGA1UEChMOVmFsaUNlcnQsIEluYy4xNT 2343 AzBgNVBAsTLFZhbGlDZXJ0IENsYXNzIDIgUG9saWN5IFZhbGlkYXRpb24gQXV0a 2344 G9yaXR5MSEwHwYDVQQDExhodHRwOi8vd3d3LnZhbGljZXJ0LmNvbS8xIDAeBgkq 2345 hkiG9w0BCQEWEWluZm9AdmFsaWNlcnQuY29tMB4XDTk5MDYyNjAwMTk1NFoXDTE 2346 5MDYyNjAwMTk1NFowgbsxJDAiBgNVBAcTG1ZhbGlDZXJ0IFZhbGlkYXRpb24gTm 2347 V0d29yazEXMBUGA1UEChMOVmFsaUNlcnQsIEluYy4xNTAzBgNVBAsTLFZhbGlDZ 2348 XJ0IENsYXNzIDIgUG9saWN5IFZhbGlkYXRpb24gQXV0aG9yaXR5MSEwHwYDVQQD 2349 ExhodHRwOi8vd3d3LnZhbGljZXJ0LmNvbS8xIDAeBgkqhkiG9w0BCQEWEWluZm9 2350 AdmFsaWNlcnQuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDOOnHK5a 2351 vIWZJV16vYdA757tn2VUdZZUcOBVXc65g2PFxTXdMwzzjsvUGJ7SVCCSRrCl6zf 2352 N1SLUzm1NZ9WlmpZdRJEy0kTRxQb7XBhVQ7/nHk01xC+YDgkRoKWzk2Z/M/VXwb 2353 P7RfZHM047QSv4dk+NoS/zcnwbNDu+97bi5p9wIDAQABMA0GCSqGSIb3DQEBBQU 2354 AA4GBADt/UG9vUJSZSWI4OB9L+KXIPqeCgfYrx+jFzug6EILLGACOTb2oWH+heQ 2355 C1u+mNr0HZDzTuIYEZoDJJKPTEjlbVUjP9UNV+mWwD5MlM/Mtsq2azSiGM5bUMM 2356 j4QssxsodyamEwCW/POuZ6lcg5Ktz885hZo+L7tdEy8W9ViH0Pd"] 2358 Appendix C. Notes on implementing base64url encoding without padding 2360 This appendix describes how to implement base64url encoding and 2361 decoding functions without padding based upon standard base64 2362 encoding and decoding functions that do use padding. 2364 To be concrete, example C# code implementing these functions is shown 2365 below. Similar code could be used in other languages. 2367 static string base64urlencode(byte [] arg) 2368 { 2369 string s = Convert.ToBase64String(arg); // Regular base64 encoder 2370 s = s.Split('=')[0]; // Remove any trailing '='s 2371 s = s.Replace('+', '-'); // 62nd char of encoding 2372 s = s.Replace('/', '_'); // 63rd char of encoding 2373 return s; 2374 } 2376 static byte [] base64urldecode(string arg) 2377 { 2378 string s = arg; 2379 s = s.Replace('-', '+'); // 62nd char of encoding 2380 s = s.Replace('_', '/'); // 63rd char of encoding 2381 switch (s.Length % 4) // Pad with trailing '='s 2382 { 2383 case 0: break; // No pad chars in this case 2384 case 2: s += "=="; break; // Two pad chars 2385 case 3: s += "="; break; // One pad char 2386 default: throw new System.Exception( 2387 "Illegal base64url string!"); 2388 } 2389 return Convert.FromBase64String(s); // Standard base64 decoder 2390 } 2392 As per the example code above, the number of '=' padding characters 2393 that needs to be added to the end of a base64url encoded string 2394 without padding to turn it into one with padding is a deterministic 2395 function of the length of the encoded string. Specifically, if the 2396 length mod 4 is 0, no padding is added; if the length mod 4 is 2, two 2397 '=' padding characters are added; if the length mod 4 is 3, one '=' 2398 padding character is added; if the length mod 4 is 1, the input is 2399 malformed. 2401 An example correspondence between unencoded and encoded values 2402 follows. The octet sequence below encodes into the string below, 2403 which when decoded, reproduces the octet sequence. 2404 3 236 255 224 193 2405 A-z_4ME 2407 Appendix D. Notes on Key Selection 2409 This appendix describes a set of possible algorithms for selecting 2410 the key to be used to validate the digital signature or MAC of a JWS 2411 or for selecting the key to be used to decrypt a JWE. This guidance 2412 describes a family of possible algorithms, rather than a single 2413 algorithm, because in different contexts, not all the sources of keys 2414 will be used, they can be tried in different orders, and sometimes 2415 not all the collected keys will be tried; hence, different algorithms 2416 will be used in different application contexts. 2418 The steps below are described for illustration purposes only; 2419 specific applications can and are likely to use different algorithms 2420 or perform some of the steps in different orders. Specific 2421 applications will frequently have a much simpler method of 2422 determining the keys to use, as there may be one or two key selection 2423 methods that are profiled for the application's use. This appendix 2424 supplements the normative information on key location in Section 6. 2426 These algorithms include the following steps. Note that the steps 2427 can be performed in any order and do not need to be treated as 2428 distinct. For example, keys can be tried as soon as they are found, 2429 rather than collecting all the keys before trying any. 2431 1. Collect the set of potentially applicable keys. Sources of keys 2432 may include: 2434 * Keys supplied by the application protocol being used. 2436 * Keys referenced by the "jku" (JWK Set URL) Header Parameter. 2438 * The key provided by the "jwk" (JSON Web Key) Header Parameter. 2440 * The key referenced by the "x5u" (X.509 URL) Header Parameter. 2442 * The key provided by the "x5c" (X.509 Certificate Chain) Header 2443 Parameter. 2445 * Other applicable keys available to the application. 2447 The order for collecting and trying keys from different key 2448 sources is typically application dependent. For example, 2449 frequently all keys from a one set of locations, such as local 2450 caches, will be tried before collecting and trying keys from 2451 other locations. 2453 2. Filter the set of collected keys. For instance, some 2454 applications will use only keys referenced by "kid" (key ID) or 2455 "x5t" (X.509 certificate SHA-1 thumbprint) parameters. If the 2456 application uses the "alg" (algorithm), "use" (public key use), 2457 or "key_ops" (key operations) parameters, keys with keys with 2458 inappropriate values of those parameters would be excluded. 2459 Additionally, keys might be filtered to include or exclude keys 2460 with certain other member values in an application specific 2461 manner. For some applications, no filtering will be applied. 2463 3. Order the set of collected keys. For instance, keys referenced 2464 by "kid" (Key ID) or "x5t" (X.509 Certificate SHA-1 Thumbprint) 2465 parameters might be tried before keys with neither of these 2466 values. Likewise, keys with certain member values might be 2467 ordered before keys with other member values. For some 2468 applications, no ordering will be applied. 2470 4. Make trust decisions about the keys. Signatures made with keys 2471 not meeting the application's trust criteria would not be 2472 accepted. Such criteria might include, but is not limited to the 2473 source of the key, whether the TLS certificate validates for keys 2474 retrieved from URLs, whether a key in an X.509 certificate is 2475 backed by a valid certificate chain, and other information known 2476 by the application. 2478 5. Attempt signature or MAC validation for a JWS or decryption of a 2479 JWE with some or all of the collected and possibly filtered 2480 and/or ordered keys. A limit on the number of keys to be tried 2481 might be applied. This process will normally terminate following 2482 a successful validation or decryption. 2484 Note that it is reasonable for some applications to perform signature 2485 or MAC validation prior to making a trust decision about a key, since 2486 keys for which the validation fails need no trust decision. 2488 Appendix E. Negative Test Case for "crit" Header Parameter 2490 Conforming implementations must reject input containing critical 2491 extensions that are not understood or cannot be processed. The 2492 following JWS must be rejected by all implementations, because it 2493 uses an extension Header Parameter name 2494 "http://example.invalid/UNDEFINED" that they do not understand. Any 2495 other similar input, in which the use of the value 2496 "http://example.invalid/UNDEFINED" is substituted for any other 2497 Header Parameter name not understood by the implementation, must also 2498 be rejected. 2500 The JWS Protected Header value for this JWS is: 2502 {"alg":"none", 2503 "crit":["http://example.invalid/UNDEFINED"], 2504 "http://example.invalid/UNDEFINED":true 2505 } 2507 The complete JWS that must be rejected is as follows (with line 2508 breaks for display purposes only): 2510 eyJhbGciOiJub25lIiwNCiAiY3JpdCI6WyJodHRwOi8vZXhhbXBsZS5jb20vVU5ERU 2511 ZJTkVEIl0sDQogImh0dHA6Ly9leGFtcGxlLmNvbS9VTkRFRklORUQiOnRydWUNCn0. 2512 RkFJTA. 2514 Appendix F. Detached Content 2516 In some contexts, it is useful integrity protect content that is not 2517 itself contained in a JWS. One way to do this is create a JWS in the 2518 normal fashion using a representation of the content as the payload, 2519 but then delete the payload representation from the JWS, and send 2520 this modified object to the recipient, rather than the JWS. When 2521 using the JWS Compact Serialization, the deletion is accomplished by 2522 replacing the second field (which contains BASE64URL(JWS Payload)) 2523 value with the empty string; when using the JWS JSON Serialization, 2524 the deletion is accomplished by deleting the "payload" member. This 2525 method assumes that the recipient can reconstruct the exact payload 2526 used in the JWS. To use the modified object, the recipient 2527 reconstructs the JWS by re-inserting the payload representation into 2528 the modified object, and uses the resulting JWS in the usual manner. 2529 Note that this method needs no support from JWS libraries, as 2530 applications can use this method by modifying the inputs and outputs 2531 of standard JWS libraries. 2533 Appendix G. Acknowledgements 2535 Solutions for signing JSON content were previously explored by Magic 2536 Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas 2537 Applications [CanvasApp], all of which influenced this draft. 2539 Thanks to Axel Nennker for his early implementation and feedback on 2540 the JWS and JWE specifications. 2542 This specification is the work of the JOSE Working Group, which 2543 includes dozens of active and dedicated participants. In particular, 2544 the following individuals contributed ideas, feedback, and wording 2545 that influenced this specification: 2547 Dirk Balfanz, Richard Barnes, Brian Campbell, Alissa Cooper, Breno de 2548 Medeiros, Stephen Farrell, Dick Hardt, Joe Hildebrand, Jeff Hodges, 2549 Russ Housley, Edmund Jay, Tero Kivinen, Yaron Y. Goland, Ben Laurie, 2550 Ted Lemon, James Manger, Matt Miller, Kathleen Moriarty, Tony 2551 Nadalin, Hideki Nara, Axel Nennker, John Panzer, Ray Polk, Emmanuel 2552 Raviart, Eric Rescorla, Pete Resnick, Jim Schaad, Paul Tarjan, Hannes 2553 Tschofenig, and Sean Turner. 2555 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2556 Sean Turner, Stephen Farrell, and Kathleen Moriarty served as 2557 Security area directors during the creation of this specification. 2559 Appendix H. Document History 2561 [[ to be removed by the RFC Editor before publication as an RFC ]] 2563 -38 2565 o Replaced uses of the phrases "JWS object" and "JWE object" with 2566 "JWS" and "JWE". 2568 o Added member names to the JWS JSON Serialization Overview. 2570 o Applied other minor editorial improvements. 2572 -37 2574 o Updated the TLS requirements language to only require 2575 implementations to support TLS when they support features using 2576 TLS. 2578 o Updated the language about integrity protecting Header Parameters 2579 when used in a trust decision. 2581 o Restricted algorithm names to using only ASCII characters. 2583 o When describing actions taken as a result of validation failures, 2584 changed statements about rejecting the JWS to statements about 2585 considering the JWS to be invalid. 2587 o Added the CRT parameter values to example RSA private key 2588 representations. 2590 o Updated the example IANA registration request subject line. 2592 -36 2593 o Defined a flattened JWS JSON Serialization syntax, which is 2594 optimized for the single digital signature or MAC case. 2596 o Clarified where white space and line breaks may occur in JSON 2597 objects by referencing Section 2 of RFC 7159. 2599 o Specified that registration reviews occur on the 2600 jose-reg-review@ietf.org mailing list. 2602 -35 2604 o Addressed AppsDir reviews by Ray Polk. 2606 o Used real values for examples in the IANA Registration Template. 2608 -34 2610 o Addressed IESG review comments by Alissa Cooper, Pete Resnick, 2611 Richard Barnes, Ted Lemon, and Stephen Farrell. 2613 o Addressed Gen-ART review comments by Russ Housley. 2615 o Referenced RFC 4945 for PEM certificate delimiter syntax. 2617 -33 2619 o Noted that certificate thumbprints are also sometimes known as 2620 certificate fingerprints. 2622 o Added an informative reference to draft-ietf-uta-tls-bcp for 2623 recommendations on improving the security of software and services 2624 using TLS. 2626 o Changed the registration review period to three weeks. 2628 o Acknowledged additional contributors. 2630 -32 2632 o Addressed Gen-ART review comments by Russ Housley. 2634 o Addressed secdir review comments by Tero Kivinen, Stephen Kent, 2635 and Scott Kelly. 2637 o Replaced the term Plaintext JWS with Unsecured JWS. 2639 -31 2640 o Reworded the language about JWS implementations ignoring the "typ" 2641 and "cty" parameters, explicitly saying that their processing is 2642 performed by JWS applications. 2644 o Added additional guidance on ciphersuites currently considered to 2645 be appropriate for use, including a reference to a recent update 2646 by the TLS working group. 2648 -30 2650 o Added subsection headings within the Overview section for the two 2651 serializations. 2653 o Added references and cleaned up the reference syntax in a few 2654 places. 2656 o Applied minor wording changes to the Security Considerations 2657 section and made other local editorial improvements. 2659 -29 2661 o Replaced the terms JWS Header, JWE Header, and JWT Header with a 2662 single JOSE Header term defined in the JWS specification. This 2663 also enabled a single Header Parameter definition to be used and 2664 reduced other areas of duplication between specifications. 2666 -28 2668 o Revised the introduction to the Security Considerations section. 2669 Also introduced additional subsection headings for security 2670 considerations items and also moved a security consideration item 2671 here from the JWA draft. 2673 o Added text about when applications typically would and would not 2674 use "typ" and "cty" header parameters. 2676 -27 2678 o Added the "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) header 2679 parameter. 2681 o Stated that any JSON inputs not conforming to the JSON-text syntax 2682 defined in RFC 7159 input MUST be rejected in their entirety. 2684 o Simplified the TLS requirements. 2686 -26 2687 o Referenced Section 6 of RFC 6125 for TLS server certificate 2688 identity validation. 2690 o Described potential sources of ambiguity in representing the JSON 2691 objects used in the examples. The octets of the actual UTF-8 2692 representations of the JSON objects used in the examples are 2693 included to remove these ambiguities. 2695 o Added a small amount of additional explanatory text to the 2696 signature validation examples to aid implementers. 2698 o Noted that octet sequences are depicted using JSON array notation. 2700 o Updated references, including to W3C specifications. 2702 -25 2704 o No changes were made, other than to the version number and date. 2706 -24 2708 o Updated the JSON reference to RFC 7159. 2710 -23 2712 o Clarified that the base64url encoding includes no line breaks, 2713 white space, or other additional characters. 2715 -22 2717 o Corrected RFC 2119 terminology usage. 2719 o Replaced references to draft-ietf-json-rfc4627bis with RFC 7158. 2721 -21 2723 o Applied review comments to the appendix "Notes on Key Selection", 2724 addressing issue #93. 2726 o Changed some references from being normative to informative, 2727 addressing issue #90. 2729 o Applied review comments to the JSON Serialization section, 2730 addressing issue #121. 2732 -20 2733 o Made terminology definitions more consistent, addressing issue 2734 #165. 2736 o Restructured the JSON Serialization section to call out the 2737 parameters used in hanging lists, addressing issue #121. 2739 o Described key filtering and refined other aspects of the text in 2740 the appendix "Notes on Key Selection", addressing issue #93. 2742 o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis, 2743 addressing issue #90. 2745 -19 2747 o Added the appendix "Notes on Validation Key Selection", addressing 2748 issue #93. 2750 o Reordered the key selection parameters. 2752 -18 2754 o Updated the mandatory-to-implement (MTI) language to say that 2755 applications using this specification need to specify what 2756 serialization and serialization features are used for that 2757 application, addressing issue #119. 2759 o Changes to address editorial and minor issues #25, #89, #97, #110, 2760 #114, #115, #116, #117, #120, and #184. 2762 o Added and used Header Parameter Description registry field. 2764 -17 2766 o Refined the "typ" and "cty" definitions to always be MIME Media 2767 Types, with the omission of "application/" prefixes recommended 2768 for brevity, addressing issue #50. 2770 o Updated the mandatory-to-implement (MTI) language to say that 2771 general-purpose implementations must implement the single 2772 signature/MAC value case for both serializations whereas special- 2773 purpose implementations can implement just one serialization if 2774 that meets the needs of the use cases the implementation is 2775 designed for, addressing issue #119. 2777 o Explicitly named all the logical components of a JWS and defined 2778 the processing rules and serializations in terms of those 2779 components, addressing issues #60, #61, and #62. 2781 o Replaced verbose repetitive phases such as "base64url encode the 2782 octets of the UTF-8 representation of X" with mathematical 2783 notation such as "BASE64URL(UTF8(X))". 2785 o Terms used in multiple documents are now defined in one place and 2786 incorporated by reference. Some lightly used or obvious terms 2787 were also removed. This addresses issue #58. 2789 -16 2791 o Changes to address editorial and minor issues #50, #98, #99, #102, 2792 #104, #106, #107, #111, and #112. 2794 -15 2796 o Clarified that it is an application decision which signatures, 2797 MACs, or plaintext values must successfully validate for the JWS 2798 to be accepted, addressing issue #35. 2800 o Corrected editorial error in "ES512" example. 2802 o Changes to address editorial and minor issues #34, #96, #100, 2803 #101, #104, #105, and #106. 2805 -14 2807 o Stated that the "signature" parameter is to be omitted in the JWS 2808 JSON Serialization when its value would be empty (which is only 2809 the case for a Plaintext JWS). 2811 -13 2813 o Made all header parameter values be per-signature/MAC, addressing 2814 issue #24. 2816 -12 2818 o Clarified that the "typ" and "cty" header parameters are used in 2819 an application-specific manner and have no effect upon the JWS 2820 processing. 2822 o Replaced the MIME types "application/jws+json" and 2823 "application/jws" with "application/jose+json" and 2824 "application/jose". 2826 o Stated that recipients MUST either reject JWSs with duplicate 2827 Header Parameter Names or use a JSON parser that returns only the 2828 lexically last duplicate member name. 2830 o Added a Serializations section with parallel treatment of the JWS 2831 Compact Serialization and the JWS JSON Serialization and also 2832 moved the former Implementation Considerations content there. 2834 -11 2836 o Added Key Identification section. 2838 o For the JWS JSON Serialization, enable header parameter values to 2839 be specified in any of three parameters: the "protected" member 2840 that is integrity protected and shared among all recipients, the 2841 "unprotected" member that is not integrity protected and shared 2842 among all recipients, and the "header" member that is not 2843 integrity protected and specific to a particular recipient. (This 2844 does not affect the JWS Compact Serialization, in which all header 2845 parameter values are in a single integrity protected JWE Header 2846 value.) 2848 o Removed suggested compact serialization for multiple digital 2849 signatures and/or MACs. 2851 o Changed the MIME type name "application/jws-js" to 2852 "application/jws+json", addressing issue #22. 2854 o Tightened the description of the "crit" (critical) header 2855 parameter. 2857 o Added a negative test case for the "crit" header parameter 2859 -10 2861 o Added an appendix suggesting a possible compact serialization for 2862 JWSs with multiple digital signatures and/or MACs. 2864 -09 2866 o Added JWS JSON Serialization, as specified by 2867 draft-jones-jose-jws-json-serialization-04. 2869 o Registered "application/jws-js" MIME type and "JWS-JS" typ header 2870 parameter value. 2872 o Defined that the default action for header parameters that are not 2873 understood is to ignore them unless specifically designated as 2874 "MUST be understood" or included in the new "crit" (critical) 2875 header parameter list. This addressed issue #6. 2877 o Changed term "JWS Secured Input" to "JWS Signing Input". 2879 o Changed from using the term "byte" to "octet" when referring to 8 2880 bit values. 2882 o Changed member name from "recipients" to "signatures" in the JWS 2883 JSON Serialization. 2885 o Added complete values using the JWS Compact Serialization for all 2886 examples. 2888 -08 2890 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2891 Tschofenig. Many of these simplified the terminology used. 2893 o Clarified statements of the form "This header parameter is 2894 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2896 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2897 Web Signature and Encryption Header Parameters registry. 2899 o Added seriesInfo information to Internet Draft references. 2901 -07 2903 o Updated references. 2905 -06 2907 o Changed "x5c" (X.509 Certificate Chain) representation from being 2908 a single string to being an array of strings, each containing a 2909 single base64 encoded DER certificate value, representing elements 2910 of the certificate chain. 2912 o Applied changes made by the RFC Editor to RFC 6749's registry 2913 language to this specification. 2915 -05 2917 o Added statement that "StringOrURI values are compared as case- 2918 sensitive strings with no transformations or canonicalizations 2919 applied". 2921 o Indented artwork elements to better distinguish them from the body 2922 text. 2924 -04 2925 o Completed JSON Security Considerations section, including 2926 considerations about rejecting input with duplicate member names. 2928 o Completed security considerations on the use of a SHA-1 hash when 2929 computing "x5t" (x.509 certificate thumbprint) values. 2931 o Refer to the registries as the primary sources of defined values 2932 and then secondarily reference the sections defining the initial 2933 contents of the registries. 2935 o Normatively reference XML DSIG 2.0 for its security 2936 considerations. 2938 o Added this language to Registration Templates: "This name is case 2939 sensitive. Names that match other registered names in a case 2940 insensitive manner SHOULD NOT be accepted." 2942 o Reference draft-jones-jose-jws-json-serialization instead of 2943 draft-jones-json-web-signature-json-serialization. 2945 o Described additional open issues. 2947 o Applied editorial suggestions. 2949 -03 2951 o Added the "cty" (content type) header parameter for declaring type 2952 information about the secured content, as opposed to the "typ" 2953 (type) header parameter, which declares type information about 2954 this object. 2956 o Added "Collision Resistant Namespace" to the terminology section. 2958 o Reference ITU.X690.1994 for DER encoding. 2960 o Added an example JWS using ECDSA P-521 SHA-512. This has 2961 particular illustrative value because of the use of the 521 bit 2962 integers in the key and signature values. This is also an example 2963 in which the payload is not a base64url encoded JSON object. 2965 o Added an example "x5c" value. 2967 o No longer say "the UTF-8 representation of the JWS Secured Input 2968 (which is the same as the ASCII representation)". Just call it 2969 "the ASCII representation of the JWS Secured Input". 2971 o Added Registration Template sections for defined registries. 2973 o Added Registry Contents sections to populate registry values. 2975 o Changed name of the JSON Web Signature and Encryption "typ" Values 2976 registry to be the JSON Web Signature and Encryption Type Values 2977 registry, since it is used for more than just values of the "typ" 2978 parameter. 2980 o Moved registries JSON Web Signature and Encryption Header 2981 Parameters and JSON Web Signature and Encryption Type Values to 2982 the JWS specification. 2984 o Numerous editorial improvements. 2986 -02 2988 o Clarified that it is an error when a "kid" value is included and 2989 no matching key is found. 2991 o Removed assumption that "kid" (key ID) can only refer to an 2992 asymmetric key. 2994 o Clarified that JWSs with duplicate Header Parameter Names MUST be 2995 rejected. 2997 o Clarified the relationship between "typ" header parameter values 2998 and MIME types. 3000 o Registered application/jws MIME type and "JWS" typ header 3001 parameter value. 3003 o Simplified JWK terminology to get replace the "JWK Key Object" and 3004 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 3005 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 3006 between single keys and sets of keys. As part of this change, the 3007 Header Parameter Name for a public key value was changed from 3008 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 3010 o Added suggestion on defining additional header parameters such as 3011 "x5t#S256" in the future for certificate thumbprints using hash 3012 algorithms other than SHA-1. 3014 o Specify RFC 2818 server identity validation, rather than RFC 6125 3015 (paralleling the same decision in the OAuth specs). 3017 o Generalized language to refer to Message Authentication Codes 3018 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 3019 unless in a context specific to HMAC algorithms. 3021 o Reformatted to give each header parameter its own section heading. 3023 -01 3025 o Moved definition of Plaintext JWSs (using "alg":"none") here from 3026 the JWT specification since this functionality is likely to be 3027 useful in more contexts that just for JWTs. 3029 o Added "jpk" and "x5c" header parameters for including JWK public 3030 keys and X.509 certificate chains directly in the header. 3032 o Clarified that this specification is defining the JWS Compact 3033 Serialization. Referenced the new JWS-JS spec, which defines the 3034 JWS JSON Serialization. 3036 o Added text "New header parameters should be introduced sparingly 3037 since an implementation that does not understand a parameter MUST 3038 reject the JWS". 3040 o Clarified that the order of the creation and validation steps is 3041 not significant in cases where there are no dependencies between 3042 the inputs and outputs of the steps. 3044 o Changed "no canonicalization is performed" to "no canonicalization 3045 need be performed". 3047 o Corrected the Magic Signatures reference. 3049 o Made other editorial improvements suggested by JOSE working group 3050 participants. 3052 -00 3054 o Created the initial IETF draft based upon 3055 draft-jones-json-web-signature-04 with no normative changes. 3057 o Changed terminology to no longer call both digital signatures and 3058 HMACs "signatures". 3060 Authors' Addresses 3062 Michael B. Jones 3063 Microsoft 3065 Email: mbj@microsoft.com 3066 URI: http://self-issued.info/ 3067 John Bradley 3068 Ping Identity 3070 Email: ve7jtb@ve7jtb.com 3071 URI: http://www.thread-safe.com/ 3073 Nat Sakimura 3074 Nomura Research Institute 3076 Email: n-sakimura@nri.co.jp 3077 URI: http://nat.sakimura.org/