idnits 2.17.1 draft-ietf-jose-json-web-signature-00.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 (January 16, 2012) is 4484 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 948 -- Looks like a reference, but probably isn't: '34' on line 948 -- Looks like a reference, but probably isn't: '97' on line 948 -- Looks like a reference, but probably isn't: '108' on line 948 -- Looks like a reference, but probably isn't: '103' on line 948 -- Looks like a reference, but probably isn't: '58' on line 948 -- Looks like a reference, but probably isn't: '82' on line 783 -- Looks like a reference, but probably isn't: '83' on line 948 -- Looks like a reference, but probably isn't: '50' on line 948 -- Looks like a reference, but probably isn't: '53' on line 948 -- Looks like a reference, but probably isn't: '54' on line 948 -- Looks like a reference, but probably isn't: '125' on line 948 -- Looks like a reference, but probably isn't: '1' on line 848 -- Looks like a reference, but probably isn't: '0' on line 1065 -- Looks like a reference, but probably isn't: '69' on line 948 -- Possible downref: Non-RFC (?) normative reference: ref. 'JWA' -- Possible downref: Non-RFC (?) normative reference: ref. 'JWK' ** Downref: Normative reference to an Historic RFC: RFC 1421 ** Obsolete normative reference: RFC 1738 (Obsoleted by RFC 4248, RFC 4266) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) -- Possible downref: Non-RFC (?) normative reference: ref. 'USA15' Summary: 7 errors (**), 0 flaws (~~), 1 warning (==), 19 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: July 19, 2012 independent 6 N. Sakimura 7 Nomura Research Institute 8 January 16, 2012 10 JSON Web Signature (JWS) 11 draft-ietf-jose-json-web-signature-00 13 Abstract 15 JSON Web Signature (JWS) is a means of representing content secured 16 with digital signatures or Hash-based Message Authentication Codes 17 (HMACs) using JSON data structures. Cryptographic algorithms and 18 identifiers used with this specification are enumerated in the 19 separate JSON Web Algorithms (JWA) specification. Related encryption 20 capabilities are described in the separate JSON Web Encryption (JWE) 21 specification. 23 Requirements Language 25 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 26 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 27 document are to be interpreted as described in RFC 2119 [RFC2119]. 29 Status of this Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at http://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on July 19, 2012. 46 Copyright Notice 48 Copyright (c) 2012 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 65 3. JSON Web Signature (JWS) Overview . . . . . . . . . . . . . . 5 66 3.1. Example JWS . . . . . . . . . . . . . . . . . . . . . . . 5 67 4. JWS Header . . . . . . . . . . . . . . . . . . . . . . . . . . 6 68 4.1. Reserved Header Parameter Names . . . . . . . . . . . . . 6 69 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 10 70 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 10 71 5. Rules for Creating and Validating a JWS . . . . . . . . . . . 10 72 6. Securing JWSs with Cryptographic Algorithms . . . . . . . . . 12 73 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 74 8. Security Considerations . . . . . . . . . . . . . . . . . . . 13 75 8.1. Unicode Comparison Security Issues . . . . . . . . . . . . 13 76 9. Open Issues and Things To Be Done (TBD) . . . . . . . . . . . 14 77 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 78 10.1. Normative References . . . . . . . . . . . . . . . . . . . 15 79 10.2. Informative References . . . . . . . . . . . . . . . . . . 16 80 Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 16 81 A.1. JWS using HMAC SHA-256 . . . . . . . . . . . . . . . . . . 17 82 A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 17 83 A.1.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 18 84 A.1.3. Validating . . . . . . . . . . . . . . . . . . . . . . 19 85 A.2. JWS using RSA SHA-256 . . . . . . . . . . . . . . . . . . 19 86 A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 19 87 A.2.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 22 88 A.2.3. Validating . . . . . . . . . . . . . . . . . . . . . . 22 89 A.3. JWS using ECDSA P-256 SHA-256 . . . . . . . . . . . . . . 23 90 A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 23 91 A.3.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 25 92 A.3.3. Validating . . . . . . . . . . . . . . . . . . . . . . 25 93 Appendix B. Notes on implementing base64url encoding without 94 padding . . . . . . . . . . . . . . . . . . . . . . . 25 95 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 26 96 Appendix D. Document History . . . . . . . . . . . . . . . . . . 27 97 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 27 99 1. Introduction 101 JSON Web Signature (JWS) is a compact format for representing content 102 secured with digital signatures or Hash-based Message Authentication 103 Codes (HMACs) intended for space constrained environments such as 104 HTTP Authorization headers and URI query parameters. It represents 105 this content using JSON [RFC4627] data structures. The JWS digital 106 signature and HMAC mechanisms are independent of the type of content 107 being secured, allowing arbitrary content to be secured. 108 Cryptographic algorithms and identifiers used with this specification 109 are enumerated in the separate JSON Web Algorithms (JWA) [JWA] 110 specification. Related encryption capabilities are described in the 111 separate JSON Web Encryption (JWE) [JWE] specification. 113 2. Terminology 115 JSON Web Signature (JWS) A data structure cryptographically securing 116 a JWS Header and a JWS Payload with a JWS Signature value. 118 JWS Header A string representing a JSON object that describes the 119 digital signature or HMAC applied to the JWS Header and the JWS 120 Payload to create the JWS Signature value. 122 JWS Payload The bytes to be secured - a.k.a., the message. 124 JWS Signature A byte array containing the cryptographic material 125 that secures the contents of the JWS Header and the JWS Payload. 127 Encoded JWS Header Base64url encoding of the bytes of the UTF-8 RFC 128 3629 [RFC3629] representation of the JWS Header. 130 Encoded JWS Payload Base64url encoding of the JWS Payload. 132 Encoded JWS Signature Base64url encoding of the JWS Signature. 134 JWS Secured Input The concatenation of the Encoded JWS Header, a 135 period ('.') character, and the Encoded JWS Payload. 137 Header Parameter Names The names of the members within the JSON 138 object represented in a JWS Header. 140 Header Parameter Values The values of the members within the JSON 141 object represented in a JWS Header. 143 Base64url Encoding For the purposes of this specification, this term 144 always refers to the URL- and filename-safe Base64 encoding 145 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 146 safe) '=' padding characters omitted, as permitted by Section 3.2. 147 (See Appendix B for notes on implementing base64url encoding 148 without padding.) 150 3. JSON Web Signature (JWS) Overview 152 JWS represents digitally signed or HMACed content using JSON data 153 structures and base64url encoding. The representation consists of 154 three parts: the JWS Header, the JWS Payload, and the JWS Signature. 155 The three parts are base64url-encoded for transmission, and typically 156 represented as the concatenation of the encoded strings in that 157 order, with the three strings being separated by period ('.') 158 characters. 160 The JWS Header describes the signature or HMAC method and parameters 161 employed. The JWS Payload is the message content to be secured. The 162 JWS Signature ensures the integrity of both the JWS Header and the 163 JWS Payload. 165 3.1. Example JWS 167 The following example JWS Header declares that the encoded object is 168 a JSON Web Token (JWT) [JWT] and the JWS Header and the JWS Payload 169 are secured using the HMAC SHA-256 algorithm: 170 {"typ":"JWT", 171 "alg":"HS256"} 173 Base64url encoding the bytes of the UTF-8 representation of the JWS 174 Header yields this Encoded JWS Header value: 175 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 177 The following is an example of a JSON object that can be used as a 178 JWS Payload. (Note that the payload can be any content, and need not 179 be a representation of a JSON object.) 180 {"iss":"joe", 181 "exp":1300819380, 182 "http://example.com/is_root":true} 184 Base64url encoding the bytes of the UTF-8 representation of the JSON 185 object yields the following Encoded JWS Payload (with line breaks for 186 display purposes only): 187 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 188 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 189 Computing the HMAC of the UTF-8 representation of the JWS Secured 190 Input (the concatenation of the Encoded JWS Header, a period ('.') 191 character, and the Encoded JWS Payload) with the HMAC SHA-256 192 algorithm and base64url encoding the result, as per Appendix A.1, 193 yields this Encoded JWS Signature value: 194 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 196 Concatenating these parts in the order Header.Payload.Signature with 197 period characters between the parts yields this complete JWS 198 representation (with line breaks for display purposes only): 199 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 200 . 201 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 202 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 203 . 204 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 206 This computation is illustrated in more detail in Appendix A.1. 208 4. JWS Header 210 The members of the JSON object represented by the JWS Header describe 211 the digital signature or HMAC applied to the Encoded JWS Header and 212 the Encoded JWS Payload and optionally additional properties of the 213 JWS. The Header Parameter Names within this object MUST be unique. 214 Implementations MUST understand the entire contents of the header; 215 otherwise, the JWS MUST be rejected. 217 The JWS Header MUST contain an "alg" (algorithm) parameter, the value 218 of which is a string that unambiguously identifies the algorithm used 219 to secure the JWS Header and the JWS Payload to produce the JWS 220 Signature. 222 There are three classes of Header Parameter Names: Reserved Header 223 Parameter Names, Public Header Parameter Names, and Private Header 224 Parameter Names. 226 4.1. Reserved Header Parameter Names 228 The following header parameter names are reserved. All the names are 229 short because a core goal of JWSs is for the representations to be 230 compact. 232 +-----------+--------+-------------+--------------------------------+ 233 | Header | JSON | Header | Header Parameter Semantics | 234 | Parameter | Value | Parameter | | 235 | Name | Type | Syntax | | 236 +-----------+--------+-------------+--------------------------------+ 237 | alg | string | StringOrURI | The "alg" (algorithm) header | 238 | | | | parameter identifies the | 239 | | | | cryptographic algorithm used | 240 | | | | to secure the JWS. A list of | 241 | | | | defined "alg" values is | 242 | | | | presented in Section 3, Table | 243 | | | | 1 of the JSON Web Algorithms | 244 | | | | (JWA) [JWA] specification. | 245 | | | | The processing of the "alg" | 246 | | | | header parameter requires that | 247 | | | | the value MUST be one that is | 248 | | | | both supported and for which | 249 | | | | there exists a key for use | 250 | | | | with that algorithm associated | 251 | | | | with the party that digitally | 252 | | | | signed or HMACed the content. | 253 | | | | The "alg" parameter value is | 254 | | | | case sensitive. This header | 255 | | | | parameter is REQUIRED. | 256 | typ | string | String | The "typ" (type) header | 257 | | | | parameter is used to declare | 258 | | | | the type of the secured | 259 | | | | content. The "typ" value is | 260 | | | | case sensitive. This header | 261 | | | | parameter is OPTIONAL. | 262 | jku | string | URL | The "jku" (JSON Web Key URL) | 263 | | | | header parameter is an | 264 | | | | absolute URL that refers to a | 265 | | | | resource for a set of | 266 | | | | JSON-encoded public keys, one | 267 | | | | of which corresponds to the | 268 | | | | key that was used to digitally | 269 | | | | sign the JWS. The keys MUST | 270 | | | | be encoded as described in the | 271 | | | | JSON Web Key (JWK) [JWK] | 272 | | | | specification. The protocol | 273 | | | | used to acquire the resource | 274 | | | | MUST provide integrity | 275 | | | | protection. An HTTP GET | 276 | | | | request to retrieve the | 277 | | | | certificate MUST use TLS RFC | 278 | | | | 2818 [RFC2818] RFC 5246 | 279 | | | | [RFC5246] with server | 280 | | | | authentication RFC 6125 | 281 | | | | [RFC6125]. This header | 282 | | | | parameter is OPTIONAL. | 283 | kid | string | String | The "kid" (key ID) header | 284 | | | | parameter is a hint indicating | 285 | | | | which specific key owned by | 286 | | | | the signer should be used to | 287 | | | | validate the digital | 288 | | | | signature. This allows | 289 | | | | signers to explicitly signal a | 290 | | | | change of key to recipients. | 291 | | | | The interpretation of the | 292 | | | | contents of the "kid" | 293 | | | | parameter is unspecified. | 294 | | | | This header parameter is | 295 | | | | OPTIONAL. | 296 | x5u | string | URL | The "x5u" (X.509 URL) header | 297 | | | | parameter is an absolute URL | 298 | | | | that refers to a resource for | 299 | | | | the X.509 public key | 300 | | | | certificate or certificate | 301 | | | | chain corresponding to the key | 302 | | | | used to digitally sign the | 303 | | | | JWS. The identified resource | 304 | | | | MUST provide a representation | 305 | | | | of the certificate or | 306 | | | | certificate chain that | 307 | | | | conforms to RFC 5280 [RFC5280] | 308 | | | | in PEM encoded form RFC 1421 | 309 | | | | [RFC1421]. The protocol used | 310 | | | | to acquire the resource MUST | 311 | | | | provide integrity protection. | 312 | | | | An HTTP GET request to | 313 | | | | retrieve the certificate MUST | 314 | | | | use TLS RFC 2818 [RFC2818] RFC | 315 | | | | 5246 [RFC5246] with server | 316 | | | | authentication RFC 6125 | 317 | | | | [RFC6125]. This header | 318 | | | | parameter is OPTIONAL. | 319 | x5t | string | String | The "x5t" (x.509 certificate | 320 | | | | thumbprint) header parameter | 321 | | | | provides a base64url encoded | 322 | | | | SHA-1 thumbprint (a.k.a. | 323 | | | | digest) of the DER encoding of | 324 | | | | an X.509 certificate that can | 325 | | | | be used to match the | 326 | | | | certificate. This header | 327 | | | | parameter is OPTIONAL. | 328 +-----------+--------+-------------+--------------------------------+ 330 Table 1: Reserved Header Parameter Definitions 332 Additional reserved header parameter names MAY be defined via the 333 IANA JSON Web Signature Header Parameters registry, as per Section 7. 334 The syntax values used above are defined as follows: 336 +-------------+-----------------------------------------------------+ 337 | Syntax Name | Syntax Definition | 338 +-------------+-----------------------------------------------------+ 339 | IntDate | The number of seconds from 1970-01-01T0:0:0Z as | 340 | | measured in UTC until the desired date/time. See | 341 | | RFC 3339 [RFC3339] for details regarding date/times | 342 | | in general and UTC in particular. | 343 | String | Any string value MAY be used. | 344 | StringOrURI | Any string value MAY be used but a value containing | 345 | | a ":" character MUST be a URI as defined in RFC | 346 | | 3986 [RFC3986]. | 347 | URL | A URL as defined in RFC 1738 [RFC1738]. | 348 +-------------+-----------------------------------------------------+ 350 Table 2: Header Parameter Syntax Definitions 352 4.2. Public Header Parameter Names 354 Additional header parameter names can be defined by those using JWSs. 355 However, in order to prevent collisions, any new header parameter 356 name or algorithm value SHOULD either be defined in the IANA JSON Web 357 Signature Header Parameters registry or be defined as a URI that 358 contains a collision resistant namespace. In each case, the definer 359 of the name or value needs to take reasonable precautions to make 360 sure they are in control of the part of the namespace they use to 361 define the header parameter name. 363 New header parameters should be introduced sparingly, as they can 364 result in non-interoperable JWSs. 366 4.3. Private Header Parameter Names 368 A producer and consumer of a JWS may agree to any header parameter 369 name that is not a Reserved Name Section 4.1 or a Public Name 370 Section 4.2. Unlike Public Names, these private names are subject to 371 collision and should be used with caution. 373 New header parameters should be introduced sparingly, as they can 374 result in non-interoperable JWSs. 376 5. Rules for Creating and Validating a JWS 378 To create a JWS, one MUST perform these steps: 380 1. Create the content to be used as the JWS Payload. 382 2. Base64url encode the bytes of the JWS Payload. This encoding 383 becomes the Encoded JWS Payload. 385 3. Create a JWS Header containing the desired set of header 386 parameters. Note that white space is explicitly allowed in the 387 representation and no canonicalization is performed before 388 encoding. 390 4. Base64url encode the bytes of the UTF-8 representation of the JWS 391 Header to create the Encoded JWS Header. 393 5. Compute the JWS Signature in the manner defined for the 394 particular algorithm being used. The JWS Secured Input is always 395 the concatenation of the Encoded JWS Header, a period ('.') 396 character, and the Encoded JWS Payload. (Note that if the JWS 397 represents a JWT, this corresponds to the portion of the JWT 398 representation preceding the second period character.) The "alg" 399 (algorithm) header parameter MUST be present in the JSON Header, 400 with the algorithm value accurately representing the algorithm 401 used to construct the JWS Signature. 403 6. Base64url encode the representation of the JWS Signature to 404 create the Encoded JWS Signature. 406 When validating a JWS, the following steps MUST be taken. If any of 407 the listed steps fails, then the JWS MUST be rejected. 409 1. The Encoded JWS Header MUST be successfully base64url decoded 410 following the restriction given in this specification that no 411 padding characters have been used. 413 2. The JWS Header MUST be completely valid JSON syntax conforming to 414 RFC 4627 [RFC4627]. 416 3. The JWS Header MUST be validated to only include parameters and 417 values whose syntax and semantics are both understood and 418 supported. 420 4. The Encoded JWS Payload MUST be successfully base64url decoded 421 following the restriction given in this specification that no 422 padding characters have been used. 424 5. The Encoded JWS Signature MUST be successfully base64url decoded 425 following the restriction given in this specification that no 426 padding characters have been used. 428 6. The JWS Signature MUST be successfully validated against the JWS 429 Header and JWS Payload in the manner defined for the algorithm 430 being used, which MUST be accurately represented by the value of 431 the "alg" (algorithm) header parameter, which MUST be present. 433 Processing a JWS inevitably requires comparing known strings to 434 values in the header. For example, in checking what the algorithm 435 is, the Unicode string encoding "alg" will be checked against the 436 member names in the JWS Header to see if there is a matching header 437 parameter name. A similar process occurs when determining if the 438 value of the "alg" header parameter represents a supported algorithm. 440 Comparisons between JSON strings and other Unicode strings MUST be 441 performed as specified below: 443 1. Remove any JSON applied escaping to produce an array of Unicode 444 code points. 446 2. Unicode Normalization [USA15] MUST NOT be applied at any point to 447 either the JSON string or to the string it is to be compared 448 against. 450 3. Comparisons between the two strings MUST be performed as a 451 Unicode code point to code point equality comparison. 453 6. Securing JWSs with Cryptographic Algorithms 455 JWS uses cryptographic algorithms to digitally sign or HMAC the 456 contents of the JWS Header and the JWS Payload. The JSON Web 457 Algorithms (JWA) [JWA] specification enumerates a set of 458 cryptographic algorithms and identifiers to be used with this 459 specification. Specifically, Section 3, Table 1 enumerates a set of 460 "alg" (algorithm) header parameter values intended for use this 461 specification. It also describes the semantics and operations that 462 are specific to these algorithms and algorithm families. 464 Public keys employed for digital signing can be identified using the 465 Header Parameter methods described in Section 4.1 or can be 466 distributed using methods that are outside the scope of this 467 specification. 469 7. IANA Considerations 471 This specification calls for: 473 o A new IANA registry entitled "JSON Web Signature Header 474 Parameters" for reserved header parameter names is defined in 475 Section 4.1. Inclusion in the registry is RFC Required in the RFC 476 5226 [RFC5226] sense for reserved JWS header parameter names that 477 are intended to be interoperable between implementations. The 478 registry will just record the reserved header parameter name and a 479 pointer to the RFC that defines it. This specification defines 480 inclusion of the header parameter names defined in Table 1. 482 8. Security Considerations 484 TBD: Lots of work to do here. We need to remember to look into any 485 issues relating to security and JSON parsing. One wonders just how 486 secure most JSON parsing libraries are. Were they ever hardened for 487 security scenarios? If not, what kind of holes does that open up? 488 Also, we need to walk through the JSON standard and see what kind of 489 issues we have especially around comparison of names. For instance, 490 comparisons of header parameter names and other parameters must occur 491 after they are unescaped. Need to also put in text about: Importance 492 of keeping secrets secret. Rotating keys. Strengths and weaknesses 493 of the different algorithms. 495 TBD: Need to put in text about why strict JSON validation is 496 necessary. Basically, that if malformed JSON is received then the 497 intent of the sender is impossible to reliably discern. One example 498 of malformed JSON that MUST be rejected is an object in which the 499 same member name occurs multiple times. 501 TBD: Write security considerations about the implications of using a 502 SHA-1 hash (for compatibility reasons) for the "x5t" (x.509 503 certificate thumbprint). 505 When utilizing TLS to retrieve information, the authority providing 506 the resource MUST be authenticated and the information retrieved MUST 507 be free from modification. 509 8.1. Unicode Comparison Security Issues 511 Header parameter names in JWSs are Unicode strings. For security 512 reasons, the representations of these names must be compared verbatim 513 after performing any escape processing (as per RFC 4627 [RFC4627], 514 Section 2.5). 516 This means, for instance, that these JSON strings must compare as 517 being equal ("sig", "\u0073ig"), whereas these must all compare as 518 being not equal to the first set or to each other ("SIG", "Sig", 519 "si\u0047"). 521 JSON strings MAY contain characters outside the Unicode Basic 522 Multilingual Plane. For instance, the G clef character (U+1D11E) may 523 be represented in a JSON string as "\uD834\uDD1E". Ideally, JWS 524 implementations SHOULD ensure that characters outside the Basic 525 Multilingual Plane are preserved and compared correctly; 526 alternatively, if this is not possible due to these characters 527 exercising limitations present in the underlying JSON implementation, 528 then input containing them MUST be rejected. 530 9. Open Issues and Things To Be Done (TBD) 532 The following items remain to be done in this draft: 534 o Clarify the optional ability to provide type information in the 535 JWS header. Specifically, clarify the intended use of the "typ" 536 Header Parameter, whether it conveys syntax or semantics, and 537 indeed, whether this is the right approach. Also clarify the 538 relationship between these type values and MIME [RFC2045] types. 540 o Clarify the semantics of the "kid" (key ID) header parameter. 541 Open issues include: What happens if a "kid" header is received 542 with an unrecognized value? Is that an error? Should it be 543 treated as if it's empty? What happens if the header has a 544 recognized value but the value doesn't match the key associated 545 with that value, but it does match another key that is associated 546 with the issuer? Is that an error? 548 o Consider whether a key type parameter should also be introduced. 550 o Add Security Considerations text on timing attacks. 552 o It would be good to have a confirmation method element so it could 553 be used with holder-of-key. 555 o Consider whether to add parameters for directly including keys in 556 the header, either as JWK Key Objects, or X.509 cert values, or 557 both. 559 o Consider whether to add version numbers. 561 o Think about how to best describe the concept currently described 562 as "the bytes of the UTF-8 representation of". Possible terms to 563 use instead of "bytes of" include "byte sequence", "octet series", 564 and "octet sequence". Also consider whether we want to add an 565 overall clarifying statement somewhere in each spec something like 566 "every place we say 'the UTF-8 representation of X', we mean 'the 567 bytes of the UTF-8 representation of X'". That would potentially 568 allow us to omit the "the bytes of" part everywhere else. 570 o Finish the Security Considerations section. 572 o Add an example in which the payload is not a base64url encoded 573 JSON object. 575 10. References 577 10.1. Normative References 579 [JWA] Jones, M., "JSON Web Algorithms (JWA)", January 2012. 581 [JWK] Jones, M., "JSON Web Key (JWK)", January 2012. 583 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 584 Mail: Part I: Message Encryption and Authentication 585 Procedures", RFC 1421, February 1993. 587 [RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform 588 Resource Locators (URL)", RFC 1738, December 1994. 590 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 591 Extensions (MIME) Part One: Format of Internet Message 592 Bodies", RFC 2045, November 1996. 594 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 595 Requirement Levels", BCP 14, RFC 2119, March 1997. 597 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 599 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 600 Internet: Timestamps", RFC 3339, July 2002. 602 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 603 10646", STD 63, RFC 3629, November 2003. 605 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 606 Resource Identifier (URI): Generic Syntax", STD 66, 607 RFC 3986, January 2005. 609 [RFC4627] Crockford, D., "The application/json Media Type for 610 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 612 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 613 Encodings", RFC 4648, October 2006. 615 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 616 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 617 May 2008. 619 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 620 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 622 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 623 Housley, R., and W. Polk, "Internet X.509 Public Key 624 Infrastructure Certificate and Certificate Revocation List 625 (CRL) Profile", RFC 5280, May 2008. 627 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 628 Verification of Domain-Based Application Service Identity 629 within Internet Public Key Infrastructure Using X.509 630 (PKIX) Certificates in the Context of Transport Layer 631 Security (TLS)", RFC 6125, March 2011. 633 [USA15] Davis, M., Whistler, K., and M. Duerst, "Unicode 634 Normalization Forms", Unicode Standard Annex 15, 09 2009. 636 10.2. Informative References 638 [CanvasApp] 639 Facebook, "Canvas Applications", 2010. 641 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 642 September 2010. 644 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 645 Encryption (JWE)", January 2012. 647 [JWT] Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, 648 J., Sakimura, N., and P. Tarjan, "JSON Web Token (JWT)", 649 December 2011. 651 [MagicSignatures] 652 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 653 Signatures", August 2010. 655 Appendix A. JWS Examples 657 This section provides several examples of JWSs. While these examples 658 all represent JSON Web Tokens (JWTs) [JWT], the payload can be any 659 base64url encoded content. 661 A.1. JWS using HMAC SHA-256 663 A.1.1. Encoding 665 The following example JWS Header declares that the data structure is 666 a JSON Web Token (JWT) [JWT] and the JWS Secured Input is secured 667 using the HMAC SHA-256 algorithm. Note that white space is 668 explicitly allowed in JWS Header strings and no canonicalization is 669 performed before encoding. 670 {"typ":"JWT", 671 "alg":"HS256"} 673 The following byte array contains the UTF-8 characters for the JWS 674 Header: 676 [123, 34, 116, 121, 112, 34, 58, 34, 74, 87, 84, 34, 44, 13, 10, 32, 677 34, 97, 108, 103, 34, 58, 34, 72, 83, 50, 53, 54, 34, 125] 679 Base64url encoding this UTF-8 representation yields this Encoded JWS 680 Header value: 681 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 683 The JWS Payload used in this example follows. (Note that the payload 684 can be any base64url encoded content, and need not be a base64url 685 encoded JSON object.) 686 {"iss":"joe", 687 "exp":1300819380, 688 "http://example.com/is_root":true} 690 The following byte array contains the UTF-8 characters for the JWS 691 Payload: 693 [123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10, 694 32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56, 695 48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97, 696 109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111, 697 111, 116, 34, 58, 116, 114, 117, 101, 125] 699 Base64url encoding the above yields the Encoded JWS Payload value 700 (with line breaks for display purposes only): 701 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 702 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 704 Concatenating the Encoded JWS Header, a period character, and the 705 Encoded JWS Payload yields this JWS Secured Input value (with line 706 breaks for display purposes only): 708 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 709 . 710 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 711 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 713 The UTF-8 representation of the JWS Secured Input is the following 714 byte array: 716 [101, 121, 74, 48, 101, 88, 65, 105, 79, 105, 74, 75, 86, 49, 81, 717 105, 76, 65, 48, 75, 73, 67, 74, 104, 98, 71, 99, 105, 79, 105, 74, 718 73, 85, 122, 73, 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 719 77, 105, 79, 105, 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 720 74, 108, 101, 72, 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 721 107, 122, 79, 68, 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 722 72, 65, 54, 76, 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 723 109, 78, 118, 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 724 106, 112, 48, 99, 110, 86, 108, 102, 81] 726 HMACs are generated using keys. This example uses the key 727 represented by the following byte array: 729 [3, 35, 53, 75, 43, 15, 165, 188, 131, 126, 6, 101, 119, 123, 166, 730 143, 90, 179, 40, 230, 240, 84, 201, 40, 169, 15, 132, 178, 210, 80, 731 46, 191, 211, 251, 90, 146, 210, 6, 71, 239, 150, 138, 180, 195, 119, 732 98, 61, 34, 61, 46, 33, 114, 5, 46, 79, 8, 192, 205, 154, 245, 103, 733 208, 128, 163] 735 Running the HMAC SHA-256 algorithm on the UTF-8 representation of the 736 JWS Secured Input with this key yields the following byte array: 738 [116, 24, 223, 180, 151, 153, 224, 37, 79, 250, 96, 125, 216, 173, 739 187, 186, 22, 212, 37, 77, 105, 214, 191, 240, 91, 88, 5, 88, 83, 740 132, 141, 121] 742 Base64url encoding the above HMAC output yields the Encoded JWS 743 Signature value: 744 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 746 A.1.2. Decoding 748 Decoding the JWS first requires removing the base64url encoding from 749 the Encoded JWS Header, the Encoded JWS Payload, and the Encoded JWS 750 Signature. We base64url decode the inputs and turn them into the 751 corresponding byte arrays. We translate the header input byte array 752 containing UTF-8 encoded characters into the JWS Header string. 754 A.1.3. Validating 756 Next we validate the decoded results. Since the "alg" parameter in 757 the header is "HS256", we validate the HMAC SHA-256 value contained 758 in the JWS Signature. If any of the validation steps fail, the JWS 759 MUST be rejected. 761 First, we validate that the JWS Header string is legal JSON. 763 To validate the HMAC value, we repeat the previous process of using 764 the correct key and the UTF-8 representation of the JWS Secured Input 765 as input to a SHA-256 HMAC function and then taking the output and 766 determining if it matches the JWS Signature. If it matches exactly, 767 the HMAC has been validated. 769 A.2. JWS using RSA SHA-256 771 A.2.1. Encoding 773 The JWS Header in this example is different from the previous example 774 in two ways: First, because a different algorithm is being used, the 775 "alg" value is different. Second, for illustration purposes only, 776 the optional "typ" parameter is not used. (This difference is not 777 related to the algorithm employed.) The JWS Header used is: 778 {"alg":"RS256"} 780 The following byte array contains the UTF-8 characters for the JWS 781 Header: 783 [123, 34, 97, 108, 103, 34, 58, 34, 82, 83, 50, 53, 54, 34, 125] 785 Base64url encoding this UTF-8 representation yields this Encoded JWS 786 Header value: 787 eyJhbGciOiJSUzI1NiJ9 789 The JWS Payload used in this example, which follows, is the same as 790 in the previous example. Since the Encoded JWS Payload will 791 therefore be the same, its computation is not repeated here. 792 {"iss":"joe", 793 "exp":1300819380, 794 "http://example.com/is_root":true} 796 Concatenating the Encoded JWS Header, a period character, and the 797 Encoded JWS Payload yields this JWS Secured Input value (with line 798 breaks for display purposes only): 800 eyJhbGciOiJSUzI1NiJ9 801 . 802 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 803 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 805 The UTF-8 representation of the JWS Secured Input is the following 806 byte array: 808 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 122, 73, 809 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, 810 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 74, 108, 101, 72, 811 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 107, 122, 79, 68, 812 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 72, 65, 54, 76, 813 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 109, 78, 118, 814 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48, 815 99, 110, 86, 108, 102, 81] 817 The RSA key consists of a public part (n, e), and a private exponent 818 d. The values of the RSA key used in this example, presented as the 819 byte arrays representing big endian integers are: 821 +-----------+-------------------------------------------------------+ 822 | Parameter | Value | 823 | Name | | 824 +-----------+-------------------------------------------------------+ 825 | n | [161, 248, 22, 10, 226, 227, 201, 180, 101, 206, 141, | 826 | | 45, 101, 98, 99, 54, 43, 146, 125, 190, 41, 225, 240, | 827 | | 36, 119, 252, 22, 37, 204, 144, 161, 54, 227, 139, | 828 | | 217, 52, 151, 197, 182, 234, 99, 221, 119, 17, 230, | 829 | | 124, 116, 41, 249, 86, 176, 251, 138, 143, 8, 154, | 830 | | 220, 75, 105, 137, 60, 193, 51, 63, 83, 237, 208, 25, | 831 | | 184, 119, 132, 37, 47, 236, 145, 79, 228, 133, 119, | 832 | | 105, 89, 75, 234, 66, 128, 211, 44, 15, 85, 191, 98, | 833 | | 148, 79, 19, 3, 150, 188, 110, 155, 223, 110, 189, | 834 | | 210, 189, 163, 103, 142, 236, 160, 198, 104, 247, 1, | 835 | | 179, 141, 191, 251, 56, 200, 52, 44, 226, 254, 109, | 836 | | 39, 250, 222, 74, 90, 72, 116, 151, 157, 212, 185, | 837 | | 207, 154, 222, 196, 199, 91, 5, 133, 44, 44, 15, 94, | 838 | | 248, 165, 193, 117, 3, 146, 249, 68, 232, 237, 100, | 839 | | 193, 16, 198, 182, 71, 96, 154, 164, 120, 58, 235, | 840 | | 156, 108, 154, 215, 85, 49, 48, 80, 99, 139, 131, | 841 | | 102, 92, 111, 111, 122, 130, 163, 150, 112, 42, 31, | 842 | | 100, 27, 130, 211, 235, 242, 57, 34, 25, 73, 31, 182, | 843 | | 134, 135, 44, 87, 22, 245, 10, 248, 53, 141, 154, | 844 | | 139, 157, 23, 195, 64, 114, 143, 127, 135, 216, 154, | 845 | | 24, 216, 252, 171, 103, 173, 132, 89, 12, 46, 207, | 846 | | 117, 147, 57, 54, 60, 7, 3, 77, 111, 96, 111, 158, | 847 | | 33, 224, 84, 86, 202, 229, 233, 161] | 848 | e | [1, 0, 1] | 849 | d | [18, 174, 113, 164, 105, 205, 10, 43, 195, 126, 82, | 850 | | 108, 69, 0, 87, 31, 29, 97, 117, 29, 100, 233, 73, | 851 | | 112, 123, 98, 89, 15, 157, 11, 165, 124, 150, 60, 64, | 852 | | 30, 63, 207, 47, 44, 211, 189, 236, 136, 229, 3, 191, | 853 | | 198, 67, 155, 11, 40, 200, 47, 125, 55, 151, 103, 31, | 854 | | 82, 19, 238, 216, 193, 90, 37, 216, 213, 206, 160, 2, | 855 | | 94, 227, 171, 46, 139, 127, 121, 33, 111, 198, 59, | 856 | | 234, 86, 39, 83, 180, 6, 68, 198, 161, 81, 39, 217, | 857 | | 178, 149, 69, 64, 160, 187, 225, 163, 5, 86, 152, 45, | 858 | | 78, 159, 222, 95, 100, 37, 241, 77, 75, 113, 52, 65, | 859 | | 181, 93, 199, 59, 155, 74, 237, 204, 146, 172, 227, | 860 | | 146, 126, 55, 245, 125, 12, 253, 94, 117, 129, 250, | 861 | | 81, 44, 143, 73, 97, 169, 235, 11, 128, 248, 168, 7, | 862 | | 70, 114, 138, 85, 255, 70, 71, 31, 52, 37, 6, 59, | 863 | | 157, 83, 100, 47, 94, 222, 30, 132, 214, 19, 8, 26, | 864 | | 250, 92, 34, 208, 81, 40, 91, 214, 59, 148, 59, 86, | 865 | | 93, 137, 138, 5, 104, 84, 19, 229, 60, 60, 108, 101, | 866 | | 37, 255, 31, 227, 78, 61, 220, 112, 240, 213, 100, | 867 | | 80, 253, 164, 139, 161, 46, 16, 78, 157, 235, 159, | 868 | | 184, 24, 129, 225, 196, 189, 242, 93, 146, 71, 244, | 869 | | 80, 200, 101, 146, 121, 104, 231, 115, 52, 244, 65, | 870 | | 79, 117, 167, 80, 225, 57, 84, 110, 58, 138, 115, | 871 | | 157] | 872 +-----------+-------------------------------------------------------+ 874 The RSA private key (n, d) is then passed to the RSA signing 875 function, which also takes the hash type, SHA-256, and the UTF-8 876 representation of the JWS Secured Input as inputs. The result of the 877 digital signature is a byte array S, which represents a big endian 878 integer. In this example, S is: 880 +--------+----------------------------------------------------------+ 881 | Result | Value | 882 | Name | | 883 +--------+----------------------------------------------------------+ 884 | S | [112, 46, 33, 137, 67, 232, 143, 209, 30, 181, 216, 45, | 885 | | 191, 120, 69, 243, 65, 6, 174, 27, 129, 255, 247, 115, | 886 | | 17, 22, 173, 209, 113, 125, 131, 101, 109, 66, 10, 253, | 887 | | 60, 150, 238, 221, 115, 162, 102, 62, 81, 102, 104, 123, | 888 | | 0, 11, 135, 34, 110, 1, 135, 237, 16, 115, 249, 69, 229, | 889 | | 130, 173, 252, 239, 22, 216, 90, 121, 142, 232, 198, | 890 | | 109, 219, 61, 184, 151, 91, 23, 208, 148, 2, 190, 237, | 891 | | 213, 217, 217, 112, 7, 16, 141, 178, 129, 96, 213, 248, | 892 | | 4, 12, 167, 68, 87, 98, 184, 31, 190, 127, 249, 217, 46, | 893 | | 10, 231, 111, 36, 242, 91, 51, 187, 230, 244, 74, 230, | 894 | | 30, 177, 4, 10, 203, 32, 4, 77, 62, 249, 18, 142, 212, | 895 | | 1, 48, 121, 91, 212, 189, 59, 65, 238, 202, 208, 102, | 896 | | 171, 101, 25, 129, 253, 228, 141, 247, 127, 55, 45, 195, | 897 | | 139, 159, 175, 221, 59, 239, 177, 139, 93, 163, 204, 60, | 898 | | 46, 176, 47, 158, 58, 65, 214, 18, 202, 173, 21, 145, | 899 | | 18, 115, 160, 95, 35, 185, 232, 56, 250, 175, 132, 157, | 900 | | 105, 132, 41, 239, 90, 30, 136, 121, 130, 54, 195, 212, | 901 | | 14, 96, 69, 34, 165, 68, 200, 242, 122, 122, 45, 184, 6, | 902 | | 99, 209, 108, 247, 202, 234, 86, 222, 64, 92, 178, 33, | 903 | | 90, 69, 178, 194, 85, 102, 181, 90, 193, 167, 72, 160, | 904 | | 112, 223, 200, 163, 42, 70, 149, 67, 208, 25, 238, 251, | 905 | | 71] | 906 +--------+----------------------------------------------------------+ 908 Base64url encoding the digital signature produces this value for the 909 Encoded JWS Signature (with line breaks for display purposes only): 910 cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7 911 AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4 912 BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K 913 0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqv 914 hJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrB 915 p0igcN_IoypGlUPQGe77Rw 917 A.2.2. Decoding 919 Decoding the JWS from this example requires processing the Encoded 920 JWS Header and Encoded JWS Payload exactly as done in the first 921 example. 923 A.2.3. Validating 925 Since the "alg" parameter in the header is "RS256", we validate the 926 RSA SHA-256 digital signature contained in the JWS Signature. If any 927 of the validation steps fail, the JWS MUST be rejected. 929 First, we validate that the JWS Header string is legal JSON. 931 Validating the JWS Signature is a little different from the previous 932 example. First, we base64url decode the Encoded JWS Signature to 933 produce a digital signature S to check. We then pass (n, e), S and 934 the UTF-8 representation of the JWS Secured Input to an RSA signature 935 verifier that has been configured to use the SHA-256 hash function. 937 A.3. JWS using ECDSA P-256 SHA-256 939 A.3.1. Encoding 941 The JWS Header for this example differs from the previous example 942 because a different algorithm is being used. The JWS Header used is: 943 {"alg":"ES256"} 945 The following byte array contains the UTF-8 characters for the JWS 946 Header: 948 [123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 50, 53, 54, 34, 125] 950 Base64url encoding this UTF-8 representation yields this Encoded JWS 951 Header value: 952 eyJhbGciOiJFUzI1NiJ9 954 The JWS Payload used in this example, which follows, is the same as 955 in the previous examples. Since the Encoded JWS Payload will 956 therefore be the same, its computation is not repeated here. 957 {"iss":"joe", 958 "exp":1300819380, 959 "http://example.com/is_root":true} 961 Concatenating the Encoded JWS Header, a period character, and the 962 Encoded JWS Payload yields this JWS Secured Input value (with line 963 breaks for display purposes only): 964 eyJhbGciOiJFUzI1NiJ9 965 . 966 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 967 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 969 The UTF-8 representation of the JWS Secured Input is the following 970 byte array: 972 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 70, 85, 122, 73, 973 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, 974 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 74, 108, 101, 72, 975 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 107, 122, 79, 68, 976 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 72, 65, 54, 76, 977 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 109, 78, 118, 978 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48, 979 99, 110, 86, 108, 102, 81] 981 The ECDSA key consists of a public part, the EC point (x, y), and a 982 private part d. The values of the ECDSA key used in this example, 983 presented as the byte arrays representing big endian integers are: 985 +-----------+-------------------------------------------------------+ 986 | Parameter | Value | 987 | Name | | 988 +-----------+-------------------------------------------------------+ 989 | x | [127, 205, 206, 39, 112, 246, 196, 93, 65, 131, 203, | 990 | | 238, 111, 219, 75, 123, 88, 7, 51, 53, 123, 233, 239, | 991 | | 19, 186, 207, 110, 60, 123, 209, 84, 69] | 992 | y | [199, 241, 68, 205, 27, 189, 155, 126, 135, 44, 223, | 993 | | 237, 185, 238, 185, 244, 179, 105, 93, 110, 169, 11, | 994 | | 36, 173, 138, 70, 35, 40, 133, 136, 229, 173] | 995 | d | [142, 155, 16, 158, 113, 144, 152, 191, 152, 4, 135, | 996 | | 223, 31, 93, 119, 233, 203, 41, 96, 110, 190, 210, | 997 | | 38, 59, 95, 87, 194, 19, 223, 132, 244, 178] | 998 +-----------+-------------------------------------------------------+ 1000 The ECDSA private part d is then passed to an ECDSA signing function, 1001 which also takes the curve type, P-256, the hash type, SHA-256, and 1002 the UTF-8 representation of the JWS Secured Input as inputs. The 1003 result of the digital signature is the EC point (R, S), where R and S 1004 are unsigned integers. In this example, the R and S values, given as 1005 byte arrays representing big endian integers are: 1007 +--------+----------------------------------------------------------+ 1008 | Result | Value | 1009 | Name | | 1010 +--------+----------------------------------------------------------+ 1011 | R | [14, 209, 33, 83, 121, 99, 108, 72, 60, 47, 127, 21, 88, | 1012 | | 7, 212, 2, 163, 178, 40, 3, 58, 249, 124, 126, 23, 129, | 1013 | | 154, 195, 22, 158, 166, 101] | 1014 | S | [197, 10, 7, 211, 140, 60, 112, 229, 216, 241, 45, 175, | 1015 | | 8, 74, 84, 128, 166, 101, 144, 197, 242, 147, 80, 154, | 1016 | | 143, 63, 127, 138, 131, 163, 84, 213] | 1017 +--------+----------------------------------------------------------+ 1019 Concatenating the S array to the end of the R array and base64url 1020 encoding the result produces this value for the Encoded JWS Signature 1021 (with line breaks for display purposes only): 1022 DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSA 1023 pmWQxfKTUJqPP3-Kg6NU1Q 1025 A.3.2. Decoding 1027 Decoding the JWS from this example requires processing the Encoded 1028 JWS Header and Encoded JWS Payload exactly as done in the first 1029 example. 1031 A.3.3. Validating 1033 Since the "alg" parameter in the header is "ES256", we validate the 1034 ECDSA P-256 SHA-256 digital signature contained in the JWS Signature. 1035 If any of the validation steps fail, the JWS MUST be rejected. 1037 First, we validate that the JWS Header string is legal JSON. 1039 Validating the JWS Signature is a little different from the first 1040 example. First, we base64url decode the Encoded JWS Signature as in 1041 the previous examples but we then need to split the 64 member byte 1042 array that must result into two 32 byte arrays, the first R and the 1043 second S. We then pass (x, y), (R, S) and the UTF-8 representation of 1044 the JWS Secured Input to an ECDSA signature verifier that has been 1045 configured to use the P-256 curve with the SHA-256 hash function. 1047 As explained in Section 3.3 of the JSON Web Algorithms (JWA) [JWA] 1048 specification, the use of the k value in ECDSA means that we cannot 1049 validate the correctness of the digital signature in the same way we 1050 validated the correctness of the HMAC. Instead, implementations MUST 1051 use an ECDSA validator to validate the digital signature. 1053 Appendix B. Notes on implementing base64url encoding without padding 1055 This appendix describes how to implement base64url encoding and 1056 decoding functions without padding based upon standard base64 1057 encoding and decoding functions that do use padding. 1059 To be concrete, example C# code implementing these functions is shown 1060 below. Similar code could be used in other languages. 1062 static string base64urlencode(byte [] arg) 1063 { 1064 string s = Convert.ToBase64String(arg); // Standard base64 encoder 1065 s = s.Split('=')[0]; // Remove any trailing '='s 1066 s = s.Replace('+', '-'); // 62nd char of encoding 1067 s = s.Replace('/', '_'); // 63rd char of encoding 1068 return s; 1069 } 1071 static byte [] base64urldecode(string arg) 1072 { 1073 string s = arg; 1074 s = s.Replace('-', '+'); // 62nd char of encoding 1075 s = s.Replace('_', '/'); // 63rd char of encoding 1076 switch (s.Length % 4) // Pad with trailing '='s 1077 { 1078 case 0: break; // No pad chars in this case 1079 case 2: s += "=="; break; // Two pad chars 1080 case 3: s += "="; break; // One pad char 1081 default: throw new System.Exception( 1082 "Illegal base64url string!"); 1083 } 1084 return Convert.FromBase64String(s); // Standard base64 decoder 1085 } 1087 As per the example code above, the number of '=' padding characters 1088 that needs to be added to the end of a base64url encoded string 1089 without padding to turn it into one with padding is a deterministic 1090 function of the length of the encoded string. Specifically, if the 1091 length mod 4 is 0, no padding is added; if the length mod 4 is 2, two 1092 '=' padding characters are added; if the length mod 4 is 3, one '=' 1093 padding character is added; if the length mod 4 is 1, the input is 1094 malformed. 1096 An example correspondence between unencoded and encoded values 1097 follows. The byte sequence below encodes into the string below, 1098 which when decoded, reproduces the byte sequence. 1099 3 236 255 224 193 1100 A-z_4ME 1102 Appendix C. Acknowledgements 1104 Solutions for signing JSON content were previously explored by Magic 1105 Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas 1106 Applications [CanvasApp], all of which influenced this draft. Dirk 1107 Balfanz, Yaron Y. Goland, John Panzer, and Paul Tarjan all made 1108 significant contributions to the design of this specification. 1110 Appendix D. Document History 1112 -00 1114 o Created the initial IETF draft based upon 1115 draft-jones-json-web-signature-04 with no normative changes. 1117 o Changed terminology to no longer call both digital signatures and 1118 HMACs "signatures". 1120 Authors' Addresses 1122 Michael B. Jones 1123 Microsoft 1125 Email: mbj@microsoft.com 1126 URI: http://self-issued.info/ 1128 John Bradley 1129 independent 1131 Email: ve7jtb@ve7jtb.com 1133 Nat Sakimura 1134 Nomura Research Institute 1136 Email: n-sakimura@nri.co.jp