idnits 2.17.1 draft-jones-json-web-token-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 : ---------------------------------------------------------------------------- ** There are 10 instances of too long lines in the document, the longest one being 270 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (December 28, 2010) is 4869 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 1138 -- Looks like a reference, but probably isn't: '34' on line 1138 -- Looks like a reference, but probably isn't: '97' on line 1138 -- Looks like a reference, but probably isn't: '108' on line 1138 -- Looks like a reference, but probably isn't: '103' on line 1138 -- Looks like a reference, but probably isn't: '58' on line 1138 -- Looks like a reference, but probably isn't: '82' on line 990 -- Looks like a reference, but probably isn't: '83' on line 1138 -- Looks like a reference, but probably isn't: '50' on line 1138 -- Looks like a reference, but probably isn't: '53' on line 1138 -- Looks like a reference, but probably isn't: '54' on line 1138 -- Looks like a reference, but probably isn't: '125' on line 1138 -- Looks like a reference, but probably isn't: '1' on line 1026 -- Looks like a reference, but probably isn't: '0' on line 1236 -- Looks like a reference, but probably isn't: '69' on line 1138 ** Downref: Normative reference to an Informational RFC: RFC 2104 ** Obsolete normative reference: RFC 3447 (Obsoleted by RFC 8017) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) -- Possible downref: Non-RFC (?) normative reference: ref. 'USA15' Summary: 5 errors (**), 0 flaws (~~), 1 warning (==), 17 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track D. Balfanz 5 Expires: July 1, 2011 Google 6 J. Bradley 7 independent 8 Y. Goland 9 Microsoft 10 J. Panzer 11 Google 12 N. Sakimura 13 Nomura Research Institute 14 December 28, 2010 16 JSON Web Token (JWT) 17 draft-jones-json-web-token-00 19 Abstract 21 JSON Web Token (JWT) defines a token format that can encode claims 22 transferred between two parties. The claims in a JWT are encoded as 23 a JSON object that is digitally signed. 25 Requirements Language 27 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 28 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 29 document are to be interpreted as described in RFC 2119 [RFC2119]. 31 Status of this Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at http://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on July 1, 2011. 48 Copyright Notice 49 Copyright (c) 2010 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 66 3. JSON Web Token (JWT) Overview . . . . . . . . . . . . . . . . 6 67 3.1. Example JWT . . . . . . . . . . . . . . . . . . . . . . . 6 68 4. JWT Claims . . . . . . . . . . . . . . . . . . . . . . . . . . 7 69 4.1. Reserved Claim Names . . . . . . . . . . . . . . . . . . . 7 70 4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 9 71 4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 9 72 5. JWT Envelope . . . . . . . . . . . . . . . . . . . . . . . . . 10 73 5.1. Reserved Envelope Parameter Names . . . . . . . . . . . . 10 74 5.2. Public Envelope Parameter Names . . . . . . . . . . . . . 12 75 5.3. Private Envelope Parameter Names . . . . . . . . . . . . . 12 76 6. General Rules for Creating and Validating a JWT . . . . . . . 12 77 7. Base64url encoding as used by JWTs . . . . . . . . . . . . . . 14 78 8. Signing JWTs with Cryptographic Algorithms . . . . . . . . . . 15 79 8.1. Signing a JWT with HMAC SHA-256 . . . . . . . . . . . . . 15 80 8.2. Signing a JWT with RSA SHA-256 . . . . . . . . . . . . . . 16 81 8.3. Signing a JWT with ECDSA P-256 SHA-256 . . . . . . . . . . 17 82 8.4. Additional Algorithms . . . . . . . . . . . . . . . . . . 19 83 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 84 10. Security Considerations . . . . . . . . . . . . . . . . . . . 20 85 10.1. Unicode Comparison Security Issues . . . . . . . . . . . . 20 86 11. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 21 87 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 21 88 13. Appendix - Non-Normative - JWT Examples . . . . . . . . . . . 21 89 13.1. JWT using HMAC SHA-256 . . . . . . . . . . . . . . . . . . 21 90 13.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . 21 91 13.1.2. Decoding . . . . . . . . . . . . . . . . . . . . . . 23 92 13.1.3. Validating . . . . . . . . . . . . . . . . . . . . . 23 93 13.2. JWT using RSA SHA-256 . . . . . . . . . . . . . . . . . . 23 94 13.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . 23 95 13.2.2. Decoding . . . . . . . . . . . . . . . . . . . . . . 26 96 13.2.3. Validating . . . . . . . . . . . . . . . . . . . . . 27 97 13.3. JWT using ECDSA P-256 SHA-256 . . . . . . . . . . . . . . 27 98 13.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . 27 99 13.3.2. Decoding . . . . . . . . . . . . . . . . . . . . . . 29 100 13.3.3. Validating . . . . . . . . . . . . . . . . . . . . . 29 101 14. Appendix - Non-Normative - Notes on implementing base64url 102 encoding without padding . . . . . . . . . . . . . . . . . . . 29 103 15. Appendix - Non-Normative - Relationship of JWTs to SAML 104 Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 105 16. Appendix - Non-Normative - Relationship of JWTs to Simple 106 Web Tokens (SWTs) . . . . . . . . . . . . . . . . . . . . . . 31 107 17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 31 108 17.1. Normative References . . . . . . . . . . . . . . . . . . . 31 109 17.2. Informative References . . . . . . . . . . . . . . . . . . 32 111 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 33 113 1. Introduction 115 JSON Web Token (JWT) is a simple token format intended for space 116 constrained environments such as HTTP Authorization headers and URI 117 query parameters. JWTs encode the claims to be transmitted as a JSON 118 object (as defined in RFC 4627 [RFC4627]) that is base64url encoded 119 and digitally signed. 121 The suggested pronunciation of JWT is the same as the English word 122 "jot". 124 2. Terminology 126 JSON Web Token (JWT) A string consisting of three JWT Token 127 Segments: the JWT Envelope Segment, the JWT Claim Segment, and the 128 JWT Crypto Segment, in that order, with the segments being 129 separated by period ('.') characters. 131 JWT Token Segment One of the three parts that make up a JSON Web 132 Token (JWT). JWT Token Segments are always base64url encoded 133 values. 135 JWT Envelope Segment A JWT Token Segment containing a base64url 136 encoded JSON object that describes the signature applied to the 137 JWT Claim Segment. 139 JWT Claim Segment A JWT Token Segment containing a base64url encoded 140 JSON object that encodes the claims represented by the JWT. 142 JWT Crypto Segment A JWT Token Segment containing base64url encoded 143 cryptographic signature material that secures the JWT Crypto 144 Segment's contents. 146 Decoded JWT Envelope Segment A JWT Envelope Segment that has been 147 base64url decoded back into a JSON object. 149 Decoded JWT Claim Segment A JWT Claim Segment that has been 150 base64url decoded back into a JSON object. 152 Decoded JWT Crypto Segment A JWT Crypto Segment that has been 153 base64url decoded back into cryptographic material. 155 Base64url Encoding For the purposes of this specification, this term 156 always refers to the he URL- and filename-safe Base64 encoding 157 described in RFC 4648 [RFC4648], Section 5, with the '=' padding 158 characters omitted, as permitted by Section 3.2; see Section 7 for 159 more details. 161 3. JSON Web Token (JWT) Overview 163 JWTs represent a set of claims as a JSON object that is base64url 164 encoded and digitally signed. As per RFC 4627 [RFC4627] Section 2.2, 165 the JSON object consists of zero or more name/value pairs (or 166 members), where the names are strings and the values are arbitrary 167 JSON values. These members are the claims represented by the JWT. 168 The JSON object is base64url encoded to produce the JWT Claim 169 Segment. An accompanying base64url encoded JSON envelope object 170 describes the signature method used. 172 The names within the object MUST be unique. The names within the 173 JSON object are referred to as Claim Names. The corresponding values 174 are referred to as Claim Values. 176 JWTs contain a signature that ensures the integrity of the content of 177 the JSON Claim Segment. This signature value is carried in the JWT 178 Crypto Segment. The JSON Envelope object MUST contain an "alg" 179 parameter, the value of which is a string that unambiguously 180 identifies the algorithm used to sign the JWT Claim Segment to 181 produce the JWT Crypto Segment. 183 3.1. Example JWT 185 The following is an example of a JSON object that can be encoded to 186 produce a JWT: 187 {"iss":"joe", 188 "exp":1300819380, 189 "http://example.com/is_root":true} 191 Base64url encoding the UTF-8 representation of the JSON object yields 192 this JWT Claim Segment value: 193 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 195 The following example JSON envelope object declares that the encoded 196 object is a JSON Web Token (JWT) and the JWT Claim Segment is signed 197 using the HMAC SHA-256 algorithm: 198 {"typ":"JWT", 199 "alg":"HS256"} 201 Base64url encoding the UTF-8 representation of the JSON envelope 202 object yields this JWT Envelope Segment value: 203 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 205 Signing the JWT Claim Segment with the HMAC SHA-256 algorithm and 206 base64url encoding the result, as per Section 8.1, yields this JWT 207 Crypto Segment value: 208 35usWj9X8HwGS-CDcx1JP2NmqcrLwZ4EKp8sNThf3cY 209 Combining these segments in the order Envelope.Claims.Signature with 210 period characters between the segments yields this complete JWT (with 211 line breaks for display purposes only): 212 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 213 . 214 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 215 . 216 35usWj9X8HwGS-CDcx1JP2NmqcrLwZ4EKp8sNThf3cY 218 This computation is illustrated in more detail in Section 13.1. 220 4. JWT Claims 222 The members of the JSON object represented by the Decoded JWT Claim 223 Segment contain the claims. Note however, that the set of claims a 224 JWT must contain to be considered valid is context-dependent and is 225 outside the scope of this specification. 227 There are three classes of JWT Claim Names: Reserved Claim Names, 228 Public Claim Names, and Private Claim Names. 230 4.1. Reserved Claim Names 232 The following claim names are reserved. None of the claims defined 233 in the table below are intended to be mandatory, but rather, provide 234 a starting point for a set of useful, interoperable claims. All the 235 names are short because a core goal of JWTs is for the tokens 236 themselves to be short. 238 +-------+---------+--------------+----------------------------------+ 239 | Claim | JSON | Claim Syntax | Claim Semantics | 240 | Name | Value | | | 241 | | Type | | | 242 +-------+---------+--------------+----------------------------------+ 243 | exp | integer | IntDate | The "exp" (expiration time) | 244 | | | | claim identifies the expiration | 245 | | | | time on or after which the token | 246 | | | | MUST NOT be accepted for | 247 | | | | processing. The processing of | 248 | | | | the "exp" claim requires that | 249 | | | | the current date/time MUST be | 250 | | | | before the expiration date/time | 251 | | | | listed in the "exp" claim. | 252 | | | | Implementers MAY provide for | 253 | | | | some small leeway, usually no | 254 | | | | more than a few minutes, to | 255 | | | | account for clock skew. This | 256 | | | | claim is OPTIONAL. | 257 | iss | string | StringAndURI | The "iss" (issuer) claim | 258 | | | | identifies the principal that | 259 | | | | issued the JWT. The processing | 260 | | | | of this claim is generally | 261 | | | | application specific. This | 262 | | | | claim is OPTIONAL. | 263 | aud | string | StringAndURI | The "aud" (audience) claim | 264 | | | | identifies the audience that the | 265 | | | | JWT is intended for. The | 266 | | | | processing of this claim | 267 | | | | requires that if a JWT consumer | 268 | | | | receives a JWT with an "aud" | 269 | | | | value that does not identify | 270 | | | | itself as the JWT audience, then | 271 | | | | the JWT MUST be rejected. The | 272 | | | | interpretation of the audience | 273 | | | | value is generally application | 274 | | | | specific. This claim is | 275 | | | | OPTIONAL. | 276 | typ | string | StringAndURI | The "typ" (type) claim is used | 277 | | | | to declare a type for the | 278 | | | | contents this JWT. The value | 279 | | | | MAY be a MIME [RFC2045] type. | 280 | | | | This claim is OPTIONAL. | 281 +-------+---------+--------------+----------------------------------+ 283 Table 1: Reserved Claim Definitions 285 Additional reserved claim names MAY be defined via the IANA JSON Web 286 Token Claims registry, as per Section 9. The syntaxes referred to 287 above are: 289 +--------------+----------------------------------------------------+ 290 | Syntax Name | Syntax Definition | 291 +--------------+----------------------------------------------------+ 292 | StringAndURI | Any string value MAY be used but a value | 293 | | containing a ":" character MUST be a URI as | 294 | | defined in RFC 3986 [RFC3986]. | 295 | URI | A URI as defined in RFC 3986 [RFC3986]. | 296 | IntDate | The number of seconds from 1970-01-01T0:0:0Z as | 297 | | measured in UTC until the desired date/time. See | 298 | | RFC 3339 [RFC3339] for details regarding | 299 | | date/times in general and UTC in particular. | 300 +--------------+----------------------------------------------------+ 302 Table 2 304 4.2. Public Claim Names 306 Claim names can be defined at will by those using JWTs. However, in 307 order to prevent collisions, any new claim name SHOULD either be 308 defined in the IANA JSON Web Token Claims registry or be defined as a 309 URI that contains a collision resistant namespace. Examples of 310 collision resistant namespaces include: 312 o Domain Names, 314 o Object Identifiers (OIDs) as defined in the ITU-T X 660 and X 670 315 Recommendation series or 317 o Universally Unique IDentifier (UUID) as defined in RFC 4122 318 [RFC4122]. 320 In each case, the definer of the name or value MUST take reasonable 321 precautions to make sure they are in control of the part of the 322 namespace they use to define the claim name. 324 4.3. Private Claim Names 326 A producer and consumer of a JWT may agree to any claim name that is 327 not a Reserved Name Section 4.1 or a Public Name Section 4.2. Unlike 328 Public Names, these private names are subject to collision and should 329 be used with caution. 331 5. JWT Envelope 333 The members of the JSON object represented by the Decoded JWT 334 Envelope Segment describe the signature applied to the JWT Claim 335 Segment and optionally additional properties of the JWT. 336 Implementations MUST understand the entire contents of the envelope; 337 otherwise, the JWT MUST be rejected for processing. 339 5.1. Reserved Envelope Parameter Names 341 The following envelope parameter names are reserved. All the names 342 are short because a core goal of JWTs is for the tokens themselves to 343 be short. 345 +-----------+--------+--------------+-------------------------------+ 346 | Envelope | JSON | Envelope | Envelope Parameter Semantics | 347 | Parameter | Value | Parameter | | 348 | Name | Type | Syntax | | 349 +-----------+--------+--------------+-------------------------------+ 350 | alg | string | StringAndURI | The "alg" (algorithm) | 351 | | | | envelope parameter identifies | 352 | | | | the cryptographic algorithm | 353 | | | | used to secure the JWT. A | 354 | | | | list of reserved alg values | 355 | | | | is in Table 4. The | 356 | | | | processing of the "alg" | 357 | | | | (algorithm) envelope | 358 | | | | parameter, if present, | 359 | | | | requires that the value of | 360 | | | | the "alg" envelope parameter | 361 | | | | MUST be one that is both | 362 | | | | supported and for which there | 363 | | | | exists a key for use with | 364 | | | | that algorithm associated | 365 | | | | with the issuer of the JWT. | 366 | | | | Note however, that if the | 367 | | | | "iss" (issuer) claim is not | 368 | | | | included in the JWT Claim | 369 | | | | Segment, then the manner in | 370 | | | | which the issuer is | 371 | | | | determined is application | 372 | | | | specific. This envelope | 373 | | | | parameter is REQUIRED. | 374 | typ | string | StringAndURI | The "typ" (type) envelope | 375 | | | | parameter is used to declare | 376 | | | | that this data structure is a | 377 | | | | JWT. If a "typ" parameter is | 378 | | | | present, its value MUST be | 379 | | | | "JWT". This envelope | 380 | | | | parameter is OPTIONAL. | 381 | | | | (Non-normative note: Other | 382 | | | | values could be used by other | 383 | | | | specifications to declare | 384 | | | | data structures other than | 385 | | | | JWTs, for instance, encrypted | 386 | | | | JSON tokens.) | 387 | keyid | string | String | The "keyid" (key ID) envelope | 388 | | | | parameter is a hint | 389 | | | | indicating which specific key | 390 | | | | owned by the signer should be | 391 | | | | used to validate the | 392 | | | | signature. This allows | 393 | | | | signers to explicitly signal | 394 | | | | a change of key to | 395 | | | | recipients. Omitting this | 396 | | | | parameter is equivalent to | 397 | | | | setting it to an empty | 398 | | | | string. The format of this | 399 | | | | parameter is unspecified. | 400 | | | | This envelope parameter is | 401 | | | | OPTIONAL. | 402 | curi | string | URI | The "curi" (certificates URI) | 403 | | | | envelope parameter is a URI | 404 | | | | that points to X.509 public | 405 | | | | key certificates that can be | 406 | | | | used to validate the | 407 | | | | signature. This envelope | 408 | | | | parameter is OPTIONAL. | 409 | ctp | string | String | The "ctp" (certificate | 410 | | | | thumbprint) envelope | 411 | | | | parameter provides a | 412 | | | | base64url encoded SHA-1 | 413 | | | | thumbprint of the DER | 414 | | | | encoding of a certificate | 415 | | | | that can be used to validate | 416 | | | | the signature. This envelope | 417 | | | | parameter is OPTIONAL. | 418 +-----------+--------+--------------+-------------------------------+ 420 Table 3: Reserved Envelope Parameter Definitions 422 Additional reserved envelope parameter names MAY be defined via the 423 IANA JSON Web Token Envelope Parameters registry, as per Section 9. 424 The envelope value syntaxes referred to above are defined in Table 2. 426 5.2. Public Envelope Parameter Names 428 Additional envelope parameter names can be defined by those using 429 JWTs. However, in order to prevent collisions, any new envelope 430 parameter name or algorithm value SHOULD either be defined in the 431 IANA JSON Web Token Envelope Parameters registry or be defined as a 432 URI that contains a collision resistant namespace. In each case, the 433 definer of the name or value MUST take reasonable precautions to make 434 sure they are in control of the part of the namespace they use to 435 define the envelope parameter name. 437 New envelope parameters should be introduced sparingly, as they can 438 result in non-interoperable JWTs. Nonetheless, some extensions 439 needed for some use cases may require them, such as an extension to 440 enable the inclusion of multiple signatures. 442 5.3. Private Envelope Parameter Names 444 A producer and consumer of a JWT may agree to any envelope parameter 445 name that is not a Reserved Name Section 5.1 or a Public Name 446 Section 5.2. Unlike Public Names, these private names are subject to 447 collision and should be used with caution. 449 New envelope parameters should be introduced sparingly, as they can 450 result in non-interoperable JWTs. 452 6. General Rules for Creating and Validating a JWT 454 To create a JWT one MUST follow these steps: 456 1. Create a JSON object containing the desired claims. Note that 457 white space is explicitly allowed in the representation and no 458 canonicalization is performed before encoding. 460 2. Translate this JSON object's Unicode code points into UTF-8, as 461 defined in RFC 3629 [RFC3629]. 463 3. Base64url encode the UTF-8 representation of this JSON object as 464 defined in this specification (without padding). This encoding 465 becomes the JWT Claim Segment. 467 4. Create a different JSON object containing the desired envelope 468 parameters. Note that white space is explicitly allowed in the 469 representation and no canonicalization is performed before 470 encoding. 472 5. Translate this JSON object's Unicode code points into UTF-8, as 473 defined in RFC 3629 [RFC3629]. 475 6. Base64url encode the UTF-8 representation of this JSON object as 476 defined in this specification (without padding). This encoding 477 becomes the JWT Envelope Segment. 479 7. Construct the JWT Crypto Segment as defined for the particular 480 algorithm being used. The "alg" envelope parameter MUST be 481 present in the JSON Envelope Segment, with the algorithm value 482 accurately representing the algorithm used to construct the JWT 483 Crypto Segment. 485 8. Combine the JWT Envelope Segment, the JWT Claim Segment and then 486 the JWT Crypto Segment in that order, separating each by period 487 characters, to create the JWT. 489 When validating a JWT the following steps MUST be taken. If any of 490 the listed steps fails then the token MUST be rejected for 491 processing. 493 1. The JWT MUST contain two period characters. 495 2. The JWT MUST be split on the two period characters resulting in 496 three non-empty segments. The first segment is the JWT Envelope 497 Segment; the second is the JWT Claim Segment; the third is the 498 JWT Crypto Segment. 500 3. The JWT Envelope Segment MUST be successfully base64url decoded 501 following the restriction given in this spec that no padding 502 characters may have been used. 504 4. The Decoded JWT Envelope Segment MUST be completely valid JSON 505 syntax. 507 5. The JWT Claim Segment MUST be successfully base64url decoded 508 following the restriction given in this spec that no padding 509 characters may have been used. 511 6. The Decoded JWT Claim Segment MUST be completely valid JSON 512 syntax. 514 7. The JWT Crypto Segment MUST be successfully base64url decoded 515 following the restriction given in this spec that no padding 516 characters may have been used. 518 8. The JWT Envelope Segment MUST be validated to only include 519 parameters and values whose syntax and semantics are both 520 understood and supported. 522 9. When used in a security-related context, the JWT Claim Segment 523 MUST be validated to only include claims whose syntax and 524 semantics are both understood and supported. 526 10. The JWT Crypto Segment MUST be successfully validated against 527 the JWT Claim Segment in the manner defined for the algorithm 528 being used, which MUST be accurately represented by the value of 529 the "alg" envelope parameter, which MUST be present. 531 Processing a JWT inevitably requires comparing known strings to 532 values in the token. For example, in checking what the algorithm is, 533 the Unicode string encoding "alg" will be checked against the member 534 names in the Decoded JWT Envelope Segment to see if there is a 535 matching envelope parameter name. A similar process occurs when 536 determining if the value of the "alg" envelope parameter represents a 537 supported algorithm. Comparing Unicode strings, however, has 538 significant security implications, as per Section 10. 540 Comparisons between JSON strings and other Unicode strings MUST be 541 performed as specified below: 543 1. Remove any JSON applied escaping to produce an array of Unicode 544 code points. 546 2. Unicode Normalization [USA15] MUST NOT be applied at any point to 547 either the JSON string or to the string it is to be compared 548 against. 550 3. Comparisons between the two strings MUST be performed as a 551 Unicode code point to code point equality comparison. 553 7. Base64url encoding as used by JWTs 555 JWTs make use of the base64url encoding as defined in RFC 4648 556 [RFC4648]. As allowed by Section 3.2 of the RFC, this specification 557 mandates that base64url encoding when used with JWTs MUST NOT use 558 padding. The reason for this restriction is that the padding 559 character ('=') is not URL safe. 561 For notes on implementing base64url encoding without padding, see 562 Section 14. 564 8. Signing JWTs with Cryptographic Algorithms 566 JWTs use specific cryptographic algorithms to sign the contents of 567 the JWT Claim Segment. The use of the following algorithms for 568 producing JWTs is defined in this section. The table below is the 569 list of "alg" envelope parameter values reserved by this 570 specification, each of which is explained in more detail in the 571 following sections: 573 +-----------------+-------------------------------------------------+ 574 | Alg Claim Value | Algorithm | 575 +-----------------+-------------------------------------------------+ 576 | HS256 | HMAC using SHA-256 hash algorithm | 577 | HS384 | HMAC using SHA-384 hash algorithm | 578 | HS512 | HMAC using SHA-512 hash algorithm | 579 | RS256 | RSA using SHA-256 hash algorithm | 580 | RS384 | RSA using SHA-384 hash algorithm | 581 | RS512 | RSA using SHA-512 hash algorithm | 582 | ES256 | ECDSA using P-256 curve and SHA-256 hash | 583 | | algorithm | 584 | ES384 | ECDSA using P-384 curve and SHA-384 hash | 585 | | algorithm | 586 | ES512 | ECDSA using P-521 curve and SHA-512 hash | 587 | | algorithm | 588 +-----------------+-------------------------------------------------+ 590 Table 4: JSON Web Token Reserved Algorithm Values 592 Of these algorithms, only HMAC SHA-256 and RSA SHA-256 MUST be 593 implemented. It is RECOMMENDED that implementations also implement 594 at least the ECDSA P-256 SHA-256 algorithm. 596 8.1. Signing a JWT with HMAC SHA-256 598 Hash based Message Authentication Codes (HMACs) enable one to use a 599 secret plus a cryptographic hash function to generate a Message 600 Authentication Code (MAC). This can be used to demonstrate that the 601 MAC matches the hashed content, in this case the JWT Claim Segment, 602 which therefore demonstrates that whoever generated the MAC was in 603 possession of the secret. 605 The algorithm for implementing and validating HMACs is provided in 606 RFC 2104 [RFC2104]. Although any HMAC can be used with JWTs, this 607 section defines the use of the SHA-256 cryptographic hash function as 608 defined in FIPS 180-3 [FIPS.180-3]. The reserved "alg" envelope 609 parameter value "HS256" is used in the JWT Envelope Segment to 610 indicate that the JWT Crypto Segment contains a base64url encoded 611 HMAC SHA-256 HMAC value. 613 The HMAC SHA-256 MAC is generated as follows: 615 1. Take the bytes of the UTF-8 representation of the JWT Claim 616 Segment and execute the HMAC SHA-256 algorithm on them using the 617 shared key to produce an HMAC. 619 2. Base64url encode the HMAC as defined in this document. 621 The output is placed in the JWT Crypto Segment for that JWT. 623 The HMAC SHA-256 MAC on a JWT is validated as follows: 625 1. Take the bytes of the UTF-8 representation of the JWT Claim 626 Segment and calculate an HMAC SHA-256 MAC on them using the 627 shared key. 629 2. Base64url encode the previously generated HMAC as defined in this 630 document. 632 3. If the JWT Crypto Segment and the previously calculated value 633 exactly match in a character by character, case sensitive 634 comparison, then one has confirmation that the key was used to 635 generate the HMAC on the JWT and that the contents of the JWT 636 Claim Segment have not be tampered with. 638 4. If the validation fails, the token MUST be rejected. 640 Signing with the HMAC SHA-384 and HMAC SHA-512 algorithms is 641 performed identically to the procedure for HMAC SHA-256 - just with 642 correspondingly longer key and result values. 644 JWT implementations MUST support the HMAC SHA-256 algorithm. Support 645 for the HMAC SHA-384 and HMAC SHA-512 algorithms is OPTIONAL. 647 8.2. Signing a JWT with RSA SHA-256 649 This section defines the use of the RSASSA-PKCS1-v1_5 signature 650 algorithm as defined in RFC 3447 [RFC3447], Section 8.2 (commonly 651 known as PKCS#1), using SHA-256 as the hash function. Note that the 652 use of the RSASSA-PKCS1-v1_5 algorithm is permitted in FIPS 186-3 653 [FIPS.186-3], Section 5.5, as is the SHA-256 cryptographic hash 654 function, which is defined in FIPS 180-3 [FIPS.180-3]. The reserved 655 "alg" envelope parameter value "RS256" is used in the JWT Envelope 656 Segment to indicate that the JWT Crypto Segment contains an RSA SHA- 657 256 signature. 659 A 2048-bit or longer key length MUST be used with this algorithm. 661 The RSA SHA-256 signature is generated as follows: 663 1. Let K be the signer's RSA private key and let M be the bytes of 664 the UTF-8 representation of the JWT Claim Segment. 666 2. Compute the octet string S = RSASSA-PKCS1-V1_5-SIGN (K, M). 668 3. Base64url encode the octet string S, as defined in this document. 670 The output is placed in the JWT Crypto Segment for that JWT. 672 The RSA SHA-256 signature on a JWT is validated as follows: 674 1. Take the JWT Crypto Segment and base64url decode it into an octet 675 string S. If decoding fails, then the token MUST be rejected. 677 2. Let M be the bytes of the UTF-8 representation of the JWT Claim 678 Segment and let (n, e) be the public key corresponding to the 679 private key used by the signer. 681 3. Validate the signature with RSASSA-PKCS1-V1_5-VERIFY ((n, e), M, 682 S). 684 4. If the validation fails, the token MUST be rejected. 686 Signing with the RSA SHA-384 and RSA SHA-512 algorithms is performed 687 identically to the procedure for RSA SHA-256 - just with 688 correspondingly longer key and result values. 690 JWT implementations MUST support the RSA SHA-256 algorithm. Support 691 for the RSA SHA-384 and RSA SHA-512 algorithms is OPTIONAL. 693 8.3. Signing a JWT with ECDSA P-256 SHA-256 695 The Elliptic Curve Digital Signature Algorithm (ECDSA) is defined by 696 FIPS 186-3 [FIPS.186-3]. ECDSA provides for the use of Elliptic 697 Curve cryptography, which is able to provide equivalent security to 698 RSA cryptography but using shorter key lengths and with greater 699 processing speed. This means that ECDSA signatures will be 700 substantially smaller in terms of length than equivalently strong RSA 701 Digital Signatures. 703 This specification defines the use of ECDSA with the P-256 curve and 704 the SHA-256 cryptographic hash function. The P-256 curve is also 705 defined in FIPS 186-3. The reserved "alg" envelope parameter value 706 "ES256" is used in the JWT Envelope Segment to indicate that the JWT 707 Crypto Segment contains a ECDSA P-256 SHA-256 signature. 709 A JWT is signed with an ECDSA P-256 SHA-256 signature as follows: 711 1. Take the bytes of the UTF-8 representation of the JWT Claim 712 Segment and generate a digital signature of them using ECDSA 713 P-256 SHA-256 with the desired private key. The output will be 714 the EC point (R, S), where R and S are unsigned integers. 716 2. Turn R and S into byte arrays in big endian order. Each array 717 will be 32 bytes long. 719 3. Concatenate the two byte arrays in the order R and then S. 721 4. Base64url encode the 64 byte array as defined in this 722 specification. 724 The output becomes the JWT Crypto Segment for the JWT. 726 The following procedure is used to validate the ECDSA signature of a 727 JWT: 729 1. Take the JWT Crypto Segment and base64url decode it into a byte 730 array. If decoding fails, the token MUST be rejected. 732 2. The output of the base64url decoding MUST be a 64 byte array. 734 3. Split the 64 byte array into two 32 byte arrays. The first array 735 will be R and the second S. Remember that the byte arrays are in 736 big endian byte order; please check the ECDSA validator in use to 737 see what byte order it requires. 739 4. Submit the bytes of the UTF-8 representation of the JWT Claim 740 Segment, R, S and the public key (x, y) to the ECDSA P-256 SHA- 741 256 validator. 743 5. If the validation fails, the token MUST be rejected. 745 The ECDSA validator will then determine if the digital signature is 746 valid, given the inputs. Note that ECDSA digital signature contains 747 a value referred to as K, which is a random number generated for each 748 digital signature instance. This means that two ECDSA digital 749 signatures using exactly the same input parameters will output 750 different signatures because their K values will be different. The 751 consequence of this is that one must validate an ECDSA signature by 752 submitting the previously specified inputs to an ECDSA validator. 754 Signing with the ECDSA P-384 SHA-384 and ECDSA P-521 SHA-512 755 algorithms is performed identically to the procedure for ECDSA P-256 756 SHA-256 - just with correspondingly longer key and result values. 758 It is RECOMMENDED that JWT implementations support the ECDSA P-256 759 SHA-256 algorithm. Support for the ECDSA P-384 SHA-384 and ECDSA 760 P-521 SHA-512 algorithms is OPTIONAL. 762 8.4. Additional Algorithms 764 Additional algorithms MAY be used to protect JWTs with corresponding 765 "alg" envelope parameter values being defined to refer to them. Like 766 claim names, new "alg" envelope parameter values SHOULD either be 767 defined in the IANA JSON Web Token Algorithms registry or be a URI 768 that contains a collision resistant namespace. In particular, the 769 use of algorithm identifiers defined in XML DSIG [RFC3275] and 770 related specifications is permitted. 772 9. IANA Considerations 774 This specification calls for: 776 o A new IANA registry entitled "JSON Web Token Claims" for reserved 777 claim names Section 4.1 used in a Decoded JWT Claim Segment. 778 Inclusion in the registry is RFC Required in the RFC 5226 779 [RFC5226] sense for reserved JWT claim names that are intended to 780 be interoperable between implementations. The registry will just 781 record the reserved claim name and a pointer to the RFC that 782 defines it. This specification defines inclusion of the claim 783 names defined in Table 1. 785 o A new IANA registry entitled "JSON Web Token Envelope Parameters" 786 for reserved envelope parameter names Section 5.1 used in a 787 Decoded JWT Envelope Parameter Segment. Inclusion in the registry 788 is RFC Required in the RFC 5226 [RFC5226] sense for reserved JWT 789 envelope parameter names that are intended to be interoperable 790 between implementations. The registry will just record the 791 reserved envelope parameter name and a pointer to the RFC that 792 defines it. This specification defines inclusion of the envelope 793 parameter names defined in Table 3. 795 o A new IANA registry entitled "JSON Web Token Algorithms" for 796 reserved values used with the "alg" envelope parameter values used 797 in a decoded JWT Envelope Segment. Inclusion in the registry is 798 RFC Required in the RFC 5226 [RFC5226] sense. The registry will 799 just record the "alg" value and a pointer to the RFC that defines 800 it. This specification defines inclusion of the algorithm values 801 defined in Table 4. 803 10. Security Considerations 805 TBD: Lots of work to do here. We need to remember to look into any 806 issues relating to security and JSON parsing. One wonders just how 807 secure most JSON parsing libraries are. Were they ever hardened for 808 security scenarios? If not, what kind of holes does that open up? 809 Also, we need to walk through the JSON standard and see what kind of 810 issues we have especially around comparison of names. For instance, 811 comparisons of claim names and other parameters must occur after they 812 are unescaped. Need to also put in text about: Importance of keeping 813 secrets secret. Rotating keys. Strengths and weaknesses of the 814 different algorithms. Case sensitivity and more generally Unicode 815 comparison issues that can cause security holes, especially in claim 816 names and explain why Unicode Normalization is such a problem. 818 TBD: Need to put in text about why strict JSON validation is 819 necessary. Basically, that if malformed JSON is received then the 820 intent of the sender is impossible to reliably discern. While in 821 non-security contexts it's o.k. to be generous in what one accepts, 822 in security contexts this can lead to serious security holes. For 823 example, malformed JSON might indicate that someone has managed to 824 find a security hole in the issuer's code and is leveraging it to get 825 the issuer to issue "bad" tokens whose content the attacker can 826 control. 828 10.1. Unicode Comparison Security Issues 830 Claim names in JWTs are Unicode strings. For security reasons, the 831 representations these names must be compared verbatim after 832 performing any escape processing (as per RFC 4627 [RFC4627], Section 833 2.5). In particular, Unicode Normalization [USA15] or case folding 834 MUST NOT be applied at any point to either the JSON string or to the 835 string it is to be compared against. 837 This means, for instance, that these JSON strings must compare as 838 being equal ("JWT", "\u004aWT"), whereas these must all compare as 839 being not equal to the first set or to each other ("jwt", "Jwt", 840 "JW\u0074"). 842 JSON strings MAY contain characters outside the Unicode Basic 843 Multilingual Plane. For instance, the G clef character (U+1D11E) may 844 be represented in a JSON string as "\uD834\uDD1E". Ideally, JWT 845 implementations SHOULD ensure that characters outside the Basic 846 Multilingual Plane are preserved and compared correctly; 847 alternatively, if this is not possible due to these characters 848 exercising limitations present in the underlying JSON implementation, 849 then input containing them MUST be rejected. 851 11. Open Issues 853 The following open issues have been identified during review of 854 previous drafts. Additional input on them is solicited. 856 o The draft currently defines no mechanism(s) for retrieving public 857 keys that are not encoded as X.509 certificates. A mechanism or 858 mechanisms similar to the Magic Signatures key discovery process 859 for Magic Keys could be added to future drafts. Some have 860 suggested that they keys themselves also be encoded as JWTs. 862 o Related to the above, it's not clear whether the "iss" claim 863 should be expected to contain a location for retrieving non-X.509 864 public keys, or whether a separate issuer key location parameter 865 should be defined. Also, does this belong in the envelope or the 866 claims? 868 12. Acknowledgements 870 The authors acknowledge that the design of JWTs was intentionally 871 influenced by the design and simplicity of Simple Web Tokens [SWT]. 872 Solutions for signing JSON tokens were also previously explored by 873 Magic Signatures [MagicSignatures], JSON Simple Sign [JSS], and 874 Canvas Applications [CanvasApp], all of which influenced this draft. 876 13. Appendix - Non-Normative - JWT Examples 878 13.1. JWT using HMAC SHA-256 880 13.1.1. Encoding 882 The Decoded JWT Claim Segment used in this example is: 883 {"iss":"joe", 884 "exp":1300819380, 885 "http://example.com/is_root":true} 887 Note that white space is explicitly allowed in Decoded JWT Claim 888 Segments and no canonicalization is performed before encoding. The 889 following byte array contains the UTF-8 characters for the Decoded 890 JWT Claim Segment: 892 [123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10, 893 32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56, 894 48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97, 895 109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111, 896 111, 116, 34, 58, 116, 114, 117, 101, 125] 897 Base64url encoding the above yields the JWT Claim Segment value: 898 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 900 The following example JSON envelope object declares that the encoded 901 object is a JSON Web Token (JWT) and the JWT Claim Segment is signed 902 using the HMAC SHA-256 algorithm: 903 {"typ":"JWT", 904 "alg":"HS256"} 906 The following byte array contains the UTF-8 characters for the 907 Decoded JWT Envelope Segment: 909 [123, 34, 116, 121, 112, 34, 58, 34, 74, 87, 84, 34, 44, 13, 10, 32, 910 34, 97, 108, 103, 34, 58, 34, 72, 83, 50, 53, 54, 34, 125] 912 Base64url encoding this UTF-8 representation yields this JWT Envelope 913 Segment value: 914 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 916 HMACs are generated using keys. This example used the key 917 represented by the following byte array: 919 [83, 159, 117, 12, 235, 169, 168, 200, 131, 152, 227, 246, 214, 212, 920 188, 74, 71, 83, 244, 166, 90, 24, 239, 251, 32, 124, 6, 201, 194, 921 104, 241, 62, 174, 246, 65, 111, 49, 52, 210, 118, 212, 124, 34, 88, 922 167, 112, 84, 88, 83, 65, 155, 18, 234, 250, 224, 101, 147, 221, 23, 923 104, 219, 170, 146, 215] 925 Running the HMAC SHA-256 algorithm on the JWT Claim Segment with this 926 key yields the following byte array: 928 [223, 155, 172, 90, 63, 87, 240, 124, 6, 75, 224, 131, 115, 29, 73, 929 63, 99, 102, 169, 202, 203, 193, 158, 4, 42, 159, 44, 53, 56, 95, 930 221, 198] 932 Base64url encoding the above HMAC output yields the JWT Crypto 933 Segment value: 934 35usWj9X8HwGS-CDcx1JP2NmqcrLwZ4EKp8sNThf3cY 936 Combining these segments in the order Envelope.Claims.Signature with 937 period characters between the segments yields this complete JWT (with 938 line breaks for display purposes only): 939 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 940 . 941 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 942 . 943 35usWj9X8HwGS-CDcx1JP2NmqcrLwZ4EKp8sNThf3cY 944 13.1.2. Decoding 946 Decoding the JWT first requires removing the base64url encoding from 947 the JWT Envelope Segment and the JWT Claim Segment. We base64url 948 decode the segments per Section 7 and turn them into the 949 corresponding UTF-8 byte arrays, which we then translate into the 950 Decoded JWT Envelope Segment and Decoded JWT Claim Segment strings. 952 13.1.3. Validating 954 Next we validate the decoded results. Since the "alg" parameter in 955 the envelope is "HS256", we validate the HMAC SHA-256 signature 956 contained in the JWT Crypto Segment. If any of the validation steps 957 fail, the token MUST be rejected. 959 First, we validate that the decoded envelope and claim segment 960 strings are both legal JSON. 962 To validate the signature, we repeat the previous process of using 963 the correct key and the JWT Claim Segment as input to a SHA-256 HMAC 964 function and then taking the output, base64url encoding it, and 965 determining if it matches the JWT Crypto Segment in the JWT. If it 966 matches exactly, the token has been validated. 968 13.2. JWT using RSA SHA-256 970 13.2.1. Encoding 972 The Decoded JWT Claim Segment used in this example is the same as in 973 the previous example: 974 {"iss":"joe", 975 "exp":1300819380, 976 "http://example.com/is_root":true} 978 Since the JWT Claim Segment will therefore be the same, its 979 computation is not repeated here. However, the Decoded JWT Envelope 980 Segment is different in two ways: First, because a different 981 algorithm is being used, the "alg" value is different. Second, for 982 illustration purposes only, the optional "typ" parameter is not used. 983 (This difference is not related to the signature algorithm employed.) 984 The Decoded JWT Envelope Segment used is: 985 {"alg":"RS256"} 987 The following byte array contains the UTF-8 characters for the 988 Decoded JWT Envelope Segment: 990 [123, 34, 97, 108, 103, 34, 58, 34, 82, 83, 50, 53, 54, 34, 125] 991 Base64url encoding this UTF-8 representation yields this JWT Envelope 992 Segment value: 993 eyJhbGciOiJSUzI1NiJ9 995 The RSA key consists of a public part (n, e), and a private exponent 996 d. The values of the RSA key used in this example, presented as the 997 byte arrays representing big endian integers are: 999 +-----------+-------------------------------------------------------+ 1000 | Parameter | Value | 1001 | Name | | 1002 +-----------+-------------------------------------------------------+ 1003 | n | [210, 252, 123, 106, 10, 30, 108, 103, 16, 74, 235, | 1004 | | 143, 136, 178, 87, 102, 155, 77, 246, 121, 221, 173, | 1005 | | 9, 155, 92, 74, 108, 217, 168, 128, 21, 181, 161, 51, | 1006 | | 191, 11, 133, 108, 120, 113, 182, 223, 0, 11, 85, 79, | 1007 | | 206, 179, 194, 237, 81, 43, 182, 143, 20, 92, 110, | 1008 | | 132, 52, 117, 47, 171, 82, 161, 207, 193, 36, 64, | 1009 | | 143, 121, 181, 138, 69, 120, 193, 100, 40, 133, 87, | 1010 | | 137, 247, 162, 73, 227, 132, 203, 45, 159, 174, 45, | 1011 | | 103, 253, 150, 251, 146, 108, 25, 142, 7, 115, 153, | 1012 | | 253, 200, 21, 192, 175, 9, 125, 222, 90, 173, 239, | 1013 | | 244, 77, 231, 14, 130, 127, 72, 120, 67, 36, 57, 191, | 1014 | | 238, 185, 96, 104, 208, 71, 79, 197, 13, 109, 144, | 1015 | | 191, 58, 152, 223, 175, 16, 64, 200, 156, 2, 214, | 1016 | | 146, 171, 59, 60, 40, 150, 96, 157, 134, 253, 115, | 1017 | | 183, 116, 206, 7, 64, 100, 124, 238, 234, 163, 16, | 1018 | | 189, 18, 249, 133, 168, 235, 159, 89, 253, 212, 38, | 1019 | | 206, 165, 178, 18, 15, 79, 42, 52, 188, 171, 118, 75, | 1020 | | 126, 108, 84, 214, 132, 2, 56, 188, 196, 5, 135, 165, | 1021 | | 158, 102, 237, 31, 51, 137, 69, 119, 99, 92, 71, 10, | 1022 | | 247, 92, 249, 44, 32, 209, 218, 67, 225, 191, 196, | 1023 | | 25, 226, 34, 166, 240, 208, 187, 53, 140, 94, 56, | 1024 | | 249, 203, 5, 10, 234, 254, 144, 72, 20, 241, 172, 26, | 1025 | | 164, 156, 202, 158, 160, 202, 131] | 1026 | e | [1, 0, 1] | 1027 | d | [95, 135, 19, 181, 226, 88, 254, 9, 248, 21, 131, | 1028 | | 236, 92, 31, 43, 117, 120, 177, 230, 252, 44, 131, | 1029 | | 81, 75, 55, 145, 55, 17, 161, 186, 68, 154, 21, 31, | 1030 | | 225, 203, 44, 160, 253, 51, 183, 113, 230, 138, 59, | 1031 | | 25, 68, 100, 157, 200, 103, 173, 28, 30, 82, 64, 187, | 1032 | | 133, 62, 95, 36, 179, 52, 89, 177, 64, 40, 210, 214, | 1033 | | 99, 107, 239, 236, 30, 141, 169, 116, 179, 82, 252, | 1034 | | 83, 211, 246, 18, 126, 168, 163, 194, 157, 209, 79, | 1035 | | 57, 65, 104, 44, 86, 167, 135, 104, 22, 78, 77, 218, | 1036 | | 143, 6, 203, 249, 199, 52, 170, 232, 0, 50, 36, 39, | 1037 | | 142, 169, 69, 74, 33, 177, 124, 176, 109, 23, 128, | 1038 | | 117, 134, 140, 192, 91, 61, 182, 255, 29, 253, 195, | 1039 | | 213, 99, 120, 180, 237, 173, 237, 240, 195, 122, 76, | 1040 | | 220, 38, 209, 212, 154, 194, 111, 111, 227, 181, 34, | 1041 | | 10, 93, 210, 147, 150, 98, 27, 188, 104, 140, 242, | 1042 | | 238, 226, 198, 224, 213, 77, 163, 199, 130, 1, 76, | 1043 | | 208, 115, 157, 178, 82, 204, 81, 202, 235, 168, 211, | 1044 | | 241, 184, 36, 186, 171, 36, 208, 104, 236, 144, 50, | 1045 | | 100, 215, 214, 120, 171, 8, 240, 110, 201, 231, 226, | 1046 | | 61, 150, 6, 40, 183, 68, 191, 148, 179, 105, 70, 86, | 1047 | | 70, 60, 126, 65, 115, 153, 237, 115, 208, 118, 200, | 1048 | | 145, 252, 244, 99, 169, 170, 156, 230, 45, 169, 205, | 1049 | | 23, 226, 55, 220, 42, 128, 2, 241] | 1050 +-----------+-------------------------------------------------------+ 1052 The RSA private key (n, d) is then passed to the RSA signing 1053 function, which also takes the hash type, SHA-256, and the JWT Claim 1054 Segment as inputs. The result of the signature is a byte array S, 1055 which represents a big endian integer. In this example, S is: 1057 +--------+----------------------------------------------------------+ 1058 | Result | Value | 1059 | Name | | 1060 +--------+----------------------------------------------------------+ 1061 | S | [208, 141, 219, 44, 66, 129, 179, 230, 69, 120, 123, | 1062 | | 108, 203, 96, 182, 145, 66, 179, 198, 104, 43, 187, 199, | 1063 | | 159, 175, 5, 217, 101, 109, 236, 88, 136, 193, 133, 79, | 1064 | | 39, 162, 131, 58, 114, 133, 202, 171, 227, 135, 157, | 1065 | | 123, 188, 90, 111, 66, 241, 38, 238, 59, 18, 125, 146, | 1066 | | 129, 14, 54, 183, 10, 221, 33, 105, 37, 173, 119, 239, | 1067 | | 92, 27, 232, 175, 173, 49, 21, 28, 252, 237, 183, 107, | 1068 | | 98, 156, 113, 116, 162, 219, 53, 96, 44, 214, 175, 154, | 1069 | | 61, 100, 175, 90, 118, 247, 42, 196, 45, 74, 217, 145, | 1070 | | 92, 39, 123, 224, 247, 171, 206, 203, 91, 167, 103, 57, | 1071 | | 163, 87, 172, 67, 77, 255, 9, 218, 107, 62, 228, 71, | 1072 | | 239, 36, 246, 23, 96, 108, 28, 19, 179, 24, 167, 196, | 1073 | | 42, 97, 198, 80, 241, 79, 31, 0, 85, 17, 50, 6, 143, | 1074 | | 238, 214, 131, 246, 13, 49, 111, 30, 142, 182, 145, 200, | 1075 | | 17, 127, 76, 236, 69, 66, 133, 198, 137, 103, 45, 3, 48, | 1076 | | 123, 203, 17, 162, 1, 105, 133, 22, 105, 25, 63, 173, | 1077 | | 186, 231, 206, 246, 22, 243, 250, 53, 237, 209, 36, 111, | 1078 | | 168, 11, 40, 237, 179, 83, 125, 180, 84, 231, 129, 37, | 1079 | | 236, 172, 22, 234, 58, 198, 187, 124, 65, 145, 148, 227, | 1080 | | 122, 177, 16, 176, 84, 28, 1, 141, 179, 57, 96, 232, | 1081 | | 215, 51, 7, 49, 63, 195, 155, 94, 51, 22, 239, 90, 138, | 1082 | | 207, 41, 62] | 1083 +--------+----------------------------------------------------------+ 1085 Base64url encoding the signature produces this value for the JWT 1086 Crypto Segment: 1087 0I3bLEKBs-ZFeHtsy2C2kUKzxmgru8efrwXZZW3sWIjBhU8nooM6coXKq-OHnXu8Wm9C8SbuOxJ9koEONrcK3SFpJa1371wb6K-tMRUc_O23a2KccXSi2zVgLNavmj1kr1p29yrELUrZkVwne-D3q87LW6dnOaNXrENN_wnaaz7kR-8k9hdgbBwTsxinxCphxlDxTx8AVREyBo_u1oP2DTFvHo62kcgRf0zsRUKFxolnLQMwe8sRogFphRZpGT-tuufO9hbz-jXt0SRvqAso7bNTfbRU54El7KwW6jrGu3xBkZTjerEQsFQcAY2zOWDo1zMHMT_Dm14zFu9ais8pPg 1089 Combining these segments in the order Envelope.Claims.Signature with 1090 period characters between the segments yields this complete JWT (with 1091 line breaks for display purposes only): 1092 eyJhbGciOiJSUzI1NiJ9 1093 . 1094 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1095 . 1096 0I3bLEKBs-ZFeHtsy2C2kUKzxmgru8efrwXZZW3sWIjBhU8nooM6coXKq-OHnXu8Wm9C8SbuOxJ9koEONrcK3SFpJa1371wb6K-tMRUc_O23a2KccXSi2zVgLNavmj1kr1p29yrELUrZkVwne-D3q87LW6dnOaNXrENN_wnaaz7kR-8k9hdgbBwTsxinxCphxlDxTx8AVREyBo_u1oP2DTFvHo62kcgRf0zsRUKFxolnLQMwe8sRogFphRZpGT-tuufO9hbz-jXt0SRvqAso7bNTfbRU54El7KwW6jrGu3xBkZTjerEQsFQcAY2zOWDo1zMHMT_Dm14zFu9ais8pPg 1098 13.2.2. Decoding 1100 Decoding the JWT from this example requires processing the JWT 1101 Envelope Segment and Claim Segment exactly as done in the first 1102 example. 1104 13.2.3. Validating 1106 Since the "alg" parameter in the envelope is "RS256", we validate the 1107 RSA SHA-256 signature contained in the JWT Crypto Segment. If any of 1108 the validation steps fail, the token MUST be rejected. 1110 First, we validate that the decoded envelope and claim segment 1111 strings are both legal JSON. 1113 Validating the JWT Crypto Segment is a little different from the 1114 previous example. First, we base64url decode the JWT Crypto Segment 1115 to produce a signature S to check. We then pass (n, e), S and the 1116 JWT Claim Segment to an RSA signature verifier that has been 1117 configured to use the SHA-256 hash function. 1119 13.3. JWT using ECDSA P-256 SHA-256 1121 13.3.1. Encoding 1123 The Decoded JWT Claim Segment used in this example is the same as in 1124 the previous examples: 1125 {"iss":"joe", 1126 "exp":1300819380, 1127 "http://example.com/is_root":true} 1129 Since the JWT Claim Segment will therefore be the same, its 1130 computation is not repeated here. However, the Decoded JWT Envelope 1131 Segment is differs from the previous example because a different 1132 algorithm is being used. The Decoded JWT Envelope Segment used is: 1133 {"alg":"ES256"} 1135 The following byte array contains the UTF-8 characters for the 1136 Decoded JWT Envelope Segment: 1138 [123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 50, 53, 54, 34, 125] 1140 Base64url encoding this UTF-8 representation yields this JWT Envelope 1141 Segment value: 1142 eyJhbGciOiJFUzI1NiJ9 1144 The ECDSA key consists of a public part, the EC point (x, y), and a 1145 private part d. The values of the ECDSA key used in this example, 1146 presented as the byte arrays representing big endian integers are: 1148 +-----------+-------------------------------------------------------+ 1149 | Parameter | Value | 1150 | Name | | 1151 +-----------+-------------------------------------------------------+ 1152 | x | [48, 160, 66, 76, 210, 28, 41, 68, 131, 138, 45, 117, | 1153 | | 201, 43, 55, 231, 110, 162, 13, 159, 0, 137, 58, 59, | 1154 | | 78, 238, 138, 60, 10, 175, 236, 62] | 1155 | y | [224, 75, 101, 233, 36, 86, 217, 136, 139, 82, 179, | 1156 | | 121, 189, 251, 213, 30, 232, 105, 239, 31, 15, 198, | 1157 | | 91, 102, 89, 105, 91, 108, 206, 8, 23, 35] | 1158 | d | [243, 189, 12, 7, 168, 31, 185, 50, 120, 30, 213, 39, | 1159 | | 82, 246, 12, 200, 154, 107, 229, 229, 25, 52, 254, 1, | 1160 | | 147, 141, 219, 85, 216, 247, 120, 1] | 1161 +-----------+-------------------------------------------------------+ 1163 The ECDSA private part d is then passed to an ECDSA signing function, 1164 which also takes the curve type, P-256, the hash type, SHA-256, and 1165 the JWT Claim Segment as inputs. The result of the signature is the 1166 EC point (R, S), where R and S are unsigned integers. In this 1167 example, the R and S values, given as byte arrays representing big 1168 endian integers are: 1170 +--------+----------------------------------------------------------+ 1171 | Result | Value | 1172 | Name | | 1173 +--------+----------------------------------------------------------+ 1174 | R | [175, 11, 115, 42, 160, 182, 181, 28, 135, 222, 52, 154, | 1175 | | 182, 237, 206, 137, 82, 20, 243, 7, 12, 164, 107, 72, | 1176 | | 236, 187, 241, 190, 26, 76, 32, 181] | 1177 | S | [120, 23, 189, 205, 202, 13, 177, 187, 23, 47, 12, 227, | 1178 | | 237, 250, 230, 233, 245, 216, 9, 170, 24, 185, 198, 187, | 1179 | | 193, 94, 158, 117, 167, 88, 153, 196] | 1180 +--------+----------------------------------------------------------+ 1182 Concatenating the S array to the end of the R array and base64url 1183 encoding the result produces this value for the JWT Crypto Segment: 1184 rwtzKqC2tRyH3jSatu3OiVIU8wcMpGtI7LvxvhpMILV4F73Nyg2xuxcvDOPt-ubp9dgJqhi5xrvBXp51p1iZxA 1186 Combining these segments in the order Envelope.Claims.Signature with 1187 period characters between the segments yields this complete JWT (with 1188 line breaks for display purposes only): 1189 eyJhbGciOiJFUzI1NiJ9 1190 . 1191 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1192 . 1193 rwtzKqC2tRyH3jSatu3OiVIU8wcMpGtI7LvxvhpMILV4F73Nyg2xuxcvDOPt-ubp9dgJqhi5xrvBXp51p1iZxA 1194 13.3.2. Decoding 1196 Decoding the JWT from this example requires processing the JWT 1197 Envelope Segment and Claim Segment exactly as done in the first 1198 example. 1200 13.3.3. Validating 1202 Since the "alg" parameter in the envelope is "ES256", we validate the 1203 ECDSA P-256 SHA-256 signature contained in the JWT Crypto Segment. 1204 If any of the validation steps fail, the token MUST be rejected. 1206 First, we validate that the decoded envelope and claim segment 1207 strings are both legal JSON. 1209 Validating the JWT Crypto Segment is a little different from the 1210 first example. First, we base64url decode the JWT Crypto Segment as 1211 in the previous examples but we then need to split the 64 member byte 1212 array that must result into two 32 byte arrays, the first R and the 1213 second S. We then pass (x, y), (R, S) and the JWT Claim Segment to an 1214 ECDSA signature verifier that has been configured to use the P-256 1215 curve with the SHA-256 hash function. 1217 As explained in Section 8.3, the use of the k value in ECDSA means 1218 that we cannot validate the correctness of the signature in the same 1219 way we validated the correctness of the HMAC. Instead, 1220 implementations MUST use an ECDSA validator to validate the 1221 signature. 1223 14. Appendix - Non-Normative - Notes on implementing base64url encoding 1224 without padding 1226 This appendix describes how to implement base64url encoding and 1227 decoding functions without padding based upon standard base64 1228 encoding and decoding functions that do use padding. 1230 To be concrete, example C# code implementing these functions is shown 1231 below. Similar code could be used in other languages. 1233 static string base64urlencode(byte [] arg) 1234 { 1235 string s = Convert.ToBase64String(arg); // Standard base64 encoder 1236 s = s.Split('=')[0]; // Remove any trailing '='s 1237 s = s.Replace('+', '-'); // 62nd char of encoding 1238 s = s.Replace('/', '_'); // 63rd char of encoding 1239 return s; 1240 } 1242 static byte [] base64urldecode(string arg) 1243 { 1244 string s = arg; 1245 s = s.Replace('-', '+'); // 62nd char of encoding 1246 s = s.Replace('_', '/'); // 63rd char of encoding 1247 switch (s.Length % 4) // Pad with trailing '='s 1248 { 1249 case 0: break; // No pad chars in this case 1250 case 2: s += "=="; break; // Two pad chars 1251 case 3: s += "="; break; // One pad char 1252 default: throw new System.Exception( 1253 "Illegal base64url string!"); 1254 } 1255 return Convert.FromBase64String(s); // Standard base64 decoder 1256 } 1258 As per the example code above, the number of '=' padding characters 1259 that needs to be added to the end of a base64url encoded string 1260 without padding to turn it into one with padding is a deterministic 1261 function of the length of the encoded string. Specifically, if the 1262 length mod 4 is 0, no padding is added; if the length mod 4 is 2, two 1263 '=' padding characters are added; if the length mod 4 is 3, one '=' 1264 padding character is added; if the length mod 4 is 1, the input is 1265 malformed. 1267 An example correspondence between unencoded and encoded values 1268 follows. The byte sequence below encodes into the string below, 1269 which when decoded, reproduces the byte sequence. 1270 3 236 255 224 193 1271 A-z_4ME 1273 15. Appendix - Non-Normative - Relationship of JWTs to SAML Tokens 1275 SAML 2.0 [OASIS.saml-core-2.0-os] provides a standard for creating 1276 tokens with much greater expressivity and more security options than 1277 supported by JWTs. However, the cost of this flexibility and 1278 expressiveness is both size and complexity. In addition, SAML's use 1279 of XML [W3C.CR-xml11-20021015] and XML DSIG [RFC3275] only 1280 contributes to the size of SAML tokens. 1282 JWTs are intended to provide a simple token format that is small 1283 enough to fit into HTTP headers and query arguments in URIs. It does 1284 this by supporting a much simpler token model than SAML and using the 1285 JSON [RFC4627] object encoding syntax. It also supports securing 1286 tokens using Hash-based Message Authentication Codes (HMACs) and 1287 digital signatures using a smaller (and less flexible) format than 1288 XML DSIG. 1290 Therefore, while JWTs can do some of the things SAML tokens do, JWTs 1291 are not intended as a full replacement for SAML tokens, but rather as 1292 a compromise token format to be used when space is at a premium. 1294 16. Appendix - Non-Normative - Relationship of JWTs to Simple Web 1295 Tokens (SWTs) 1297 Both JWTs and Simple Web Tokens SWT [SWT], at their core, enable sets 1298 of claims to be communicated between applications. For SWTs, both 1299 the claim names and claim values are strings. For JWTs, while claim 1300 names are strings, claim values can be any JSON type. Both token 1301 types offer cryptographic protection of their content: SWTs with HMAC 1302 SHA-256 and JWTs with a choice of algorithms, including HMAC SHA-256, 1303 RSA SHA-256, and ECDSA P-256 SHA-256. 1305 17. References 1307 17.1. Normative References 1309 [FIPS.180-3] 1310 National Institute of Standards and Technology, "Secure 1311 Hash Standard (SHS)", FIPS PUB 180-3, October 2008. 1313 [FIPS.186-3] 1314 National Institute of Standards and Technology, "Digital 1315 Signature Standard (DSS)", FIPS PUB 186-3, June 2009. 1317 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1318 Extensions (MIME) Part One: Format of Internet Message 1319 Bodies", RFC 2045, November 1996. 1321 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1322 Hashing for Message Authentication", RFC 2104, 1323 February 1997. 1325 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1326 Requirement Levels", BCP 14, RFC 2119, March 1997. 1328 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 1329 Internet: Timestamps", RFC 3339, July 2002. 1331 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1332 Standards (PKCS) #1: RSA Cryptography Specifications 1333 Version 2.1", RFC 3447, February 2003. 1335 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1336 10646", STD 63, RFC 3629, November 2003. 1338 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1339 Resource Identifier (URI): Generic Syntax", STD 66, 1340 RFC 3986, January 2005. 1342 [RFC4627] Crockford, D., "The application/json Media Type for 1343 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1345 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1346 Encodings", RFC 4648, October 2006. 1348 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1349 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1350 May 2008. 1352 [USA15] Davis, M., Whistler, K., and M. Duerst, "Unicode 1353 Normalization Forms", Unicode Standard Annex 15, 09 2009. 1355 17.2. Informative References 1357 [CanvasApp] 1358 Facebook, "Canvas Applications", 2010. 1360 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 1361 September 2010. 1363 [MagicSignatures] 1364 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 1365 Signatures", August 2010. 1367 [OASIS.saml-core-2.0-os] 1368 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 1369 "Assertions and Protocol for the OASIS Security Assertion 1370 Markup Language (SAML) V2.0", OASIS Standard saml-core- 1371 2.0-os, March 2005. 1373 [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup 1374 Language) XML-Signature Syntax and Processing", RFC 3275, 1375 March 2002. 1377 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1378 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1379 July 2005. 1381 [SWT] Hardt, D. and Y. Goland, "Simple Web Token (SWT)", 1382 Version 0.9.5.1, November 2009. 1384 [W3C.CR-xml11-20021015] 1385 Cowan, J., "Extensible Markup Language (XML) 1.1", W3C 1386 CR CR-xml11-20021015, October 2002. 1388 Authors' Addresses 1390 Michael B. Jones 1391 Microsoft 1393 Email: mbj@microsoft.com 1394 URI: http://self-issued.info/ 1396 Dirk Balfanz 1397 Google 1399 Email: balfanz@google.com 1401 John Bradley 1402 independent 1404 Email: ve7jtb@ve7jtb.com 1406 Yaron Y. Goland 1407 Microsoft 1409 Email: yarong@microsoft.com 1411 John Panzer 1412 Google 1414 Email: jpanzer@google.com 1415 Nat Sakimura 1416 Nomura Research Institute 1418 Email: n-sakimura@nri.co.jp