idnits 2.17.1 draft-ietf-jose-json-web-signature-01.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 (March 12, 2012) is 4421 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 1047 -- Looks like a reference, but probably isn't: '34' on line 1047 -- Looks like a reference, but probably isn't: '97' on line 1047 -- Looks like a reference, but probably isn't: '108' on line 1047 -- Looks like a reference, but probably isn't: '103' on line 1047 -- Looks like a reference, but probably isn't: '58' on line 1047 -- Looks like a reference, but probably isn't: '82' on line 883 -- Looks like a reference, but probably isn't: '83' on line 1047 -- Looks like a reference, but probably isn't: '50' on line 1047 -- Looks like a reference, but probably isn't: '53' on line 1047 -- Looks like a reference, but probably isn't: '54' on line 1047 -- Looks like a reference, but probably isn't: '125' on line 1047 -- Looks like a reference, but probably isn't: '1' on line 947 -- Looks like a reference, but probably isn't: '0' on line 1191 -- Looks like a reference, but probably isn't: '69' on line 1047 == Unused Reference: 'RFC2045' is defined on line 692, but no explicit reference was found in the text -- 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 (~~), 2 warnings (==), 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: September 13, 2012 independent 6 N. Sakimura 7 Nomura Research Institute 8 March 12, 2012 10 JSON Web Signature (JWS) 11 draft-ietf-jose-json-web-signature-01 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 September 13, 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 . . . . . . . . . . . . . . 11 70 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 11 71 5. Rules for Creating and Validating a JWS . . . . . . . . . . . 11 72 6. Securing JWSs with Cryptographic Algorithms . . . . . . . . . 13 73 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 74 8. Security Considerations . . . . . . . . . . . . . . . . . . . 14 75 8.1. Unicode Comparison Security Issues . . . . . . . . . . . . 15 76 9. Open Issues and Things To Be Done (TBD) . . . . . . . . . . . 15 77 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 78 10.1. Normative References . . . . . . . . . . . . . . . . . . . 16 79 10.2. Informative References . . . . . . . . . . . . . . . . . . 18 80 Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 18 81 A.1. JWS using HMAC SHA-256 . . . . . . . . . . . . . . . . . . 18 82 A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 18 83 A.1.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 20 84 A.1.3. Validating . . . . . . . . . . . . . . . . . . . . . . 20 85 A.2. JWS using RSA SHA-256 . . . . . . . . . . . . . . . . . . 20 86 A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 20 87 A.2.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 24 88 A.2.3. Validating . . . . . . . . . . . . . . . . . . . . . . 24 89 A.3. JWS using ECDSA P-256 SHA-256 . . . . . . . . . . . . . . 25 90 A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 25 91 A.3.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 27 92 A.3.3. Validating . . . . . . . . . . . . . . . . . . . . . . 27 93 A.4. Example Plaintext JWS . . . . . . . . . . . . . . . . . . 27 94 Appendix B. Notes on implementing base64url encoding without 95 padding . . . . . . . . . . . . . . . . . . . . . . . 28 96 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 29 97 Appendix D. Document History . . . . . . . . . . . . . . . . . . 29 98 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30 100 1. Introduction 102 JSON Web Signature (JWS) is a compact format for representing content 103 secured with digital signatures or Hash-based Message Authentication 104 Codes (HMACs) intended for space constrained environments such as 105 HTTP Authorization headers and URI query parameters. It represents 106 this content using JSON [RFC4627] data structures. The JWS digital 107 signature and HMAC mechanisms are independent of the type of content 108 being secured, allowing arbitrary content to be secured. 109 Cryptographic algorithms and identifiers used with this specification 110 are enumerated in the separate JSON Web Algorithms (JWA) [JWA] 111 specification. Related encryption capabilities are described in the 112 separate JSON Web Encryption (JWE) [JWE] specification. 114 2. Terminology 116 JSON Web Signature (JWS) A data structure cryptographically securing 117 a JWS Header and a JWS Payload with a JWS Signature value. 119 JWS Header A string representing a JSON object that describes the 120 digital signature or HMAC applied to the JWS Header and the JWS 121 Payload to create the JWS Signature value. 123 JWS Payload The bytes to be secured - a.k.a., the message. 125 JWS Signature A byte array containing the cryptographic material 126 that secures the contents of the JWS Header and the JWS Payload. 128 Encoded JWS Header Base64url encoding of the bytes of the UTF-8 RFC 129 3629 [RFC3629] representation of the JWS Header. 131 Encoded JWS Payload Base64url encoding of the JWS Payload. 133 Encoded JWS Signature Base64url encoding of the JWS Signature. 135 JWS Secured Input The concatenation of the Encoded JWS Header, a 136 period ('.') character, and the Encoded JWS Payload. 138 Header Parameter Names The names of the members within the JSON 139 object represented in a JWS Header. 141 Header Parameter Values The values of the members within the JSON 142 object represented in a JWS Header. 144 JWS Compact Serialization A representation of the JWS as the 145 concatenation of the Encoded JWS Header, the Encoded JWS Payload, 146 and the Encoded JWS Signature in that order, with the three 147 strings being separated by period ('.') characters. 149 Base64url Encoding For the purposes of this specification, this term 150 always refers to the URL- and filename-safe Base64 encoding 151 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 152 safe) '=' padding characters omitted, as permitted by Section 3.2. 153 (See Appendix B for notes on implementing base64url encoding 154 without padding.) 156 3. JSON Web Signature (JWS) Overview 158 JWS represents digitally signed or HMACed content using JSON data 159 structures and base64url encoding. The representation consists of 160 three parts: the JWS Header, the JWS Payload, and the JWS Signature. 161 In the Compact Serialization, the three parts are base64url-encoded 162 for transmission, and represented as the concatenation of the encoded 163 strings in that order, with the three strings being separated by 164 period ('.') characters. (A JSON Serialization for this information 165 is defined in the separate JSON Web Signature JSON Serialization 166 (JWS-JS) [JWS-JS] specification.) 168 The JWS Header describes the signature or HMAC method and parameters 169 employed. The JWS Payload is the message content to be secured. The 170 JWS Signature ensures the integrity of both the JWS Header and the 171 JWS Payload. 173 3.1. Example JWS 175 The following example JWS Header declares that the encoded object is 176 a JSON Web Token (JWT) [JWT] and the JWS Header and the JWS Payload 177 are secured using the HMAC SHA-256 algorithm: 178 {"typ":"JWT", 179 "alg":"HS256"} 181 Base64url encoding the bytes of the UTF-8 representation of the JWS 182 Header yields this Encoded JWS Header value: 183 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 185 The following is an example of a JSON object that can be used as a 186 JWS Payload. (Note that the payload can be any content, and need not 187 be a representation of a JSON object.) 188 {"iss":"joe", 189 "exp":1300819380, 190 "http://example.com/is_root":true} 192 Base64url encoding the bytes of the UTF-8 representation of the JSON 193 object yields the following Encoded JWS Payload (with line breaks for 194 display purposes only): 195 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 196 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 198 Computing the HMAC of the UTF-8 representation of the JWS Secured 199 Input (the concatenation of the Encoded JWS Header, a period ('.') 200 character, and the Encoded JWS Payload) with the HMAC SHA-256 201 algorithm and base64url encoding the result, as per Appendix A.1, 202 yields this Encoded JWS Signature value: 203 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 205 Concatenating these parts in the order Header.Payload.Signature with 206 period characters between the parts yields this complete JWS 207 representation (with line breaks for display purposes only): 208 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 209 . 210 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 211 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 212 . 213 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 215 This computation is illustrated in more detail in Appendix A.1. 217 4. JWS Header 219 The members of the JSON object represented by the JWS Header describe 220 the digital signature or HMAC applied to the Encoded JWS Header and 221 the Encoded JWS Payload and optionally additional properties of the 222 JWS. The Header Parameter Names within this object MUST be unique. 223 Implementations MUST understand the entire contents of the header; 224 otherwise, the JWS MUST be rejected. 226 The JWS Header MUST contain an "alg" (algorithm) parameter, the value 227 of which is a string that unambiguously identifies the algorithm used 228 to secure the JWS Header and the JWS Payload to produce the JWS 229 Signature. 231 There are three classes of Header Parameter Names: Reserved Header 232 Parameter Names, Public Header Parameter Names, and Private Header 233 Parameter Names. 235 4.1. Reserved Header Parameter Names 237 The following header parameter names are reserved. All the names are 238 short because a core goal of JWSs is for the representations to be 239 compact. 241 +-----------+--------+----------------+-----------------------------+ 242 | Header | JSON | Header | Header Parameter Semantics | 243 | Parameter | Value | Parameter | | 244 | Name | Type | Syntax | | 245 +-----------+--------+----------------+-----------------------------+ 246 | alg | string | StringOrURI | The "alg" (algorithm) | 247 | | | | header parameter identifies | 248 | | | | the cryptographic algorithm | 249 | | | | used to secure the JWS. A | 250 | | | | list of defined "alg" | 251 | | | | values is presented in | 252 | | | | Section 3, Table 1 of the | 253 | | | | JSON Web Algorithms (JWA) | 254 | | | | [JWA] specification. The | 255 | | | | processing of the "alg" | 256 | | | | header parameter requires | 257 | | | | that the value MUST be one | 258 | | | | that is both supported and | 259 | | | | for which there exists a | 260 | | | | key for use with that | 261 | | | | algorithm associated with | 262 | | | | the party that digitally | 263 | | | | signed or HMACed the | 264 | | | | content. The "alg" | 265 | | | | parameter value is case | 266 | | | | sensitive. This header | 267 | | | | parameter is REQUIRED. | 268 | jku | string | URL | The "jku" (JSON Web Key | 269 | | | | URL) header parameter is an | 270 | | | | absolute URL that refers to | 271 | | | | a resource for a set of | 272 | | | | JSON-encoded public keys, | 273 | | | | one of which corresponds to | 274 | | | | the key that was used to | 275 | | | | digitally sign the JWS. | 276 | | | | The keys MUST be encoded as | 277 | | | | described in the JSON Web | 278 | | | | Key (JWK) [JWK] | 279 | | | | specification. The | 280 | | | | protocol used to acquire | 281 | | | | the resource MUST provide | 282 | | | | integrity protection. An | 283 | | | | HTTP GET request to | 284 | | | | retrieve the certificate | 285 | | | | MUST use TLS RFC 2818 | 286 | | | | [RFC2818] RFC 5246 | 287 | | | | [RFC5246] with server | 288 | | | | authentication RFC 6125 | 289 | | | | [RFC6125]. This header | 290 | | | | parameter is OPTIONAL. | 291 | kid | string | String | The "kid" (key ID) header | 292 | | | | parameter is a hint | 293 | | | | indicating which specific | 294 | | | | key owned by the signer | 295 | | | | should be used to validate | 296 | | | | the digital signature. | 297 | | | | This allows signers to | 298 | | | | explicitly signal a change | 299 | | | | of key to recipients. The | 300 | | | | interpretation of the | 301 | | | | contents of the "kid" | 302 | | | | parameter is unspecified. | 303 | | | | This header parameter is | 304 | | | | OPTIONAL. | 305 | jpk | object | JWK Key Object | The "jpk" (JSON Public Key) | 306 | | | | header parameter is a | 307 | | | | public key that corresponds | 308 | | | | to the key that was used to | 309 | | | | digitally sign the JWS. | 310 | | | | This key is represented in | 311 | | | | the same manner as a JSON | 312 | | | | Web Key [JWK] JWK Key | 313 | | | | Object value. This header | 314 | | | | parameter is OPTIONAL. | 315 | x5u | string | URL | The "x5u" (X.509 URL) | 316 | | | | header parameter is an | 317 | | | | absolute URL that refers to | 318 | | | | a resource for the X.509 | 319 | | | | public key certificate or | 320 | | | | certificate chain | 321 | | | | corresponding to the key | 322 | | | | used to digitally sign the | 323 | | | | JWS. The identified | 324 | | | | resource MUST provide a | 325 | | | | representation of the | 326 | | | | certificate or certificate | 327 | | | | chain that conforms to RFC | 328 | | | | 5280 [RFC5280] in PEM | 329 | | | | encoded form RFC 1421 | 330 | | | | [RFC1421]. The certificate | 331 | | | | containing the public key | 332 | | | | of the entity signing the | 333 | | | | JWS MUST be the first | 334 | | | | certificate. This MAY be | 335 | | | | followed by additional | 336 | | | | certificates, with each | 337 | | | | subsequent certificate | 338 | | | | being the one used to | 339 | | | | certify the previous one. | 340 | | | | The protocol used to | 341 | | | | acquire the resource MUST | 342 | | | | provide integrity | 343 | | | | protection. An HTTP GET | 344 | | | | request to retrieve the | 345 | | | | certificate MUST use TLS | 346 | | | | RFC 2818 [RFC2818] RFC 5246 | 347 | | | | [RFC5246] with server | 348 | | | | authentication RFC 6125 | 349 | | | | [RFC6125]. This header | 350 | | | | parameter is OPTIONAL. | 351 | x5t | string | String | The "x5t" (x.509 | 352 | | | | certificate thumbprint) | 353 | | | | header parameter provides a | 354 | | | | base64url encoded SHA-1 | 355 | | | | thumbprint (a.k.a. digest) | 356 | | | | of the DER encoding of an | 357 | | | | X.509 certificate that can | 358 | | | | be used to match the | 359 | | | | certificate. This header | 360 | | | | parameter is OPTIONAL. | 361 | x5c | array | ArrayOfStrings | The "x5c" (x.509 | 362 | | | | certificate chain) header | 363 | | | | parameter contains the | 364 | | | | X.509 public key | 365 | | | | certificate or certificate | 366 | | | | chain corresponding to the | 367 | | | | key used to digitally sign | 368 | | | | the JWS. The certificate | 369 | | | | or certificate chain is | 370 | | | | represented as an array of | 371 | | | | certificate values. Each | 372 | | | | value is a base64-encoded | 373 | | | | (not base64url encoded) | 374 | | | | DER/BER PKIX certificate | 375 | | | | value. The certificate | 376 | | | | containing the public key | 377 | | | | of the entity signing the | 378 | | | | JWS MUST be the first | 379 | | | | certificate. This MAY be | 380 | | | | followed by additional | 381 | | | | certificates, with each | 382 | | | | subsequent certificate | 383 | | | | being the one used to | 384 | | | | certify the previous one. | 385 | | | | The recipient MUST verify | 386 | | | | the certificate chain | 387 | | | | according to [RFC5280] and | 388 | | | | reject the JWS if any | 389 | | | | validation failure occurs. | 390 | | | | This header parameter is | 391 | | | | OPTIONAL. | 392 | typ | string | String | The "typ" (type) header | 393 | | | | parameter is used to | 394 | | | | declare the type of the | 395 | | | | secured content. The "typ" | 396 | | | | value is case sensitive. | 397 | | | | This header parameter is | 398 | | | | OPTIONAL. | 399 +-----------+--------+----------------+-----------------------------+ 401 Table 1: Reserved Header Parameter Definitions 403 Additional reserved header parameter names MAY be defined via the 404 IANA JSON Web Signature Header Parameters registry, as per Section 7. 405 The syntax values used above are defined as follows: 407 +----------------+--------------------------------------------------+ 408 | Syntax Name | Syntax Definition | 409 +----------------+--------------------------------------------------+ 410 | IntDate | The number of seconds from 1970-01-01T0:0:0Z as | 411 | | measured in UTC until the desired date/time. | 412 | | See RFC 3339 [RFC3339] for details regarding | 413 | | date/times in general and UTC in particular. | 414 | String | Any string value MAY be used. | 415 | StringOrURI | Any string value MAY be used but a value | 416 | | containing a ":" character MUST be a URI as | 417 | | defined in RFC 3986 [RFC3986]. | 418 | URL | A URL as defined in RFC 1738 [RFC1738]. | 419 | ArrayOfStrings | An array of string values. | 420 +----------------+--------------------------------------------------+ 422 Table 2: Header Parameter Syntax Definitions 424 4.2. Public Header Parameter Names 426 Additional header parameter names can be defined by those using JWSs. 427 However, in order to prevent collisions, any new header parameter 428 name or algorithm value SHOULD either be defined in the IANA JSON Web 429 Signature Header Parameters registry or be defined as a URI that 430 contains a collision resistant namespace. In each case, the definer 431 of the name or value needs to take reasonable precautions to make 432 sure they are in control of the part of the namespace they use to 433 define the header parameter name. 435 New header parameters should be introduced sparingly since an 436 implementation that does not understand a parameter MUST reject the 437 JWS. 439 4.3. Private Header Parameter Names 441 A producer and consumer of a JWS may agree to any header parameter 442 name that is not a Reserved Name Section 4.1 or a Public Name 443 Section 4.2. Unlike Public Names, these private names are subject to 444 collision and should be used with caution. 446 New header parameters should be introduced sparingly, as they can 447 result in non-interoperable JWSs. 449 5. Rules for Creating and Validating a JWS 451 To create a JWS, one MUST perform these steps. The order of the 452 steps is not significant in cases where there are no dependencies 453 between the inputs and outputs of the steps. 455 1. Create the content to be used as the JWS Payload. 457 2. Base64url encode the bytes of the JWS Payload. This encoding 458 becomes the Encoded JWS Payload. 460 3. Create a JWS Header containing the desired set of header 461 parameters. Note that white space is explicitly allowed in the 462 representation and no canonicalization need be performed before 463 encoding. 465 4. Base64url encode the bytes of the UTF-8 representation of the JWS 466 Header to create the Encoded JWS Header. 468 5. Compute the JWS Signature in the manner defined for the 469 particular algorithm being used. The JWS Secured Input is always 470 the concatenation of the Encoded JWS Header, a period ('.') 471 character, and the Encoded JWS Payload. (Note that if the JWS 472 represents a JWT, this corresponds to the portion of the JWT 473 representation preceding the second period character.) The "alg" 474 (algorithm) header parameter MUST be present in the JSON Header, 475 with the algorithm value accurately representing the algorithm 476 used to construct the JWS Signature. 478 6. Base64url encode the representation of the JWS Signature to 479 create the Encoded JWS Signature. 481 7. The three encoded parts, taken together, are the result. The 482 Compact Serialization of this result is the concatenation of the 483 Encoded JWS Header, the Encoded JWS Payload, and the Encoded JWS 484 Signature in that order, with the three strings being separated 485 by period ('.') characters. 487 When validating a JWS, the following steps MUST be taken. The order 488 of the steps is not significant in cases where there are no 489 dependencies between the inputs and outputs of the steps. If any of 490 the listed steps fails, then the JWS MUST be rejected. 492 1. Parse the three parts of the input (which are separated by period 493 characters when using the JWS Compact Serialization) into the 494 Encoded JWS Header, the Encoded JWS Payload, and the Encoded JWS 495 Signature. 497 2. The Encoded JWS Header MUST be successfully base64url decoded 498 following the restriction given in this specification that no 499 padding characters have been used. 501 3. The JWS Header MUST be completely valid JSON syntax conforming to 502 RFC 4627 [RFC4627]. 504 4. The JWS Header MUST be validated to only include parameters and 505 values whose syntax and semantics are both understood and 506 supported. 508 5. The Encoded JWS Payload MUST be successfully base64url decoded 509 following the restriction given in this specification that no 510 padding characters have been used. 512 6. The Encoded JWS Signature MUST be successfully base64url decoded 513 following the restriction given in this specification that no 514 padding characters have been used. 516 7. The JWS Signature MUST be successfully validated against the JWS 517 Secured Input (the concatenation of the Encoded JWS Header, a 518 period ('.') character, and the Encoded JWS Payload) in the 519 manner defined for the algorithm being used, which MUST be 520 accurately represented by the value of the "alg" (algorithm) 521 header parameter, which MUST be present. 523 Processing a JWS inevitably requires comparing known strings to 524 values in the header. For example, in checking what the algorithm 525 is, the Unicode string encoding "alg" will be checked against the 526 member names in the JWS Header to see if there is a matching header 527 parameter name. A similar process occurs when determining if the 528 value of the "alg" header parameter represents a supported algorithm. 530 Comparisons between JSON strings and other Unicode strings MUST be 531 performed as specified below: 533 1. Remove any JSON applied escaping to produce an array of Unicode 534 code points. 536 2. Unicode Normalization [USA15] MUST NOT be applied at any point to 537 either the JSON string or to the string it is to be compared 538 against. 540 3. Comparisons between the two strings MUST be performed as a 541 Unicode code point to code point equality comparison. 543 6. Securing JWSs with Cryptographic Algorithms 545 JWS uses cryptographic algorithms to digitally sign or HMAC the 546 contents of the JWS Header and the JWS Payload. The JSON Web 547 Algorithms (JWA) [JWA] specification enumerates a set of 548 cryptographic algorithms and identifiers to be used with this 549 specification. Specifically, Section 3, Table 1 enumerates a set of 550 "alg" (algorithm) header parameter values intended for use this 551 specification. It also describes the semantics and operations that 552 are specific to these algorithms and algorithm families. 554 Public keys employed for digital signing can be identified using the 555 Header Parameter methods described in Section 4.1 or can be 556 distributed using methods that are outside the scope of this 557 specification. 559 7. IANA Considerations 561 This specification calls for: 563 o A new IANA registry entitled "JSON Web Signature Header 564 Parameters" for reserved header parameter names is defined in 565 Section 4.1. Inclusion in the registry is RFC Required in the RFC 566 5226 [RFC5226] sense for reserved JWS header parameter names that 567 are intended to be interoperable between implementations. The 568 registry will just record the reserved header parameter name and a 569 pointer to the RFC that defines it. This specification defines 570 inclusion of the header parameter names defined in Table 1. 572 8. Security Considerations 574 TBD: Lots of work to do here. We need to remember to look into any 575 issues relating to security and JSON parsing. One wonders just how 576 secure most JSON parsing libraries are. Were they ever hardened for 577 security scenarios? If not, what kind of holes does that open up? 578 Also, we need to walk through the JSON standard and see what kind of 579 issues we have especially around comparison of names. For instance, 580 comparisons of header parameter names and other parameters must occur 581 after they are unescaped. Need to also put in text about: Importance 582 of keeping secrets secret. Rotating keys. Strengths and weaknesses 583 of the different algorithms. 585 TBD: Need to put in text about why strict JSON validation is 586 necessary. Basically, that if malformed JSON is received then the 587 intent of the sender is impossible to reliably discern. One example 588 of malformed JSON that MUST be rejected is an object in which the 589 same member name occurs multiple times. 591 TBD: Write security considerations about the implications of using a 592 SHA-1 hash (for compatibility reasons) for the "x5t" (x.509 593 certificate thumbprint). 595 When utilizing TLS to retrieve information, the authority providing 596 the resource MUST be authenticated and the information retrieved MUST 597 be free from modification. 599 8.1. Unicode Comparison Security Issues 601 Header parameter names in JWSs are Unicode strings. For security 602 reasons, the representations of these names must be compared verbatim 603 after performing any escape processing (as per RFC 4627 [RFC4627], 604 Section 2.5). 606 This means, for instance, that these JSON strings must compare as 607 being equal ("sig", "\u0073ig"), whereas these must all compare as 608 being not equal to the first set or to each other ("SIG", "Sig", 609 "si\u0047"). 611 JSON strings MAY contain characters outside the Unicode Basic 612 Multilingual Plane. For instance, the G clef character (U+1D11E) may 613 be represented in a JSON string as "\uD834\uDD1E". Ideally, JWS 614 implementations SHOULD ensure that characters outside the Basic 615 Multilingual Plane are preserved and compared correctly; 616 alternatively, if this is not possible due to these characters 617 exercising limitations present in the underlying JSON implementation, 618 then input containing them MUST be rejected. 620 9. Open Issues and Things To Be Done (TBD) 622 The following items remain to be done in this draft: 624 o EDITORIAL: Give each header parameter definition its own section. 625 This will let them appear in the index, will give space for 626 examples when needed, and will get rid of the way-too-cramped 627 tables. 629 o Describe the relationship between the JWS, JWE, and JWT header 630 parameters. In particular, point out that the set of "alg" values 631 defined by each must be compatible and non-overlapping. 633 o Combine the JWS and JWE "alg" parameter registries and possibly 634 also the header parameter registries. 636 o Clarify the intended use of the "typ" Header Parameter across the 637 JWS, JWE, and JWT specifications. Decide whether a registry of 638 "typ" values is appropriate. 640 o Add normative text that requires rejecting headers in which member 641 names occur multiple times, as apparently this is legal JSON. 643 o Clarify the semantics of the "kid" (key ID) header parameter. 644 Open issues include: What happens if a "kid" header is received 645 with an unrecognized value? Is that an error? Should it be 646 treated as if it's empty? What happens if the header has a 647 recognized value but the value doesn't match the key associated 648 with that value, but it does match another key that is associated 649 with the issuer? Is that an error? 651 o Consider whether a key type parameter should also be introduced. 653 o It would be good to have a confirmation method element so it could 654 be used with holder-of-key. 656 o EDITORIAL: Think about how to best describe the concept currently 657 described as "the bytes of the UTF-8 representation of". Possible 658 terms to use instead of "bytes of" include "byte sequence", "octet 659 series", and "octet sequence". Also consider whether we want to 660 add an overall clarifying statement somewhere in each spec 661 something like "every place we say 'the UTF-8 representation of 662 X', we mean 'the bytes of the UTF-8 representation of X'". That 663 would potentially allow us to omit the "the bytes of" part 664 everywhere else. 666 o Write a note in the Security Considerations section about how 667 "x5t" (x.509 certificate thumbprint) should be deprecated because 668 of known problems with SHA-1. 670 o Add Security Considerations text on timing attacks. 672 o Finish the Security Considerations section. 674 o EDITORIAL: Add an example in which the payload is not a base64url 675 encoded JSON object. 677 10. References 679 10.1. Normative References 681 [JWA] Jones, M., "JSON Web Algorithms (JWA)", March 2012. 683 [JWK] Jones, M., "JSON Web Key (JWK)", March 2012. 685 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 686 Mail: Part I: Message Encryption and Authentication 687 Procedures", RFC 1421, February 1993. 689 [RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform 690 Resource Locators (URL)", RFC 1738, December 1994. 692 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 693 Extensions (MIME) Part One: Format of Internet Message 694 Bodies", RFC 2045, November 1996. 696 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 697 Requirement Levels", BCP 14, RFC 2119, March 1997. 699 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 701 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 702 Internet: Timestamps", RFC 3339, July 2002. 704 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 705 10646", STD 63, RFC 3629, November 2003. 707 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 708 Resource Identifier (URI): Generic Syntax", STD 66, 709 RFC 3986, January 2005. 711 [RFC4627] Crockford, D., "The application/json Media Type for 712 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 714 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 715 Encodings", RFC 4648, October 2006. 717 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 718 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 719 May 2008. 721 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 722 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 724 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 725 Housley, R., and W. Polk, "Internet X.509 Public Key 726 Infrastructure Certificate and Certificate Revocation List 727 (CRL) Profile", RFC 5280, May 2008. 729 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 730 Verification of Domain-Based Application Service Identity 731 within Internet Public Key Infrastructure Using X.509 732 (PKIX) Certificates in the Context of Transport Layer 733 Security (TLS)", RFC 6125, March 2011. 735 [USA15] Davis, M., Whistler, K., and M. Duerst, "Unicode 736 Normalization Forms", Unicode Standard Annex 15, 09 2009. 738 10.2. Informative References 740 [CanvasApp] 741 Facebook, "Canvas Applications", 2010. 743 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 744 September 2010. 746 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 747 Encryption (JWE)", March 2012. 749 [JWS-JS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 750 Signature JSON Serialization (JWS-JS)", March 2012. 752 [JWT] Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, 753 J., Sakimura, N., and P. Tarjan, "JSON Web Token (JWT)", 754 March 2012. 756 [MagicSignatures] 757 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 758 Signatures", January 2011. 760 Appendix A. JWS Examples 762 This section provides several examples of JWSs. While these examples 763 all represent JSON Web Tokens (JWTs) [JWT], the payload can be any 764 base64url encoded content. 766 A.1. JWS using HMAC SHA-256 768 A.1.1. Encoding 770 The following example JWS Header declares that the data structure is 771 a JSON Web Token (JWT) [JWT] and the JWS Secured Input is secured 772 using the HMAC SHA-256 algorithm. 773 {"typ":"JWT", 774 "alg":"HS256"} 776 The following byte array contains the UTF-8 characters for the JWS 777 Header: 779 [123, 34, 116, 121, 112, 34, 58, 34, 74, 87, 84, 34, 44, 13, 10, 32, 780 34, 97, 108, 103, 34, 58, 34, 72, 83, 50, 53, 54, 34, 125] 782 Base64url encoding this UTF-8 representation yields this Encoded JWS 783 Header value: 784 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 785 The JWS Payload used in this example follows. (Note that the payload 786 can be any base64url encoded content, and need not be a base64url 787 encoded JSON object.) 788 {"iss":"joe", 789 "exp":1300819380, 790 "http://example.com/is_root":true} 792 The following byte array contains the UTF-8 characters for the JWS 793 Payload: 795 [123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10, 796 32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56, 797 48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97, 798 109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111, 799 111, 116, 34, 58, 116, 114, 117, 101, 125] 801 Base64url encoding the above yields the Encoded JWS Payload value 802 (with line breaks for display purposes only): 803 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 804 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 806 Concatenating the Encoded JWS Header, a period character, and the 807 Encoded JWS Payload yields this JWS Secured Input value (with line 808 breaks for display purposes only): 809 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 810 . 811 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 812 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 814 The UTF-8 representation of the JWS Secured Input is the following 815 byte array: 817 [101, 121, 74, 48, 101, 88, 65, 105, 79, 105, 74, 75, 86, 49, 81, 818 105, 76, 65, 48, 75, 73, 67, 74, 104, 98, 71, 99, 105, 79, 105, 74, 819 73, 85, 122, 73, 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 820 77, 105, 79, 105, 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 821 74, 108, 101, 72, 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 822 107, 122, 79, 68, 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 823 72, 65, 54, 76, 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 824 109, 78, 118, 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 825 106, 112, 48, 99, 110, 86, 108, 102, 81] 827 HMACs are generated using keys. This example uses the key 828 represented by the following byte array: 830 [3, 35, 53, 75, 43, 15, 165, 188, 131, 126, 6, 101, 119, 123, 166, 831 143, 90, 179, 40, 230, 240, 84, 201, 40, 169, 15, 132, 178, 210, 80, 832 46, 191, 211, 251, 90, 146, 210, 6, 71, 239, 150, 138, 180, 195, 119, 833 98, 61, 34, 61, 46, 33, 114, 5, 46, 79, 8, 192, 205, 154, 245, 103, 834 208, 128, 163] 836 Running the HMAC SHA-256 algorithm on the UTF-8 representation of the 837 JWS Secured Input with this key yields the following byte array: 839 [116, 24, 223, 180, 151, 153, 224, 37, 79, 250, 96, 125, 216, 173, 840 187, 186, 22, 212, 37, 77, 105, 214, 191, 240, 91, 88, 5, 88, 83, 841 132, 141, 121] 843 Base64url encoding the above HMAC output yields the Encoded JWS 844 Signature value: 845 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 847 A.1.2. Decoding 849 Decoding the JWS first requires removing the base64url encoding from 850 the Encoded JWS Header, the Encoded JWS Payload, and the Encoded JWS 851 Signature. We base64url decode the inputs and turn them into the 852 corresponding byte arrays. We translate the header input byte array 853 containing UTF-8 encoded characters into the JWS Header string. 855 A.1.3. Validating 857 Next we validate the decoded results. Since the "alg" parameter in 858 the header is "HS256", we validate the HMAC SHA-256 value contained 859 in the JWS Signature. If any of the validation steps fail, the JWS 860 MUST be rejected. 862 First, we validate that the JWS Header string is legal JSON. 864 To validate the HMAC value, we repeat the previous process of using 865 the correct key and the UTF-8 representation of the JWS Secured Input 866 as input to a SHA-256 HMAC function and then taking the output and 867 determining if it matches the JWS Signature. If it matches exactly, 868 the HMAC has been validated. 870 A.2. JWS using RSA SHA-256 872 A.2.1. Encoding 874 The JWS Header in this example is different from the previous example 875 in two ways: First, because a different algorithm is being used, the 876 "alg" value is different. Second, for illustration purposes only, 877 the optional "typ" parameter is not used. (This difference is not 878 related to the algorithm employed.) The JWS Header used is: 879 {"alg":"RS256"} 880 The following byte array contains the UTF-8 characters for the JWS 881 Header: 883 [123, 34, 97, 108, 103, 34, 58, 34, 82, 83, 50, 53, 54, 34, 125] 885 Base64url encoding this UTF-8 representation yields this Encoded JWS 886 Header value: 887 eyJhbGciOiJSUzI1NiJ9 889 The JWS Payload used in this example, which follows, is the same as 890 in the previous example. Since the Encoded JWS Payload will 891 therefore be the same, its computation is not repeated here. 892 {"iss":"joe", 893 "exp":1300819380, 894 "http://example.com/is_root":true} 896 Concatenating the Encoded JWS Header, a period character, and the 897 Encoded JWS Payload yields this JWS Secured Input value (with line 898 breaks for display purposes only): 899 eyJhbGciOiJSUzI1NiJ9 900 . 901 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 902 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 904 The UTF-8 representation of the JWS Secured Input is the following 905 byte array: 907 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 122, 73, 908 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, 909 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 74, 108, 101, 72, 910 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 107, 122, 79, 68, 911 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 72, 65, 54, 76, 912 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 109, 78, 118, 913 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48, 914 99, 110, 86, 108, 102, 81] 916 The RSA key consists of a public part (n, e), and a private exponent 917 d. The values of the RSA key used in this example, presented as the 918 byte arrays representing big endian integers are: 920 +-----------+-------------------------------------------------------+ 921 | Parameter | Value | 922 | Name | | 923 +-----------+-------------------------------------------------------+ 924 | n | [161, 248, 22, 10, 226, 227, 201, 180, 101, 206, 141, | 925 | | 45, 101, 98, 99, 54, 43, 146, 125, 190, 41, 225, 240, | 926 | | 36, 119, 252, 22, 37, 204, 144, 161, 54, 227, 139, | 927 | | 217, 52, 151, 197, 182, 234, 99, 221, 119, 17, 230, | 928 | | 124, 116, 41, 249, 86, 176, 251, 138, 143, 8, 154, | 929 | | 220, 75, 105, 137, 60, 193, 51, 63, 83, 237, 208, 25, | 930 | | 184, 119, 132, 37, 47, 236, 145, 79, 228, 133, 119, | 931 | | 105, 89, 75, 234, 66, 128, 211, 44, 15, 85, 191, 98, | 932 | | 148, 79, 19, 3, 150, 188, 110, 155, 223, 110, 189, | 933 | | 210, 189, 163, 103, 142, 236, 160, 198, 104, 247, 1, | 934 | | 179, 141, 191, 251, 56, 200, 52, 44, 226, 254, 109, | 935 | | 39, 250, 222, 74, 90, 72, 116, 151, 157, 212, 185, | 936 | | 207, 154, 222, 196, 199, 91, 5, 133, 44, 44, 15, 94, | 937 | | 248, 165, 193, 117, 3, 146, 249, 68, 232, 237, 100, | 938 | | 193, 16, 198, 182, 71, 96, 154, 164, 120, 58, 235, | 939 | | 156, 108, 154, 215, 85, 49, 48, 80, 99, 139, 131, | 940 | | 102, 92, 111, 111, 122, 130, 163, 150, 112, 42, 31, | 941 | | 100, 27, 130, 211, 235, 242, 57, 34, 25, 73, 31, 182, | 942 | | 134, 135, 44, 87, 22, 245, 10, 248, 53, 141, 154, | 943 | | 139, 157, 23, 195, 64, 114, 143, 127, 135, 216, 154, | 944 | | 24, 216, 252, 171, 103, 173, 132, 89, 12, 46, 207, | 945 | | 117, 147, 57, 54, 60, 7, 3, 77, 111, 96, 111, 158, | 946 | | 33, 224, 84, 86, 202, 229, 233, 161] | 947 | e | [1, 0, 1] | 948 | d | [18, 174, 113, 164, 105, 205, 10, 43, 195, 126, 82, | 949 | | 108, 69, 0, 87, 31, 29, 97, 117, 29, 100, 233, 73, | 950 | | 112, 123, 98, 89, 15, 157, 11, 165, 124, 150, 60, 64, | 951 | | 30, 63, 207, 47, 44, 211, 189, 236, 136, 229, 3, 191, | 952 | | 198, 67, 155, 11, 40, 200, 47, 125, 55, 151, 103, 31, | 953 | | 82, 19, 238, 216, 193, 90, 37, 216, 213, 206, 160, 2, | 954 | | 94, 227, 171, 46, 139, 127, 121, 33, 111, 198, 59, | 955 | | 234, 86, 39, 83, 180, 6, 68, 198, 161, 81, 39, 217, | 956 | | 178, 149, 69, 64, 160, 187, 225, 163, 5, 86, 152, 45, | 957 | | 78, 159, 222, 95, 100, 37, 241, 77, 75, 113, 52, 65, | 958 | | 181, 93, 199, 59, 155, 74, 237, 204, 146, 172, 227, | 959 | | 146, 126, 55, 245, 125, 12, 253, 94, 117, 129, 250, | 960 | | 81, 44, 143, 73, 97, 169, 235, 11, 128, 248, 168, 7, | 961 | | 70, 114, 138, 85, 255, 70, 71, 31, 52, 37, 6, 59, | 962 | | 157, 83, 100, 47, 94, 222, 30, 132, 214, 19, 8, 26, | 963 | | 250, 92, 34, 208, 81, 40, 91, 214, 59, 148, 59, 86, | 964 | | 93, 137, 138, 5, 104, 84, 19, 229, 60, 60, 108, 101, | 965 | | 37, 255, 31, 227, 78, 61, 220, 112, 240, 213, 100, | 966 | | 80, 253, 164, 139, 161, 46, 16, 78, 157, 235, 159, | 967 | | 184, 24, 129, 225, 196, 189, 242, 93, 146, 71, 244, | 968 | | 80, 200, 101, 146, 121, 104, 231, 115, 52, 244, 65, | 969 | | 79, 117, 167, 80, 225, 57, 84, 110, 58, 138, 115, | 970 | | 157] | 971 +-----------+-------------------------------------------------------+ 973 The RSA private key (n, d) is then passed to the RSA signing 974 function, which also takes the hash type, SHA-256, and the UTF-8 975 representation of the JWS Secured Input as inputs. The result of the 976 digital signature is a byte array S, which represents a big endian 977 integer. In this example, S is: 979 +--------+----------------------------------------------------------+ 980 | Result | Value | 981 | Name | | 982 +--------+----------------------------------------------------------+ 983 | S | [112, 46, 33, 137, 67, 232, 143, 209, 30, 181, 216, 45, | 984 | | 191, 120, 69, 243, 65, 6, 174, 27, 129, 255, 247, 115, | 985 | | 17, 22, 173, 209, 113, 125, 131, 101, 109, 66, 10, 253, | 986 | | 60, 150, 238, 221, 115, 162, 102, 62, 81, 102, 104, 123, | 987 | | 0, 11, 135, 34, 110, 1, 135, 237, 16, 115, 249, 69, 229, | 988 | | 130, 173, 252, 239, 22, 216, 90, 121, 142, 232, 198, | 989 | | 109, 219, 61, 184, 151, 91, 23, 208, 148, 2, 190, 237, | 990 | | 213, 217, 217, 112, 7, 16, 141, 178, 129, 96, 213, 248, | 991 | | 4, 12, 167, 68, 87, 98, 184, 31, 190, 127, 249, 217, 46, | 992 | | 10, 231, 111, 36, 242, 91, 51, 187, 230, 244, 74, 230, | 993 | | 30, 177, 4, 10, 203, 32, 4, 77, 62, 249, 18, 142, 212, | 994 | | 1, 48, 121, 91, 212, 189, 59, 65, 238, 202, 208, 102, | 995 | | 171, 101, 25, 129, 253, 228, 141, 247, 127, 55, 45, 195, | 996 | | 139, 159, 175, 221, 59, 239, 177, 139, 93, 163, 204, 60, | 997 | | 46, 176, 47, 158, 58, 65, 214, 18, 202, 173, 21, 145, | 998 | | 18, 115, 160, 95, 35, 185, 232, 56, 250, 175, 132, 157, | 999 | | 105, 132, 41, 239, 90, 30, 136, 121, 130, 54, 195, 212, | 1000 | | 14, 96, 69, 34, 165, 68, 200, 242, 122, 122, 45, 184, 6, | 1001 | | 99, 209, 108, 247, 202, 234, 86, 222, 64, 92, 178, 33, | 1002 | | 90, 69, 178, 194, 85, 102, 181, 90, 193, 167, 72, 160, | 1003 | | 112, 223, 200, 163, 42, 70, 149, 67, 208, 25, 238, 251, | 1004 | | 71] | 1005 +--------+----------------------------------------------------------+ 1007 Base64url encoding the digital signature produces this value for the 1008 Encoded JWS Signature (with line breaks for display purposes only): 1009 cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7 1010 AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4 1011 BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K 1012 0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqv 1013 hJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrB 1014 p0igcN_IoypGlUPQGe77Rw 1016 A.2.2. Decoding 1018 Decoding the JWS from this example requires processing the Encoded 1019 JWS Header and Encoded JWS Payload exactly as done in the first 1020 example. 1022 A.2.3. Validating 1024 Since the "alg" parameter in the header is "RS256", we validate the 1025 RSA SHA-256 digital signature contained in the JWS Signature. If any 1026 of the validation steps fail, the JWS MUST be rejected. 1028 First, we validate that the JWS Header string is legal JSON. 1030 Validating the JWS Signature is a little different from the previous 1031 example. First, we base64url decode the Encoded JWS Signature to 1032 produce a digital signature S to check. We then pass (n, e), S and 1033 the UTF-8 representation of the JWS Secured Input to an RSA signature 1034 verifier that has been configured to use the SHA-256 hash function. 1036 A.3. JWS using ECDSA P-256 SHA-256 1038 A.3.1. Encoding 1040 The JWS Header for this example differs from the previous example 1041 because a different algorithm is being used. The JWS Header used is: 1042 {"alg":"ES256"} 1044 The following byte array contains the UTF-8 characters for the JWS 1045 Header: 1047 [123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 50, 53, 54, 34, 125] 1049 Base64url encoding this UTF-8 representation yields this Encoded JWS 1050 Header value: 1051 eyJhbGciOiJFUzI1NiJ9 1053 The JWS Payload used in this example, which follows, is the same as 1054 in the previous examples. Since the Encoded JWS Payload will 1055 therefore be the same, its computation is not repeated here. 1056 {"iss":"joe", 1057 "exp":1300819380, 1058 "http://example.com/is_root":true} 1060 Concatenating the Encoded JWS Header, a period character, and the 1061 Encoded JWS Payload yields this JWS Secured Input value (with line 1062 breaks for display purposes only): 1063 eyJhbGciOiJFUzI1NiJ9 1064 . 1065 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1066 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1068 The UTF-8 representation of the JWS Secured Input is the following 1069 byte array: 1071 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 70, 85, 122, 73, 1072 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, 1073 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 74, 108, 101, 72, 1074 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 107, 122, 79, 68, 1075 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 72, 65, 54, 76, 1076 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 109, 78, 118, 1077 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48, 1078 99, 110, 86, 108, 102, 81] 1080 The ECDSA key consists of a public part, the EC point (x, y), and a 1081 private part d. The values of the ECDSA key used in this example, 1082 presented as the byte arrays representing big endian integers are: 1084 +-----------+-------------------------------------------------------+ 1085 | Parameter | Value | 1086 | Name | | 1087 +-----------+-------------------------------------------------------+ 1088 | x | [127, 205, 206, 39, 112, 246, 196, 93, 65, 131, 203, | 1089 | | 238, 111, 219, 75, 123, 88, 7, 51, 53, 123, 233, 239, | 1090 | | 19, 186, 207, 110, 60, 123, 209, 84, 69] | 1091 | y | [199, 241, 68, 205, 27, 189, 155, 126, 135, 44, 223, | 1092 | | 237, 185, 238, 185, 244, 179, 105, 93, 110, 169, 11, | 1093 | | 36, 173, 138, 70, 35, 40, 133, 136, 229, 173] | 1094 | d | [142, 155, 16, 158, 113, 144, 152, 191, 152, 4, 135, | 1095 | | 223, 31, 93, 119, 233, 203, 41, 96, 110, 190, 210, | 1096 | | 38, 59, 95, 87, 194, 19, 223, 132, 244, 178] | 1097 +-----------+-------------------------------------------------------+ 1099 The ECDSA private part d is then passed to an ECDSA signing function, 1100 which also takes the curve type, P-256, the hash type, SHA-256, and 1101 the UTF-8 representation of the JWS Secured Input as inputs. The 1102 result of the digital signature is the EC point (R, S), where R and S 1103 are unsigned integers. In this example, the R and S values, given as 1104 byte arrays representing big endian integers are: 1106 +--------+----------------------------------------------------------+ 1107 | Result | Value | 1108 | Name | | 1109 +--------+----------------------------------------------------------+ 1110 | R | [14, 209, 33, 83, 121, 99, 108, 72, 60, 47, 127, 21, 88, | 1111 | | 7, 212, 2, 163, 178, 40, 3, 58, 249, 124, 126, 23, 129, | 1112 | | 154, 195, 22, 158, 166, 101] | 1113 | S | [197, 10, 7, 211, 140, 60, 112, 229, 216, 241, 45, 175, | 1114 | | 8, 74, 84, 128, 166, 101, 144, 197, 242, 147, 80, 154, | 1115 | | 143, 63, 127, 138, 131, 163, 84, 213] | 1116 +--------+----------------------------------------------------------+ 1118 Concatenating the S array to the end of the R array and base64url 1119 encoding the result produces this value for the Encoded JWS Signature 1120 (with line breaks for display purposes only): 1121 DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSA 1122 pmWQxfKTUJqPP3-Kg6NU1Q 1124 A.3.2. Decoding 1126 Decoding the JWS from this example requires processing the Encoded 1127 JWS Header and Encoded JWS Payload exactly as done in the first 1128 example. 1130 A.3.3. Validating 1132 Since the "alg" parameter in the header is "ES256", we validate the 1133 ECDSA P-256 SHA-256 digital signature contained in the JWS Signature. 1134 If any of the validation steps fail, the JWS MUST be rejected. 1136 First, we validate that the JWS Header string is legal JSON. 1138 Validating the JWS Signature is a little different from the first 1139 example. First, we base64url decode the Encoded JWS Signature as in 1140 the previous examples but we then need to split the 64 member byte 1141 array that must result into two 32 byte arrays, the first R and the 1142 second S. We then pass (x, y), (R, S) and the UTF-8 representation of 1143 the JWS Secured Input to an ECDSA signature verifier that has been 1144 configured to use the P-256 curve with the SHA-256 hash function. 1146 As explained in Section 3.3 of the JSON Web Algorithms (JWA) [JWA] 1147 specification, the use of the k value in ECDSA means that we cannot 1148 validate the correctness of the digital signature in the same way we 1149 validated the correctness of the HMAC. Instead, implementations MUST 1150 use an ECDSA validator to validate the digital signature. 1152 A.4. Example Plaintext JWS 1154 The following example JWS Header declares that the encoded object is 1155 a Plaintext JWS: 1156 {"alg":"none"} 1158 Base64url encoding the bytes of the UTF-8 representation of the JWS 1159 Header yields this Encoded JWS Header: 1160 eyJhbGciOiJub25lIn0 1162 The JWS Payload used in this example, which follows, is the same as 1163 in the previous examples. Since the Encoded JWS Payload will 1164 therefore be the same, its computation is not repeated here. 1165 {"iss":"joe", 1166 "exp":1300819380, 1167 "http://example.com/is_root":true} 1169 The Encoded JWS Signature is the empty string. 1171 Concatenating these parts in the order Header.Payload.Signature with 1172 period characters between the parts yields this complete JWS (with 1173 line breaks for display purposes only): 1174 eyJhbGciOiJub25lIn0 1175 . 1176 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1177 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1178 . 1180 Appendix B. Notes on implementing base64url encoding without padding 1182 This appendix describes how to implement base64url encoding and 1183 decoding functions without padding based upon standard base64 1184 encoding and decoding functions that do use padding. 1186 To be concrete, example C# code implementing these functions is shown 1187 below. Similar code could be used in other languages. 1188 static string base64urlencode(byte [] arg) 1189 { 1190 string s = Convert.ToBase64String(arg); // Standard base64 encoder 1191 s = s.Split('=')[0]; // Remove any trailing '='s 1192 s = s.Replace('+', '-'); // 62nd char of encoding 1193 s = s.Replace('/', '_'); // 63rd char of encoding 1194 return s; 1195 } 1197 static byte [] base64urldecode(string arg) 1198 { 1199 string s = arg; 1200 s = s.Replace('-', '+'); // 62nd char of encoding 1201 s = s.Replace('_', '/'); // 63rd char of encoding 1202 switch (s.Length % 4) // Pad with trailing '='s 1203 { 1204 case 0: break; // No pad chars in this case 1205 case 2: s += "=="; break; // Two pad chars 1206 case 3: s += "="; break; // One pad char 1207 default: throw new System.Exception( 1208 "Illegal base64url string!"); 1209 } 1210 return Convert.FromBase64String(s); // Standard base64 decoder 1211 } 1213 As per the example code above, the number of '=' padding characters 1214 that needs to be added to the end of a base64url encoded string 1215 without padding to turn it into one with padding is a deterministic 1216 function of the length of the encoded string. Specifically, if the 1217 length mod 4 is 0, no padding is added; if the length mod 4 is 2, two 1218 '=' padding characters are added; if the length mod 4 is 3, one '=' 1219 padding character is added; if the length mod 4 is 1, the input is 1220 malformed. 1222 An example correspondence between unencoded and encoded values 1223 follows. The byte sequence below encodes into the string below, 1224 which when decoded, reproduces the byte sequence. 1225 3 236 255 224 193 1226 A-z_4ME 1228 Appendix C. Acknowledgements 1230 Solutions for signing JSON content were previously explored by Magic 1231 Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas 1232 Applications [CanvasApp], all of which influenced this draft. Dirk 1233 Balfanz, Yaron Y. Goland, John Panzer, and Paul Tarjan all made 1234 significant contributions to the design of this specification. 1236 Appendix D. Document History 1238 -01 1240 o Moved definition of Plaintext JWSs (using "alg":"none") here from 1241 the JWT specification since this functionality is likely to be 1242 useful in more contexts that just for JWTs. 1244 o Added "jpk" and "x5c" header parameters for including JWK public 1245 keys and X.509 certificate chains directly in the header. 1247 o Clarified that this specification is defining the JWS Compact 1248 Serialization. Referenced the new JWS-JS spec, which defines the 1249 JWS JSON Serialization. 1251 o Added text "New header parameters should be introduced sparingly 1252 since an implementation that does not understand a parameter MUST 1253 reject the JWS". 1255 o Clarified that the order of the creation and validation steps is 1256 not significant in cases where there are no dependencies between 1257 the inputs and outputs of the steps. 1259 o Changed "no canonicalization is performed" to "no canonicalization 1260 need be performed". 1262 o Corrected the Magic Signatures reference. 1264 o Made other editorial improvements suggested by JOSE working group 1265 participants. 1267 -00 1269 o Created the initial IETF draft based upon 1270 draft-jones-json-web-signature-04 with no normative changes. 1272 o Changed terminology to no longer call both digital signatures and 1273 HMACs "signatures". 1275 Authors' Addresses 1277 Michael B. Jones 1278 Microsoft 1280 Email: mbj@microsoft.com 1281 URI: http://self-issued.info/ 1283 John Bradley 1284 independent 1286 Email: ve7jtb@ve7jtb.com 1288 Nat Sakimura 1289 Nomura Research Institute 1291 Email: n-sakimura@nri.co.jp