idnits 2.17.1 draft-ietf-jose-json-web-signature-16.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 == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The "crit" (critical) header parameter indicates that extensions to [[ this specification ]] are being used that MUST be understood and processed. Its value is an array listing the header parameter names defined by those extensions that are used in the JWS Header. If any of the listed extension header parameters are not understood and supported by the receiver, it MUST reject the JWS. Senders MUST NOT include header parameter names defined by [[ this specification ]] or by [JWA] for use with JWS, duplicate names, or names that do not occur as header parameter names within the JWS Header in the "crit" list. Senders MUST not use the empty list "[]" as the "crit" value. Recipients MAY reject the JWS if the critical list contains any header parameter names defined by [[ this specification ]] or by [JWA] for use with JWS, or any other constraints on its use are violated. This header parameter MUST be integrity protected, and therefore MUST occur only with the JWS Protected Header, when used. Use of this header parameter is OPTIONAL. This header parameter MUST be understood and processed by implementations. -- The document date (September 15, 2013) is 3877 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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 1715 -- Looks like a reference, but probably isn't: '34' on line 1715 -- Looks like a reference, but probably isn't: '97' on line 1724 -- Looks like a reference, but probably isn't: '108' on line 1724 -- Looks like a reference, but probably isn't: '103' on line 1715 -- Looks like a reference, but probably isn't: '58' on line 1715 -- Looks like a reference, but probably isn't: '82' on line 1452 -- Looks like a reference, but probably isn't: '83' on line 1715 -- Looks like a reference, but probably isn't: '50' on line 1715 -- Looks like a reference, but probably isn't: '53' on line 1715 -- Looks like a reference, but probably isn't: '54' on line 1594 -- Looks like a reference, but probably isn't: '125' on line 1715 -- Looks like a reference, but probably isn't: '69' on line 1715 -- Looks like a reference, but probably isn't: '49' on line 1715 -- Looks like a reference, but probably isn't: '80' on line 1724 -- Looks like a reference, but probably isn't: '121' on line 1724 -- Looks like a reference, but probably isn't: '111' on line 1724 -- Looks like a reference, but probably isn't: '100' on line 1724 -- Looks like a reference, but probably isn't: '0' on line 2042 -- Possible downref: Non-RFC (?) normative reference: ref. 'ECMAScript' -- Possible downref: Non-RFC (?) normative reference: ref. 'ITU.X690.1994' ** Downref: Normative reference to an Historic RFC: RFC 1421 ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) -- Possible downref: Non-RFC (?) normative reference: ref. 'USA15' -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' Summary: 7 errors (**), 0 flaws (~~), 2 warnings (==), 25 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: March 19, 2014 Ping Identity 6 N. Sakimura 7 NRI 8 September 15, 2013 10 JSON Web Signature (JWS) 11 draft-ietf-jose-json-web-signature-16 13 Abstract 15 JSON Web Signature (JWS) represents content secured with digital 16 signatures or Message Authentication Codes (MACs) using JavaScript 17 Object Notation (JSON) based data structures. Cryptographic 18 algorithms and identifiers for use with this specification are 19 described in the separate JSON Web Algorithms (JWA) specification and 20 an IANA registry defined by that specification. Related encryption 21 capabilities are described in the separate JSON Web Encryption (JWE) 22 specification. 24 Status of this Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on March 19, 2014. 41 Copyright Notice 43 Copyright (c) 2013 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 60 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 3. JSON Web Signature (JWS) Overview . . . . . . . . . . . . . . 6 62 3.1. Example JWS . . . . . . . . . . . . . . . . . . . . . . . 6 63 4. JWS Header . . . . . . . . . . . . . . . . . . . . . . . . . . 8 64 4.1. Registered Header Parameter Names . . . . . . . . . . . . 8 65 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 8 66 4.1.2. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 9 67 4.1.3. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 9 68 4.1.4. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 9 69 4.1.5. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header 70 Parameter . . . . . . . . . . . . . . . . . . . . . . 9 71 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter . . . 10 72 4.1.7. "kid" (Key ID) Header Parameter . . . . . . . . . . . 10 73 4.1.8. "typ" (Type) Header Parameter . . . . . . . . . . . . 10 74 4.1.9. "cty" (Content Type) Header Parameter . . . . . . . . 11 75 4.1.10. "crit" (Critical) Header Parameter . . . . . . . . . . 11 76 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 12 77 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 12 78 5. Producing and Consuming JWSs . . . . . . . . . . . . . . . . . 12 79 5.1. Message Signing or MACing . . . . . . . . . . . . . . . . 12 80 5.2. Message Signature or MAC Validation . . . . . . . . . . . 13 81 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 15 82 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 15 83 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 16 84 7.1. JWS Compact Serialization . . . . . . . . . . . . . . . . 16 85 7.2. JWS JSON Serialization . . . . . . . . . . . . . . . . . . 16 86 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 87 8.1. JSON Web Signature and Encryption Header Parameters 88 Registry . . . . . . . . . . . . . . . . . . . . . . . . . 19 89 8.1.1. Registration Template . . . . . . . . . . . . . . . . 19 90 8.1.2. Initial Registry Contents . . . . . . . . . . . . . . 20 91 8.2. JSON Web Signature and Encryption Type Values Registry . . 21 92 8.2.1. Registration Template . . . . . . . . . . . . . . . . 21 93 8.2.2. Initial Registry Contents . . . . . . . . . . . . . . 22 94 8.3. Media Type Registration . . . . . . . . . . . . . . . . . 22 95 8.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 22 97 9. Security Considerations . . . . . . . . . . . . . . . . . . . 23 98 9.1. Cryptographic Security Considerations . . . . . . . . . . 23 99 9.2. JSON Security Considerations . . . . . . . . . . . . . . . 25 100 9.3. Unicode Comparison Security Considerations . . . . . . . . 25 101 9.4. TLS Requirements . . . . . . . . . . . . . . . . . . . . . 26 102 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26 103 10.1. Normative References . . . . . . . . . . . . . . . . . . . 26 104 10.2. Informative References . . . . . . . . . . . . . . . . . . 28 105 Appendix A. JWS Examples . . . . . . . . . . . . . . . . . . . . 28 106 A.1. Example JWS using HMAC SHA-256 . . . . . . . . . . . . . . 29 107 A.1.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 29 108 A.1.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 31 109 A.1.3. Validating . . . . . . . . . . . . . . . . . . . . . . 31 110 A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 . . . . . . . . 31 111 A.2.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 31 112 A.2.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 34 113 A.2.3. Validating . . . . . . . . . . . . . . . . . . . . . . 34 114 A.3. Example JWS using ECDSA P-256 SHA-256 . . . . . . . . . . 34 115 A.3.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 34 116 A.3.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 36 117 A.3.3. Validating . . . . . . . . . . . . . . . . . . . . . . 36 118 A.4. Example JWS using ECDSA P-521 SHA-512 . . . . . . . . . . 37 119 A.4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . 37 120 A.4.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . 39 121 A.4.3. Validating . . . . . . . . . . . . . . . . . . . . . . 39 122 A.5. Example Plaintext JWS . . . . . . . . . . . . . . . . . . 39 123 A.6. Example JWS Using JWS JSON Serialization . . . . . . . . . 40 124 A.6.1. JWS Per-Signature Protected Headers . . . . . . . . . 40 125 A.6.2. JWS Per-Signature Unprotected Headers . . . . . . . . 41 126 A.6.3. Complete JWS Header Values . . . . . . . . . . . . . . 41 127 A.6.4. Complete JWS JSON Serialization Representation . . . . 41 128 Appendix B. "x5c" (X.509 Certificate Chain) Example . . . . . . . 42 129 Appendix C. Notes on implementing base64url encoding without 130 padding . . . . . . . . . . . . . . . . . . . . . . . 44 131 Appendix D. Negative Test Case for "crit" Header Parameter . . . 45 132 Appendix E. Acknowledgements . . . . . . . . . . . . . . . . . . 45 133 Appendix F. Document History . . . . . . . . . . . . . . . . . . 46 134 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 52 136 1. Introduction 138 JSON Web Signature (JWS) represents content secured with digital 139 signatures or Message Authentication Codes (MACs) using JavaScript 140 Object Notation (JSON) [RFC4627] based data structures. The JWS 141 cryptographic mechanisms provide integrity protection for an 142 arbitrary sequence of octets. 144 Two closely related serializations for JWS objects are defined. The 145 JWS Compact Serialization is a compact, URL-safe representation 146 intended for space constrained environments such as HTTP 147 Authorization headers and URI query parameters. The JWS JSON 148 Serialization represents JWS objects as JSON objects and enables 149 multiple signatures and/or MACs to be applied to the same content. 150 Both share the same cryptographic underpinnings. 152 Cryptographic algorithms and identifiers for use with this 153 specification are described in the separate JSON Web Algorithms (JWA) 154 [JWA] specification and an IANA registry defined by that 155 specification. Related encryption capabilities are described in the 156 separate JSON Web Encryption (JWE) [JWE] specification. 158 Names defined by this specification are short because a core goal is 159 for the resulting representations to be compact. 161 1.1. Notational Conventions 163 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 164 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 165 document are to be interpreted as described in Key words for use in 166 RFCs to Indicate Requirement Levels [RFC2119]. If these words are 167 used without being spelled in uppercase then they are to be 168 interpreted with their normal natural language meanings. 170 2. Terminology 172 JSON Web Signature (JWS) A data structure representing a digitally 173 signed or MACed message. The structure represents three values: 174 the JWS Header, the JWS Payload, and the JWS Signature. 176 JSON Text Object A UTF-8 [RFC3629] encoded text string representing 177 a JSON object; the syntax of JSON objects is defined in Section 178 2.2 of [RFC4627]. 180 JWS Header A JSON Text Object (or JSON Text Objects, when using the 181 JWS JSON Serialization) that describes the digital signature or 182 MAC operation applied to create the JWS Signature value. The 183 members of the JWS Header object(s) are Header Parameters. 185 JWS Payload The sequence of octets to be secured -- a.k.a., the 186 message. The payload can contain an arbitrary sequence of octets. 188 JWS Signature A sequence of octets containing the cryptographic 189 material that ensures the integrity of the JWS Protected Header 190 and the JWS Payload. The JWS Signature value is a digital 191 signature or MAC value calculated over the JWS Signing Input using 192 the parameters specified in the JWS Header. 194 JWS Protected Header A JSON Text Object that contains the portion of 195 the JWS Header that is integrity protected. For the JWS Compact 196 Serialization, this comprises the entire JWS Header. For the JWS 197 JSON Serialization, this is one component of the JWS Header. 199 Header Parameter A name/value pair that is member of the JWS Header. 201 Header Parameter Name The name of a member of the JWS Header. 203 Header Parameter Value The value of a member of the JWS Header. 205 Base64url Encoding Base64 encoding using the URL- and filename-safe 206 character set defined in Section 5 of RFC 4648 [RFC4648], with all 207 trailing '=' characters omitted (as permitted by Section 3.2). 208 (See Appendix C for notes on implementing base64url encoding 209 without padding.) 211 Encoded JWS Header Base64url encoding of the JWS Protected Header. 213 Encoded JWS Payload Base64url encoding of the JWS Payload. 215 Encoded JWS Signature Base64url encoding of the JWS Signature. 217 JWS Signing Input The concatenation of the Encoded JWS Header, a 218 period ('.') character, and the Encoded JWS Payload. 220 JWS Compact Serialization A representation of the JWS as the 221 concatenation of the Encoded JWS Header, the Encoded JWS Payload, 222 and the Encoded JWS Signature in that order, with the three 223 strings being separated by two period ('.') characters. This 224 representation is compact and URL-safe. 226 JWS JSON Serialization A representation of the JWS as a JSON 227 structure containing JWS Header, Encoded JWS Payload, and Encoded 228 JWS Signature values. Unlike the JWS Compact Serialization, the 229 JWS JSON Serialization enables multiple digital signatures and/or 230 MACs to be applied to the same content. This representation is 231 neither compact nor URL-safe. 233 Collision Resistant Name A name in a namespace that enables names to 234 be allocated in a manner such that they are highly unlikely to 235 collide with other names. Examples of collision resistant 236 namespaces include: Domain Names, Object Identifiers (OIDs) as 237 defined in the ITU-T X.660 and X.670 Recommendation series, and 238 Universally Unique IDentifiers (UUIDs) [RFC4122]. When using an 239 administratively delegated namespace, the definer of a name needs 240 to take reasonable precautions to ensure they are in control of 241 the portion of the namespace they use to define the name. 243 StringOrURI A JSON string value, with the additional requirement 244 that while arbitrary string values MAY be used, any value 245 containing a ":" character MUST be a URI [RFC3986]. StringOrURI 246 values are compared as case-sensitive strings with no 247 transformations or canonicalizations applied. 249 3. JSON Web Signature (JWS) Overview 251 JWS represents digitally signed or MACed content using JSON data 252 structures and base64url encoding. Three values are represented in a 253 JWS: the JWS Header, the JWS Payload, and the JWS Signature. In the 254 Compact Serialization, the three values are base64url-encoded for 255 transmission, and represented as the concatenation of the encoded 256 strings in that order, with the three strings being separated by two 257 period ('.') characters. A JSON Serialization for this information 258 is also defined in Section 7.2. 260 The JWS Header describes the signature or MAC method and parameters 261 employed. The JWS Payload is the message content to be secured. The 262 JWS Signature ensures the integrity of both the JWS Protected Header 263 and the JWS Payload. 265 3.1. Example JWS 267 This section provides an example of a JWS. Its computation is 268 described in more detail in Appendix A.1, including specifying the 269 exact octet sequences representing the JSON values used and the key 270 value used. 272 The following example JWS Header declares that the encoded object is 273 a JSON Web Token (JWT) [JWT] and the JWS Header and the JWS Payload 274 are secured using the HMAC SHA-256 algorithm: 276 {"typ":"JWT", 277 "alg":"HS256"} 279 Base64url encoding the octets of the UTF-8 representation of the JWS 280 Header yields this Encoded JWS Header value: 282 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 284 The UTF-8 representation of following JSON object is used as the JWS 285 Payload. (Note that the payload can be any content, and need not be 286 a representation of a JSON object.) 288 {"iss":"joe", 289 "exp":1300819380, 290 "http://example.com/is_root":true} 292 Base64url encoding the JWS Payload yields this Encoded JWS Payload 293 (with line breaks for display purposes only): 295 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 296 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 298 Computing the HMAC of the octets of the ASCII [USASCII] 299 representation of the JWS Signing Input (the concatenation of the 300 Encoded JWS Header, a period ('.') character, and the Encoded JWS 301 Payload) with the HMAC SHA-256 algorithm using the key specified in 302 Appendix A.1 and base64url encoding the result yields this Encoded 303 JWS Signature value: 305 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 307 Concatenating these values in the order Header.Payload.Signature with 308 period ('.') characters between the parts yields this complete JWS 309 representation using the JWS Compact Serialization (with line breaks 310 for display purposes only): 312 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 313 . 314 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 315 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 316 . 317 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 319 See Appendix A for additional examples. 321 4. JWS Header 323 The members of the JSON object(s) representing the JWS Header 324 describe the digital signature or MAC applied to the Encoded JWS 325 Header and the Encoded JWS Payload and optionally additional 326 properties of the JWS. The Header Parameter Names within the JWS 327 Header MUST be unique; recipients MUST either reject JWSs with 328 duplicate Header Parameter Names or use a JSON parser that returns 329 only the lexically last duplicate member name, as specified in 330 Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript]. 332 Implementations are required to understand the specific header 333 parameters defined by this specification that are designated as "MUST 334 be understood" and process them in the manner defined in this 335 specification. All other header parameters defined by this 336 specification that are not so designated MUST be ignored when not 337 understood. Unless listed as a critical header parameter, per 338 Section 4.1.10, all header parameters not defined by this 339 specification MUST be ignored when not understood. 341 There are three classes of Header Parameter Names: Registered Header 342 Parameter Names, Public Header Parameter Names, and Private Header 343 Parameter Names. 345 4.1. Registered Header Parameter Names 347 The following Header Parameter Names are registered in the IANA JSON 348 Web Signature and Encryption Header Parameters registry defined in 349 Section 8.1, with meanings as defined below. 351 As indicated by the common registry, JWSs and JWEs share a common 352 header parameter space; when a parameter is used by both 353 specifications, its usage must be compatible between the 354 specifications. 356 4.1.1. "alg" (Algorithm) Header Parameter 358 The "alg" (algorithm) header parameter identifies the cryptographic 359 algorithm used to secure the JWS. The signature, MAC, or plaintext 360 value is not valid if the "alg" value does not represent a supported 361 algorithm, or if there is not a key for use with that algorithm 362 associated with the party that digitally signed or MACed the content. 363 "alg" values SHOULD either be registered in the IANA JSON Web 364 Signature and Encryption Algorithms registry defined in [JWA] or be a 365 value that contains a Collision Resistant Name. The "alg" value is a 366 case sensitive string containing a StringOrURI value. Use of this 367 header parameter is REQUIRED. This header parameter MUST be 368 understood and processed by implementations. 370 A list of defined "alg" values can be found in the IANA JSON Web 371 Signature and Encryption Algorithms registry defined in [JWA]; the 372 initial contents of this registry are the values defined in Section 373 3.1 of the JSON Web Algorithms (JWA) [JWA] specification. 375 4.1.2. "jku" (JWK Set URL) Header Parameter 377 The "jku" (JWK Set URL) header parameter is a URI [RFC3986] that 378 refers to a resource for a set of JSON-encoded public keys, one of 379 which corresponds to the key used to digitally sign the JWS. The 380 keys MUST be encoded as a JSON Web Key Set (JWK Set) [JWK]. The 381 protocol used to acquire the resource MUST provide integrity 382 protection; an HTTP GET request to retrieve the JWK Set MUST use TLS 383 [RFC2818] [RFC5246]; the identity of the server MUST be validated, as 384 per Section 3.1 of HTTP Over TLS [RFC2818]. Use of this header 385 parameter is OPTIONAL. 387 4.1.3. "jwk" (JSON Web Key) Header Parameter 389 The "jwk" (JSON Web Key) header parameter is the public key that 390 corresponds to the key used to digitally sign the JWS. This key is 391 represented as a JSON Web Key [JWK]. Use of this header parameter is 392 OPTIONAL. 394 4.1.4. "x5u" (X.509 URL) Header Parameter 396 The "x5u" (X.509 URL) header parameter is a URI [RFC3986] that refers 397 to a resource for the X.509 public key certificate or certificate 398 chain [RFC5280] corresponding to the key used to digitally sign the 399 JWS. The identified resource MUST provide a representation of the 400 certificate or certificate chain that conforms to RFC 5280 [RFC5280] 401 in PEM encoded form [RFC1421]. The certificate containing the public 402 key corresponding to the key used to digitally sign the JWS MUST be 403 the first certificate. This MAY be followed by additional 404 certificates, with each subsequent certificate being the one used to 405 certify the previous one. The protocol used to acquire the resource 406 MUST provide integrity protection; an HTTP GET request to retrieve 407 the certificate MUST use TLS [RFC2818] [RFC5246]; the identity of the 408 server MUST be validated, as per Section 3.1 of HTTP Over TLS 409 [RFC2818]. Use of this header parameter is OPTIONAL. 411 4.1.5. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter 413 The "x5t" (X.509 Certificate SHA-1 Thumbprint) header parameter is a 414 base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER 415 encoding of the X.509 certificate [RFC5280] corresponding to the key 416 used to digitally sign the JWS. Use of this header parameter is 417 OPTIONAL. 419 If, in the future, certificate thumbprints need to be computed using 420 hash functions other than SHA-1, it is suggested that additional 421 related header parameters be defined for that purpose. For example, 422 it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint 423 using SHA-256) header parameter could be defined by registering it in 424 the IANA JSON Web Signature and Encryption Header Parameters registry 425 defined in Section 8.1. 427 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter 429 The "x5c" (X.509 Certificate Chain) header parameter contains the 430 X.509 public key certificate or certificate chain [RFC5280] 431 corresponding to the key used to digitally sign the JWS. The 432 certificate or certificate chain is represented as a JSON array of 433 certificate value strings. Each string in the array is a base64 434 encoded ([RFC4648] Section 4 -- not base64url encoded) DER 435 [ITU.X690.1994] PKIX certificate value. The certificate containing 436 the public key corresponding to the key used to digitally sign the 437 JWS MUST be the first certificate. This MAY be followed by 438 additional certificates, with each subsequent certificate being the 439 one used to certify the previous one. The recipient MUST verify the 440 certificate chain according to [RFC5280] and reject the signature if 441 any validation failure occurs. Use of this header parameter is 442 OPTIONAL. 444 See Appendix B for an example "x5c" value. 446 4.1.7. "kid" (Key ID) Header Parameter 448 The "kid" (key ID) header parameter is a hint indicating which key 449 was used to secure the JWS. This parameter allows originators to 450 explicitly signal a change of key to recipients. Should the 451 recipient be unable to locate a key corresponding to the "kid" value, 452 they SHOULD treat that condition as an error. The interpretation of 453 the "kid" value is unspecified. Its value MUST be a string. Use of 454 this header parameter is OPTIONAL. 456 When used with a JWK, the "kid" value can be used to match a JWK 457 "kid" parameter value. 459 4.1.8. "typ" (Type) Header Parameter 461 The "typ" (type) header parameter is used to declare the type of this 462 complete JWS object in an application-specific manner in contexts 463 where this is useful to the application. This parameter has no 464 effect upon the JWS processing. The type value "JOSE" can be used by 465 applications to indicate that this object is a JWS or JWE using the 466 JWS Compact Serialization or the JWE Compact Serialization. The type 467 value "JOSE+JSON" can be used by applications to indicate that this 468 object is a JWS or JWE using the JWS JSON Serialization or the JWE 469 JSON Serialization. Other type values can also be used by 470 applications. The "typ" value is a case sensitive string. Use of 471 this header parameter is OPTIONAL. 473 MIME Media Type [RFC2046] values MAY be used as "typ" values. When 474 MIME Media Type values are used, it is RECOMMENDED that they be 475 spelled using the exact character case used in the MIME Media Types 476 registry [IANA.MediaTypes], since this field is case sensitive, 477 whereas MIME Media Type values are case insensitive. 479 "typ" values SHOULD either be registered in the IANA JSON Web 480 Signature and Encryption Type Values registry defined in Section 8.2 481 or be a value that contains a Collision Resistant Name. 483 4.1.9. "cty" (Content Type) Header Parameter 485 The "cty" (content type) header parameter is used to declare the type 486 of the secured content (the payload) in an application-specific 487 manner in contexts where this is useful to the application. This 488 parameter has no effect upon the JWS processing. The "cty" value is 489 a case sensitive string. Use of this header parameter is OPTIONAL. 491 The values used for the "cty" header parameter come from the same 492 value space as the "typ" header parameter, with the same rules 493 applying. 495 4.1.10. "crit" (Critical) Header Parameter 497 The "crit" (critical) header parameter indicates that extensions to 498 [[ this specification ]] are being used that MUST be understood and 499 processed. Its value is an array listing the header parameter names 500 defined by those extensions that are used in the JWS Header. If any 501 of the listed extension header parameters are not understood and 502 supported by the receiver, it MUST reject the JWS. Senders MUST NOT 503 include header parameter names defined by [[ this specification ]] or 504 by [JWA] for use with JWS, duplicate names, or names that do not 505 occur as header parameter names within the JWS Header in the "crit" 506 list. Senders MUST not use the empty list "[]" as the "crit" value. 507 Recipients MAY reject the JWS if the critical list contains any 508 header parameter names defined by [[ this specification ]] or by 509 [JWA] for use with JWS, or any other constraints on its use are 510 violated. This header parameter MUST be integrity protected, and 511 therefore MUST occur only with the JWS Protected Header, when used. 512 Use of this header parameter is OPTIONAL. This header parameter MUST 513 be understood and processed by implementations. 515 An example use, along with a hypothetical "exp" (expiration-time) 516 field is: 518 {"alg":"ES256", 519 "crit":["exp"], 520 "exp":1363284000 521 } 523 4.2. Public Header Parameter Names 525 Additional Header Parameter Names can be defined by those using JWSs. 526 However, in order to prevent collisions, any new Header Parameter 527 Name SHOULD either be registered in the IANA JSON Web Signature and 528 Encryption Header Parameters registry defined in Section 8.1 or be a 529 Public Name: a value that contains a Collision Resistant Name. In 530 each case, the definer of the name or value needs to take reasonable 531 precautions to make sure they are in control of the part of the 532 namespace they use to define the Header Parameter Name. 534 New header parameters should be introduced sparingly, as they can 535 result in non-interoperable JWSs. 537 4.3. Private Header Parameter Names 539 A producer and consumer of a JWS may agree to use Header Parameter 540 Names that are Private Names: names that are not Registered Header 541 Parameter Names Section 4.1 or Public Header Parameter Names 542 Section 4.2. Unlike Public Header Parameter Names, Private Header 543 Parameter Names are subject to collision and should be used with 544 caution. 546 5. Producing and Consuming JWSs 548 5.1. Message Signing or MACing 550 To create a JWS, one MUST perform these steps. The order of the 551 steps is not significant in cases where there are no dependencies 552 between the inputs and outputs of the steps. 554 1. Create the content to be used as the JWS Payload. 556 2. Base64url encode the octets of the JWS Payload. This encoding 557 becomes the Encoded JWS Payload. 559 3. Create a JWS Header containing the desired set of header 560 parameters. Note that white space is explicitly allowed in the 561 representation and no canonicalization need be performed before 562 encoding. 564 4. Base64url encode the octets of the UTF-8 representation of the 565 JWS Protected Header to create the Encoded JWS Header. If the 566 JWS Protected Header is not present (which can only happen when 567 using the JWS JSON Serialization and no "protected" member is 568 present), let the Encoded JWS Header be the empty string. 570 5. Compute the JWS Signature in the manner defined for the 571 particular algorithm being used over the JWS Signing Input (the 572 concatenation of the Encoded JWS Header, a period ('.') 573 character, and the Encoded JWS Payload). The "alg" (algorithm) 574 header parameter MUST be present in the JWS Header, with the 575 algorithm value accurately representing the algorithm used to 576 construct the JWS Signature. 578 6. Base64url encode the representation of the JWS Signature to 579 create the Encoded JWS Signature. 581 7. The three encoded parts are result values used in both the JWS 582 Compact Serialization and the JWS JSON Serialization 583 representations. 585 8. If the JWS JSON Serialization is being used, repeat this process 586 for each digital signature or MAC value being applied. 588 9. Create the desired serialized output. The JWS Compact 589 Serialization of this result is the concatenation of the Encoded 590 JWS Header, the Encoded JWS Payload, and the Encoded JWS 591 Signature in that order, with the three strings being separated 592 by two period ('.') characters. The JWS JSON Serialization is 593 described in Section 7.2. 595 5.2. Message Signature or MAC Validation 597 When validating a JWS, the following steps MUST be taken. The order 598 of the steps is not significant in cases where there are no 599 dependencies between the inputs and outputs of the steps. If any of 600 the listed steps fails, then the signature or MAC cannot be 601 validated. 603 It is an application decision which signatures, MACs, or plaintext 604 values must successfully validate for the JWS to be accepted. In 605 some cases, all must successfully validate or the JWS will be 606 rejected. In other cases, only a specific signature, MAC, or 607 plaintext value needs to be successfully validated. However, in all 608 cases, at least one signature, MAC, or plaintext value MUST 609 successfully validate or the JWS MUST be rejected. 611 1. Parse the serialized input to determine the values of the JWS 612 Header, the Encoded JWS Payload, and the Encoded JWS Signature. 613 When using the JWS Compact Serialization, the Encoded JWS 614 Header, the Encoded JWS Payload, and the Encoded JWS Signature 615 are represented as text strings in that order, separated by two 616 period ('.') characters. The JWS JSON Serialization is 617 described in Section 7.2. 619 2. The Encoded JWS Header MUST be successfully base64url decoded 620 following the restriction given in this specification that no 621 padding characters have been used. 623 3. Let the JWS Protected Header value be the result of base64url 624 decoding the Encoded JWS Header. 626 4. The resulting JWS Protected Header MUST be a completely valid 627 JSON object conforming to RFC 4627 [RFC4627]. 629 5. If using the JWS Compact Serialization, let the JWS Header be 630 the JWS Protected Header; otherwise, when using the JWS JSON 631 Serialization, let the JWS Header be the union of the members of 632 the corresponding "protected" and "header" header parameter 633 values, all of which must be completely valid JSON objects. 635 6. The resulting JWS Header MUST NOT contain duplicate Header 636 Parameter Names. When using the JWS JSON Serialization, this 637 restriction includes that the same Header Parameter Name also 638 MUST NOT occur in distinct JSON Text Object values that together 639 comprise the JWS Header. 641 7. The resulting JWS Header MUST be validated to only include 642 parameters and values whose syntax and semantics are both 643 understood and supported or that are specified as being ignored 644 when not understood. 646 8. The Encoded JWS Payload MUST be successfully base64url decoded 647 following the restriction given in this specification that no 648 padding characters have been used. 650 9. The Encoded JWS Signature MUST be successfully base64url decoded 651 following the restriction given in this specification that no 652 padding characters have been used. 654 10. The JWS Signature MUST be successfully validated against the JWS 655 Signing Input (the concatenation of the Encoded JWS Header, a 656 period ('.') character, and the Encoded JWS Payload) in the 657 manner defined for the algorithm being used, which MUST be 658 accurately represented by the value of the "alg" (algorithm) 659 header parameter, which MUST be present. 661 11. If the JWS JSON Serialization is being used, repeat this process 662 for each digital signature or MAC value contained in the 663 representation. 665 5.3. String Comparison Rules 667 Processing a JWS inevitably requires comparing known strings to 668 values in JSON objects. For example, in checking what the algorithm 669 is, the Unicode string encoding "alg" will be checked against the 670 member names in the JWS Header to see if there is a matching Header 671 Parameter Name. A similar process occurs when determining if the 672 value of the "alg" header parameter represents a supported algorithm. 674 Comparisons between JSON strings and other Unicode strings MUST be 675 performed as specified below: 677 1. Remove any JSON escaping from the input JSON string and convert 678 the string into a sequence of Unicode code points. 680 2. Likewise, convert the string to be compared against into a 681 sequence of Unicode code points. 683 3. Unicode Normalization [USA15] MUST NOT be applied at any point to 684 either the JSON string or to the string it is to be compared 685 against. 687 4. Comparisons between the two strings MUST be performed as a 688 Unicode code point to code point equality comparison. (Note that 689 values that originally used different Unicode encodings (UTF-8, 690 UTF-16, etc.) may result in the same code point values.) 692 Also, see the JSON security considerations in Section 9.2 and the 693 Unicode security considerations in Section 9.3. 695 6. Key Identification 697 It is necessary for the recipient of a JWS to be able to determine 698 the key that was employed for the digital signature or MAC operation. 699 The key employed can be identified using the Header Parameter methods 700 described in Section 4.1 or can be identified using methods that are 701 outside the scope of this specification. Specifically, the Header 702 Parameters "jku", "jwk", "x5u", "x5t", "x5c", and "kid" can be used 703 to identify the key used. These header parameters MUST be integrity 704 protected if the information that they convey is to be utilized in a 705 trust decision. 707 The sender SHOULD include sufficient information in the Header 708 Parameters to identify the key used, unless the application uses 709 another means or convention to determine the key used. Validation of 710 the signature or MAC fails when the algorithm used requires a key 711 (which is true of all algorithms except for "none") and the key used 712 cannot be determined. 714 The means of exchanging any shared symmetric keys used is outside the 715 scope of this specification. 717 7. Serializations 719 JWS objects use one of two serializations, the JWS Compact 720 Serialization or the JWS JSON Serialization. The JWS Compact 721 Serialization is mandatory to implement. Implementation of the JWS 722 JSON Serialization is OPTIONAL. 724 7.1. JWS Compact Serialization 726 The JWS Compact Serialization represents digitally signed or MACed 727 content as a compact URL-safe string. This string is the 728 concatenation of the Encoded JWS Header, the Encoded JWS Payload, and 729 the Encoded JWS Signature in that order, with the three strings being 730 separated by two period ('.') characters. Only one signature/MAC is 731 supported by the JWS Compact Serialization. 733 7.2. JWS JSON Serialization 735 The JWS JSON Serialization represents digitally signed or MACed 736 content as a JSON object. Unlike the JWS Compact Serialization, 737 content using the JWS JSON Serialization can be secured with more 738 than one digital signature and/or MAC value. 740 The representation is closely related to that used in the JWS Compact 741 Serialization, with the following differences for the JWS JSON 742 Serialization: 744 o Values in the JWS JSON Serialization are represented as members of 745 a JSON object, rather than as base64url encoded strings separated 746 by period ('.') characters. (However binary values and values 747 that are integrity protected are still base64url encoded.) 749 o The Encoded JWS Payload value is stored in the "payload" member. 751 o There can be multiple signature and/or MAC values, rather than 752 just one. A JSON array in the "signatures" member is used to hold 753 values that are specific to a particular signature or MAC 754 computation, with one array element per signature/MAC represented. 755 These array elements are JSON objects. 757 o Each Encoded JWS Signature value, if non-empty, is stored in the 758 "signature" member of a JSON object that is an element of the 759 "signatures" array. 761 o Each Encoded JWS Header value, which is a base64url encoded set of 762 header parameter values that are included in the signature/MAC 763 computation, if non-empty, is stored in the "protected" member of 764 the corresponding element of the "signatures" array. 766 o Unlike the JWS Compact Serialization, in the JWS JSON 767 Serialization there can also be header parameter values that are 768 not included in the signature/MAC computation. If present, 769 unprotected header parameter values are represented as an 770 unencoded JSON Text Object in the "header" member of the 771 corresponding element of the "signatures" array. 773 o The header parameter values used when creating or validating 774 individual signature or MAC values are the union of the two sets 775 of header parameter values that may be present: (1) the integrity- 776 protected per-signature/MAC values represented in the "protected" 777 member of the signature/MAC's array element, and (2) the non- 778 integrity-protected per-signature/MAC values in the "header" 779 member of the signature/MAC's array element. The union of these 780 sets of header parameters comprises the JWS Header. The header 781 parameter names in the two locations MUST be disjoint. 783 The syntax of a JWS using the JWS JSON Serialization is as follows: 785 { 786 "payload":"" 787 "signatures":[ 788 {"protected":", 789 "header":"", 790 "signature":""}, 791 ... 792 {"protected":", 793 "header":"", 794 "signature":""}], 795 } 797 Of these members, only the "payload", "signatures", and "signature" 798 members MUST be present. At least one of the "protected" and 799 "header" members MUST be present for each signature/MAC computation 800 so that an "alg" header parameter value is conveyed. 802 The contents of the Encoded JWS Payload and Encoded JWS Signature 803 values are exactly as defined in the rest of this specification. 804 They are interpreted and validated in the same manner, with each 805 corresponding Encoded JWS Signature and set of header parameter 806 values being created and validated together. The JWS Header values 807 used are the union of the header parameters in the corresponding 808 "protected" and "header" members, as described earlier. 810 Each JWS Signature value is computed on the JWS Signing Input using 811 the parameters of the corresponding JWS Header value in the same 812 manner as for the JWS Compact Serialization. This has the desirable 813 property that each Encoded JWS Signature value in the "signatures" 814 array is identical to the value that would have been computed for the 815 same parameter in the JWS Compact Serialization, provided that the 816 Encoded JWS Header value for that signature/MAC computation (which 817 represents the integrity-protected header parameter values) matches 818 that used in the JWS Compact Serialization. 820 See Appendix A.6 for an example of computing a JWS using the JWS JSON 821 Serialization. 823 8. IANA Considerations 825 The following registration procedure is used for all the registries 826 established by this specification. 828 Values are registered with a Specification Required [RFC5226] after a 829 two-week review period on the [TBD]@ietf.org mailing list, on the 830 advice of one or more Designated Experts. However, to allow for the 831 allocation of values prior to publication, the Designated Expert(s) 832 may approve registration once they are satisfied that such a 833 specification will be published. 835 Registration requests must be sent to the [TBD]@ietf.org mailing list 836 for review and comment, with an appropriate subject (e.g., "Request 837 for access token type: example"). [[ Note to the RFC Editor: The name 838 of the mailing list should be determined in consultation with the 839 IESG and IANA. Suggested name: jose-reg-review. ]] 841 Within the review period, the Designated Expert(s) will either 842 approve or deny the registration request, communicating this decision 843 to the review list and IANA. Denials should include an explanation 844 and, if applicable, suggestions as to how to make the request 845 successful. Registration requests that are undetermined for a period 846 longer than 21 days can be brought to the IESG's attention (using the 847 iesg@iesg.org mailing list) for resolution. 849 Criteria that should be applied by the Designated Expert(s) includes 850 determining whether the proposed registration duplicates existing 851 functionality, determining whether it is likely to be of general 852 applicability or whether it is useful only for a single application, 853 and whether the registration makes sense. 855 IANA must only accept registry updates from the Designated Expert(s) 856 and should direct all requests for registration to the review mailing 857 list. 859 It is suggested that multiple Designated Experts be appointed who are 860 able to represent the perspectives of different applications using 861 this specification, in order to enable broadly-informed review of 862 registration decisions. In cases where a registration decision could 863 be perceived as creating a conflict of interest for a particular 864 Expert, that Expert should defer to the judgment of the other 865 Expert(s). 867 8.1. JSON Web Signature and Encryption Header Parameters Registry 869 This specification establishes the IANA JSON Web Signature and 870 Encryption Header Parameters registry for JWS and JWE Header 871 Parameter Names. The registry records the Header Parameter Name and 872 a reference to the specification that defines it. The same Header 873 Parameter Name MAY be registered multiple times, provided that the 874 parameter usage is compatible between the specifications. Different 875 registrations of the same Header Parameter Name will typically use 876 different Header Parameter Usage Location(s) values. 878 8.1.1. Registration Template 880 Header Parameter Name: 881 The name requested (e.g., "example"). Because a core goal of this 882 specification is for the resulting representations to be compact, 883 it is RECOMMENDED that the name be short -- not to exceed 8 884 characters without a compelling reason to do so. This name is 885 case sensitive. Names may not match other registered names in a 886 case insensitive manner unless the Designated Expert(s) state that 887 there is a compelling reason to allow an exception in this 888 particular case. 890 Header Parameter Usage Location(s): 891 The header parameter usage locations, which should be one or more 892 of the values "JWS" or "JWE". 894 Change Controller: 895 For Standards Track RFCs, state "IESG". For others, give the name 896 of the responsible party. Other details (e.g., postal address, 897 email address, home page URI) may also be included. 899 Specification Document(s): 900 Reference to the document(s) that specify the parameter, 901 preferably including URI(s) that can be used to retrieve copies of 902 the document(s). An indication of the relevant sections may also 903 be included but is not required. 905 8.1.2. Initial Registry Contents 907 This specification registers the Header Parameter Names defined in 908 Section 4.1 in this registry. 910 o Header Parameter Name: "alg" 911 o Header Parameter Usage Location(s): JWS 912 o Change Controller: IESG 913 o Specification Document(s): Section 4.1.1 of [[ this document ]] 915 o Header Parameter Name: "jku" 916 o Header Parameter Usage Location(s): JWS 917 o Change Controller: IESG 918 o Specification Document(s): Section 4.1.2 of [[ this document ]] 920 o Header Parameter Name: "jwk" 921 o Header Parameter Usage Location(s): JWS 922 o Change Controller: IESG 923 o Specification document(s): Section 4.1.3 of [[ this document ]] 925 o Header Parameter Name: "x5u" 926 o Header Parameter Usage Location(s): JWS 927 o Change Controller: IESG 928 o Specification Document(s): Section 4.1.4 of [[ this document ]] 930 o Header Parameter Name: "x5t" 931 o Header Parameter Usage Location(s): JWS 932 o Change Controller: IESG 933 o Specification Document(s): Section 4.1.5 of [[ this document ]] 935 o Header Parameter Name: "x5c" 936 o Header Parameter Usage Location(s): JWS 937 o Change Controller: IESG 938 o Specification Document(s): Section 4.1.6 of [[ this document ]] 939 o Header Parameter Name: "kid" 940 o Header Parameter Usage Location(s): JWS 941 o Change Controller: IESG 942 o Specification Document(s): Section 4.1.7 of [[ this document ]] 944 o Header Parameter Name: "typ" 945 o Header Parameter Usage Location(s): JWS 946 o Change Controller: IESG 947 o Specification Document(s): Section 4.1.8 of [[ this document ]] 949 o Header Parameter Name: "cty" 950 o Header Parameter Usage Location(s): JWS 951 o Change Controller: IESG 952 o Specification Document(s): Section 4.1.9 of [[ this document ]] 954 o Header Parameter Name: "crit" 955 o Header Parameter Usage Location(s): JWS 956 o Change Controller: IESG 957 o Specification Document(s): Section 4.1.10 of [[ this document ]] 959 8.2. JSON Web Signature and Encryption Type Values Registry 961 This specification establishes the IANA JSON Web Signature and 962 Encryption Type Values registry for values of the JWS and JWE "typ" 963 (type) header parameter. It is RECOMMENDED that all registered "typ" 964 values also include a MIME Media Type [RFC2046] value that the 965 registered value is a short name for. The registry records the "typ" 966 value, the MIME type value that it is an abbreviation for (if any), 967 and a reference to the specification that defines it. 969 MIME Media Type [RFC2046] values MUST NOT be directly registered as 970 "typ" values; rather, "typ" values MAY be registered as short names 971 for MIME types. 973 8.2.1. Registration Template 975 "typ" Header Parameter Value: 976 The name requested (e.g., "example"). Because a core goal of this 977 specification is for the resulting representations to be compact, 978 it is RECOMMENDED that the name be short -- not to exceed 8 979 characters without a compelling reason to do so. This name is 980 case sensitive. Names may not match other registered names in a 981 case insensitive manner unless the Designated Expert(s) state that 982 there is a compelling reason to allow an exception in this 983 particular case. 985 Abbreviation for MIME Type: 986 The MIME type that this name is an abbreviation for (e.g., 987 "application/example"). 989 Change Controller: 990 For Standards Track RFCs, state "IESG". For others, give the name 991 of the responsible party. Other details (e.g., postal address, 992 email address, home page URI) may also be included. 994 Specification Document(s): 995 Reference to the document(s) that specify the parameter, 996 preferably including URI(s) that can be used to retrieve copies of 997 the document(s). An indication of the relevant sections may also 998 be included but is not required. 1000 8.2.2. Initial Registry Contents 1002 This specification registers the "JOSE" and "JOSE+JSON" type values 1003 in this registry: 1005 o "typ" Header Parameter Value: "JOSE" 1006 o Abbreviation for MIME type: application/jose 1007 o Change Controller: IESG 1008 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1010 o "typ" Header Parameter Value: "JOSE+JSON" 1011 o Abbreviation for MIME type: application/jose+json 1012 o Change Controller: IESG 1013 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1015 8.3. Media Type Registration 1017 8.3.1. Registry Contents 1019 This specification registers the "application/jose" Media Type 1020 [RFC2046] in the MIME Media Types registry [IANA.MediaTypes], which 1021 can be used to indicate that the content is a JWS or JWE object using 1022 the JWS Compact Serialization or the JWE Compact Serialization and 1023 the "application/jose+json" Media Type in the MIME Media Types 1024 registry, which can be used to indicate that the content is a JWS or 1025 JWE object using the JWS JSON Serialization or the JWE JSON 1026 Serialization. 1028 o Type name: application 1029 o Subtype name: jose 1030 o Required parameters: n/a 1031 o Optional parameters: n/a 1032 o Encoding considerations: 8bit; application/jose values are encoded 1033 as a series of base64url encoded values (some of which may be the 1034 empty string) separated by period ('.') characters. 1035 o Security considerations: See the Security Considerations section 1036 of [[ this document ]] 1037 o Interoperability considerations: n/a 1038 o Published specification: [[ this document ]] 1039 o Applications that use this media type: OpenID Connect, Mozilla 1040 Persona, Salesforce, Google, numerous others that use signed JWTs 1041 o Additional information: Magic number(s): n/a, File extension(s): 1042 n/a, Macintosh file type code(s): n/a 1043 o Person & email address to contact for further information: Michael 1044 B. Jones, mbj@microsoft.com 1045 o Intended usage: COMMON 1046 o Restrictions on usage: none 1047 o Author: Michael B. Jones, mbj@microsoft.com 1048 o Change Controller: IESG 1050 o Type name: application 1051 o Subtype name: jose+json 1052 o Required parameters: n/a 1053 o Optional parameters: n/a 1054 o Encoding considerations: 8bit; application/jose+json values are 1055 represented as a JSON Object; UTF-8 encoding SHOULD be employed 1056 for the JSON object. 1057 o Security considerations: See the Security Considerations section 1058 of [[ this document ]] 1059 o Interoperability considerations: n/a 1060 o Published specification: [[ this document ]] 1061 o Applications that use this media type: TBD 1062 o Additional information: Magic number(s): n/a, File extension(s): 1063 n/a, Macintosh file type code(s): n/a 1064 o Person & email address to contact for further information: Michael 1065 B. Jones, mbj@microsoft.com 1066 o Intended usage: COMMON 1067 o Restrictions on usage: none 1068 o Author: Michael B. Jones, mbj@microsoft.com 1069 o Change Controller: IESG 1071 9. Security Considerations 1073 9.1. Cryptographic Security Considerations 1075 All of the security issues faced by any cryptographic application 1076 must be faced by a JWS/JWE/JWK agent. Among these issues are 1077 protecting the user's private and symmetric keys, preventing various 1078 attacks, and helping the user avoid mistakes such as inadvertently 1079 encrypting a message for the wrong recipient. The entire list of 1080 security considerations is beyond the scope of this document, but 1081 some significant concerns are listed here. 1083 All the security considerations in XML DSIG 2.0 1084 [W3C.CR-xmldsig-core2-20120124], also apply to this specification, 1085 other than those that are XML specific. Likewise, many of the best 1086 practices documented in XML Signature Best Practices 1087 [W3C.WD-xmldsig-bestpractices-20110809] also apply to this 1088 specification, other than those that are XML specific. 1090 Keys are only as strong as the amount of entropy used to generate 1091 them. A minimum of 128 bits of entropy should be used for all keys, 1092 and depending upon the application context, more may be required. In 1093 particular, it may be difficult to generate sufficiently random 1094 values in some browsers and application environments. 1096 Creators of JWSs should not allow third parties to insert arbitrary 1097 content into the message without adding entropy not controlled by the 1098 third party. 1100 When utilizing TLS to retrieve information, the authority providing 1101 the resource MUST be authenticated and the information retrieved MUST 1102 be free from modification. 1104 When cryptographic algorithms are implemented in such a way that 1105 successful operations take a different amount of time than 1106 unsuccessful operations, attackers may be able to use the time 1107 difference to obtain information about the keys employed. Therefore, 1108 such timing differences must be avoided. 1110 A SHA-1 hash is used when computing "x5t" (x.509 certificate 1111 thumbprint) values, for compatibility reasons. Should an effective 1112 means of producing SHA-1 hash collisions be developed, and should an 1113 attacker wish to interfere with the use of a known certificate on a 1114 given system, this could be accomplished by creating another 1115 certificate whose SHA-1 hash value is the same and adding it to the 1116 certificate store used by the intended victim. A prerequisite to 1117 this attack succeeding is the attacker having write access to the 1118 intended victim's certificate store. 1120 If, in the future, certificate thumbprints need to be computed using 1121 hash functions other than SHA-1, it is suggested that additional 1122 related header parameters be defined for that purpose. For example, 1123 it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint 1124 using SHA-256) header parameter could be defined and used. 1126 9.2. JSON Security Considerations 1128 Strict JSON validation is a security requirement. If malformed JSON 1129 is received, then the intent of the sender is impossible to reliably 1130 discern. Ambiguous and potentially exploitable situations could 1131 arise if the JSON parser used does not reject malformed JSON syntax. 1133 Section 2.2 of the JavaScript Object Notation (JSON) specification 1134 [RFC4627] states "The names within an object SHOULD be unique", 1135 whereas this specification states that "Header Parameter Names within 1136 this object MUST be unique; recipients MUST either reject JWSs with 1137 duplicate Header Parameter Names or use a JSON parser that returns 1138 only the lexically last duplicate member name, as specified in 1139 Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript]". 1140 Thus, this specification requires that the Section 2.2 "SHOULD" be 1141 treated as a "MUST" by senders and that it be either treated as a 1142 "MUST" or in the manner specified in ECMAScript 5.1 by receivers. 1143 Ambiguous and potentially exploitable situations could arise if the 1144 JSON parser used does not enforce the uniqueness of member names or 1145 returns an unpredictable value for duplicate member names. 1147 Some JSON parsers might not reject input that contains extra 1148 significant characters after a valid input. For instance, the input 1149 "{"tag":"value"}ABCD" contains a valid JSON object followed by the 1150 extra characters "ABCD". Such input MUST be rejected in its 1151 entirety. 1153 9.3. Unicode Comparison Security Considerations 1155 Header Parameter Names and algorithm names are Unicode strings. For 1156 security reasons, the representations of these names must be compared 1157 verbatim after performing any escape processing (as per RFC 4627 1158 [RFC4627], Section 2.5). This means, for instance, that these JSON 1159 strings must compare as being equal ("sig", "\u0073ig"), whereas 1160 these must all compare as being not equal to the first set or to each 1161 other ("SIG", "Sig", "si\u0047"). 1163 JSON strings can contain characters outside the Unicode Basic 1164 Multilingual Plane. For instance, the G clef character (U+1D11E) may 1165 be represented in a JSON string as "\uD834\uDD1E". Ideally, JWS 1166 implementations SHOULD ensure that characters outside the Basic 1167 Multilingual Plane are preserved and compared correctly; 1168 alternatively, if this is not possible due to these characters 1169 exercising limitations present in the underlying JSON implementation, 1170 then input containing them MUST be rejected. 1172 9.4. TLS Requirements 1174 Implementations MUST support TLS. Which version(s) ought to be 1175 implemented will vary over time, and depend on the widespread 1176 deployment and known security vulnerabilities at the time of 1177 implementation. At the time of this writing, TLS version 1.2 1178 [RFC5246] is the most recent version, but has very limited actual 1179 deployment, and might not be readily available in implementation 1180 toolkits. TLS version 1.0 [RFC2246] is the most widely deployed 1181 version, and will give the broadest interoperability. 1183 To protect against information disclosure and tampering, 1184 confidentiality protection MUST be applied using TLS with a 1185 ciphersuite that provides confidentiality and integrity protection. 1187 Whenever TLS is used, a TLS server certificate check MUST be 1188 performed, per RFC 6125 [RFC6125]. 1190 10. References 1192 10.1. Normative References 1194 [ECMAScript] 1195 Ecma International, "ECMAScript Language Specification, 1196 5.1 Edition", ECMA 262, June 2011. 1198 [IANA.MediaTypes] 1199 Internet Assigned Numbers Authority (IANA), "MIME Media 1200 Types", 2005. 1202 [ITU.X690.1994] 1203 International Telecommunications Union, "Information 1204 Technology - ASN.1 encoding rules: Specification of Basic 1205 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1206 Distinguished Encoding Rules (DER)", ITU-T Recommendation 1207 X.690, 1994. 1209 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1210 draft-ietf-jose-json-web-algorithms (work in progress), 1211 September 2013. 1213 [JWK] Jones, M., "JSON Web Key (JWK)", 1214 draft-ietf-jose-json-web-key (work in progress), 1215 September 2013. 1217 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 1218 Mail: Part I: Message Encryption and Authentication 1219 Procedures", RFC 1421, February 1993. 1221 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1222 Extensions (MIME) Part Two: Media Types", RFC 2046, 1223 November 1996. 1225 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1226 Requirement Levels", BCP 14, RFC 2119, March 1997. 1228 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 1229 RFC 2246, January 1999. 1231 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1233 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1234 10646", STD 63, RFC 3629, November 2003. 1236 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1237 Resource Identifier (URI): Generic Syntax", STD 66, 1238 RFC 3986, January 2005. 1240 [RFC4627] Crockford, D., "The application/json Media Type for 1241 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1243 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1244 Encodings", RFC 4648, October 2006. 1246 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1247 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1248 May 2008. 1250 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1251 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1253 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1254 Housley, R., and W. Polk, "Internet X.509 Public Key 1255 Infrastructure Certificate and Certificate Revocation List 1256 (CRL) Profile", RFC 5280, May 2008. 1258 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1259 Verification of Domain-Based Application Service Identity 1260 within Internet Public Key Infrastructure Using X.509 1261 (PKIX) Certificates in the Context of Transport Layer 1262 Security (TLS)", RFC 6125, March 2011. 1264 [USA15] Davis, M., Whistler, K., and M. Deurst, "Unicode 1265 Normalization Forms", Unicode Standard Annex 15, 09 2009. 1267 [USASCII] American National Standards Institute, "Coded Character 1268 Set -- 7-bit American Standard Code for Information 1269 Interchange", ANSI X3.4, 1986. 1271 [W3C.WD-xmldsig-bestpractices-20110809] 1272 Datta, P. and F. Hirsch, "XML Signature Best Practices", 1273 World Wide Web Consortium WD WD-xmldsig-bestpractices- 1274 20110809, August 2011, . 1277 10.2. Informative References 1279 [CanvasApp] 1280 Facebook, "Canvas Applications", 2010. 1282 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 1283 September 2010. 1285 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 1286 Encryption (JWE)", draft-ietf-jose-json-web-encryption 1287 (work in progress), September 2013. 1289 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1290 (JWT)", draft-ietf-oauth-json-web-token (work in 1291 progress), July 2013. 1293 [MagicSignatures] 1294 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 1295 Signatures", January 2011. 1297 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1298 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1299 July 2005. 1301 [W3C.CR-xmldsig-core2-20120124] 1302 Eastlake, D., Reagle, J., Yiu, K., Solo, D., Datta, P., 1303 Hirsch, F., Cantor, S., and T. Roessler, "XML Signature 1304 Syntax and Processing Version 2.0", World Wide Web 1305 Consortium CR CR-xmldsig-core2-20120124, January 2012, 1306 . 1308 Appendix A. JWS Examples 1310 This section provides several examples of JWSs. While the first 1311 three examples all represent JSON Web Tokens (JWTs) [JWT], the 1312 payload can be any octet sequence, as shown in Appendix A.4. 1314 A.1. Example JWS using HMAC SHA-256 1316 A.1.1. Encoding 1318 The following example JWS Header declares that the data structure is 1319 a JSON Web Token (JWT) [JWT] and the JWS Signing Input is secured 1320 using the HMAC SHA-256 algorithm. 1322 {"typ":"JWT", 1323 "alg":"HS256"} 1325 The following octet sequence contains the UTF-8 representation of the 1326 JWS Header: 1328 [123, 34, 116, 121, 112, 34, 58, 34, 74, 87, 84, 34, 44, 13, 10, 32, 1329 34, 97, 108, 103, 34, 58, 34, 72, 83, 50, 53, 54, 34, 125] 1331 Base64url encoding these octets yields this Encoded JWS Header value: 1333 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 1335 The JWS Payload used in this example is the octets of the UTF-8 1336 representation of the JSON object below. (Note that the payload can 1337 be any base64url encoded octet sequence, and need not be a base64url 1338 encoded JSON object.) 1340 {"iss":"joe", 1341 "exp":1300819380, 1342 "http://example.com/is_root":true} 1344 The following octet sequence, which is the UTF-8 representation of 1345 the JSON object above, is the JWS Payload: 1347 [123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10, 1348 32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56, 1349 48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97, 1350 109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111, 1351 111, 116, 34, 58, 116, 114, 117, 101, 125] 1353 Base64url encoding the JWS Payload yields this Encoded JWS Payload 1354 value (with line breaks for display purposes only): 1356 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1357 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1359 Concatenating the Encoded JWS Header, a period ('.') character, and 1360 the Encoded JWS Payload yields this JWS Signing Input value (with 1361 line breaks for display purposes only): 1363 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 1364 . 1365 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1366 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1368 The ASCII representation of the JWS Signing Input is the following 1369 octet sequence: 1371 [101, 121, 74, 48, 101, 88, 65, 105, 79, 105, 74, 75, 86, 49, 81, 1372 105, 76, 65, 48, 75, 73, 67, 74, 104, 98, 71, 99, 105, 79, 105, 74, 1373 73, 85, 122, 73, 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 1374 77, 105, 79, 105, 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 1375 74, 108, 101, 72, 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 1376 107, 122, 79, 68, 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 1377 72, 65, 54, 76, 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 1378 109, 78, 118, 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 1379 106, 112, 48, 99, 110, 86, 108, 102, 81] 1381 HMACs are generated using keys. This example uses the symmetric key 1382 represented in JSON Web Key [JWK] format below (with line breaks for 1383 display purposes only): 1385 {"kty":"oct", 1386 "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75 1387 aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow" 1388 } 1390 Running the HMAC SHA-256 algorithm on the octets of the ASCII 1391 representation of the JWS Signing Input with this key yields this 1392 octet sequence: 1394 [116, 24, 223, 180, 151, 153, 224, 37, 79, 250, 96, 125, 216, 173, 1395 187, 186, 22, 212, 37, 77, 105, 214, 191, 240, 91, 88, 5, 88, 83, 1396 132, 141, 121] 1398 Base64url encoding the above HMAC output yields this Encoded JWS 1399 Signature value: 1401 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 1403 Concatenating these values in the order Header.Payload.Signature with 1404 period ('.') characters between the parts yields this complete JWS 1405 representation using the JWS Compact Serialization (with line breaks 1406 for display purposes only): 1408 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 1409 . 1410 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1411 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1412 . 1413 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk 1415 A.1.2. Decoding 1417 Decoding the JWS requires base64url decoding the Encoded JWS Header, 1418 Encoded JWS Payload, and Encoded JWS Signature to produce the JWS 1419 Header, JWS Payload, and JWS Signature octet sequences. The octet 1420 sequence containing the UTF-8 representation of the JWS Header is 1421 decoded into the JWS Header string. 1423 A.1.3. Validating 1425 Next we validate the decoded results. Since the "alg" parameter in 1426 the header is "HS256", we validate the HMAC SHA-256 value contained 1427 in the JWS Signature. 1429 First, we validate that the JWS Header string is legal JSON. 1431 To validate the HMAC value, we repeat the previous process of using 1432 the correct key and the ASCII representation of the JWS Signing Input 1433 as input to the HMAC SHA-256 function and then taking the output and 1434 determining if it matches the JWS Signature. If it matches exactly, 1435 the HMAC has been validated. 1437 A.2. Example JWS using RSASSA-PKCS-v1_5 SHA-256 1439 A.2.1. Encoding 1441 The JWS Header in this example is different from the previous example 1442 in two ways: First, because a different algorithm is being used, the 1443 "alg" value is different. Second, for illustration purposes only, 1444 the optional "typ" parameter is not used. (This difference is not 1445 related to the algorithm employed.) The JWS Header used is: 1447 {"alg":"RS256"} 1449 The following octet sequence contains the UTF-8 representation of the 1450 JWS Header: 1452 [123, 34, 97, 108, 103, 34, 58, 34, 82, 83, 50, 53, 54, 34, 125] 1454 Base64url encoding these octets yields this Encoded JWS Header value: 1456 eyJhbGciOiJSUzI1NiJ9 1458 The JWS Payload used in this example, which follows, is the same as 1459 in the previous example. Since the Encoded JWS Payload will 1460 therefore be the same, its computation is not repeated here. 1462 {"iss":"joe", 1463 "exp":1300819380, 1464 "http://example.com/is_root":true} 1466 Concatenating the Encoded JWS Header, a period ('.') character, and 1467 the Encoded JWS Payload yields this JWS Signing Input value (with 1468 line breaks for display purposes only): 1470 eyJhbGciOiJSUzI1NiJ9 1471 . 1472 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1473 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1475 The ASCII representation of the JWS Signing Input is the following 1476 octet sequence: 1478 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 122, 73, 1479 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, 1480 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 74, 108, 101, 72, 1481 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 107, 122, 79, 68, 1482 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 72, 65, 54, 76, 1483 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 109, 78, 118, 1484 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48, 1485 99, 110, 86, 108, 102, 81] 1487 This example uses the RSA key represented in JSON Web Key [JWK] 1488 format below (with line breaks for display purposes only): 1490 {"kty":"RSA", 1491 "n":"ofgWCuLjybRlzo0tZWJjNiuSfb4p4fAkd_wWJcyQoTbji9k0l8W26mPddx 1492 HmfHQp-Vaw-4qPCJrcS2mJPMEzP1Pt0Bm4d4QlL-yRT-SFd2lZS-pCgNMs 1493 D1W_YpRPEwOWvG6b32690r2jZ47soMZo9wGzjb_7OMg0LOL-bSf63kpaSH 1494 SXndS5z5rexMdbBYUsLA9e-KXBdQOS-UTo7WTBEMa2R2CapHg665xsmtdV 1495 MTBQY4uDZlxvb3qCo5ZwKh9kG4LT6_I5IhlJH7aGhyxXFvUK-DWNmoudF8 1496 NAco9_h9iaGNj8q2ethFkMLs91kzk2PAcDTW9gb54h4FRWyuXpoQ", 1497 "e":"AQAB", 1498 "d":"Eq5xpGnNCivDflJsRQBXHx1hdR1k6Ulwe2JZD50LpXyWPEAeP88vLNO97I 1499 jlA7_GQ5sLKMgvfTeXZx9SE-7YwVol2NXOoAJe46sui395IW_GO-pWJ1O0 1500 BkTGoVEn2bKVRUCgu-GjBVaYLU6f3l9kJfFNS3E0QbVdxzubSu3Mkqzjkn 1501 439X0M_V51gfpRLI9JYanrC4D4qAdGcopV_0ZHHzQlBjudU2QvXt4ehNYT 1502 CBr6XCLQUShb1juUO1ZdiYoFaFQT5Tw8bGUl_x_jTj3ccPDVZFD9pIuhLh 1503 BOneufuBiB4cS98l2SR_RQyGWSeWjnczT0QU91p1DhOVRuOopznQ" 1505 } 1507 The RSA private key is then passed to the RSA signing function, which 1508 also takes the hash type, SHA-256, and the octets of the ASCII 1509 representation of the JWS Signing Input as inputs. The result of the 1510 digital signature is an octet sequence, which represents a big endian 1511 integer. In this example, it is: 1513 [112, 46, 33, 137, 67, 232, 143, 209, 30, 181, 216, 45, 191, 120, 69, 1514 243, 65, 6, 174, 27, 129, 255, 247, 115, 17, 22, 173, 209, 113, 125, 1515 131, 101, 109, 66, 10, 253, 60, 150, 238, 221, 115, 162, 102, 62, 81, 1516 102, 104, 123, 0, 11, 135, 34, 110, 1, 135, 237, 16, 115, 249, 69, 1517 229, 130, 173, 252, 239, 22, 216, 90, 121, 142, 232, 198, 109, 219, 1518 61, 184, 151, 91, 23, 208, 148, 2, 190, 237, 213, 217, 217, 112, 7, 1519 16, 141, 178, 129, 96, 213, 248, 4, 12, 167, 68, 87, 98, 184, 31, 1520 190, 127, 249, 217, 46, 10, 231, 111, 36, 242, 91, 51, 187, 230, 244, 1521 74, 230, 30, 177, 4, 10, 203, 32, 4, 77, 62, 249, 18, 142, 212, 1, 1522 48, 121, 91, 212, 189, 59, 65, 238, 202, 208, 102, 171, 101, 25, 129, 1523 253, 228, 141, 247, 127, 55, 45, 195, 139, 159, 175, 221, 59, 239, 1524 177, 139, 93, 163, 204, 60, 46, 176, 47, 158, 58, 65, 214, 18, 202, 1525 173, 21, 145, 18, 115, 160, 95, 35, 185, 232, 56, 250, 175, 132, 157, 1526 105, 132, 41, 239, 90, 30, 136, 121, 130, 54, 195, 212, 14, 96, 69, 1527 34, 165, 68, 200, 242, 122, 122, 45, 184, 6, 99, 209, 108, 247, 202, 1528 234, 86, 222, 64, 92, 178, 33, 90, 69, 178, 194, 85, 102, 181, 90, 1529 193, 167, 72, 160, 112, 223, 200, 163, 42, 70, 149, 67, 208, 25, 238, 1530 251, 71] 1532 Base64url encoding the digital signature produces this value for the 1533 Encoded JWS Signature (with line breaks for display purposes only): 1535 cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7 1536 AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4 1537 BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K 1538 0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqv 1539 hJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrB 1540 p0igcN_IoypGlUPQGe77Rw 1542 Concatenating these values in the order Header.Payload.Signature with 1543 period ('.') characters between the parts yields this complete JWS 1544 representation using the JWS Compact Serialization (with line breaks 1545 for display purposes only): 1547 eyJhbGciOiJSUzI1NiJ9 1548 . 1549 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1550 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1551 . 1552 cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7 1553 AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4 1554 BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K 1555 0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqv 1556 hJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrB 1557 p0igcN_IoypGlUPQGe77Rw 1559 A.2.2. Decoding 1561 Decoding the JWS requires base64url decoding the Encoded JWS Header, 1562 Encoded JWS Payload, and Encoded JWS Signature to produce the JWS 1563 Header, JWS Payload, and JWS Signature octet sequences. The octet 1564 sequence containing the UTF-8 representation of the JWS Header is 1565 decoded into the JWS Header string. 1567 A.2.3. Validating 1569 Since the "alg" parameter in the header is "RS256", we validate the 1570 RSASSA-PKCS-v1_5 SHA-256 digital signature contained in the JWS 1571 Signature. 1573 First, we validate that the JWS Header string is legal JSON. 1575 Validating the JWS Signature is a little different from the previous 1576 example. First, we base64url decode the Encoded JWS Signature to 1577 produce a digital signature S to check. We then pass (n, e), S and 1578 the octets of the ASCII representation of the JWS Signing Input to an 1579 RSASSA-PKCS-v1_5 signature verifier that has been configured to use 1580 the SHA-256 hash function. 1582 A.3. Example JWS using ECDSA P-256 SHA-256 1584 A.3.1. Encoding 1586 The JWS Header for this example differs from the previous example 1587 because a different algorithm is being used. The JWS Header used is: 1589 {"alg":"ES256"} 1591 The following octet sequence contains the UTF-8 representation of the 1592 JWS Header: 1594 [123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 50, 53, 54, 34, 125] 1595 Base64url encoding these octets yields this Encoded JWS Header value: 1597 eyJhbGciOiJFUzI1NiJ9 1599 The JWS Payload used in this example, which follows, is the same as 1600 in the previous examples. Since the Encoded JWS Payload will 1601 therefore be the same, its computation is not repeated here. 1603 {"iss":"joe", 1604 "exp":1300819380, 1605 "http://example.com/is_root":true} 1607 Concatenating the Encoded JWS Header, a period ('.') character, and 1608 the Encoded JWS Payload yields this JWS Signing Input value (with 1609 line breaks for display purposes only): 1611 eyJhbGciOiJFUzI1NiJ9 1612 . 1613 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1614 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1616 The ASCII representation of the JWS Signing Input is the following 1617 octet sequence: 1619 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 70, 85, 122, 73, 1620 49, 78, 105, 74, 57, 46, 101, 121, 74, 112, 99, 51, 77, 105, 79, 105, 1621 74, 113, 98, 50, 85, 105, 76, 65, 48, 75, 73, 67, 74, 108, 101, 72, 1622 65, 105, 79, 106, 69, 122, 77, 68, 65, 52, 77, 84, 107, 122, 79, 68, 1623 65, 115, 68, 81, 111, 103, 73, 109, 104, 48, 100, 72, 65, 54, 76, 1624 121, 57, 108, 101, 71, 70, 116, 99, 71, 120, 108, 76, 109, 78, 118, 1625 98, 83, 57, 112, 99, 49, 57, 121, 98, 50, 57, 48, 73, 106, 112, 48, 1626 99, 110, 86, 108, 102, 81] 1628 This example uses the elliptic curve key represented in JSON Web Key 1629 [JWK] format below: 1631 {"kty":"EC", 1632 "crv":"P-256", 1633 "x":"f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU", 1634 "y":"x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0", 1635 "d":"jpsQnnGQmL-YBIffH1136cspYG6-0iY7X1fCE9-E9LI" 1636 } 1638 The ECDSA private part d is then passed to an ECDSA signing function, 1639 which also takes the curve type, P-256, the hash type, SHA-256, and 1640 the octets of the ASCII representation of the JWS Signing Input as 1641 inputs. The result of the digital signature is the EC point (R, S), 1642 where R and S are unsigned integers. In this example, the R and S 1643 values, given as octet sequences representing big endian integers 1644 are: 1646 +--------+----------------------------------------------------------+ 1647 | Result | Value | 1648 | Name | | 1649 +--------+----------------------------------------------------------+ 1650 | R | [14, 209, 33, 83, 121, 99, 108, 72, 60, 47, 127, 21, 88, | 1651 | | 7, 212, 2, 163, 178, 40, 3, 58, 249, 124, 126, 23, 129, | 1652 | | 154, 195, 22, 158, 166, 101] | 1653 | S | [197, 10, 7, 211, 140, 60, 112, 229, 216, 241, 45, 175, | 1654 | | 8, 74, 84, 128, 166, 101, 144, 197, 242, 147, 80, 154, | 1655 | | 143, 63, 127, 138, 131, 163, 84, 213] | 1656 +--------+----------------------------------------------------------+ 1658 Concatenating the S array to the end of the R array and base64url 1659 encoding the result produces this value for the Encoded JWS Signature 1660 (with line breaks for display purposes only): 1662 DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSA 1663 pmWQxfKTUJqPP3-Kg6NU1Q 1665 Concatenating these values in the order Header.Payload.Signature with 1666 period ('.') characters between the parts yields this complete JWS 1667 representation using the JWS Compact Serialization (with line breaks 1668 for display purposes only): 1670 eyJhbGciOiJFUzI1NiJ9 1671 . 1672 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1673 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1674 . 1675 DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSA 1676 pmWQxfKTUJqPP3-Kg6NU1Q 1678 A.3.2. Decoding 1680 Decoding the JWS requires base64url decoding the Encoded JWS Header, 1681 Encoded JWS Payload, and Encoded JWS Signature to produce the JWS 1682 Header, JWS Payload, and JWS Signature octet sequences. The octet 1683 sequence containing the UTF-8 representation of the JWS Header is 1684 decoded into the JWS Header string. 1686 A.3.3. Validating 1688 Since the "alg" parameter in the header is "ES256", we validate the 1689 ECDSA P-256 SHA-256 digital signature contained in the JWS Signature. 1691 First, we validate that the JWS Header string is legal JSON. 1693 Validating the JWS Signature is a little different from the first 1694 example. First, we base64url decode the Encoded JWS Signature as in 1695 the previous examples but we then need to split the 64 member octet 1696 sequence that must result into two 32 octet sequences, the first R 1697 and the second S. We then pass (x, y), (R, S) and the octets of the 1698 ASCII representation of the JWS Signing Input to an ECDSA signature 1699 verifier that has been configured to use the P-256 curve with the 1700 SHA-256 hash function. 1702 A.4. Example JWS using ECDSA P-521 SHA-512 1704 A.4.1. Encoding 1706 The JWS Header for this example differs from the previous example 1707 because different ECDSA curves and hash functions are used. The JWS 1708 Header used is: 1710 {"alg":"ES512"} 1712 The following octet sequence contains the UTF-8 representation of the 1713 JWS Header: 1715 [123, 34, 97, 108, 103, 34, 58, 34, 69, 83, 53, 49, 50, 34, 125] 1717 Base64url encoding these octets yields this Encoded JWS Header value: 1719 eyJhbGciOiJFUzUxMiJ9 1721 The JWS Payload used in this example, is the ASCII string "Payload". 1722 The representation of this string is the octet sequence: 1724 [80, 97, 121, 108, 111, 97, 100] 1726 Base64url encoding these octets yields this Encoded JWS Payload 1727 value: 1729 UGF5bG9hZA 1731 Concatenating the Encoded JWS Header, a period ('.') character, and 1732 the Encoded JWS Payload yields this JWS Signing Input value: 1734 eyJhbGciOiJFUzUxMiJ9.UGF5bG9hZA 1736 The ASCII representation of the JWS Signing Input is the following 1737 octet sequence: 1739 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 70, 85, 122, 85, 1740 120, 77, 105, 74, 57, 46, 85, 71, 70, 53, 98, 71, 57, 104, 90, 65] 1742 This example uses the elliptic curve key represented in JSON Web Key 1743 [JWK] format below (with line breaks for display purposes only): 1745 {"kty":"EC", 1746 "crv":"P-521", 1747 "x":"AekpBQ8ST8a8VcfVOTNl353vSrDCLLJXmPk06wTjxrrjcBpXp5EOnYG_ 1748 NjFZ6OvLFV1jSfS9tsz4qUxcWceqwQGk", 1749 "y":"ADSmRA43Z1DSNx_RvcLI87cdL07l6jQyyBXMoxVg_l2Th-x3S1WDhjDl 1750 y79ajL4Kkd0AZMaZmh9ubmf63e3kyMj2", 1751 "d":"AY5pb7A0UFiB3RELSD64fTLOSV_jazdF7fLYyuTw8lOfRhWg6Y6rUrPA 1752 xerEzgdRhajnu0ferB0d53vM9mE15j2C" 1753 } 1755 The ECDSA private part d is then passed to an ECDSA signing function, 1756 which also takes the curve type, P-521, the hash type, SHA-512, and 1757 the octets of the ASCII representation of the JWS Signing Input as 1758 inputs. The result of the digital signature is the EC point (R, S), 1759 where R and S are unsigned integers. In this example, the R and S 1760 values, given as octet sequences representing big endian integers 1761 are: 1763 +--------+----------------------------------------------------------+ 1764 | Result | Value | 1765 | Name | | 1766 +--------+----------------------------------------------------------+ 1767 | R | [1, 220, 12, 129, 231, 171, 194, 209, 232, 135, 233, | 1768 | | 117, 247, 105, 122, 210, 26, 125, 192, 1, 217, 21, 82, | 1769 | | 91, 45, 240, 255, 83, 19, 34, 239, 71, 48, 157, 147, | 1770 | | 152, 105, 18, 53, 108, 163, 214, 68, 231, 62, 153, 150, | 1771 | | 106, 194, 164, 246, 72, 143, 138, 24, 50, 129, 223, 133, | 1772 | | 206, 209, 172, 63, 237, 119, 109] | 1773 | S | [0, 111, 6, 105, 44, 5, 41, 208, 128, 61, 152, 40, 92, | 1774 | | 61, 152, 4, 150, 66, 60, 69, 247, 196, 170, 81, 193, | 1775 | | 199, 78, 59, 194, 169, 16, 124, 9, 143, 42, 142, 131, | 1776 | | 48, 206, 238, 34, 175, 83, 203, 220, 159, 3, 107, 155, | 1777 | | 22, 27, 73, 111, 68, 68, 21, 238, 144, 229, 232, 148, | 1778 | | 188, 222, 59, 242, 103] | 1779 +--------+----------------------------------------------------------+ 1781 Concatenating the S array to the end of the R array and base64url 1782 encoding the result produces this value for the Encoded JWS Signature 1783 (with line breaks for display purposes only): 1785 AdwMgeerwtHoh-l192l60hp9wAHZFVJbLfD_UxMi70cwnZOYaRI1bKPWROc-mZZq 1786 wqT2SI-KGDKB34XO0aw_7XdtAG8GaSwFKdCAPZgoXD2YBJZCPEX3xKpRwcdOO8Kp 1787 EHwJjyqOgzDO7iKvU8vcnwNrmxYbSW9ERBXukOXolLzeO_Jn 1789 Concatenating these values in the order Header.Payload.Signature with 1790 period ('.') characters between the parts yields this complete JWS 1791 representation using the JWS Compact Serialization (with line breaks 1792 for display purposes only): 1794 eyJhbGciOiJFUzUxMiJ9 1795 . 1796 UGF5bG9hZA 1797 . 1798 AdwMgeerwtHoh-l192l60hp9wAHZFVJbLfD_UxMi70cwnZOYaRI1bKPWROc-mZZq 1799 wqT2SI-KGDKB34XO0aw_7XdtAG8GaSwFKdCAPZgoXD2YBJZCPEX3xKpRwcdOO8Kp 1800 EHwJjyqOgzDO7iKvU8vcnwNrmxYbSW9ERBXukOXolLzeO_Jn 1802 A.4.2. Decoding 1804 Decoding the JWS requires base64url decoding the Encoded JWS Header, 1805 Encoded JWS Payload, and Encoded JWS Signature to produce the JWS 1806 Header, JWS Payload, and JWS Signature octet sequences. The octet 1807 sequence containing the UTF-8 representation of the JWS Header is 1808 decoded into the JWS Header string. 1810 A.4.3. Validating 1812 Since the "alg" parameter in the header is "ES512", we validate the 1813 ECDSA P-521 SHA-512 digital signature contained in the JWS Signature. 1815 First, we validate that the JWS Header string is legal JSON. 1817 Validating the JWS Signature is similar to the previous example. 1818 First, we base64url decode the Encoded JWS Signature as in the 1819 previous examples but we then need to split the 132 member octet 1820 sequence that must result into two 66 octet sequences, the first R 1821 and the second S. We then pass (x, y), (R, S) and the octets of the 1822 ASCII representation of the JWS Signing Input to an ECDSA signature 1823 verifier that has been configured to use the P-521 curve with the 1824 SHA-512 hash function. 1826 A.5. Example Plaintext JWS 1828 The following example JWS Header declares that the encoded object is 1829 a Plaintext JWS: 1831 {"alg":"none"} 1833 Base64url encoding the octets of the UTF-8 representation of the JWS 1834 Header yields this Encoded JWS Header: 1836 eyJhbGciOiJub25lIn0 1838 The JWS Payload used in this example, which follows, is the same as 1839 in the previous examples. Since the Encoded JWS Payload will 1840 therefore be the same, its computation is not repeated here. 1842 {"iss":"joe", 1843 "exp":1300819380, 1844 "http://example.com/is_root":true} 1846 The Encoded JWS Signature is the empty string. 1848 Concatenating these parts in the order Header.Payload.Signature with 1849 period ('.') characters between the parts yields this complete JWS 1850 (with line breaks for display purposes only): 1852 eyJhbGciOiJub25lIn0 1853 . 1854 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1855 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1856 . 1858 A.6. Example JWS Using JWS JSON Serialization 1860 This section contains an example using the JWS JSON Serialization. 1861 This example demonstrates the capability for conveying multiple 1862 digital signatures and/or MACs for the same payload. 1864 The Encoded JWS Payload used in this example is the same as that used 1865 in the examples in Appendix A.2 and Appendix A.3 (with line breaks 1866 for display purposes only): 1868 eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt 1869 cGxlLmNvbS9pc19yb290Ijp0cnVlfQ 1871 Two digital signatures are used in this example: the first using 1872 RSASSA-PKCS-v1_5 SHA-256 and the second using ECDSA P-256 SHA-256. 1873 For the first, the JWS Protected Header and key are the same as in 1874 Appendix A.2, resulting in the same JWS Signature value; therefore, 1875 its computation is not repeated here. For the second, the JWS 1876 Protected Header and key are the same as in Appendix A.3, resulting 1877 in the same JWS Signature value; therefore, its computation is not 1878 repeated here. 1880 A.6.1. JWS Per-Signature Protected Headers 1882 The JWS Protected Header value used for the first signature is: 1884 {"alg":"RS256"} 1886 Base64url encoding these octets yields this Encoded JWS Header value: 1888 eyJhbGciOiJSUzI1NiJ9 1890 The JWS Protected Header value used for the second signature is: 1892 {"alg":"ES256"} 1894 Base64url encoding these octets yields this Encoded JWS Header value: 1896 eyJhbGciOiJFUzI1NiJ9 1898 A.6.2. JWS Per-Signature Unprotected Headers 1900 Key ID values are supplied for both keys using per-signature header 1901 parameters. The two values used to represent these Key IDs are: 1903 {"kid":"2010-12-29"} 1905 and 1907 {"kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"} 1909 A.6.3. Complete JWS Header Values 1911 Combining the protected and unprotected header values supplied, the 1912 JWS Header values used for the first and second signatures 1913 respectively are: 1915 {"alg":"RS256", 1916 "kid":"2010-12-29"} 1918 and 1920 {"alg":"ES256", 1921 "kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"} 1923 A.6.4. Complete JWS JSON Serialization Representation 1925 The complete JSON Web Signature JSON Serialization for these values 1926 is as follows (with line breaks for display purposes only): 1928 {"payload": 1929 "eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGF 1930 tcGxlLmNvbS9pc19yb290Ijp0cnVlfQ", 1931 "signatures":[ 1932 {"protected":"eyJhbGciOiJSUzI1NiJ9", 1933 "header": 1934 {"kid":"2010-12-29"}, 1935 "signature": 1936 "cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZ 1937 mh7AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjb 1938 KBYNX4BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHl 1939 b1L07Qe7K0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZES 1940 c6BfI7noOPqvhJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AX 1941 LIhWkWywlVmtVrBp0igcN_IoypGlUPQGe77Rw"}, 1942 {"protected":"eyJhbGciOiJFUzI1NiJ9", 1943 "header": 1944 {"kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"}, 1945 "signature": 1946 "DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8IS 1947 lSApmWQxfKTUJqPP3-Kg6NU1Q"}] 1948 } 1950 Appendix B. "x5c" (X.509 Certificate Chain) Example 1952 The JSON array below is an example of a certificate chain that could 1953 be used as the value of an "x5c" (X.509 Certificate Chain) header 1954 parameter, per Section 4.1.6. Note that since these strings contain 1955 base64 encoded (not base64url encoded) values, they are allowed to 1956 contain white space and line breaks. 1958 ["MIIE3jCCA8agAwIBAgICAwEwDQYJKoZIhvcNAQEFBQAwYzELMAkGA1UEBhMCVVM 1959 xITAfBgNVBAoTGFRoZSBHbyBEYWRkeSBHcm91cCwgSW5jLjExMC8GA1UECxMoR2 1960 8gRGFkZHkgQ2xhc3MgMiBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTAeFw0wNjExM 1961 TYwMTU0MzdaFw0yNjExMTYwMTU0MzdaMIHKMQswCQYDVQQGEwJVUzEQMA4GA1UE 1962 CBMHQXJpem9uYTETMBEGA1UEBxMKU2NvdHRzZGFsZTEaMBgGA1UEChMRR29EYWR 1963 keS5jb20sIEluYy4xMzAxBgNVBAsTKmh0dHA6Ly9jZXJ0aWZpY2F0ZXMuZ29kYW 1964 RkeS5jb20vcmVwb3NpdG9yeTEwMC4GA1UEAxMnR28gRGFkZHkgU2VjdXJlIENlc 1965 nRpZmljYXRpb24gQXV0aG9yaXR5MREwDwYDVQQFEwgwNzk2OTI4NzCCASIwDQYJ 1966 KoZIhvcNAQEBBQADggEPADCCAQoCggEBAMQt1RWMnCZM7DI161+4WQFapmGBWTt 1967 wY6vj3D3HKrjJM9N55DrtPDAjhI6zMBS2sofDPZVUBJ7fmd0LJR4h3mUpfjWoqV 1968 Tr9vcyOdQmVZWt7/v+WIbXnvQAjYwqDL1CBM6nPwT27oDyqu9SoWlm2r4arV3aL 1969 GbqGmu75RpRSgAvSMeYddi5Kcju+GZtCpyz8/x4fKL4o/K1w/O5epHBp+YlLpyo 1970 7RJlbmr2EkRTcDCVw5wrWCs9CHRK8r5RsL+H0EwnWGu1NcWdrxcx+AuP7q2BNgW 1971 JCJjPOq8lh8BJ6qf9Z/dFjpfMFDniNoW1fho3/Rb2cRGadDAW/hOUoz+EDU8CAw 1972 EAAaOCATIwggEuMB0GA1UdDgQWBBT9rGEyk2xF1uLuhV+auud2mWjM5zAfBgNVH 1973 SMEGDAWgBTSxLDSkdRMEXGzYcs9of7dqGrU4zASBgNVHRMBAf8ECDAGAQH/AgEA 1974 MDMGCCsGAQUFBwEBBCcwJTAjBggrBgEFBQcwAYYXaHR0cDovL29jc3AuZ29kYWR 1975 keS5jb20wRgYDVR0fBD8wPTA7oDmgN4Y1aHR0cDovL2NlcnRpZmljYXRlcy5nb2 1976 RhZGR5LmNvbS9yZXBvc2l0b3J5L2dkcm9vdC5jcmwwSwYDVR0gBEQwQjBABgRVH 1977 SAAMDgwNgYIKwYBBQUHAgEWKmh0dHA6Ly9jZXJ0aWZpY2F0ZXMuZ29kYWRkeS5j 1978 b20vcmVwb3NpdG9yeTAOBgNVHQ8BAf8EBAMCAQYwDQYJKoZIhvcNAQEFBQADggE 1979 BANKGwOy9+aG2Z+5mC6IGOgRQjhVyrEp0lVPLN8tESe8HkGsz2ZbwlFalEzAFPI 1980 UyIXvJxwqoJKSQ3kbTJSMUA2fCENZvD117esyfxVgqwcSeIaha86ykRvOe5GPLL 1981 5CkKSkB2XIsKd83ASe8T+5o0yGPwLPk9Qnt0hCqU7S+8MxZC9Y7lhyVJEnfzuz9 1982 p0iRFEUOOjZv2kWzRaJBydTXRE4+uXR21aITVSzGh6O1mawGhId/dQb8vxRMDsx 1983 uxN89txJx9OjxUUAiKEngHUuHqDTMBqLdElrRhjZkAzVvb3du6/KFUJheqwNTrZ 1984 EjYx8WnM25sgVjOuH0aBsXBTWVU+4=", 1985 "MIIE+zCCBGSgAwIBAgICAQ0wDQYJKoZIhvcNAQEFBQAwgbsxJDAiBgNVBAcTG1Z 1986 hbGlDZXJ0IFZhbGlkYXRpb24gTmV0d29yazEXMBUGA1UEChMOVmFsaUNlcnQsIE 1987 luYy4xNTAzBgNVBAsTLFZhbGlDZXJ0IENsYXNzIDIgUG9saWN5IFZhbGlkYXRpb 1988 24gQXV0aG9yaXR5MSEwHwYDVQQDExhodHRwOi8vd3d3LnZhbGljZXJ0LmNvbS8x 1989 IDAeBgkqhkiG9w0BCQEWEWluZm9AdmFsaWNlcnQuY29tMB4XDTA0MDYyOTE3MDY 1990 yMFoXDTI0MDYyOTE3MDYyMFowYzELMAkGA1UEBhMCVVMxITAfBgNVBAoTGFRoZS 1991 BHbyBEYWRkeSBHcm91cCwgSW5jLjExMC8GA1UECxMoR28gRGFkZHkgQ2xhc3MgM 1992 iBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTCCASAwDQYJKoZIhvcNAQEBBQADggEN 1993 ADCCAQgCggEBAN6d1+pXGEmhW+vXX0iG6r7d/+TvZxz0ZWizV3GgXne77ZtJ6XC 1994 APVYYYwhv2vLM0D9/AlQiVBDYsoHUwHU9S3/Hd8M+eKsaA7Ugay9qK7HFiH7Eux 1995 6wwdhFJ2+qN1j3hybX2C32qRe3H3I2TqYXP2WYktsqbl2i/ojgC95/5Y0V4evLO 1996 tXiEqITLdiOr18SPaAIBQi2XKVlOARFmR6jYGB0xUGlcmIbYsUfb18aQr4CUWWo 1997 riMYavx4A6lNf4DD+qta/KFApMoZFv6yyO9ecw3ud72a9nmYvLEHZ6IVDd2gWMZ 1998 Eewo+YihfukEHU1jPEX44dMX4/7VpkI+EdOqXG68CAQOjggHhMIIB3TAdBgNVHQ 1999 4EFgQU0sSw0pHUTBFxs2HLPaH+3ahq1OMwgdIGA1UdIwSByjCBx6GBwaSBvjCBu 2000 zEkMCIGA1UEBxMbVmFsaUNlcnQgVmFsaWRhdGlvbiBOZXR3b3JrMRcwFQYDVQQK 2001 Ew5WYWxpQ2VydCwgSW5jLjE1MDMGA1UECxMsVmFsaUNlcnQgQ2xhc3MgMiBQb2x 2002 pY3kgVmFsaWRhdGlvbiBBdXRob3JpdHkxITAfBgNVBAMTGGh0dHA6Ly93d3cudm 2003 FsaWNlcnQuY29tLzEgMB4GCSqGSIb3DQEJARYRaW5mb0B2YWxpY2VydC5jb22CA 2004 QEwDwYDVR0TAQH/BAUwAwEB/zAzBggrBgEFBQcBAQQnMCUwIwYIKwYBBQUHMAGG 2005 F2h0dHA6Ly9vY3NwLmdvZGFkZHkuY29tMEQGA1UdHwQ9MDswOaA3oDWGM2h0dHA 2006 6Ly9jZXJ0aWZpY2F0ZXMuZ29kYWRkeS5jb20vcmVwb3NpdG9yeS9yb290LmNybD 2007 BLBgNVHSAERDBCMEAGBFUdIAAwODA2BggrBgEFBQcCARYqaHR0cDovL2NlcnRpZ 2008 mljYXRlcy5nb2RhZGR5LmNvbS9yZXBvc2l0b3J5MA4GA1UdDwEB/wQEAwIBBjAN 2009 BgkqhkiG9w0BAQUFAAOBgQC1QPmnHfbq/qQaQlpE9xXUhUaJwL6e4+PrxeNYiY+ 2010 Sn1eocSxI0YGyeR+sBjUZsE4OWBsUs5iB0QQeyAfJg594RAoYC5jcdnplDQ1tgM 2011 QLARzLrUc+cb53S8wGd9D0VmsfSxOaFIqII6hR8INMqzW/Rn453HWkrugp++85j 2012 09VZw==", 2013 "MIIC5zCCAlACAQEwDQYJKoZIhvcNAQEFBQAwgbsxJDAiBgNVBAcTG1ZhbGlDZXJ 2014 0IFZhbGlkYXRpb24gTmV0d29yazEXMBUGA1UEChMOVmFsaUNlcnQsIEluYy4xNT 2015 AzBgNVBAsTLFZhbGlDZXJ0IENsYXNzIDIgUG9saWN5IFZhbGlkYXRpb24gQXV0a 2016 G9yaXR5MSEwHwYDVQQDExhodHRwOi8vd3d3LnZhbGljZXJ0LmNvbS8xIDAeBgkq 2017 hkiG9w0BCQEWEWluZm9AdmFsaWNlcnQuY29tMB4XDTk5MDYyNjAwMTk1NFoXDTE 2018 5MDYyNjAwMTk1NFowgbsxJDAiBgNVBAcTG1ZhbGlDZXJ0IFZhbGlkYXRpb24gTm 2019 V0d29yazEXMBUGA1UEChMOVmFsaUNlcnQsIEluYy4xNTAzBgNVBAsTLFZhbGlDZ 2020 XJ0IENsYXNzIDIgUG9saWN5IFZhbGlkYXRpb24gQXV0aG9yaXR5MSEwHwYDVQQD 2021 ExhodHRwOi8vd3d3LnZhbGljZXJ0LmNvbS8xIDAeBgkqhkiG9w0BCQEWEWluZm9 2022 AdmFsaWNlcnQuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDOOnHK5a 2023 vIWZJV16vYdA757tn2VUdZZUcOBVXc65g2PFxTXdMwzzjsvUGJ7SVCCSRrCl6zf 2024 N1SLUzm1NZ9WlmpZdRJEy0kTRxQb7XBhVQ7/nHk01xC+YDgkRoKWzk2Z/M/VXwb 2025 P7RfZHM047QSv4dk+NoS/zcnwbNDu+97bi5p9wIDAQABMA0GCSqGSIb3DQEBBQU 2026 AA4GBADt/UG9vUJSZSWI4OB9L+KXIPqeCgfYrx+jFzug6EILLGACOTb2oWH+heQ 2027 C1u+mNr0HZDzTuIYEZoDJJKPTEjlbVUjP9UNV+mWwD5MlM/Mtsq2azSiGM5bUMM 2028 j4QssxsodyamEwCW/POuZ6lcg5Ktz885hZo+L7tdEy8W9ViH0Pd"] 2030 Appendix C. Notes on implementing base64url encoding without padding 2032 This appendix describes how to implement base64url encoding and 2033 decoding functions without padding based upon standard base64 2034 encoding and decoding functions that do use padding. 2036 To be concrete, example C# code implementing these functions is shown 2037 below. Similar code could be used in other languages. 2039 static string base64urlencode(byte [] arg) 2040 { 2041 string s = Convert.ToBase64String(arg); // Regular base64 encoder 2042 s = s.Split('=')[0]; // Remove any trailing '='s 2043 s = s.Replace('+', '-'); // 62nd char of encoding 2044 s = s.Replace('/', '_'); // 63rd char of encoding 2045 return s; 2046 } 2048 static byte [] base64urldecode(string arg) 2049 { 2050 string s = arg; 2051 s = s.Replace('-', '+'); // 62nd char of encoding 2052 s = s.Replace('_', '/'); // 63rd char of encoding 2053 switch (s.Length % 4) // Pad with trailing '='s 2054 { 2055 case 0: break; // No pad chars in this case 2056 case 2: s += "=="; break; // Two pad chars 2057 case 3: s += "="; break; // One pad char 2058 default: throw new System.Exception( 2059 "Illegal base64url string!"); 2060 } 2061 return Convert.FromBase64String(s); // Standard base64 decoder 2062 } 2064 As per the example code above, the number of '=' padding characters 2065 that needs to be added to the end of a base64url encoded string 2066 without padding to turn it into one with padding is a deterministic 2067 function of the length of the encoded string. Specifically, if the 2068 length mod 4 is 0, no padding is added; if the length mod 4 is 2, two 2069 '=' padding characters are added; if the length mod 4 is 3, one '=' 2070 padding character is added; if the length mod 4 is 1, the input is 2071 malformed. 2073 An example correspondence between unencoded and encoded values 2074 follows. The octet sequence below encodes into the string below, 2075 which when decoded, reproduces the octet sequence. 2076 3 236 255 224 193 2077 A-z_4ME 2079 Appendix D. Negative Test Case for "crit" Header Parameter 2081 Conforming implementations must reject input containing critical 2082 extensions that are not understood or cannot be processed. The 2083 following JWS must be rejected by all implementations, because it 2084 uses an extension header parameter name 2085 "http://example.invalid/UNDEFINED" that they do not understand. Any 2086 other similar input, in which the use of the value 2087 "http://example.invalid/UNDEFINED" is substituted for any other 2088 header parameter name not understood by the implementation, must also 2089 be rejected. 2091 The JWS Header value for this JWS is: 2093 {"alg":"none", 2094 "crit":["http://example.invalid/UNDEFINED"], 2095 "http://example.invalid/UNDEFINED":true 2096 } 2098 The complete JWS that must be rejected is as follows (with line 2099 breaks for display purposes only): 2101 eyJhbGciOiJub25lIiwNCiAiY3JpdCI6WyJodHRwOi8vZXhhbXBsZS5jb20vVU5ERU 2102 ZJTkVEIl0sDQogImh0dHA6Ly9leGFtcGxlLmNvbS9VTkRFRklORUQiOnRydWUNCn0. 2103 RkFJTA. 2105 Appendix E. Acknowledgements 2107 Solutions for signing JSON content were previously explored by Magic 2108 Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas 2109 Applications [CanvasApp], all of which influenced this draft. 2111 Thanks to Axel Nennker for his early implementation and feedback on 2112 the JWS and JWE specifications. 2114 This specification is the work of the JOSE Working Group, which 2115 includes dozens of active and dedicated participants. In particular, 2116 the following individuals contributed ideas, feedback, and wording 2117 that influenced this specification: 2119 Dirk Balfanz, Richard Barnes, Brian Campbell, Breno de Medeiros, Dick 2120 Hardt, Joe Hildebrand, Jeff Hodges, Edmund Jay, Yaron Y. Goland, Ben 2121 Laurie, James Manger, Matt Miller, Tony Nadalin, Axel Nennker, John 2122 Panzer, Emmanuel Raviart, Eric Rescorla, Jim Schaad, Paul Tarjan, 2123 Hannes Tschofenig, and Sean Turner. 2125 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2126 Sean Turner and Stephen Farrell served as Security area directors 2127 during the creation of this specification. 2129 Appendix F. Document History 2131 [[ to be removed by the RFC Editor before publication as an RFC ]] 2133 -16 2135 o Changes to address editorial and minor issues #50, #98, #99, #102, 2136 #104, #106, #107, #111, and #112. 2138 -15 2140 o Clarified that it is an application decision which signatures, 2141 MACs, or plaintext values must successfully validate for the JWS 2142 to be accepted, addressing issue #35. 2144 o Corrected editorial error in "ES512" example. 2146 o Changes to address editorial and minor issues #34, #96, #100, 2147 #101, #104, #105, and #106. 2149 -14 2151 o Stated that the "signature" parameter is to be omitted in the JWS 2152 JSON Serialization when its value would be empty (which is only 2153 the case for a Plaintext JWS). 2155 -13 2157 o Made all header parameter values be per-signature/MAC, addressing 2158 issue #24. 2160 -12 2161 o Clarified that the "typ" and "cty" header parameters are used in 2162 an application-specific manner and have no effect upon the JWS 2163 processing. 2165 o Replaced the MIME types "application/jws+json" and 2166 "application/jws" with "application/jose+json" and 2167 "application/jose". 2169 o Stated that recipients MUST either reject JWSs with duplicate 2170 Header Parameter Names or use a JSON parser that returns only the 2171 lexically last duplicate member name. 2173 o Added a Serializations section with parallel treatment of the JWS 2174 Compact Serialization and the JWS JSON Serialization and also 2175 moved the former Implementation Considerations content there. 2177 -11 2179 o Added Key Identification section. 2181 o For the JWS JSON Serialization, enable header parameter values to 2182 be specified in any of three parameters: the "protected" member 2183 that is integrity protected and shared among all recipients, the 2184 "unprotected" member that is not integrity protected and shared 2185 among all recipients, and the "header" member that is not 2186 integrity protected and specific to a particular recipient. (This 2187 does not affect the JWS Compact Serialization, in which all header 2188 parameter values are in a single integrity protected JWE Header 2189 value.) 2191 o Removed suggested compact serialization for multiple digital 2192 signatures and/or MACs. 2194 o Changed the MIME type name "application/jws-js" to 2195 "application/jws+json", addressing issue #22. 2197 o Tightened the description of the "crit" (critical) header 2198 parameter. 2200 o Added a negative test case for the "crit" header parameter 2202 -10 2204 o Added an appendix suggesting a possible compact serialization for 2205 JWSs with multiple digital signatures and/or MACs. 2207 -09 2208 o Added JWS JSON Serialization, as specified by 2209 draft-jones-jose-jws-json-serialization-04. 2211 o Registered "application/jws-js" MIME type and "JWS-JS" typ header 2212 parameter value. 2214 o Defined that the default action for header parameters that are not 2215 understood is to ignore them unless specifically designated as 2216 "MUST be understood" or included in the new "crit" (critical) 2217 header parameter list. This addressed issue #6. 2219 o Changed term "JWS Secured Input" to "JWS Signing Input". 2221 o Changed from using the term "byte" to "octet" when referring to 8 2222 bit values. 2224 o Changed member name from "recipients" to "signatures" in the JWS 2225 JSON Serialization. 2227 o Added complete values using the JWS Compact Serialization for all 2228 examples. 2230 -08 2232 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2233 Tschofenig. Many of these simplified the terminology used. 2235 o Clarified statements of the form "This header parameter is 2236 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2238 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2239 Web Signature and Encryption Header Parameters registry. 2241 o Added seriesInfo information to Internet Draft references. 2243 -07 2245 o Updated references. 2247 -06 2249 o Changed "x5c" (X.509 Certificate Chain) representation from being 2250 a single string to being an array of strings, each containing a 2251 single base64 encoded DER certificate value, representing elements 2252 of the certificate chain. 2254 o Applied changes made by the RFC Editor to RFC 6749's registry 2255 language to this specification. 2257 -05 2259 o Added statement that "StringOrURI values are compared as case- 2260 sensitive strings with no transformations or canonicalizations 2261 applied". 2263 o Indented artwork elements to better distinguish them from the body 2264 text. 2266 -04 2268 o Completed JSON Security Considerations section, including 2269 considerations about rejecting input with duplicate member names. 2271 o Completed security considerations on the use of a SHA-1 hash when 2272 computing "x5t" (x.509 certificate thumbprint) values. 2274 o Refer to the registries as the primary sources of defined values 2275 and then secondarily reference the sections defining the initial 2276 contents of the registries. 2278 o Normatively reference XML DSIG 2.0 [W3C.CR-xmldsig-core2-20120124] 2279 for its security considerations. 2281 o Added this language to Registration Templates: "This name is case 2282 sensitive. Names that match other registered names in a case 2283 insensitive manner SHOULD NOT be accepted." 2285 o Reference draft-jones-jose-jws-json-serialization instead of 2286 draft-jones-json-web-signature-json-serialization. 2288 o Described additional open issues. 2290 o Applied editorial suggestions. 2292 -03 2294 o Added the "cty" (content type) header parameter for declaring type 2295 information about the secured content, as opposed to the "typ" 2296 (type) header parameter, which declares type information about 2297 this object. 2299 o Added "Collision Resistant Namespace" to the terminology section. 2301 o Reference ITU.X690.1994 for DER encoding. 2303 o Added an example JWS using ECDSA P-521 SHA-512. This has 2304 particular illustrative value because of the use of the 521 bit 2305 integers in the key and signature values. This is also an example 2306 in which the payload is not a base64url encoded JSON object. 2308 o Added an example "x5c" value. 2310 o No longer say "the UTF-8 representation of the JWS Secured Input 2311 (which is the same as the ASCII representation)". Just call it 2312 "the ASCII representation of the JWS Secured Input". 2314 o Added Registration Template sections for defined registries. 2316 o Added Registry Contents sections to populate registry values. 2318 o Changed name of the JSON Web Signature and Encryption "typ" Values 2319 registry to be the JSON Web Signature and Encryption Type Values 2320 registry, since it is used for more than just values of the "typ" 2321 parameter. 2323 o Moved registries JSON Web Signature and Encryption Header 2324 Parameters and JSON Web Signature and Encryption Type Values to 2325 the JWS specification. 2327 o Numerous editorial improvements. 2329 -02 2331 o Clarified that it is an error when a "kid" value is included and 2332 no matching key is found. 2334 o Removed assumption that "kid" (key ID) can only refer to an 2335 asymmetric key. 2337 o Clarified that JWSs with duplicate Header Parameter Names MUST be 2338 rejected. 2340 o Clarified the relationship between "typ" header parameter values 2341 and MIME types. 2343 o Registered application/jws MIME type and "JWS" typ header 2344 parameter value. 2346 o Simplified JWK terminology to get replace the "JWK Key Object" and 2347 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2348 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2349 between single keys and sets of keys. As part of this change, the 2350 Header Parameter Name for a public key value was changed from 2351 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2353 o Added suggestion on defining additional header parameters such as 2354 "x5t#S256" in the future for certificate thumbprints using hash 2355 algorithms other than SHA-1. 2357 o Specify RFC 2818 server identity validation, rather than RFC 6125 2358 (paralleling the same decision in the OAuth specs). 2360 o Generalized language to refer to Message Authentication Codes 2361 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2362 unless in a context specific to HMAC algorithms. 2364 o Reformatted to give each header parameter its own section heading. 2366 -01 2368 o Moved definition of Plaintext JWSs (using "alg":"none") here from 2369 the JWT specification since this functionality is likely to be 2370 useful in more contexts that just for JWTs. 2372 o Added "jpk" and "x5c" header parameters for including JWK public 2373 keys and X.509 certificate chains directly in the header. 2375 o Clarified that this specification is defining the JWS Compact 2376 Serialization. Referenced the new JWS-JS spec, which defines the 2377 JWS JSON Serialization. 2379 o Added text "New header parameters should be introduced sparingly 2380 since an implementation that does not understand a parameter MUST 2381 reject the JWS". 2383 o Clarified that the order of the creation and validation steps is 2384 not significant in cases where there are no dependencies between 2385 the inputs and outputs of the steps. 2387 o Changed "no canonicalization is performed" to "no canonicalization 2388 need be performed". 2390 o Corrected the Magic Signatures reference. 2392 o Made other editorial improvements suggested by JOSE working group 2393 participants. 2395 -00 2397 o Created the initial IETF draft based upon 2398 draft-jones-json-web-signature-04 with no normative changes. 2400 o Changed terminology to no longer call both digital signatures and 2401 HMACs "signatures". 2403 Authors' Addresses 2405 Michael B. Jones 2406 Microsoft 2408 Email: mbj@microsoft.com 2409 URI: http://self-issued.info/ 2411 John Bradley 2412 Ping Identity 2414 Email: ve7jtb@ve7jtb.com 2416 Nat Sakimura 2417 Nomura Research Institute 2419 Email: n-sakimura@nri.co.jp