idnits 2.17.1 draft-hallambaker-mesh-protocol-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 6 instances of too long lines in the document, the longest one being 3 characters in excess of 72. ** The abstract seems to contain references ([1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 23, 2019) is 1646 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 1540 -- Looks like a reference, but probably isn't: '2' on line 1543 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group P. Hallam-Baker 3 Internet-Draft October 23, 2019 4 Intended status: Informational 5 Expires: April 25, 2020 7 Mathematical Mesh 3.0 Part V: Protocol Reference 8 draft-hallambaker-mesh-protocol-03 10 Abstract 12 The Mathematical Mesh 'The Mesh' is an end-to-end secure 13 infrastructure that facilitates the exchange of configuration and 14 credential data between multiple user devices. The core protocols of 15 the Mesh are described with examples of common use cases and 16 reference data. 18 [Note to Readers] 20 Discussion of this draft takes place on the MATHMESH mailing list 21 (mathmesh@ietf.org), which is archived at 22 https://mailarchive.ietf.org/arch/search/?email_list=mathmesh. 24 This document is also available online at 25 http://mathmesh.com/Documents/draft-hallambaker-mesh-protocol.html 26 [1] . 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on April 25, 2020. 45 Copyright Notice 47 Copyright (c) 2019 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (https://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 63 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 2.1. Requirements Language . . . . . . . . . . . . . . . . . . 5 65 2.2. Defined Terms . . . . . . . . . . . . . . . . . . . . . . 5 66 2.3. Related Specifications . . . . . . . . . . . . . . . . . 5 67 2.4. Implementation Status . . . . . . . . . . . . . . . . . . 5 68 3. Mesh Service . . . . . . . . . . . . . . . . . . . . . . . . 6 69 3.1. Data Model . . . . . . . . . . . . . . . . . . . . . . . 6 70 3.2. Partitioning . . . . . . . . . . . . . . . . . . . . . . 7 71 4. Protocol Bindings . . . . . . . . . . . . . . . . . . . . . . 7 72 4.1. DNS Web Service Discovery . . . . . . . . . . . . . . . . 7 73 4.2. Web Service Protocol Binding . . . . . . . . . . . . . . 7 74 4.2.1. Transport Security . . . . . . . . . . . . . . . . . 8 75 4.2.2. HTTP Message Binding . . . . . . . . . . . . . . . . 8 76 4.2.3. Request . . . . . . . . . . . . . . . . . . . . . . . 8 77 4.2.4. Response . . . . . . . . . . . . . . . . . . . . . . 9 78 4.3. DARE Message Encapsulation . . . . . . . . . . . . . . . 10 79 4.3.1. Null Authentication . . . . . . . . . . . . . . . . . 11 80 4.3.2. Device Authentication . . . . . . . . . . . . . . . . 11 81 4.3.3. Profile Authentication . . . . . . . . . . . . . . . 11 82 4.3.4. Ticket Authentication . . . . . . . . . . . . . . . . 11 83 4.4. Payload Encoding . . . . . . . . . . . . . . . . . . . . 11 84 4.5. Error handling and response codes . . . . . . . . . . . . 12 85 5. Service Description . . . . . . . . . . . . . . . . . . . . . 13 86 6. Account Management . . . . . . . . . . . . . . . . . . . . . 14 87 7. Container Synchronization . . . . . . . . . . . . . . . . . . 16 88 7.1. Status Transaction . . . . . . . . . . . . . . . . . . . 17 89 7.2. Download Transaction . . . . . . . . . . . . . . . . . . 17 90 7.2.1. Conflict Detection . . . . . . . . . . . . . . . . . 17 91 7.2.2. Filtering . . . . . . . . . . . . . . . . . . . . . . 17 92 7.3. Upload Transaction . . . . . . . . . . . . . . . . . . . 17 94 8. Device Connection . . . . . . . . . . . . . . . . . . . . . . 18 95 8.1. Device Authenticated . . . . . . . . . . . . . . . . . . 18 96 8.2. PIN Authenticated . . . . . . . . . . . . . . . . . . . . 19 97 8.3. EARL connection mode . . . . . . . . . . . . . . . . . . 19 98 9. Mesh Messaging . . . . . . . . . . . . . . . . . . . . . . . 19 99 9.1. Message Exchange . . . . . . . . . . . . . . . . . . . . 20 100 9.1.1. Client-Service (Post Transaction) . . . . . . . . . . 20 101 9.1.2. Service-Service (Post Transaction) . . . . . . . . . 20 102 9.1.3. Service-Client (Synchronization) . . . . . . . . . . 21 103 10. Protocol Schema . . . . . . . . . . . . . . . . . . . . . . . 22 104 10.1. Request Messages . . . . . . . . . . . . . . . . . . . . 22 105 10.1.1. Message: MeshRequest . . . . . . . . . . . . . . . . 22 106 10.1.2. Message: MeshRequestUser . . . . . . . . . . . . . . 22 107 10.2. Response Messages . . . . . . . . . . . . . . . . . . . 22 108 10.2.1. Message: MeshResponse . . . . . . . . . . . . . . . 23 109 10.3. Imported Objects . . . . . . . . . . . . . . . . . . . . 23 110 10.4. Common Structures . . . . . . . . . . . . . . . . . . . 23 111 10.4.1. Structure: KeyValue . . . . . . . . . . . . . . . . 23 112 10.4.2. Structure: ConstraintsSelect . . . . . . . . . . . . 23 113 10.4.3. Structure: ConstraintsData . . . . . . . . . . . . . 24 114 10.4.4. Structure: PolicyAccount . . . . . . . . . . . . . . 24 115 10.4.5. Structure: ContainerStatus . . . . . . . . . . . . . 24 116 10.4.6. Structure: ContainerUpdate . . . . . . . . . . . . . 25 117 10.5. Transaction: Hello . . . . . . . . . . . . . . . . . . . 25 118 10.5.1. Message: MeshHelloResponse . . . . . . . . . . . . . 25 119 10.6. Transaction: Complete . . . . . . . . . . . . . . . . . 26 120 10.6.1. Message: CompleteRequest . . . . . . . . . . . . . . 26 121 10.7. Transaction: Status . . . . . . . . . . . . . . . . . . 26 122 10.7.1. Message: StatusRequest . . . . . . . . . . . . . . . 26 123 10.7.2. Message: StatusResponse . . . . . . . . . . . . . . 27 124 10.8. Transaction: Download . . . . . . . . . . . . . . . . . 27 125 10.8.1. Message: DownloadRequest . . . . . . . . . . . . . . 27 126 10.8.2. Message: DownloadResponse . . . . . . . . . . . . . 27 127 10.9. Transaction: Upload . . . . . . . . . . . . . . . . . . 28 128 10.9.1. Message: UploadRequest . . . . . . . . . . . . . . . 28 129 10.9.2. Message: UploadResponse . . . . . . . . . . . . . . 28 130 10.9.3. Structure: EntryResponse . . . . . . . . . . . . . . 29 131 10.10. Transaction: Post . . . . . . . . . . . . . . . . . . . 29 132 10.10.1. Message: PostRequest . . . . . . . . . . . . . . . 29 133 10.10.2. Message: PostResponse . . . . . . . . . . . . . . . 30 134 10.11. Transaction: Connect . . . . . . . . . . . . . . . . . . 30 135 10.11.1. Message: ConnectRequest . . . . . . . . . . . . . . 30 136 10.11.2. Message: ConnectResponse . . . . . . . . . . . . . 30 137 10.12. Transaction: CreateAccount . . . . . . . . . . . . . . . 30 138 10.12.1. Message: CreateRequest . . . . . . . . . . . . . . 31 139 10.12.2. Message: CreateResponse . . . . . . . . . . . . . . 31 140 10.13. Transaction: DeleteAccount . . . . . . . . . . . . . . . 31 141 10.13.1. Message: DeleteRequest . . . . . . . . . . . . . . 32 142 10.13.2. Message: DeleteResponse . . . . . . . . . . . . . . 32 143 11. Security Considerations . . . . . . . . . . . . . . . . . . . 32 144 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 145 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 32 146 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 32 147 14.1. Normative References . . . . . . . . . . . . . . . . . . 32 148 14.2. Informative References . . . . . . . . . . . . . . . . . 33 149 14.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 33 150 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 33 152 1. Introduction 154 This document describes the Mesh Service protocol supported by Mesh 155 Services, an account-based protocol that facilitates exchange of data 156 between devices connected to a Mesh profile and between Mesh 157 accounts. 159 Mesh Service Accounts support the following services: 161 o Provides the master persistence store for the Catalogs and Spools 162 associated with the account. 164 o Enables synchronization of Catalogs and Spools with connected 165 devices. 167 o Enforces access control on inbound Mesh Messages from other users 168 and other Mesh Services. 170 o Authenticates outbound Mesh Messages, certifying that they comply 171 with abuse mitigation policies. 173 A Mesh Profile MAY be bound to multiple Mesh Service Accounts at the 174 same time but only one Mesh Service Account is considered to be 175 authoritative at a time. Users may add or remove Mesh Service 176 Accounts and change the account designated as authoritative at any 177 time. 179 The Mesh Services are build from a very small set of primitives which 180 provide a surprisingly extensive set of capabilities. These 181 primitives are: 183 Hello Describes the features and options provided by the service and 184 provides a 'null' transaction which MAY be used to establish an 185 authentication ticket without performing any action, 187 CreateAccount, DeleteAccount Manage the creation and deletion of 188 accounts at the service. 190 Status, Download, Upload Support synchronization of Mesh containers 191 between the service (Master) and the connected devices (Replicas). 193 Connect Initiate the process of connecting a device to a Mesh 194 profile from the device itself. 196 Post Request that a Mesh Message be transferred to one or more Mesh 197 Accounts. 199 Although these functions could in principle be used to replace many 200 if not most existing Internet application protocols, the principal 201 value of any communication protocol lies in the size of the audience 202 it allows them to communicate with. Thus, while the Mesh Messaging 203 service is designed to support efficient and reliable transfer of 204 messages ranging in size from a few bytes to multiple terabytes, the 205 near-term applications of these services will be to applications that 206 are not adequately supported by existing protocols if at all. 208 2. Definitions 210 This section presents the related specifications and standard, the 211 terms that are used as terms of art within the documents and the 212 terms used as requirements language. 214 2.1. Requirements Language 216 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 217 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 218 document are to be interpreted as described in [RFC2119] . 220 2.2. Defined Terms 222 The terms of art used in this document are described in the Mesh 223 Architecture Guide [draft-hallambaker-mesh-architecture] . 225 2.3. Related Specifications 227 The architecture of the Mathematical Mesh is described in the Mesh 228 Architecture Guide [draft-hallambaker-mesh-architecture] . The Mesh 229 documentation set and related specifications are described in this 230 document. 232 2.4. Implementation Status 234 The implementation status of the reference code base is described in 235 the companion document [draft-hallambaker-mesh-developer] . 237 3. Mesh Service 239 A Mesh Service is a minimally trusted service. In particular a user 240 does not need to trust a Mesh service to protect the confidentiality 241 or integrity of most data stored in the account catalogs and spools. 243 Unless the use of the Mesh Service is highly restricted, a user does 244 need to trust the Mesh Service in certain respects: 246 Data Loss A service could refuse to respond to requests to download 247 data. 249 Integrity (Stale Data) The use of Merkle Trees limits but does not 250 eliminate the ability of a Mesh Service to respond to requests 251 with stale data. 253 Messaging A service could reject requests to post messages to or 254 accept messages from other mesh users. 256 This risk is a necessary consequence of the fact that the Mesh 257 Service Provider is accountable to other Mesh Service Providers 258 for abuse originating from their service. 260 Traffic analysis A Mesh Service has knowledge of the number of Mesh 261 Messages being sent and received by its users and the addresses to 262 which they are being sent to or received from. 264 The need to trust the Mesh Service in these respects is mitigated by 265 accountability and the user's ability to change Mesh Service 266 providers at any time they choose with minimal inconvenience. 268 It is possible that some of these risks will be reduced in future 269 versions of the Mesh Service Protocol but it is highly unlikely that 270 these can be eliminated entirely without compromising practicality or 271 efficiency. 273 3.1. Data Model 275 The design of the Mesh Service model followed a quasi-formal approach 276 in which the system was reduced to schemas which could in principle 277 be rendered in a formal development method but without construction 278 of proofs. 280 Like the contents of Mesh Accounts, a Mesh Service may be represented 281 by a collection of catalogs and spools, for example: 283 Account Catalog Contains the account entries. 285 Incident Spool Reports of potential abuse 287 Backup of the service MAY be implemented using the same container 288 synchronization mechanism used to synchronize account catalogs and 289 spools. 291 3.2. Partitioning 293 Mesh Services supporting a large number of accounts or large activity 294 volume MAY partition the account catalog between one or more hosts 295 using the usual tiered service model in which a front-end server 296 receives traffic for any account hosted at the server and routes the 297 request to the back-end service that provides the persistence store 298 for that account. 300 In addition, the Mesh Service Protocol supports a 'direct connection' 301 partitioning model in which devices are given a DNS name which MAY 302 allow for direct connection to the persistence host or to a front-end 303 service offering service that is in some way specific to that 304 account. 306 4. Protocol Bindings 308 Mesh Service transactions are mapped to an underlying messaging and 309 transport protocol. The following binding 311 Mesh Services MUST support the Web Service binding specified in this 312 document and MAY support the UDP binding currently in development. 314 4.1. DNS Web Service Discovery 316 The DNS Web Service discovery mechanism is used to discover Mesh 317 Services regardless of the protocol binding .The service name, DNS 318 prefix and and .well-known service suffix are specified as follows: 320 o Service Name: mmm 322 o DNS Prefix: _mmm._tcp 324 o Well Known service suffix: /.well-known/mmm 326 4.2. Web Service Protocol Binding 328 The Web Service Protocol binding makes use of the most widely 329 deployed and used protocols: 331 o Discovery: DNS Service discovery 332 o Transport: TLS 334 o Application: HTTP 336 o Presentation: DARE Message 338 o Encoding: JSON, JSON-B 340 The chief limitations of the Web Service Protocol Binding are that 341 the use of TCP based transport results in unsatisfactory latency for 342 some applications and that the HTTP application layer only serves to 343 allow a host to support multiple services on the same TCP/IP port. 345 4.2.1. Transport Security 347 Mesh Services MUST offer TLS transport and MAY offer non TLS 348 transport. MESH clients SHOULD use TLS transport when connecting to 349 a MESH service. 351 TLS version 1.3 [RFC8446] or higher MUST be supported. Client 352 authentication SHOULD NOT be used. 354 4.2.2. HTTP Message Binding 356 All messages are exchanged as HTTP POST transactions. Support for 357 and use of HTTP/1.1 [RFC7230] is REQUIRED. Services MAY support 358 HTTP/2. 360 In contrast to other approaches to the design of Web Services, the 361 only use made of the HTTP transport is to distinguish between 362 different services on the same host using the Host header and .well- 363 known convention and for message framing. No use is made of the URI 364 request line to identify commands, nor are the caching or proxy 365 capabilities of HTTP made use of. 367 4.2.3. Request 369 The HTTP request MAY contain any valid HTTP header specified in 370 [RFC7230] . 372 Request Line URI /well-known/ (unless overridden using a 373 TXT path attribute) 375 Request Line Method POST 377 Host: Header 379 Content-Encoding As specified in section yy below. 381 Content-Type As specified in section zz below. 383 Content-Length or Transfer-Encoding As specified in [RFC7230] . 385 Payload The content payload as specified in section XX below. 387 [Note, this is showing the payload, not the binding as is intended 388 because the current code doesn't implement it as intended yet] 390 { 391 "Hello": {}} 393 4.2.4. Response 395 The response MAY contain any HTTP response header but since JWB 396 services do not make use of HTTP caching and messages are not 397 intended to be modified by HTTP intermediaries, only a limited number 398 of headers have significance: 400 Response Code The HTTP response code. This is processed as 401 described in section zz below. 403 Content-Type As specified in section zz below. 405 Content-Length or Transfer-Encoding As specified in [RFC7230] . 407 Cache-Control Since the only valid HTTP method for a JWB request is 408 POST, JWB responses are not cacheable. The use of the cache- 409 control header is therefore unnecessary. However, experience 410 suggests that reviewers find it easier to understand protocol 411 specifications if they are reminded of the fact that caching is 412 neither supported nor desired. 414 [Note, this is showing the payload, not the binding as is intended 415 because the current code doesn't implement it as intended yet] 417 { 418 "MeshHelloResponse": { 419 "Status": 201, 420 "Version": { 421 "Major": 3, 422 "Minor": 0, 423 "Encodings": [{ 424 "ID": ["application/json"]}]}, 425 "EnvelopedProfileService": [{ 426 "dig": "S512"}, 427 "ewogICJQcm9maWxlU2VydmljZSI6IHsKICAgICJLZXlPZmZsaW5lU2l 428 nbmF0dXJlIjogewogICAgICAiVURGIjogIk1BNk0tSEJDQy1DMktULVJJSDctV 429 kZZQy1YSTVXLTJUV1kiLAogICAgICAiUHVibGljUGFyYW1ldGVycyI6IHsKICA 430 gICAgICAiUHVibGljS2V5RUNESCI6IHsKICAgICAgICAgICJjcnYiOiAiRWQ0N 431 DgiLAogICAgICAgICAgIlB1YmxpYyI6ICJtXy1ZbXZocnYzb0RlaHZtUEV2cGV 432 xcWd5c28xc2d3TUxOa3M5NTRXOTlnbm1sX2VGNlRzCiAgc01IaUhyZDJEcnFhb 433 EFHcXpjT1VDYi1BIn19fX19", 434 { 435 "signatures": [{ 436 "alg": "S512", 437 "kid": "MA6M-HBCC-C2KT-RIH7-VFYC-XI5W-2TWY", 438 "signature": "VvhWJdlvJvlLo_A5iY9K9Oedg44iv9gfwvcQ-ydez23a-aALL 439 r8ukcOLWXVYsCFd8mqfXAcDU3sAVs7UIox3HpHBFe0DCOA2yAUqEe1YMQYria- 440 THTQHxGC3tEU7LMICSWH0RUvRQtYwRPdJuCVbISoA"}], 441 "PayloadDigest": "ptw0BNt_3p5MUPYELmoe8SeLRKg0o4frMUL-43qbCQiY4 442 JJKPjR1jSNAjfZvRyWlxsMIoYcGAXmMPk-CqIbI4Q"}], 443 "EnvelopedProfileHost": [{ 444 "dig": "S512"}, 445 "ewogICJQcm9maWxlSG9zdCI6IHsKICAgICJLZXlPZmZsaW5lU2lnbmF 446 0dXJlIjogewogICAgICAiVURGIjogIk1DR0ctNktaWC1ESkFELVNMTlYtTDQ2S 447 C1QR1NPLUhSVzciLAogICAgICAiUHVibGljUGFyYW1ldGVycyI6IHsKICAgICA 448 gICAiUHVibGljS2V5RUNESCI6IHsKICAgICAgICAgICJjcnYiOiAiRWQ0NDgiL 449 AogICAgICAgICAgIlB1YmxpYyI6ICJDRC1ia3dIclp5TnVibk91bkFCNEJYeHd 450 XbjBmWFVDMVBMTlp1Q2RQQzJsUWFfZF9jTmNxCiAgcmh0U3J0OHdSbEgxdm9BX 451 0FteHBzQi1BIn19fSwKICAgICJLZXlBdXRoZW50aWNhdGlvbiI6IHsKICAgICA 452 gIlVERiI6ICJNQjRPLVlWU0wtNFhHWi1LSlRGLVpTVUstUzRVTy1VSFZTIiwKI 453 CAgICAgIlB1YmxpY1BhcmFtZXRlcnMiOiB7CiAgICAgICAgIlB1YmxpY0tleUV 454 DREgiOiB7CiAgICAgICAgICAiY3J2IjogIkVkNDQ4IiwKICAgICAgICAgICJQd 455 WJsaWMiOiAieV8tMDJZNmFaZ25fdkhZckRQU3ZxSlN6NzBLWHJHa25IWC1fMFZ 456 fZ2c2LTREN1NveFRjZgogIEM0LXUxbnBuRHlUamltbVZnVnY1cDNvQSJ9fX19f 457 Q", 458 { 459 "signatures": [{ 460 "alg": "S512", 461 "kid": "MCGG-6KZX-DJAD-SLNV-L46H-PGSO-HRW7", 462 "signature": "A-lgHnIUgGu43ceUOdAfHgC_EqzX2FC4Webm5aMwGeqpSad2l 463 Vtyw5FNCw-LEikhGcOBI7GQHBWAQo_jV5VUJW3euW1oO71N5GT_iFM9v99tA4- 464 lSirwQINFaQpCJloDw8vWBZ_KQkP30mfkKOQa0T8A"}], 465 "PayloadDigest": "wvwhuYak6oflca3tPJh4kYSDP8KiBl7rr1247gNEYjRCg 466 0YkFswLvB6TnyV1HZwoIdT3CectRkLOSr7StXUaXg"}]}} 468 4.3. DARE Message Encapsulation 470 The payload of the HTTP requests and responses is a DARE Message 471 whose payload contains the Mesh Service request or response. 473 The DARE Message encapsulation is used to authenticate the request or 474 response data. The form of the authentication depending on the 475 credentials available to the sender at the time the request is made. 477 Mesh Service MUST support the use of Mutually Authenticated Key 478 Exchange [draft-hallambaker-mesh-security] to establish the Master 479 Key used for authentication of requests and responses. 481 Requests and Responses MUST be authenticated. Requests and Responses 482 MUST be encrypted if the transport is not encrypted and MAY be 483 encrypted otherwise. 485 4.3.1. Null Authentication 487 Null Authentication MAY be used to make a Hello Request. 489 The Null Authentication mechanism MUST NOT be used for any Mesh 490 Service request or response other than a Hello request. 492 Since the Mutually Authenticated key exchange requires both parties 493 to know the public key of the other, it is not possible for a client 494 to authenticate itself to the service until it has obtained the 495 service public key. One means by which the client MAY obtain the 496 service public key is by requesting the service return the credential 497 in a Hello transaction. 499 4.3.2. Device Authentication 501 Device Authentication is used in two circumstances 503 o When requesting creation of an account 505 o When a device is requesting connection to a profile. 507 4.3.3. Profile Authentication 509 Profile Authentication has the same form as Device Authentication 510 except that the client provides its Device Connection Assertion as 511 part of the request: 513 4.3.4. Ticket Authentication 515 Ticket Authentication is used after a device has obtained an 516 authentication ticket from a service. The ticket is returned in the 517 response to a previous Profile Authentication exchange. 519 4.4. Payload Encoding 521 The Dare Message payload of a Hello request MUST be encoded in JSON 522 encoding. The payload of all other requests MUST be in either JSON 523 encoding or one of the encodings advertised as being accepted in a 524 Hello response from the Service. Services MUST accept JSON encoding 525 and MAY support the JSON-B or JSON-C encodings as specified in this 526 document. Services MUST generate a response that is compatible with 527 the DARE Message Content-Type specified in the request. 529 JSON was originally developed to provide a serialization format for 530 the JavaScript programming language [ECMA-262] . While this approach 531 is generally applicable to the type systems of scripting programming 532 languages, it is less well matched to the richer type systems of 533 modern object oriented programming languages such as Java and C#. 535 Working within a subset of the capabilities of JSON allows a Web 536 Service protocol to be accessed with equal ease from either platform 537 type. The following capabilities of JSON are avoided: 539 The ability to use arbitrary strings as field names. 541 The use of JSON objects to define maps directly 543 The following data field types are used: 545 Integer Integer values are encoded as JSON number values. 547 String Test strings are encoded as JSON text strings. 549 Boolean Boolean values are encoded as JSON 'false', 'true' or 'null' 550 tokens according to value. 552 Sequence Sequences of data items that are encoded as JSON arrays 554 Object of known type Objects whose type is known to the receiver are 555 encoded as JSON objects 557 Object of variable type Objects whose type is not known to the 558 receiver are encoded as JSON objects containing a single field 559 whose name describes the type of the object value and whose value 560 contains the value. 562 Binary Data Byte sequences are converted to BASE64-url encoding 563 [RFC4648] and encoded as JSON string values. 565 Date Time Date Time values are converted to Internet time format as 566 described in [RFC3339] and encoded as JSON string values. 568 4.5. Error handling and response codes 570 It is possible for an error to occur at any of the three layers in 571 the Web Service binding: 573 Service Layer 575 HTTP Layer 577 Transport Layer 579 Services SHOULD always attempt to return error codes at the highest 580 level possible. However, it is clearly impossible for a connection 581 that is refused at the Transport layer to return an error code at the 582 HTTP layer. It is however possible for a HTTP layer error response 583 to contain a content body. 585 In the case that a response contains both a HTTP response code and a 586 well-formed payload containing a response, the payload response SHALL 587 have precedence. 589 5. Service Description 591 The Hello transaction is used to determine the features supported by 592 the service and obtain the service credentials 594 The request payload: 596 { 597 "Hello": {}} 599 The response payload: 601 { 602 "MeshHelloResponse": { 603 "Status": 201, 604 "Version": { 605 "Major": 3, 606 "Minor": 0, 607 "Encodings": [{ 608 "ID": ["application/json"]}]}, 609 "EnvelopedProfileService": [{ 610 "dig": "S512"}, 611 "ewogICJQcm9maWxlU2VydmljZSI6IHsKICAgICJLZXlPZmZsaW5lU2l 612 nbmF0dXJlIjogewogICAgICAiVURGIjogIk1BNk0tSEJDQy1DMktULVJJSDctV 613 kZZQy1YSTVXLTJUV1kiLAogICAgICAiUHVibGljUGFyYW1ldGVycyI6IHsKICA 614 gICAgICAiUHVibGljS2V5RUNESCI6IHsKICAgICAgICAgICJjcnYiOiAiRWQ0N 615 DgiLAogICAgICAgICAgIlB1YmxpYyI6ICJtXy1ZbXZocnYzb0RlaHZtUEV2cGV 616 xcWd5c28xc2d3TUxOa3M5NTRXOTlnbm1sX2VGNlRzCiAgc01IaUhyZDJEcnFhb 617 EFHcXpjT1VDYi1BIn19fX19", 618 { 619 "signatures": [{ 620 "alg": "S512", 621 "kid": "MA6M-HBCC-C2KT-RIH7-VFYC-XI5W-2TWY", 622 "signature": "VvhWJdlvJvlLo_A5iY9K9Oedg44iv9gfwvcQ-ydez23a-aALL 623 r8ukcOLWXVYsCFd8mqfXAcDU3sAVs7UIox3HpHBFe0DCOA2yAUqEe1YMQYria- 624 THTQHxGC3tEU7LMICSWH0RUvRQtYwRPdJuCVbISoA"}], 625 "PayloadDigest": "ptw0BNt_3p5MUPYELmoe8SeLRKg0o4frMUL-43qbCQiY4 626 JJKPjR1jSNAjfZvRyWlxsMIoYcGAXmMPk-CqIbI4Q"}], 627 "EnvelopedProfileHost": [{ 628 "dig": "S512"}, 629 "ewogICJQcm9maWxlSG9zdCI6IHsKICAgICJLZXlPZmZsaW5lU2lnbmF 630 0dXJlIjogewogICAgICAiVURGIjogIk1DR0ctNktaWC1ESkFELVNMTlYtTDQ2S 631 C1QR1NPLUhSVzciLAogICAgICAiUHVibGljUGFyYW1ldGVycyI6IHsKICAgICA 632 gICAiUHVibGljS2V5RUNESCI6IHsKICAgICAgICAgICJjcnYiOiAiRWQ0NDgiL 633 AogICAgICAgICAgIlB1YmxpYyI6ICJDRC1ia3dIclp5TnVibk91bkFCNEJYeHd 634 XbjBmWFVDMVBMTlp1Q2RQQzJsUWFfZF9jTmNxCiAgcmh0U3J0OHdSbEgxdm9BX 635 0FteHBzQi1BIn19fSwKICAgICJLZXlBdXRoZW50aWNhdGlvbiI6IHsKICAgICA 636 gIlVERiI6ICJNQjRPLVlWU0wtNFhHWi1LSlRGLVpTVUstUzRVTy1VSFZTIiwKI 637 CAgICAgIlB1YmxpY1BhcmFtZXRlcnMiOiB7CiAgICAgICAgIlB1YmxpY0tleUV 638 DREgiOiB7CiAgICAgICAgICAiY3J2IjogIkVkNDQ4IiwKICAgICAgICAgICJQd 639 WJsaWMiOiAieV8tMDJZNmFaZ25fdkhZckRQU3ZxSlN6NzBLWHJHa25IWC1fMFZ 640 fZ2c2LTREN1NveFRjZgogIEM0LXUxbnBuRHlUamltbVZnVnY1cDNvQSJ9fX19f 641 Q", 642 { 643 "signatures": [{ 644 "alg": "S512", 645 "kid": "MCGG-6KZX-DJAD-SLNV-L46H-PGSO-HRW7", 646 "signature": "A-lgHnIUgGu43ceUOdAfHgC_EqzX2FC4Webm5aMwGeqpSad2l 647 Vtyw5FNCw-LEikhGcOBI7GQHBWAQo_jV5VUJW3euW1oO71N5GT_iFM9v99tA4- 648 lSirwQINFaQpCJloDw8vWBZ_KQkP30mfkKOQa0T8A"}], 649 "PayloadDigest": "wvwhuYak6oflca3tPJh4kYSDP8KiBl7rr1247gNEYjRCg 650 0YkFswLvB6TnyV1HZwoIdT3CectRkLOSr7StXUaXg"}]}} 652 6. Account Management 654 A Mesh Account is bound to a Mesh Service by completing a 655 CreateAccount transaction with the service. 657 The client requesting the account creation specifies the ProfileMesh 658 profile describing the requested account and lists of initial entries 659 to populate the devices and contacts catalogs. Additional catalogs 660 MAY be synchronized if the account creation request is accepted. 662 The request payload: 664 { 665 "CreateAccount": { 666 "ServiceID": "alice@example.com", 667 "SignedProfileMesh": [{ 668 "dig": "S512"}, 670 "ewogICJQcm9maWxlTWVzaCI6IHsKICAgICJLZXlPZmZsaW5lU2lnbmF 671 0dXJlIjogewogICAgICAiVURGIjogIk1BWk0tRVFQQi1ZNkJZLUIzVzQtNlFaU 672 y1DSkVTLVFMVFIiLAogICAgICAiUHVibGljUGFyYW1ldGVycyI6IHsKICAgICA 673 gICAiUHVibGljS2V5RUNESCI6IHsKICAgICAgICAgICJjcnYiOiAiRWQ0NDgiL 674 AogICAgICAgICAgIlB1YmxpYyI6ICJfbFpqSmoyZC0zMXd1LW5LdWFlWUoyUld 675 NSmszenplWjF6MUFsMnc1czBFV0tZUVMzUDhOCiAgc1dKWGVNV1hKR3R5eldKO 676 DRESGp4NXdBIn19fSwKICAgICJLZXlzT25saW5lU2lnbmF0dXJlIjogW3sKICA 677 gICAgICAiVURGIjogIk1DQUQtTzRZUy1GT0s3LVRKU0ktVVBPVC1FWDZULVhIU 678 zUiLAogICAgICAgICJQdWJsaWNQYXJhbWV0ZXJzIjogewogICAgICAgICAgIlB 679 1YmxpY0tleUVDREgiOiB7CiAgICAgICAgICAgICJjcnYiOiAiRWQ0NDgiLAogI 680 CAgICAgICAgICAiUHVibGljIjogIi1vb3ZwYzNJdGFhUDlwMmRZczdqcW8zUnI 681 wQkp5YTg3NW11UFM4cVZIc1ppaFltTzhSdDkKICB4UjAwaVViN19BcTFUQzFXc 682 zJNeG9Jb0EifX19XSwKICAgICJLZXlFbmNyeXB0aW9uIjogewogICAgICAiVUR 683 GIjogIk1BTE0tTFBBNy0zNkNOLUtDWVItVFpRVC1ZMkZGLVFOT1IiLAogICAgI 684 CAiUHVibGljUGFyYW1ldGVycyI6IHsKICAgICAgICAiUHVibGljS2V5RUNESCI 685 6IHsKICAgICAgICAgICJjcnYiOiAiRWQ0NDgiLAogICAgICAgICAgIlB1YmxpY 686 yI6ICJiUFFjVE1wVUtNUnhZUzJqemRGM1NhNmhQWnF4U05iWFh2a0dXNVowVWx 687 meS0xRkF0TkdpCiAgUldHREFfY05GNGJfV00xWjg4RlBldktBIn19fX19", 688 { 689 "signatures": [{ 690 "alg": "S512", 691 "kid": "MAZM-EQPB-Y6BY-B3W4-6QZS-CJES-QLTR", 692 "signature": "oDS89V8WumsdjG4JCkylsIhCxV2Fi-u5rSiA6cxvNn97CUdD0 693 w3FzLlo4qc_Bt51TZ0RjRc_JOaAP0eX_udrV9tRW5z85w4ULjHD8mcqTjPw--M 694 JvGls5DgOFilGAtN8QFeri7OUiBipmhpScFPiAjUA"}], 695 "PayloadDigest": "FX_G1V53MWl_tZHwD1o4Stfc4NJ-IcNn-2VhrO7jZ77CH 696 yL71DF-skE0hiU8TgKtAhX_y8yYPKQ66bubcYBBcg"}], 697 "SignedAssertionAccount": [{ 698 "dig": "S512"}, 699 "ewogICJQcm9maWxlQWNjb3VudCI6IHsKICAgICJLZXlPZmZsaW5lU2l 700 nbmF0dXJlIjogewogICAgICAiVURGIjogIk1EWDctNERNWS02RktYLU5aMlgtV 701 klLRC1HTDRXLVc1UE8iLAogICAgICAiUHVibGljUGFyYW1ldGVycyI6IHsKICA 702 gICAgICAiUHVibGljS2V5RUNESCI6IHsKICAgICAgICAgICJjcnYiOiAiRWQ0N 703 DgiLAogICAgICAgICAgIlB1YmxpYyI6ICJ1VXRkMzN4b0FyX293bXNRZm5YVGp 704 pdUtsWTBvcHZfaFphdF9TU2d5N2c2a3g5Yl90cHdmCiAgcFZpNVAtTEV4eXlne 705 jhRVElxOVJmUTBBIn19fSwKICAgICJLZXlzT25saW5lU2lnbmF0dXJlIjogW3s 706 KICAgICAgICAiVURGIjogIk1DNkQtRUZXSy03Q0tTLVNWSzQtUk9IVi01MlhBL 707 UtQRkUiLAogICAgICAgICJQdWJsaWNQYXJhbWV0ZXJzIjogewogICAgICAgICA 708 gIlB1YmxpY0tleUVDREgiOiB7CiAgICAgICAgICAgICJjcnYiOiAiRWQ0NDgiL 709 AogICAgICAgICAgICAiUHVibGljIjogInlVR0I5bjhHclZadW4ycnZuUEdKdmU 710 3T3JDejI4enlsakVDbjlycU1hVkk3VV9BNlQ3bHcKICBWUVcxcmc3UTFkVVZTa 711 Hl5MFIySXVOb0EifX19XSwKICAgICJTZXJ2aWNlSURzIjogWyJhbGljZUBleGF 712 tcGxlLmNvbSJdLAogICAgIk1lc2hQcm9maWxlVURGIjogIk1BWk0tRVFQQi1ZN 713 kJZLUIzVzQtNlFaUy1DSkVTLVFMVFIiLAogICAgIktleUVuY3J5cHRpb24iOiB 714 7CiAgICAgICJVREYiOiAiTUNDWi1aV1dSLUxQVVktR1VFSy1FQk02LVNZS1AtS 715 0pIQSIsCiAgICAgICJQdWJsaWNQYXJhbWV0ZXJzIjogewogICAgICAgICJQdWJ 716 saWNLZXlFQ0RIIjogewogICAgICAgICAgImNydiI6ICJFZDQ0OCIsCiAgICAgI 717 CAgICAiUHVibGljIjogIm5HMkowS0hSeENzZmJMb2JSUW9iWGZnZ1FWZVBFVjF 718 vd0Vka3Y5R3RXaWhnQVR3N0Zzc1IKICBDelBHNnFfaFE0YTd4ei1NU0xqRjNTZ 719 0EifX19fX0", 720 { 721 "signatures": [{ 722 "alg": "S512", 723 "kid": "MCAD-O4YS-FOK7-TJSI-UPOT-EX6T-XHS5", 724 "signature": "AQKCDz1mw4wRebixv3N72yz46kz-Wx_NfzEsI7kG9w5Extnvt 725 rleMy8c9Y3X781uoSOf31dJKiMAdVU2RdYXyhaKohIp3ImKKmi9yIq00LH7ptZ 726 jGdZsn6Mc1lx59qVwqpQwbAC__hU9ONFJYnsXUg4A"}], 727 "PayloadDigest": "qB_IQ4LgFEMPdqmYTBH0ISjSXx3a2HFez3PKWO7A88wCl 728 XBK2minR4PrQnCC-bfbvRrZVfm6SekjlV48Ho6gaA"}]}} 730 The response payload: 732 { 733 "CreateResponse": { 734 "Status": 201, 735 "StatusDescription": "Operation completed successfully"}} 737 An account registration is deleted using the DeleteAccount 738 transaction. 740 7. Container Synchronization 742 All the state associated with a Mesh profile is stored as a sequence 743 of DARE Messages in a Dare Container. The Mesh Service holding the 744 master copy of the persistence stores and the devices connected to 745 the profile containing complete copies (replicas) or partial copies 746 (redactions). 748 Thus, the only primitive needed to achieve synchronization of the 749 profile state are those required for synchronization of a DARE 750 Container. These steps are: 752 o Obtain the status of the catalogs and spools associated with the 753 account. 755 o Download catalog and spool updates 757 o Upload catalog updates. 759 To ensure a satisfactory user experience, Mesh Messages are 760 intentionally limited in size to 64 KB or less, thus ensuring that an 761 application can retrieve the most recent 100 messages almost 762 instantaneously on a high bandwidth connection and without undue 763 delay on a slower one. 765 7.1. Status Transaction 767 The status transaction returns the status of the containers the 768 device is authorized to access for the specified account together 769 with the updated Device Connection Entry if this has been modified 770 since the entry presented to authenticate the request was issued. 772 7.2. Download Transaction 774 The download transaction returns a collection of entries from one or 775 more containers associated with the profile. 777 Optional filtering criteria MAY be specified to only return objects 778 matching specific criteria and/or only return certain parts of the 779 selected messages. 781 The service MAY limit the number of entries returned in an individual 782 response for performance reasons. 784 7.2.1. Conflict Detection 786 Clients SHOULD check to determine if updates to a container conflict 787 with pending updates on the device waiting to be uploaded. For 788 example, if a contact that the user modified on the device attempting 789 to synchronize was subsequently deleted. 791 The means of resolving such conflicts is not in the scope of this 792 specification. 794 7.2.2. Filtering 796 Clients may request container updates be filtered to redact catalog 797 entries that have been updated or deleted or spool entries that have 798 been read, deleted or were received before a certain date. 800 7.3. Upload Transaction 802 The upload transaction upload objects to a catalog or spool. 804 Multiple objects MAY be uploaded at once. Object updates MAY be 805 conditional on the successful completion of other upload requests. 807 The transaction MAY be performed in one request/response round trip 808 or with separate round trips to confirm that the transaction is 809 accepted by the service before sending large number of updates. 811 8. Device Connection 813 Devices request connection to a Mesh profile using the Connect 814 transaction. Three connection mechanisms are currently defined. All 815 three of which offer strong mutual authentication. 817 Device Authenticated 819 Pin Authenticated 821 EARL Connection Mode 823 The first two of these mechanisms are initiated from the device being 824 connected which requires that the Mesh Service Account it is being 825 connected to be entered into it. Use of these mechanisms thus 826 requires keyboard and display affordances or accessibility 827 equivalents. 829 The last mechanism is initiated from an administration device that is 830 already connected to the account. It is intended for use in 831 circumstances where the device being connected does not have the 832 necessary affordances to allow the Device or PIN authenticated modes. 834 In either case, the connection request is completed by the device 835 requesting synchronization with the Mesh Account using its device 836 credential for authentication. If the connection request was 837 accepted, the device will be provisioned with the Device Connection 838 Assertion allowing it to complete the process. 840 The Device Connection Assertion includes an overlay device profile 841 containing a set of private key contributions to be used to perform 842 key cogeneration on the original set of device keys to create a new 843 device profile to be used for all purposes associated with the Mesh 844 Profile to which it has just been connected. This assures the user 845 that the keys the device uses for performing operation in the context 846 of their profile are not affected by any compromise that might have 847 occurred during manufacture or at any point after up to the time it 848 was connected to their profile. 850 8.1. Device Authenticated 852 The direct connection mechanism requires that both the administration 853 device and the device originating the connection request have data 854 entry and output affordances and that it is possible for the user to 855 compare the authentication codes presented by the two devices to 856 check that they are identical. 858 8.2. PIN Authenticated 860 The PIN Connection mechanism is similar to the Direct connection 861 mechanism except that the process is initiated on an administration 862 device by requesting assignment of a new authentication PIN. The PIN 863 is then input to the connecting device to authenticate the request. 865 8.3. EARL connection mode 867 The EARL/QR code connection mechanisms are used to connect a 868 constrained device to a Mesh profile by means of an Encrypted 869 Authenticated Resource Locator, typically presented as a QR code on 870 the device itself or its packaging. 872 9. Mesh Messaging 874 Mesh Messages provide a means of communication between Mesh Service 875 Accounts with capabilities that are not possible or poorly supported 876 in traditional SMTP mail messaging: 878 o End-to-end confidentiality and authentication by default. 880 o Abuse mitigation by applying access control to every inbound and 881 outbound message. 883 o End-to-end secure group messaging. 885 o Transfer of very large data sets (Terabytes). 887 Note that although Mesh Messaging is designed to facilitate the 888 transfer of very large data sets, the size of Mesh Messages 889 themselves is severely restricted. The current default maximum size 890 being 64 KB. This approach allows Mesh 892 In addition, the platform anticipates but does not currently support 893 additional cryptographic security capabilities: 895 o Traffic analysis resistance using mix networks (Chaum). 897 o Simultaneous contract binding using fair contract signing 898 (Micali). 900 While these capabilities might in time cause Mesh Messaging to 901 replace SMTP, this is not a near term goal. The short-term goal of 902 Mesh Messaging is to support the Contact Exchange and Confirmation 903 applications. 905 Two important classes of application that are not currently supported 906 directly are payments and presence. While prototypes of these 907 applications have been considered, it is not clear if these are best 908 implemented as special cases of the Confirmation and Contact Exchange 909 applications or as separate applications in their own right. 911 9.1. Message Exchange 913 To enable effective abuse mitigation, Mesh Messaging enforces a four 914 corner communication model in which all outbound and inbound messages 915 pass through a Mesh Service which accredits and authorizes the 916 messages on the user's behalf. 918 [[This figure is not viewable in this format. The figure is 919 available at http://mathmesh.com/Documents/draft-hallambaker-mesh- 920 protocol.html [2].]] 922 The Post transaction is used for client-service and service-service 923 messaging transactions. 925 9.1.1. Client-Service (Post Transaction) 927 To send a message, the client creates the Mesh Message structure, 928 encapsulates it in a DARE Message and forwards this to its service 929 using a Post transaction. 931 The Post transaction is authenticated to the service by device using 932 the usual means of profile or ticket authentication. 934 The DARE Message MUST be signed under a device signature key 935 accredited by a Device Connection Assertion provided in the message 936 signature block. 938 9.1.2. Service-Service (Post Transaction) 940 The Mesh Service receiving the message from the user's device MAY 941 attempt immediate retransmission or queue it to be sent at a future 942 time. Mesh Services SHOULD forward messages without undue delay. 944 The Post transaction forwarding the message to the destination 945 service carries the same payload as the original request but is 946 authenticated by the service forwarding it. This authentication MAY 947 be my means of either profile or ticket authentication. 949 9.1.2.1. Denial of Service Mitigation 951 Services SHOULD implement Denial of Service mitigation strategies 952 including limiting the maximum time taken to complete a transaction 953 and refusing connections from clients that engage in patterns of 954 behavior consistent with abuse. 956 The limitation in message size allows Mesh Services to aggressively 957 time out connections that take too long to complete a transaction. A 958 Mesh Service that hosted on a 10Mb/s link should be able to transfer 959 20 messages a second. If the service is taking more than 5 seconds 960 to complete a transaction, either the source or the destination 961 service is overloaded or the message itself is an attack. 963 Imposing hard constraints on Mesh Service performance requires 964 deployments to scale and apply resources appropriately. If a service 965 is attempting to transfer 100 messages simultaneously and 40% are 966 taking 4 seconds or more, this indicates that the number of 967 simultaneous transfers being attempted should be reduced. 968 Contrawise, if 90% are completinin less than a second, the number of 969 threads allocated to sending outbound messages might be increased. 971 9.1.2.2. Access Control 973 The inbound service MUST subject inbound messages to Access Control 974 according to the credentials presented in the DARE Message payload. 976 After verifying the signature and checking that the key is properly 977 accredited in accordance with site policy, the service applies 978 authorization controls taking account of: 980 o The accreditation of the sender 982 o The accreditation of the transmitting Service 984 o The type of Mesh Message being sent 986 o User policy as specified in their Contact Catalog 988 o Site policy. 990 9.1.3. Service-Client (Synchronization) 992 The final recipient receives the message by synchronizing their 993 inbound spool. 995 10. Protocol Schema 997 HTTP Well Known Service Prefix: /.well-known/mmm 999 Every Mesh Portal Service transaction consists of exactly one request 1000 followed by exactly one response. Mesh Service transactions MAY 1001 cause modification of the data stored in the Mesh Service or the Mesh 1002 itself but do not cause changes to the connection state. The 1003 protocol itself is thus idempotent. There is no set sequence in 1004 which operations are required to be performed. It is not necessary 1005 to perform a Hello transaction prior to any other transaction. 1007 10.1. Request Messages 1009 A Mesh Portal Service request consists of a payload object that 1010 inherits from the MeshRequest class. When using the HTTP binding, 1011 the request MUST specify the portal DNS address in the HTTP Host 1012 field. 1014 10.1.1. Message: MeshRequest 1016 Base class for all request messages. 1018 [No fields] 1020 10.1.2. Message: MeshRequestUser 1022 Base class for all request messages made by a user. 1024 Inherits: MeshRequest 1026 Inherits: MeshRequest 1028 Account: String (Optional) The fully qualified account name 1029 (including DNS address) to which the request is directed. 1031 DeviceProfile: DareEnvelope (Optional) Device profile of the device 1032 making the request. 1034 10.2. Response Messages 1036 A Mesh Portal Service response consists of a payload object that 1037 inherits from the MeshResponse class. When using the HTTP binding, 1038 the response SHOULD report the Status response code in the HTTP 1039 response message. However the response code returned in the payload 1040 object MUST always be considered authoritative. 1042 10.2.1. Message: MeshResponse 1044 Base class for all response messages. Contains only the status code 1045 and status description fields. 1047 [No fields] 1049 10.3. Imported Objects 1051 The Mesh Service protocol makes use of JSON objects defined in the 1052 JOSE Signatgure and Encryption specifications and in the DARE Data At 1053 Rest Encryption extensions to JOSE. 1055 10.4. Common Structures 1057 The following common structures are used in the protocol messages: 1059 10.4.1. Structure: KeyValue 1061 Describes a Key/Value structure used to make queries for records 1062 matching one or more selection criteria. 1064 Key: String (Optional) The data retrieval key. 1066 Value: String (Optional) The data value to match. 1068 10.4.2. Structure: ConstraintsSelect 1070 Specifies constraints to be applied to a search result. These allow 1071 a client to limit the number of records returned, the quantity of 1072 data returned, the earliest and latest data returned, etc. 1074 Container: String (Optional) The container to be searched. 1076 IndexMin: Integer (Optional) Only return objects with an index value 1077 that is equal to or higher than the value specified. 1079 IndexMax: Integer (Optional) Only return objects with an index value 1080 that is equal to or lower than the value specified. 1082 NotBefore: DateTime (Optional) Only data published on or after the 1083 specified time instant is requested. 1085 Before: DateTime (Optional) Only data published before the specified 1086 time instant is requested. This excludes data published at the 1087 specified time instant. 1089 PageKey: String (Optional) Specifies a page key returned in a 1090 previous search operation in which the number of responses 1091 exceeded the specified bounds. 1093 When a page key is specified, all the other search parameters 1094 except for MaxEntries and MaxBytes are ignored and the service 1095 returns the next set of data responding to the earlier query. 1097 10.4.3. Structure: ConstraintsData 1099 Specifies constraints on the data to be sent. 1101 MaxEntries: Integer (Optional) Maximum number of entries to send. 1103 BytesOffset: Integer (Optional) Specifies an offset to be applied to 1104 the payload data before it is sent. This allows large payloads to 1105 be transferred incrementally. 1107 BytesMax: Integer (Optional) Maximum number of payload bytes to 1108 send. 1110 Header: Boolean (Optional) Return the entry header 1112 Payload: Boolean (Optional) Return the entry payload 1114 Trailer: Boolean (Optional) Return the entry trailer 1116 10.4.4. Structure: PolicyAccount 1118 Describes the account creation policy including constraints on 1119 account names, whether there is an open account creation policy, etc. 1121 Minimum: Integer (Optional) Specifies the minimum length of an 1122 account name. 1124 Maximum: Integer (Optional) Specifies the maximum length of an 1125 account name. 1127 InvalidCharacters: String (Optional) A list of characters that the 1128 service does not accept in account names. The list of characters 1129 MAY not be exhaustive but SHOULD include any illegal characters in 1130 the proposed account name. 1132 10.4.5. Structure: ContainerStatus 1134 Container: String (Optional) 1136 Container: String (Optional) 1137 Index: Integer (Optional) 1139 Index: Integer (Optional) 1141 Digest: Binary (Optional) 1143 10.4.6. Structure: ContainerUpdate 1145 Inherits: ContainerStatus 1147 Inherits: ContainerStatus 1149 Envelopes: DareEnvelope [0..Many] The entries to be uploaded. 1151 10.5. Transaction: Hello 1153 Request: HelloRequest 1155 Request: HelloRequest 1157 Response: MeshHelloResponse 1159 Report service and version information. 1161 The Hello transaction provides a means of determining which protocol 1162 versions, message encodings and transport protocols are supported by 1163 the service. 1165 The PostConstraints field MAY be used to advise senders of a maximum 1166 size of payload that MAY be sent in an initial Post request. 1168 10.5.1. Message: MeshHelloResponse 1170 ConstraintsUpdate: ConstraintsData (Optional) Specifies the default 1171 data constraints for updates. 1173 ConstraintsPost: ConstraintsData (Optional) Specifies the default 1174 data constraints for message senders. 1176 PolicyAccount: PolicyAccount (Optional) Specifies the account 1177 creation policy 1179 EnvelopedProfileService: DareEnvelope (Optional) The enveloped 1180 master profile of the service. 1182 EnvelopedProfileHost: DareEnvelope (Optional) The enveloped profile 1183 of the host. 1185 10.6. Transaction: Complete 1187 Request: CompleteRequest 1189 Request: CompleteRequest 1191 Response: StatusResponse 1193 10.6.1. Message: CompleteRequest 1195 Inherits: StatusRequest 1197 Inherits: StatusRequest 1199 ServiceID: String (Optional) 1201 10.7. Transaction: Status 1203 Request: StatusRequest 1205 Request: StatusRequest 1207 Response: StatusResponse 1209 10.7.1. Message: StatusRequest 1211 Inherits: MeshRequestUser 1213 Inherits: MeshRequestUser 1215 DeviceUDF: String (Optional) 1217 DeviceUDF: String (Optional) 1219 ProfileMasterDigest: Binary (Optional) 1221 ProfileMasterDigest: Binary (Optional) 1223 Catalogs: String [0..Many] 1225 Catalogs: String [0..Many] 1227 Spools: String [0..Many] 1229 10.7.2. Message: StatusResponse 1231 Inherits: MeshResponse 1233 Inherits: MeshResponse 1235 EnvelopedProfileMaster: DareEnvelope (Optional) The master profile 1236 that provides the root of trust for this Mesh 1238 EnvelopedCatalogEntryDevice: DareEnvelope (Optional) The catalog 1239 device entry 1241 ContainerStatus: ContainerStatus [0..Many] 1243 10.8. Transaction: Download 1245 Request: DownloadRequest 1247 Request: DownloadRequest 1249 Response: DownloadResponse 1251 Request objects from the specified container with the specified 1252 search criteria. 1254 10.8.1. Message: DownloadRequest 1256 Inherits: MeshRequestUser 1258 Request objects from the specified container(s). 1260 A client MAY request only objects matching specified search criteria 1261 be returned and MAY request that only specific fields or parts of the 1262 payload be returned. 1264 Select: ConstraintsSelect [0..Many] Specifies constraints to be 1265 applied to a search result. These allow a client to limit the 1266 number of records returned, the quantity of data returned, the 1267 earliest and latest data returned, etc. 1269 ConstraintsPost: ConstraintsData (Optional) Specifies the data 1270 constraints to be applied to the responses. 1272 10.8.2. Message: DownloadResponse 1274 Inherits: MeshResponse 1276 Return the set of objects requested. 1278 Services SHOULD NOT return a response that is disproportionately 1279 large relative to the speed of the network connection without a clear 1280 indication from the client that it is relevant. A service MAY limit 1281 the number of objects returned. A service MAY limit the scope of 1282 each response. 1284 Updates: ContainerUpdate [0..Many] The updated data 1286 10.9. Transaction: Upload 1288 Request: UploadRequest 1290 Request: UploadRequest 1292 Response: UploadResponse 1294 Request objects from the specified container with the specified 1295 search criteria. 1297 10.9.1. Message: UploadRequest 1299 Inherits: MeshRequestUser 1301 Upload entries to a container. This request is only valid if it is 1302 issued by the owner of the account 1304 Updates: ContainerUpdate [0..Many] The data to be updated 1306 Self: DareEnvelope [0..Many] Entries to be added to the inbound 1307 spool on the account, e.g. completion messages. 1309 10.9.2. Message: UploadResponse 1311 Inherits: MeshResponse 1313 Response to an upload request. 1315 Entries: EntryResponse [0..Many] The responses to the entries. 1317 ConstraintsData: ConstraintsData (Optional) If the upload request 1318 contains redacted entries, specifies constraints that apply to the 1319 redacted entries as a group. Thus the total payloads of all the 1320 messages must not exceed the specified value. 1322 10.9.3. Structure: EntryResponse 1324 IndexRequest: Integer (Optional) The index value of the entry in the 1325 request. 1327 IndexContainer: Integer (Optional) The index value assigned to the 1328 entry in the container. 1330 Result: String (Optional) Specifies the result of attempting to add 1331 the entry to a catalog or spool. Valid values for a message are 1332 'Accept', 'Reject'. Valid values for an entry are 'Accept', 1333 'Reject' and 'Conflict'. 1335 ConstraintsData: ConstraintsData (Optional) If the entry was 1336 redacted, specifies constraints that apply to the redacted entries 1337 as a group. Thus the total payloads of all the messages must not 1338 exceed the specified value. 1340 10.10. Transaction: Post 1342 Request: PostRequest 1344 Request: PostRequest 1346 Response: PostResponse 1348 Request to post to a spool from an external party. The request and 1349 response messages are extensions of the corresponding messages for 1350 the Upload transaction. It is expected that additional fields will 1351 be added as the need arises. 1353 10.10.1. Message: PostRequest 1355 Inherits: MeshRequest 1357 Inherits: MeshRequest 1359 Accounts: String [0..Many] The account(s) to which the request is 1360 directed. 1362 Message: DareEnvelope [0..Many] The entries to be uploaded. These 1363 MAY be either complete messages or redacted messages. In either 1364 case, the messages MUST conform to the ConstraintsUpdate specified 1365 by the service 1367 Self: DareEnvelope [0..Many] Messages to be appended to the user's 1368 self spool. this is typically used to post notifications to the 1369 user to mark messages as having been read or responded to. 1371 10.10.2. Message: PostResponse 1373 Inherits: UploadResponse 1375 [No fields] 1377 10.11. Transaction: Connect 1379 Request: ConnectRequest 1381 Request: ConnectRequest 1383 Response: ConnectResponse 1385 Request information necessary to begin making a connection request. 1387 10.11.1. Message: ConnectRequest 1389 Inherits: MeshRequest 1391 Inherits: MeshRequest 1393 MessageConnectionRequestClient: DareEnvelope (Optional) The 1394 connection request generated by the client 1396 10.11.2. Message: ConnectResponse 1398 Inherits: MeshResponse 1400 Inherits: MeshResponse 1402 EnvelopedConnectionResponse: DareEnvelope (Optional) The connection 1403 request generated by the client 1405 EnvelopedProfileMaster: DareEnvelope (Optional) The master profile 1406 that provides the root of trust for this Mesh 1408 EnvelopedAccountAssertion: DareEnvelope (Optional) The current 1409 account assertion 1411 10.12. Transaction: CreateAccount 1413 Request: CreateRequest 1415 Request: CreateRequest 1417 Response: CreateResponse 1418 Request creation of a new service account. 1420 Attempt 1422 10.12.1. Message: CreateRequest 1424 Request binding of an account to a service address. 1426 Inherits: MeshRequest 1428 Inherits: MeshRequest 1430 ServiceID: String (Optional) The service account to bind to. 1432 SignedProfileMesh: DareEnvelope (Optional) The persistent profile 1433 that will be used to validate changes to the account assertion. 1435 SignedAssertionAccount: DareEnvelope (Optional) The signed assertion 1436 describing the account. 1438 10.12.2. Message: CreateResponse 1440 Inherits: MeshResponse 1442 Reports the success or failure of a Create transaction. 1444 Reason: String (Optional) Text explaining the status of the creation 1445 request. 1447 URL: String (Optional) A URL to which the user is directed to 1448 complete the account creation request. 1450 10.13. Transaction: DeleteAccount 1452 Request: DeleteRequest 1454 Request: DeleteRequest 1456 Response: DeleteResponse 1458 Request deletion of a new service account. 1460 Attempt 1462 10.13.1. Message: DeleteRequest 1464 Request creation of a new portal account. The request specifies the 1465 requested account identifier and the Mesh profile to be associated 1466 with the account. 1468 Inherits: MeshRequestUser 1470 [No fields] 1472 10.13.2. Message: DeleteResponse 1474 Inherits: MeshResponse 1476 Reports the success or failure of a Delete transaction. 1478 [No fields] 1480 11. Security Considerations 1482 The security considerations for use and implementation of Mesh 1483 services and applications are described in the Mesh Security 1484 Considerations guide [draft-hallambaker-mesh-security] . 1486 12. IANA Considerations 1488 All the IANA considerations for the Mesh documents are specified in 1489 this document 1491 13. Acknowledgements 1493 A list of people who have contributed to the design of the Mesh is 1494 presented in [draft-hallambaker-mesh-architecture] . 1496 14. References 1498 14.1. Normative References 1500 [draft-hallambaker-mesh-architecture] 1501 Hallam-Baker, P., "Mathematical Mesh 3.0 Part I: 1502 Architecture Guide", draft-hallambaker-mesh- 1503 architecture-10 (work in progress), August 2019. 1505 [draft-hallambaker-mesh-security] 1506 Hallam-Baker, P., "Mathematical Mesh Part VII: Security 1507 Considerations", draft-hallambaker-mesh-security-01 (work 1508 in progress), July 2019. 1510 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1511 Requirement Levels", BCP 14, RFC 2119, 1512 DOI 10.17487/RFC2119, March 1997. 1514 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1515 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002. 1517 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1518 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006. 1520 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1521 (HTTP/1.1): Message Syntax and Routing", RFC 7230, 1522 DOI 10.17487/RFC7230, June 2014. 1524 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1525 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018. 1527 14.2. Informative References 1529 [draft-hallambaker-mesh-developer] 1530 Hallam-Baker, P., "Mathematical Mesh: Reference 1531 Implementation", draft-hallambaker-mesh-developer-08 (work 1532 in progress), April 2019. 1534 [ECMA-262] 1535 Ecma International, "ECMAScript(R) 2017 Language 1536 Specification", June 2017. 1538 14.3. URIs 1540 [1] http://mathmesh.com/Documents/draft-hallambaker-mesh- 1541 protocol.html 1543 [2] http://mathmesh.com/Documents/draft-hallambaker-mesh- 1544 protocol.html 1546 Author's Address 1548 Phillip Hallam-Baker 1550 Email: phill@hallambaker.com