idnits 2.17.1 draft-looker-jwm-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (January 15, 2020) is 1556 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'ECMAScript' ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Looker, Ed. 3 Internet-Draft Mattr 4 Intended status: Standards Track January 15, 2020 5 Expires: July 18, 2020 7 JSON Web Message 8 draft-looker-jwm-01 10 Abstract 12 JSON Web Message (JWM) is a flexible way to encode application-level 13 messages in JSON for transfer over a variety of transport protocols. 14 JWMs use JSON Web Encryption (JWE) to protect integrity, achieve 15 confidentiality, and achieve repudiable authentication; alternatively 16 or in addition, they use JSON Web Signatures (JWS) to associate 17 messages with a non-repudiable digital signature. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on July 18, 2020. 36 Copyright Notice 38 Copyright (c) 2020 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (https://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 55 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. JSON Web Message (JWM) Overview . . . . . . . . . . . . . . . 4 57 2.1. Relationship to JWT . . . . . . . . . . . . . . . . . . . 4 58 2.2. Example Signed JWM . . . . . . . . . . . . . . . . . . . 5 59 2.3. Example Encrypted JWM . . . . . . . . . . . . . . . . . . 7 60 3. JWM Attributes . . . . . . . . . . . . . . . . . . . . . . . 9 61 3.1. Registered Attribute Names . . . . . . . . . . . . . . . 10 62 3.1.1. "id" Attribute . . . . . . . . . . . . . . . . . . . 10 63 3.1.2. "type" Attribute . . . . . . . . . . . . . . . . . . 10 64 3.1.3. "body" Attribute . . . . . . . . . . . . . . . . . . 10 65 3.1.4. "to" Attribute . . . . . . . . . . . . . . . . . . . 11 66 3.1.5. "from" Attribute . . . . . . . . . . . . . . . . . . 11 67 3.1.6. "thread_id" Attribute . . . . . . . . . . . . . . . . 11 68 3.1.7. "created_time" Attribute . . . . . . . . . . . . . . 11 69 3.1.8. "expires_time" Attribute . . . . . . . . . . . . . . 11 70 3.1.9. "reply_url" Attribute . . . . . . . . . . . . . . . . 11 71 3.1.10. "reply_to" Attribute . . . . . . . . . . . . . . . . 12 72 3.2. Public Attribute Names . . . . . . . . . . . . . . . . . 12 73 3.3. Private Attribute Names . . . . . . . . . . . . . . . . . 12 74 4. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . . . 12 75 4.1. "typ" (Type) Header Parameter . . . . . . . . . . . . . . 12 76 4.2. "cty" (Content Type) Header Parameter . . . . . . . . . . 13 77 4.3. Replicating Attributes as Header Parameters . . . . . . . 13 78 5. Creating and Validating JWMs . . . . . . . . . . . . . . . . 13 79 5.1. Creating a JWM . . . . . . . . . . . . . . . . . . . . . 13 80 5.2. Validating a JWM . . . . . . . . . . . . . . . . . . . . 15 81 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 16 82 6. Implementation Requirements . . . . . . . . . . . . . . . . . 16 83 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 84 7.1. Registration Template . . . . . . . . . . . . . . . . . . 17 85 7.1.1. Attribute Name: . . . . . . . . . . . . . . . . . . . 17 86 7.1.2. Attribute Description . . . . . . . . . . . . . . . . 17 87 7.1.3. Change Controller . . . . . . . . . . . . . . . . . . 17 88 7.1.4. Specification Document(s) . . . . . . . . . . . . . . 17 89 7.1.5. Initial Registry Contents . . . . . . . . . . . . . . 18 90 8. Media Type Registration . . . . . . . . . . . . . . . . . . . 19 91 8.1. Registry Contents . . . . . . . . . . . . . . . . . . . . 19 92 9. Security Considerations . . . . . . . . . . . . . . . . . . . 19 93 9.1. Trust Decisions . . . . . . . . . . . . . . . . . . . . . 19 94 9.2. Signing and Encryption Order . . . . . . . . . . . . . . 19 95 10. Privacy Considerations . . . . . . . . . . . . . . . . . . . 20 96 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 20 97 12. Normative References . . . . . . . . . . . . . . . . . . . . 20 98 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 21 100 1. Introduction 102 JSON Web Message (JWM) is a flexible way to encode application-level 103 messages in JSON for transfer over a variety of transport protocols. 104 JWMs use JSON Web Encryption (JWE) to protect integrity, achieve 105 confidentiality, and achieve repudiable authentication; alternatively 106 or in addition, they use JSON Web Signatures (JWS) to associate 107 messages with a non-repudiable digital signature. JWMs are inspired 108 by JWTs [RFC7519]; more details about this relationship are 109 documented in Section 2.1. 111 1.1. Notational Conventions 113 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 114 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 115 "OPTIONAL" in this document are to be interpreted as described in BCP 116 14 RFC 2119 [RFC2119] RFC 8174 [RFC8174] when, and only when, they 117 appear in all capitals, as shown here. 119 1.2. Terminology 121 The terms "JSON Web Signature (JWS)", "Base64url Encoding", "Header 122 Parameter", "JOSE Header", "JWS Payload", "JWS Signature", "JWS 123 Compact Serialization" and "JWS JSON Serialization" are defined by 124 the JWS specification [RFC7515]. 126 The terms "JSON Web Encryption (JWE)", "JWE Compact Serialization" 127 and "JWE JSON Serialization" are defined by the JWE specification 128 [RFC7516]. 130 The terms "StringOrURI", "NumericDate" are defined by the JWT 131 specification [RFC7519]. 133 The following terms are defined by this specification: 135 JSON Web Message A JWM Attribute Set, encoded in a JWS and/or JWE, 136 enabling it to be digitally signed and/or encrypted. 138 JWM Attribute Set A JSON object of attributes conveyed by the JWM. 140 Attribute A piece of information conveyed in a message, sent from a 141 sender intended for processing by one or more recipients. An 142 attribute is represented in a JWM Attribute Set as a name/value 143 pair consisting of an Attribute Name and an Attribute Value. 145 Attribute Name The name portion of an attribute representation. An 146 attribute name is always a string. 148 Attribute Value The value portion of an attribute representation. 149 An attribute value can be any JSON value. 151 Nested JWM A JWM in which nested signing and/or encryption is 152 employed. In Nested JWMs, a JWM is used as the payload or 153 plaintext value of an enclosing JWS or JWE structure, 154 respectively. 156 2. JSON Web Message (JWM) Overview 158 2.1. Relationship to JWT 160 JWMs conceptually share parallels to JWTs: 162 o A JWM contains a JSON object comprised of attributes known as a 163 JWM Attribute Set, where the attributes featured in the set can be 164 public, private or registered in an IANA registry. This is 165 conceptually parallel to claims in JWTs, the JWT Claim Set, and 166 the JWT claims IANA registry. 168 o A JWM leverages JSON Web Signature (JWS) and or JSON Web 169 Encryption (JWE) to achieve digital signing, integrity protection 170 and or confidentiality via encryption for the JWM attribute set in 171 similar ways to JWT for the JWT claim set. 173 JWMs also deviate from JWTs in important ways that prevent a 174 converged specification. 176 o JWM and JWT have different intents. A JWM is about a sender 177 creating a message composed of attributes, where the message is 178 destined for a recipient or recipients. Whereas a JWT is about an 179 issuer expressing claims about a subject to an audience. 181 o The primary usage of JWTs centers around creating tokens that are 182 digitally signed or integrity protected through a Message 183 Authentication Code (MAC) by leveraging JWS. Encrypted JWTs via 184 JWE are less common and as defined in Section 8 of [RFC7519] they 185 are optional to implement. Whereas JWMs require both JWS and JWE 186 implementations. 188 o Because JWTs must be compact and URL-safe, they require compact 189 serialization for both JWS and JWE representations. This means 190 JWTs can feature only a single digital signature, and/or encrypt 191 for only a single recipient. In contrast, JWMs support multiple 192 digital signatures, and encryption for multiple recipients. They 193 achieve this using the JSON-based serialization of JWS and JWE. 195 o JWTs support an insecure format as defined in Section 6 of 196 [RFC7519], JWMs do not allow this format due to the 197 vulnerabilities it introduces. 199 In the spirit of specification re-use and promoting ease of 200 understanding, this specification's structure is inspired by 201 [RFC7519]. 203 2.2. Example Signed JWM 205 The following example JOSE Header declares that the object is a JWM, 206 and the JWM is a JWS that has been digitally signed using ECDSA with 207 the curve p-256 and SHA-256 as the hashing algorithm ("ES256"). The 208 signer of the JWM has indicated that the key used to sign the JWM is 209 identified by "Ef1sFuyOozYm3CEY4iCdwqxiSyXZ5Br-eUDdQXk6jaQ" (with 210 line breaks for display purposes only): 212 {"typ":"JWM", 213 "kid":"Ef1sFuyOozYm3CEY4iCdwqxiSyXZ5Br-eUDdQXk6jaQ", 214 "alg":"ES256"} 216 Base64url encoding the octets of the UTF-8 representation of the JOSE 217 Header yields this encoded JOSE Header value (with line breaks for 218 display purposes only): 220 eyJ0eXAiOiJKV00iLCJraWQiOiJFZjFzRnV5T296WW0zQ0VZNGlDZHdxeGlTeVhaNUJyL 221 WVVRGRRWGs2amFRIiwiYWxnIjoiRVMyNTYifQ 223 The following is an example of a JWM Attributes Set (with line breaks 224 for display purposes only): 226 {"id":"urn:uuid:ef5a7369-f0b9-4143-a49d-2b9c7ee51117", 227 "type":"hello-world-message-type", 228 "from":"urn:uuid:8abdf5fb-621e-4cf5-a595-071bc2c91d82", 229 "expires_time":1516239022, 230 "created_time":1516269022, 231 "body":{"message": "Hello world!"}} 233 Base64url encoding the octets of the UTF-8 the JWS Payload yields 234 this encoded JWS Payload (with line breaks for display purposes 235 only): 237 eyJpZCI6InVybjp1dWlkOmVmNWE3MzY5LWYwYjktNDE0My1hNDlkLTJiOWM3ZWU1MTExN 238 yIsInR5cGUiOiJoZWxsby13b3JsZC1tZXNzYWdlLXR5cGUiLCJmcm9tIjoidXJuOnV1aW 239 Q6OGFiZGY1ZmItNjIxZS00Y2Y1LWE1OTUtMDcxYmMyYzkxZDgyIiwiZXhwaXJ5IjoxNTE 240 2MjM5MDIyLCJ0aW1lX3N0YW1wIjoxNTE2MjY5MDIyLCJib2R5Ijp7Im1lc3NhZ2UiOiJI 241 ZWxsbyB3b3JsZCEifX0 243 Computing the signature of the encoded JOSE Header and encoded JWS 244 Payload with the ECDSA with the curve p-256 and SHA-256 as the 245 hashing algorithm and base64url encoding the value in the manner 246 specified in [RFC7515] yields this encoded JWS Signature: 248 UDE7NsEJyhiewrX2_Z9OdIdB2ZREauoPoUAKdEmW72d8H_ivkjC1p7G16WHunBMq1zFka 249 nINTil3-H1FlhbzsQ 251 Compact Serialization (with line breaks for display purposes only): 253 eyJ0eXAiOiJKV00iLCJraWQiOiJFZjFzRnV5T296WW0zQ0VZNGlDZHdxeGlTeVhaNUJyL 254 WVVRGRRWGs2amFRIiwiYWxnIjoiRVMyNTYifQ 255 . 256 eyJpZCI6InVybjp1dWlkOmVmNWE3MzY5LWYwYjktNDE0My1hNDlkLTJiOWM3ZWU1MTExN 257 yIsInR5cGUiOiJoZWxsby13b3JsZC1tZXNzYWdlLXR5cGUiLCJmcm9tIjoidXJuOnV1aW 258 Q6OGFiZGY1ZmItNjIxZS00Y2Y1LWE1OTUtMDcxYmMyYzkxZDgyIiwiZXhwaXJ5IjoxNTE 259 2MjM5MDIyLCJ0aW1lX3N0YW1wIjoxNTE2MjY5MDIyLCJib2R5Ijp7Im1lc3NhZ2UiOiJI 260 ZWxsbyB3b3JsZCEifX0 261 . 262 UDE7NsEJyhiewrX2_Z9OdIdB2ZREauoPoUAKdEmW72d8H_ivkjC1p7G16WHunBMq1zFka 263 nINTil3-H1FlhbzsQ 265 JSON Serialization: (with line breaks for display purposes only): 267 { 268 "payload": "eyJpZCI6InVybjp1dWlkOmVmNWE3MzY5LWYwYjktNDE0My1hNDl 269 kLTJiOWM3ZWU1MTExNyIsInR5cGUiOiJoZWxsby13b3JsZC1tZXNzYWdlLXR5cG 270 UiLCJmcm9tIjoidXJuOnV1aWQ6OGFiZGY1ZmItNjIxZS00Y2Y1LWE1OTUtMDcxY 271 mMyYzkxZDgyIiwiZXhwaXJ5IjoxNTE2MjM5MDIyLCJ0aW1lX3N0YW1wIjoxNTE2 272 MjY5MDIyLCJib2R5Ijp7Im1lc3NhZ2UiOiJIZWxsbyB3b3JsZCEifX0", 273 "signatures": [ 274 { 275 "protected": "eyJ0eXAiOiJKV00iLCJraWQiOiJFZjFzRnV5T296WW0zQ 276 0VZNGlDZHdxeGlTeVhaNUJyLWVVRGRRWGs2amFRIiwiYWxnIjoiRVMyNTYi 277 fQ", 278 "signature": "rwhHoGJZRyLliF2jPqGXMddBLWlJls4XqSO21GH2itlwh 279 3d3Zb2jAtqA93s9Lb6ktXoxqHxNy4Lbirtr3pCHQA" 280 } 281 ] 282 } 284 2.3. Example Encrypted JWM 286 The following example JOSE Header declares that the object is a JWM, 287 and the JWM is a JWE that has been encrypted using AES in Galois/ 288 Counter Mode (GCM) with 256-bit for content encryption (with line 289 breaks for display purposes only): 291 { 292 "typ":"JWM", 293 "enc":"A256GCM" 294 } 296 The following JOSE Header declares that the sender has used Elliptic 297 Curve Diffie-Hellman Ephemeral Static (ECDH-ES+A256KW) for key 298 agreement with AES based key wrapping to encrypt the content 299 encryption key (CEK). The keys required to perform the opposite 300 Diffie-Helman are identified by the key id of 301 "PGoXzs0NWaR_meKgTZLbEuDoSVTaFuyrbWI7V9dpjCg" along with the 302 ephemeral public key declared by the JSON object "epk". The 303 encrypted CEK is represented by the "encrypted_key" field (with line 304 breaks for display purposes only): 306 { 307 "kid": "PGoXzs0NWaR_meKgTZLbEuDoSVTaFuyrbWI7V9dpjCg", 308 "alg": "ECDH-ES+A256KW", 309 "epk": { 310 "kty": "EC", 311 "crv": "P-256", 312 "x": "-Nh7ShRB_xaCBZRdIiVCul3SoR0Yw4TGEQqqGij1vJs", 313 "y": "9tLx81PMfQkrOw8yuI2YwI0o7MtNzaCGfCBbZBW5YrM" 314 } 315 } 317 Because the JWE features a single recipient, the two JOSE headers are 318 combined into a single JOSE header, that can be represented as the 319 following. 321 { 322 "typ": "JWM", 323 "enc": "A256GCM", 324 "kid": "PGoXzs0NWaR_meKgTZLbEuDoSVTaFuyrbWI7V9dpjCg", 325 "alg": "ECDH-ES+A256KW", 326 "epk": { 327 "kty": "EC", 328 "crv": "P-256", 329 "x": "-Nh7ShRB_xaCBZRdIiVCul3SoR0Yw4TGEQqqGij1vJs", 330 "y": "9tLx81PMfQkrOw8yuI2YwI0o7MtNzaCGfCBbZBW5YrM" 331 } 332 } 334 The following is an example of a JWM Attributes Set (with line breaks 335 for display purposes only): 337 {"id":"urn:uuid:ef5a7369-f0b9-4143-a49d-2b9c7ee51117", 338 "type":"hello-world-message-type", 339 "from":"urn:uuid:8abdf5fb-621e-4cf5-a595-071bc2c91d82", 340 "expires_time":1516239022, 341 "created_time":1516269022, 342 "body":{"message": "Hello world!"}} 344 Encrypting the above plaintext for the recipient yields the following 345 ciphertext in base64url form. 347 awEW6ssGMbQxmvv4FPf0smom4QvPNrgLaxFiMMRXmUTgcs6mLcSJDbUhwLfGfnEeu2a0b 348 cGLRt7tTuQij5RBIe6sflhIgOjpr3VAHdZBYJbF Jg9dCMW_hVk0iLytmFV5BhvqXUXDA 349 ckwwTU41PcS2_qO5uqdIe24teP8Bd_IbVeVnaUwrEEBGJvxYDTefdZ4gryrzKFsLLBD5F 350 r9TsCFEddg0RL xaXFGX1YT8Jm6Ahm-jd6Ol9qIpWx- 351 8PMaFcZl7h4sPiAGVPiaaCyzTsMy8KW0Nmz3cEFqjEm4Ipc 353 Composing this information into a valid JWE leads to the following 354 possible expressions 356 Compact Serialization (with line breaks for display purposes only): 358 eyJ0eXAiOiJKV00iLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiUEdvWHpzME5XYVJfbWVLZ 359 1RaTGJFdURvU1ZUYUZ1eXJiV0k3VjlkcGpDZyIsImFsZyI6I kVDREgtRVMrQTI1NktXI 360 iwiZXBrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiZGdMdy1wOG5kZ0xRSm 361 hZeWhUaGhpVDRhbmJlRjhaak1MYXRxR 2dXVGxHSSIsInkiOiJ3MkNfcjUzekdUdVZscD 362 hQVndFZjViWWI0TWo4bXVjNTVtMHh6VkVMN1o0In19 363 . 364 rAiydPRY_cciOmaQ-tnNiacHWn2Z2GqDgf0FcG4nK2L_KsPd1V1OSA 365 . 366 EIY6u2ahL0MI28ah 367 . 369 awEW6ssGMbQxmvv4FPf0smom4QvPNrgLaxFiMMRXmUTgcs6mLcSJDbUhwLfGfnEeu2a0b 370 cGLRt7tTuQij5RBIe6sflhIgOjpr3VAHdZBYJbF Jg9dCMW_hVk0iLytmFV5BhvqXUXDA 371 ckwwTU41PcS2_qO5uqdIe24teP8Bd_IbVeVnaUwrEEBGJvxYDTefdZ4gryrzKFsLLBD5F 372 r9TsCFEddg0RL xaXFGX1YT8Jm6Ahm-jd6Ol9qIpWx- 373 8PMaFcZl7h4sPiAGVPiaaCyzTsMy8KW0Nmz3cEFqjEm4Ipc 374 . 375 fp_tT_6qsQK2d9szRAwWgA 377 JSON Serialization (with line breaks for display purposes only): 379 { 380 "protected": "eyJ0eXAiOiJKV00iLCJlbmMiOiJBMjU2R0NNIiwi 381 a2lkIjoiUEdvWHpzME5XYVJfbWVLZ1RaTGJFdURvU1ZUYUZ1eXJiV0 382 k3VjlkcGpDZyIsImFsZyI6IkVDREgtRVMrQTI1NktXIiwiZXBrIjp7 383 Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiLU5oN1NoUkJfeG 384 FDQlpSZElpVkN1bDNTb1IwWXc0VEdFUXFxR2lqMXZKcyIsInkiOiI5 385 dEx4ODFQTWZRa3JPdzh5dUkyWXdJMG83TXROemFDR2ZDQmJaQlc1WX 386 JNIn19", 387 "recipients": [ 388 { 389 "encrypted_key": "J1Fs9JaDjOT_5481ORQWfEZmHy7OjE3p 390 TNKccnK7hlqjxbPalQWWLg" 391 } 392 ], 393 "iv": "u5kIzo0m_d2PjI4m", 394 "ciphertext": "qGuFFoHy7HBmkf2BaY6eREwzEjn6O_FnRoXj2H- 395 DAXo1PgQdfON-_1QbxtnT8e8z_M6Gown7s8fLtYNmIHAuixqFQnSA4 396 fdMcMSi02z1MYEn2JC-1EkVbWr4TqQgFP1EyymB6XjCWDiwTYd2xpK 397 oUshu8WW601HLSgFIRUG3-cK_ZSdFaoWosIgAH5EQ2ayJkRB_7dXuo 398 6_AYdIzMahvPz0n1yHHBlYBuYeR58V-x85ACeCGtzL2OptPa2TmWdA 399 9Bi1MK6TYGZKezc6rpCK_VRSnLXhFwa1C3T0QBes", 400 "tag": "doeAoagwJe9BwKayfcduiw" 401 } 403 3. JWM Attributes 405 The JWM Attributes Set represents a JSON object whose members are the 406 attributes conveyed by the JWM. The Attribute Names within a JWM 407 Attributes Set MUST be unique; JWM parsers MUST either reject JWMs 408 with duplicate Attribute Names or use a JSON parser that returns only 409 the lexically last duplicate member name, as specified in 410 Section 15.12 ("The JSON Object") of ECMAScript 5.1 [ECMAScript]. 412 The set of attributes that a JWM must contain to be considered valid 413 is context dependent and is outside the scope of this specification. 414 Specific applications of JWMs will require implementations to 415 understand and process some attributes in particular ways. However, 416 in the absence of such requirements, all attributes that are not 417 understood by implementations MUST be ignored. 419 There are three classes of JWM Attribute Names: Registered Attribute 420 Names, Public Attribute Names and Private Attribute Names. 422 3.1. Registered Attribute Names 424 The following Attribute Names are registered in the IANA "JSON Web 425 Message Attributes" registry established by Section 7. None of the 426 attributes defined below are intended to be mandatory to use or 427 implement in all cases, but rather they provide a starting point for 428 a set of useful, interoperable attributes. Applications using JWMs 429 should define which specific Attributes they use and when they are 430 required or optional. 432 3.1.1. "id" Attribute 434 The "id" attribute is used to define a unique identifier for a JWM. 435 The "id" attribute value MUST be assigned in a manner that ensures 436 that there is a negligible probability that the same value will be 437 accidentally assigned to another JWM. The processing of this 438 attribute is generally application specific. The "id" attribute 439 value is a case-sensitive string containing a StringOrURI value. Use 440 of this attribute is OPTIONAL. 442 3.1.2. "type" Attribute 444 The "type" attribute is used to define the type of the message. The 445 processing of this attribute is generally application specific. The 446 "type" attribute value is a case-sensitive string containing a 447 StringOrURI value. The "type" attribute value can be used by 448 applications to inform the structure and content of the "message 449 body" and indicate the presence of other JWM attributes. Use of this 450 attribute is OPTIONAL. 452 3.1.3. "body" Attribute 454 The "body" attribute is used to define a location for application 455 level message content. The "body" attribute value is a JSON object 456 conforming to RFC 7159 [RFC7159]. The processing of this attribute 457 is generally application specific. Use of this attribute is 458 OPTIONAL. 460 3.1.4. "to" Attribute 462 The "to" attribute is used to define the intended recipients of the 463 JWM. The "to" attribute value is an array of case-sensitive strings 464 each containing a StringOrURI value. The processing of this 465 attribute is generally application specific. Use of this attribute 466 is OPTIONAL. 468 3.1.5. "from" Attribute 470 The "from" attribute is used to define the sender of the JWM. The 471 "from" attribute value is a case-sensitive string containing a 472 StringOrURI value. The processing of this attribute is generally 473 application specific. Use of this attribute is OPTIONAL. 475 3.1.6. "thread_id" Attribute 477 The "thread_id" attribute is used to associate the JWM to a group of 478 related messages often referred to as a thread. The "thread_id" 479 attribute value is a case-sensitive string containing a StringOrURI 480 value. The processing of this attribute is generally application 481 specific. Use of this attribute is OPTIONAL. 483 3.1.7. "created_time" Attribute 485 The "created_time" attribute is used to define the time in which the 486 message was created. The "created_time" attributes value MUST be a 487 number containing a NumericDate value. The processing of this 488 attribute is generally application specific. Use of this attribute 489 is OPTIONAL. 491 3.1.8. "expires_time" Attribute 493 The "expires_time" attribute is used to define the lifespan or 494 lifetime of the JWM. The "expires_time" attributes value MUST be a 495 number containing a NumericDate value. The processing of this 496 attribute is generally application specific. Use of this attribute 497 is OPTIONAL. 499 3.1.9. "reply_url" Attribute 501 The "reply_url" attribute is used to define a url to which a response 502 to the message can be sent. The "reply_url" attribute value is a 503 case-sensitive string containing a StringOrURI value. The processing 504 of this attribute is generally application specific. Use of this 505 attribute is OPTIONAL. 507 3.1.10. "reply_to" Attribute 509 The "reply_to" attribute is used to define who a response to the 510 message should be sent to. The "reply_to" attribute value is a case- 511 sensitive string containing an array of case-sensitive strings 512 containing StringOrURI values. The processing of this attribute is 513 generally application specific. Use of this attribute is OPTIONAL. 515 3.2. Public Attribute Names 517 Attribute Names can be defined at will by those using JWMs. However, 518 in order to prevent collisions, any new Attribute Name should either 519 be registered in the IANA "JSON Web Message Attributes" registry 520 established by Section 7 or be a Public Name: a value that contains a 521 Collision-Resistant Name. In each case, the definer of the name or 522 value needs to take reasonable precautions to make sure they are in 523 control of the part of the namespace they use to define the Attribute 524 Name. 526 3.3. Private Attribute Names 528 A producer and consumer of a JWM MAY agree to use Attribute Names 529 that are Private Names: names that are not Registered Attribute Names 530 Section 3.1 or Public Attribute Names Section 3.2. Unlike Public 531 Attribute Names, Private Attribute Names are subject to collision and 532 should be used with caution. 534 4. JOSE Header 536 For a JWM object, the members of the JSON object represented by the 537 JOSE Header describe the cryptographic operations applied to the JWM 538 and optionally, additional properties of the JWM. Depending upon 539 whether the JWM is a JWS or JWE, the corresponding rules for the JOSE 540 Header values apply. 542 This specification further specifies the use of the following header 543 parameters in both the cases where the JWM is a JWS and where it is a 544 JWE. 546 4.1. "typ" (Type) Header Parameter 548 The "typ" (type) Header Parameter defined by [RFC7515] and [RFC7516] 549 is used by JWM applications to declare the media type 550 [IANA.MediaTypes] of this complete JWM. This is intended for use by 551 the JWM application when values that are not JWMs could also be 552 present in an application data structure that can contain a JWM 553 object; the application can use this value to disambiguate among the 554 different kinds of objects that might be present. It will typically 555 not be used by applications when it is already known that the object 556 is a JWM. This parameter is ignored by JWM implementations; any 557 processing of this parameter is performed by the JWM application. If 558 present, it is RECOMMENDED that its value be "JWM" to indicate that 559 this object is a JWM. While media type names are not case sensitive, 560 it is RECOMMENDED that "JWM" always be spelled using uppercase 561 characters for compatibility with legacy implementations. Use of 562 this Header Parameter is OPTIONAL. 564 4.2. "cty" (Content Type) Header Parameter 566 The "cty" (content type) Header Parameter defined by [RFC7515] and 567 [RFC7516] is used by this specification to convey structural 568 information about the JWM. 570 In the normal case in which nested signing or encryption operations 571 are not employed, the use of this Header Parameter is NOT 572 RECOMMENDED. In the case that nested signing or encryption is 573 employed, this Header Parameter MUST be present; in this case, the 574 value MUST be "JWM", to indicate that a Nested JWM is carried in this 575 JWM. While media type names are not case sensitive, it is 576 RECOMMENDED that "JWM" always be spelled using uppercase characters 577 for compatibility with legacy implementations. 579 4.3. Replicating Attributes as Header Parameters 581 In some applications using encrypted JWMs, it is useful to have an 582 unencrypted representation of some attributes. This might be used, 583 for instance, in application processing rules to determine whether 584 and how to process the JWM before it is decrypted. 586 This specification allows Attributes present in the JWM Attributes 587 Set to be replicated as JOSE Header Parameters in a JWM that is a 588 JWE, as needed by the application. If such replicated attributes are 589 present, the application receiving them SHOULD verify that their 590 values are identical, unless the application defines other specific 591 processing rules for these attributes. It is the responsibility of 592 the application to ensure that only attributes that are safe to be 593 transmitted in an unencrypted manner are replicated as JOSE Header 594 Parameter values in the JWM. 596 5. Creating and Validating JWMs 598 5.1. Creating a JWM 600 To create a JWM, the following steps are performed. The order of the 601 steps is not significant in cases where there are no dependencies 602 between the inputs and outputs of the steps. 604 1. Create a JWM Attribute Set containing the desired attributes. 605 Note that whitespace is explicitly allowed in the representation 606 and no canonicalization need be performed before encoding. 608 2. Let the Message be the octets of the UTF-8 representation of the 609 JWM Attributes Set. 611 3. Create a JOSE Header containing the desired set of Header 612 Parameters. The JWM MUST conform to either the JWS [RFC7515] or 613 JWE [RFC7516] specification. Note that whitespace is explicitly 614 allowed in the representation and no canonicalization need be 615 performed before encoding. THE JOSE "typ" header must be set to 616 "JWM". 618 4. Depending upon whether the JWM is a JWS or JWE, there are two 619 cases: 621 o If the JWM is a JWS, create a JWS using the JWM Attribute Set as 622 the JWS Payload; all steps specified in JWS [RFC7515] for creating 623 a JWS MUST be followed. If the resulting JWS features only a 624 single signature, it can optionally be formated into JWS compact 625 serialization format allowing the message to be URL safe. If 626 however, the resulting JWS features multiple signatures and URL 627 safety for the message is still required, the entire JWS in JSON 628 serialization format MUST be encoded to base64url format. 629 Otherwise the output format for the JWS MUST be JWS JSON 630 serialization format. 632 o Else, if the JWM is a JWE, create a JWE using the JWM Attribute 633 Set as the plaintext for the JWE; all steps specified in JWE 634 [RFC7516] for creating a JWE MUST be followed. If the resulting 635 JWE features only a single recipient, it can optionally be 636 formated into JWE compact serialization format allowing the 637 message to be URL safe. If however, the resulting JWE features 638 multiple recipients and URL safety for the message is still 639 required, the entire JWE in JSON serialization format MUST be 640 encoded to base64url format. Otherwise the output format for the 641 JWE MUST be JWE JSON serialization format. 643 1. If a Nested JWM is desired, let the Message be the JWS or JWE, 644 and return to Step 3, using a "cty" (content type) value of "JWM" 645 in the new JOSE Header created in that step. 647 2. Otherwise, let the resulting JWM be the JWS or JWE. 649 5.2. Validating a JWM 651 When validating a JWM, the following steps are performed. The order 652 of the steps is not significant in cases where there are no 653 dependencies between the inputs and outputs of the steps. If any of 654 the listed steps fail, then the JWM MUST be rejected; that is, 655 treated by the application as an invalid input. 657 1. If the JWM is a valid base64url string containing at least one 658 period ('.') character. 660 1. Let the Encoded JOSE Header be the portion of the JWM before 661 the first period ('.') character. 663 2. Base64url decode the Encoded JOSE Header following the 664 restriction that no line breaks, whitespace, or other 665 additional characters have been used. 667 3. Verify that the resulting octet sequence is a UTF-8-encoded 668 representation of a completely valid JSON object conforming 669 to RFC 7159 [RFC7159]; let the JOSE Header be this JSON 670 object. 672 2. Else, if the JWM is a valid base64url string containing no period 673 ('.') characters. 675 1. Let the Encoded JWS or JWE be the entire base64url string. 677 2. Base64url decode the Encoded JWS or JWE following the 678 restriction that no line breaks, whitespace, or other 679 additional characters have been used. 681 3. Verify that the resulting octet sequence is a UTF-8-encoded 682 representation of a completely valid JSON object conforming 683 to RFC 7159 [RFC7159]; let the JWS or JWE be this JSON 684 object. 686 3. Else, if the JWM is a UTF-8-encoded representation of a 687 completely valid JSON object conforming to RFC 7159 [RFC7159]; 688 let the JWS or JWE be this JSON object. 690 4. Verify that the resulting JOSE Header includes only parameters 691 and values whose syntax and semantics are both understood and 692 supported or that are specified as being ignored when not 693 understood. 695 5. Determine whether the JWM is a JWS or a JWE using any of the 696 methods described in Section 9 of [RFC7516]. 698 6. Depending upon whether the JWM is a JWS or JWE, there are two 699 cases: 701 * If the JWM is a JWS, follow the steps specified in [RFC7515] 702 for validating a JWS. Let the Message be the result of 703 base64url decoding the JWS Payload. 705 * Else, if the JWM is a JWE, follow the steps specified in 706 [RFC7516] for validating a JWE. Let the Message be the 707 resulting plaintext. 709 7. If the JOSE Header contains a "cty" (content type) value of 710 "JWM", then the Message is a JWM that was the subject of nested 711 signing or encryption operations. In this case, return to Step 712 1, using the Message as the JWM. 714 8. Otherwise, base64url decode the Message following the restriction 715 that no line breaks, whitespace, or other additional characters 716 have been used. 718 9. Verify that the resulting octet sequence is a UTF-8-encoded 719 representation of a completely valid JSON object conforming to 720 RFC 7159 [RFC7159]; let the JWM Attributes Set be this JSON 721 object. 723 Finally, note that it is an application decision which algorithms may 724 be used in a given context. Even if a JWM can be successfully 725 validated, unless the algorithms used in the JWM are acceptable to 726 the application, it SHOULD reject the JWM. 728 5.3. String Comparison Rules 730 These rules are identical to those applied to JWTs outlined in 731 Section 7.3 of [RFC7519]. 733 6. Implementation Requirements 735 This section defines which algorithms and features of this 736 specification are mandatory to implement. Applications using this 737 specification can impose additional requirements upon implementations 738 that they use. 740 Support for digitally signed JWMs using JWS is REQUIRED. Of the 741 signature and MAC algorithms specified in JSON Web Algorithms 742 [RFC7518], only ECDSA using the P-256 curve and SHA-256 hash 743 algorithm ("ES256") MUST be implemented by conforming JWM 744 implementations. It is RECOMMENDED that implementations also support 745 ECDSA using the P-521 curve and the SHA-512 hash algorithm ("ES512") 746 and EdDSA using the Ed25519 curve and SHA-512 hash algorithm. 747 Support for other algorithms and key sizes is OPTIONAL. 749 Support for encrypted JWMs using JWE is also REQUIRED. Of the 750 encryption algorithms specified in [RFC7518], using Elliptic Curve 751 Diffie-Hellman Ephemeral Static (ECDH-ES) to agree upon a key and 752 using this key to to perform key wrapping of a Content Encryption Key 753 ("ECDH-ES+A128KW" and "ECDH-ES+A256KW") MUST be supported. With 754 regards to content encryption, AES in Galois/Counter Mode (GCM) with 755 128-bit and 256-bit keys ("A128GCM" and "A256GCM") MUST also be 756 supported. 758 Usage of the "none" algorithm identifier in a JWM as defined in the 759 JOSE Web Algorithms section 3.6 [RFC7518] MUST be considered invalid. 761 Support for Nested JWMs is also REQUIRED. 763 7. IANA Considerations 765 7.1. Registration Template 767 7.1.1. Attribute Name: 769 The name requested (e.g., "type"). Because a core goal of this 770 specification is for the resulting representations to be compact, it 771 is RECOMMENDED that the name be short - that is, not to exceed 8 772 characters without a compelling reason to do so. This name is case 773 sensitive. Names may not match other registered names in a case- 774 insensitive manner unless the Designated Experts state that there is 775 a compelling reason to allow an exception. 777 7.1.2. Attribute Description 779 Brief description of the attribute (e.g., "Message Type"). 781 7.1.3. Change Controller 783 For Standards Track RFCs, list the "IESG". For others, give the name 784 of the responsible party. Other details (e.g., postal address, email 785 address, home page URI) may also be included. 787 7.1.4. Specification Document(s) 789 Reference to the document or documents that specify the parameter, 790 preferably including URIs that can be used to retrieve copies of the 791 documents. An indication of the relevant sections may also be 792 included but is not required. 794 7.1.5. Initial Registry Contents 796 o Attribute Name: "id" 797 o Attribute Description: Message ID 798 o Change Controller: 799 o Specification Document(s): 801 o Attribute Name: "type" 802 o Attribute Description: Message Type 803 o Change Controller: 804 o Specification Document(s): 806 o Attribute Name: "body" 807 o Attribute Description: Message Body 808 o Change Controller: 809 o Specification Document(s): 811 o Attribute Name: "to" 812 o Attribute Description: Message Recipients 813 o Change Controller: 814 o Specification Document(s): 816 o Attribute Name: "from" 817 o Attribute Description: Message From 818 o Change Controller: 819 o Specification Document(s): 821 o Attribute Name: "thread_id" 822 o Attribute Description: Message Thread ID 823 o Change Controller: 824 o Specification Document(s): 826 o Attribute Name: "created_time" 827 o Attribute Description: Message Created Time 828 o Change Controller: 829 o Specification Document(s): 831 o Attribute Name: "expires_time" 832 o Attribute Description: Message Expiry Time 833 o Change Controller: 834 o Specification Document(s): 836 o Attribute Name: "reply_url" 837 o Attribute Description: Message Reply URL 838 o Change Controller: 839 o Specification Document(s): 841 o Attribute Name: "reply_to" 842 o Attribute Description: Message Reply To 843 o Change Controller: 844 o Specification Document(s): 846 8. Media Type Registration 848 8.1. Registry Contents 850 9. Security Considerations 852 All of the security issues that are pertinent to any cryptographic 853 application must be addressed by JWM/JWS/JWE/JWK agents. Among these 854 issues are protecting the user's asymmetric private and symmetric 855 secret keys and employing countermeasures to various attacks. 857 All the security considerations in the JWS specification also apply 858 to JWM, as do the JWE security considerations when encryption is 859 employed. In particular, Sections 10.12 ("JSON Security 860 Considerations") and 10.13 ("Unicode Comparison Security 861 Considerations") of [RFC7515] apply equally to the JWM Attributes Set 862 in the same manner that they do to the JOSE Header. 864 9.1. Trust Decisions 866 The contents of a JWM cannot be relied upon in a trust decision 867 unless its contents have been cryptographically secured and bound to 868 the context necessary for the trust decision. In particular, the 869 key(s) used to sign and/or encrypt the JWM will typically need to 870 verifiably be under the control of the party identified by the 871 associated cryptographic operation. 873 9.2. Signing and Encryption Order 875 While syntactically the signing and encryption operations for Nested 876 JWMs may be applied in any order, if both signing and encryption are 877 necessary, normally producers should sign the message and then 878 encrypt the result (thus encrypting the signature). This prevents 879 attacks in which the signature is stripped, leaving just an encrypted 880 message, as well as providing privacy for the signer. Furthermore, 881 signatures over encrypted text are not considered valid in many 882 jurisdictions. 884 Note that potential concerns about security issues related to the 885 order of signing and encryption operations are already addressed by 886 the underlying JWS and JWE specifications; in particular, because JWE 887 only supports the use of authenticated encryption algorithms, 888 cryptographic concerns about the potential need to sign after 889 encryption that apply in many contexts do not apply to this 890 specification. 892 10. Privacy Considerations 894 A JWM may contain privacy-sensitive information. When this is the 895 case, measures MUST be taken to prevent disclosure of this 896 information to unintended parties. One way to achieve this is to use 897 an encrypted JWM and authenticate the recipient. Another way is to 898 ensure that JWMs containing unencrypted privacy-sensitive information 899 are only transmitted using protocols utilizing encryption that 900 support endpoint authentication, such as Transport Layer Security 901 (TLS). Omitting privacy-sensitive information from a JWM is the 902 simplest way of minimizing privacy issues. 904 11. Acknowledgements 906 The authors of this specification would like to acknowledge the 907 following individuals for the significant contribution of ideas and 908 time spent reviewing this document: 909 Kyle Den Hartog 910 Daniel Hardman 912 12. Normative References 914 [ECMAScript] 915 Ecma International, "ECMAScript Language Specification, 916 5.1 Edition", ECMA Standard 262, June 2011, 917 . 920 [IANA.MediaTypes] 921 IANA, "Media Types", 922 . 924 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 925 Requirement Levels", BCP 14, RFC 2119, 926 DOI 10.17487/RFC2119, March 1997, 927 . 929 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 930 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 931 2014, . 933 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 934 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 935 2015, . 937 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 938 RFC 7516, DOI 10.17487/RFC7516, May 2015, 939 . 941 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 942 DOI 10.17487/RFC7518, May 2015, 943 . 945 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 946 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 947 . 949 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 950 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 951 May 2017, . 953 Author's Address 955 Tobias Looker (editor) 956 Mattr 958 Email: tobias.looker@mattr.global