Mathematical Mesh: Reference
Comodo Group Inc.
philliph@comodo.com
Security
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.
NB: The reference material in this document is generated from the schema used to derive the source code. The tool used to create this material has not been optimized to produce output for the IETF documentation format at this time. Consequently the formatting is currently sub-optimal.
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 RFC 2119 [RFC2119].
A profile is a first class object. It has a globally unique identifier that provides an unambiguous reference to the profile in any situation.
A record describes the state of an object at the completion of a specific Transaction.
A transaction is an event in which the state of an object changes. Every transaction has a globally unique transaction identifier. Transaction identifiers are issued in a monotonic sequence such that a transaction that completes at time t1 will always have a lower transaction identifier than one that begins at time t2 where t2 > t1.
The master profile contains the axioms of trust for a Mesh user.
The key used to sign the profile MUST be MasterSigningKey
The Master Signing key is the ultimate trust axiom for the Master Profile.
The key used to sign the profile MUST be a member of MasterProfile/OnlineSignatureKeys
The Master Profile that this personal profile is an instance of.
A list of application profile entries specifying which application profiles are attached to the personal profile
The key used to sign the profile MUST be MasterSigningKey
The Master Signing key is the ultimate trust axiom for the Master Profile.
Container for public key pair data
UDF: String (Optional)
X509Certificate: Binary (Optional)
X509Chain: Binary [0..Many]
X509CSR: Binary (Optional)
Container for JOSE signed data and related attributes.
Data: Binary (Optional)
Container for JOSE encrypted data and related attributes.
Data: Binary (Optional)
Base class for all Mesh Profile objects.
Identifier: String (Optional)
Inherits: Entry
Contains a signed profile entry
SignedData: JoseWebSignature (Optional)
Inherits: Entry
Parent class from which all profile types are derived
Names: String [0..Many]
Updated: DateTime (Optional)
NotaryToken: String (Optional)
Inherits: SignedProfile
Contains a signed device profile
[None]
Inherits: Profile
Describes a mesh device.
Description: String (Optional)
DeviceSignatureKey: PublicKey (Optional)
DeviceAuthenticationKey: PublicKey (Optional)
DeviceEncryptiontionKey: PublicKey (Optional)
Private portion of device encryption profile.
DeviceSignatureKey: Key (Optional)
DeviceAuthenticationKey: Key (Optional)
DeviceEncryptiontionKey: Key (Optional)
Inherits: SignedProfile
Contains a signed Personal master profile
[None]
Inherits: Profile
Describes the long term parameters associated with a personal profile.
MasterSignatureKey: PublicKey (Optional)
MasterEscrowKeys: PublicKey [0..Many]
OnlineSignatureKeys: PublicKey [0..Many]
Inherits: SignedProfile
Contains a signed Personal current profile
[None]
Inherits: Profile
Describes the current applications and devices connected to a personal master profile.
SignedMasterProfile: SignedMasterProfile (Optional)
Devices: SignedDeviceProfile [0..Many]
Applications: ApplicationProfileEntry [0..Many]
Inherits: SignedProfile
Contains a signed device profile
[None]
Inherits: Entry
Contains an encrypted profile entry
EncryptedData: JoseWebEncryption (Optional)
Inherits: Profile
Parent class from which all application profiles inherit.
EncryptedData: JoseWebEncryption (Optional)
Identifier: String (Optional)
Type: String (Optional)
Friendly: String (Optional)
SignID: String [0..Many]
DecryptID: String [0..Many]
Describes network connection parameters for an application
ServiceName: String (Optional)
Port: Integer (Optional)
Prefix: String (Optional)
Security: String [0..Many]
UserName: String (Optional)
Password: String (Optional)
URI: String (Optional)
Authentication: String (Optional)
TimeOut: Integer (Optional)
Polling: Boolean (Optional)
Inherits: ApplicationProfile
Stores usernames and passwords
[None]
AutoGenerate: Boolean (Optional)
Entries: PasswordEntry [0..Many]
NeverAsk: String [0..Many]
Username password entry for a single site
Sites: String [0..Many]
Username: String (Optional)
Password: String (Optional)
Inherits: ApplicationProfile
Public profile describes mail receipt policy. Private describes Sending policy
EncryptionPGP: PublicKey (Optional)
EncryptionSMIME: PublicKey (Optional)
Describes a mail account configuration
Private profile contains connection settings for the inbound and outbound mail server(s) and cryptographic private keys. Public profile may contain security policy information for the sender.
EmailAddress: String (Optional)
ReplyToAddress: String (Optional)
DisplayName: String (Optional)
AccountName: String (Optional)
Inbound: Connection [0..Many]
Outbound: Connection [0..Many]
Sign: PublicKey [0..Many]
Encrypt: PublicKey [0..Many]
Inherits: ApplicationProfile
Describes the network profile to follow
[None]
Describes the network profile to follow
Sites: String [0..Many]
DNS: Connection [0..Many]
Prefix: String [0..Many]
CTL: Binary (Optional)
WebPKI: String [0..Many]
Inherits: Entry
Contains escrowed data
EncryptedData: JoseWebEncryption (Optional)
Inherits: EscrowEntry
Contains data escrowed using the offline escrow mechanism.
[None]
Inherits: EscrowEntry
Contains data escrowed using the online escrow mechanism.
[None]
A set of escrowed keys.
PrivateKeys: Key [0..Many]
Describes a connection request.
ParentUDF: String (Optional)
Device: SignedDeviceProfile (Optional)
Inherits: SignedProfile
Contains a ConnectionRequest signed by the corresponding device signature key.
[None]
Describes the result of a connection request.
Inherits: ConnectionRequest
Result: String (Optional)
Inherits: SignedProfile
Contains a signed connection result
[None]
SRV Prefix:
HTTP Well Known Service Prefix:
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 Portal 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 a ValidateAccount, Publish or 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.
Portal: String (Optional)
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.
A service MAY return either the response message specified for that transaction or any parent of that message. Thus the MeshResponse message MAY be returned in response to any request.
Status: Integer (Optional)
StatusDescription: String (Optional)
The following response codes are returned when a transaction has completed successfully.
[201] SuccessOK
[201] SuccessCreated
[202] SuccessUpdated
The following response codes are returned when a transaction did not complete because the target service has been redirected.
In the case that a redirect code is returned, the StatusDescription field contains the URI of the new service. Note however that the redirect location indicated in a status response might be incorrect or even malicious and cannot be considered trustworthy without appropriate authentication.
[303] RedirectPermanent
[307] RedirectTemporary
A response code in the range 400-499 is returned when the service was able to process the transaction but the transaction resulted in an error.
[401] ClientUnauthorized
[404] NotFound
[409] AlreadyExists
A response code in the range 500-599 is returned when the service was unable to process the transaction but the transaction due to an internal failure.
[500] ServerInternal
[503] ServerOverload
The Mesh Service protocol makes use of JSON objects defined in the JOSE Signatgure and Encryption specifications.
The following common structures are used in the protocol messages:
Describes a protocol version.
Major: Integer (Optional)
Minor: Integer (Optional)
Encodings: Encoding [0..Many]
URI: String [0..Many]
Describes a message content encoding.
ID: String [0..Many]
Dictionary: String [0..Many]
Describes a Key/Value structure used to make queries for records matching one or more selection criteria.
Key: String (Optional)
Value: String (Optional)
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.
NotBefore: DateTime (Optional)
Before: DateTime (Optional)
MaxEntries: Integer (Optional)
MaxBytes: Integer (Optional)
PageKey: String (Optional)
Request: HelloRequest
Response:HelloResponse
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.
Inherits: MeshRequest
[None]
Always reports success. Describes the configuration of the Mesh portal service.
Inherits: MeshResponse
Version: Version (Optional)
Alternates: Version [0..Many]
Request: ValidateRequest
Response:ValidateResponse
Request validation of a proposed name for a new account.
For validation of a user's account name during profile creation.
Inherits: MeshRequest
Describes the proposed account properties. Currently, these are limited to the account name but could be extended in future versions of the protocol.
Account: String (Optional)
Reserve: Boolean (Optional)
Language: String [0..Many]
Inherits: MeshResponse
States whether the proposed account properties are acceptable and (optional) returns an indication of what properties are valid.
Note that receiving a 'Valid' responseto a Validate Request does not guarantee creation of the account. In addition to the possibility that the account namecould be requested by another user between the Validate and Create transactions, a portal service MAY perform more stringent validation criteria when an account is actually being created. For example, checking with the authoritative list of current accounts rather than a cached copy.
Valid: Boolean (Optional)
Minimum: Integer (Optional)
Maximum: Integer (Optional)
InvalidCharacters: String (Optional)
Reason: String (Optional)
Request: CreateRequest
Response:CreateResponse
Request creation of a new portal account.
Unlike a profile, a mesh account is specific to a particular Mesh portal. A mesh account must be created and accepted before a profile can be published.
Request creation of a new portal account. The request specifies the requested account identifier and the Mesh profile to be associated with the account.
Inherits: MeshRequest
Account: String (Optional)
Inherits: MeshResponse
Reports the success or failure of a Create transaction.
[None]
Request: GetRequest
Response:GetResponse
Search for data in the mesh that matches a set of properties described by a sequence of key/value pairs.
Describes the Portal or Mesh data to be retreived.
Inherits: MeshRequest
Identifier: String (Optional)
Account: String (Optional)
KeyValues: KeyValue [0..Many]
SearchConstraints: SearchConstraints (Optional)
Multiple: Boolean (Optional)
Full: Boolean (Optional)
Reports the success or failure of a Get transaction. If a Mesh entry matching the specified profile is found, containsthe list of entries matching the request.
Inherits: MeshResponse
DataItems: DataItem [0..Many]
PageKey: String (Optional)
Request: PublishRequest
Response:PublishResponse
Publish a profile or key escrow entry to the mesh.
Requests publication of the specified Mesh entry.
Inherits: MeshRequest
[None]
Reports the success or failure of a Publish transaction.
Inherits: MeshResponse
[None]
Request: StatusRequest
Response:StatusResponse
Request the current status of the mesh as seen by the portal to which it is directed.
The response to the status request contains the last signed checkpoint and proof chains for each of the peer portals that have been checkpointed.
[Not currently implemented]
Inherits: MeshRequest
Initiates a status transaction.
[None]
Reports the success or failure of a Status transaction.
Inherits: MeshResponse
LastWriteTime: DateTime (Optional)
LastCheckpointTime: DateTime (Optional)
NextCheckpointTime: DateTime (Optional)
CheckpointValue: String (Optional)
Request: ConnectStartRequest
Response:ConnectStartResponse
Request connection of a new device to a mesh profile
Inherits: MeshRequest
Initial device connection request.
SignedRequest: SignedConnectionRequest (Optional)
AccountID: String (Optional)
Reports the success or failure of a ConnectStart transaction.
Inherits: MeshRequest
[None]
Request: ConnectStatusRequest
Response:ConnectStatusResponse
Request status of pending connection request of a new device to a mesh profile
Inherits: MeshRequest
Request status information for a pending request posted previously.
AccountID: String (Optional)
DeviceID: String (Optional)
Reports the success or failure of a ConnectStatus transaction.
Inherits: MeshRequest
Result: SignedConnectionResult (Optional)
Request: ConnectPendingRequest
Response:ConnectPendingResponse
Request a list of pending requests for an administration profile.
Inherits: MeshRequest
Specify the criteria for pending requests.
AccountID: String (Optional)
SearchConstraints: SearchConstraints (Optional)
Reports the success or failure of a ConnectPending transaction.
Inherits: MeshRequest
Pending: SignedConnectionRequest [0..Many]
PageKey: String (Optional)
Request: ConnectCompleteRequest
Response:ConnectCompleteResponse
Post response to a pending connection request.
Reports the success or failure of a ConnectComplete transaction.
Inherits: MeshRequest
Result: SignedConnectionResult (Optional)
AccountID: String (Optional)
Inherits: MeshRequest
Reports the success or failure of a ConnectComplete transaction.
[None]
Request: TransferRequest
Response:TransferResponse
Request a bulk transfer of the log between the specified transaction identifiers. Requires appropriate authorization
[Not currently implemented]
Inherits: MeshRequest
SearchConstraints: SearchConstraints (Optional)
Inherits: MeshResponse
Reports the success or failure of a Transfer transaction. If successful, contains the list of Mesh records to be transferred.
DataItems: DataItem [0..Many]
PageKey: String (Optional)
The precise implementation of the portal service and the data structures representing state at the portal service are outside the scope of this specification.
The specification of the Mesh Portal objects given here is to enable future formal specification of the portal protocols by defining the state changes resulting from portal transactions.
Like the Mesh itself, the state of the portal is tracked by an append only log. This log contains entries binding account identifiers to mesh profiles and lists of pending connections.
Created: DateTime (Optional)
Modified: DateTime (Optional)
Entry containing the UniqueID is Account[Name]-[Portal] Indexed by [Name], [UserProfileUDF] [Most recent open]
Inherits: PortalEntry
AccountID: String (Optional)
UserProfileUDF: String (Optional)
Status: String (Optional)
Inherits: Account
Profile: SignedPersonalProfile (Optional)
Object containing the list of currently pending device connection requests for the specified account. Unique-ID is ConnectionsPending-[UserProfileUDF]
Inherits: Account
Requests: SignedConnectionRequest [0..Many]
All the IANA considerations for the Mesh documents are specified in this document
Key words for use in RFCs to Indicate Requirement Levels
Internet Assigned Numbers Authority (IANA) Procedures for the Management of the Service Name and Transport Protocol Port Number Registry