idnits 2.17.1 draft-hallambaker-mesh-developer-01.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. ** There is 1 instance of too long lines in the document, the longest one being 5 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 7, 2016) is 2943 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. 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. Hallam-Baker 3 Internet-Draft Comodo Group Inc. 4 Intended status: Informational March 7, 2016 5 Expires: September 8, 2016 7 Mathematical Mesh: Developer's Guide 8 draft-hallambaker-mesh-developer-01 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 September 8, 2016. 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 1. Getting the Reference Code and Build Tools 54 The Mesh Reference library was developed using Visual Studio 2015 55 Community Edition using PHB's Build Tools extensions. The reference 56 code itself is currently limited to C# libraries. 58 The code should in theory run under other operating systems but this 59 is not currently tested. 61 Development under different development environments is also possible 62 but would require re-engineering to make use of the line mode 63 versions of the build tools. 65 1.1. Obtaining the Development Environment 67 Visual Studio 2015 Community Edition is currently available at no 68 cost for a wide range of non-commercial development including 69 personal use and development of Open Source software. For full 70 details, please consult the license published by Microsoft. 72 https://www.visualstudio.com/ 74 1.2. Obtaining the Build Tools 76 Over half the code in the reference code library is generated using 77 code generators. These are used to ensure that the specification, 78 examples and reference code are always kept in synchronization. 80 The build tools are published under an MIT License and are available 81 in two forms: 83 As stand-alone tools to be run from the command line. 85 As a VSIX package that integrates into the Visual Studio environment. 87 The source distribution is configured to use the tools integrated 88 into the Visual Studio environment. If development on other 89 platforms is desired, the simplest approach is likely to be to write 90 a tool that reads the Visual Studio configuration files and generates 91 the corresponding files for use with make. 93 The VSIX package is available from the Visual Studio extensions 94 gallery: 96 PHB Code Generation Tools 97 The source code for the build tools is available from: 99 https://sourceforge.net/projects/phb-build-tools/ 101 1.3. Obtaining the Mesh Source Libraries 103 The Mesh reference library source code is published under an MIT 104 license and is available from: 106 https://sourceforge.net/projects/mathematicalmesh/ 108 2. Running the Reference Code Examples 110 The reference code examples are designed to illustrate how the Mesh 111 might be used in an application rather than be standalone tools in 112 their own right. The Mesh is designed to make it each for developers 113 to add security to their own applications rather than providing the 114 applications themselves. 116 2.1. Starting the Server 118 On the Windows platform, the server runs in the context of the 119 platform Web server and must be granted permission to bind to the 120 range of server addresses used using the netsh command. 122 From a command prompt with administrator privileges, run the 123 following command: 125 netsh http add urlacl http:///.well-known/mmm/ \user=\ 127 Where is the DNS domain name under which the service is run, is the 128 Windows domain name of the machine and the account name. 130 To start the service from the command line type: 132 servermesh 134 The server does not require administration privileges. 136 2.2. The Profile Manager Wizard 138 The profile manager wizard demonstrates functions that are performed 139 on an administration device. These include creating a completely new 140 profile and initial configuration of applications, connecting a 141 device to the profile and recovery of the profile from escrow data. 143 To run the client from the command line, place the executable image 144 in a location that it will be found in the PATH variable and type: 146 meshclient 148 2.3. The Profile Connection Wizard 150 The Profile connection wizard demonstrates the much more restricted 151 functionality that would be required in a Mesh connected application 152 and/or a profile manager for a non-administration device. 154 To run the client from the command line, place the executable image 155 in a location that it will be found in the PATH variable and type: 157 meshconnect 159 3. Platform specific configuration data 161 3.1. Windows 163 3.1.1. Private Key Data 165 All private key data is stored using the Windows public key store. 166 At minimum, this ensures that private keys are obfuscated and 167 encrypted under the account password to protect the data against 168 casual extraction attacks. On a machine with cryptographic hardware 169 support such as a TPM or HSM, extraction of the private key may be 170 infeasible without physical access to the machine and possibly 171 require sophisticated diagnostic equipment. 173 3.1.2. Registry settings 175 Separate settings are used for production and test code. Test Code 176 should use the Registry Hive: 178 HKEY_CURRENT_USER\SOFTWARE\CryptoMesh 180 Production code should use the hive 182 HKEY_CURRENT_USER\SOFTWARE\MathematicalMesh 184 In either case the sub structure is: 186 Accounts Contains the set of Mesh Portal Accounts for the user. 187 The default value is the account name of the default account. 188 The Name of the each key is a portal account name and the value 189 a REG_SZ entry containing the UDF of the profile master key. 191 PersonalProfiles Contains the set of Mesh Profiles for the user. 192 The default value is the UDF of the default profile master key. 193 The Name of each key is the UDF of the master key and the value 194 a REG_SZ entry containing the file location of the cached copy 195 of the personal profile. 197 ThisDevice Contains the set of Device profiles in the same format 198 as the PersonalProfiles. 200 3.1.3. Profile data files 202 The profile data itself is stored in data files at the location 203 specified in the registry. The files are standard XML files in UTF8 204 encoding. 206 3.2. OSX and Linux 208 [[Not yet implemented, subject to change.] 210 All configuration information is stored in the user directory ~/.mmm 212 Keys are stored in SSH key file format [RFC4716] using the customary 213 name and extension conventions for that application. 215 4. Using the Mesh C#/.Net Libraries in an Application 217 The application ExampleGenerator shows the use of the Mesh in an 218 application using the convenience API. It is the application program 219 used to generate the examples in the reference document. 221 ExampleGenerator implements a client that connects to a remote 222 WebService, creates new personal profile with an escrow entry with 223 offline recovery codes, attaches applications and other devices, 224 updates an application profile, deletes all the profile data from the 225 local machine and then restores them using the recovery codes and 226 escrow entry. 228 4.1. Creating a Portal Client Connection 230 The normal method of creating a Portal Client connection is? 232 Since the purpose of the ExampleGenerator is to create examples for 233 the documentation, it is not necessary for the JSON Remote Procedure 234 Calls to actually be 'Remote'. Instead the 'Local' Procedure Call 235 mode is used in which the client and server both run in the same 236 process with the client API invoking the server dispatch methods 237 through an interface that performs JSON serialization and 238 deserialization but does not invoke the network transport. 240 ?. 242 For purposes of testing and initial development of a Web Service it 243 is frequently desirable to further simplify the implementation by 244 dispensing with the serialization layer and the client calling the 245 server dispatch methods directly. 247 ?. 249 4.2. Checking that a Portal Account name is acceptable 251 4.3. Creating a Personal Profile 253 4.4. Creating an Offline Escrow Entry 255 4.5. Publishing the Profile and Escrow Entries 257 4.6. Attaching a New Device 259 4.7. Attaching a new Application 261 4.8. Deleting Profile Data 263 4.9. Recovering Profile Data 265 5. Using other languages 267 If you are building Mesh applications in another language, the least 268 effort approach may be to rewrite the PROTOGEN build tool to target 269 your language. 271 Protogen does support generation of C header files that may be used 272 to drive a parser. If however you are adding Mesh support for an 273 application that already uses JSON based protocols, you might want to 274 edit the generator scripting files to generate code for your existing 275 libraries. 277 5.1. Using the C Binding 279 6. Reference Code Architecture 281 6.1. Protocol Definition 283 6.1.1. Serialization 284 6.1.2. Deserialization 286 6.1.3. Class library 288 6.2. Profile 290 6.2.1. Generation 292 6.2.2. Validation 294 6.2.3. Operations 296 6.3. Server 298 6.3.1. Management Class 300 6.3.2. Dispatch Class 302 6.3.3. Connection Modes 304 6.3.3.1. Direct 306 6.3.3.2. Local 308 6.3.3.3. Remote 310 6.4. Client 312 6.4.1. Stub Library 314 6.4.2. Convenience API 316 7. Security Considerations 318 Security Considerations are addressed in the companion document 319 [draft-hallambaker-mesh-architecture] 321 8. IANA Considerations 323 IANA Considerations are addressed in the companion document [draft- 324 hallambaker-mesh-architecture] 326 9. Acknowledgements 328 Comodo Group: Egemen Tas, Melhi Abdulhayo?lu, Rob Stradling, Robin 329 Alden. 331 10. Normative References 333 [RFC4716] Galbraith, J. and R. Thayer, "The Secure Shell (SSH) 334 Public Key File Format", RFC 4716, DOI 10.17487/RFC4716, 335 November 2006. 337 [draft-hallambaker-mesh-architecture] 338 "[Reference Not Found!]". 340 Author's Address 342 Phillip Hallam-Baker 343 Comodo Group Inc. 345 Email: philliph@comodo.com