idnits 2.17.1 draft-ietf-jose-json-web-signature-08.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 (December 27, 2012) is 4137 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 1372 -- Looks like a reference, but probably isn't: '34' on line 1372 -- Looks like a reference, but probably isn't: '97' on line 1381 -- Looks like a reference, but probably isn't: '108' on line 1381 -- Looks like a reference, but probably isn't: '103' on line 1372 -- Looks like a reference, but probably isn't: '58' on line 1372 -- Looks like a reference, but probably isn't: '82' on line 1086 -- Looks like a reference, but probably isn't: '83' on line 1372 -- Looks like a reference, but probably isn't: '50' on line 1372 -- Looks like a reference, but probably isn't: '53' on line 1372 -- Looks like a reference, but probably isn't: '54' on line 1248 -- Looks like a reference, but probably isn't: '125' on line 1372 -- Looks like a reference, but probably isn't: '1' on line 1152 -- Looks like a reference, but probably isn't: '0' on line 1615 -- Looks like a reference, but probably isn't: '69' on line 1372 -- Looks like a reference, but probably isn't: '49' on line 1372 -- Looks like a reference, but probably isn't: '80' on line 1381 -- Looks like a reference, but probably isn't: '121' on line 1381 -- Looks like a reference, but probably isn't: '111' on line 1381 -- Looks like a reference, but probably isn't: '100' on line 1381 == Unused Reference: 'RFC3629' is defined on line 876, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'ITU.X690.1994' ** Downref: Normative reference to an Historic RFC: RFC 1421 ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 4288 (Obsoleted by RFC 6838) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) -- Possible downref: Non-RFC (?) normative reference: ref. 'USA15' -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' Summary: 6 errors (**), 0 flaws (~~), 2 warnings (==), 24 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JOSE Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track J. Bradley 5 Expires: June 30, 2013 Ping Identity 6 N. Sakimura 7 NRI 8 December 27, 2012 10 JSON Web Signature (JWS) 11 draft-ietf-jose-json-web-signature-08 13 Abstract 15 JSON Web Signature (JWS) is a means of representing content secured 16 with digital signatures or Message Authentication Codes (MACs) using 17 JavaScript Object Notation (JSON) data structures. Cryptographic 18 algorithms and identifiers for use with this specification are 19 described in the separate JSON Web Algorithms (JWA) specification. 20 Related encryption capabilities are described in the separate JSON 21 Web Encryption (JWE) specification. 23 Status of this Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on June 30, 2013. 40 Copyright Notice 42 Copyright (c) 2012 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 3. JSON Web Signature (JWS) Overview . . . . . . . . . . . . . . 5 61 3.1. Example JWS . . . . . . . . . . . . . . . . . . . . . . . 6 62 4. JWS Header . . . . . . . . . . . . . . . . . . . . . . . . . . 7 63 4.1. Reserved Header Parameter Names . . . . . . . . . . . . . 7 64 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 7 65 4.1.2. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 8 66 4.1.3. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 8 67 4.1.4. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 8 68 4.1.5. "x5t" (X.509 Certificate Thumbprint) Header 69 Parameter . . . . . . . . . . . . . . . . . . . . . . 8 70 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter . . . 9 71 4.1.7. "kid" (Key ID) Header Parameter . . . . . . . . . . . 9 72 4.1.8. "typ" (Type) Header Parameter . . . . . . . . . . . . 9 73 4.1.9. "cty" (Content Type) Header Parameter . . . . . . . . 10 74 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 10 75 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 10 76 5. Producing and Consuming JWSs . . . . . . . . . . . . . . . . . 10 77 5.1. Message Signing or MACing . . . . . . . . . . . . . . . . 10 78 5.2. Message Signature or MAC Validation . . . . . . . . . . . 11 79 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 12 80 6. Securing JWSs with Cryptographic Algorithms . . . . . . . . . 13 81 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 82 7.1. JSON Web Signature and Encryption Header Parameters 83 Registry . . . . . . . . . . . . . . . . . . . . . . . . . 13 84 7.1.1. Registration Template . . . . . . . . . . . . . . . . 14 85 7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 14 86 7.2. JSON Web Signature and Encryption Type Values Registry . . 15 87 7.2.1. Registration Template . . . . . . . . . . . . . . . . 16 88 7.2.2. Initial Registry Contents . . . . . . . . . . . . . . 16 89 7.3. Media Type Registration . . . . . . . . . . . . . . . . . 16 90 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 16 91 8. Security Considerations . . . . . . . . . . . . . . . . . . . 17 92 8.1. Cryptographic Security Considerations . . . . . . . . . . 17 93 8.2. JSON Security Considerations . . . . . . . . . . . . . . . 18 94 8.3. Unicode Comparison Security Considerations . . . . . . . . 18 95 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 96 9.1. Normative References . . . . . . . . . . . . . . . . . . . 19 97 9.2. Informative References . . . . . . . . . . . . . . . . . . 20 98 Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 21 99 A.1. JWS using HMAC SHA-256 . . . . . . . . . . . . . . . . . . 21 100 A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 21 101 A.1.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 23 102 A.1.3. Validating . . . . . . . . . . . . . . . . . . . . . . 23 103 A.2. JWS using RSA SHA-256 . . . . . . . . . . . . . . . . . . 23 104 A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 23 105 A.2.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 27 106 A.2.3. Validating . . . . . . . . . . . . . . . . . . . . . . 27 107 A.3. JWS using ECDSA P-256 SHA-256 . . . . . . . . . . . . . . 27 108 A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 27 109 A.3.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 29 110 A.3.3. Validating . . . . . . . . . . . . . . . . . . . . . . 29 111 A.4. JWS using ECDSA P-521 SHA-512 . . . . . . . . . . . . . . 30 112 A.4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 30 113 A.4.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 32 114 A.4.3. Validating . . . . . . . . . . . . . . . . . . . . . . 32 115 A.5. Example Plaintext JWS . . . . . . . . . . . . . . . . . . 33 116 Appendix B. "x5c" (X.509 Certificate Chain) Example . . . . . . . 33 117 Appendix C. Notes on implementing base64url encoding without 118 padding . . . . . . . . . . . . . . . . . . . . . . . 35 119 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 36 120 Appendix E. Open Issues . . . . . . . . . . . . . . . . . . . . . 37 121 Appendix F. Document History . . . . . . . . . . . . . . . . . . 37 122 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 41 124 1. Introduction 126 JSON Web Signature (JWS) is a compact format for representing content 127 secured with digital signatures or Message Authentication Codes 128 (MACs) intended for space constrained environments such as HTTP 129 Authorization headers and URI query parameters. It represents this 130 content using JavaScript Object Notation (JSON) [RFC4627] based data 131 structures. The JWS cryptographic mechanisms provide integrity 132 protection for arbitrary sequences of bytes. 134 Cryptographic algorithms and identifiers for use with this 135 specification are described in the separate JSON Web Algorithms (JWA) 136 [JWA] specification. Related encryption capabilities are described 137 in the separate JSON Web Encryption (JWE) [JWE] specification. 139 1.1. Notational Conventions 141 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 142 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 143 document are to be interpreted as described in Key words for use in 144 RFCs to Indicate Requirement Levels [RFC2119]. 146 2. Terminology 148 JSON Web Signature (JWS) A data structure representing a digitally 149 signed or MACed message. The structure consists of three parts: 150 the JWS Header, the JWS Payload, and the JWS Signature value. 152 JSON Text Object A UTF-8 encoded text string representing a JSON 153 object; the syntax of JSON objects is defined in Section 2.2 of 154 [RFC4627]. 156 JWS Header A JSON Text Object that describes the digital signature 157 or MAC operation applied to create the JWS Signature value. 159 JWS Payload The bytes to be secured -- a.k.a., the message. The 160 payload can contain an arbitrary sequence of bytes. 162 JWS Signature A byte array containing the cryptographic material 163 that secures the JWS Header and the JWS Payload. 165 Base64url Encoding The URL- and filename-safe Base64 encoding 166 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 167 safe) '=' padding characters omitted, as permitted by Section 3.2. 168 (See Appendix C for notes on implementing base64url encoding 169 without padding.) 171 Encoded JWS Header Base64url encoding of the JWS Header. 173 Encoded JWS Payload Base64url encoding of the JWS Payload. 175 Encoded JWS Signature Base64url encoding of the JWS Signature. 177 JWS Secured Input The concatenation of the Encoded JWS Header, a 178 period ('.') character, and the Encoded JWS Payload. 180 Header Parameter Name The name of a member of the JWS Header. 182 Header Parameter Value The value of a member of the JWS Header. 184 JWS Compact Serialization A representation of the JWS as the 185 concatenation of the Encoded JWS Header, the Encoded JWS Payload, 186 and the Encoded JWS Signature in that order, with the three 187 strings being separated by two period ('.') characters. 189 Collision Resistant Namespace A namespace that allows names to be 190 allocated in a manner such that they are highly unlikely to 191 collide with other names. For instance, collision resistance can 192 be achieved through administrative delegation of portions of the 193 namespace or through use of collision-resistant name allocation 194 functions. Examples of Collision Resistant Namespaces include: 195 Domain Names, Object Identifiers (OIDs) as defined in the ITU-T 196 X.660 and X.670 Recommendation series, and Universally Unique 197 IDentifiers (UUIDs) [RFC4122]. When using an administratively 198 delegated namespace, the definer of a name needs to take 199 reasonable precautions to ensure they are in control of the 200 portion of the namespace they use to define the name. 202 StringOrURI A JSON string value, with the additional requirement 203 that while arbitrary string values MAY be used, any value 204 containing a ":" character MUST be a URI [RFC3986]. StringOrURI 205 values are compared as case-sensitive strings with no 206 transformations or canonicalizations applied. 208 3. JSON Web Signature (JWS) Overview 210 JWS represents digitally signed or MACed content using JSON data 211 structures and base64url encoding. The representation consists of 212 three parts: the JWS Header, the JWS Payload, and the JWS Signature. 213 In the Compact Serialization, the three parts are base64url-encoded 214 for transmission, and represented as the concatenation of the encoded 215 strings in that order, with the three strings being separated by two 216 period ('.') characters. (A JSON Serialization for this information 217 is defined in the separate JSON Web Signature JSON Serialization 218 (JWS-JS) [JWS-JS] specification.) 220 The JWS Header describes the signature or MAC method and parameters 221 employed. The JWS Payload is the message content to be secured. The 222 JWS Signature ensures the integrity of both the JWS Header and the 223 JWS Payload. 225 3.1. Example JWS 227 The following example JWS Header declares that the encoded object is 228 a JSON Web Token (JWT) [JWT] and the JWS Header and the JWS Payload 229 are secured using the HMAC SHA-256 algorithm: 231 {"typ":"JWT", 232 "alg":"HS256"} 234 Base64url encoding the bytes of the UTF-8 representation of the JWS 235 Header yields this Encoded JWS Header value: 237 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 239 The following is an example of a JSON object that can be used as a 240 JWS Payload. (Note that the payload can be any content, and need not 241 be a representation of a JSON object.) 243 {"iss":"joe", 244 "exp":1300819380, 245 "http://example.com/is_root":true} 247 Base64url encoding the bytes of the UTF-8 representation of the JSON 248 object yields the following Encoded JWS Payload (with line breaks for 249 display purposes only): 251 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 252 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 254 Computing the HMAC of the bytes of the ASCII [USASCII] representation 255 of the JWS Secured Input (the concatenation of the Encoded JWS 256 Header, a period ('.') character, and the Encoded JWS Payload) with 257 the HMAC SHA-256 algorithm using the key specified in Appendix A.1 258 and base64url encoding the result yields this Encoded JWS Signature 259 value: 261 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 263 Concatenating these parts in the order Header.Payload.Signature with 264 period ('.') characters between the parts yields this complete JWS 265 representation (with line breaks for display purposes only): 267 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 268 . 269 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 270 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 271 . 272 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 274 This computation is illustrated in more detail in Appendix A.1. 276 4. JWS Header 278 The members of the JSON object represented by the JWS Header describe 279 the digital signature or MAC applied to the Encoded JWS Header and 280 the Encoded JWS Payload and optionally additional properties of the 281 JWS. The Header Parameter Names within this object MUST be unique; 282 JWSs with duplicate Header Parameter Names MUST be rejected. 283 Implementations MUST understand the entire contents of the header; 284 otherwise, the JWS MUST be rejected. 286 There are three classes of Header Parameter Names: Reserved Header 287 Parameter Names, Public Header Parameter Names, and Private Header 288 Parameter Names. 290 4.1. Reserved Header Parameter Names 292 The following Header Parameter Names are reserved with meanings as 293 defined below. All the names are short because a core goal of JWSs 294 is for the representations to be compact. 296 Additional reserved Header Parameter Names MAY be defined via the 297 IANA JSON Web Signature and Encryption Header Parameters registry 298 Section 7.1. As indicated by the common registry, JWSs and JWEs 299 share a common header parameter space; when a parameter is used by 300 both specifications, its usage must be compatible between the 301 specifications. 303 4.1.1. "alg" (Algorithm) Header Parameter 305 The "alg" (algorithm) header parameter identifies the cryptographic 306 algorithm used to secure the JWS. The algorithm specified by the 307 "alg" value MUST be supported by the implementation and there MUST be 308 a key for use with that algorithm associated with the party that 309 digitally signed or MACed the content or the JWS MUST be rejected. 310 "alg" values SHOULD either be registered in the IANA JSON Web 311 Signature and Encryption Algorithms registry [JWA] or be a value that 312 contains a Collision Resistant Namespace. The "alg" value is a case 313 sensitive string containing a StringOrURI value. Use of this header 314 parameter is REQUIRED. 316 A list of defined "alg" values can be found in the IANA JSON Web 317 Signature and Encryption Algorithms registry [JWA]; the initial 318 contents of this registry are the values defined in Section 3.1 of 319 the JSON Web Algorithms (JWA) [JWA] specification. 321 4.1.2. "jku" (JWK Set URL) Header Parameter 323 The "jku" (JWK Set URL) header parameter is a URI [RFC3986] that 324 refers to a resource for a set of JSON-encoded public keys, one of 325 which corresponds to the key used to digitally sign the JWS. The 326 keys MUST be encoded as a JSON Web Key Set (JWK Set) [JWK]. The 327 protocol used to acquire the resource MUST provide integrity 328 protection; an HTTP GET request to retrieve the certificate MUST use 329 TLS [RFC2818] [RFC5246]; the identity of the server MUST be 330 validated, as per Section 3.1 of HTTP Over TLS [RFC2818]. Use of 331 this header parameter is OPTIONAL. 333 4.1.3. "jwk" (JSON Web Key) Header Parameter 335 The "jwk" (JSON Web Key) header parameter is a public key that 336 corresponds to the key used to digitally sign the JWS. This key is 337 represented as a JSON Web Key [JWK]. Use of this header parameter is 338 OPTIONAL. 340 4.1.4. "x5u" (X.509 URL) Header Parameter 342 The "x5u" (X.509 URL) header parameter is a URI [RFC3986] that refers 343 to a resource for the X.509 public key certificate or certificate 344 chain [RFC5280] corresponding to the key used to digitally sign the 345 JWS. The identified resource MUST provide a representation of the 346 certificate or certificate chain that conforms to RFC 5280 [RFC5280] 347 in PEM encoded form [RFC1421]. The certificate containing the public 348 key of the entity that digitally signed the JWS MUST be the first 349 certificate. This MAY be followed by additional certificates, with 350 each subsequent certificate being the one used to certify the 351 previous one. The protocol used to acquire the resource MUST provide 352 integrity protection; an HTTP GET request to retrieve the certificate 353 MUST use TLS [RFC2818] [RFC5246]; the identity of the server MUST be 354 validated, as per Section 3.1 of HTTP Over TLS [RFC2818]. Use of 355 this header parameter is OPTIONAL. 357 4.1.5. "x5t" (X.509 Certificate Thumbprint) Header Parameter 359 The "x5t" (X.509 Certificate Thumbprint) header parameter provides a 360 base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER 361 encoding of the X.509 certificate [RFC5280] corresponding to the key 362 used to digitally sign the JWS. Use of this header parameter is 363 OPTIONAL. 365 If, in the future, certificate thumbprints need to be computed using 366 hash functions other than SHA-1, it is suggested that additional 367 related header parameters be defined for that purpose. For example, 368 it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint 369 using SHA-256) header parameter could be defined by registering it in 370 the IANA JSON Web Signature and Encryption Header Parameters registry 371 Section 7.1. 373 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter 375 The "x5c" (X.509 Certificate Chain) header parameter contains the 376 X.509 public key certificate or certificate chain [RFC5280] 377 corresponding to the key used to digitally sign the JWS. The 378 certificate or certificate chain is represented as an array of 379 certificate value strings. Each string is a base64 encoded 380 ([RFC4648] Section 4 -- not base64url encoded) DER [ITU.X690.1994] 381 PKIX certificate value. The certificate containing the public key of 382 the entity that digitally signed the JWS MUST be the first 383 certificate. This MAY be followed by additional certificates, with 384 each subsequent certificate being the one used to certify the 385 previous one. The recipient MUST verify the certificate chain 386 according to [RFC5280] and reject the JWS if any validation failure 387 occurs. Use of this header parameter is OPTIONAL. 389 See Appendix B for an example "x5c" value. 391 4.1.7. "kid" (Key ID) Header Parameter 393 The "kid" (key ID) header parameter is a hint indicating which key 394 was used to secure the JWS. This parameter allows originators to 395 explicitly signal a change of key to recipients. Should the 396 recipient be unable to locate a key corresponding to the "kid" value, 397 they SHOULD treat that condition as an error. The interpretation of 398 the "kid" value is unspecified. Its value MUST be a string. Use of 399 this header parameter is OPTIONAL. 401 When used with a JWK, the "kid" value MAY be used to match a JWK 402 "kid" parameter value. 404 4.1.8. "typ" (Type) Header Parameter 406 The "typ" (type) header parameter is used to declare the type of this 407 object. The type value "JWS" MAY be used to indicate that this 408 object is a JWS. The "typ" value is a case sensitive string. Use of 409 this header parameter is OPTIONAL. 411 MIME Media Type [RFC2046] values MAY be used as "typ" values. 413 "typ" values SHOULD either be registered in the IANA JSON Web 414 Signature and Encryption Type Values registry Section 7.2 or be a 415 value that contains a Collision Resistant Namespace. 417 4.1.9. "cty" (Content Type) Header Parameter 419 The "cty" (content type) header parameter is used to declare the type 420 of the secured content (the Payload). The "cty" value is a case 421 sensitive string. Use of this header parameter is OPTIONAL. 423 The values used for the "cty" header parameter come from the same 424 value space as the "typ" header parameter, with the same rules 425 applying. 427 4.2. Public Header Parameter Names 429 Additional Header Parameter Names can be defined by those using JWSs. 430 However, in order to prevent collisions, any new Header Parameter 431 Name SHOULD either be registered in the IANA JSON Web Signature and 432 Encryption Header Parameters registry Section 7.1 or be a Public 433 Name: a value that contains a Collision Resistant Namespace. In each 434 case, the definer of the name or value needs to take reasonable 435 precautions to make sure they are in control of the part of the 436 namespace they use to define the Header Parameter Name. 438 New header parameters should be introduced sparingly, as they can 439 result in non-interoperable JWSs. 441 4.3. Private Header Parameter Names 443 A producer and consumer of a JWS may agree to use Header Parameter 444 Names that are Private Names: names that are not Reserved Names 445 Section 4.1 or Public Names Section 4.2. Unlike Public Names, 446 Private Names are subject to collision and should be used with 447 caution. 449 5. Producing and Consuming JWSs 451 5.1. Message Signing or MACing 453 To create a JWS, one MUST perform these steps. The order of the 454 steps is not significant in cases where there are no dependencies 455 between the inputs and outputs of the steps. 457 1. Create the content to be used as the JWS Payload. 459 2. Base64url encode the bytes of the JWS Payload. This encoding 460 becomes the Encoded JWS Payload. 462 3. Create a JWS Header containing the desired set of header 463 parameters. Note that white space is explicitly allowed in the 464 representation and no canonicalization need be performed before 465 encoding. 467 4. Base64url encode the bytes of the UTF-8 representation of the JWS 468 Header to create the Encoded JWS Header. 470 5. Compute the JWS Signature in the manner defined for the 471 particular algorithm being used. The JWS Secured Input is always 472 the concatenation of the Encoded JWS Header, a period ('.') 473 character, and the Encoded JWS Payload. The "alg" (algorithm) 474 header parameter MUST be present in the JSON Header, with the 475 algorithm value accurately representing the algorithm used to 476 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 two period ('.') characters. 487 5.2. Message Signature or MAC Validation 489 When validating a JWS, the following steps MUST be taken. The order 490 of the steps is not significant in cases where there are no 491 dependencies between the inputs and outputs of the steps. If any of 492 the listed steps fails, then the JWS MUST be rejected. 494 1. Parse the three parts of the input (which are separated by period 495 ('.') characters when using the JWS Compact Serialization) into 496 the Encoded JWS Header, the Encoded JWS Payload, and the Encoded 497 JWS Signature. 499 2. The Encoded JWS Header MUST be successfully base64url decoded 500 following the restriction given in this specification that no 501 padding characters have been used. 503 3. The resulting JWS Header MUST be completely valid JSON syntax 504 conforming to RFC 4627 [RFC4627]. 506 4. The resulting JWS Header MUST be validated to only include 507 parameters and values whose syntax and semantics are both 508 understood and supported. 510 5. The Encoded JWS Payload MUST be successfully base64url decoded 511 following the restriction given in this specification that no 512 padding characters have been used. 514 6. The Encoded JWS Signature MUST be successfully base64url decoded 515 following the restriction given in this specification that no 516 padding characters have been used. 518 7. The JWS Signature MUST be successfully validated against the JWS 519 Secured Input (the concatenation of the Encoded JWS Header, a 520 period ('.') character, and the Encoded JWS Payload) in the 521 manner defined for the algorithm being used, which MUST be 522 accurately represented by the value of the "alg" (algorithm) 523 header parameter, which MUST be present. 525 5.3. String Comparison Rules 527 Processing a JWS inevitably requires comparing known strings to 528 values in JSON objects. For example, in checking what the algorithm 529 is, the Unicode string encoding "alg" will be checked against the 530 member names in the JWS Header to see if there is a matching Header 531 Parameter Name. A similar process occurs when determining if the 532 value of the "alg" header parameter represents a supported algorithm. 534 Comparisons between JSON strings and other Unicode strings MUST be 535 performed as specified below: 537 1. Remove any JSON escaping from the input JSON string and convert 538 the string into a sequence of Unicode code points. 540 2. Likewise, convert the string to be compared against into a 541 sequence of Unicode code points. 543 3. Unicode Normalization [USA15] MUST NOT be applied at any point to 544 either the JSON string or to the string it is to be compared 545 against. 547 4. Comparisons between the two strings MUST be performed as a 548 Unicode code point to code point equality comparison. (Note that 549 values that originally used different Unicode encodings (UTF-8, 550 UTF-16, etc.) may result in the same code point values.) 552 Also, see the JSON security considerations in Section 8.2 and the 553 Unicode security considerations in Section 8.3. 555 6. Securing JWSs with Cryptographic Algorithms 557 JWS uses cryptographic algorithms to digitally sign or MAC the JWS 558 Header and the JWS Payload. The JSON Web Algorithms (JWA) [JWA] 559 specification describes a set of cryptographic algorithms and 560 identifiers to be used with this specification. Specifically, 561 Section 3.1 specifies a set of "alg" (algorithm) header parameter 562 values intended for use this specification. It also describes the 563 semantics and operations that are specific to these algorithms. 565 Public keys employed for digital signing can be identified using the 566 Header Parameter methods described in Section 4.1 or can be 567 distributed using methods that are outside the scope of this 568 specification. 570 7. IANA Considerations 572 The following registration procedure is used for all the registries 573 established by this specification. 575 Values are registered with a Specification Required [RFC5226] after a 576 two-week review period on the [TBD]@ietf.org mailing list, on the 577 advice of one or more Designated Experts. However, to allow for the 578 allocation of values prior to publication, the Designated Expert(s) 579 may approve registration once they are satisfied that such a 580 specification will be published. 582 Registration requests must be sent to the [TBD]@ietf.org mailing list 583 for review and comment, with an appropriate subject (e.g., "Request 584 for access token type: example"). [[ Note to RFC-EDITOR: The name of 585 the mailing list should be determined in consultation with the IESG 586 and IANA. Suggested name: jose-reg-review. ]] 588 Within the review period, the Designated Expert(s) will either 589 approve or deny the registration request, communicating this decision 590 to the review list and IANA. Denials should include an explanation 591 and, if applicable, suggestions as to how to make the request 592 successful. 594 IANA must only accept registry updates from the Designated Expert(s) 595 and should direct all requests for registration to the review mailing 596 list. 598 7.1. JSON Web Signature and Encryption Header Parameters Registry 600 This specification establishes the IANA JSON Web Signature and 601 Encryption Header Parameters registry for reserved JWS and JWE Header 602 Parameter Names. The registry records the reserved Header Parameter 603 Name and a reference to the specification that defines it. The same 604 Header Parameter Name may be registered multiple times, provided that 605 the parameter usage is compatible between the specifications. 606 Different registrations of the same Header Parameter Name will 607 typically use different Header Parameter Usage Location(s) values. 609 7.1.1. Registration Template 611 Header Parameter Name: 612 The name requested (e.g., "example"). This name is case 613 sensitive. Names that match other registered names in a case 614 insensitive manner SHOULD NOT be accepted. 616 Header Parameter Usage Location(s): 617 The header parameter usage locations, which should be one or more 618 of the values "JWS" or "JWE". 620 Change Controller: 621 For Standards Track RFCs, state "IETF". For others, give the name 622 of the responsible party. Other details (e.g., postal address, 623 email address, home page URI) may also be included. 625 Specification Document(s): 626 Reference to the document(s) that specify the parameter, 627 preferably including URI(s) that can be used to retrieve copies of 628 the document(s). An indication of the relevant sections may also 629 be included but is not required. 631 7.1.2. Initial Registry Contents 633 This specification registers the Header Parameter Names defined in 634 Section 4.1 in this registry. 636 o Header Parameter Name: "alg" 637 o Header Parameter Usage Location(s): JWS 638 o Change Controller: IETF 639 o Specification Document(s): Section 4.1.1 of [[ this document ]] 641 o Header Parameter Name: "jku" 642 o Header Parameter Usage Location(s): JWS 643 o Change Controller: IETF 644 o Specification Document(s): Section 4.1.2 of [[ this document ]] 646 o Header Parameter Name: "jwk" 647 o Header Parameter Usage Location(s): JWS 648 o Change Controller: IETF 649 o Specification document(s): Section 4.1.3 of [[ this document ]] 651 o Header Parameter Name: "x5u" 652 o Header Parameter Usage Location(s): JWS 653 o Change Controller: IETF 654 o Specification Document(s): Section 4.1.4 of [[ this document ]] 656 o Header Parameter Name: "x5t" 657 o Header Parameter Usage Location(s): JWS 658 o Change Controller: IETF 659 o Specification Document(s): Section 4.1.5 of [[ this document ]] 661 o Header Parameter Name: "x5c" 662 o Header Parameter Usage Location(s): JWS 663 o Change Controller: IETF 664 o Specification Document(s): Section 4.1.6 of [[ this document ]] 666 o Header Parameter Name: "kid" 667 o Header Parameter Usage Location(s): JWS 668 o Change Controller: IETF 669 o Specification Document(s): Section 4.1.7 of [[ this document ]] 671 o Header Parameter Name: "typ" 672 o Header Parameter Usage Location(s): JWS 673 o Change Controller: IETF 674 o Specification Document(s): Section 4.1.8 of [[ this document ]] 676 o Header Parameter Name: "cty" 677 o Header Parameter Usage Location(s): JWS 678 o Change Controller: IETF 679 o Specification Document(s): Section 4.1.9 of [[ this document ]] 681 7.2. JSON Web Signature and Encryption Type Values Registry 683 This specification establishes the IANA JSON Web Signature and 684 Encryption Type Values registry for values of the JWS and JWE "typ" 685 (type) header parameter. It is RECOMMENDED that all registered "typ" 686 values also include a MIME Media Type [RFC2046] value that the 687 registered value is a short name for. The registry records the "typ" 688 value, the MIME type value that it is an abbreviation for (if any), 689 and a reference to the specification that defines it. 691 MIME Media Type [RFC2046] values MUST NOT be directly registered as 692 new "typ" values; rather, new "typ" values MAY be registered as short 693 names for MIME types. 695 7.2.1. Registration Template 697 "typ" Header Parameter Value: 698 The name requested (e.g., "example"). This name is case 699 sensitive. Names that match other registered names in a case 700 insensitive manner SHOULD NOT be accepted. 702 Abbreviation for MIME Type: 703 The MIME type that this name is an abbreviation for (e.g., 704 "application/example"). 706 Change Controller: 707 For Standards Track RFCs, state "IETF". For others, give the name 708 of the responsible party. Other details (e.g., postal address, 709 email address, home page URI) may also be included. 711 Specification Document(s): 712 Reference to the document(s) that specify the parameter, 713 preferably including URI(s) that can be used to retrieve copies of 714 the document(s). An indication of the relevant sections may also 715 be included but is not required. 717 7.2.2. Initial Registry Contents 719 This specification registers the "JWS" type value in this registry: 721 o "typ" Header Parameter Value: "JWS" 722 o Abbreviation for MIME type: application/jws 723 o Change Controller: IETF 724 o Specification Document(s): Section 4.1.8 of [[ this document ]] 726 7.3. Media Type Registration 728 7.3.1. Registry Contents 730 This specification registers the "application/jws" Media Type 731 [RFC2046] in the MIME Media Type registry [RFC4288] to indicate that 732 the content is a JWS using the Compact Serialization. 734 o Type name: application 735 o Subtype name: jws 736 o Required parameters: n/a 737 o Optional parameters: n/a 738 o Encoding considerations: JWS values are encoded as a series of 739 base64url encoded values (some of which may be the empty string) 740 separated by period ('.') characters 742 o Security considerations: See the Security Considerations section 743 of this document 744 o Interoperability considerations: n/a 745 o Published specification: [[ this document ]] 746 o Applications that use this media type: OpenID Connect, Mozilla 747 Browser ID, Salesforce, Google, numerous others that use signed 748 JWTs 749 o Additional information: Magic number(s): n/a, File extension(s): 750 n/a, Macintosh file type code(s): n/a 751 o Person & email address to contact for further information: Michael 752 B. Jones, mbj@microsoft.com 753 o Intended usage: COMMON 754 o Restrictions on usage: none 755 o Author: Michael B. Jones, mbj@microsoft.com 756 o Change Controller: IETF 758 8. Security Considerations 760 8.1. Cryptographic Security Considerations 762 All of the security issues faced by any cryptographic application 763 must be faced by a JWS/JWE/JWK agent. Among these issues are 764 protecting the user's private and symmetric keys, preventing various 765 attacks, and helping the user avoid mistakes such as inadvertently 766 encrypting a message for the wrong recipient. The entire list of 767 security considerations is beyond the scope of this document, but 768 some significant concerns are listed here. 770 All the security considerations in XML DSIG 2.0 771 [W3C.CR-xmldsig-core2-20120124], also apply to this specification, 772 other than those that are XML specific. Likewise, many of the best 773 practices documented in XML Signature Best Practices 774 [W3C.WD-xmldsig-bestpractices-20110809] also apply to this 775 specification, other than those that are XML specific. 777 Keys are only as strong as the amount of entropy used to generate 778 them. A minimum of 128 bits of entropy should be used for all keys, 779 and depending upon the application context, more may be required. In 780 particular, it may be difficult to generate sufficiently random 781 values in some browsers and application environments. 783 When utilizing TLS to retrieve information, the authority providing 784 the resource MUST be authenticated and the information retrieved MUST 785 be free from modification. 787 When cryptographic algorithms are implemented in such a way that 788 successful operations take a different amount of time than 789 unsuccessful operations, attackers may be able to use the time 790 difference to obtain information about the keys employed. Therefore, 791 such timing differences must be avoided. 793 A SHA-1 hash is used when computing "x5t" (x.509 certificate 794 thumbprint) values, for compatibility reasons. Should an effective 795 means of producing SHA-1 hash collisions be developed, and should an 796 attacker wish to interfere with the use of a known certificate on a 797 given system, this could be accomplished by creating another 798 certificate whose SHA-1 hash value is the same and adding it to the 799 certificate store used by the intended victim. A prerequisite to 800 this attack succeeding is the attacker having write access to the 801 intended victim's certificate store. 803 If, in the future, certificate thumbprints need to be computed using 804 hash functions other than SHA-1, it is suggested that additional 805 related header parameters be defined for that purpose. For example, 806 it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint 807 using SHA-256) header parameter could be defined and used. 809 8.2. JSON Security Considerations 811 Strict JSON validation is a security requirement. If malformed JSON 812 is received, then the intent of the sender is impossible to reliably 813 discern. Ambiguous and potentially exploitable situations could 814 arise if the JSON parser used does not reject malformed JSON syntax. 816 Section 2.2 of the JavaScript Object Notation (JSON) specification 817 [RFC4627] states "The names within an object SHOULD be unique", 818 whereas this specification states that "Header Parameter Names within 819 this object MUST be unique; JWSs with duplicate Header Parameter 820 Names MUST be rejected". Thus, this specification requires that the 821 Section 2.2 "SHOULD" be treated as a "MUST". Ambiguous and 822 potentially exploitable situations could arise if the JSON parser 823 used does not enforce the uniqueness of member names. 825 8.3. Unicode Comparison Security Considerations 827 Header Parameter Names and algorithm names are Unicode strings. For 828 security reasons, the representations of these names must be compared 829 verbatim after performing any escape processing (as per RFC 4627 830 [RFC4627], Section 2.5). This means, for instance, that these JSON 831 strings must compare as being equal ("sig", "\u0073ig"), whereas 832 these must all compare as being not equal to the first set or to each 833 other ("SIG", "Sig", "si\u0047"). 835 JSON strings MAY contain characters outside the Unicode Basic 836 Multilingual Plane. For instance, the G clef character (U+1D11E) may 837 be represented in a JSON string as "\uD834\uDD1E". Ideally, JWS 838 implementations SHOULD ensure that characters outside the Basic 839 Multilingual Plane are preserved and compared correctly; 840 alternatively, if this is not possible due to these characters 841 exercising limitations present in the underlying JSON implementation, 842 then input containing them MUST be rejected. 844 9. References 846 9.1. Normative References 848 [ITU.X690.1994] 849 International Telecommunications Union, "Information 850 Technology - ASN.1 encoding rules: Specification of Basic 851 Encoding Rules (BER), Canonical Encoding Rules (CER) and 852 Distinguished Encoding Rules (DER)", ITU-T Recommendation 853 X.690, 1994. 855 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 856 draft-ietf-jose-json-web-algorithms (work in progress), 857 December 2012. 859 [JWK] Jones, M., "JSON Web Key (JWK)", 860 draft-ietf-jose-json-web-key (work in progress), 861 December 2012. 863 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 864 Mail: Part I: Message Encryption and Authentication 865 Procedures", RFC 1421, February 1993. 867 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 868 Extensions (MIME) Part Two: Media Types", RFC 2046, 869 November 1996. 871 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 872 Requirement Levels", BCP 14, RFC 2119, March 1997. 874 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 876 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 877 10646", STD 63, RFC 3629, November 2003. 879 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 880 Resource Identifier (URI): Generic Syntax", STD 66, 881 RFC 3986, January 2005. 883 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 884 Registration Procedures", BCP 13, RFC 4288, December 2005. 886 [RFC4627] Crockford, D., "The application/json Media Type for 887 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 889 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 890 Encodings", RFC 4648, October 2006. 892 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 893 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 894 May 2008. 896 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 897 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 899 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 900 Housley, R., and W. Polk, "Internet X.509 Public Key 901 Infrastructure Certificate and Certificate Revocation List 902 (CRL) Profile", RFC 5280, May 2008. 904 [USA15] Davis, M., Whistler, K., and M. Duerst, "Unicode 905 Normalization Forms", Unicode Standard Annex 15, 09 2009. 907 [USASCII] American National Standards Institute, "Coded Character 908 Set -- 7-bit American Standard Code for Information 909 Interchange", ANSI X3.4, 1986. 911 [W3C.WD-xmldsig-bestpractices-20110809] 912 Datta, P. and F. Hirsch, "XML Signature Best Practices", 913 World Wide Web Consortium WD WD-xmldsig-bestpractices- 914 20110809, August 2011, . 917 9.2. Informative References 919 [CanvasApp] 920 Facebook, "Canvas Applications", 2010. 922 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 923 September 2010. 925 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 926 Encryption (JWE)", draft-ietf-jose-json-web-encryption 927 (work in progress), December 2012. 929 [JWS-JS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 930 Signature JSON Serialization (JWS-JS)", 931 draft-jones-jose-jws-json-serialization (work in 932 progress), December 2012. 934 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 935 (JWT)", draft-ietf-oauth-json-web-token (work in 936 progress), December 2012. 938 [MagicSignatures] 939 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 940 Signatures", January 2011. 942 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 943 Unique IDentifier (UUID) URN Namespace", RFC 4122, 944 July 2005. 946 [W3C.CR-xmldsig-core2-20120124] 947 Yiu, K., Solo, D., Eastlake, D., Datta, P., Hirsch, F., 948 Reagle, J., Cantor, S., and T. Roessler, "XML Signature 949 Syntax and Processing Version 2.0", World Wide Web 950 Consortium CR CR-xmldsig-core2-20120124, January 2012, 951 . 953 Appendix A. JWS Examples 955 This section provides several examples of JWSs. While these examples 956 all represent JSON Web Tokens (JWTs) [JWT], the payload can be any 957 base64url encoded content. 959 A.1. JWS using HMAC SHA-256 961 A.1.1. Encoding 963 The following example JWS Header declares that the data structure is 964 a JSON Web Token (JWT) [JWT] and the JWS Secured Input is secured 965 using the HMAC SHA-256 algorithm. 967 {"typ":"JWT", 968 "alg":"HS256"} 970 The following byte array contains the UTF-8 representation of the JWS 971 Header: 973 [123, 34, 116, 121, 112, 34, 58, 34, 74, 87, 84, 34, 44, 13, 10, 32, 974 34, 97, 108, 103, 34, 58, 34, 72, 83, 50, 53, 54, 34, 125] 976 Base64url encoding these bytes yields this Encoded JWS Header value: 978 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 980 The JWS Payload used in this example is the bytes of the UTF-8 981 representation of the JSON object below. (Note that the payload can 982 be any base64url encoded sequence of bytes, and need not be a 983 base64url encoded JSON object.) 985 {"iss":"joe", 986 "exp":1300819380, 987 "http://example.com/is_root":true} 989 The following byte array, which is the UTF-8 representation of the 990 JSON object above, is the JWS Payload: 992 [123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10, 993 32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56, 994 48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97, 995 109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111, 996 111, 116, 34, 58, 116, 114, 117, 101, 125] 998 Base64url encoding the above yields the Encoded JWS Payload value 999 (with line breaks for display purposes only): 1001 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1002 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1004 Concatenating the Encoded JWS Header, a period ('.') character, and 1005 the Encoded JWS Payload yields this JWS Secured Input value (with 1006 line breaks for display purposes only): 1008 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 1009 . 1010 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1011 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1013 The ASCII representation of the JWS Secured Input is the following 1014 byte array: 1016 [101, 121, 74, 48, 101, 88, 65, 105, 79, 105, 74, 75, 86, 49, 81, 1017 105, 76, 65, 48, 75, 73, 67, 74, 104, 98, 71, 99, 105, 79, 105, 74, 1018 73, 85, 122, 73, 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 1019 77, 105, 79, 105, 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 1020 74, 108, 101, 72, 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 1021 107, 122, 79, 68, 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 1022 72, 65, 54, 76, 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 1023 109, 78, 118, 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 1024 106, 112, 48, 99, 110, 86, 108, 102, 81] 1026 HMACs are generated using keys. This example uses the key 1027 represented by the following byte array: 1029 [3, 35, 53, 75, 43, 15, 165, 188, 131, 126, 6, 101, 119, 123, 166, 1030 143, 90, 179, 40, 230, 240, 84, 201, 40, 169, 15, 132, 178, 210, 80, 1031 46, 191, 211, 251, 90, 146, 210, 6, 71, 239, 150, 138, 180, 195, 119, 1032 98, 61, 34, 61, 46, 33, 114, 5, 46, 79, 8, 192, 205, 154, 245, 103, 1033 208, 128, 163] 1035 Running the HMAC SHA-256 algorithm on the bytes of the ASCII 1036 representation of the JWS Secured Input with this key yields the 1037 following byte array: 1039 [116, 24, 223, 180, 151, 153, 224, 37, 79, 250, 96, 125, 216, 173, 1040 187, 186, 22, 212, 37, 77, 105, 214, 191, 240, 91, 88, 5, 88, 83, 1041 132, 141, 121] 1043 Base64url encoding the above HMAC output yields the Encoded JWS 1044 Signature value: 1046 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 1048 A.1.2. Decoding 1050 Decoding the JWS requires base64url decoding the Encoded JWS Header, 1051 Encoded JWS Payload, and Encoded JWS Signature to produce the JWS 1052 Header, JWS Payload, and JWS Signature byte arrays. The byte array 1053 containing the UTF-8 representation of the JWS Header is decoded into 1054 the JWS Header string. 1056 A.1.3. Validating 1058 Next we validate the decoded results. Since the "alg" parameter in 1059 the header is "HS256", we validate the HMAC SHA-256 value contained 1060 in the JWS Signature. If any of the validation steps fail, the JWS 1061 MUST be rejected. 1063 First, we validate that the JWS Header string is legal JSON. 1065 To validate the HMAC value, we repeat the previous process of using 1066 the correct key and the ASCII representation of the JWS Secured Input 1067 as input to the HMAC SHA-256 function and then taking the output and 1068 determining if it matches the JWS Signature. If it matches exactly, 1069 the HMAC has been validated. 1071 A.2. JWS using RSA SHA-256 1073 A.2.1. Encoding 1075 The JWS Header in this example is different from the previous example 1076 in two ways: First, because a different algorithm is being used, the 1077 "alg" value is different. Second, for illustration purposes only, 1078 the optional "typ" parameter is not used. (This difference is not 1079 related to the algorithm employed.) The JWS Header used is: 1081 {"alg":"RS256"} 1083 The following byte array contains the UTF-8 representation of the JWS 1084 Header: 1086 [123, 34, 97, 108, 103, 34, 58, 34, 82, 83, 50, 53, 54, 34, 125] 1088 Base64url encoding these bytes yields this Encoded JWS Header value: 1090 eyJhbGciOiJSUzI1NiJ9 1092 The JWS Payload used in this example, which follows, is the same as 1093 in the previous example. Since the Encoded JWS Payload will 1094 therefore be the same, its computation is not repeated here. 1096 {"iss":"joe", 1097 "exp":1300819380, 1098 "http://example.com/is_root":true} 1100 Concatenating the Encoded JWS Header, a period ('.') character, and 1101 the Encoded JWS Payload yields this JWS Secured Input value (with 1102 line breaks for display purposes only): 1104 eyJhbGciOiJSUzI1NiJ9 1105 . 1106 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1107 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1109 The ASCII representation of the JWS Secured Input is the following 1110 byte array: 1112 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 122, 73, 1113 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, 1114 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 74, 108, 101, 72, 1115 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 107, 122, 79, 68, 1116 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 72, 65, 54, 76, 1117 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 109, 78, 118, 1118 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48, 1119 99, 110, 86, 108, 102, 81] 1121 The RSA key consists of a public part (Modulus, Exponent), and a 1122 Private Exponent. The values of the RSA key used in this example, 1123 presented as the byte arrays representing big endian integers are: 1125 +-----------+-------------------------------------------------------+ 1126 | Parameter | Value | 1127 | Name | | 1128 +-----------+-------------------------------------------------------+ 1129 | Modulus | [161, 248, 22, 10, 226, 227, 201, 180, 101, 206, 141, | 1130 | | 45, 101, 98, 99, 54, 43, 146, 125, 190, 41, 225, 240, | 1131 | | 36, 119, 252, 22, 37, 204, 144, 161, 54, 227, 139, | 1132 | | 217, 52, 151, 197, 182, 234, 99, 221, 119, 17, 230, | 1133 | | 124, 116, 41, 249, 86, 176, 251, 138, 143, 8, 154, | 1134 | | 220, 75, 105, 137, 60, 193, 51, 63, 83, 237, 208, 25, | 1135 | | 184, 119, 132, 37, 47, 236, 145, 79, 228, 133, 119, | 1136 | | 105, 89, 75, 234, 66, 128, 211, 44, 15, 85, 191, 98, | 1137 | | 148, 79, 19, 3, 150, 188, 110, 155, 223, 110, 189, | 1138 | | 210, 189, 163, 103, 142, 236, 160, 198, 104, 247, 1, | 1139 | | 179, 141, 191, 251, 56, 200, 52, 44, 226, 254, 109, | 1140 | | 39, 250, 222, 74, 90, 72, 116, 151, 157, 212, 185, | 1141 | | 207, 154, 222, 196, 199, 91, 5, 133, 44, 44, 15, 94, | 1142 | | 248, 165, 193, 117, 3, 146, 249, 68, 232, 237, 100, | 1143 | | 193, 16, 198, 182, 71, 96, 154, 164, 120, 58, 235, | 1144 | | 156, 108, 154, 215, 85, 49, 48, 80, 99, 139, 131, | 1145 | | 102, 92, 111, 111, 122, 130, 163, 150, 112, 42, 31, | 1146 | | 100, 27, 130, 211, 235, 242, 57, 34, 25, 73, 31, 182, | 1147 | | 134, 135, 44, 87, 22, 245, 10, 248, 53, 141, 154, | 1148 | | 139, 157, 23, 195, 64, 114, 143, 127, 135, 216, 154, | 1149 | | 24, 216, 252, 171, 103, 173, 132, 89, 12, 46, 207, | 1150 | | 117, 147, 57, 54, 60, 7, 3, 77, 111, 96, 111, 158, | 1151 | | 33, 224, 84, 86, 202, 229, 233, 161] | 1152 | Exponent | [1, 0, 1] | 1153 | Private | [18, 174, 113, 164, 105, 205, 10, 43, 195, 126, 82, | 1154 | Exponent | 108, 69, 0, 87, 31, 29, 97, 117, 29, 100, 233, 73, | 1155 | | 112, 123, 98, 89, 15, 157, 11, 165, 124, 150, 60, 64, | 1156 | | 30, 63, 207, 47, 44, 211, 189, 236, 136, 229, 3, 191, | 1157 | | 198, 67, 155, 11, 40, 200, 47, 125, 55, 151, 103, 31, | 1158 | | 82, 19, 238, 216, 193, 90, 37, 216, 213, 206, 160, 2, | 1159 | | 94, 227, 171, 46, 139, 127, 121, 33, 111, 198, 59, | 1160 | | 234, 86, 39, 83, 180, 6, 68, 198, 161, 81, 39, 217, | 1161 | | 178, 149, 69, 64, 160, 187, 225, 163, 5, 86, 152, 45, | 1162 | | 78, 159, 222, 95, 100, 37, 241, 77, 75, 113, 52, 65, | 1163 | | 181, 93, 199, 59, 155, 74, 237, 204, 146, 172, 227, | 1164 | | 146, 126, 55, 245, 125, 12, 253, 94, 117, 129, 250, | 1165 | | 81, 44, 143, 73, 97, 169, 235, 11, 128, 248, 168, 7, | 1166 | | 70, 114, 138, 85, 255, 70, 71, 31, 52, 37, 6, 59, | 1167 | | 157, 83, 100, 47, 94, 222, 30, 132, 214, 19, 8, 26, | 1168 | | 250, 92, 34, 208, 81, 40, 91, 214, 59, 148, 59, 86, | 1169 | | 93, 137, 138, 5, 104, 84, 19, 229, 60, 60, 108, 101, | 1170 | | 37, 255, 31, 227, 78, 61, 220, 112, 240, 213, 100, | 1171 | | 80, 253, 164, 139, 161, 46, 16, 78, 157, 235, 159, | 1172 | | 184, 24, 129, 225, 196, 189, 242, 93, 146, 71, 244, | 1173 | | 80, 200, 101, 146, 121, 104, 231, 115, 52, 244, 65, | 1174 | | 79, 117, 167, 80, 225, 57, 84, 110, 58, 138, 115, | 1175 | | 157] | 1176 +-----------+-------------------------------------------------------+ 1178 The RSA private key (Modulus, Private Exponent) is then passed to the 1179 RSA signing function, which also takes the hash type, SHA-256, and 1180 the bytes of the ASCII representation of the JWS Secured Input as 1181 inputs. The result of the digital signature is a byte array, which 1182 represents a big endian integer. In this example, it is: 1184 [112, 46, 33, 137, 67, 232, 143, 209, 30, 181, 216, 45, 191, 120, 69, 1185 243, 65, 6, 174, 27, 129, 255, 247, 115, 17, 22, 173, 209, 113, 125, 1186 131, 101, 109, 66, 10, 253, 60, 150, 238, 221, 115, 162, 102, 62, 81, 1187 102, 104, 123, 0, 11, 135, 34, 110, 1, 135, 237, 16, 115, 249, 69, 1188 229, 130, 173, 252, 239, 22, 216, 90, 121, 142, 232, 198, 109, 219, 1189 61, 184, 151, 91, 23, 208, 148, 2, 190, 237, 213, 217, 217, 112, 7, 1190 16, 141, 178, 129, 96, 213, 248, 4, 12, 167, 68, 87, 98, 184, 31, 1191 190, 127, 249, 217, 46, 10, 231, 111, 36, 242, 91, 51, 187, 230, 244, 1192 74, 230, 30, 177, 4, 10, 203, 32, 4, 77, 62, 249, 18, 142, 212, 1, 1193 48, 121, 91, 212, 189, 59, 65, 238, 202, 208, 102, 171, 101, 25, 129, 1194 253, 228, 141, 247, 127, 55, 45, 195, 139, 159, 175, 221, 59, 239, 1195 177, 139, 93, 163, 204, 60, 46, 176, 47, 158, 58, 65, 214, 18, 202, 1196 173, 21, 145, 18, 115, 160, 95, 35, 185, 232, 56, 250, 175, 132, 157, 1197 105, 132, 41, 239, 90, 30, 136, 121, 130, 54, 195, 212, 14, 96, 69, 1198 34, 165, 68, 200, 242, 122, 122, 45, 184, 6, 99, 209, 108, 247, 202, 1199 234, 86, 222, 64, 92, 178, 33, 90, 69, 178, 194, 85, 102, 181, 90, 1200 193, 167, 72, 160, 112, 223, 200, 163, 42, 70, 149, 67, 208, 25, 238, 1201 251, 71] 1203 Base64url encoding the digital signature produces this value for the 1204 Encoded JWS Signature (with line breaks for display purposes only): 1206 cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7 1207 AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4 1208 BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K 1209 0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqv 1210 hJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrB 1211 p0igcN_IoypGlUPQGe77Rw 1213 A.2.2. Decoding 1215 Decoding the JWS requires base64url decoding the Encoded JWS Header, 1216 Encoded JWS Payload, and Encoded JWS Signature to produce the JWS 1217 Header, JWS Payload, and JWS Signature byte arrays. The byte array 1218 containing the UTF-8 representation of the JWS Header is decoded into 1219 the JWS Header string. 1221 A.2.3. Validating 1223 Since the "alg" parameter in the header is "RS256", we validate the 1224 RSA SHA-256 digital signature contained in the JWS Signature. If any 1225 of the validation steps fail, the JWS MUST be rejected. 1227 First, we validate that the JWS Header string is legal JSON. 1229 Validating the JWS Signature is a little different from the previous 1230 example. First, we base64url decode the Encoded JWS Signature to 1231 produce a digital signature S to check. We then pass (n, e), S and 1232 the bytes of the ASCII representation of the JWS Secured Input to an 1233 RSA signature verifier that has been configured to use the SHA-256 1234 hash function. 1236 A.3. JWS using ECDSA P-256 SHA-256 1238 A.3.1. Encoding 1240 The JWS Header for this example differs from the previous example 1241 because a different algorithm is being used. The JWS Header used is: 1243 {"alg":"ES256"} 1245 The following byte array contains the UTF-8 representation of the JWS 1246 Header: 1248 [123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 50, 53, 54, 34, 125] 1249 Base64url encoding these bytes yields this Encoded JWS Header value: 1251 eyJhbGciOiJFUzI1NiJ9 1253 The JWS Payload used in this example, which follows, is the same as 1254 in the previous examples. Since the Encoded JWS Payload will 1255 therefore be the same, its computation is not repeated here. 1257 {"iss":"joe", 1258 "exp":1300819380, 1259 "http://example.com/is_root":true} 1261 Concatenating the Encoded JWS Header, a period ('.') character, and 1262 the Encoded JWS Payload yields this JWS Secured Input value (with 1263 line breaks for display purposes only): 1265 eyJhbGciOiJFUzI1NiJ9 1266 . 1267 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1268 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1270 The ASCII representation of the JWS Secured Input is the following 1271 byte array: 1273 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 70, 85, 122, 73, 1274 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, 1275 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 74, 108, 101, 72, 1276 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 107, 122, 79, 68, 1277 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 72, 65, 54, 76, 1278 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 109, 78, 118, 1279 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48, 1280 99, 110, 86, 108, 102, 81] 1282 The ECDSA key consists of a public part, the EC point (x, y), and a 1283 private part d. The values of the ECDSA key used in this example, 1284 presented as the byte arrays representing three 256 bit big endian 1285 integers are: 1287 +-----------+-------------------------------------------------------+ 1288 | Parameter | Value | 1289 | Name | | 1290 +-----------+-------------------------------------------------------+ 1291 | x | [127, 205, 206, 39, 112, 246, 196, 93, 65, 131, 203, | 1292 | | 238, 111, 219, 75, 123, 88, 7, 51, 53, 123, 233, 239, | 1293 | | 19, 186, 207, 110, 60, 123, 209, 84, 69] | 1294 | y | [199, 241, 68, 205, 27, 189, 155, 126, 135, 44, 223, | 1295 | | 237, 185, 238, 185, 244, 179, 105, 93, 110, 169, 11, | 1296 | | 36, 173, 138, 70, 35, 40, 133, 136, 229, 173] | 1297 | d | [142, 155, 16, 158, 113, 144, 152, 191, 152, 4, 135, | 1298 | | 223, 31, 93, 119, 233, 203, 41, 96, 110, 190, 210, | 1299 | | 38, 59, 95, 87, 194, 19, 223, 132, 244, 178] | 1300 +-----------+-------------------------------------------------------+ 1302 The ECDSA private part d is then passed to an ECDSA signing function, 1303 which also takes the curve type, P-256, the hash type, SHA-256, and 1304 the bytes of the ASCII representation of the JWS Secured Input as 1305 inputs. The result of the digital signature is the EC point (R, S), 1306 where R and S are unsigned integers. In this example, the R and S 1307 values, given as byte arrays representing big endian integers are: 1309 +--------+----------------------------------------------------------+ 1310 | Result | Value | 1311 | Name | | 1312 +--------+----------------------------------------------------------+ 1313 | R | [14, 209, 33, 83, 121, 99, 108, 72, 60, 47, 127, 21, 88, | 1314 | | 7, 212, 2, 163, 178, 40, 3, 58, 249, 124, 126, 23, 129, | 1315 | | 154, 195, 22, 158, 166, 101] | 1316 | S | [197, 10, 7, 211, 140, 60, 112, 229, 216, 241, 45, 175, | 1317 | | 8, 74, 84, 128, 166, 101, 144, 197, 242, 147, 80, 154, | 1318 | | 143, 63, 127, 138, 131, 163, 84, 213] | 1319 +--------+----------------------------------------------------------+ 1321 Concatenating the S array to the end of the R array and base64url 1322 encoding the result produces this value for the Encoded JWS Signature 1323 (with line breaks for display purposes only): 1325 DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSA 1326 pmWQxfKTUJqPP3-Kg6NU1Q 1328 A.3.2. Decoding 1330 Decoding the JWS requires base64url decoding the Encoded JWS Header, 1331 Encoded JWS Payload, and Encoded JWS Signature to produce the JWS 1332 Header, JWS Payload, and JWS Signature byte arrays. The byte array 1333 containing the UTF-8 representation of the JWS Header is decoded into 1334 the JWS Header string. 1336 A.3.3. Validating 1338 Since the "alg" parameter in the header is "ES256", we validate the 1339 ECDSA P-256 SHA-256 digital signature contained in the JWS Signature. 1340 If any of the validation steps fail, the JWS MUST be rejected. 1342 First, we validate that the JWS Header string is legal JSON. 1344 Validating the JWS Signature is a little different from the first 1345 example. First, we base64url decode the Encoded JWS Signature as in 1346 the previous examples but we then need to split the 64 member byte 1347 array that must result into two 32 byte arrays, the first R and the 1348 second S. We then pass (x, y), (R, S) and the bytes of the ASCII 1349 representation of the JWS Secured Input to an ECDSA signature 1350 verifier that has been configured to use the P-256 curve with the 1351 SHA-256 hash function. 1353 As explained in Section 3.4 of the JSON Web Algorithms (JWA) [JWA] 1354 specification, the use of the K value in ECDSA means that we cannot 1355 validate the correctness of the digital signature in the same way we 1356 validated the correctness of the HMAC. Instead, implementations MUST 1357 use an ECDSA validator to validate the digital signature. 1359 A.4. JWS using ECDSA P-521 SHA-512 1361 A.4.1. Encoding 1363 The JWS Header for this example differs from the previous example 1364 because a different ECDSA curve and hash function are used. The JWS 1365 Header used is: 1367 {"alg":"ES512"} 1369 The following byte array contains the UTF-8 representation of the JWS 1370 Header: 1372 [123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 53, 49, 50, 34, 125] 1374 Base64url encoding these bytes yields this Encoded JWS Header value: 1376 eyJhbGciOiJFUzUxMiJ9 1378 The JWS Payload used in this example, is the ASCII string "Payload". 1379 The representation of this string is the byte array: 1381 [80, 97, 121, 108, 111, 97, 100] 1383 Base64url encoding these bytes yields the Encoded JWS Payload value: 1385 UGF5bG9hZA 1387 Concatenating the Encoded JWS Header, a period ('.') character, and 1388 the Encoded JWS Payload yields this JWS Secured Input value: 1390 eyJhbGciOiJFUzUxMiJ9.UGF5bG9hZA 1392 The ASCII representation of the JWS Secured Input is the following 1393 byte array: 1395 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 70, 85, 122, 85, 1396 120, 77, 105, 74, 57, 46, 85, 71, 70, 53, 98, 71, 57, 104, 90, 65] 1398 The ECDSA key consists of a public part, the EC point (x, y), and a 1399 private part d. The values of the ECDSA key used in this example, 1400 presented as the byte arrays representing three 521 bit big endian 1401 integers are: 1403 +-----------+-------------------------------------------------------+ 1404 | Parameter | Value | 1405 | Name | | 1406 +-----------+-------------------------------------------------------+ 1407 | x | [1, 233, 41, 5, 15, 18, 79, 198, 188, 85, 199, 213, | 1408 | | 57, 51, 101, 223, 157, 239, 74, 176, 194, 44, 178, | 1409 | | 87, 152, 249, 52, 235, 4, 227, 198, 186, 227, 112, | 1410 | | 26, 87, 167, 145, 14, 157, 129, 191, 54, 49, 89, 232, | 1411 | | 235, 203, 21, 93, 99, 73, 244, 189, 182, 204, 248, | 1412 | | 169, 76, 92, 89, 199, 170, 193, 1, 164] | 1413 | y | [0, 52, 166, 68, 14, 55, 103, 80, 210, 55, 31, 209, | 1414 | | 189, 194, 200, 243, 183, 29, 47, 78, 229, 234, 52, | 1415 | | 50, 200, 21, 204, 163, 21, 96, 254, 93, 147, 135, | 1416 | | 236, 119, 75, 85, 131, 134, 48, 229, 203, 191, 90, | 1417 | | 140, 190, 10, 145, 221, 0, 100, 198, 153, 154, 31, | 1418 | | 110, 110, 103, 250, 221, 237, 228, 200, 200, 246] | 1419 | d | [1, 142, 105, 111, 176, 52, 80, 88, 129, 221, 17, 11, | 1420 | | 72, 62, 184, 125, 50, 206, 73, 95, 227, 107, 55, 69, | 1421 | | 237, 242, 216, 202, 228, 240, 242, 83, 159, 70, 21, | 1422 | | 160, 233, 142, 171, 82, 179, 192, 197, 234, 196, 206, | 1423 | | 7, 81, 133, 168, 231, 187, 71, 222, 172, 29, 29, 231, | 1424 | | 123, 204, 246, 97, 53, 230, 61, 130] | 1425 +-----------+-------------------------------------------------------+ 1427 The ECDSA private part d is then passed to an ECDSA signing function, 1428 which also takes the curve type, P-521, the hash type, SHA-512, and 1429 the bytes of the ASCII representation of the JWS Secured Input as 1430 inputs. The result of the digital signature is the EC point (R, S), 1431 where R and S are unsigned integers. In this example, the R and S 1432 values, given as byte arrays representing big endian integers are: 1434 +--------+----------------------------------------------------------+ 1435 | Result | Value | 1436 | Name | | 1437 +--------+----------------------------------------------------------+ 1438 | R | [1, 220, 12, 129, 231, 171, 194, 209, 232, 135, 233, | 1439 | | 117, 247, 105, 122, 210, 26, 125, 192, 1, 217, 21, 82, | 1440 | | 91, 45, 240, 255, 83, 19, 34, 239, 71, 48, 157, 147, | 1441 | | 152, 105, 18, 53, 108, 163, 214, 68, 231, 62, 153, 150, | 1442 | | 106, 194, 164, 246, 72, 143, 138, 24, 50, 129, 223, 133, | 1443 | | 206, 209, 172, 63, 237, 119, 109] | 1444 | S | [0, 111, 6, 105, 44, 5, 41, 208, 128, 61, 152, 40, 92, | 1445 | | 61, 152, 4, 150, 66, 60, 69, 247, 196, 170, 81, 193, | 1446 | | 199, 78, 59, 194, 169, 16, 124, 9, 143, 42, 142, 131, | 1447 | | 48, 206, 238, 34, 175, 83, 203, 220, 159, 3, 107, 155, | 1448 | | 22, 27, 73, 111, 68, 68, 21, 238, 144, 229, 232, 148, | 1449 | | 188, 222, 59, 242, 103] | 1450 +--------+----------------------------------------------------------+ 1452 Concatenating the S array to the end of the R array and base64url 1453 encoding the result produces this value for the Encoded JWS Signature 1454 (with line breaks for display purposes only): 1456 AdwMgeerwtHoh-l192l60hp9wAHZFVJbLfD_UxMi70cwnZOYaRI1bKPWROc-mZZq 1457 wqT2SI-KGDKB34XO0aw_7XdtAG8GaSwFKdCAPZgoXD2YBJZCPEX3xKpRwcdOO8Kp 1458 EHwJjyqOgzDO7iKvU8vcnwNrmxYbSW9ERBXukOXolLzeO_Jn 1460 A.4.2. Decoding 1462 Decoding the JWS requires base64url decoding the Encoded JWS Header, 1463 Encoded JWS Payload, and Encoded JWS Signature to produce the JWS 1464 Header, JWS Payload, and JWS Signature byte arrays. The byte array 1465 containing the UTF-8 representation of the JWS Header is decoded into 1466 the JWS Header string. 1468 A.4.3. Validating 1470 Since the "alg" parameter in the header is "ES512", we validate the 1471 ECDSA P-521 SHA-512 digital signature contained in the JWS Signature. 1472 If any of the validation steps fail, the JWS MUST be rejected. 1474 First, we validate that the JWS Header string is legal JSON. 1476 Validating the JWS Signature is similar to the previous example. 1477 First, we base64url decode the Encoded JWS Signature as in the 1478 previous examples but we then need to split the 132 member byte array 1479 that must result into two 66 byte arrays, the first R and the second 1480 S. We then pass (x, y), (R, S) and the bytes of the ASCII 1481 representation of the JWS Secured Input to an ECDSA signature 1482 verifier that has been configured to use the P-521 curve with the 1483 SHA-512 hash function. 1485 As explained in Section 3.4 of the JSON Web Algorithms (JWA) [JWA] 1486 specification, the use of the K value in ECDSA means that we cannot 1487 validate the correctness of the digital signature in the same way we 1488 validated the correctness of the HMAC. Instead, implementations MUST 1489 use an ECDSA validator to validate the digital signature. 1491 A.5. Example Plaintext JWS 1493 The following example JWS Header declares that the encoded object is 1494 a Plaintext JWS: 1496 {"alg":"none"} 1498 Base64url encoding the bytes of the UTF-8 representation of the JWS 1499 Header yields this Encoded JWS Header: 1501 eyJhbGciOiJub25lIn0 1503 The JWS Payload used in this example, which follows, is the same as 1504 in the previous examples. Since the Encoded JWS Payload will 1505 therefore be the same, its computation is not repeated here. 1507 {"iss":"joe", 1508 "exp":1300819380, 1509 "http://example.com/is_root":true} 1511 The Encoded JWS Signature is the empty string. 1513 Concatenating these parts in the order Header.Payload.Signature with 1514 period ('.') characters between the parts yields this complete JWS 1515 (with line breaks for display purposes only): 1517 eyJhbGciOiJub25lIn0 1518 . 1519 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1520 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1521 . 1523 Appendix B. "x5c" (X.509 Certificate Chain) Example 1525 The JSON array below is an example of a certificate chain that could 1526 be used as the value of an "x5c" (X.509 Certificate Chain) header 1527 parameter, per Section 4.1.6. Note that since these strings contain 1528 base64 encoded (not base64url encoded) values, they are allowed to 1529 contain white space and line breaks. 1531 ["MIIE3jCCA8agAwIBAgICAwEwDQYJKoZIhvcNAQEFBQAwYzELMAkGA1UEBhMCVVM 1532 xITAfBgNVBAoTGFRoZSBHbyBEYWRkeSBHcm91cCwgSW5jLjExMC8GA1UECxMoR2 1533 8gRGFkZHkgQ2xhc3MgMiBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTAeFw0wNjExM 1534 TYwMTU0MzdaFw0yNjExMTYwMTU0MzdaMIHKMQswCQYDVQQGEwJVUzEQMA4GA1UE 1535 CBMHQXJpem9uYTETMBEGA1UEBxMKU2NvdHRzZGFsZTEaMBgGA1UEChMRR29EYWR 1536 keS5jb20sIEluYy4xMzAxBgNVBAsTKmh0dHA6Ly9jZXJ0aWZpY2F0ZXMuZ29kYW 1537 RkeS5jb20vcmVwb3NpdG9yeTEwMC4GA1UEAxMnR28gRGFkZHkgU2VjdXJlIENlc 1538 nRpZmljYXRpb24gQXV0aG9yaXR5MREwDwYDVQQFEwgwNzk2OTI4NzCCASIwDQYJ 1539 KoZIhvcNAQEBBQADggEPADCCAQoCggEBAMQt1RWMnCZM7DI161+4WQFapmGBWTt 1540 wY6vj3D3HKrjJM9N55DrtPDAjhI6zMBS2sofDPZVUBJ7fmd0LJR4h3mUpfjWoqV 1541 Tr9vcyOdQmVZWt7/v+WIbXnvQAjYwqDL1CBM6nPwT27oDyqu9SoWlm2r4arV3aL 1542 GbqGmu75RpRSgAvSMeYddi5Kcju+GZtCpyz8/x4fKL4o/K1w/O5epHBp+YlLpyo 1543 7RJlbmr2EkRTcDCVw5wrWCs9CHRK8r5RsL+H0EwnWGu1NcWdrxcx+AuP7q2BNgW 1544 JCJjPOq8lh8BJ6qf9Z/dFjpfMFDniNoW1fho3/Rb2cRGadDAW/hOUoz+EDU8CAw 1545 EAAaOCATIwggEuMB0GA1UdDgQWBBT9rGEyk2xF1uLuhV+auud2mWjM5zAfBgNVH 1546 SMEGDAWgBTSxLDSkdRMEXGzYcs9of7dqGrU4zASBgNVHRMBAf8ECDAGAQH/AgEA 1547 MDMGCCsGAQUFBwEBBCcwJTAjBggrBgEFBQcwAYYXaHR0cDovL29jc3AuZ29kYWR 1548 keS5jb20wRgYDVR0fBD8wPTA7oDmgN4Y1aHR0cDovL2NlcnRpZmljYXRlcy5nb2 1549 RhZGR5LmNvbS9yZXBvc2l0b3J5L2dkcm9vdC5jcmwwSwYDVR0gBEQwQjBABgRVH 1550 SAAMDgwNgYIKwYBBQUHAgEWKmh0dHA6Ly9jZXJ0aWZpY2F0ZXMuZ29kYWRkeS5j 1551 b20vcmVwb3NpdG9yeTAOBgNVHQ8BAf8EBAMCAQYwDQYJKoZIhvcNAQEFBQADggE 1552 BANKGwOy9+aG2Z+5mC6IGOgRQjhVyrEp0lVPLN8tESe8HkGsz2ZbwlFalEzAFPI 1553 UyIXvJxwqoJKSQ3kbTJSMUA2fCENZvD117esyfxVgqwcSeIaha86ykRvOe5GPLL 1554 5CkKSkB2XIsKd83ASe8T+5o0yGPwLPk9Qnt0hCqU7S+8MxZC9Y7lhyVJEnfzuz9 1555 p0iRFEUOOjZv2kWzRaJBydTXRE4+uXR21aITVSzGh6O1mawGhId/dQb8vxRMDsx 1556 uxN89txJx9OjxUUAiKEngHUuHqDTMBqLdElrRhjZkAzVvb3du6/KFUJheqwNTrZ 1557 EjYx8WnM25sgVjOuH0aBsXBTWVU+4=", 1558 "MIIE+zCCBGSgAwIBAgICAQ0wDQYJKoZIhvcNAQEFBQAwgbsxJDAiBgNVBAcTG1Z 1559 hbGlDZXJ0IFZhbGlkYXRpb24gTmV0d29yazEXMBUGA1UEChMOVmFsaUNlcnQsIE 1560 luYy4xNTAzBgNVBAsTLFZhbGlDZXJ0IENsYXNzIDIgUG9saWN5IFZhbGlkYXRpb 1561 24gQXV0aG9yaXR5MSEwHwYDVQQDExhodHRwOi8vd3d3LnZhbGljZXJ0LmNvbS8x 1562 IDAeBgkqhkiG9w0BCQEWEWluZm9AdmFsaWNlcnQuY29tMB4XDTA0MDYyOTE3MDY 1563 yMFoXDTI0MDYyOTE3MDYyMFowYzELMAkGA1UEBhMCVVMxITAfBgNVBAoTGFRoZS 1564 BHbyBEYWRkeSBHcm91cCwgSW5jLjExMC8GA1UECxMoR28gRGFkZHkgQ2xhc3MgM 1565 iBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTCCASAwDQYJKoZIhvcNAQEBBQADggEN 1566 ADCCAQgCggEBAN6d1+pXGEmhW+vXX0iG6r7d/+TvZxz0ZWizV3GgXne77ZtJ6XC 1567 APVYYYwhv2vLM0D9/AlQiVBDYsoHUwHU9S3/Hd8M+eKsaA7Ugay9qK7HFiH7Eux 1568 6wwdhFJ2+qN1j3hybX2C32qRe3H3I2TqYXP2WYktsqbl2i/ojgC95/5Y0V4evLO 1569 tXiEqITLdiOr18SPaAIBQi2XKVlOARFmR6jYGB0xUGlcmIbYsUfb18aQr4CUWWo 1570 riMYavx4A6lNf4DD+qta/KFApMoZFv6yyO9ecw3ud72a9nmYvLEHZ6IVDd2gWMZ 1571 Eewo+YihfukEHU1jPEX44dMX4/7VpkI+EdOqXG68CAQOjggHhMIIB3TAdBgNVHQ 1572 4EFgQU0sSw0pHUTBFxs2HLPaH+3ahq1OMwgdIGA1UdIwSByjCBx6GBwaSBvjCBu 1573 zEkMCIGA1UEBxMbVmFsaUNlcnQgVmFsaWRhdGlvbiBOZXR3b3JrMRcwFQYDVQQK 1574 Ew5WYWxpQ2VydCwgSW5jLjE1MDMGA1UECxMsVmFsaUNlcnQgQ2xhc3MgMiBQb2x 1575 pY3kgVmFsaWRhdGlvbiBBdXRob3JpdHkxITAfBgNVBAMTGGh0dHA6Ly93d3cudm 1576 FsaWNlcnQuY29tLzEgMB4GCSqGSIb3DQEJARYRaW5mb0B2YWxpY2VydC5jb22CA 1577 QEwDwYDVR0TAQH/BAUwAwEB/zAzBggrBgEFBQcBAQQnMCUwIwYIKwYBBQUHMAGG 1578 F2h0dHA6Ly9vY3NwLmdvZGFkZHkuY29tMEQGA1UdHwQ9MDswOaA3oDWGM2h0dHA 1579 6Ly9jZXJ0aWZpY2F0ZXMuZ29kYWRkeS5jb20vcmVwb3NpdG9yeS9yb290LmNybD 1580 BLBgNVHSAERDBCMEAGBFUdIAAwODA2BggrBgEFBQcCARYqaHR0cDovL2NlcnRpZ 1581 mljYXRlcy5nb2RhZGR5LmNvbS9yZXBvc2l0b3J5MA4GA1UdDwEB/wQEAwIBBjAN 1582 BgkqhkiG9w0BAQUFAAOBgQC1QPmnHfbq/qQaQlpE9xXUhUaJwL6e4+PrxeNYiY+ 1583 Sn1eocSxI0YGyeR+sBjUZsE4OWBsUs5iB0QQeyAfJg594RAoYC5jcdnplDQ1tgM 1584 QLARzLrUc+cb53S8wGd9D0VmsfSxOaFIqII6hR8INMqzW/Rn453HWkrugp++85j 1585 09VZw==", 1586 "MIIC5zCCAlACAQEwDQYJKoZIhvcNAQEFBQAwgbsxJDAiBgNVBAcTG1ZhbGlDZXJ 1587 0IFZhbGlkYXRpb24gTmV0d29yazEXMBUGA1UEChMOVmFsaUNlcnQsIEluYy4xNT 1588 AzBgNVBAsTLFZhbGlDZXJ0IENsYXNzIDIgUG9saWN5IFZhbGlkYXRpb24gQXV0a 1589 G9yaXR5MSEwHwYDVQQDExhodHRwOi8vd3d3LnZhbGljZXJ0LmNvbS8xIDAeBgkq 1590 hkiG9w0BCQEWEWluZm9AdmFsaWNlcnQuY29tMB4XDTk5MDYyNjAwMTk1NFoXDTE 1591 5MDYyNjAwMTk1NFowgbsxJDAiBgNVBAcTG1ZhbGlDZXJ0IFZhbGlkYXRpb24gTm 1592 V0d29yazEXMBUGA1UEChMOVmFsaUNlcnQsIEluYy4xNTAzBgNVBAsTLFZhbGlDZ 1593 XJ0IENsYXNzIDIgUG9saWN5IFZhbGlkYXRpb24gQXV0aG9yaXR5MSEwHwYDVQQD 1594 ExhodHRwOi8vd3d3LnZhbGljZXJ0LmNvbS8xIDAeBgkqhkiG9w0BCQEWEWluZm9 1595 AdmFsaWNlcnQuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDOOnHK5a 1596 vIWZJV16vYdA757tn2VUdZZUcOBVXc65g2PFxTXdMwzzjsvUGJ7SVCCSRrCl6zf 1597 N1SLUzm1NZ9WlmpZdRJEy0kTRxQb7XBhVQ7/nHk01xC+YDgkRoKWzk2Z/M/VXwb 1598 P7RfZHM047QSv4dk+NoS/zcnwbNDu+97bi5p9wIDAQABMA0GCSqGSIb3DQEBBQU 1599 AA4GBADt/UG9vUJSZSWI4OB9L+KXIPqeCgfYrx+jFzug6EILLGACOTb2oWH+heQ 1600 C1u+mNr0HZDzTuIYEZoDJJKPTEjlbVUjP9UNV+mWwD5MlM/Mtsq2azSiGM5bUMM 1601 j4QssxsodyamEwCW/POuZ6lcg5Ktz885hZo+L7tdEy8W9ViH0Pd"] 1603 Appendix C. Notes on implementing base64url encoding without padding 1605 This appendix describes how to implement base64url encoding and 1606 decoding functions without padding based upon standard base64 1607 encoding and decoding functions that do use padding. 1609 To be concrete, example C# code implementing these functions is shown 1610 below. Similar code could be used in other languages. 1612 static string base64urlencode(byte [] arg) 1613 { 1614 string s = Convert.ToBase64String(arg); // Regular base64 encoder 1615 s = s.Split('=')[0]; // Remove any trailing '='s 1616 s = s.Replace('+', '-'); // 62nd char of encoding 1617 s = s.Replace('/', '_'); // 63rd char of encoding 1618 return s; 1619 } 1621 static byte [] base64urldecode(string arg) 1622 { 1623 string s = arg; 1624 s = s.Replace('-', '+'); // 62nd char of encoding 1625 s = s.Replace('_', '/'); // 63rd char of encoding 1626 switch (s.Length % 4) // Pad with trailing '='s 1627 { 1628 case 0: break; // No pad chars in this case 1629 case 2: s += "=="; break; // Two pad chars 1630 case 3: s += "="; break; // One pad char 1631 default: throw new System.Exception( 1632 "Illegal base64url string!"); 1633 } 1634 return Convert.FromBase64String(s); // Standard base64 decoder 1635 } 1637 As per the example code above, the number of '=' padding characters 1638 that needs to be added to the end of a base64url encoded string 1639 without padding to turn it into one with padding is a deterministic 1640 function of the length of the encoded string. Specifically, if the 1641 length mod 4 is 0, no padding is added; if the length mod 4 is 2, two 1642 '=' padding characters are added; if the length mod 4 is 3, one '=' 1643 padding character is added; if the length mod 4 is 1, the input is 1644 malformed. 1646 An example correspondence between unencoded and encoded values 1647 follows. The byte sequence below encodes into the string below, 1648 which when decoded, reproduces the byte sequence. 1649 3 236 255 224 193 1650 A-z_4ME 1652 Appendix D. Acknowledgements 1654 Solutions for signing JSON content were previously explored by Magic 1655 Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas 1656 Applications [CanvasApp], all of which influenced this draft. 1658 Thanks to Axel Nennker for his early implementation and feedback on 1659 the JWS and JWE specifications. 1661 This specification is the work of the JOSE Working Group, which 1662 includes dozens of active and dedicated participants. In particular, 1663 the following individuals contributed ideas, feedback, and wording 1664 that influenced this specification: 1666 Dirk Balfanz, Richard Barnes, Brian Campbell, Breno de Medeiros, Dick 1667 Hardt, Joe Hildebrand, Jeff Hodges, Edmund Jay, Yaron Y. Goland, Ben 1668 Laurie, James Manger, Tony Nadalin, Axel Nennker, John Panzer, 1669 Emmanuel Raviart, Eric Rescorla, Jim Schaad, Paul Tarjan, Hannes 1670 Tschofenig, and Sean Turner. 1672 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 1673 Sean Turner and Stephen Farrell served as Security area directors 1674 during the creation of this specification. 1676 Appendix E. Open Issues 1678 [[ to be removed by the RFC editor before publication as an RFC ]] 1680 The following items remain to be considered or done in this draft: 1682 o Should all header fields continue to be required to be understood 1683 by implementations using them or should a means of declaring that 1684 specific header fields may be safely ignored if not understood 1685 should be defined? 1687 Appendix F. Document History 1689 [[ to be removed by the RFC editor before publication as an RFC ]] 1691 -08 1693 o Applied editorial improvements suggested by Jeff Hodges and Hannes 1694 Tschofenig. Many of these simplified the terminology used. 1696 o Clarified statements of the form "This header parameter is 1697 OPTIONAL" to "Use of this header parameter is OPTIONAL". 1699 o Added a Header Parameter Usage Location(s) field to the IANA JSON 1700 Web Signature and Encryption Header Parameters registry. 1702 o Added seriesInfo information to Internet Draft references. 1704 -07 1705 o Updated references. 1707 -06 1709 o Changed "x5c" (X.509 Certificate Chain) representation from being 1710 a single string to being an array of strings, each containing a 1711 single base64 encoded DER certificate value, representing elements 1712 of the certificate chain. 1714 o Applied changes made by the RFC Editor to RFC 6749's registry 1715 language to this specification. 1717 -05 1719 o Added statement that "StringOrURI values are compared as case- 1720 sensitive strings with no transformations or canonicalizations 1721 applied". 1723 o Indented artwork elements to better distinguish them from the body 1724 text. 1726 -04 1728 o Completed JSON Security Considerations section, including 1729 considerations about rejecting input with duplicate member names. 1731 o Completed security considerations on the use of a SHA-1 hash when 1732 computing "x5t" (x.509 certificate thumbprint) values. 1734 o Refer to the registries as the primary sources of defined values 1735 and then secondarily reference the sections defining the initial 1736 contents of the registries. 1738 o Normatively reference XML DSIG 2.0 [W3C.CR-xmldsig-core2-20120124] 1739 for its security considerations. 1741 o Added this language to Registration Templates: "This name is case 1742 sensitive. Names that match other registered names in a case 1743 insensitive manner SHOULD NOT be accepted." 1745 o Reference draft-jones-jose-jws-json-serialization instead of 1746 draft-jones-json-web-signature-json-serialization. 1748 o Described additional open issues. 1750 o Applied editorial suggestions. 1752 -03 1753 o Added the "cty" (content type) header parameter for declaring type 1754 information about the secured content, as opposed to the "typ" 1755 (type) header parameter, which declares type information about 1756 this object. 1758 o Added "Collision Resistant Namespace" to the terminology section. 1760 o Reference ITU.X690.1994 for DER encoding. 1762 o Added an example JWS using ECDSA P-521 SHA-512. This has 1763 particular illustrative value because of the use of the 521 bit 1764 integers in the key and signature values. This is also an example 1765 in which the payload is not a base64url encoded JSON object. 1767 o Added an example "x5c" value. 1769 o No longer say "the UTF-8 representation of the JWS Secured Input 1770 (which is the same as the ASCII representation)". Just call it 1771 "the ASCII representation of the JWS Secured Input". 1773 o Added Registration Template sections for defined registries. 1775 o Added Registry Contents sections to populate registry values. 1777 o Changed name of the JSON Web Signature and Encryption "typ" Values 1778 registry to be the JSON Web Signature and Encryption Type Values 1779 registry, since it is used for more than just values of the "typ" 1780 parameter. 1782 o Moved registries JSON Web Signature and Encryption Header 1783 Parameters and JSON Web Signature and Encryption Type Values to 1784 the JWS specification. 1786 o Numerous editorial improvements. 1788 -02 1790 o Clarified that it is an error when a "kid" value is included and 1791 no matching key is found. 1793 o Removed assumption that "kid" (key ID) can only refer to an 1794 asymmetric key. 1796 o Clarified that JWSs with duplicate Header Parameter Names MUST be 1797 rejected. 1799 o Clarified the relationship between "typ" header parameter values 1800 and MIME types. 1802 o Registered application/jws MIME type and "JWS" typ header 1803 parameter value. 1805 o Simplified JWK terminology to get replace the "JWK Key Object" and 1806 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 1807 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 1808 between single keys and sets of keys. As part of this change, the 1809 Header Parameter Name for a public key value was changed from 1810 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 1812 o Added suggestion on defining additional header parameters such as 1813 "x5t#S256" in the future for certificate thumbprints using hash 1814 algorithms other than SHA-1. 1816 o Specify RFC 2818 server identity validation, rather than RFC 6125 1817 (paralleling the same decision in the OAuth specs). 1819 o Generalized language to refer to Message Authentication Codes 1820 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 1821 unless in a context specific to HMAC algorithms. 1823 o Reformatted to give each header parameter its own section heading. 1825 -01 1827 o Moved definition of Plaintext JWSs (using "alg":"none") here from 1828 the JWT specification since this functionality is likely to be 1829 useful in more contexts that just for JWTs. 1831 o Added "jpk" and "x5c" header parameters for including JWK public 1832 keys and X.509 certificate chains directly in the header. 1834 o Clarified that this specification is defining the JWS Compact 1835 Serialization. Referenced the new JWS-JS spec, which defines the 1836 JWS JSON Serialization. 1838 o Added text "New header parameters should be introduced sparingly 1839 since an implementation that does not understand a parameter MUST 1840 reject the JWS". 1842 o Clarified that the order of the creation and validation steps is 1843 not significant in cases where there are no dependencies between 1844 the inputs and outputs of the steps. 1846 o Changed "no canonicalization is performed" to "no canonicalization 1847 need be performed". 1849 o Corrected the Magic Signatures reference. 1851 o Made other editorial improvements suggested by JOSE working group 1852 participants. 1854 -00 1856 o Created the initial IETF draft based upon 1857 draft-jones-json-web-signature-04 with no normative changes. 1859 o Changed terminology to no longer call both digital signatures and 1860 HMACs "signatures". 1862 Authors' Addresses 1864 Michael B. Jones 1865 Microsoft 1867 Email: mbj@microsoft.com 1868 URI: http://self-issued.info/ 1870 John Bradley 1871 Ping Identity 1873 Email: ve7jtb@ve7jtb.com 1875 Nat Sakimura 1876 Nomura Research Institute 1878 Email: n-sakimura@nri.co.jp