idnits 2.17.1 draft-ietf-jose-json-web-signature-10.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 (April 25, 2013) is 4019 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '123' on line 1613 -- Looks like a reference, but probably isn't: '34' on line 1613 -- Looks like a reference, but probably isn't: '97' on line 1622 -- Looks like a reference, but probably isn't: '108' on line 1622 -- Looks like a reference, but probably isn't: '103' on line 1613 -- Looks like a reference, but probably isn't: '58' on line 1613 -- Looks like a reference, but probably isn't: '82' on line 1294 -- Looks like a reference, but probably isn't: '83' on line 1613 -- Looks like a reference, but probably isn't: '50' on line 1613 -- Looks like a reference, but probably isn't: '53' on line 1613 -- Looks like a reference, but probably isn't: '54' on line 1474 -- Looks like a reference, but probably isn't: '125' on line 1613 -- Looks like a reference, but probably isn't: '1' on line 1361 -- Looks like a reference, but probably isn't: '0' on line 1871 -- Looks like a reference, but probably isn't: '69' on line 1613 -- Looks like a reference, but probably isn't: '49' on line 1613 -- Looks like a reference, but probably isn't: '80' on line 1622 -- Looks like a reference, but probably isn't: '121' on line 1622 -- Looks like a reference, but probably isn't: '111' on line 1622 -- Looks like a reference, but probably isn't: '100' on line 1622 -- Possible downref: Non-RFC (?) normative reference: ref. 'ITU.X690.1994' ** Downref: Normative reference to an Historic RFC: RFC 1421 ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 4288 (Obsoleted by RFC 6838) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) -- Possible downref: Non-RFC (?) normative reference: ref. 'USA15' -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' Summary: 6 errors (**), 0 flaws (~~), 1 warning (==), 24 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JOSE Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track J. Bradley 5 Expires: October 27, 2013 Ping Identity 6 N. Sakimura 7 NRI 8 April 25, 2013 10 JSON Web Signature (JWS) 11 draft-ietf-jose-json-web-signature-10 13 Abstract 15 JSON Web Signature (JWS) is a means of representing content secured 16 with digital signatures or Message Authentication Codes (MACs) using 17 JavaScript Object Notation (JSON) data structures. Cryptographic 18 algorithms and identifiers for use with this specification are 19 described in the separate JSON Web Algorithms (JWA) specification. 20 Related encryption capabilities are described in the separate JSON 21 Web Encryption (JWE) specification. 23 Status of this Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on October 27, 2013. 40 Copyright Notice 42 Copyright (c) 2013 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 3. JSON Web Signature (JWS) Overview . . . . . . . . . . . . . . 6 61 3.1. Example JWS . . . . . . . . . . . . . . . . . . . . . . . 6 62 4. JWS Header . . . . . . . . . . . . . . . . . . . . . . . . . . 7 63 4.1. Reserved Header Parameter Names . . . . . . . . . . . . . 8 64 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 8 65 4.1.2. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 8 66 4.1.3. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 9 67 4.1.4. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 9 68 4.1.5. "x5t" (X.509 Certificate Thumbprint) Header 69 Parameter . . . . . . . . . . . . . . . . . . . . . . 9 70 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter . . . 9 71 4.1.7. "kid" (Key ID) Header Parameter . . . . . . . . . . . 10 72 4.1.8. "typ" (Type) Header Parameter . . . . . . . . . . . . 10 73 4.1.9. "cty" (Content Type) Header Parameter . . . . . . . . 10 74 4.1.10. "crit" (Critical) Header Parameter . . . . . . . . . . 11 75 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 11 76 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 11 77 5. Producing and Consuming JWSs . . . . . . . . . . . . . . . . . 11 78 5.1. Message Signing or MACing . . . . . . . . . . . . . . . . 12 79 5.2. Message Signature or MAC Validation . . . . . . . . . . . 13 80 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 14 81 6. Securing JWSs with Cryptographic Algorithms . . . . . . . . . 14 82 7. JSON Serialization . . . . . . . . . . . . . . . . . . . . . . 15 83 7.1. Example JWS-JS . . . . . . . . . . . . . . . . . . . . . . 15 84 8. Implementation Considerations . . . . . . . . . . . . . . . . 17 85 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 86 9.1. JSON Web Signature and Encryption Header Parameters 87 Registry . . . . . . . . . . . . . . . . . . . . . . . . . 17 88 9.1.1. Registration Template . . . . . . . . . . . . . . . . 18 89 9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 18 90 9.2. JSON Web Signature and Encryption Type Values Registry . . 19 91 9.2.1. Registration Template . . . . . . . . . . . . . . . . 19 92 9.2.2. Initial Registry Contents . . . . . . . . . . . . . . 20 93 9.3. Media Type Registration . . . . . . . . . . . . . . . . . 20 94 9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 20 95 10. Security Considerations . . . . . . . . . . . . . . . . . . . 21 96 10.1. Cryptographic Security Considerations . . . . . . . . . . 21 97 10.2. JSON Security Considerations . . . . . . . . . . . . . . . 23 98 10.3. Unicode Comparison Security Considerations . . . . . . . . 23 99 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23 100 11.1. Normative References . . . . . . . . . . . . . . . . . . . 23 101 11.2. Informative References . . . . . . . . . . . . . . . . . . 25 102 Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 26 103 A.1. Example JWS using HMAC SHA-256 . . . . . . . . . . . . . . 26 104 A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 26 105 A.1.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 28 106 A.1.3. Validating . . . . . . . . . . . . . . . . . . . . . . 28 107 A.2. Example JWS using RSA SHA-256 . . . . . . . . . . . . . . 28 108 A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 28 109 A.2.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 32 110 A.2.3. Validating . . . . . . . . . . . . . . . . . . . . . . 32 111 A.3. Example JWS using ECDSA P-256 SHA-256 . . . . . . . . . . 33 112 A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 33 113 A.3.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 35 114 A.3.3. Validating . . . . . . . . . . . . . . . . . . . . . . 35 115 A.4. Example JWS using ECDSA P-521 SHA-512 . . . . . . . . . . 36 116 A.4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 36 117 A.4.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 38 118 A.4.3. Validating . . . . . . . . . . . . . . . . . . . . . . 38 119 A.5. Example Plaintext JWS . . . . . . . . . . . . . . . . . . 39 120 Appendix B. "x5c" (X.509 Certificate Chain) Example . . . . . . . 40 121 Appendix C. Notes on implementing base64url encoding without 122 padding . . . . . . . . . . . . . . . . . . . . . . . 41 123 Appendix D. Possible Compact Serialization for Multiple 124 Signatures . . . . . . . . . . . . . . . . . . . . . 42 125 Appendix E. Acknowledgements . . . . . . . . . . . . . . . . . . 43 126 Appendix F. Document History . . . . . . . . . . . . . . . . . . 44 127 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 48 129 1. Introduction 131 JSON Web Signature (JWS) is a compact format for representing content 132 secured with digital signatures or Message Authentication Codes 133 (MACs) intended for space constrained environments such as HTTP 134 Authorization headers and URI query parameters. It represents this 135 content using JavaScript Object Notation (JSON) [RFC4627] based data 136 structures. The JWS cryptographic mechanisms provide integrity 137 protection for arbitrary sequences of octets. 139 Cryptographic algorithms and identifiers for use with this 140 specification are described in the separate JSON Web Algorithms (JWA) 141 [JWA] specification. Related encryption capabilities are described 142 in the separate JSON Web Encryption (JWE) [JWE] specification. 144 1.1. Notational Conventions 146 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 147 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 148 document are to be interpreted as described in Key words for use in 149 RFCs to Indicate Requirement Levels [RFC2119]. 151 2. Terminology 153 JSON Web Signature (JWS) A data structure representing a digitally 154 signed or MACed message. The structure represents three values: 155 the JWS Header, the JWS Payload, and the JWS Signature. 157 JSON Text Object A UTF-8 [RFC3629] encoded text string representing 158 a JSON object; the syntax of JSON objects is defined in Section 159 2.2 of [RFC4627]. 161 JWS Header A JSON Text Object that describes the digital signature 162 or MAC operation applied to create the JWS Signature value. 164 JWS Payload The sequence of octets to be secured -- a.k.a., the 165 message. The payload can contain an arbitrary sequence of octets. 167 JWS Signature A sequence of octets containing the cryptographic 168 material that ensures the integrity of the JWS Header and the JWS 169 Payload. The JWS Signature value is a digital signature or MAC 170 value calculated over the JWS Signing Input using the parameters 171 specified in the JWS Header. 173 Base64url Encoding The URL- and filename-safe Base64 encoding 174 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 175 safe) '=' padding characters omitted, as permitted by Section 3.2. 176 (See Appendix C for notes on implementing base64url encoding 177 without padding.) 179 Encoded JWS Header Base64url encoding of the JWS Header. 181 Encoded JWS Payload Base64url encoding of the JWS Payload. 183 Encoded JWS Signature Base64url encoding of the JWS Signature. 185 JWS Signing Input The concatenation of the Encoded JWS Header, a 186 period ('.') character, and the Encoded JWS Payload. 188 Header Parameter Name The name of a member of the JWS Header. 190 Header Parameter Value The value of a member of the JWS Header. 192 JWS Compact Serialization A representation of the JWS as the 193 concatenation of the Encoded JWS Header, the Encoded JWS Payload, 194 and the Encoded JWS Signature in that order, with the three 195 strings being separated by two period ('.') characters. This 196 results in a compact, URL-safe representation. 198 JWS JSON Serialization A representation of the JWS as a JSON 199 structure containing Encoded JWS Header, Encoded JWS Payload, and 200 Encoded JWS Signature values. Unlike the JWS Compact 201 Serialization, the JWS JSON Serialization enables multiple digital 202 signatures and/or MACs to be applied to the same content. This 203 representation is neither compact nor URL-safe. 205 Collision Resistant Namespace A namespace that allows names to be 206 allocated in a manner such that they are highly unlikely to 207 collide with other names. For instance, collision resistance can 208 be achieved through administrative delegation of portions of the 209 namespace or through use of collision-resistant name allocation 210 functions. Examples of Collision Resistant Namespaces include: 211 Domain Names, Object Identifiers (OIDs) as defined in the ITU-T 212 X.660 and X.670 Recommendation series, and Universally Unique 213 IDentifiers (UUIDs) [RFC4122]. When using an administratively 214 delegated namespace, the definer of a name needs to take 215 reasonable precautions to ensure they are in control of the 216 portion of the namespace they use to define the name. 218 StringOrURI A JSON string value, with the additional requirement 219 that while arbitrary string values MAY be used, any value 220 containing a ":" character MUST be a URI [RFC3986]. StringOrURI 221 values are compared as case-sensitive strings with no 222 transformations or canonicalizations applied. 224 3. JSON Web Signature (JWS) Overview 226 JWS represents digitally signed or MACed content using JSON data 227 structures and base64url encoding. Three values are represented in a 228 JWS: the JWS Header, the JWS Payload, and the JWS Signature. In the 229 Compact Serialization, the three values are base64url-encoded for 230 transmission, and represented as the concatenation of the encoded 231 strings in that order, with the three strings being separated by two 232 period ('.') characters. A JSON Serialization for this information 233 is also defined in Section 7. 235 The JWS Header describes the signature or MAC method and parameters 236 employed. The JWS Payload is the message content to be secured. The 237 JWS Signature ensures the integrity of both the JWS Header and the 238 JWS Payload. 240 3.1. Example JWS 242 The following example JWS Header declares that the encoded object is 243 a JSON Web Token (JWT) [JWT] and the JWS Header and the JWS Payload 244 are secured using the HMAC SHA-256 algorithm: 246 {"typ":"JWT", 247 "alg":"HS256"} 249 Base64url encoding the octets of the UTF-8 representation of the JWS 250 Header yields this Encoded JWS Header value: 252 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 254 The following is an example of a JSON object that can be used as a 255 JWS Payload. (Note that the payload can be any content, and need not 256 be a representation of a JSON object.) 258 {"iss":"joe", 259 "exp":1300819380, 260 "http://example.com/is_root":true} 262 Base64url encoding the octets of the UTF-8 representation of the JSON 263 object yields the following Encoded JWS Payload (with line breaks for 264 display purposes only): 266 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 267 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 269 Computing the HMAC of the octets of the ASCII [USASCII] 270 representation of the JWS Signing Input (the concatenation of the 271 Encoded JWS Header, a period ('.') character, and the Encoded JWS 272 Payload) with the HMAC SHA-256 algorithm using the key specified in 273 Appendix A.1 and base64url encoding the result yields this Encoded 274 JWS Signature value: 276 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 278 Concatenating these values in the order Header.Payload.Signature with 279 period ('.') characters between the parts yields this complete JWS 280 representation using the JWS Compact Serialization (with line breaks 281 for display purposes only): 283 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 284 . 285 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 286 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 287 . 288 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 290 This computation is illustrated in more detail in Appendix A.1. 292 4. JWS Header 294 The members of the JSON object represented by the JWS Header describe 295 the digital signature or MAC applied to the Encoded JWS Header and 296 the Encoded JWS Payload and optionally additional properties of the 297 JWS. The Header Parameter Names within this object MUST be unique; 298 JWSs with duplicate Header Parameter Names MUST be rejected. 300 Implementations are required to understand the specific header 301 parameters defined by this specification that are designated as "MUST 302 be understood" and process them in the manner defined in this 303 specification. All other header parameters defined by this 304 specification that are not so designated MUST be ignored when not 305 understood. Unless listed as a critical header parameter, per 306 Section 4.1.10, all other header parameters MUST be ignored when not 307 understood. 309 There are three classes of Header Parameter Names: Reserved Header 310 Parameter Names, Public Header Parameter Names, and Private Header 311 Parameter Names. 313 4.1. Reserved Header Parameter Names 315 The following Header Parameter Names are reserved with meanings as 316 defined below. All the names are short because a core goal of this 317 specification is for the resulting representations using the JWS 318 Compact Serialization to be compact. 320 Additional reserved Header Parameter Names MAY be defined via the 321 IANA JSON Web Signature and Encryption Header Parameters registry 322 Section 9.1. As indicated by the common registry, JWSs and JWEs 323 share a common header parameter space; when a parameter is used by 324 both specifications, its usage must be compatible between the 325 specifications. 327 4.1.1. "alg" (Algorithm) Header Parameter 329 The "alg" (algorithm) header parameter identifies the cryptographic 330 algorithm used to secure the JWS. The algorithm specified by the 331 "alg" value MUST be supported by the implementation and there MUST be 332 a key for use with that algorithm associated with the party that 333 digitally signed or MACed the content or the JWS MUST be rejected. 334 "alg" values SHOULD either be registered in the IANA JSON Web 335 Signature and Encryption Algorithms registry [JWA] or be a value that 336 contains a Collision Resistant Namespace. The "alg" value is a case 337 sensitive string containing a StringOrURI value. Use of this header 338 parameter is REQUIRED. This header parameter MUST be understood by 339 implementations. 341 A list of defined "alg" values can be found in the IANA JSON Web 342 Signature and Encryption Algorithms registry [JWA]; the initial 343 contents of this registry are the values defined in Section 3.1 of 344 the JSON Web Algorithms (JWA) [JWA] specification. 346 4.1.2. "jku" (JWK Set URL) Header Parameter 348 The "jku" (JWK Set URL) header parameter is a URI [RFC3986] that 349 refers to a resource for a set of JSON-encoded public keys, one of 350 which corresponds to the key used to digitally sign the JWS. The 351 keys MUST be encoded as a JSON Web Key Set (JWK Set) [JWK]. The 352 protocol used to acquire the resource MUST provide integrity 353 protection; an HTTP GET request to retrieve the certificate MUST use 354 TLS [RFC2818] [RFC5246]; the identity of the server MUST be 355 validated, as per Section 3.1 of HTTP Over TLS [RFC2818]. Use of 356 this header parameter is OPTIONAL. 358 4.1.3. "jwk" (JSON Web Key) Header Parameter 360 The "jwk" (JSON Web Key) header parameter is the public key that 361 corresponds to the key used to digitally sign the JWS. This key is 362 represented as a JSON Web Key [JWK]. Use of this header parameter is 363 OPTIONAL. 365 4.1.4. "x5u" (X.509 URL) Header Parameter 367 The "x5u" (X.509 URL) header parameter is a URI [RFC3986] that refers 368 to a resource for the X.509 public key certificate or certificate 369 chain [RFC5280] corresponding to the key used to digitally sign the 370 JWS. The identified resource MUST provide a representation of the 371 certificate or certificate chain that conforms to RFC 5280 [RFC5280] 372 in PEM encoded form [RFC1421]. The certificate containing the public 373 key corresponding to the key used to digitally sign the JWS MUST be 374 the first certificate. This MAY be followed by additional 375 certificates, with each subsequent certificate being the one used to 376 certify the previous one. The protocol used to acquire the resource 377 MUST provide integrity protection; an HTTP GET request to retrieve 378 the certificate MUST use TLS [RFC2818] [RFC5246]; the identity of the 379 server MUST be validated, as per Section 3.1 of HTTP Over TLS 380 [RFC2818]. Use of this header parameter is OPTIONAL. 382 4.1.5. "x5t" (X.509 Certificate Thumbprint) Header Parameter 384 The "x5t" (X.509 Certificate Thumbprint) header parameter provides a 385 base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER 386 encoding of the X.509 certificate [RFC5280] corresponding to the key 387 used to digitally sign the JWS. Use of this header parameter is 388 OPTIONAL. 390 If, in the future, certificate thumbprints need to be computed using 391 hash functions other than SHA-1, it is suggested that additional 392 related header parameters be defined for that purpose. For example, 393 it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint 394 using SHA-256) header parameter could be defined by registering it in 395 the IANA JSON Web Signature and Encryption Header Parameters registry 396 Section 9.1. 398 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter 400 The "x5c" (X.509 Certificate Chain) header parameter contains the 401 X.509 public key certificate or certificate chain [RFC5280] 402 corresponding to the key used to digitally sign the JWS. The 403 certificate or certificate chain is represented as an array of 404 certificate value strings. Each string is a base64 encoded 405 ([RFC4648] Section 4 -- not base64url encoded) DER [ITU.X690.1994] 406 PKIX certificate value. The certificate containing the public key 407 corresponding to the key used to digitally sign the JWS MUST be the 408 first certificate. This MAY be followed by additional certificates, 409 with each subsequent certificate being the one used to certify the 410 previous one. The recipient MUST verify the certificate chain 411 according to [RFC5280] and reject the JWS if any validation failure 412 occurs. Use of this header parameter is OPTIONAL. 414 See Appendix B for an example "x5c" value. 416 4.1.7. "kid" (Key ID) Header Parameter 418 The "kid" (key ID) header parameter is a hint indicating which key 419 was used to secure the JWS. This parameter allows originators to 420 explicitly signal a change of key to recipients. Should the 421 recipient be unable to locate a key corresponding to the "kid" value, 422 they SHOULD treat that condition as an error. The interpretation of 423 the "kid" value is unspecified. Its value MUST be a string. Use of 424 this header parameter is OPTIONAL. 426 When used with a JWK, the "kid" value can be used to match a JWK 427 "kid" parameter value. 429 4.1.8. "typ" (Type) Header Parameter 431 The "typ" (type) header parameter is used to declare the type of this 432 object. The type value "JWS" is used to indicate that this object is 433 a JWS using the JWS Compact Serialization. The type value "JWS-JS" 434 is used to indicate that this object is a JWS using the JWS JSON 435 Serialization. The "typ" value is a case sensitive string. Use of 436 this header parameter is OPTIONAL. 438 MIME Media Type [RFC2046] values MAY be used as "typ" values. 440 "typ" values SHOULD either be registered in the IANA JSON Web 441 Signature and Encryption Type Values registry Section 9.2 or be a 442 value that contains a Collision Resistant Namespace. 444 4.1.9. "cty" (Content Type) Header Parameter 446 The "cty" (content type) header parameter is used to declare the type 447 of the secured content (the Payload). For example, the JSON Web 448 Token (JWT) [JWT] specification uses the "cty" value "JWT" to 449 indicate that the Payload is a JSON Web Token (JWT). The "cty" value 450 is a case sensitive string. Use of this header parameter is 451 OPTIONAL. 453 The values used for the "cty" header parameter come from the same 454 value space as the "typ" header parameter, with the same rules 455 applying. 457 4.1.10. "crit" (Critical) Header Parameter 459 The "crit" (critical) header parameter is array listing the names of 460 header parameters that are present in the JWS Header that MUST be 461 understood and processed by the implementation or if not understood, 462 MUST cause the JWS to be rejected. This list MUST NOT include header 463 parameters defined by this specification, duplicate names, or names 464 that do not occur as header parameters within the JWS. Use of this 465 header parameter is OPTIONAL. This header parameter MUST be 466 understood by implementations. 468 An example use, along with a hypothetical "exp" (expiration-time) 469 field is: 471 {"alg":"ES256", 472 "crit":["exp"], 473 "exp":1363284000 474 } 476 4.2. Public Header Parameter Names 478 Additional Header Parameter Names can be defined by those using JWSs. 479 However, in order to prevent collisions, any new Header Parameter 480 Name SHOULD either be registered in the IANA JSON Web Signature and 481 Encryption Header Parameters registry Section 9.1 or be a Public 482 Name: a value that contains a Collision Resistant Namespace. In each 483 case, the definer of the name or value needs to take reasonable 484 precautions to make sure they are in control of the part of the 485 namespace they use to define the Header Parameter Name. 487 New header parameters should be introduced sparingly, as they can 488 result in non-interoperable JWSs. 490 4.3. Private Header Parameter Names 492 A producer and consumer of a JWS may agree to use Header Parameter 493 Names that are Private Names: names that are not Reserved Names 494 Section 4.1 or Public Names Section 4.2. Unlike Public Names, 495 Private Names are subject to collision and should be used with 496 caution. 498 5. Producing and Consuming JWSs 499 5.1. Message Signing or MACing 501 To create a JWS, one MUST perform these steps. The order of the 502 steps is not significant in cases where there are no dependencies 503 between the inputs and outputs of the steps. 505 1. Create the content to be used as the JWS Payload. 507 2. Base64url encode the octets of the JWS Payload. This encoding 508 becomes the Encoded JWS Payload. 510 3. Create a JWS Header containing the desired set of header 511 parameters. Note that white space is explicitly allowed in the 512 representation and no canonicalization need be performed before 513 encoding. 515 4. Base64url encode the octets of the UTF-8 representation of the 516 JWS Header to create the Encoded JWS Header. 518 5. Compute the JWS Signature in the manner defined for the 519 particular algorithm being used over the JWS Signing Input (the 520 concatenation of the Encoded JWS Header, a period ('.') 521 character, and the Encoded JWS Payload). The "alg" (algorithm) 522 header parameter MUST be present in the JWS Header, with the 523 algorithm value accurately representing the algorithm used to 524 construct the JWS Signature. 526 6. Base64url encode the representation of the JWS Signature to 527 create the Encoded JWS Signature. 529 7. The three encoded parts are the result values used in both the 530 JWS Compact Serialization and the JWS JSON Serialization 531 representations. 533 8. If the JWS JSON Serialization is being used, repeat this process 534 for each digital signature or MAC value being applied. 536 9. Create the desired serialized output. The JWS Compact 537 Serialization of this result is the concatenation of the Encoded 538 JWS Header, the Encoded JWS Payload, and the Encoded JWS 539 Signature in that order, with the three strings being separated 540 by two period ('.') characters. The JWS JSON Serialization is 541 described in Section 7. 543 5.2. Message Signature or MAC Validation 545 When validating a JWS, the following steps MUST be taken. The order 546 of the steps is not significant in cases where there are no 547 dependencies between the inputs and outputs of the steps. If any of 548 the listed steps fails, then the JWS MUST be rejected. 550 1. Parse the serialized input to determine the values of the Encoded 551 JWS Header, the Encoded JWS Payload, and the Encoded JWS 552 Signature. When using the JWS Compact Serialization, these three 553 values are represented as text strings in that order, separated 554 by two period ('.') characters. The JWS JSON Serialization is 555 described in Section 7. 557 2. The Encoded JWS Header MUST be successfully base64url decoded 558 following the restriction given in this specification that no 559 padding characters have been used. 561 3. The resulting JWS Header MUST be completely valid JSON syntax 562 conforming to RFC 4627 [RFC4627]. 564 4. The resulting JWS Header MUST be validated to only include 565 parameters and values whose syntax and semantics are both 566 understood and supported or that are specified as being ignored 567 when not understood. 569 5. The Encoded JWS Payload MUST be successfully base64url decoded 570 following the restriction given in this specification that no 571 padding characters have been used. 573 6. The Encoded JWS Signature MUST be successfully base64url decoded 574 following the restriction given in this specification that no 575 padding characters have been used. 577 7. The JWS Signature MUST be successfully validated against the JWS 578 Signing Input (the concatenation of the Encoded JWS Header, a 579 period ('.') character, and the Encoded JWS Payload) in the 580 manner defined for the algorithm being used, which MUST be 581 accurately represented by the value of the "alg" (algorithm) 582 header parameter, which MUST be present. 584 8. If the JWS JSON Serialization is being used, repeat this process 585 for each digital signature or MAC value contained in the 586 representation. 588 5.3. String Comparison Rules 590 Processing a JWS inevitably requires comparing known strings to 591 values in JSON objects. For example, in checking what the algorithm 592 is, the Unicode string encoding "alg" will be checked against the 593 member names in the JWS Header to see if there is a matching Header 594 Parameter Name. A similar process occurs when determining if the 595 value of the "alg" header parameter represents a supported algorithm. 597 Comparisons between JSON strings and other Unicode strings MUST be 598 performed as specified below: 600 1. Remove any JSON escaping from the input JSON string and convert 601 the string into a sequence of Unicode code points. 603 2. Likewise, convert the string to be compared against into a 604 sequence of Unicode code points. 606 3. Unicode Normalization [USA15] MUST NOT be applied at any point to 607 either the JSON string or to the string it is to be compared 608 against. 610 4. Comparisons between the two strings MUST be performed as a 611 Unicode code point to code point equality comparison. (Note that 612 values that originally used different Unicode encodings (UTF-8, 613 UTF-16, etc.) may result in the same code point values.) 615 Also, see the JSON security considerations in Section 10.2 and the 616 Unicode security considerations in Section 10.3. 618 6. Securing JWSs with Cryptographic Algorithms 620 JWS uses cryptographic algorithms to digitally sign or MAC the JWS 621 Header and the JWS Payload. The JSON Web Algorithms (JWA) [JWA] 622 specification describes a set of cryptographic algorithms and 623 identifiers to be used with this specification. Specifically, 624 Section 3.1 specifies a set of "alg" (algorithm) header parameter 625 values intended for use this specification. It also describes the 626 semantics and operations that are specific to these algorithms. 628 Public keys employed for digital signing can be identified using the 629 Header Parameter methods described in Section 4.1 or can be 630 distributed using methods that are outside the scope of this 631 specification. 633 7. JSON Serialization 635 The JWS JSON Serialization represents digitally signed or MACed 636 content as a JSON object with a "signatures" member containing an 637 array of per-signature information and a "payload" member containing 638 a shared Encoded JWS Payload value. Each member of the "signatures" 639 array is a JSON object with a "header" member containing an Encoded 640 JWS Header value and a "signature" member containing an Encoded JWS 641 Signature value. 643 Unlike the JWS Compact Serialization, content using the JWS JSON 644 Serialization MAY be secured with more than one digital signature 645 and/or MAC value. Each is represented as an Encoded JWS Signature 646 value in the "signature" member of an object in the "signatures" 647 array. For each signature, there is an Encoded JWS Encoded Header 648 value in the "header" member of the same object in the "signatures" 649 array. This specifies the digital signature or MAC applied to the 650 Encoded JWS Header value and the shared Encoded JWS Payload value to 651 create the JWS Signature value. Therefore, the syntax is: 653 {"signatures":[ 654 {"header":"
", 655 "signature":""}, 656 ... 657 {"header":"
", 658 "signature":""}], 659 "payload":"" 660 } 662 The contents of the Encoded JWS Header, Encoded JWS Payload, and 663 Encoded JWS Signature values are exactly as specified in the rest of 664 this specification. They are interpreted and validated in the same 665 manner, with each corresponding "header" and "signature" value being 666 created and validated together. 668 Each JWS Signature value is computed on the JWS Signing Input 669 corresponding to the concatenation of the Encoded JWS Header, a 670 period ('.') character, and the Encoded JWS Payload in the same 671 manner as for the JWS Compact Serialization. This has the desirable 672 result that each Encoded JWS Signature value in the "signatures" 673 array is identical to the value that would be used for the same 674 parameter in the JWS Compact Serialization, as is the shared JWS 675 Payload value. 677 7.1. Example JWS-JS 679 This section contains an example using the JWS JSON Serialization. 680 This example demonstrates the capability for conveying multiple 681 digital signatures and/or MACs for the same payload. 683 The Encoded JWS Payload used in this example is the same as used in 684 the examples in Appendix A (with line breaks for display purposes 685 only): 687 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 688 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 690 Two digital signatures are used in this example: an RSA SHA-256 691 signature, for which the header and signature values are the same as 692 in Appendix A.2, and an ECDSA P-256 SHA-256 signature, for which the 693 header and signature values are the same as in Appendix A.3. The two 694 Decoded JWS Header Segments used are: 696 {"alg":"RS256"} 698 and: 700 {"alg":"ES256"} 702 Since the computations of the JWS Header and JWS Signature values are 703 the same as in Appendix A.2 and Appendix A.3, they are not repeated 704 here. 706 The complete JSON Web Signature JSON Serialization (JWS-JS) for these 707 values is as follows (with line breaks for display purposes only): 709 {"signatures":[ 710 {"header":"eyJhbGciOiJSUzI1NiJ9", 711 "signature": 712 "cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZ 713 mh7AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjb 714 KBYNX4BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHl 715 b1L07Qe7K0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZES 716 c6BfI7noOPqvhJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AX 717 LIhWkWywlVmtVrBp0igcN_IoypGlUPQGe77Rw"}, 718 {"header":"eyJhbGciOiJFUzI1NiJ9", 719 "signature": 720 "DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8IS 721 lSApmWQxfKTUJqPP3-Kg6NU1Q"}], 722 "payload": 723 "eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGF 724 tcGxlLmNvbS9pc19yb290Ijp0cnVlfQ" 725 } 727 8. Implementation Considerations 729 The JWS Compact Serialization is mandatory to implement. 730 Implementation of the JWS JSON Serialization is OPTIONAL. 732 9. IANA Considerations 734 The following registration procedure is used for all the registries 735 established by this specification. 737 Values are registered with a Specification Required [RFC5226] after a 738 two-week review period on the [TBD]@ietf.org mailing list, on the 739 advice of one or more Designated Experts. However, to allow for the 740 allocation of values prior to publication, the Designated Expert(s) 741 may approve registration once they are satisfied that such a 742 specification will be published. 744 Registration requests must be sent to the [TBD]@ietf.org mailing list 745 for review and comment, with an appropriate subject (e.g., "Request 746 for access token type: example"). [[ Note to RFC-EDITOR: The name of 747 the mailing list should be determined in consultation with the IESG 748 and IANA. Suggested name: jose-reg-review. ]] 750 Within the review period, the Designated Expert(s) will either 751 approve or deny the registration request, communicating this decision 752 to the review list and IANA. Denials should include an explanation 753 and, if applicable, suggestions as to how to make the request 754 successful. 756 IANA must only accept registry updates from the Designated Expert(s) 757 and should direct all requests for registration to the review mailing 758 list. 760 9.1. JSON Web Signature and Encryption Header Parameters Registry 762 This specification establishes the IANA JSON Web Signature and 763 Encryption Header Parameters registry for reserved JWS and JWE Header 764 Parameter Names. The registry records the reserved Header Parameter 765 Name and a reference to the specification that defines it. The same 766 Header Parameter Name MAY be registered multiple times, provided that 767 the parameter usage is compatible between the specifications. 768 Different registrations of the same Header Parameter Name will 769 typically use different Header Parameter Usage Location(s) values. 771 9.1.1. Registration Template 773 Header Parameter Name: 774 The name requested (e.g., "example"). This name is case 775 sensitive. Names that match other registered names in a case 776 insensitive manner SHOULD NOT be accepted. 778 Header Parameter Usage Location(s): 779 The header parameter usage locations, which should be one or more 780 of the values "JWS" or "JWE". 782 Change Controller: 783 For Standards Track RFCs, state "IETF". For others, give the name 784 of the responsible party. Other details (e.g., postal address, 785 email address, home page URI) may also be included. 787 Specification Document(s): 788 Reference to the document(s) that specify the parameter, 789 preferably including URI(s) that can be used to retrieve copies of 790 the document(s). An indication of the relevant sections may also 791 be included but is not required. 793 9.1.2. Initial Registry Contents 795 This specification registers the Header Parameter Names defined in 796 Section 4.1 in this registry. 798 o Header Parameter Name: "alg" 799 o Header Parameter Usage Location(s): JWS 800 o Change Controller: IETF 801 o Specification Document(s): Section 4.1.1 of [[ this document ]] 803 o Header Parameter Name: "jku" 804 o Header Parameter Usage Location(s): JWS 805 o Change Controller: IETF 806 o Specification Document(s): Section 4.1.2 of [[ this document ]] 808 o Header Parameter Name: "jwk" 809 o Header Parameter Usage Location(s): JWS 810 o Change Controller: IETF 811 o Specification document(s): Section 4.1.3 of [[ this document ]] 813 o Header Parameter Name: "x5u" 814 o Header Parameter Usage Location(s): JWS 815 o Change Controller: IETF 816 o Specification Document(s): Section 4.1.4 of [[ this document ]] 817 o Header Parameter Name: "x5t" 818 o Header Parameter Usage Location(s): JWS 819 o Change Controller: IETF 820 o Specification Document(s): Section 4.1.5 of [[ this document ]] 822 o Header Parameter Name: "x5c" 823 o Header Parameter Usage Location(s): JWS 824 o Change Controller: IETF 825 o Specification Document(s): Section 4.1.6 of [[ this document ]] 827 o Header Parameter Name: "kid" 828 o Header Parameter Usage Location(s): JWS 829 o Change Controller: IETF 830 o Specification Document(s): Section 4.1.7 of [[ this document ]] 832 o Header Parameter Name: "typ" 833 o Header Parameter Usage Location(s): JWS 834 o Change Controller: IETF 835 o Specification Document(s): Section 4.1.8 of [[ this document ]] 837 o Header Parameter Name: "cty" 838 o Header Parameter Usage Location(s): JWS 839 o Change Controller: IETF 840 o Specification Document(s): Section 4.1.9 of [[ this document ]] 842 o Header Parameter Name: "crit" 843 o Header Parameter Usage Location(s): JWS 844 o Change Controller: IETF 845 o Specification Document(s): Section 4.1.10 of [[ this document ]] 847 9.2. JSON Web Signature and Encryption Type Values Registry 849 This specification establishes the IANA JSON Web Signature and 850 Encryption Type Values registry for values of the JWS and JWE "typ" 851 (type) header parameter. It is RECOMMENDED that all registered "typ" 852 values also include a MIME Media Type [RFC2046] value that the 853 registered value is a short name for. The registry records the "typ" 854 value, the MIME type value that it is an abbreviation for (if any), 855 and a reference to the specification that defines it. 857 MIME Media Type [RFC2046] values MUST NOT be directly registered as 858 new "typ" values; rather, new "typ" values MAY be registered as short 859 names for MIME types. 861 9.2.1. Registration Template 862 "typ" Header Parameter Value: 863 The name requested (e.g., "example"). This name is case 864 sensitive. Names that match other registered names in a case 865 insensitive manner SHOULD NOT be accepted. 867 Abbreviation for MIME Type: 868 The MIME type that this name is an abbreviation for (e.g., 869 "application/example"). 871 Change Controller: 872 For Standards Track RFCs, state "IETF". For others, give the name 873 of the responsible party. Other details (e.g., postal address, 874 email address, home page URI) may also be included. 876 Specification Document(s): 877 Reference to the document(s) that specify the parameter, 878 preferably including URI(s) that can be used to retrieve copies of 879 the document(s). An indication of the relevant sections may also 880 be included but is not required. 882 9.2.2. Initial Registry Contents 884 This specification registers the "JWS" and "JWS-JS" type values in 885 this registry: 887 o "typ" Header Parameter Value: "JWS" 888 o Abbreviation for MIME type: application/jws 889 o Change Controller: IETF 890 o Specification Document(s): Section 4.1.8 of [[ this document ]] 892 o "typ" Header Parameter Value: "JWS-JS" 893 o Abbreviation for MIME type: application/jws-js 894 o Change Controller: IETF 895 o Specification Document(s): Section 4.1.8 of [[ this document ]] 897 9.3. Media Type Registration 899 9.3.1. Registry Contents 901 This specification registers the "application/jws" and 902 "application/jws-js" Media Types [RFC2046] in the MIME Media Type 903 registry [RFC4288] to indicate, respectively, that the content is a 904 JWS using the JWS Compact Serialization or a JWS using the JWS JSON 905 Serialization. 907 o Type name: application 908 o Subtype name: jws 909 o Required parameters: n/a 910 o Optional parameters: n/a 911 o Encoding considerations: JWS values are encoded as a series of 912 base64url encoded values (some of which may be the empty string) 913 separated by period ('.') characters 914 o Security considerations: See the Security Considerations section 915 of [[ this document ]] 916 o Interoperability considerations: n/a 917 o Published specification: [[ this document ]] 918 o Applications that use this media type: OpenID Connect, Mozilla 919 Persona, Salesforce, Google, numerous others that use signed JWTs 920 o Additional information: Magic number(s): n/a, File extension(s): 921 n/a, Macintosh file type code(s): n/a 922 o Person & email address to contact for further information: Michael 923 B. Jones, mbj@microsoft.com 924 o Intended usage: COMMON 925 o Restrictions on usage: none 926 o Author: Michael B. Jones, mbj@microsoft.com 927 o Change Controller: IETF 929 o Type name: application 930 o Subtype name: jws-js 931 o Required parameters: n/a 932 o Optional parameters: n/a 933 o Encoding considerations: JWS-JS values are represented as a JSON 934 Object; UTF-8 encoding SHOULD be employed for the JSON object. 935 o Security considerations: See the Security Considerations section 936 of [[ this document ]] 937 o Interoperability considerations: n/a 938 o Published specification: [[ this document ]] 939 o Applications that use this media type: TBD 940 o Additional information: Magic number(s): n/a, File extension(s): 941 n/a, Macintosh file type code(s): n/a 942 o Person & email address to contact for further information: Michael 943 B. Jones, mbj@microsoft.com 944 o Intended usage: COMMON 945 o Restrictions on usage: none 946 o Author: Michael B. Jones, mbj@microsoft.com 947 o Change Controller: IETF 949 10. Security Considerations 951 10.1. Cryptographic Security Considerations 953 All of the security issues faced by any cryptographic application 954 must be faced by a JWS/JWE/JWK agent. Among these issues are 955 protecting the user's private and symmetric keys, preventing various 956 attacks, and helping the user avoid mistakes such as inadvertently 957 encrypting a message for the wrong recipient. The entire list of 958 security considerations is beyond the scope of this document, but 959 some significant concerns are listed here. 961 All the security considerations in XML DSIG 2.0 962 [W3C.CR-xmldsig-core2-20120124], also apply to this specification, 963 other than those that are XML specific. Likewise, many of the best 964 practices documented in XML Signature Best Practices 965 [W3C.WD-xmldsig-bestpractices-20110809] also apply to this 966 specification, other than those that are XML specific. 968 Keys are only as strong as the amount of entropy used to generate 969 them. A minimum of 128 bits of entropy should be used for all keys, 970 and depending upon the application context, more may be required. In 971 particular, it may be difficult to generate sufficiently random 972 values in some browsers and application environments. 974 Creators of JWSs should not allow third parties to insert arbitrary 975 content into the message without adding entropy not controlled by the 976 third party. 978 When utilizing TLS to retrieve information, the authority providing 979 the resource MUST be authenticated and the information retrieved MUST 980 be free from modification. 982 When cryptographic algorithms are implemented in such a way that 983 successful operations take a different amount of time than 984 unsuccessful operations, attackers may be able to use the time 985 difference to obtain information about the keys employed. Therefore, 986 such timing differences must be avoided. 988 A SHA-1 hash is used when computing "x5t" (x.509 certificate 989 thumbprint) values, for compatibility reasons. Should an effective 990 means of producing SHA-1 hash collisions be developed, and should an 991 attacker wish to interfere with the use of a known certificate on a 992 given system, this could be accomplished by creating another 993 certificate whose SHA-1 hash value is the same and adding it to the 994 certificate store used by the intended victim. A prerequisite to 995 this attack succeeding is the attacker having write access to the 996 intended victim's certificate store. 998 If, in the future, certificate thumbprints need to be computed using 999 hash functions other than SHA-1, it is suggested that additional 1000 related header parameters be defined for that purpose. For example, 1001 it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint 1002 using SHA-256) header parameter could be defined and used. 1004 10.2. JSON Security Considerations 1006 Strict JSON validation is a security requirement. If malformed JSON 1007 is received, then the intent of the sender is impossible to reliably 1008 discern. Ambiguous and potentially exploitable situations could 1009 arise if the JSON parser used does not reject malformed JSON syntax. 1011 Section 2.2 of the JavaScript Object Notation (JSON) specification 1012 [RFC4627] states "The names within an object SHOULD be unique", 1013 whereas this specification states that "Header Parameter Names within 1014 this object MUST be unique; JWSs with duplicate Header Parameter 1015 Names MUST be rejected". Thus, this specification requires that the 1016 Section 2.2 "SHOULD" be treated as a "MUST". Ambiguous and 1017 potentially exploitable situations could arise if the JSON parser 1018 used does not enforce the uniqueness of member names. 1020 Some JSON parsers might not reject input that contains extra 1021 significant characters after a valid input. For instance, the input 1022 "{"tag":"value"}ABCD" contains a valid JSON object followed by the 1023 extra characters "ABCD". Such input MUST be rejected in its 1024 entirety. 1026 10.3. Unicode Comparison Security Considerations 1028 Header Parameter Names and algorithm names are Unicode strings. For 1029 security reasons, the representations of these names must be compared 1030 verbatim after performing any escape processing (as per RFC 4627 1031 [RFC4627], Section 2.5). This means, for instance, that these JSON 1032 strings must compare as being equal ("sig", "\u0073ig"), whereas 1033 these must all compare as being not equal to the first set or to each 1034 other ("SIG", "Sig", "si\u0047"). 1036 JSON strings can contain characters outside the Unicode Basic 1037 Multilingual Plane. For instance, the G clef character (U+1D11E) may 1038 be represented in a JSON string as "\uD834\uDD1E". Ideally, JWS 1039 implementations SHOULD ensure that characters outside the Basic 1040 Multilingual Plane are preserved and compared correctly; 1041 alternatively, if this is not possible due to these characters 1042 exercising limitations present in the underlying JSON implementation, 1043 then input containing them MUST be rejected. 1045 11. References 1047 11.1. Normative References 1049 [ITU.X690.1994] 1050 International Telecommunications Union, "Information 1051 Technology - ASN.1 encoding rules: Specification of Basic 1052 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1053 Distinguished Encoding Rules (DER)", ITU-T Recommendation 1054 X.690, 1994. 1056 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1057 draft-ietf-jose-json-web-algorithms (work in progress), 1058 April 2013. 1060 [JWK] Jones, M., "JSON Web Key (JWK)", 1061 draft-ietf-jose-json-web-key (work in progress), 1062 April 2013. 1064 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 1065 Mail: Part I: Message Encryption and Authentication 1066 Procedures", RFC 1421, February 1993. 1068 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1069 Extensions (MIME) Part Two: Media Types", RFC 2046, 1070 November 1996. 1072 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1073 Requirement Levels", BCP 14, RFC 2119, March 1997. 1075 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1077 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1078 10646", STD 63, RFC 3629, November 2003. 1080 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1081 Resource Identifier (URI): Generic Syntax", STD 66, 1082 RFC 3986, January 2005. 1084 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 1085 Registration Procedures", RFC 4288, December 2005. 1087 [RFC4627] Crockford, D., "The application/json Media Type for 1088 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1090 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1091 Encodings", RFC 4648, October 2006. 1093 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1094 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1095 May 2008. 1097 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1098 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1100 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1101 Housley, R., and W. Polk, "Internet X.509 Public Key 1102 Infrastructure Certificate and Certificate Revocation List 1103 (CRL) Profile", RFC 5280, May 2008. 1105 [USA15] Davis, M., Whistler, K., and M. Duerst, "Unicode 1106 Normalization Forms", Unicode Standard Annex 15, 09 2009. 1108 [USASCII] American National Standards Institute, "Coded Character 1109 Set -- 7-bit American Standard Code for Information 1110 Interchange", ANSI X3.4, 1986. 1112 [W3C.WD-xmldsig-bestpractices-20110809] 1113 Datta, P. and F. Hirsch, "XML Signature Best Practices", 1114 World Wide Web Consortium WD WD-xmldsig-bestpractices- 1115 20110809, August 2011, . 1118 11.2. Informative References 1120 [CanvasApp] 1121 Facebook, "Canvas Applications", 2010. 1123 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 1124 September 2010. 1126 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 1127 Encryption (JWE)", draft-ietf-jose-json-web-encryption 1128 (work in progress), April 2013. 1130 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1131 (JWT)", draft-ietf-oauth-json-web-token (work in 1132 progress), April 2013. 1134 [MagicSignatures] 1135 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 1136 Signatures", January 2011. 1138 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1139 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1140 July 2005. 1142 [W3C.CR-xmldsig-core2-20120124] 1143 Eastlake, D., Reagle, J., Yiu, K., Solo, D., Datta, P., 1144 Hirsch, F., Cantor, S., and T. Roessler, "XML Signature 1145 Syntax and Processing Version 2.0", World Wide Web 1146 Consortium CR CR-xmldsig-core2-20120124, January 2012, 1147 . 1149 Appendix A. JWS Examples 1151 This section provides several examples of JWSs. While these examples 1152 all represent JSON Web Tokens (JWTs) [JWT], the payload can be any 1153 base64url encoded content. 1155 A.1. Example JWS using HMAC SHA-256 1157 A.1.1. Encoding 1159 The following example JWS Header declares that the data structure is 1160 a JSON Web Token (JWT) [JWT] and the JWS Signing Input is secured 1161 using the HMAC SHA-256 algorithm. 1163 {"typ":"JWT", 1164 "alg":"HS256"} 1166 The following octet sequence contains the UTF-8 representation of the 1167 JWS Header: 1169 [123, 34, 116, 121, 112, 34, 58, 34, 74, 87, 84, 34, 44, 13, 10, 32, 1170 34, 97, 108, 103, 34, 58, 34, 72, 83, 50, 53, 54, 34, 125] 1172 Base64url encoding these octets yields this Encoded JWS Header value: 1174 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 1176 The JWS Payload used in this example is the octets of the UTF-8 1177 representation of the JSON object below. (Note that the payload can 1178 be any base64url encoded octet sequence, and need not be a base64url 1179 encoded JSON object.) 1181 {"iss":"joe", 1182 "exp":1300819380, 1183 "http://example.com/is_root":true} 1185 The following octet sequence, which is the UTF-8 representation of 1186 the JSON object above, is the JWS Payload: 1188 [123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10, 1189 32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56, 1190 48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97, 1191 109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111, 1192 111, 116, 34, 58, 116, 114, 117, 101, 125] 1194 Base64url encoding the above yields the Encoded JWS Payload value 1195 (with line breaks for display purposes only): 1197 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1198 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1200 Concatenating the Encoded JWS Header, a period ('.') character, and 1201 the Encoded JWS Payload yields this JWS Signing Input value (with 1202 line breaks for display purposes only): 1204 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 1205 . 1206 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1207 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1209 The ASCII representation of the JWS Signing Input is the following 1210 octet sequence: 1212 [101, 121, 74, 48, 101, 88, 65, 105, 79, 105, 74, 75, 86, 49, 81, 1213 105, 76, 65, 48, 75, 73, 67, 74, 104, 98, 71, 99, 105, 79, 105, 74, 1214 73, 85, 122, 73, 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 1215 77, 105, 79, 105, 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 1216 74, 108, 101, 72, 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 1217 107, 122, 79, 68, 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 1218 72, 65, 54, 76, 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 1219 109, 78, 118, 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 1220 106, 112, 48, 99, 110, 86, 108, 102, 81] 1222 HMACs are generated using keys. This example uses the key 1223 represented by the following octet sequence: 1225 [3, 35, 53, 75, 43, 15, 165, 188, 131, 126, 6, 101, 119, 123, 166, 1226 143, 90, 179, 40, 230, 240, 84, 201, 40, 169, 15, 132, 178, 210, 80, 1227 46, 191, 211, 251, 90, 146, 210, 6, 71, 239, 150, 138, 180, 195, 119, 1228 98, 61, 34, 61, 46, 33, 114, 5, 46, 79, 8, 192, 205, 154, 245, 103, 1229 208, 128, 163] 1231 Running the HMAC SHA-256 algorithm on the octets of the ASCII 1232 representation of the JWS Signing Input with this key yields the 1233 following octet sequence: 1235 [116, 24, 223, 180, 151, 153, 224, 37, 79, 250, 96, 125, 216, 173, 1236 187, 186, 22, 212, 37, 77, 105, 214, 191, 240, 91, 88, 5, 88, 83, 1237 132, 141, 121] 1239 Base64url encoding the above HMAC output yields the Encoded JWS 1240 Signature value: 1242 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 1244 Concatenating these values in the order Header.Payload.Signature with 1245 period ('.') characters between the parts yields this complete JWS 1246 representation using the JWS Compact Serialization (with line breaks 1247 for display purposes only): 1249 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 1250 . 1251 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1252 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1253 . 1254 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 1256 A.1.2. Decoding 1258 Decoding the JWS requires base64url decoding the Encoded JWS Header, 1259 Encoded JWS Payload, and Encoded JWS Signature to produce the JWS 1260 Header, JWS Payload, and JWS Signature octet sequences. The octet 1261 sequence containing the UTF-8 representation of the JWS Header is 1262 decoded into the JWS Header string. 1264 A.1.3. Validating 1266 Next we validate the decoded results. Since the "alg" parameter in 1267 the header is "HS256", we validate the HMAC SHA-256 value contained 1268 in the JWS Signature. If any of the validation steps fail, the JWS 1269 MUST be rejected. 1271 First, we validate that the JWS Header string is legal JSON. 1273 To validate the HMAC value, we repeat the previous process of using 1274 the correct key and the ASCII representation of the JWS Signing Input 1275 as input to the HMAC SHA-256 function and then taking the output and 1276 determining if it matches the JWS Signature. If it matches exactly, 1277 the HMAC has been validated. 1279 A.2. Example JWS using RSA SHA-256 1281 A.2.1. Encoding 1283 The JWS Header in this example is different from the previous example 1284 in two ways: First, because a different algorithm is being used, the 1285 "alg" value is different. Second, for illustration purposes only, 1286 the optional "typ" parameter is not used. (This difference is not 1287 related to the algorithm employed.) The JWS Header used is: 1289 {"alg":"RS256"} 1291 The following octet sequence contains the UTF-8 representation of the 1292 JWS Header: 1294 [123, 34, 97, 108, 103, 34, 58, 34, 82, 83, 50, 53, 54, 34, 125] 1296 Base64url encoding these octets yields this Encoded JWS Header value: 1298 eyJhbGciOiJSUzI1NiJ9 1300 The JWS Payload used in this example, which follows, is the same as 1301 in the previous example. Since the Encoded JWS Payload will 1302 therefore be the same, its computation is not repeated here. 1304 {"iss":"joe", 1305 "exp":1300819380, 1306 "http://example.com/is_root":true} 1308 Concatenating the Encoded JWS Header, a period ('.') character, and 1309 the Encoded JWS Payload yields this JWS Signing Input value (with 1310 line breaks for display purposes only): 1312 eyJhbGciOiJSUzI1NiJ9 1313 . 1314 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1315 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1317 The ASCII representation of the JWS Signing Input is the following 1318 octet sequence: 1320 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 122, 73, 1321 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, 1322 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 74, 108, 101, 72, 1323 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 107, 122, 79, 68, 1324 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 72, 65, 54, 76, 1325 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 109, 78, 118, 1326 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48, 1327 99, 110, 86, 108, 102, 81] 1329 The RSA key consists of a public part (Modulus, Exponent), and a 1330 Private Exponent. The values of the RSA key used in this example, 1331 presented as the octet sequences representing big endian integers 1332 are: 1334 +-----------+-------------------------------------------------------+ 1335 | Parameter | Value | 1336 | Name | | 1337 +-----------+-------------------------------------------------------+ 1338 | Modulus | [161, 248, 22, 10, 226, 227, 201, 180, 101, 206, 141, | 1339 | | 45, 101, 98, 99, 54, 43, 146, 125, 190, 41, 225, 240, | 1340 | | 36, 119, 252, 22, 37, 204, 144, 161, 54, 227, 139, | 1341 | | 217, 52, 151, 197, 182, 234, 99, 221, 119, 17, 230, | 1342 | | 124, 116, 41, 249, 86, 176, 251, 138, 143, 8, 154, | 1343 | | 220, 75, 105, 137, 60, 193, 51, 63, 83, 237, 208, 25, | 1344 | | 184, 119, 132, 37, 47, 236, 145, 79, 228, 133, 119, | 1345 | | 105, 89, 75, 234, 66, 128, 211, 44, 15, 85, 191, 98, | 1346 | | 148, 79, 19, 3, 150, 188, 110, 155, 223, 110, 189, | 1347 | | 210, 189, 163, 103, 142, 236, 160, 198, 104, 247, 1, | 1348 | | 179, 141, 191, 251, 56, 200, 52, 44, 226, 254, 109, | 1349 | | 39, 250, 222, 74, 90, 72, 116, 151, 157, 212, 185, | 1350 | | 207, 154, 222, 196, 199, 91, 5, 133, 44, 44, 15, 94, | 1351 | | 248, 165, 193, 117, 3, 146, 249, 68, 232, 237, 100, | 1352 | | 193, 16, 198, 182, 71, 96, 154, 164, 120, 58, 235, | 1353 | | 156, 108, 154, 215, 85, 49, 48, 80, 99, 139, 131, | 1354 | | 102, 92, 111, 111, 122, 130, 163, 150, 112, 42, 31, | 1355 | | 100, 27, 130, 211, 235, 242, 57, 34, 25, 73, 31, 182, | 1356 | | 134, 135, 44, 87, 22, 245, 10, 248, 53, 141, 154, | 1357 | | 139, 157, 23, 195, 64, 114, 143, 127, 135, 216, 154, | 1358 | | 24, 216, 252, 171, 103, 173, 132, 89, 12, 46, 207, | 1359 | | 117, 147, 57, 54, 60, 7, 3, 77, 111, 96, 111, 158, | 1360 | | 33, 224, 84, 86, 202, 229, 233, 161] | 1361 | Exponent | [1, 0, 1] | 1362 | Private | [18, 174, 113, 164, 105, 205, 10, 43, 195, 126, 82, | 1363 | Exponent | 108, 69, 0, 87, 31, 29, 97, 117, 29, 100, 233, 73, | 1364 | | 112, 123, 98, 89, 15, 157, 11, 165, 124, 150, 60, 64, | 1365 | | 30, 63, 207, 47, 44, 211, 189, 236, 136, 229, 3, 191, | 1366 | | 198, 67, 155, 11, 40, 200, 47, 125, 55, 151, 103, 31, | 1367 | | 82, 19, 238, 216, 193, 90, 37, 216, 213, 206, 160, 2, | 1368 | | 94, 227, 171, 46, 139, 127, 121, 33, 111, 198, 59, | 1369 | | 234, 86, 39, 83, 180, 6, 68, 198, 161, 81, 39, 217, | 1370 | | 178, 149, 69, 64, 160, 187, 225, 163, 5, 86, 152, 45, | 1371 | | 78, 159, 222, 95, 100, 37, 241, 77, 75, 113, 52, 65, | 1372 | | 181, 93, 199, 59, 155, 74, 237, 204, 146, 172, 227, | 1373 | | 146, 126, 55, 245, 125, 12, 253, 94, 117, 129, 250, | 1374 | | 81, 44, 143, 73, 97, 169, 235, 11, 128, 248, 168, 7, | 1375 | | 70, 114, 138, 85, 255, 70, 71, 31, 52, 37, 6, 59, | 1376 | | 157, 83, 100, 47, 94, 222, 30, 132, 214, 19, 8, 26, | 1377 | | 250, 92, 34, 208, 81, 40, 91, 214, 59, 148, 59, 86, | 1378 | | 93, 137, 138, 5, 104, 84, 19, 229, 60, 60, 108, 101, | 1379 | | 37, 255, 31, 227, 78, 61, 220, 112, 240, 213, 100, | 1380 | | 80, 253, 164, 139, 161, 46, 16, 78, 157, 235, 159, | 1381 | | 184, 24, 129, 225, 196, 189, 242, 93, 146, 71, 244, | 1382 | | 80, 200, 101, 146, 121, 104, 231, 115, 52, 244, 65, | 1383 | | 79, 117, 167, 80, 225, 57, 84, 110, 58, 138, 115, | 1384 | | 157] | 1385 +-----------+-------------------------------------------------------+ 1387 The RSA private key (Modulus, Private Exponent) is then passed to the 1388 RSA signing function, which also takes the hash type, SHA-256, and 1389 the octets of the ASCII representation of the JWS Signing Input as 1390 inputs. The result of the digital signature is an octet sequence, 1391 which represents a big endian integer. In this example, it is: 1393 [112, 46, 33, 137, 67, 232, 143, 209, 30, 181, 216, 45, 191, 120, 69, 1394 243, 65, 6, 174, 27, 129, 255, 247, 115, 17, 22, 173, 209, 113, 125, 1395 131, 101, 109, 66, 10, 253, 60, 150, 238, 221, 115, 162, 102, 62, 81, 1396 102, 104, 123, 0, 11, 135, 34, 110, 1, 135, 237, 16, 115, 249, 69, 1397 229, 130, 173, 252, 239, 22, 216, 90, 121, 142, 232, 198, 109, 219, 1398 61, 184, 151, 91, 23, 208, 148, 2, 190, 237, 213, 217, 217, 112, 7, 1399 16, 141, 178, 129, 96, 213, 248, 4, 12, 167, 68, 87, 98, 184, 31, 1400 190, 127, 249, 217, 46, 10, 231, 111, 36, 242, 91, 51, 187, 230, 244, 1401 74, 230, 30, 177, 4, 10, 203, 32, 4, 77, 62, 249, 18, 142, 212, 1, 1402 48, 121, 91, 212, 189, 59, 65, 238, 202, 208, 102, 171, 101, 25, 129, 1403 253, 228, 141, 247, 127, 55, 45, 195, 139, 159, 175, 221, 59, 239, 1404 177, 139, 93, 163, 204, 60, 46, 176, 47, 158, 58, 65, 214, 18, 202, 1405 173, 21, 145, 18, 115, 160, 95, 35, 185, 232, 56, 250, 175, 132, 157, 1406 105, 132, 41, 239, 90, 30, 136, 121, 130, 54, 195, 212, 14, 96, 69, 1407 34, 165, 68, 200, 242, 122, 122, 45, 184, 6, 99, 209, 108, 247, 202, 1408 234, 86, 222, 64, 92, 178, 33, 90, 69, 178, 194, 85, 102, 181, 90, 1409 193, 167, 72, 160, 112, 223, 200, 163, 42, 70, 149, 67, 208, 25, 238, 1410 251, 71] 1412 Base64url encoding the digital signature produces this value for the 1413 Encoded JWS Signature (with line breaks for display purposes only): 1415 cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7 1416 AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4 1417 BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K 1418 0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqv 1419 hJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrB 1420 p0igcN_IoypGlUPQGe77Rw 1422 Concatenating these values in the order Header.Payload.Signature with 1423 period ('.') characters between the parts yields this complete JWS 1424 representation using the JWS Compact Serialization (with line breaks 1425 for display purposes only): 1427 eyJhbGciOiJSUzI1NiJ9 1428 . 1429 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1430 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1431 . 1432 cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7 1433 AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4 1434 BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K 1435 0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqv 1436 hJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrB 1437 p0igcN_IoypGlUPQGe77Rw 1439 A.2.2. Decoding 1441 Decoding the JWS requires base64url decoding the Encoded JWS Header, 1442 Encoded JWS Payload, and Encoded JWS Signature to produce the JWS 1443 Header, JWS Payload, and JWS Signature octet sequences. The octet 1444 sequence containing the UTF-8 representation of the JWS Header is 1445 decoded into the JWS Header string. 1447 A.2.3. Validating 1449 Since the "alg" parameter in the header is "RS256", we validate the 1450 RSA SHA-256 digital signature contained in the JWS Signature. If any 1451 of the validation steps fail, the JWS MUST be rejected. 1453 First, we validate that the JWS Header string is legal JSON. 1455 Validating the JWS Signature is a little different from the previous 1456 example. First, we base64url decode the Encoded JWS Signature to 1457 produce a digital signature S to check. We then pass (n, e), S and 1458 the octets of the ASCII representation of the JWS Signing Input to an 1459 RSA signature verifier that has been configured to use the SHA-256 1460 hash function. 1462 A.3. Example JWS using ECDSA P-256 SHA-256 1464 A.3.1. Encoding 1466 The JWS Header for this example differs from the previous example 1467 because a different algorithm is being used. The JWS Header used is: 1469 {"alg":"ES256"} 1471 The following octet sequence contains the UTF-8 representation of the 1472 JWS Header: 1474 [123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 50, 53, 54, 34, 125] 1476 Base64url encoding these octets yields this Encoded JWS Header value: 1478 eyJhbGciOiJFUzI1NiJ9 1480 The JWS Payload used in this example, which follows, is the same as 1481 in the previous examples. Since the Encoded JWS Payload will 1482 therefore be the same, its computation is not repeated here. 1484 {"iss":"joe", 1485 "exp":1300819380, 1486 "http://example.com/is_root":true} 1488 Concatenating the Encoded JWS Header, a period ('.') character, and 1489 the Encoded JWS Payload yields this JWS Signing Input value (with 1490 line breaks for display purposes only): 1492 eyJhbGciOiJFUzI1NiJ9 1493 . 1494 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1495 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1497 The ASCII representation of the JWS Signing Input is the following 1498 octet sequence: 1500 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 70, 85, 122, 73, 1501 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, 1502 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 74, 108, 101, 72, 1503 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 107, 122, 79, 68, 1504 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 72, 65, 54, 76, 1505 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 109, 78, 118, 1506 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48, 1507 99, 110, 86, 108, 102, 81] 1509 The ECDSA key consists of a public part, the EC point (x, y), and a 1510 private part d. The values of the ECDSA key used in this example, 1511 presented as the octet sequences representing three 256 bit big 1512 endian integers are: 1514 +-----------+-------------------------------------------------------+ 1515 | Parameter | Value | 1516 | Name | | 1517 +-----------+-------------------------------------------------------+ 1518 | x | [127, 205, 206, 39, 112, 246, 196, 93, 65, 131, 203, | 1519 | | 238, 111, 219, 75, 123, 88, 7, 51, 53, 123, 233, 239, | 1520 | | 19, 186, 207, 110, 60, 123, 209, 84, 69] | 1521 | y | [199, 241, 68, 205, 27, 189, 155, 126, 135, 44, 223, | 1522 | | 237, 185, 238, 185, 244, 179, 105, 93, 110, 169, 11, | 1523 | | 36, 173, 138, 70, 35, 40, 133, 136, 229, 173] | 1524 | d | [142, 155, 16, 158, 113, 144, 152, 191, 152, 4, 135, | 1525 | | 223, 31, 93, 119, 233, 203, 41, 96, 110, 190, 210, | 1526 | | 38, 59, 95, 87, 194, 19, 223, 132, 244, 178] | 1527 +-----------+-------------------------------------------------------+ 1529 The ECDSA private part d is then passed to an ECDSA signing function, 1530 which also takes the curve type, P-256, the hash type, SHA-256, and 1531 the octets of the ASCII representation of the JWS Signing Input as 1532 inputs. The result of the digital signature is the EC point (R, S), 1533 where R and S are unsigned integers. In this example, the R and S 1534 values, given as octet sequences representing big endian integers 1535 are: 1537 +--------+----------------------------------------------------------+ 1538 | Result | Value | 1539 | Name | | 1540 +--------+----------------------------------------------------------+ 1541 | R | [14, 209, 33, 83, 121, 99, 108, 72, 60, 47, 127, 21, 88, | 1542 | | 7, 212, 2, 163, 178, 40, 3, 58, 249, 124, 126, 23, 129, | 1543 | | 154, 195, 22, 158, 166, 101] | 1544 | S | [197, 10, 7, 211, 140, 60, 112, 229, 216, 241, 45, 175, | 1545 | | 8, 74, 84, 128, 166, 101, 144, 197, 242, 147, 80, 154, | 1546 | | 143, 63, 127, 138, 131, 163, 84, 213] | 1547 +--------+----------------------------------------------------------+ 1549 Concatenating the S array to the end of the R array and base64url 1550 encoding the result produces this value for the Encoded JWS Signature 1551 (with line breaks for display purposes only): 1553 DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSA 1554 pmWQxfKTUJqPP3-Kg6NU1Q 1556 Concatenating these values in the order Header.Payload.Signature with 1557 period ('.') characters between the parts yields this complete JWS 1558 representation using the JWS Compact Serialization (with line breaks 1559 for display purposes only): 1561 eyJhbGciOiJFUzI1NiJ9 1562 . 1563 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1564 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1565 . 1566 DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSA 1567 pmWQxfKTUJqPP3-Kg6NU1Q 1569 A.3.2. Decoding 1571 Decoding the JWS requires base64url decoding the Encoded JWS Header, 1572 Encoded JWS Payload, and Encoded JWS Signature to produce the JWS 1573 Header, JWS Payload, and JWS Signature octet sequences. The octet 1574 sequence containing the UTF-8 representation of the JWS Header is 1575 decoded into the JWS Header string. 1577 A.3.3. Validating 1579 Since the "alg" parameter in the header is "ES256", we validate the 1580 ECDSA P-256 SHA-256 digital signature contained in the JWS Signature. 1581 If any of the validation steps fail, the JWS MUST be rejected. 1583 First, we validate that the JWS Header string is legal JSON. 1585 Validating the JWS Signature is a little different from the first 1586 example. First, we base64url decode the Encoded JWS Signature as in 1587 the previous examples but we then need to split the 64 member octet 1588 sequence that must result into two 32 octet sequences, the first R 1589 and the second S. We then pass (x, y), (R, S) and the octets of the 1590 ASCII representation of the JWS Signing Input to an ECDSA signature 1591 verifier that has been configured to use the P-256 curve with the 1592 SHA-256 hash function. 1594 As explained in Section 3.4 of the JSON Web Algorithms (JWA) [JWA] 1595 specification, the use of the K value in ECDSA means that we cannot 1596 validate the correctness of the digital signature in the same way we 1597 validated the correctness of the HMAC. Instead, implementations MUST 1598 use an ECDSA validator to validate the digital signature. 1600 A.4. Example JWS using ECDSA P-521 SHA-512 1602 A.4.1. Encoding 1604 The JWS Header for this example differs from the previous example 1605 because a different ECDSA curve and hash function are used. The JWS 1606 Header used is: 1608 {"alg":"ES512"} 1610 The following octet sequence contains the UTF-8 representation of the 1611 JWS Header: 1613 [123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 53, 49, 50, 34, 125] 1615 Base64url encoding these octets yields this Encoded JWS Header value: 1617 eyJhbGciOiJFUzUxMiJ9 1619 The JWS Payload used in this example, is the ASCII string "Payload". 1620 The representation of this string is the octet sequence: 1622 [80, 97, 121, 108, 111, 97, 100] 1624 Base64url encoding these octets yields the Encoded JWS Payload value: 1626 UGF5bG9hZA 1628 Concatenating the Encoded JWS Header, a period ('.') character, and 1629 the Encoded JWS Payload yields this JWS Signing Input value: 1631 eyJhbGciOiJFUzUxMiJ9.UGF5bG9hZA 1633 The ASCII representation of the JWS Signing Input is the following 1634 octet sequence: 1636 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 70, 85, 122, 85, 1637 120, 77, 105, 74, 57, 46, 85, 71, 70, 53, 98, 71, 57, 104, 90, 65] 1639 The ECDSA key consists of a public part, the EC point (x, y), and a 1640 private part d. The values of the ECDSA key used in this example, 1641 presented as the octet sequences representing three 521 bit big 1642 endian integers are: 1644 +-----------+-------------------------------------------------------+ 1645 | Parameter | Value | 1646 | Name | | 1647 +-----------+-------------------------------------------------------+ 1648 | x | [1, 233, 41, 5, 15, 18, 79, 198, 188, 85, 199, 213, | 1649 | | 57, 51, 101, 223, 157, 239, 74, 176, 194, 44, 178, | 1650 | | 87, 152, 249, 52, 235, 4, 227, 198, 186, 227, 112, | 1651 | | 26, 87, 167, 145, 14, 157, 129, 191, 54, 49, 89, 232, | 1652 | | 235, 203, 21, 93, 99, 73, 244, 189, 182, 204, 248, | 1653 | | 169, 76, 92, 89, 199, 170, 193, 1, 164] | 1654 | y | [0, 52, 166, 68, 14, 55, 103, 80, 210, 55, 31, 209, | 1655 | | 189, 194, 200, 243, 183, 29, 47, 78, 229, 234, 52, | 1656 | | 50, 200, 21, 204, 163, 21, 96, 254, 93, 147, 135, | 1657 | | 236, 119, 75, 85, 131, 134, 48, 229, 203, 191, 90, | 1658 | | 140, 190, 10, 145, 221, 0, 100, 198, 153, 154, 31, | 1659 | | 110, 110, 103, 250, 221, 237, 228, 200, 200, 246] | 1660 | d | [1, 142, 105, 111, 176, 52, 80, 88, 129, 221, 17, 11, | 1661 | | 72, 62, 184, 125, 50, 206, 73, 95, 227, 107, 55, 69, | 1662 | | 237, 242, 216, 202, 228, 240, 242, 83, 159, 70, 21, | 1663 | | 160, 233, 142, 171, 82, 179, 192, 197, 234, 196, 206, | 1664 | | 7, 81, 133, 168, 231, 187, 71, 222, 172, 29, 29, 231, | 1665 | | 123, 204, 246, 97, 53, 230, 61, 130] | 1666 +-----------+-------------------------------------------------------+ 1668 The ECDSA private part d is then passed to an ECDSA signing function, 1669 which also takes the curve type, P-521, the hash type, SHA-512, and 1670 the octets of the ASCII representation of the JWS Signing Input as 1671 inputs. The result of the digital signature is the EC point (R, S), 1672 where R and S are unsigned integers. In this example, the R and S 1673 values, given as octet sequences representing big endian integers 1674 are: 1676 +--------+----------------------------------------------------------+ 1677 | Result | Value | 1678 | Name | | 1679 +--------+----------------------------------------------------------+ 1680 | R | [1, 220, 12, 129, 231, 171, 194, 209, 232, 135, 233, | 1681 | | 117, 247, 105, 122, 210, 26, 125, 192, 1, 217, 21, 82, | 1682 | | 91, 45, 240, 255, 83, 19, 34, 239, 71, 48, 157, 147, | 1683 | | 152, 105, 18, 53, 108, 163, 214, 68, 231, 62, 153, 150, | 1684 | | 106, 194, 164, 246, 72, 143, 138, 24, 50, 129, 223, 133, | 1685 | | 206, 209, 172, 63, 237, 119, 109] | 1686 | S | [0, 111, 6, 105, 44, 5, 41, 208, 128, 61, 152, 40, 92, | 1687 | | 61, 152, 4, 150, 66, 60, 69, 247, 196, 170, 81, 193, | 1688 | | 199, 78, 59, 194, 169, 16, 124, 9, 143, 42, 142, 131, | 1689 | | 48, 206, 238, 34, 175, 83, 203, 220, 159, 3, 107, 155, | 1690 | | 22, 27, 73, 111, 68, 68, 21, 238, 144, 229, 232, 148, | 1691 | | 188, 222, 59, 242, 103] | 1692 +--------+----------------------------------------------------------+ 1694 Concatenating the S array to the end of the R array and base64url 1695 encoding the result produces this value for the Encoded JWS Signature 1696 (with line breaks for display purposes only): 1698 AdwMgeerwtHoh-l192l60hp9wAHZFVJbLfD_UxMi70cwnZOYaRI1bKPWROc-mZZq 1699 wqT2SI-KGDKB34XO0aw_7XdtAG8GaSwFKdCAPZgoXD2YBJZCPEX3xKpRwcdOO8Kp 1700 EHwJjyqOgzDO7iKvU8vcnwNrmxYbSW9ERBXukOXolLzeO_Jn 1702 Concatenating these values in the order Header.Payload.Signature with 1703 period ('.') characters between the parts yields this complete JWS 1704 representation using the JWS Compact Serialization (with line breaks 1705 for display purposes only): 1707 eyJhbGciOiJFUzUxMiJ9 1708 . 1709 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1710 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1711 . 1712 AdwMgeerwtHoh-l192l60hp9wAHZFVJbLfD_UxMi70cwnZOYaRI1bKPWROc-mZZq 1713 wqT2SI-KGDKB34XO0aw_7XdtAG8GaSwFKdCAPZgoXD2YBJZCPEX3xKpRwcdOO8Kp 1714 EHwJjyqOgzDO7iKvU8vcnwNrmxYbSW9ERBXukOXolLzeO_Jn 1716 A.4.2. Decoding 1718 Decoding the JWS requires base64url decoding the Encoded JWS Header, 1719 Encoded JWS Payload, and Encoded JWS Signature to produce the JWS 1720 Header, JWS Payload, and JWS Signature octet sequences. The octet 1721 sequence containing the UTF-8 representation of the JWS Header is 1722 decoded into the JWS Header string. 1724 A.4.3. Validating 1726 Since the "alg" parameter in the header is "ES512", we validate the 1727 ECDSA P-521 SHA-512 digital signature contained in the JWS Signature. 1728 If any of the validation steps fail, the JWS MUST be rejected. 1730 First, we validate that the JWS Header string is legal JSON. 1732 Validating the JWS Signature is similar to the previous example. 1733 First, we base64url decode the Encoded JWS Signature as in the 1734 previous examples but we then need to split the 132 member octet 1735 sequence that must result into two 66 octet sequences, the first R 1736 and the second S. We then pass (x, y), (R, S) and the octets of the 1737 ASCII representation of the JWS Signing Input to an ECDSA signature 1738 verifier that has been configured to use the P-521 curve with the 1739 SHA-512 hash function. 1741 As explained in Section 3.4 of the JSON Web Algorithms (JWA) [JWA] 1742 specification, the use of the K value in ECDSA means that we cannot 1743 validate the correctness of the digital signature in the same way we 1744 validated the correctness of the HMAC. Instead, implementations MUST 1745 use an ECDSA validator to validate the digital signature. 1747 A.5. Example Plaintext JWS 1749 The following example JWS Header declares that the encoded object is 1750 a Plaintext JWS: 1752 {"alg":"none"} 1754 Base64url encoding the octets of the UTF-8 representation of the JWS 1755 Header yields this Encoded JWS Header: 1757 eyJhbGciOiJub25lIn0 1759 The JWS Payload used in this example, which follows, is the same as 1760 in the previous examples. Since the Encoded JWS Payload will 1761 therefore be the same, its computation is not repeated here. 1763 {"iss":"joe", 1764 "exp":1300819380, 1765 "http://example.com/is_root":true} 1767 The Encoded JWS Signature is the empty string. 1769 Concatenating these parts in the order Header.Payload.Signature with 1770 period ('.') characters between the parts yields this complete JWS 1771 (with line breaks for display purposes only): 1773 eyJhbGciOiJub25lIn0 1774 . 1775 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1776 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1777 . 1779 Appendix B. "x5c" (X.509 Certificate Chain) Example 1781 The JSON array below is an example of a certificate chain that could 1782 be used as the value of an "x5c" (X.509 Certificate Chain) header 1783 parameter, per Section 4.1.6. Note that since these strings contain 1784 base64 encoded (not base64url encoded) values, they are allowed to 1785 contain white space and line breaks. 1787 ["MIIE3jCCA8agAwIBAgICAwEwDQYJKoZIhvcNAQEFBQAwYzELMAkGA1UEBhMCVVM 1788 xITAfBgNVBAoTGFRoZSBHbyBEYWRkeSBHcm91cCwgSW5jLjExMC8GA1UECxMoR2 1789 8gRGFkZHkgQ2xhc3MgMiBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTAeFw0wNjExM 1790 TYwMTU0MzdaFw0yNjExMTYwMTU0MzdaMIHKMQswCQYDVQQGEwJVUzEQMA4GA1UE 1791 CBMHQXJpem9uYTETMBEGA1UEBxMKU2NvdHRzZGFsZTEaMBgGA1UEChMRR29EYWR 1792 keS5jb20sIEluYy4xMzAxBgNVBAsTKmh0dHA6Ly9jZXJ0aWZpY2F0ZXMuZ29kYW 1793 RkeS5jb20vcmVwb3NpdG9yeTEwMC4GA1UEAxMnR28gRGFkZHkgU2VjdXJlIENlc 1794 nRpZmljYXRpb24gQXV0aG9yaXR5MREwDwYDVQQFEwgwNzk2OTI4NzCCASIwDQYJ 1795 KoZIhvcNAQEBBQADggEPADCCAQoCggEBAMQt1RWMnCZM7DI161+4WQFapmGBWTt 1796 wY6vj3D3HKrjJM9N55DrtPDAjhI6zMBS2sofDPZVUBJ7fmd0LJR4h3mUpfjWoqV 1797 Tr9vcyOdQmVZWt7/v+WIbXnvQAjYwqDL1CBM6nPwT27oDyqu9SoWlm2r4arV3aL 1798 GbqGmu75RpRSgAvSMeYddi5Kcju+GZtCpyz8/x4fKL4o/K1w/O5epHBp+YlLpyo 1799 7RJlbmr2EkRTcDCVw5wrWCs9CHRK8r5RsL+H0EwnWGu1NcWdrxcx+AuP7q2BNgW 1800 JCJjPOq8lh8BJ6qf9Z/dFjpfMFDniNoW1fho3/Rb2cRGadDAW/hOUoz+EDU8CAw 1801 EAAaOCATIwggEuMB0GA1UdDgQWBBT9rGEyk2xF1uLuhV+auud2mWjM5zAfBgNVH 1802 SMEGDAWgBTSxLDSkdRMEXGzYcs9of7dqGrU4zASBgNVHRMBAf8ECDAGAQH/AgEA 1803 MDMGCCsGAQUFBwEBBCcwJTAjBggrBgEFBQcwAYYXaHR0cDovL29jc3AuZ29kYWR 1804 keS5jb20wRgYDVR0fBD8wPTA7oDmgN4Y1aHR0cDovL2NlcnRpZmljYXRlcy5nb2 1805 RhZGR5LmNvbS9yZXBvc2l0b3J5L2dkcm9vdC5jcmwwSwYDVR0gBEQwQjBABgRVH 1806 SAAMDgwNgYIKwYBBQUHAgEWKmh0dHA6Ly9jZXJ0aWZpY2F0ZXMuZ29kYWRkeS5j 1807 b20vcmVwb3NpdG9yeTAOBgNVHQ8BAf8EBAMCAQYwDQYJKoZIhvcNAQEFBQADggE 1808 BANKGwOy9+aG2Z+5mC6IGOgRQjhVyrEp0lVPLN8tESe8HkGsz2ZbwlFalEzAFPI 1809 UyIXvJxwqoJKSQ3kbTJSMUA2fCENZvD117esyfxVgqwcSeIaha86ykRvOe5GPLL 1810 5CkKSkB2XIsKd83ASe8T+5o0yGPwLPk9Qnt0hCqU7S+8MxZC9Y7lhyVJEnfzuz9 1811 p0iRFEUOOjZv2kWzRaJBydTXRE4+uXR21aITVSzGh6O1mawGhId/dQb8vxRMDsx 1812 uxN89txJx9OjxUUAiKEngHUuHqDTMBqLdElrRhjZkAzVvb3du6/KFUJheqwNTrZ 1813 EjYx8WnM25sgVjOuH0aBsXBTWVU+4=", 1814 "MIIE+zCCBGSgAwIBAgICAQ0wDQYJKoZIhvcNAQEFBQAwgbsxJDAiBgNVBAcTG1Z 1815 hbGlDZXJ0IFZhbGlkYXRpb24gTmV0d29yazEXMBUGA1UEChMOVmFsaUNlcnQsIE 1816 luYy4xNTAzBgNVBAsTLFZhbGlDZXJ0IENsYXNzIDIgUG9saWN5IFZhbGlkYXRpb 1817 24gQXV0aG9yaXR5MSEwHwYDVQQDExhodHRwOi8vd3d3LnZhbGljZXJ0LmNvbS8x 1818 IDAeBgkqhkiG9w0BCQEWEWluZm9AdmFsaWNlcnQuY29tMB4XDTA0MDYyOTE3MDY 1819 yMFoXDTI0MDYyOTE3MDYyMFowYzELMAkGA1UEBhMCVVMxITAfBgNVBAoTGFRoZS 1820 BHbyBEYWRkeSBHcm91cCwgSW5jLjExMC8GA1UECxMoR28gRGFkZHkgQ2xhc3MgM 1821 iBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTCCASAwDQYJKoZIhvcNAQEBBQADggEN 1822 ADCCAQgCggEBAN6d1+pXGEmhW+vXX0iG6r7d/+TvZxz0ZWizV3GgXne77ZtJ6XC 1823 APVYYYwhv2vLM0D9/AlQiVBDYsoHUwHU9S3/Hd8M+eKsaA7Ugay9qK7HFiH7Eux 1824 6wwdhFJ2+qN1j3hybX2C32qRe3H3I2TqYXP2WYktsqbl2i/ojgC95/5Y0V4evLO 1825 tXiEqITLdiOr18SPaAIBQi2XKVlOARFmR6jYGB0xUGlcmIbYsUfb18aQr4CUWWo 1826 riMYavx4A6lNf4DD+qta/KFApMoZFv6yyO9ecw3ud72a9nmYvLEHZ6IVDd2gWMZ 1827 Eewo+YihfukEHU1jPEX44dMX4/7VpkI+EdOqXG68CAQOjggHhMIIB3TAdBgNVHQ 1828 4EFgQU0sSw0pHUTBFxs2HLPaH+3ahq1OMwgdIGA1UdIwSByjCBx6GBwaSBvjCBu 1829 zEkMCIGA1UEBxMbVmFsaUNlcnQgVmFsaWRhdGlvbiBOZXR3b3JrMRcwFQYDVQQK 1830 Ew5WYWxpQ2VydCwgSW5jLjE1MDMGA1UECxMsVmFsaUNlcnQgQ2xhc3MgMiBQb2x 1831 pY3kgVmFsaWRhdGlvbiBBdXRob3JpdHkxITAfBgNVBAMTGGh0dHA6Ly93d3cudm 1832 FsaWNlcnQuY29tLzEgMB4GCSqGSIb3DQEJARYRaW5mb0B2YWxpY2VydC5jb22CA 1833 QEwDwYDVR0TAQH/BAUwAwEB/zAzBggrBgEFBQcBAQQnMCUwIwYIKwYBBQUHMAGG 1834 F2h0dHA6Ly9vY3NwLmdvZGFkZHkuY29tMEQGA1UdHwQ9MDswOaA3oDWGM2h0dHA 1835 6Ly9jZXJ0aWZpY2F0ZXMuZ29kYWRkeS5jb20vcmVwb3NpdG9yeS9yb290LmNybD 1836 BLBgNVHSAERDBCMEAGBFUdIAAwODA2BggrBgEFBQcCARYqaHR0cDovL2NlcnRpZ 1837 mljYXRlcy5nb2RhZGR5LmNvbS9yZXBvc2l0b3J5MA4GA1UdDwEB/wQEAwIBBjAN 1838 BgkqhkiG9w0BAQUFAAOBgQC1QPmnHfbq/qQaQlpE9xXUhUaJwL6e4+PrxeNYiY+ 1839 Sn1eocSxI0YGyeR+sBjUZsE4OWBsUs5iB0QQeyAfJg594RAoYC5jcdnplDQ1tgM 1840 QLARzLrUc+cb53S8wGd9D0VmsfSxOaFIqII6hR8INMqzW/Rn453HWkrugp++85j 1841 09VZw==", 1842 "MIIC5zCCAlACAQEwDQYJKoZIhvcNAQEFBQAwgbsxJDAiBgNVBAcTG1ZhbGlDZXJ 1843 0IFZhbGlkYXRpb24gTmV0d29yazEXMBUGA1UEChMOVmFsaUNlcnQsIEluYy4xNT 1844 AzBgNVBAsTLFZhbGlDZXJ0IENsYXNzIDIgUG9saWN5IFZhbGlkYXRpb24gQXV0a 1845 G9yaXR5MSEwHwYDVQQDExhodHRwOi8vd3d3LnZhbGljZXJ0LmNvbS8xIDAeBgkq 1846 hkiG9w0BCQEWEWluZm9AdmFsaWNlcnQuY29tMB4XDTk5MDYyNjAwMTk1NFoXDTE 1847 5MDYyNjAwMTk1NFowgbsxJDAiBgNVBAcTG1ZhbGlDZXJ0IFZhbGlkYXRpb24gTm 1848 V0d29yazEXMBUGA1UEChMOVmFsaUNlcnQsIEluYy4xNTAzBgNVBAsTLFZhbGlDZ 1849 XJ0IENsYXNzIDIgUG9saWN5IFZhbGlkYXRpb24gQXV0aG9yaXR5MSEwHwYDVQQD 1850 ExhodHRwOi8vd3d3LnZhbGljZXJ0LmNvbS8xIDAeBgkqhkiG9w0BCQEWEWluZm9 1851 AdmFsaWNlcnQuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDOOnHK5a 1852 vIWZJV16vYdA757tn2VUdZZUcOBVXc65g2PFxTXdMwzzjsvUGJ7SVCCSRrCl6zf 1853 N1SLUzm1NZ9WlmpZdRJEy0kTRxQb7XBhVQ7/nHk01xC+YDgkRoKWzk2Z/M/VXwb 1854 P7RfZHM047QSv4dk+NoS/zcnwbNDu+97bi5p9wIDAQABMA0GCSqGSIb3DQEBBQU 1855 AA4GBADt/UG9vUJSZSWI4OB9L+KXIPqeCgfYrx+jFzug6EILLGACOTb2oWH+heQ 1856 C1u+mNr0HZDzTuIYEZoDJJKPTEjlbVUjP9UNV+mWwD5MlM/Mtsq2azSiGM5bUMM 1857 j4QssxsodyamEwCW/POuZ6lcg5Ktz885hZo+L7tdEy8W9ViH0Pd"] 1859 Appendix C. Notes on implementing base64url encoding without padding 1861 This appendix describes how to implement base64url encoding and 1862 decoding functions without padding based upon standard base64 1863 encoding and decoding functions that do use padding. 1865 To be concrete, example C# code implementing these functions is shown 1866 below. Similar code could be used in other languages. 1868 static string base64urlencode(byte [] arg) 1869 { 1870 string s = Convert.ToBase64String(arg); // Regular base64 encoder 1871 s = s.Split('=')[0]; // Remove any trailing '='s 1872 s = s.Replace('+', '-'); // 62nd char of encoding 1873 s = s.Replace('/', '_'); // 63rd char of encoding 1874 return s; 1875 } 1877 static byte [] base64urldecode(string arg) 1878 { 1879 string s = arg; 1880 s = s.Replace('-', '+'); // 62nd char of encoding 1881 s = s.Replace('_', '/'); // 63rd char of encoding 1882 switch (s.Length % 4) // Pad with trailing '='s 1883 { 1884 case 0: break; // No pad chars in this case 1885 case 2: s += "=="; break; // Two pad chars 1886 case 3: s += "="; break; // One pad char 1887 default: throw new System.Exception( 1888 "Illegal base64url string!"); 1889 } 1890 return Convert.FromBase64String(s); // Standard base64 decoder 1891 } 1893 As per the example code above, the number of '=' padding characters 1894 that needs to be added to the end of a base64url encoded string 1895 without padding to turn it into one with padding is a deterministic 1896 function of the length of the encoded string. Specifically, if the 1897 length mod 4 is 0, no padding is added; if the length mod 4 is 2, two 1898 '=' padding characters are added; if the length mod 4 is 3, one '=' 1899 padding character is added; if the length mod 4 is 1, the input is 1900 malformed. 1902 An example correspondence between unencoded and encoded values 1903 follows. The octet sequence below encodes into the string below, 1904 which when decoded, reproduces the octet sequence. 1905 3 236 255 224 193 1906 A-z_4ME 1908 Appendix D. Possible Compact Serialization for Multiple Signatures 1910 Appendix C of [JWE] suggests a possible compact serialization for 1911 JWEs with multiple recipients. This suggests a corresponding compact 1912 serialization for JWSs with multiple digital signatures and/or MACs. 1913 This possible compact serialization concatenates instances of the 1914 per-signature/MAC fields, separating them with tilde ('~') 1915 characters, which are URL-safe. 1917 The concatenation of the Encoded JWS Header values goes before the 1918 first period ('.') character in the compact serialization. The 1919 concatenation of the corresponding Encoded JWS Signature values goes 1920 after the second period ('.') character in the compact serialization. 1922 A complete compact serialization of the multi-signature/MAC JWS in 1923 Section 7.1 (with line breaks for display purposes only) would be: 1925 eyJhbGciOiJSUzI1NiJ9 1926 ~ 1927 eyJhbGciOiJFUzI1NiJ9 1928 . 1929 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGF 1930 tcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1931 . 1932 cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZ 1933 mh7AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjb 1934 KBYNX4BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHl 1935 b1L07Qe7K0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZES 1936 c6BfI7noOPqvhJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AX 1937 LIhWkWywlVmtVrBp0igcN_IoypGlUPQGe77Rw 1938 ~ 1939 DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8IS 1940 lSApmWQxfKTUJqPP3-Kg6NU1Q 1942 This representation is suggested for those who may desire or require 1943 a compact, URL-safe serialization of JWSs with multiple digital 1944 signatures and/or MACs. It is a suggestion to implementers for whom 1945 this functionality would be valuable, and not a normative part of 1946 this specification. 1948 Appendix E. Acknowledgements 1950 Solutions for signing JSON content were previously explored by Magic 1951 Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas 1952 Applications [CanvasApp], all of which influenced this draft. 1954 Thanks to Axel Nennker for his early implementation and feedback on 1955 the JWS and JWE specifications. 1957 This specification is the work of the JOSE Working Group, which 1958 includes dozens of active and dedicated participants. In particular, 1959 the following individuals contributed ideas, feedback, and wording 1960 that influenced this specification: 1962 Dirk Balfanz, Richard Barnes, Brian Campbell, Breno de Medeiros, Dick 1963 Hardt, Joe Hildebrand, Jeff Hodges, Edmund Jay, Yaron Y. Goland, Ben 1964 Laurie, James Manger, Tony Nadalin, Axel Nennker, John Panzer, 1965 Emmanuel Raviart, Eric Rescorla, Jim Schaad, Paul Tarjan, Hannes 1966 Tschofenig, and Sean Turner. 1968 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 1969 Sean Turner and Stephen Farrell served as Security area directors 1970 during the creation of this specification. 1972 Appendix F. Document History 1974 [[ to be removed by the RFC editor before publication as an RFC ]] 1976 -10 1978 o Added an appendix suggesting a possible compact serialization for 1979 JWSs with multiple digital signatures and/or MACs. 1981 -09 1983 o Added JWS JSON Serialization, as specified by 1984 draft-jones-jose-jws-json-serialization-04. 1986 o Registered "application/jws-js" MIME type and "JWS-JS" typ header 1987 parameter value. 1989 o Defined that the default action for header parameters that are not 1990 understood is to ignore them unless specifically designated as 1991 "MUST be understood" or included in the new "crit" (critical) 1992 header parameter list. This addressed issue #6. 1994 o Changed term "JWS Secured Input" to "JWS Signing Input". 1996 o Changed from using the term "byte" to "octet" when referring to 8 1997 bit values. 1999 o Changed member name from "recipients" to "signatures" in the JWS 2000 JSON Serialization. 2002 o Added complete values using the JWS Compact Serialization for all 2003 examples. 2005 -08 2007 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2008 Tschofenig. Many of these simplified the terminology used. 2010 o Clarified statements of the form "This header parameter is 2011 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2013 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2014 Web Signature and Encryption Header Parameters registry. 2016 o Added seriesInfo information to Internet Draft references. 2018 -07 2020 o Updated references. 2022 -06 2024 o Changed "x5c" (X.509 Certificate Chain) representation from being 2025 a single string to being an array of strings, each containing a 2026 single base64 encoded DER certificate value, representing elements 2027 of the certificate chain. 2029 o Applied changes made by the RFC Editor to RFC 6749's registry 2030 language to this specification. 2032 -05 2034 o Added statement that "StringOrURI values are compared as case- 2035 sensitive strings with no transformations or canonicalizations 2036 applied". 2038 o Indented artwork elements to better distinguish them from the body 2039 text. 2041 -04 2043 o Completed JSON Security Considerations section, including 2044 considerations about rejecting input with duplicate member names. 2046 o Completed security considerations on the use of a SHA-1 hash when 2047 computing "x5t" (x.509 certificate thumbprint) values. 2049 o Refer to the registries as the primary sources of defined values 2050 and then secondarily reference the sections defining the initial 2051 contents of the registries. 2053 o Normatively reference XML DSIG 2.0 [W3C.CR-xmldsig-core2-20120124] 2054 for its security considerations. 2056 o Added this language to Registration Templates: "This name is case 2057 sensitive. Names that match other registered names in a case 2058 insensitive manner SHOULD NOT be accepted." 2060 o Reference draft-jones-jose-jws-json-serialization instead of 2061 draft-jones-json-web-signature-json-serialization. 2063 o Described additional open issues. 2065 o Applied editorial suggestions. 2067 -03 2069 o Added the "cty" (content type) header parameter for declaring type 2070 information about the secured content, as opposed to the "typ" 2071 (type) header parameter, which declares type information about 2072 this object. 2074 o Added "Collision Resistant Namespace" to the terminology section. 2076 o Reference ITU.X690.1994 for DER encoding. 2078 o Added an example JWS using ECDSA P-521 SHA-512. This has 2079 particular illustrative value because of the use of the 521 bit 2080 integers in the key and signature values. This is also an example 2081 in which the payload is not a base64url encoded JSON object. 2083 o Added an example "x5c" value. 2085 o No longer say "the UTF-8 representation of the JWS Secured Input 2086 (which is the same as the ASCII representation)". Just call it 2087 "the ASCII representation of the JWS Secured Input". 2089 o Added Registration Template sections for defined registries. 2091 o Added Registry Contents sections to populate registry values. 2093 o Changed name of the JSON Web Signature and Encryption "typ" Values 2094 registry to be the JSON Web Signature and Encryption Type Values 2095 registry, since it is used for more than just values of the "typ" 2096 parameter. 2098 o Moved registries JSON Web Signature and Encryption Header 2099 Parameters and JSON Web Signature and Encryption Type Values to 2100 the JWS specification. 2102 o Numerous editorial improvements. 2104 -02 2105 o Clarified that it is an error when a "kid" value is included and 2106 no matching key is found. 2108 o Removed assumption that "kid" (key ID) can only refer to an 2109 asymmetric key. 2111 o Clarified that JWSs with duplicate Header Parameter Names MUST be 2112 rejected. 2114 o Clarified the relationship between "typ" header parameter values 2115 and MIME types. 2117 o Registered application/jws MIME type and "JWS" typ header 2118 parameter value. 2120 o Simplified JWK terminology to get replace the "JWK Key Object" and 2121 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2122 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2123 between single keys and sets of keys. As part of this change, the 2124 Header Parameter Name for a public key value was changed from 2125 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2127 o Added suggestion on defining additional header parameters such as 2128 "x5t#S256" in the future for certificate thumbprints using hash 2129 algorithms other than SHA-1. 2131 o Specify RFC 2818 server identity validation, rather than RFC 6125 2132 (paralleling the same decision in the OAuth specs). 2134 o Generalized language to refer to Message Authentication Codes 2135 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2136 unless in a context specific to HMAC algorithms. 2138 o Reformatted to give each header parameter its own section heading. 2140 -01 2142 o Moved definition of Plaintext JWSs (using "alg":"none") here from 2143 the JWT specification since this functionality is likely to be 2144 useful in more contexts that just for JWTs. 2146 o Added "jpk" and "x5c" header parameters for including JWK public 2147 keys and X.509 certificate chains directly in the header. 2149 o Clarified that this specification is defining the JWS Compact 2150 Serialization. Referenced the new JWS-JS spec, which defines the 2151 JWS JSON Serialization. 2153 o Added text "New header parameters should be introduced sparingly 2154 since an implementation that does not understand a parameter MUST 2155 reject the JWS". 2157 o Clarified that the order of the creation and validation steps is 2158 not significant in cases where there are no dependencies between 2159 the inputs and outputs of the steps. 2161 o Changed "no canonicalization is performed" to "no canonicalization 2162 need be performed". 2164 o Corrected the Magic Signatures reference. 2166 o Made other editorial improvements suggested by JOSE working group 2167 participants. 2169 -00 2171 o Created the initial IETF draft based upon 2172 draft-jones-json-web-signature-04 with no normative changes. 2174 o Changed terminology to no longer call both digital signatures and 2175 HMACs "signatures". 2177 Authors' Addresses 2179 Michael B. Jones 2180 Microsoft 2182 Email: mbj@microsoft.com 2183 URI: http://self-issued.info/ 2185 John Bradley 2186 Ping Identity 2188 Email: ve7jtb@ve7jtb.com 2190 Nat Sakimura 2191 Nomura Research Institute 2193 Email: n-sakimura@nri.co.jp