| Network Working Group | P. Hallam-Baker |
| Internet-Draft | April 4, 2019 |
| Intended status: Informational | |
| Expires: October 6, 2019 |
Mathematical Mesh Part V: Protocol Reference
draft-hallambaker-mesh-protocol-00
The Mathematical Mesh 'The Mesh' is an end-to-end secure infrastructure that facilitates the exchange of configuration and credential data between multiple user devices. The core protocols of the Mesh are described with examples of common use cases and reference data.
This document is also available online at http://mathmesh.com/Documents/draft-hallambaker-mesh-protocol.html .
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on October 6, 2019.
Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
This document describes the data structures and network protocols of the Mathematical Mesh illustrated with illustrative examples. For an overview of the Mesh objectives and architecture, consult the accompanying Architecture Guide [draft-hallambaker-mesh-architecture]
This document has two main sections. The first section presents examples of using the Mesh to address common use cases. The second section contains the Mesh profile and service schemas. All the material in both sections is generated from the Mesh reference implementation [draft-hallambaker-mesh-developer] .
Although some of the services described in this document could be used to replace existing Internet protocols including FTP and SMTP, the principal value of any communication protocol lies in the size of the audience it allows them to communicate with. Thus, while the Mesh Messaging service is designed to support efficient and reliable transfer of messages ranging in size from a few bytes to multiple terabytes, the near term applications of these services will be to applications that are not adequately supported by existing protocols if at all.
This section presents the related specifications and standard, the terms that are used as terms of art within the documents and the terms used as requirements language.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] .
The terms of art used in this document are described in the Mesh Architecture Guide [draft-hallambaker-mesh-architecture] .
The architecture of the Mathematical Mesh is described in the Mesh Architecture Guide [draft-hallambaker-mesh-architecture] . The Mesh documentation set and related specifications are described in this document.
The implementation status of the reference code base is described in the companion document [draft-hallambaker-mesh-developer] .
Sync
Rapid access - only take last 100 messages
Limitation on message size ensures that
Obtain updated device profile (if it exists) and the status of the set of catalogs the device is authorized
Read objects from a catalog or spool owned by the client making the request.
Optional filtering criteria MAY be specified to only return objects matching specific criteria and/or only return certain parts of the selected messages.
The transaction MAY be performed in one request/response round trip or with separate round trips to confirm that the transaction is accepted by the service before sending large volumes of data.
Upload objects to a catalog or spool owned by Read objects from a catalog or spool owned by the client making the request.
Multiple objects MAY be uploaded at once. Object updates MAY be conditional on the successful completion of other upload requests.
The transaction MAY be performed in one request/response round trip or with separate round trips to confirm that the transaction is accepted by the service before sending large volumes of data.
Four corner model enforced.
Messages are limited to control with very small amounts of data
Long messages are exchanged as detachments using separate protocol (HTTP).
This ensures that messages are processed quickly and reliably. A server will not be blocked by receipt of a long message.
Aggressive controls on services may be enforced to prevent DoS attacks.
Post transaction is used for client-service and service-service transactions.
Untrusted service, minimize trust to bare minimum
Can't read content of any message.
Can only read contact catalog entries.
Contains the account entries.
Log of all updates to accounts.
Synchronization off-host provides backup.
Reports of potential abuse
Can split out handling of accounts to separate hosts each handling a subset of accounts.
User clients are directed to connect to a specific host in any case by means of redirects.
Synchronizing Account spools protects data against loss and provides for fast restart capability.
Transactions consist of single request message followed by a single response message.
Default binding is HTTPS/DARE/JSON
Hello Transaction may be used to determine features supported by the service and the service configuration
```` Example ProtocolHello ````
```` Example ProtocolHelloDevice ````
```` Example ProtocolHelloProfile ````
```` Example ProtocolHelloTicket ````
```` Example ProtocolAccountCreate ````
```` Example ProtocolAccountDelete ````
```` Example ProtocolStatus ````
```` Example ProtocolDownload ````
```` Example ProtocolProtocolUploadHello ````
```` Example ProtocolConnect ````
```` Example ProtocolConnectPIN ````
```` Example ProtocolConnectEARL ````
All communications between accounts is performed through mesh messages.
Four corner model
```` Example ProtocolContact ````
```` Example ProtocolConfirm ````
Every Mesh Portal Service transaction consists of exactly one request followed by exactly one response. Mesh Service transactions MAY cause modification of the data stored in the Mesh Service or the Mesh itself but do not cause changes to the connection state. The protocol itself is thus idempotent. There is no set sequence in which operations are required to be performed. It is not necessary to perform a Hello transaction prior to any other transaction.
A Mesh Portal Service request consists of a payload object that inherits from the MeshRequest class. When using the HTTP binding, the request MUST specify the portal DNS address in the HTTP Host field.
Base class for all request messages.
[No fields]
Base class for all request messages made by a user.
A Mesh Portal Service response consists of a payload object that inherits from the MeshResponse class. When using the HTTP binding, the response SHOULD report the Status response code in the HTTP response message. However the response code returned in the payload object MUST always be considered authoritative.
Base class for all response messages. Contains only the status code and status description fields.
[No fields]
The Mesh Service protocol makes use of JSON objects defined in the JOSE Signatgure and Encryption specifications and in the DARE Data At Rest Encryption extensions to JOSE.
The following common structures are used in the protocol messages:
Describes a Key/Value structure used to make queries for records matching one or more selection criteria.
Specifies constraints to be applied to a search result. These allow a client to limit the number of records returned, the quantity of data returned, the earliest and latest data returned, etc.
Specifies constraints on the data to be sent.
Describes the account creation policy including constraints on account names, whether there is an open account creation policy, etc.
Report service and version information.
The Hello transaction provides a means of determining which protocol versions, message encodings and transport protocols are supported by the service.
The PostConstraints field MAY be used to advise senders of a maximum size of payload that MAY be sent in an initial Post request.
Request objects from the specified container with the specified search criteria.
Request objects from the specified container(s).
A client MAY request only objects matching specified search criteria be returned and MAY request that only specific fields or parts of the payload be returned.
Return the set of objects requested.
Services SHOULD NOT return a response that is disproportionately large relative to the speed of the network connection without a clear indication from the client that it is relevant. A service MAY limit the number of objects returned. A service MAY limit the scope of each response.
Request objects from the specified container with the specified search criteria.
Upload entries to a container. This request is only valid if it is issued by the owner of the account
Response to an upload request.
Request to post to a spool from an external party. The request and response messages are extensions of the corresponding messages for the Upload transaction. It is expected that additional fields will be added as the need arises.
[No fields]
Request information necessary to begin making a connection request.
Request creation of a new service account.
Attempt
Request creation of a new portal account. The request specifies the requested account identifier and the Mesh profile to be associated with the account.
Reports the success or failure of a Create transaction.
Request deletion of a new service account.
Attempt
Request creation of a new portal account. The request specifies the requested account identifier and the Mesh profile to be associated with the account.
[No fields]
Reports the success or failure of a Delete transaction.
[No fields]
The security considerations for use and implementation of Mesh services and applications are described in the Mesh Security Considerations guide [draft-hallambaker-mesh-security] .
All the IANA considerations for the Mesh documents are specified in this document
| [draft-hallambaker-mesh-architecture] | Hallam-Baker, P., "Mathematical Mesh Part I: Architecture Guide", Internet-Draft draft-hallambaker-mesh-architecture-06, August 2018. |
| [draft-hallambaker-mesh-security] | , "[Reference Not Found!]" |
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
| [draft-hallambaker-mesh-developer] | Hallam-Baker, P., "Mathematical Mesh: Reference Implementation", Internet-Draft draft-hallambaker-mesh-developer-07, April 2018. |