idnits 2.17.1 draft-hallambaker-mesh-reference-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 334 has weird spacing: '... of the entry...' == Line 462 has weird spacing: '... escrow of pr...' == Line 467 has weird spacing: '... sign devic...' == Line 887 has weird spacing: '...request is di...' == Line 912 has weird spacing: '...bugging and l...' == (8 more instances...) -- The document date (May 9, 2017) is 2543 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'None' is mentioned on line 1512, but not defined -- Looks like a reference, but probably isn't: '201' on line 924 -- Looks like a reference, but probably isn't: '202' on line 928 -- Looks like a reference, but probably isn't: '303' on line 943 -- Looks like a reference, but probably isn't: '307' on line 947 -- Looks like a reference, but probably isn't: '401' on line 957 -- Looks like a reference, but probably isn't: '404' on line 961 -- Looks like a reference, but probably isn't: '409' on line 965 -- Looks like a reference, but probably isn't: '500' on line 975 -- Looks like a reference, but probably isn't: '503' on line 979 == Missing Reference: 'Name' is mentioned on line 1584, but not defined == Missing Reference: 'UserProfileUDF' is mentioned on line 1584, but not defined Summary: 0 errors (**), 0 flaws (~~), 10 warnings (==), 10 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 Comodo Group Inc. 4 Intended status: Standards Track May 9, 2017 5 Expires: November 10, 2017 7 Mathematical Mesh: Reference 8 draft-hallambaker-mesh-reference-04 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 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on November 10, 2017. 35 Copyright Notice 37 Copyright (c) 2017 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 53 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 2.1. Requirements Language . . . . . . . . . . . . . . . . . . 4 55 3. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 5 56 3.1. Data Model . . . . . . . . . . . . . . . . . . . . . . . 5 57 3.1.1. First Class Object . . . . . . . . . . . . . . . . . 5 58 3.1.2. Profile . . . . . . . . . . . . . . . . . . . . . . . 5 59 3.1.3. Record . . . . . . . . . . . . . . . . . . . . . . . 5 60 3.1.4. Transaction . . . . . . . . . . . . . . . . . . . . . 5 61 3.2. Profile Types . . . . . . . . . . . . . . . . . . . . . . 5 62 3.3. Master Profile . . . . . . . . . . . . . . . . . . . . . 5 63 3.4. Personal Profile . . . . . . . . . . . . . . . . . . . . 6 64 3.5. Device Profile . . . . . . . . . . . . . . . . . . . . . 6 65 3.6. Application Profile . . . . . . . . . . . . . . . . . . . 6 66 4. Cryptographic Data Objects . . . . . . . . . . . . . . . . . 7 67 4.1. Public Key Objects . . . . . . . . . . . . . . . . . . . 7 68 4.1.1. Structure: PublicKey . . . . . . . . . . . . . . . . 7 69 4.2. JOSE Signature Objects . . . . . . . . . . . . . . . . . 7 70 4.2.1. Structure: SignedData . . . . . . . . . . . . . . . . 7 71 4.3. JOSE Encryption Objects . . . . . . . . . . . . . . . . . 7 72 4.3.1. Structure: EncryptedData . . . . . . . . . . . . . . 7 73 5. Mesh Profile Objects . . . . . . . . . . . . . . . . . . . . 8 74 5.1. Base Profile Objects . . . . . . . . . . . . . . . . . . 8 75 5.1.1. Structure: Entry . . . . . . . . . . . . . . . . . . 8 76 5.1.2. Structure: SignedProfile . . . . . . . . . . . . . . 8 77 5.1.3. Structure: Profile . . . . . . . . . . . . . . . . . 8 78 5.2. Device Profile Objects . . . . . . . . . . . . . . . . . 9 79 5.2.1. Structure: SignedDeviceProfile . . . . . . . . . . . 9 80 5.2.2. Structure: DeviceProfile . . . . . . . . . . . . . . 9 81 5.2.3. Structure: DevicePrivateProfile . . . . . . . . . . . 10 82 5.3. Master Profile Objects . . . . . . . . . . . . . . . . . 10 83 5.3.1. Structure: SignedMasterProfile . . . . . . . . . . . 10 84 5.3.2. Structure: MasterProfile . . . . . . . . . . . . . . 11 85 5.4. Personal Profile Objects . . . . . . . . . . . . . . . . 11 86 5.4.1. Structure: SignedPersonalProfile . . . . . . . . . . 11 87 5.4.2. Structure: PersonalProfile . . . . . . . . . . . . . 12 88 5.5. Application Profile Objects . . . . . . . . . . . . . . . 12 89 5.5.1. Structure: SignedApplicationProfile . . . . . . . . . 12 90 5.5.2. Structure: EncryptedProfile . . . . . . . . . . . . . 12 91 5.5.3. Structure: ApplicationProfile . . . . . . . . . . . . 13 92 5.5.4. Structure: ApplicationProfileEntry . . . . . . . . . 13 93 5.6. Common Application Objects . . . . . . . . . . . . . . . 14 94 5.6.1. Structure: Connection . . . . . . . . . . . . . . . . 14 95 5.7. Password Application Profile Objects . . . . . . . . . . 15 96 5.7.1. Structure: PasswordProfile . . . . . . . . . . . . . 15 97 5.7.2. Structure: PasswordProfilePrivate . . . . . . . . . . 15 98 5.7.3. Structure: PasswordEntry . . . . . . . . . . . . . . 16 99 5.8. Mail Application Profile Objects . . . . . . . . . . . . 16 100 5.8.1. Structure: MailProfile . . . . . . . . . . . . . . . 16 101 5.8.2. Structure: MailProfilePrivate . . . . . . . . . . . . 17 102 5.9. Network Application Profile Objects . . . . . . . . . . . 18 103 5.9.1. Structure: NetworkProfile . . . . . . . . . . . . . . 18 104 5.9.2. Structure: NetworkProfilePrivate . . . . . . . . . . 18 105 5.10. Key Escrow Objects . . . . . . . . . . . . . . . . . . . 19 106 5.10.1. Structure: EscrowEntry . . . . . . . . . . . . . . . 19 107 5.10.2. Structure: OfflineEscrowEntry . . . . . . . . . . . 19 108 5.10.3. Structure: OnlineEscrowEntry . . . . . . . . . . . . 20 109 5.10.4. Structure: EscrowedKeySet . . . . . . . . . . . . . 20 110 6. Portal Connection . . . . . . . . . . . . . . . . . . . . . . 20 111 6.1. Connection Request and Response Structures . . . . . . . 20 112 6.1.1. Structure: ConnectionRequest . . . . . . . . . . . . 20 113 6.1.2. Structure: SignedConnectionRequest . . . . . . . . . 20 114 6.1.3. Structure: ConnectionResult . . . . . . . . . . . . . 21 115 6.1.4. Structure: SignedConnectionResult . . . . . . . . . . 21 116 7. Mesh Portal Service Reference . . . . . . . . . . . . . . . . 21 117 7.1. Request Messages . . . . . . . . . . . . . . . . . . . . 22 118 7.1.1. Message: MeshRequest . . . . . . . . . . . . . . . . 22 119 7.2. Response Messages . . . . . . . . . . . . . . . . . . . . 22 120 7.2.1. Message: MeshResponse . . . . . . . . . . . . . . . . 22 121 7.2.2. Successful Response Codes . . . . . . . . . . . . . . 23 122 7.2.3. Warning Response Codes . . . . . . . . . . . . . . . 23 123 7.2.4. Error Response Codes . . . . . . . . . . . . . . . . 24 124 7.2.5. Failure Response Codes . . . . . . . . . . . . . . . 24 125 7.3. Imported Objects . . . . . . . . . . . . . . . . . . . . 24 126 7.4. Common Structures . . . . . . . . . . . . . . . . . . . . 25 127 7.4.1. Structure: Version . . . . . . . . . . . . . . . . . 25 128 7.4.2. Structure: Encoding . . . . . . . . . . . . . . . . . 25 129 7.4.3. Structure: KeyValue . . . . . . . . . . . . . . . . . 26 130 7.4.4. Structure: SearchConstraints . . . . . . . . . . . . 26 131 7.5. Transaction: Hello . . . . . . . . . . . . . . . . . . . 27 132 7.5.1. Message: HelloRequest . . . . . . . . . . . . . . . . 27 133 7.5.2. Message: HelloResponse . . . . . . . . . . . . . . . 27 134 7.6. Transaction: ValidateAccount . . . . . . . . . . . . . . 28 135 7.6.1. Message: ValidateRequest . . . . . . . . . . . . . . 28 136 7.6.2. Message: ValidateResponse . . . . . . . . . . . . . . 29 137 7.7. Transaction: CreateAccount . . . . . . . . . . . . . . . 30 138 7.7.1. Message: CreateRequest . . . . . . . . . . . . . . . 30 139 7.7.2. Message: CreateResponse . . . . . . . . . . . . . . . 30 140 7.8. Transaction: Get . . . . . . . . . . . . . . . . . . . . 30 141 7.8.1. Message: GetRequest . . . . . . . . . . . . . . . . . 31 142 7.8.2. Message: GetResponse . . . . . . . . . . . . . . . . 32 143 7.9. Transaction: Publish . . . . . . . . . . . . . . . . . . 32 144 7.9.1. Message: PublishRequest . . . . . . . . . . . . . . . 32 145 7.9.2. Message: PublishResponse . . . . . . . . . . . . . . 32 147 7.10. Transaction: Status . . . . . . . . . . . . . . . . . . . 33 148 7.10.1. Message: StatusRequest . . . . . . . . . . . . . . . 33 149 7.10.2. Message: StatusResponse . . . . . . . . . . . . . . 33 150 7.11. Transaction: ConnectStart . . . . . . . . . . . . . . . . 34 151 7.11.1. Message: ConnectStartRequest . . . . . . . . . . . . 34 152 7.11.2. Message: ConnectStartResponse . . . . . . . . . . . 34 153 7.12. Transaction: ConnectStatus . . . . . . . . . . . . . . . 35 154 7.12.1. Message: ConnectStatusRequest . . . . . . . . . . . 35 155 7.12.2. Message: ConnectStatusResponse . . . . . . . . . . . 35 156 7.13. Transaction: ConnectPending . . . . . . . . . . . . . . . 36 157 7.13.1. Message: ConnectPendingRequest . . . . . . . . . . . 36 158 7.13.2. Message: ConnectPendingResponse . . . . . . . . . . 36 159 7.14. Transaction: ConnectComplete . . . . . . . . . . . . . . 37 160 7.14.1. Message: ConnectCompleteRequest . . . . . . . . . . 37 161 7.14.2. Message: ConnectCompleteResponse . . . . . . . . . . 37 162 7.15. Transaction: Transfer . . . . . . . . . . . . . . . . . . 38 163 7.15.1. Message: TransferRequest . . . . . . . . . . . . . . 38 164 7.15.2. Message: TransferResponse . . . . . . . . . . . . . 38 165 8. Mesh Portal Objects . . . . . . . . . . . . . . . . . . . . . 39 166 8.1. Mesh Portal Log Entries . . . . . . . . . . . . . . . . . 39 167 8.1.1. Structure: PortalEntry . . . . . . . . . . . . . . . 39 168 8.1.2. Structure: Account . . . . . . . . . . . . . . . . . 39 169 8.1.3. Structure: AccountProfile . . . . . . . . . . . . . . 40 170 8.1.4. Structure: ConnectionsPending . . . . . . . . . . . . 40 171 9. Security Considerations . . . . . . . . . . . . . . . . . . . 40 172 9.1. Confidentiality . . . . . . . . . . . . . . . . . . . . . 40 173 9.2. Integrity . . . . . . . . . . . . . . . . . . . . . . . . 40 174 9.3. Service . . . . . . . . . . . . . . . . . . . . . . . . . 41 175 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41 176 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 41 177 12. Normative References . . . . . . . . . . . . . . . . . . . . 41 178 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 41 180 1. Introduction 182 NB: The reference material in this document is generated from the 183 schema used to derive the source code. The tool used to create this 184 material has not been optimized to produce output for the IETF 185 documentation format at this time. Consequently the formatting is 186 currently sub-optimal. 188 2. Definitions 190 2.1. Requirements Language 192 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 193 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 194 document are to be interpreted as described in RFC 2119 [RFC2119]. 196 3. Architecture 198 3.1. Data Model 200 3.1.1. First Class Object 202 3.1.2. Profile 204 A profile is a first class object. It has a globally unique 205 identifier that provides an unambiguous reference to the profile in 206 any situation. 208 3.1.3. Record 210 A record describes the state of an object at the completion of a 211 specific Transaction. 213 3.1.4. Transaction 215 A transaction is an event in which the state of an object changes. 216 Every transaction has a globally unique transaction identifier. 217 Transaction identifiers are issued in a monotonic sequence such that 218 a transaction that completes at time t1 will always have a lower 219 transaction identifier than one that begins at time t2 where t2 > t1. 221 3.2. Profile Types 223 Master Profile 225 Personal Profile 227 Application Profile 229 Device Profile 231 3.3. Master Profile 233 The master profile contains the axioms of trust for a Mesh user. 235 Identifier: "Master" + UDF Fingerprint of the Master Signing Key 237 Signature: Master Signing Key The key used to sign the profile 238 MUST be MasterSigningKey 240 Property: Master Signing Key The Master Signing key is the 241 ultimate trust axiom for the Master Profile. 243 Property: Master Escrow Keys 245 Property: Online Signature Keys 247 3.4. Personal Profile 249 Identifier: UDF Fingerprint of the Master Signing Key 251 Signature: Online Signature Key The key used to sign the profile 252 MUST be a member of MasterProfile/OnlineSignatureKeys 254 Property: Master Profile The Master Profile that this personal 255 profile is an instance of. 257 Property: Devices 259 Property: Applications A list of application profile entries 260 specifying which application profiles are attached to the 261 personal profile 263 3.5. Device Profile 265 Identifier: UDF Fingerprint of the Device Signing Key 267 Signature: Device Signing Key The key used to sign the profile 268 MUST be MasterSigningKey 270 Property: Device Signing Key The Master Signing key is the 271 ultimate trust axiom for the Master Profile. 273 Property: Device Encryption Key 275 Property: Device Authentication Key 277 3.6. Application Profile 279 Identifier: Randomly chosen 281 Property: Encrypted Data 283 4. Cryptographic Data Objects 285 4.1. Public Key Objects 287 4.1.1. Structure: PublicKey 289 Container for public key pair data 291 UDF: String (Optional) 293 UDF fingerprint of the key 295 X509Certificate: Binary (Optional) 297 List of X.509 Certificates 299 X509Chain: Binary [0..Many] 301 X.509 Certificate chain. 303 X509CSR: Binary (Optional) 305 X.509 Certificate Signing Request. 307 4.2. JOSE Signature Objects 309 4.2.1. Structure: SignedData 311 Container for JOSE signed data and related attributes. 313 Data: Binary (Optional) 315 4.3. JOSE Encryption Objects 317 4.3.1. Structure: EncryptedData 319 Container for JOSE encrypted data and related attributes. 321 Data: Binary (Optional) 323 5. Mesh Profile Objects 325 5.1. Base Profile Objects 327 5.1.1. Structure: Entry 329 Base class for all Mesh Profile objects. 331 Identifier: String (Optional) 333 Globally unique identifier that remains constant for the lifetime 334 of the entry. 336 5.1.2. Structure: SignedProfile 338 o 340 * Inherits: Entry 342 Contains a signed profile entry 344 SignedData: JoseWebSignature (Optional) 346 The signed profile. 348 Note that each child of SignedProfile requires that the Payload 349 field of the SignedData object contain an object of a specific 350 type. For example, a SignedDeviceProfile object MUST contain a 351 Payload field that contains a DeviceProfile object. 353 5.1.3. Structure: Profile 355 o 357 * Inherits: Entry 359 Parent class from which all profile types are derived 361 Names: String [0..Many] 363 Fingerprints of index terms for profile retrieval. The use of the 364 fingerprint of the name rather than the name itself is a 366 precaution against enumeration attacks and other forms of abuse. 368 Updated: DateTime (Optional) 370 The time instant the profile was last modified. 372 NotaryToken: String (Optional) 374 A Uniform Notary Token providing evidence that a signature was 375 performed after the notary token was created. 377 5.2. Device Profile Objects 379 5.2.1. Structure: SignedDeviceProfile 381 o 383 * Inherits: SignedProfile 385 Contains a signed device profile 387 [None] 389 5.2.2. Structure: DeviceProfile 391 o 393 * Inherits: Profile 395 Describes a mesh device. 397 Description: String (Optional) 399 Description of the device 401 DeviceSignatureKey: PublicKey (Optional) 403 Key used to sign certificates for the DAK and DEK. The 404 fingerprint of the DSK is the UniqueID of the Device Profile 406 DeviceAuthenticationKey: PublicKey (Optional) 408 Key used to authenticate requests made by the device. 410 DeviceEncryptiontionKey: PublicKey (Optional) 412 Key used to pass encrypted data to the device such as a 413 DeviceUseEntry 415 5.2.3. Structure: DevicePrivateProfile 417 Private portion of device encryption profile. 419 DeviceSignatureKey: Key (Optional) 421 Private portion of the DeviceSignatureKey 423 DeviceAuthenticationKey: Key (Optional) 425 Private portion of the DeviceAuthenticationKey 427 DeviceEncryptiontionKey: Key (Optional) 429 Private portion of the DeviceEncryptiontionKey 431 5.3. Master Profile Objects 433 5.3.1. Structure: SignedMasterProfile 435 o 437 * Inherits: SignedProfile 439 Contains a signed Personal master profile 441 [None] 443 5.3.2. Structure: MasterProfile 445 o 447 * Inherits: Profile 449 Describes the long term parameters associated with a personal 450 profile. 452 MasterSignatureKey: PublicKey (Optional) 454 The root of trust for the Personal PKI, the public key of the PMSK 455 is presented as a self-signed X.509v3 certificate with 456 Certificate Signing use enabled. The PMSK is used to sign 457 certificates for the PMEK, POSK and PKEK keys. 459 MasterEscrowKeys: PublicKey [0..Many] 461 A Personal Profile MAY contain one or more PMEK keys to enable 462 escrow of private keys used for stored data. 464 OnlineSignatureKeys: PublicKey [0..Many] 466 A Personal profile contains at least one POSK which is used to 467 sign device administration application profiles. 469 5.4. Personal Profile Objects 471 5.4.1. Structure: SignedPersonalProfile 473 o 475 * Inherits: SignedProfile 477 Contains a signed Personal current profile 479 [None] 481 5.4.2. Structure: PersonalProfile 483 o 485 * Inherits: Profile 487 Describes the current applications and devices connected to a 488 personal master profile. 490 SignedMasterProfile: SignedMasterProfile (Optional) 492 The corresponding master profile. The profile MUST be signed by 493 the PMSK. 495 Devices: SignedDeviceProfile [0..Many] 497 The set of device profiles connected to the profile. The profile 498 MUST be signed by the DSK in the profile. 500 Applications: ApplicationProfileEntry [0..Many] 502 Application profiles connected to this profile. 504 5.5. Application Profile Objects 506 5.5.1. Structure: SignedApplicationProfile 508 o 510 * Inherits: SignedProfile 512 Contains a signed device profile 514 [None] 516 5.5.2. Structure: EncryptedProfile 518 o 520 * Inherits: Entry 522 Contains an encrypted profile entry 523 EncryptedData: JoseWebEncryption (Optional) 525 The signed and encrypted profile 527 5.5.3. Structure: ApplicationProfile 529 o 531 * Inherits: Profile 533 Parent class from which all application profiles inherit. 535 EncryptedData: JoseWebEncryption (Optional) 537 Encrypted application data 539 5.5.4. Structure: ApplicationProfileEntry 541 Identifier: String (Optional) 543 The unique identifier of the application 545 Type: String (Optional) 547 The application type 549 Friendly: String (Optional) 551 Optional friendly name identifying the application. 553 SignID: String [0..Many] 555 List of devices authorized to sign application profiles 557 DecryptID: String [0..Many] 558 List of devices authorized to read private parts of application 559 profiles 561 5.6. Common Application Objects 563 5.6.1. Structure: Connection 565 Describes network connection parameters for an application 567 ServiceName: String (Optional) 569 DNS address of the server 571 Port: Integer (Optional) 573 TCP/UDP Port number 575 Prefix: String (Optional) 577 DNS service prefix as described in [RFC6335] 579 Security: String [0..Many] 581 Describes the security mode to use. Valid choices are 582 Direct/Upgrade/None 584 UserName: String (Optional) 586 Username to present to the service for authentication 588 Password: String (Optional) 590 Password to present to the service for authentication 592 URI: String (Optional) 593 Service connection parameters in URI format 595 Authentication: String (Optional) 597 List of the supported/acceptable authentication mechanisms, 598 preferred mechanism first. 600 TimeOut: Integer (Optional) 602 Service timeout in seconds. 604 Polling: Boolean (Optional) 606 If set, the client should poll the specified service 607 intermittently for updates. 609 5.7. Password Application Profile Objects 611 5.7.1. Structure: PasswordProfile 613 o 615 * Inherits: ApplicationProfile 617 Stores usernames and passwords 619 [None] 621 5.7.2. Structure: PasswordProfilePrivate 623 AutoGenerate: Boolean (Optional) 625 If true, a client MAY offer to automatically generate strong (i.e. 626 not memorable) passwords for a user. A user would not normally 627 want to use this feature unless they have access to Mesh password 628 management on every device they use to browse the Web 630 Entries: PasswordEntry [0..Many] 631 A list of password credential entries. 633 NeverAsk: String [0..Many] 635 A list of domain names of sites for which clients MUST NOT ask to 636 store passwords for. 638 5.7.3. Structure: PasswordEntry 640 Username password entry for a single site 642 Sites: String [0..Many] 644 DNS name of site *.example.com matches www.example.com etc. 646 Username: String (Optional) 648 Case sensitive username 650 Password: String (Optional) 652 Case sensitive password. 654 5.8. Mail Application Profile Objects 656 5.8.1. Structure: MailProfile 658 o 660 * Inherits: ApplicationProfile 662 Public profile describes mail receipt policy. Private describes 663 Sending policy 665 EncryptionPGP: PublicKey (Optional) 667 The current OpenPGP encryption key 669 EncryptionSMIME: PublicKey (Optional) 671 The current S/MIME encryption key 673 5.8.2. Structure: MailProfilePrivate 675 Describes a mail account configuration 677 Private profile contains connection settings for the inbound and 678 outbound mail server(s) and cryptographic private keys. Public 679 profile may contain security policy information for the sender. 681 EmailAddress: String (Optional) 683 The RFC822 Email address. [e.g. "alice@example.com"] 685 ReplyToAddress: String (Optional) 687 The RFC822 Reply toEmail address. [e.g. "alice@example.com"] 689 When set, allows a sender to tell the receiver that replies to 690 this account should be directed to this address. 692 DisplayName: String (Optional) 694 The Display Name. [e.g. "Alice Example"] 696 AccountName: String (Optional) 698 The Account Name for display to the app user [e.g. "Work 699 Account"] 701 Inbound: Connection [0..Many] 703 The Inbound Mail Connection(s). This is typically IMAP4 or POP3 704 If multiple connections are specified, the order in the sequence 705 indicates the preference order. 707 Outbound: Connection [0..Many] 709 The Outbound Mail Connection(s). This is typically SMTP/SUBMIT 711 If multiple connections are specified, the order in the sequence 712 indicates the preference order. 714 Sign: PublicKey [0..Many] 716 The public keypair(s) for signing and decrypting email. 718 If multiple public keys are specified, the order indicates 719 preference. 721 Encrypt: PublicKey [0..Many] 723 The public keypairs for encrypting and decrypting email. 725 If multiple public keys are specified, the order indicates 726 preference. 728 5.9. Network Application Profile Objects 730 5.9.1. Structure: NetworkProfile 732 o 734 * Inherits: ApplicationProfile 736 Describes the network profile to follow 738 [None] 740 5.9.2. Structure: NetworkProfilePrivate 742 Describes the network profile to follow 744 Sites: String [0..Many] 745 DNS name of sites to which profile applies *.example.com matches 746 www.example.com etc. 748 DNS: Connection [0..Many] 750 DNS Resolution Services 752 Prefix: String [0..Many] 754 DNS prefixes to search 756 CTL: Binary (Optional) 758 Certificate Trust List giving WebPKI roots to trust 760 WebPKI: String [0..Many] 762 List of UDF fingerprints of keys making up the trust roots to be 763 accepted for Web PKI purposes. 765 5.10. Key Escrow Objects 767 5.10.1. Structure: EscrowEntry 769 o 771 * Inherits: Entry 773 Contains escrowed data 775 EncryptedData: JoseWebEncryption (Optional) 777 5.10.2. Structure: OfflineEscrowEntry 779 o 781 * Inherits: EscrowEntry 783 Contains data escrowed using the offline escrow mechanism. 785 [None] 787 5.10.3. Structure: OnlineEscrowEntry 789 o 791 * Inherits: EscrowEntry 793 Contains data escrowed using the online escrow mechanism. 795 [None] 797 5.10.4. Structure: EscrowedKeySet 799 A set of escrowed keys. 801 PrivateKeys: Key [0..Many] 803 The escrowed keys. 805 6. Portal Connection 807 6.1. Connection Request and Response Structures 809 6.1.1. Structure: ConnectionRequest 811 Describes a connection request. 813 ParentUDF: String (Optional) 815 UDF of Mesh Profile to which connection is requested. 817 Device: SignedDeviceProfile (Optional) 819 The Device profile to be connected 821 6.1.2. Structure: SignedConnectionRequest 823 o 825 * Inherits: SignedProfile 827 Contains a ConnectionRequest signed by the corresponding device 828 signature key. 830 [None] 832 6.1.3. Structure: ConnectionResult 834 Describes the result of a connection request. 836 o 838 * Inherits: ConnectionRequest 840 Result: String (Optional) 842 The result of the connection request. Valid responses are: 843 Accepted, Refused, Query. 845 6.1.4. Structure: SignedConnectionResult 847 o 849 * Inherits: SignedProfile 851 Contains a signed connection result 853 [None] 855 7. Mesh Portal Service Reference 857 SRV Prefix: 859 _mmm._tcp 861 HTTP Well Known Service Prefix: 863 /.well-known/mmm 865 Every Mesh Portal Service transaction consists of exactly one request 866 followed by exactly one response. Mesh Service transactions MAY 867 cause modification of the data stored in the Mesh Portal or the Mesh 868 itself but do not cause changes to the connection state. The 869 protocol itself is thus idempotent. There is no set sequence in 870 which operations are required to be performed. It is not necessary 871 to perform a Hello transaction prior to a ValidateAccount, Publish or 872 any other transaction. 874 7.1. Request Messages 876 A Mesh Portal Service request consists of a payload object that 877 inherits from the MeshRequest class. When using the HTTP binding, 878 the request MUST specify the portal DNS address in the HTTP Host 879 field. 881 7.1.1. Message: MeshRequest 883 Base class for all request messages. 885 Portal: String (Optional) 887 Name of the Mesh Portal Service to which the request is directed. 889 7.2. Response Messages 891 A Mesh Portal Service response consists of a payload object that 892 inherits from the MeshResponse class. When using the HTTP binding, 893 the response SHOULD report the Status response code in the HTTP 894 response message. However the response code returned in the payload 895 object MUST always be considered authoritative. 897 7.2.1. Message: MeshResponse 899 Base class for all response messages. Contains only the status code 900 and status description fields. 902 A service MAY return either the response message specified for that 903 transaction or any parent of that message. Thus the MeshResponse 904 message MAY be returned in response to any request. 906 Status: Integer (Optional) 908 Status return code. The SMTP/HTTP scheme of 2xx = Success, 3xx = 909 incomplete, 4xx = failure is followed. 911 StatusDescription: String (Optional) 912 Text description of the status return code for debugging and log 913 file use. 915 7.2.2. Successful Response Codes 917 The following response codes are returned when a transaction has 918 completed successfully. 920 [201] SuccessOK 922 Operation completed successfully 924 [201] SuccessCreated 926 Operation completed successfully, new data item created 928 [202] SuccessUpdated 930 Operation completed successfully, data item was updated 932 7.2.3. Warning Response Codes 934 The following response codes are returned when a transaction did not 935 complete because the target service has been redirected. 937 In the case that a redirect code is returned, the StatusDescription 938 field contains the URI of the new service. Note however that the 939 redirect location indicated in a status response might be incorrect 940 or even malicious and cannot be considered trustworthy without 941 appropriate authentication. 943 [303] RedirectPermanent 945 Service has been permanently moved 947 [307] RedirectTemporary 949 Service has been temporarily moved 951 7.2.4. Error Response Codes 953 A response code in the range 400-499 is returned when the service was 954 able to process the transaction but the transaction resulted in an 955 error. 957 [401] ClientUnauthorized 959 Client is not authorized to perform specified request 961 [404] NotFound 963 The requested object could not be found. 965 [409] AlreadyExists 967 The requested object already exists. 969 7.2.5. Failure Response Codes 971 A response code in the range 500-599 is returned when the service was 972 unable to process the transaction but the transaction due to an 973 internal failure. 975 [500] ServerInternal 977 An internal error occurred at the server 979 [503] ServerOverload 981 The server cannot handle the request as it is overloaded 983 7.3. Imported Objects 985 The Mesh Service protocol makes use of JSON objects defined in the 986 JOSE Signatgure and Encryption specifications. 988 7.4. Common Structures 990 The following common structures are used in the protocol messages: 992 7.4.1. Structure: Version 994 Describes a protocol version. 996 Major: Integer (Optional) 998 Major version number of the service protocol. A higher 1000 Minor: Integer (Optional) 1002 Minor version number of the service protocol. 1004 Encodings: Encoding [0..Many] 1006 Enumerates alternative encodings (e.g. ASN.1, XML, JSON-B) 1007 supported by the service. If no encodings are specified, the JSON 1008 encoding is assumed. 1010 URI: String [0..Many] 1012 The preferred URI for this service. This MAY be used to effect a 1013 redirect in the case that a service moves. 1015 7.4.2. Structure: Encoding 1017 Describes a message content encoding. 1019 ID: String [0..Many] 1021 The IANA encoding name 1023 Dictionary: String [0..Many] 1024 For encodings that employ a named dictionary for tag or data 1025 compression, the name of the dictionary as defined by that 1026 encoding scheme. 1028 7.4.3. Structure: KeyValue 1030 Describes a Key/Value structure used to make queries for records 1031 matching one or more selection criteria. 1033 Key: String (Optional) 1035 The data retrieval key. 1037 Value: String (Optional) 1039 The data value to match. 1041 7.4.4. Structure: SearchConstraints 1043 Specifies constraints to be applied to a search result. These allow 1044 a client to limit the number of records returned, the quantity of 1045 data returned, the earliest and latest data returned, etc. 1047 NotBefore: DateTime (Optional) 1049 Only data published on or after the specified time instant is 1050 requested. 1052 Before: DateTime (Optional) 1054 Only data published before the specified time instant is 1055 requested. This excludes data published at the specified time 1056 instant. 1058 MaxEntries: Integer (Optional) 1060 Maximum number of data entries to return. 1062 MaxBytes: Integer (Optional) 1064 Maximum number of data bytes to return. 1066 PageKey: String (Optional) 1068 Specifies a page key returned in a previous search operation in 1069 which the number of responses exceeded the specified bounds. 1071 When a page key is specified, all the other search parameters 1072 except for MaxEntries and MaxBytes are ignored and the service 1073 returns the next set of data responding to the earlier query. 1075 7.5. Transaction: Hello 1077 Request: HelloRequest 1079 Response:HelloResponse 1081 Report service and version information. 1083 The Hello transaction provides a means of determining which protocol 1084 versions, message encodings and transport protocols are supported by 1085 the service. 1087 7.5.1. Message: HelloRequest 1089 o 1091 * Inherits: MeshRequest 1093 [None] 1095 7.5.2. Message: HelloResponse 1097 Always reports success. Describes the configuration of the Mesh 1098 portal service. 1100 o 1102 * Inherits: MeshResponse 1104 Version: Version (Optional) 1105 Enumerates the protocol versions supported 1107 Alternates: Version [0..Many] 1109 Enumerates alternate protocol version(s) supported 1111 7.6. Transaction: ValidateAccount 1113 Request: ValidateRequest 1115 Response:ValidateResponse 1117 Request validation of a proposed name for a new account. 1119 For validation of a user's account name during profile creation. 1121 7.6.1. Message: ValidateRequest 1123 o 1125 * Inherits: MeshRequest 1127 Describes the proposed account properties. Currently, these are 1128 limited to the account name but could be extended in future versions 1129 of the protocol. 1131 Account: String (Optional) 1133 Account name requested 1135 Reserve: Boolean (Optional) 1137 If true, request a reservation for the specified account name. 1138 Note that the service is not obliged to honor reservation 1139 requests. 1141 Language: String [0..Many] 1143 List of ISO language codes in order of preference. For creating 1144 explanatory text. 1146 7.6.2. Message: ValidateResponse 1148 o 1150 * Inherits: MeshResponse 1152 States whether the proposed account properties are acceptable and 1153 (optional) returns an indication of what properties are valid. 1155 Note that receiving a 'Valid' responseto a Validate Request does not 1156 guarantee creation of the account. In addition to the possibility 1157 that the account namecould be requested by another user between the 1158 Validate and Create transactions, a portal service MAY perform more 1159 stringent validation criteria when an account is actually being 1160 created. For example, checking with the authoritative list of 1161 current accounts rather than a cached copy. 1163 Valid: Boolean (Optional) 1165 If true, the specified account identifier is acceptable. If 1166 false, the account identifier is rejected. 1168 Minimum: Integer (Optional) 1170 Specifies the minimum length of an account name. 1172 Maximum: Integer (Optional) 1174 Specifies the maximum length of an account name. 1176 InvalidCharacters: String (Optional) 1178 A list of characters that the service does not accept in account 1179 names. The list of characters MAY not be exhaustive but SHOULD 1180 include any illegal characters in the proposed account name. 1182 Reason: String (Optional) 1183 Text explaining the reason an account name was rejected. 1185 7.7. Transaction: CreateAccount 1187 Request: CreateRequest 1189 Response:CreateResponse 1191 Request creation of a new portal account. 1193 Unlike a profile, a mesh account is specific to a particular Mesh 1194 portal. A mesh account must be created and accepted before a profile 1195 can be published. 1197 7.7.1. Message: CreateRequest 1199 Request creation of a new portal account. The request specifies the 1200 requested account identifier and the Mesh profile to be associated 1201 with the account. 1203 o 1205 * Inherits: MeshRequest 1207 Account: String (Optional) 1209 Account identifier requested. 1211 7.7.2. Message: CreateResponse 1213 o 1215 * Inherits: MeshResponse 1217 Reports the success or failure of a Create transaction. 1219 [None] 1221 7.8. Transaction: Get 1223 Request: GetRequest 1225 Response:GetResponse 1227 Search for data in the mesh that matches a set of properties 1228 described by a sequence of key/value pairs. 1230 7.8.1. Message: GetRequest 1232 Describes the Portal or Mesh data to be retreived. 1234 o 1236 * Inherits: MeshRequest 1238 Identifier: String (Optional) 1240 Lookup by profile ID 1242 Account: String (Optional) 1244 Lookup by Account ID 1246 KeyValues: KeyValue [0..Many] 1248 List of KeyValue pairs specifying the conditions to be met 1250 SearchConstraints: SearchConstraints (Optional) 1252 Constrain the search to a specific time interval and/or limit the 1253 number and/or total size of data records returned. 1255 Multiple: Boolean (Optional) 1257 If true return multiple responses if available 1259 Full: Boolean (Optional) 1261 If true, the client requests that the full Mesh data record be 1262 returned containing both the Mesh entry itself and the Mesh 1263 metadata that allows the date and time of the publication of the 1264 Mesh entry to be verified. 1266 7.8.2. Message: GetResponse 1268 Reports the success or failure of a Get transaction. If a Mesh entry 1269 matching the specified profile is found, containsthe list of entries 1270 matching the request. 1272 o 1274 * Inherits: MeshResponse 1276 DataItems: DataItem [0..Many] 1278 List of mesh data records matching the request. 1280 PageKey: String (Optional) 1282 If non-null, indicates that the number and/or size of the data 1283 records returned exceeds either the SearchConstraints specified in 1284 the request or internal server limits. 1286 7.9. Transaction: Publish 1288 Request: PublishRequest 1290 Response:PublishResponse 1292 Publish a profile or key escrow entry to the mesh. 1294 7.9.1. Message: PublishRequest 1296 Requests publication of the specified Mesh entry. 1298 o 1300 * Inherits: MeshRequest 1302 [None] 1304 7.9.2. Message: PublishResponse 1306 Reports the success or failure of a Publish transaction. 1308 o 1309 * Inherits: MeshResponse 1311 [None] 1313 7.10. Transaction: Status 1315 Request: StatusRequest 1317 Response:StatusResponse 1319 Request the current status of the mesh as seen by the portal to which 1320 it is directed. 1322 The response to the status request contains the last signed 1323 checkpoint and proof chains for each of the peer portals that have 1324 been checkpointed. 1326 [Not currently implemented] 1328 7.10.1. Message: StatusRequest 1330 o 1332 * Inherits: MeshRequest 1334 Initiates a status transaction. 1336 [None] 1338 7.10.2. Message: StatusResponse 1340 Reports the success or failure of a Status transaction. 1342 o 1344 * Inherits: MeshResponse 1346 LastWriteTime: DateTime (Optional) 1348 Time that the last write update was made to the Mesh 1350 LastCheckpointTime: DateTime (Optional) 1352 Time that the last Mesh checkpoint was calculated. 1354 NextCheckpointTime: DateTime (Optional) 1356 Time at which the next Mesh checkpoint should be calculated. 1358 CheckpointValue: String (Optional) 1360 Last checkpoint value. 1362 7.11. Transaction: ConnectStart 1364 Request: ConnectStartRequest 1366 Response:ConnectStartResponse 1368 Request connection of a new device to a mesh profile 1370 7.11.1. Message: ConnectStartRequest 1372 o 1374 * Inherits: MeshRequest 1376 Initial device connection request. 1378 SignedRequest: SignedConnectionRequest (Optional) 1380 Device connection request signed by thesignature key of the 1381 device requesting connection. 1383 AccountID: String (Optional) 1385 Account identifier of account to which the device is requesting 1386 connection. 1388 7.11.2. Message: ConnectStartResponse 1390 Reports the success or failure of a ConnectStart transaction. 1392 o 1393 * Inherits: MeshRequest 1395 [None] 1397 7.12. Transaction: ConnectStatus 1399 Request: ConnectStatusRequest 1401 Response:ConnectStatusResponse 1403 Request status of pending connection request of a new device to a 1404 mesh profile 1406 7.12.1. Message: ConnectStatusRequest 1408 o 1410 * Inherits: MeshRequest 1412 Request status information for a pending request posted previously. 1414 AccountID: String (Optional) 1416 Account identifier for which pending connection information is 1417 requested. 1419 DeviceID: String (Optional) 1421 Device identifier of device requesting status information. 1423 7.12.2. Message: ConnectStatusResponse 1425 Reports the success or failure of a ConnectStatus transaction. 1427 o 1429 * Inherits: MeshRequest 1431 Result: SignedConnectionResult (Optional) 1433 The signed ConnectionResult object. 1435 7.13. Transaction: ConnectPending 1437 Request: ConnectPendingRequest 1439 Response:ConnectPendingResponse 1441 Request a list of pending requests for an administration profile. 1443 7.13.1. Message: ConnectPendingRequest 1445 o 1447 * Inherits: MeshRequest 1449 Specify the criteria for pending requests. 1451 AccountID: String (Optional) 1453 The account identifier of the account for which pending connection 1454 requests are requested. 1456 SearchConstraints: SearchConstraints (Optional) 1458 Constrain the search to a specific time interval and/or limit the 1459 number and/or total size of data records returned. 1461 7.13.2. Message: ConnectPendingResponse 1463 Reports the success or failure of a ConnectPending transaction. 1465 o 1467 * Inherits: MeshRequest 1469 Pending: SignedConnectionRequest [0..Many] 1471 A list of pending requests satisfying the criteria set out in the 1472 request. 1474 PageKey: String (Optional) 1475 If non-null, indicates that the number and/or size of the data 1476 records returned exceeds either the SearchConstraints specified in 1477 the request or internal server limits. 1479 7.14. Transaction: ConnectComplete 1481 Request: ConnectCompleteRequest 1483 Response:ConnectCompleteResponse 1485 Post response to a pending connection request. 1487 7.14.1. Message: ConnectCompleteRequest 1489 Reports the success or failure of a ConnectComplete transaction. 1491 o 1493 * Inherits: MeshRequest 1495 Result: SignedConnectionResult (Optional) 1497 The connection result to be posted to the portal. The result MUST 1498 be signed by a valid administration key for the Mesh profile. 1500 AccountID: String (Optional) 1502 The account identifier to which the connection result is posted. 1504 7.14.2. Message: ConnectCompleteResponse 1506 o 1508 * Inherits: MeshRequest 1510 Reports the success or failure of a ConnectComplete transaction. 1512 [None] 1514 7.15. Transaction: Transfer 1516 Request: TransferRequest 1518 Response:TransferResponse 1520 Request a bulk transfer of the log between the specified transaction 1521 identifiers. Requires appropriate authorization 1523 [Not currently implemented] 1525 7.15.1. Message: TransferRequest 1527 o 1529 * Inherits: MeshRequest 1531 SearchConstraints: SearchConstraints (Optional) 1533 Constrain the search to a specific time interval and/or limit the 1534 number and/or total size of data records returned. 1536 7.15.2. Message: TransferResponse 1538 o 1540 * Inherits: MeshResponse 1542 Reports the success or failure of a Transfer transaction. If 1543 successful, contains the list of Mesh records to be transferred. 1545 DataItems: DataItem [0..Many] 1547 List of mesh data records matching the request. 1549 PageKey: String (Optional) 1551 If non-null, indicates that the number and/or size of the data 1552 records returned exceeds either the SearchConstraints specified in 1553 the request or internal server limits. 1555 8. Mesh Portal Objects 1557 The precise implementation of the portal service and the data 1558 structures representing state at the portal service are outside the 1559 scope of this specification. 1561 The specification of the Mesh Portal objects given here is to enable 1562 future formal specification of the portal protocols by defining the 1563 state changes resulting from portal transactions. 1565 8.1. Mesh Portal Log Entries 1567 Like the Mesh itself, the state of the portal is tracked by an append 1568 only log. This log contains entries binding account identifiers to 1569 mesh profiles and lists of pending connections. 1571 8.1.1. Structure: PortalEntry 1573 Created: DateTime (Optional) 1575 Time the pending item was created. 1577 Modified: DateTime (Optional) 1579 Time the pending item was last modified. 1581 8.1.2. Structure: Account 1583 Entry containing the UniqueID is Account[Name]-[Portal] Indexed by 1584 [Name], [UserProfileUDF] [Most recent open] 1586 o 1588 * Inherits: PortalEntry 1590 AccountID: String (Optional) 1592 Assigned account identifier, e.g. 'alice@example.com'. Account 1593 names are not case sensitive. 1595 UserProfileUDF: String (Optional) 1596 Fingerprint of associated user profile 1598 Status: String (Optional) 1600 Status of the account, valid values are 'Open', 'Closed', 1601 'Suspended' 1603 8.1.3. Structure: AccountProfile 1605 o 1607 * Inherits: Account 1609 Profile: SignedPersonalProfile (Optional) 1611 The personal profile associated with the account. 1613 8.1.4. Structure: ConnectionsPending 1615 Object containing the list of currently pending device connection 1616 requests for the specified account. Unique-ID is 1617 ConnectionsPending-[UserProfileUDF] 1619 o 1621 * Inherits: Account 1623 Requests: SignedConnectionRequest [0..Many] 1625 List of pending requests 1627 9. Security Considerations 1629 TBS 1631 9.1. Confidentiality 1633 9.2. Integrity 1634 9.3. Service 1636 10. IANA Considerations 1638 All the IANA considerations for the Mesh documents are specified in 1639 this document 1641 11. Acknowledgements 1643 12. Normative References 1645 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1646 Requirement Levels", BCP 14, RFC 2119, 1647 DOI 10.17487/RFC2119, March 1997. 1649 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 1650 Cheshire, "Internet Assigned Numbers Authority (IANA) 1651 Procedures for the Management of the Service Name and 1652 Transport Protocol Port Number Registry", BCP 165, 1653 RFC 6335, DOI 10.17487/RFC6335, August 2011. 1655 Author's Address 1657 Phillip Hallam-Baker 1658 Comodo Group Inc. 1660 Email: philliph@comodo.com