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