idnits 2.17.1 draft-hallambaker-mesh-protocol-06.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 : ---------------------------------------------------------------------------- ** The document seems to lack an Authors' Addresses Section. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (27 July 2020) is 1362 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group P. M. Hallam-Baker 3 Internet-Draft ThresholdSecrets.com 4 Intended status: Informational 27 July 2020 5 Expires: 28 January 2021 7 Mathematical Mesh 3.0 Part V: Protocol Reference 8 draft-hallambaker-mesh-protocol-06 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. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on 28 January 2021. 44 Copyright Notice 46 Copyright (c) 2020 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 51 license-info) in effect on the date of publication of this document. 52 Please review these documents carefully, as they describe your rights 53 and restrictions with respect to this document. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 58 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 2.1. Requirements Language . . . . . . . . . . . . . . . . . . 5 60 2.2. Defined Terms . . . . . . . . . . . . . . . . . . . . . . 5 61 2.3. Related Specifications . . . . . . . . . . . . . . . . . 6 62 2.4. Implementation Status . . . . . . . . . . . . . . . . . . 6 63 3. Mesh Service . . . . . . . . . . . . . . . . . . . . . . . . 6 64 3.1. Data Model . . . . . . . . . . . . . . . . . . . . . . . 7 65 3.2. Partitioning . . . . . . . . . . . . . . . . . . . . . . 7 66 4. Protocol Bindings . . . . . . . . . . . . . . . . . . . . . . 7 67 4.1. DNS Web Service Discovery . . . . . . . . . . . . . . . . 7 68 4.2. Web Service Protocol Binding . . . . . . . . . . . . . . 8 69 4.2.1. Transport Security . . . . . . . . . . . . . . . . . 8 70 4.2.2. HTTP Message Binding . . . . . . . . . . . . . . . . 8 71 4.2.3. Request . . . . . . . . . . . . . . . . . . . . . . . 9 72 4.2.4. Response . . . . . . . . . . . . . . . . . . . . . . 9 73 4.3. DARE Message Encapsulation . . . . . . . . . . . . . . . 11 74 4.3.1. Null Authentication . . . . . . . . . . . . . . . . . 11 75 4.3.2. Device Authentication . . . . . . . . . . . . . . . . 12 76 4.3.3. Profile Authentication . . . . . . . . . . . . . . . 12 77 4.3.4. Ticket Authentication . . . . . . . . . . . . . . . . 12 78 4.4. Payload Encoding . . . . . . . . . . . . . . . . . . . . 12 79 4.5. Error handling and response codes . . . . . . . . . . . . 13 80 5. Service Description . . . . . . . . . . . . . . . . . . . . . 13 81 6. Account Management . . . . . . . . . . . . . . . . . . . . . 15 82 7. Container Synchronization . . . . . . . . . . . . . . . . . . 17 83 7.1. Status Transaction . . . . . . . . . . . . . . . . . . . 17 84 7.2. Download Transaction . . . . . . . . . . . . . . . . . . 17 85 7.2.1. Conflict Detection . . . . . . . . . . . . . . . . . 18 86 7.2.2. Filtering . . . . . . . . . . . . . . . . . . . . . . 18 87 7.3. Upload Transaction . . . . . . . . . . . . . . . . . . . 18 88 8. Device Connection . . . . . . . . . . . . . . . . . . . . . . 18 89 8.1. Device Authenticated . . . . . . . . . . . . . . . . . . 19 90 8.2. PIN Authenticated . . . . . . . . . . . . . . . . . . . . 19 91 8.3. EARL connection mode . . . . . . . . . . . . . . . . . . 19 92 9. Mesh Messaging . . . . . . . . . . . . . . . . . . . . . . . 19 93 9.1. Message Exchange . . . . . . . . . . . . . . . . . . . . 20 94 9.1.1. Client-Service (Post Transaction) . . . . . . . . . . 21 95 9.1.2. Service-Service (Post Transaction) . . . . . . . . . 21 96 9.1.3. Service-Client (Synchronization) . . . . . . . . . . 22 98 10. Protocol Schema . . . . . . . . . . . . . . . . . . . . . . . 22 99 10.1. Request Messages . . . . . . . . . . . . . . . . . . . . 22 100 10.1.1. Message: MeshRequest . . . . . . . . . . . . . . . . 22 101 10.1.2. Message: MeshRequestUser . . . . . . . . . . . . . . 23 102 10.2. Response Messages . . . . . . . . . . . . . . . . . . . 23 103 10.2.1. Message: MeshResponse . . . . . . . . . . . . . . . 23 104 10.3. Imported Objects . . . . . . . . . . . . . . . . . . . . 23 105 10.4. Common Structures . . . . . . . . . . . . . . . . . . . 23 106 10.4.1. Structure: KeyValue . . . . . . . . . . . . . . . . 23 107 10.4.2. Structure: ConstraintsSelect . . . . . . . . . . . . 24 108 10.4.3. Structure: ConstraintsData . . . . . . . . . . . . . 24 109 10.4.4. Structure: PolicyAccount . . . . . . . . . . . . . . 25 110 10.4.5. Structure: ContainerStatus . . . . . . . . . . . . . 25 111 10.4.6. Structure: ContainerUpdate . . . . . . . . . . . . . 25 112 10.5. Transaction: Hello . . . . . . . . . . . . . . . . . . . 25 113 10.5.1. Message: MeshHelloResponse . . . . . . . . . . . . . 25 114 10.6. Transaction: CreateAccount . . . . . . . . . . . . . . . 26 115 10.6.1. Message: CreateRequest . . . . . . . . . . . . . . . 26 116 10.6.2. Message: CreateResponse . . . . . . . . . . . . . . 26 117 10.7. Transaction: DeleteAccount . . . . . . . . . . . . . . . 27 118 10.7.1. Message: DeleteRequest . . . . . . . . . . . . . . . 27 119 10.7.2. Message: DeleteResponse . . . . . . . . . . . . . . 27 120 10.8. Transaction: Complete . . . . . . . . . . . . . . . . . 27 121 10.8.1. Message: CompleteRequest . . . . . . . . . . . . . . 27 122 10.8.2. Message: CompleteResponse . . . . . . . . . . . . . 27 123 10.9. Transaction: Status . . . . . . . . . . . . . . . . . . 28 124 10.9.1. Message: StatusRequest . . . . . . . . . . . . . . . 28 125 10.9.2. Message: StatusResponse . . . . . . . . . . . . . . 28 126 10.10. Transaction: Download . . . . . . . . . . . . . . . . . 28 127 10.10.1. Message: DownloadRequest . . . . . . . . . . . . . 28 128 10.10.2. Message: DownloadResponse . . . . . . . . . . . . . 29 129 10.11. Transaction: Upload . . . . . . . . . . . . . . . . . . 29 130 10.11.1. Message: UploadRequest . . . . . . . . . . . . . . 29 131 10.11.2. Message: UploadResponse . . . . . . . . . . . . . . 29 132 10.11.3. Structure: EntryResponse . . . . . . . . . . . . . 30 133 10.12. Transaction: Publish . . . . . . . . . . . . . . . . . . 30 134 10.12.1. Message: PublishRequest . . . . . . . . . . . . . . 30 135 10.12.2. Message: PublishResponse . . . . . . . . . . . . . 30 136 10.13. Transaction: Post . . . . . . . . . . . . . . . . . . . 31 137 10.13.1. Message: PostRequest . . . . . . . . . . . . . . . 31 138 10.13.2. Message: PostResponse . . . . . . . . . . . . . . . 31 139 10.14. Transaction: Connect . . . . . . . . . . . . . . . . . . 31 140 10.14.1. Message: ConnectRequest . . . . . . . . . . . . . . 31 141 10.14.2. Message: ConnectResponse . . . . . . . . . . . . . 32 142 10.15. Transaction: Claim . . . . . . . . . . . . . . . . . . . 32 143 10.15.1. Message: ClaimRequest . . . . . . . . . . . . . . . 32 144 10.15.2. Message: ClaimResponse . . . . . . . . . . . . . . 32 145 10.16. Transaction: PollClaim . . . . . . . . . . . . . . . . . 32 146 10.16.1. Message: PollClaimRequest . . . . . . . . . . . . . 32 147 10.16.2. Message: PollClaimResponse . . . . . . . . . . . . 33 148 10.17. Transaction: CreateGroup . . . . . . . . . . . . . . . . 33 149 10.17.1. Message: CreateGroupRequest . . . . . . . . . . . . 33 150 10.17.2. Message: CreateGroupResponse . . . . . . . . . . . 33 151 10.17.3. Structure: CryptographicOperation . . . . . . . . . 33 152 10.17.4. Structure: CryptographicOperationSign . . . . . . . 33 153 10.17.5. Structure: CryptographicOperationKeyAgreement . . . 34 154 10.17.6. Structure: CryptographicOperationGenerate . . . . . 34 155 10.17.7. Structure: CryptographicOperationShare . . . . . . 34 156 10.17.8. Structure: CryptographicResult . . . . . . . . . . 34 157 10.17.9. Structure: CryptographicResultKeyAgreement . . . . 34 158 10.18. Transaction: Operate . . . . . . . . . . . . . . . . . . 34 159 10.18.1. Message: OperateRequest . . . . . . . . . . . . . . 34 160 10.18.2. Message: OperateResponse . . . . . . . . . . . . . 35 161 11. Security Considerations . . . . . . . . . . . . . . . . . . . 35 162 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 163 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 35 164 14. Normative References . . . . . . . . . . . . . . . . . . . . 35 165 15. Informative References . . . . . . . . . . . . . . . . . . . 36 167 1. Introduction 169 This document describes the Mesh Service protocol supported by Mesh 170 Services, an account-based protocol that facilitates exchange of data 171 between devices connected to a Mesh profile and between Mesh 172 accounts. 174 Mesh Service Accounts support the following services: 176 * Provides the master persistence store for the Catalogs and Spools 177 associated with the account. 179 * Enables synchronization of Catalogs and Spools with connected 180 devices. 182 * Enforces access control on inbound Mesh Messages from other users 183 and other Mesh Services. 185 * Authenticates outbound Mesh Messages, certifying that they comply 186 with abuse mitigation policies. 188 A Mesh Profile MAY be bound to multiple Mesh Service Accounts at the 189 same time but only one Mesh Service Account is considered to be 190 authoritative at a time. Users may add or remove Mesh Service 191 Accounts and change the account designated as authoritative at any 192 time. 194 The Mesh Services are build from a very small set of primitives which 195 provide a surprisingly extensive set of capabilities. These 196 primitives are: 198 "Hello" Describes the features and options provided by the service 199 and provides a 'null' transaction which MAY be used to establish 200 an authentication ticket without performing any action, 202 CreateAccount, DeleteAccount Manage the creation and deletion of 203 accounts at the service. 205 Status, Download, "Upload" Support synchronization of Mesh 206 containers between the service (Master) and the connected devices 207 (Replicas). 209 Connect Initiate the process of connecting a device to a Mesh 210 profile from the device itself. 212 Post Request that a Mesh Message be transferred to one or more Mesh 213 Accounts. 215 Although these functions could in principle be used to replace many 216 if not most existing Internet application protocols, the principal 217 value of any communication protocol lies in the size of the audience 218 it allows them to communicate with. Thus, while the Mesh Messaging 219 service is designed to support efficient and reliable transfer of 220 messages ranging in size from a few bytes to multiple terabytes, the 221 near-term applications of these services will be to applications that 222 are not adequately supported by existing protocols if at all. 224 2. Definitions 226 This section presents the related specifications and standard, the 227 terms that are used as terms of art within the documents and the 228 terms used as requirements language. 230 2.1. Requirements Language 232 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 233 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 234 document are to be interpreted as described in [RFC2119]. 236 2.2. Defined Terms 238 The terms of art used in this document are described in the _Mesh 239 Architecture Guide_ [draft-hallambaker-mesh-architecture]. 241 2.3. Related Specifications 243 The architecture of the Mathematical Mesh is described in the _Mesh 244 Architecture Guide_ [draft-hallambaker-mesh-architecture]. The Mesh 245 documentation set and related specifications are described in this 246 document. 248 2.4. Implementation Status 250 The implementation status of the reference code base is described in 251 the companion document [draft-hallambaker-mesh-developer]. 253 3. Mesh Service 255 A Mesh Service is a minimally trusted service. In particular a user 256 does not need to trust a Mesh service to protect the confidentiality 257 or integrity of most data stored in the account catalogs and spools. 259 Unless the use of the Mesh Service is highly restricted, a user does 260 need to trust the Mesh Service in certain respects: 262 Data Loss A service could refuse to respond to requests to download 263 data. 265 Integrity (Stale Data) The use of Merkle Trees limits but does not 266 eliminate the ability of a Mesh Service to respond to requests 267 with stale data. 269 Messaging A service could reject requests to post messages to or 270 accept messages from other mesh users. 272 This risk is a necessary consequence of the fact that the Mesh 273 Service Provider is accountable to other Mesh Service Providers 274 for abuse originating from their service. 276 Traffic analysis A Mesh Service has knowledge of the number of Mesh 277 Messages being sent and received by its users and the addresses to 278 which they are being sent to or received from. 280 The need to trust the Mesh Service in these respects is mitigated by 281 accountability and the user's ability to change Mesh Service 282 providers at any time they choose with minimal inconvenience. 284 It is possible that some of these risks will be reduced in future 285 versions of the Mesh Service Protocol but it is highly unlikely that 286 these can be eliminated entirely without compromising practicality or 287 efficiency. 289 3.1. Data Model 291 The design of the Mesh Service model followed a quasi-formal approach 292 in which the system was reduced to schemas which could in principle 293 be rendered in a formal development method but without construction 294 of proofs. 296 Like the contents of Mesh Accounts, a Mesh Service may be represented 297 by a collection of catalogs and spools, for example: 299 Account Catalog Contains the account entries. 301 Incident Spool Reports of potential abuse 303 Backup of the service MAY be implemented using the same container 304 synchronization mechanism used to synchronize account catalogs and 305 spools. 307 3.2. Partitioning 309 Mesh Services supporting a large number of accounts or large activity 310 volume MAY partition the account catalog between one or more hosts 311 using the usual tiered service model in which a front-end server 312 receives traffic for any account hosted at the server and routes the 313 request to the back-end service that provides the persistence store 314 for that account. 316 In addition, the Mesh Service Protocol supports a 'direct connection' 317 partitioning model in which devices are given a DNS name which MAY 318 allow for direct connection to the persistence host or to a front-end 319 service offering service that is in some way specific to that 320 account. 322 4. Protocol Bindings 324 Mesh Service transactions are mapped to an underlying messaging and 325 transport protocol. The following binding 327 Mesh Services MUST support the Web Service binding specified in this 328 document and MAY support the UDP binding currently in development. 330 4.1. DNS Web Service Discovery 332 The DNS Web Service discovery mechanism is used to discover Mesh 333 Services regardless of the protocol binding .The service name, DNS 334 prefix and and .well-known service suffix are specified as follows: 336 * Service Name: mmm 337 * DNS Prefix: _mmm._tcp 339 * Well Known service suffix: /.well-known/mmm 341 4.2. Web Service Protocol Binding 343 The Web Service Protocol binding makes use of the most widely 344 deployed and used protocols: 346 * Discovery: DNS Service discovery 348 * Transport: TLS 350 * Application: HTTP 352 * Presentation: DARE Message 354 * Encoding: JSON, JSON-B 356 The chief limitations of the Web Service Protocol Binding are that 357 the use of TCP based transport results in unsatisfactory latency for 358 some applications and that the HTTP application layer only serves to 359 allow a host to support multiple services on the same TCP/IP port. 361 4.2.1. Transport Security 363 Mesh Services MUST offer TLS transport and MAY offer non TLS 364 transport. MESH clients SHOULD use TLS transport when connecting to 365 a MESH service. 367 TLS version 1.3 [RFC8446] or higher MUST be supported. Client 368 authentication SHOULD NOT be used. 370 4.2.2. HTTP Message Binding 372 All messages are exchanged as HTTP POST transactions. Support for 373 and use of HTTP/1.1 [RFC7230] is REQUIRED. Services MAY support 374 HTTP/2. 376 In contrast to other approaches to the design of Web Services, the 377 only use made of the HTTP transport is to distinguish between 378 different services on the same host using the Host header and .well- 379 known convention and for message framing. No use is made of the URI 380 request line to identify commands, nor are the caching or proxy 381 capabilities of HTTP made use of. 383 4.2.3. Request 385 The HTTP request MAY contain any valid HTTP header specified in 386 [RFC7230]. 388 Request Line URI "/well-known/" (unless overridden using a 389 TXT path attribute) 391 Request Line Method POST 393 Host: Header 395 Content-Encoding As specified in section yy below. 397 Content-Type As specified in section zz below. 399 Content-Length or Transfer-Encoding As specified in [RFC7230]. 401 Payload The content payload as specified in section XX below. 403 [Note, this is showing the payload, not the binding as is intended 404 because the current code doesn't implement it as intended yet] 406 { 407 "Hello": {}} 409 4.2.4. Response 411 The response MAY contain any HTTP response header but since JWB 412 services do not make use of HTTP caching and messages are not 413 intended to be modified by HTTP intermediaries, only a limited number 414 of headers have significance: 416 Response Code The HTTP response code. This is processed as 417 described in section zz below. 419 Content-Type As specified in section zz below. 421 Content-Length or Transfer-Encoding As specified in [RFC7230]. 423 Cache-Control Since the only valid HTTP method for a JWB request is 424 POST, JWB responses are not cacheable. The use of the cache- 425 control header is therefore unnecessary. However, experience 426 suggests that reviewers find it easier to understand protocol 427 specifications if they are reminded of the fact that caching is 428 neither supported nor desired. 430 [Note, this is showing the payload, not the binding as is intended 431 because the current code doesn't implement it as intended yet] 433 { 434 "MeshHelloResponse": { 435 "Status": 201, 436 "Version": { 437 "Major": 3, 438 "Minor": 0, 439 "Encodings": [{ 440 "ID": ["application/json"]}]}, 441 "EnvelopedProfileService": [{ 442 "dig": "SHA2"}, 443 "ewogICJQcm9maWxlU2VydmljZSI6IHsKICAgICJLZXlPZmZsaW5lU2l 444 nbmF0dXJlIjogewogICAgICAiVURGIjogIk1BWFotSVBHNy1WSEFPLVdRVVQtQ 445 0JUTC1ITFMyLVNLT1ciLAogICAgICAiUHVibGljUGFyYW1ldGVycyI6IHsKICA 446 gICAgICAiUHVibGljS2V5RUNESCI6IHsKICAgICAgICAgICJjcnYiOiAiRWQ0N 447 DgiLAogICAgICAgICAgIlB1YmxpYyI6ICJiY2paaUQzQmdQcThOSEE4VFFzbEp 448 RbzBzOE14R1o0VWRPUV8zcGZBWGhmUkdLdDh3aVhlCiAgZTl6MzZ4V0JxVGVKR 449 khhd09uTWNPcmlBIn19fSwKICAgICJLZXlFbmNyeXB0aW9uIjogewogICAgICA 450 iVURGIjogIk1EM0gtM09LRi1LTDM0LU02Q0YtSkVHVS1BMkVNLUNUWVUiLAogI 451 CAgICAiUHVibGljUGFyYW1ldGVycyI6IHsKICAgICAgICAiUHVibGljS2V5RUN 452 ESCI6IHsKICAgICAgICAgICJjcnYiOiAiWDQ0OCIsCiAgICAgICAgICAiUHVib 453 GljIjogInBJcjlQeTVrWm52QU9paTZ0REdRejc1ZFVCNTNpQkIxM0ZKQXZzSDJ 454 NdHlJU2RQWFZ3TWMKICBrU3FOTGl5TzBpUTJaanE5QkRXVmpmOEEifX19fX0", 455 { 456 "signatures": [{ 457 "alg": "SHA2", 458 "kid": "MAXZ-IPG7-VHAO-WQUT-CBTL-HLS2-SKOW", 459 "signature": "Q8tU8qUnPvpxEqpZd_TWkvIN8_1YtRCkxGqSk2Exad_ 460 4PlWzr 461 AzG_cX9VT5UmOaJ6cmi-lM8hF8Am-OgRNkxGkb1y_OYtaKBXnUeBGHG3jtnplU 462 vx3VlWReJn0VqYMiTfcAQ5PKNujHbf4iCso6PSAcA"}], 463 "PayloadDigest": "tWH90O5uV-b6VvIjiwiClRkJ6D2C64GZLXqZk5pAhxt 464 QW 465 wqcCzKM3f7s6slOuJ6fZ267uDg6QQ2UF55_vjsiSA"}], 466 "EnvelopedProfileHost": [{ 467 "dig": "SHA2"}, 468 "ewogICJQcm9maWxlSG9zdCI6IHsKICAgICJLZXlPZmZsaW5lU2lnbmF 469 0dXJlIjogewogICAgICAiVURGIjogIk1CM1otSzVITC1FS0FCLTZNNUotM1BLW 470 S1CSVlCLUpZSzUiLAogICAgICAiUHVibGljUGFyYW1ldGVycyI6IHsKICAgICA 471 gICAiUHVibGljS2V5RUNESCI6IHsKICAgICAgICAgICJjcnYiOiAiRWQ0NDgiL 472 AogICAgICAgICAgIlB1YmxpYyI6ICJnamlvV3pVYllqNkxMQ2I0NGRrYUw4STV 473 wOTFpcE5IaHJOTVF0VlFJbFA2aXg3MmZVWnFYCiAgRFpBTmdKSzNpOXU4RGNIT 474 XhpV0hsalFBIn19fSwKICAgICJLZXlBdXRoZW50aWNhdGlvbiI6IHsKICAgICA 475 gIlVERiI6ICJNQ1g3LTZQQ0QtV1BISC1WRjRMLVZRNVgtSVNJSC1UVk0zIiwKI 476 CAgICAgIlB1YmxpY1BhcmFtZXRlcnMiOiB7CiAgICAgICAgIlB1YmxpY0tleUV 477 DREgiOiB7CiAgICAgICAgICAiY3J2IjogIlg0NDgiLAogICAgICAgICAgIlB1Y 478 mxpYyI6ICJPbGViSVA0Y3otOEVWV05lRFBVTE9rajJlczd2dTdBUF9OTEo1MWs 479 xSDBYb1N0UWtFaWtQCiAgQ19vM3FCVmJsVUh2Uk0wblBFQmxjdGdBIn19fX19", 480 { 481 "signatures": [{ 482 "alg": "SHA2", 483 "kid": "MB3Z-K5HL-EKAB-6M5J-3PKY-BIYB-JYK5", 484 "signature": "Ten3iq7kUJdif_NE94cr-RJ0OJD8qrG-9gj7eu-M6ae 485 oqLk3_ 486 Ew9MqJ8nxvpI13YWEq1Zb9uRfaAbcOghmncfeN9rwTeoApfGEE5lZ5O2h97s1m 487 inEKmUEWMOoT2-CBkVSZlH50rYADhbJ9N1ZpWRDAA"}], 488 "PayloadDigest": "2K1y20hWCmxcFb_DzTRpHlEyPbqySb-TPF8cA6Y_T5i 489 fc 490 OupwDkIwlLqWQBML9IxCZyqtZ37vJh4DkAA6LGWWg"}]}} 492 4.3. DARE Message Encapsulation 494 The payload of the HTTP requests and responses is a DARE Message 495 whose payload contains the Mesh Service request or response. 497 The DARE Message encapsulation is used to authenticate the request or 498 response data. The form of the authentication depending on the 499 credentials available to the sender at the time the request is made. 501 Mesh Service MUST support the use of Mutually Authenticated Key 502 Exchange [draft-hallambaker-mesh-security] to establish the Master 503 Key used for authentication of requests and responses. 505 Requests and Responses MUST be authenticated. Requests and Responses 506 MUST be encrypted if the transport is not encrypted and MAY be 507 encrypted otherwise. 509 4.3.1. Null Authentication 511 Null Authentication MAY be used to make a "Hello" Request. 513 The Null Authentication mechanism MUST NOT be used for any Mesh 514 Service request or response other than a "Hello" request. 516 Since the Mutually Authenticated key exchange requires both parties 517 to know the public key of the other, it is not possible for a client 518 to authenticate itself to the service until it has obtained the 519 service public key. One means by which the client MAY obtain the 520 service public key is by requesting the service return the credential 521 in a "Hello" transaction. 523 4.3.2. Device Authentication 525 Device Authentication is used in two circumstances 527 * When requesting creation of an account 529 * When a device is requesting connection to a profile. 531 4.3.3. Profile Authentication 533 Profile Authentication has the same form as Device Authentication 534 except that the client provides its Device Connection Assertion as 535 part of the request: 537 4.3.4. Ticket Authentication 539 Ticket Authentication is used after a device has obtained an 540 authentication ticket from a service. The ticket is returned in the 541 response to a previous Profile Authentication exchange. 543 4.4. Payload Encoding 545 The Dare Message payload of a "Hello" request MUST be encoded in JSON 546 encoding. The payload of all other requests MUST be in either JSON 547 encoding or one of the encodings advertised as being accepted in a 548 Hello response from the Service. Services MUST accept JSON encoding 549 and MAY support the JSON-B or JSON-C encodings as specified in this 550 document. Services MUST generate a response that is compatible with 551 the DARE Message Content-Type specified in the request. 553 JSON was originally developed to provide a serialization format for 554 the JavaScript programming language [ECMA-262]. While this approach 555 is generally applicable to the type systems of scripting programming 556 languages, it is less well matched to the richer type systems of 557 modern object oriented programming languages such as Java and C#. 559 Working within a subset of the capabilities of JSON allows a Web 560 Service protocol to be accessed with equal ease from either platform 561 type. The following capabilities of JSON are avoided: 563 The ability to use arbitrary strings as field names. 565 The use of JSON objects to define maps directly 567 The following data field types are used: 569 Integer Integer values are encoded as JSON number values. 571 String Test strings are encoded as JSON text strings. 573 Boolean Boolean values are encoded as JSON 'false', 'true' or 'null' 574 tokens according to value. 576 Sequence Sequences of data items that are encoded as JSON arrays 578 Object of known type Objects whose type is known to the receiver are 579 encoded as JSON objects 581 Object of variable type Objects whose type is not known to the 582 receiver are encoded as JSON objects containing a single field 583 whose name describes the type of the object value and whose value 584 contains the value. 586 Binary Data Byte sequences are converted to BASE64-url encoding 587 [RFC4648] and encoded as JSON string values. 589 Date Time Date Time values are converted to Internet time format as 590 described in [RFC3339] and encoded as JSON string values. 592 4.5. Error handling and response codes 594 It is possible for an error to occur at any of the three layers in 595 the Web Service binding: 597 Service Layer 599 HTTP Layer 601 Transport Layer 603 Services SHOULD always attempt to return error codes at the highest 604 level possible. However, it is clearly impossible for a connection 605 that is refused at the Transport layer to return an error code at the 606 HTTP layer. It is however possible for a HTTP layer error response 607 to contain a content body. 609 In the case that a response contains both a HTTP response code and a 610 well-formed payload containing a response, the payload response SHALL 611 have precedence. 613 5. Service Description 615 The Hello transaction is used to determine the features supported by 616 the service and obtain the service credentials 618 The request payload: 620 { 621 "Hello": {}} 623 The response payload: 625 { 626 "MeshHelloResponse": { 627 "Status": 201, 628 "Version": { 629 "Major": 3, 630 "Minor": 0, 631 "Encodings": [{ 632 "ID": ["application/json"]}]}, 633 "EnvelopedProfileService": [{ 634 "dig": "SHA2"}, 635 "ewogICJQcm9maWxlU2VydmljZSI6IHsKICAgICJLZXlPZmZsaW5lU2l 636 nbmF0dXJlIjogewogICAgICAiVURGIjogIk1BWFotSVBHNy1WSEFPLVdRVVQtQ 637 0JUTC1ITFMyLVNLT1ciLAogICAgICAiUHVibGljUGFyYW1ldGVycyI6IHsKICA 638 gICAgICAiUHVibGljS2V5RUNESCI6IHsKICAgICAgICAgICJjcnYiOiAiRWQ0N 639 DgiLAogICAgICAgICAgIlB1YmxpYyI6ICJiY2paaUQzQmdQcThOSEE4VFFzbEp 640 RbzBzOE14R1o0VWRPUV8zcGZBWGhmUkdLdDh3aVhlCiAgZTl6MzZ4V0JxVGVKR 641 khhd09uTWNPcmlBIn19fSwKICAgICJLZXlFbmNyeXB0aW9uIjogewogICAgICA 642 iVURGIjogIk1EM0gtM09LRi1LTDM0LU02Q0YtSkVHVS1BMkVNLUNUWVUiLAogI 643 CAgICAiUHVibGljUGFyYW1ldGVycyI6IHsKICAgICAgICAiUHVibGljS2V5RUN 644 ESCI6IHsKICAgICAgICAgICJjcnYiOiAiWDQ0OCIsCiAgICAgICAgICAiUHVib 645 GljIjogInBJcjlQeTVrWm52QU9paTZ0REdRejc1ZFVCNTNpQkIxM0ZKQXZzSDJ 646 NdHlJU2RQWFZ3TWMKICBrU3FOTGl5TzBpUTJaanE5QkRXVmpmOEEifX19fX0", 647 { 648 "signatures": [{ 649 "alg": "SHA2", 650 "kid": "MAXZ-IPG7-VHAO-WQUT-CBTL-HLS2-SKOW", 651 "signature": "Q8tU8qUnPvpxEqpZd_TWkvIN8_1YtRCkxGqSk2Exad_ 652 4PlWzr 653 AzG_cX9VT5UmOaJ6cmi-lM8hF8Am-OgRNkxGkb1y_OYtaKBXnUeBGHG3jtnplU 654 vx3VlWReJn0VqYMiTfcAQ5PKNujHbf4iCso6PSAcA"}], 655 "PayloadDigest": "tWH90O5uV-b6VvIjiwiClRkJ6D2C64GZLXqZk5pAhxt 656 QW 657 wqcCzKM3f7s6slOuJ6fZ267uDg6QQ2UF55_vjsiSA"}], 658 "EnvelopedProfileHost": [{ 659 "dig": "SHA2"}, 660 "ewogICJQcm9maWxlSG9zdCI6IHsKICAgICJLZXlPZmZsaW5lU2lnbmF 661 0dXJlIjogewogICAgICAiVURGIjogIk1CM1otSzVITC1FS0FCLTZNNUotM1BLW 662 S1CSVlCLUpZSzUiLAogICAgICAiUHVibGljUGFyYW1ldGVycyI6IHsKICAgICA 663 gICAiUHVibGljS2V5RUNESCI6IHsKICAgICAgICAgICJjcnYiOiAiRWQ0NDgiL 664 AogICAgICAgICAgIlB1YmxpYyI6ICJnamlvV3pVYllqNkxMQ2I0NGRrYUw4STV 665 wOTFpcE5IaHJOTVF0VlFJbFA2aXg3MmZVWnFYCiAgRFpBTmdKSzNpOXU4RGNIT 666 XhpV0hsalFBIn19fSwKICAgICJLZXlBdXRoZW50aWNhdGlvbiI6IHsKICAgICA 667 gIlVERiI6ICJNQ1g3LTZQQ0QtV1BISC1WRjRMLVZRNVgtSVNJSC1UVk0zIiwKI 668 CAgICAgIlB1YmxpY1BhcmFtZXRlcnMiOiB7CiAgICAgICAgIlB1YmxpY0tleUV 669 DREgiOiB7CiAgICAgICAgICAiY3J2IjogIlg0NDgiLAogICAgICAgICAgIlB1Y 670 mxpYyI6ICJPbGViSVA0Y3otOEVWV05lRFBVTE9rajJlczd2dTdBUF9OTEo1MWs 671 xSDBYb1N0UWtFaWtQCiAgQ19vM3FCVmJsVUh2Uk0wblBFQmxjdGdBIn19fX19", 672 { 673 "signatures": [{ 674 "alg": "SHA2", 675 "kid": "MB3Z-K5HL-EKAB-6M5J-3PKY-BIYB-JYK5", 676 "signature": "Ten3iq7kUJdif_NE94cr-RJ0OJD8qrG-9gj7eu-M6ae 677 oqLk3_ 678 Ew9MqJ8nxvpI13YWEq1Zb9uRfaAbcOghmncfeN9rwTeoApfGEE5lZ5O2h97s1m 679 inEKmUEWMOoT2-CBkVSZlH50rYADhbJ9N1ZpWRDAA"}], 680 "PayloadDigest": "2K1y20hWCmxcFb_DzTRpHlEyPbqySb-TPF8cA6Y_T5i 681 fc 682 OupwDkIwlLqWQBML9IxCZyqtZ37vJh4DkAA6LGWWg"}]}} 684 6. Account Management 686 A Mesh Account is bound to a Mesh Service by completing a 687 "CreateAccount" transaction with the service. 689 The client requesting the account creation specifies the 690 "ProfileMesh" profile describing the requested account and lists of 691 initial entries to populate the devices and contacts catalogs. 692 Additional catalogs MAY be synchronized if the account creation 693 request is accepted. 695 The request payload: 697 { 698 "Hello": {}} 700 The response payload: 702 { 703 "MeshHelloResponse": { 704 "Status": 201, 705 "Version": { 706 "Major": 3, 707 "Minor": 0, 708 "Encodings": [{ 709 "ID": ["application/json"]}]}, 710 "EnvelopedProfileService": [{ 711 "dig": "SHA2"}, 712 "ewogICJQcm9maWxlU2VydmljZSI6IHsKICAgICJLZXlPZmZsaW5lU2l 713 nbmF0dXJlIjogewogICAgICAiVURGIjogIk1BWFotSVBHNy1WSEFPLVdRVVQtQ 714 0JUTC1ITFMyLVNLT1ciLAogICAgICAiUHVibGljUGFyYW1ldGVycyI6IHsKICA 715 gICAgICAiUHVibGljS2V5RUNESCI6IHsKICAgICAgICAgICJjcnYiOiAiRWQ0N 716 DgiLAogICAgICAgICAgIlB1YmxpYyI6ICJiY2paaUQzQmdQcThOSEE4VFFzbEp 717 RbzBzOE14R1o0VWRPUV8zcGZBWGhmUkdLdDh3aVhlCiAgZTl6MzZ4V0JxVGVKR 718 khhd09uTWNPcmlBIn19fSwKICAgICJLZXlFbmNyeXB0aW9uIjogewogICAgICA 719 iVURGIjogIk1EM0gtM09LRi1LTDM0LU02Q0YtSkVHVS1BMkVNLUNUWVUiLAogI 720 CAgICAiUHVibGljUGFyYW1ldGVycyI6IHsKICAgICAgICAiUHVibGljS2V5RUN 721 ESCI6IHsKICAgICAgICAgICJjcnYiOiAiWDQ0OCIsCiAgICAgICAgICAiUHVib 722 GljIjogInBJcjlQeTVrWm52QU9paTZ0REdRejc1ZFVCNTNpQkIxM0ZKQXZzSDJ 723 NdHlJU2RQWFZ3TWMKICBrU3FOTGl5TzBpUTJaanE5QkRXVmpmOEEifX19fX0", 724 { 725 "signatures": [{ 726 "alg": "SHA2", 727 "kid": "MAXZ-IPG7-VHAO-WQUT-CBTL-HLS2-SKOW", 728 "signature": "Q8tU8qUnPvpxEqpZd_TWkvIN8_1YtRCkxGqSk2Exad_ 729 4PlWzr 730 AzG_cX9VT5UmOaJ6cmi-lM8hF8Am-OgRNkxGkb1y_OYtaKBXnUeBGHG3jtnplU 731 vx3VlWReJn0VqYMiTfcAQ5PKNujHbf4iCso6PSAcA"}], 732 "PayloadDigest": "tWH90O5uV-b6VvIjiwiClRkJ6D2C64GZLXqZk5pAhxt 733 QW 734 wqcCzKM3f7s6slOuJ6fZ267uDg6QQ2UF55_vjsiSA"}], 735 "EnvelopedProfileHost": [{ 736 "dig": "SHA2"}, 737 "ewogICJQcm9maWxlSG9zdCI6IHsKICAgICJLZXlPZmZsaW5lU2lnbmF 738 0dXJlIjogewogICAgICAiVURGIjogIk1CM1otSzVITC1FS0FCLTZNNUotM1BLW 739 S1CSVlCLUpZSzUiLAogICAgICAiUHVibGljUGFyYW1ldGVycyI6IHsKICAgICA 740 gICAiUHVibGljS2V5RUNESCI6IHsKICAgICAgICAgICJjcnYiOiAiRWQ0NDgiL 741 AogICAgICAgICAgIlB1YmxpYyI6ICJnamlvV3pVYllqNkxMQ2I0NGRrYUw4STV 742 wOTFpcE5IaHJOTVF0VlFJbFA2aXg3MmZVWnFYCiAgRFpBTmdKSzNpOXU4RGNIT 743 XhpV0hsalFBIn19fSwKICAgICJLZXlBdXRoZW50aWNhdGlvbiI6IHsKICAgICA 744 gIlVERiI6ICJNQ1g3LTZQQ0QtV1BISC1WRjRMLVZRNVgtSVNJSC1UVk0zIiwKI 745 CAgICAgIlB1YmxpY1BhcmFtZXRlcnMiOiB7CiAgICAgICAgIlB1YmxpY0tleUV 746 DREgiOiB7CiAgICAgICAgICAiY3J2IjogIlg0NDgiLAogICAgICAgICAgIlB1Y 747 mxpYyI6ICJPbGViSVA0Y3otOEVWV05lRFBVTE9rajJlczd2dTdBUF9OTEo1MWs 748 xSDBYb1N0UWtFaWtQCiAgQ19vM3FCVmJsVUh2Uk0wblBFQmxjdGdBIn19fX19", 749 { 750 "signatures": [{ 751 "alg": "SHA2", 752 "kid": "MB3Z-K5HL-EKAB-6M5J-3PKY-BIYB-JYK5", 753 "signature": "Ten3iq7kUJdif_NE94cr-RJ0OJD8qrG-9gj7eu-M6ae 754 oqLk3_ 755 Ew9MqJ8nxvpI13YWEq1Zb9uRfaAbcOghmncfeN9rwTeoApfGEE5lZ5O2h97s1m 756 inEKmUEWMOoT2-CBkVSZlH50rYADhbJ9N1ZpWRDAA"}], 757 "PayloadDigest": "2K1y20hWCmxcFb_DzTRpHlEyPbqySb-TPF8cA6Y_T5i 758 fc 759 OupwDkIwlLqWQBML9IxCZyqtZ37vJh4DkAA6LGWWg"}]}} 761 An account registration is deleted using the "DeleteAccount" 762 transaction. 764 7. Container Synchronization 766 All the state associated with a Mesh profile is stored as a sequence 767 of DARE Messages in a Dare Container. The Mesh Service holding the 768 master copy of the persistence stores and the devices connected to 769 the profile containing complete copies (replicas) or partial copies 770 (redactions). 772 Thus, the only primitive needed to achieve synchronization of the 773 profile state are those required for synchronization of a DARE 774 Container. These steps are: 776 * Obtain the status of the catalogs and spools associated with the 777 account. 779 * Download catalog and spool updates 781 * Upload catalog updates. 783 To ensure a satisfactory user experience, Mesh Messages are 784 intentionally limited in size to 64 KB or less, thus ensuring that an 785 application can retrieve the most recent 100 messages almost 786 instantaneously on a high bandwidth connection and without undue 787 delay on a slower one. 789 7.1. Status Transaction 791 The status transaction returns the status of the containers the 792 device is authorized to access for the specified account together 793 with the updated Device Connection Entry if this has been modified 794 since the entry presented to authenticate the request was issued. 796 7.2. Download Transaction 798 The download transaction returns a collection of entries from one or 799 more containers associated with the profile. 801 Optional filtering criteria MAY be specified to only return objects 802 matching specific criteria and/or only return certain parts of the 803 selected messages. 805 The service MAY limit the number of entries returned in an individual 806 response for performance reasons. 808 7.2.1. Conflict Detection 810 Clients SHOULD check to determine if updates to a container conflict 811 with pending updates on the device waiting to be uploaded. For 812 example, if a contact that the user modified on the device attempting 813 to synchronize was subsequently deleted. 815 The means of resolving such conflicts is not in the scope of this 816 specification. 818 7.2.2. Filtering 820 Clients may request container updates be filtered to redact catalog 821 entries that have been updated or deleted or spool entries that have 822 been read, deleted or were received before a certain date. 824 7.3. Upload Transaction 826 The upload transaction upload objects to a catalog or spool. 828 Multiple objects MAY be uploaded at once. Object updates MAY be 829 conditional on the successful completion of other upload requests. 831 The transaction MAY be performed in one request/response round trip 832 or with separate round trips to confirm that the transaction is 833 accepted by the service before sending large number of updates. 835 8. Device Connection 837 Devices request connection to a Mesh profile using the "Connect" 838 transaction. Three connection mechanisms are currently defined. All 839 three of which offer strong mutual authentication. 841 Device Authenticated 843 Pin Authenticated 845 EARL Connection Mode 847 The first two of these mechanisms are initiated from the device being 848 connected which requires that the Mesh Service Account it is being 849 connected to be entered into it. Use of these mechanisms thus 850 requires keyboard and display affordances or accessibility 851 equivalents. 853 The last mechanism is initiated from an administration device that is 854 already connected to the account. It is intended for use in 855 circumstances where the device being connected does not have the 856 necessary affordances to allow the Device or PIN authenticated modes. 858 In either case, the connection request is completed by the device 859 requesting synchronization with the Mesh Account using its device 860 credential for authentication. If the connection request was 861 accepted, the device will be provisioned with the Device Connection 862 Assertion allowing it to complete the process. 864 The Device Connection Assertion includes an overlay device profile 865 containing a set of private key contributions to be used to perform 866 key cogeneration on the original set of device keys to create a new 867 device profile to be used for all purposes associated with the Mesh 868 Profile to which it has just been connected. This assures the user 869 that the keys the device uses for performing operation in the context 870 of their profile are not affected by any compromise that might have 871 occurred during manufacture or at any point after up to the time it 872 was connected to their profile. 874 8.1. Device Authenticated 876 The direct connection mechanism requires that both the administration 877 device and the device originating the connection request have data 878 entry and output affordances and that it is possible for the user to 879 compare the authentication codes presented by the two devices to 880 check that they are identical. 882 8.2. PIN Authenticated 884 The PIN Connection mechanism is similar to the Direct connection 885 mechanism except that the process is initiated on an administration 886 device by requesting assignment of a new authentication PIN. The PIN 887 is then input to the connecting device to authenticate the request. 889 8.3. EARL connection mode 891 The EARL/QR code connection mechanisms are used to connect a 892 constrained device to a Mesh profile by means of an Encrypted 893 Authenticated Resource Locator, typically presented as a QR code on 894 the device itself or its packaging. 896 9. Mesh Messaging 898 Mesh Messages provide a means of communication between Mesh Service 899 Accounts with capabilities that are not possible or poorly supported 900 in traditional SMTP mail messaging: 902 * End-to-end confidentiality and authentication by default. 904 * Abuse mitigation by applying access control to every inbound and 905 outbound message. 907 * End-to-end secure group messaging. 909 * Transfer of very large data sets (Terabytes). 911 Note that although Mesh Messaging is designed to facilitate the 912 transfer of very large data sets, the size of Mesh Messages 913 themselves is severely restricted. The current default maximum size 914 being 64 KB. This approach allows Mesh 916 In addition, the platform anticipates but does not currently support 917 additional cryptographic security capabilities: 919 * Traffic analysis resistance using mix networks (Chaum). 921 * Simultaneous contract binding using fair contract signing 922 (Micali). 924 While these capabilities might in time cause Mesh Messaging to 925 replace SMTP, this is not a near term goal. The short-term goal of 926 Mesh Messaging is to support the Contact Exchange and Confirmation 927 applications. 929 Two important classes of application that are not currently supported 930 directly are payments and presence. While prototypes of these 931 applications have been considered, it is not clear if these are best 932 implemented as special cases of the Confirmation and Contact Exchange 933 applications or as separate applications in their own right. 935 9.1. Message Exchange 937 To enable effective abuse mitigation, Mesh Messaging enforces a four 938 corner communication model in which all outbound and inbound messages 939 pass through a Mesh Service which accredits and authorizes the 940 messages on the user's behalf. 942 (Artwork only available as svg: No external link available, see 943 draft-hallambaker-mesh-protocol-06.html for artwork.) 945 Figure 1 947 The Post transaction is used for client-service and service-service 948 messaging transactions. 950 9.1.1. Client-Service (Post Transaction) 952 To send a message, the client creates the Mesh Message structure, 953 encapsulates it in a DARE Message and forwards this to its service 954 using a "Post" transaction. 956 The Post transaction is authenticated to the service by device using 957 the usual means of profile or ticket authentication. 959 The DARE Message MUST be signed under a device signature key 960 accredited by a Device Connection Assertion provided in the message 961 signature block. 963 9.1.2. Service-Service (Post Transaction) 965 The Mesh Service receiving the message from the user's device MAY 966 attempt immediate retransmission or queue it to be sent at a future 967 time. Mesh Services SHOULD forward messages without undue delay. 969 The Post transaction forwarding the message to the destination 970 service carries the same payload as the original request but is 971 authenticated by the service forwarding it. This authentication MAY 972 be my means of either profile or ticket authentication. 974 9.1.2.1. Denial of Service Mitigation 976 Services SHOULD implement Denial of Service mitigation strategies 977 including limiting the maximum time taken to complete a transaction 978 and refusing connections from clients that engage in patterns of 979 behavior consistent with abuse. 981 The limitation in message size allows Mesh Services to aggressively 982 time out connections that take too long to complete a transaction. A 983 Mesh Service that hosted on a 10Mb/s link should be able to transfer 984 20 messages a second. If the service is taking more than 5 seconds 985 to complete a transaction, either the source or the destination 986 service is overloaded or the message itself is an attack. 988 Imposing hard constraints on Mesh Service performance requires 989 deployments to scale and apply resources appropriately. If a service 990 is attempting to transfer 100 messages simultaneously and 40% are 991 taking 4 seconds or more, this indicates that the number of 992 simultaneous transfers being attempted should be reduced. 993 Contrawise, if 90% are completinin less than a second, the number of 994 threads allocated to sending outbound messages might be increased. 996 9.1.2.2. Access Control 998 The inbound service MUST subject inbound messages to Access Control 999 according to the credentials presented in the DARE Message payload. 1001 After verifying the signature and checking that the key is properly 1002 accredited in accordance with site policy, the service applies 1003 authorization controls taking account of: 1005 * The accreditation of the sender 1007 * The accreditation of the transmitting Service 1009 * The type of Mesh Message being sent 1011 * User policy as specified in their Contact Catalog 1013 * Site policy. 1015 9.1.3. Service-Client (Synchronization) 1017 The final recipient receives the message by synchronizing their 1018 inbound spool. 1020 10. Protocol Schema 1022 HTTP Well Known Service Prefix: /.well-known/mmm 1024 Every Mesh Portal Service transaction consists of exactly one request 1025 followed by exactly one response. Mesh Service transactions MAY 1026 cause modification of the data stored in the Mesh Service or the Mesh 1027 itself but do not cause changes to the connection state. The 1028 protocol itself is thus idempotent. There is no set sequence in 1029 which operations are required to be performed. It is not necessary 1030 to perform a Hello transaction prior to any other transaction. 1032 10.1. Request Messages 1034 A Mesh Portal Service request consists of a payload object that 1035 inherits from the MeshRequest class. When using the HTTP binding, 1036 the request MUST specify the portal DNS address in the HTTP Host 1037 field. 1039 10.1.1. Message: MeshRequest 1041 Base class for all request messages. 1043 [No fields] 1045 10.1.2. Message: MeshRequestUser 1047 Base class for all request messages made by a user. 1049 Inherits: MeshRequest 1051 Account: String (Optional) The fully qualified account name 1052 (including DNS address) to which the request is directed. 1054 DeviceProfile: DareEnvelope (Optional) Device profile of the device 1055 making the request. 1057 10.2. Response Messages 1059 A Mesh Portal Service response consists of a payload object that 1060 inherits from the MeshResponse class. When using the HTTP binding, 1061 the response SHOULD report the Status response code in the HTTP 1062 response message. However the response code returned in the payload 1063 object MUST always be considered authoritative. 1065 10.2.1. Message: MeshResponse 1067 Base class for all response messages. Contains only the status code 1068 and status description fields. 1070 [No fields] 1072 10.3. Imported Objects 1074 The Mesh Service protocol makes use of JSON objects defined in the 1075 JOSE Signatgure and Encryption specifications and in the DARE Data At 1076 Rest Encryption extensions to JOSE. 1078 10.4. Common Structures 1080 The following common structures are used in the protocol messages: 1082 10.4.1. Structure: KeyValue 1084 Describes a Key/Value structure used to make queries for records 1085 matching one or more selection criteria. 1087 Key: String (Optional) The data retrieval key. 1089 Value: String (Optional) The data value to match. 1091 10.4.2. Structure: ConstraintsSelect 1093 Specifies constraints to be applied to a search result. These allow 1094 a client to limit the number of records returned, the quantity of 1095 data returned, the earliest and latest data returned, etc. 1097 Container: String (Optional) The container to be searched. 1099 IndexMin: Integer (Optional) Only return objects with an index value 1100 that is equal to or higher than the value specified. 1102 IndexMax: Integer (Optional) Only return objects with an index value 1103 that is equal to or lower than the value specified. 1105 NotBefore: DateTime (Optional) Only data published on or after the 1106 specified time instant is requested. 1108 Before: DateTime (Optional) Only data published before the specified 1109 time instant is requested. This excludes data published at the 1110 specified time instant. 1112 PageKey: String (Optional) Specifies a page key returned in a 1113 previous search operation in which the number of responses 1114 exceeded the specified bounds. 1116 When a page key is specified, all the other search parameters 1117 except for MaxEntries and MaxBytes are ignored and the service 1118 returns the next set of data responding to the earlier query. 1120 10.4.3. Structure: ConstraintsData 1122 Specifies constraints on the data to be sent. 1124 MaxEntries: Integer (Optional) Maximum number of entries to send. 1126 BytesOffset: Integer (Optional) Specifies an offset to be applied to 1127 the payload data before it is sent. This allows large payloads to 1128 be transferred incrementally. 1130 BytesMax: Integer (Optional) Maximum number of payload bytes to 1131 send. 1133 Header: Boolean (Optional) Return the entry header 1135 Payload: Boolean (Optional) Return the entry payload 1137 Trailer: Boolean (Optional) Return the entry trailer 1139 10.4.4. Structure: PolicyAccount 1141 Describes the account creation policy including constraints on 1142 account names, whether there is an open account creation policy, etc. 1144 Minimum: Integer (Optional) Specifies the minimum length of an 1145 account name. 1147 Maximum: Integer (Optional) Specifies the maximum length of an 1148 account name. 1150 InvalidCharacters: String (Optional) A list of characters that the 1151 service does not accept in account names. The list of characters 1152 MAY not be exhaustive but SHOULD include any illegal characters in 1153 the proposed account name. 1155 10.4.5. Structure: ContainerStatus 1157 Container: String (Optional) 1159 Index: Integer (Optional) 1161 Digest: Binary (Optional) 1163 10.4.6. Structure: ContainerUpdate 1165 Inherits: ContainerStatus 1167 Envelopes: DareEnvelope [0..Many] The entries to be uploaded. 1169 10.5. Transaction: Hello 1171 Request: HelloRequest 1173 Response: MeshHelloResponse 1175 Report service and version information. 1177 The Hello transaction provides a means of determining which protocol 1178 versions, message encodings and transport protocols are supported by 1179 the service. 1181 The PostConstraints field MAY be used to advise senders of a maximum 1182 size of payload that MAY be sent in an initial Post request. 1184 10.5.1. Message: MeshHelloResponse 1186 ConstraintsUpdate: ConstraintsData (Optional) Specifies the default 1187 data constraints for updates. 1189 ConstraintsPost: ConstraintsData (Optional) Specifies the default 1190 data constraints for message senders. 1192 PolicyAccount: PolicyAccount (Optional) Specifies the account 1193 creation policy 1195 EnvelopedProfileService: DareEnvelope (Optional) The enveloped 1196 master profile of the service. 1198 EnvelopedProfileHost: DareEnvelope (Optional) The enveloped profile 1199 of the host. 1201 10.6. Transaction: CreateAccount 1203 Request: CreateRequest 1205 Response: CreateResponse 1207 Request creation of a new service account or group. 1209 Attempt 1211 10.6.1. Message: CreateRequest 1213 Request binding of an account to a service address. 1215 Inherits: MeshRequest 1217 AccountAddress: String (Optional) The service account to bind to. 1219 SignedProfileMesh: DareEnvelope (Optional) The persistent profile 1220 that will be used to validate changes to the account assertion. 1222 SignedAssertionAccount: DareEnvelope (Optional) The signed assertion 1223 describing the account. 1225 10.6.2. Message: CreateResponse 1227 Inherits: MeshResponse 1229 Reports the success or failure of a Create transaction. 1231 Reason: String (Optional) Text explaining the status of the creation 1232 request. 1234 URL: String (Optional) A URL to which the user is directed to 1235 complete the account creation request. 1237 10.7. Transaction: DeleteAccount 1239 Request: DeleteRequest 1241 Response: DeleteResponse 1243 Request deletion of a service account. 1245 10.7.1. Message: DeleteRequest 1247 Request creation of a new portal account. The request specifies the 1248 requested account identifier and the Mesh profile to be associated 1249 with the account. 1251 Inherits: MeshRequestUser 1253 [No fields] 1255 10.7.2. Message: DeleteResponse 1257 Inherits: MeshResponse 1259 Reports the success or failure of a Delete transaction. 1261 [No fields] 1263 10.8. Transaction: Complete 1265 Request: CompleteRequest 1267 Response: CompleteResponse 1269 10.8.1. Message: CompleteRequest 1271 Inherits: StatusRequest 1273 AccountAddress: String (Optional) 1275 ResponseID: String (Optional) 1277 10.8.2. Message: CompleteResponse 1279 Inherits: MeshResponse 1281 SignedResponse: DareEnvelope (Optional) The signed assertion 1282 describing the result of the connect request 1284 10.9. Transaction: Status 1286 Request: StatusRequest 1288 Response: StatusResponse 1290 10.9.1. Message: StatusRequest 1292 Inherits: MeshRequestUser 1294 DeviceUDF: String (Optional) 1296 ProfileMasterDigest: Binary (Optional) 1298 Catalogs: String [0..Many] 1300 Spools: String [0..Many] 1302 10.9.2. Message: StatusResponse 1304 Inherits: MeshResponse 1306 EnvelopedProfileMaster: DareEnvelope (Optional) The master profile 1307 that provides the root of trust for this Mesh 1309 EnvelopedCatalogEntryDevice: DareEnvelope (Optional) The catalog 1310 device entry 1312 ContainerStatus: ContainerStatus [0..Many] 1314 10.10. Transaction: Download 1316 Request: DownloadRequest 1318 Response: DownloadResponse 1320 Request objects from the specified container with the specified 1321 search criteria. 1323 10.10.1. Message: DownloadRequest 1325 Inherits: MeshRequestUser 1327 Request objects from the specified container(s). 1329 A client MAY request only objects matching specified search criteria 1330 be returned and MAY request that only specific fields or parts of the 1331 payload be returned. 1333 Select: ConstraintsSelect [0..Many] Specifies constraints to be 1334 applied to a search result. These allow a client to limit the 1335 number of records returned, the quantity of data returned, the 1336 earliest and latest data returned, etc. 1338 ConstraintsPost: ConstraintsData (Optional) Specifies the data 1339 constraints to be applied to the responses. 1341 10.10.2. Message: DownloadResponse 1343 Inherits: MeshResponse 1345 Return the set of objects requested. 1347 Services SHOULD NOT return a response that is disproportionately 1348 large relative to the speed of the network connection without a clear 1349 indication from the client that it is relevant. A service MAY limit 1350 the number of objects returned. A service MAY limit the scope of 1351 each response. 1353 Updates: ContainerUpdate [0..Many] The updated data 1355 10.11. Transaction: Upload 1357 Request: UploadRequest 1359 Response: UploadResponse 1361 Request objects from the specified container with the specified 1362 search criteria. 1364 10.11.1. Message: UploadRequest 1366 Inherits: MeshRequestUser 1368 Upload entries to a container. This request is only valid if it is 1369 issued by the owner of the account 1371 Updates: ContainerUpdate [0..Many] The data to be updated 1373 Self: DareEnvelope [0..Many] Entries to be added to the inbound 1374 spool on the account, e.g. completion messages. 1376 10.11.2. Message: UploadResponse 1378 Inherits: MeshResponse 1380 Response to an upload request. 1382 Entries: EntryResponse [0..Many] The responses to the entries. 1384 ConstraintsData: ConstraintsData (Optional) If the upload request 1385 contains redacted entries, specifies constraints that apply to the 1386 redacted entries as a group. Thus the total payloads of all the 1387 messages must not exceed the specified value. 1389 10.11.3. Structure: EntryResponse 1391 IndexRequest: Integer (Optional) The index value of the entry in the 1392 request. 1394 IndexContainer: Integer (Optional) The index value assigned to the 1395 entry in the container. 1397 Result: String (Optional) Specifies the result of attempting to add 1398 the entry to a catalog or spool. Valid values for a message are 1399 'Accept', 'Reject'. Valid values for an entry are 'Accept', 1400 'Reject' and 'Conflict'. 1402 ConstraintsData: ConstraintsData (Optional) If the entry was 1403 redacted, specifies constraints that apply to the redacted entries 1404 as a group. Thus the total payloads of all the messages must not 1405 exceed the specified value. 1407 10.12. Transaction: Publish 1409 Request: PublishRequest 1411 Response: PublishResponse 1413 Request to post to a spool from an external party. The request and 1414 response messages are extensions of the corresponding messages for 1415 the Upload transaction. It is expected that additional fields will 1416 be added as the need arises. 1418 10.12.1. Message: PublishRequest 1420 Inherits: MeshRequest 1422 Publications: CatalogedPublication [0..Many] The entries to be 1423 published. These may contain the full data or just the 1424 identifier, length and fingerprint. 1426 10.12.2. Message: PublishResponse 1428 Inherits: MeshResponse 1430 [No fields] 1432 10.13. Transaction: Post 1434 Request: PostRequest 1436 Response: PostResponse 1438 Request to post to a spool from an external party. The request and 1439 response messages are extensions of the corresponding messages for 1440 the Upload transaction. It is expected that additional fields will 1441 be added as the need arises. 1443 10.13.1. Message: PostRequest 1445 Inherits: MeshRequest 1447 Accounts: String [0..Many] The account(s) to which the request is 1448 directed. 1450 Message: DareEnvelope [0..Many] The entries to be uploaded. These 1451 MAY be either complete messages or redacted messages. In either 1452 case, the messages MUST conform to the ConstraintsUpdate specified 1453 by the service 1455 Self: DareEnvelope [0..Many] Messages to be appended to the user's 1456 self spool. this is typically used to post notifications to the 1457 user to mark messages as having been read or responded to. 1459 10.13.2. Message: PostResponse 1461 Inherits: UploadResponse 1463 [No fields] 1465 10.14. Transaction: Connect 1467 Request: ConnectRequest 1469 Response: ConnectResponse 1471 Request information necessary to begin making a connection request. 1473 10.14.1. Message: ConnectRequest 1475 Inherits: MeshRequest 1477 MessageConnectionRequestClient: DareEnvelope (Optional) The 1478 connection request generated by the client 1480 10.14.2. Message: ConnectResponse 1482 Inherits: MeshResponse 1484 EnvelopedConnectionResponse: DareEnvelope (Optional) The connection 1485 request generated by the client 1487 EnvelopedProfileMaster: DareEnvelope (Optional) The master profile 1488 that provides the root of trust for this Mesh 1490 EnvelopedAccountAssertion: DareEnvelope (Optional) The current 1491 account assertion 1493 10.15. Transaction: Claim 1495 Request: ClaimRequest 1497 Response: ClaimResponse 1499 Claim a publication 1501 10.15.1. Message: ClaimRequest 1503 Inherits: MeshRequest 1505 EnvelopedMessageClaim: DareEnvelope (Optional) The claim message 1507 10.15.2. Message: ClaimResponse 1509 Inherits: MeshResponse 1511 CatalogedPublication: CatalogedPublication (Optional) The encrypted 1512 device profile 1514 10.16. Transaction: PollClaim 1516 Request: PollClaimRequest 1518 Response: PollClaimResponse 1520 Check party making claim 1522 10.16.1. Message: PollClaimRequest 1524 Inherits: MeshRequest 1525 PublicationId: String (Optional) The envelope identifier formed from 1526 the PublicationId. 1528 TargetAccountAddress: String (Optional) Account to which the claim 1529 is directed 1531 10.16.2. Message: PollClaimResponse 1533 Inherits: MeshResponse 1535 EnvelopedMessageClaim: DareEnvelope (Optional) The claim message 1537 10.17. Transaction: CreateGroup 1539 Request: CreateGroupRequest 1541 Response: CreateGroupResponse 1543 Check party making claim 1545 10.17.1. Message: CreateGroupRequest 1547 Inherits: MeshRequest 1549 AccountAddress: String (Optional) The service account to bind to. 1551 SignedProfileGroup: DareEnvelope (Optional) The persistent profile 1552 that will be used to validate changes to the account assertion. 1554 10.17.2. Message: CreateGroupResponse 1556 Inherits: CreateResponse 1558 [No fields] 1560 10.17.3. Structure: CryptographicOperation 1562 KeyId: String (Optional) The key identifier 1564 KeyCoefficient: Binary (Optional) Lagrange coefficient multiplier to 1565 be applied to the private key 1567 10.17.4. Structure: CryptographicOperationSign 1569 Inherits: CryptographicOperation 1571 Data: Binary (Optional) The data to sign 1572 PartialR: Binary (Optional) Contribution to the R offset. 1574 10.17.5. Structure: CryptographicOperationKeyAgreement 1576 Inherits: CryptographicOperation 1578 [No fields] 1580 10.17.6. Structure: CryptographicOperationGenerate 1582 Inherits: CryptographicOperation 1584 [No fields] 1586 10.17.7. Structure: CryptographicOperationShare 1588 Inherits: CryptographicOperation 1590 Threshold: Integer (Optional) 1592 Shares: Integer (Optional) 1594 10.17.8. Structure: CryptographicResult 1596 Error: String (Optional) 1598 10.17.9. Structure: CryptographicResultKeyAgreement 1600 Inherits: CryptographicResult 1602 [No fields] 1604 10.18. Transaction: Operate 1606 Request: OperateRequest 1608 Response: OperateResponse 1610 Perform a set of cryptographic operations 1612 10.18.1. Message: OperateRequest 1614 Inherits: MeshRequest 1616 AccountAddress: String (Optional) The service account the capability 1617 is bound to 1619 10.18.2. Message: OperateResponse 1621 Inherits: MeshResponse 1623 [No fields] 1625 11. Security Considerations 1627 The security considerations for use and implementation of Mesh 1628 services and applications are described in the Mesh Security 1629 Considerations guide [draft-hallambaker-mesh-security]. 1631 12. IANA Considerations 1633 All the IANA considerations for the Mesh documents are specified in 1634 this document 1636 13. Acknowledgements 1638 A list of people who have contributed to the design of the Mesh is 1639 presented in [draft-hallambaker-mesh-architecture]. 1641 14. Normative References 1643 [draft-hallambaker-mesh-architecture] 1644 Hallam-Baker, P., "Mathematical Mesh 3.0 Part I: 1645 Architecture Guide", Work in Progress, Internet-Draft, 1646 draft-hallambaker-mesh-architecture-13, 9 March 2020, 1647 . 1650 [draft-hallambaker-mesh-security] 1651 Hallam-Baker, P., "Mathematical Mesh 3.0 Part VII: 1652 Security Considerations", Work in Progress, Internet- 1653 Draft, draft-hallambaker-mesh-security-04, 9 March 2020, 1654 . 1657 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1658 Requirement Levels", BCP 14, RFC 2119, 1659 DOI 10.17487/RFC2119, March 1997, 1660 . 1662 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1663 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1664 . 1666 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1667 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1668 . 1670 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1671 (HTTP/1.1): Message Syntax and Routing", RFC 7230, 1672 DOI 10.17487/RFC7230, June 2014, 1673 . 1675 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1676 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1677 . 1679 15. Informative References 1681 [draft-hallambaker-mesh-developer] 1682 Hallam-Baker, P., "Mathematical Mesh: Reference 1683 Implementation", Work in Progress, Internet-Draft, draft- 1684 hallambaker-mesh-developer-09, 23 October 2019, 1685 . 1688 [ECMA-262] Ecma International, "ECMAScript(R) 2017 Language 1689 Specification", June 2017.