idnits 2.17.1 draft-hallambaker-mesh-developer-02.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 Introduction section. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 19, 2016) is 2769 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 1 error (**), 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. Hallam-Baker 3 Internet-Draft Comodo Group Inc. 4 Intended status: Informational September 19, 2016 5 Expires: March 23, 2017 7 Mathematical Mesh: Developer's Guide 8 draft-hallambaker-mesh-developer-02 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. 16 This document describes how to install and run the Mesh reference 17 code and make use of the reference code in applications. It does not 18 form a part of the Mesh specifications and is not normative. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on March 23, 2017. 37 Copyright Notice 39 Copyright (c) 2016 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Getting the Reference Code and Build Tools . . . . . . . . . 3 55 1.1. Obtaining the Development Environment . . . . . . . . . . 3 56 1.2. Obtaining the Build Tools . . . . . . . . . . . . . . . . 3 57 1.3. Obtaining the Mesh Source Libraries . . . . . . . . . . . 4 58 2. Running the Reference Code Examples . . . . . . . . . . . . . 4 59 2.1. Starting the Server . . . . . . . . . . . . . . . . . . . 4 60 2.2. The Profile Manager Wizard . . . . . . . . . . . . . . . 4 61 2.3. The Profile Connection Wizard . . . . . . . . . . . . . . 5 62 3. Platform specific configuration data . . . . . . . . . . . . 5 63 3.1. Windows . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 3.1.1. Private Key Data . . . . . . . . . . . . . . . . . . 5 65 3.1.2. Registry settings . . . . . . . . . . . . . . . . . . 5 66 3.1.3. Profile data files . . . . . . . . . . . . . . . . . 6 67 3.2. OSX and Linux . . . . . . . . . . . . . . . . . . . . . . 6 68 4. Using the Mesh C#/.Net Libraries in an Application . . . . . 6 69 4.1. Creating a Portal Client Connection . . . . . . . . . . . 6 70 4.2. Checking that a Portal Account name is acceptable . . . . 7 71 4.3. Creating a Personal Profile . . . . . . . . . . . . . . . 7 72 4.4. Creating an Offline Escrow Entry . . . . . . . . . . . . 7 73 4.5. Publishing the Profile and Escrow Entries . . . . . . . . 7 74 4.6. Attaching a New Device . . . . . . . . . . . . . . . . . 7 75 4.7. Attaching a new Application . . . . . . . . . . . . . . . 7 76 4.8. Deleting Profile Data . . . . . . . . . . . . . . . . . . 7 77 4.9. Recovering Profile Data . . . . . . . . . . . . . . . . . 7 78 5. Using other languages . . . . . . . . . . . . . . . . . . . . 7 79 5.1. Using the C Binding . . . . . . . . . . . . . . . . . . . 7 80 6. Reference Code Architecture . . . . . . . . . . . . . . . . . 7 81 6.1. Protocol Definition . . . . . . . . . . . . . . . . . . . 8 82 6.1.1. Serialization . . . . . . . . . . . . . . . . . . . . 8 83 6.1.2. Deserialization . . . . . . . . . . . . . . . . . . . 8 84 6.1.3. Class library . . . . . . . . . . . . . . . . . . . . 8 85 6.2. Profile . . . . . . . . . . . . . . . . . . . . . . . . . 8 86 6.2.1. Generation . . . . . . . . . . . . . . . . . . . . . 8 87 6.2.2. Validation . . . . . . . . . . . . . . . . . . . . . 8 88 6.2.3. Operations . . . . . . . . . . . . . . . . . . . . . 8 89 6.3. Server . . . . . . . . . . . . . . . . . . . . . . . . . 8 90 6.3.1. Management Class . . . . . . . . . . . . . . . . . . 8 91 6.3.2. Dispatch Class . . . . . . . . . . . . . . . . . . . 8 92 6.3.3. Connection Modes . . . . . . . . . . . . . . . . . . 8 93 6.4. Client . . . . . . . . . . . . . . . . . . . . . . . . . 8 94 6.4.1. Stub Library . . . . . . . . . . . . . . . . . . . . 8 95 6.4.2. Convenience API . . . . . . . . . . . . . . . . . . . 8 96 7. Security Considerations . . . . . . . . . . . . . . . . . . . 8 97 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 98 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 99 10. Normative References . . . . . . . . . . . . . . . . . . . . 9 100 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 102 1. Getting the Reference Code and Build Tools 104 The Mesh Reference library was developed using Visual Studio 2015 105 Community Edition using PHB's Build Tools extensions. The reference 106 code itself is currently limited to C# libraries. 108 The code should in theory run under other operating systems but this 109 is not currently tested. 111 Development under different development environments is also possible 112 but would require re-engineering to make use of the line mode 113 versions of the build tools. 115 1.1. Obtaining the Development Environment 117 Visual Studio 2015 Community Edition is currently available at no 118 cost for a wide range of non-commercial development including 119 personal use and development of Open Source software. For full 120 details, please consult the license published by Microsoft. 122 https://www.visualstudio.com/ 124 1.2. Obtaining the Build Tools 126 Over half the code in the reference code library is generated using 127 code generators. These are used to ensure that the specification, 128 examples and reference code are always kept in synchronization. 130 The build tools are published under an MIT License and are available 131 in two forms: 133 As stand-alone tools to be run from the command line. 135 As a VSIX package that integrates into the Visual Studio environment. 137 The source distribution is configured to use the tools integrated 138 into the Visual Studio environment. If development on other 139 platforms is desired, the simplest approach is likely to be to write 140 a tool that reads the Visual Studio configuration files and generates 141 the corresponding files for use with make. 143 The VSIX package is available from the Visual Studio extensions 144 gallery: 146 PHB Code Generation Tools 148 The source code for the build tools is available from: 150 https://sourceforge.net/projects/phb-build-tools/ 152 1.3. Obtaining the Mesh Source Libraries 154 The Mesh reference library source code is published under an MIT 155 license and is available from: 157 https://sourceforge.net/projects/mathematicalmesh/ 159 2. Running the Reference Code Examples 161 The reference code examples are designed to illustrate how the Mesh 162 might be used in an application rather than be standalone tools in 163 their own right. The Mesh is designed to make it each for developers 164 to add security to their own applications rather than providing the 165 applications themselves. 167 2.1. Starting the Server 169 On the Windows platform, the server runs in the context of the 170 platform Web server and must be granted permission to bind to the 171 range of server addresses used using the netsh command. 173 From a command prompt with administrator privileges, run the 174 following command: 176 netsh http add urlacl http:///.well-known/mmm/ 177 \user=\ 179 Where is the DNS domain name under which the service is run, is the 180 Windows domain name of the machine and the account name. 182 To start the service from the command line type: 184 servermesh 186 The server does not require administration privileges. 188 2.2. The Profile Manager Wizard 190 The profile manager wizard demonstrates functions that are performed 191 on an administration device. These include creating a completely new 192 profile and initial configuration of applications, connecting a 193 device to the profile and recovery of the profile from escrow data. 195 To run the client from the command line, place the executable image 196 in a location that it will be found in the PATH variable and type: 198 meshclient 200 2.3. The Profile Connection Wizard 202 The Profile connection wizard demonstrates the much more restricted 203 functionality that would be required in a Mesh connected application 204 and/or a profile manager for a non-administration device. 206 To run the client from the command line, place the executable image 207 in a location that it will be found in the PATH variable and type: 209 meshconnect 211 3. Platform specific configuration data 213 3.1. Windows 215 3.1.1. Private Key Data 217 All private key data is stored using the Windows public key store. 218 At minimum, this ensures that private keys are obfuscated and 219 encrypted under the account password to protect the data against 220 casual extraction attacks. On a machine with cryptographic hardware 221 support such as a TPM or HSM, extraction of the private key may be 222 infeasible without physical access to the machine and possibly 223 require sophisticated diagnostic equipment. 225 3.1.2. Registry settings 227 Separate settings are used for production and test code. Test Code 228 should use the Registry Hive: 230 HKEY_CURRENT_USER\SOFTWARE\CryptoMesh 232 Production code should use the hive 234 HKEY_CURRENT_USER\SOFTWARE\MathematicalMesh 236 In either case the sub structure is: 238 Accounts Contains the set of Mesh Portal Accounts for the user. 239 The default value is the account name of the default account. 241 The Name of the each key is a portal account name and the value 242 a REG_SZ entry containing the UDF of the profile master key. 244 PersonalProfiles Contains the set of Mesh Profiles for the user. 245 The default value is the UDF of the default profile master key. 246 The Name of each key is the UDF of the master key and the value 247 a REG_SZ entry containing the file location of the cached copy 248 of the personal profile. 250 ThisDevice Contains the set of Device profiles in the same format 251 as the PersonalProfiles. 253 3.1.3. Profile data files 255 The profile data itself is stored in data files at the location 256 specified in the registry. The files are standard XML files in UTF8 257 encoding. 259 3.2. OSX and Linux 261 [[Not yet implemented, subject to change.] 263 All configuration information is stored in the user directory ~/.mmm 265 Keys are stored in SSH key file format [RFC4716] using the customary 266 name and extension conventions for that application. 268 4. Using the Mesh C#/.Net Libraries in an Application 270 The application ExampleGenerator shows the use of the Mesh in an 271 application using the convenience API. It is the application program 272 used to generate the examples in the reference document. 274 ExampleGenerator implements a client that connects to a remote 275 WebService, creates new personal profile with an escrow entry with 276 offline recovery codes, attaches applications and other devices, 277 updates an application profile, deletes all the profile data from the 278 local machine and then restores them using the recovery codes and 279 escrow entry. 281 4.1. Creating a Portal Client Connection 283 The normal method of creating a Portal Client connection is? 285 Since the purpose of the ExampleGenerator is to create examples for 286 the documentation, it is not necessary for the JSON Remote Procedure 287 Calls to actually be 'Remote'. Instead the 'Local' Procedure Call 288 mode is used in which the client and server both run in the same 289 process with the client API invoking the server dispatch methods 290 through an interface that performs JSON serialization and 291 deserialization but does not invoke the network transport. 293 ?. 295 For purposes of testing and initial development of a Web Service it 296 is frequently desirable to further simplify the implementation by 297 dispensing with the serialization layer and the client calling the 298 server dispatch methods directly. 300 ?. 302 4.2. Checking that a Portal Account name is acceptable 304 4.3. Creating a Personal Profile 306 4.4. Creating an Offline Escrow Entry 308 4.5. Publishing the Profile and Escrow Entries 310 4.6. Attaching a New Device 312 4.7. Attaching a new Application 314 4.8. Deleting Profile Data 316 4.9. Recovering Profile Data 318 5. Using other languages 320 If you are building Mesh applications in another language, the least 321 effort approach may be to rewrite the PROTOGEN build tool to target 322 your language. 324 Protogen does support generation of C header files that may be used 325 to drive a parser. If however you are adding Mesh support for an 326 application that already uses JSON based protocols, you might want to 327 edit the generator scripting files to generate code for your existing 328 libraries. 330 5.1. Using the C Binding 332 6. Reference Code Architecture 333 6.1. Protocol Definition 335 6.1.1. Serialization 337 6.1.2. Deserialization 339 6.1.3. Class library 341 6.2. Profile 343 6.2.1. Generation 345 6.2.2. Validation 347 6.2.3. Operations 349 6.3. Server 351 6.3.1. Management Class 353 6.3.2. Dispatch Class 355 6.3.3. Connection Modes 357 6.3.3.1. Direct 359 6.3.3.2. Local 361 6.3.3.3. Remote 363 6.4. Client 365 6.4.1. Stub Library 367 6.4.2. Convenience API 369 7. Security Considerations 371 Security Considerations are addressed in the companion document 372 [draft-hallambaker-mesh-architecture-01] 374 8. IANA Considerations 376 IANA Considerations are addressed in the companion document [draft- 377 hallambaker-mesh-architecture-01] 379 9. Acknowledgements 381 Comodo Group: Egemen Tas, Melhi Abdulhayo?lu, Rob Stradling, Robin 382 Alden. 384 10. Normative References 386 [draft-hallambaker-mesh-architecture-01] 387 "[Reference Not Found!]". 389 [RFC4716] Galbraith, J. and R. Thayer, "The Secure Shell (SSH) 390 Public Key File Format", RFC 4716, DOI 10.17487/RFC4716, 391 November 2006. 393 Author's Address 395 Phillip Hallam-Baker 396 Comodo Group Inc. 398 Email: philliph@comodo.com