Mathematical Mesh: Reference Implementation

1.1. Requirements Language

This document is not normative and does not contain requirements language¶

1.2. Defined Terms

The terms of art used in this document are described in the Mesh Architecture Guide [draft-hallambaker-mesh-architecture].¶

1.3. Related Specifications

The architecture of the Mathematical Mesh is described in the Mesh Architecture Guide [draft-hallambaker-mesh-architecture]. The Mesh documentation set and related specifications are described in this document.¶

1.4. Implementation Status

The implementation status of the reference code base is described in the companion document [draft-hallambaker-mesh-developer].¶

2.1. Obtaining the Development Environment

Visual Studio 2017 Community Edition is currently available at no cost for a wide range of non-commercial development including personal use and development of Open Source software. For full details, please consult the license published by Microsoft.¶

https://www.visualstudio.com/

2.2. Obtaining the Build Tools

Over half the code in the reference code library is generated using code generators. These are used to ensure that the specification, examples and reference code are always kept in synchronization.¶

The build tools are published under an MIT License and are available in two forms:¶

As stand-alone tools to be run from the command line.¶

As a VSIX package that integrates into the Visual Studio environment.¶

The source distribution is configured to use the tools integrated into the Visual Studio environment. If development on other platforms is desired, the simplest approach is likely to be to write a tool that reads the Visual Studio configuration files and generates the corresponding files for use with make.¶

The VSIX package is available from the Visual Studio extensions gallery:¶

PHB Code Generation Tools

The source code for the build tools is available from:¶

https://sourceforge.net/projects/phb-build-tools/

2.3. Obtaining the Mesh Source Libraries

The Mesh reference library source code is published under an MIT license and is available from:¶

https://sourceforge.net/projects/mathematicalmesh/

3.1. Creating a software signing key

The purpose of signing assemblies is so that they can be authenticated during the load process. For this to be secure, it is of course essential that each developer has their own key.¶

To create a software developer signing key, the Visual Studio 'sn' tool is used. To run the tool, start the Visual Studio Developer Console in administrator mode. This requires the following steps:¶

Move to a directory you want to write to.¶

Set the machine to create user based keys¶

Create a new key and write it to a file.¶

Copy the file from the key to a container.¶

Delete the container.¶

Locate the private key file¶

Give permission to use the key.¶

This is of course one of the tasks we would like to automate with the Mesh tools in due course but that presents a bootstrap problem.¶

C:\Windows\System32>cd hallam

c:\Users\hallam>sn -m N

Microsoft (R) .NET Framework Strong Name Utility  Version 4.0.30319.0
Copyright (c) Microsoft Corporation.  All rights reserved.

Key containers are user based

c:\Users\hallam>sn -k fred.snk

Microsoft (R) .NET Framework Strong Name Utility  Version 4.0.30319.0
Copyright (c) Microsoft Corporation.  All rights reserved.

Key pair written to fred.snk

c:\Users\hallam>sn -i fred.snk SigningKeyDeveloper

Microsoft (R) .NET Framework Strong Name Utility  Version 4.0.30319.0
Copyright (c) Microsoft Corporation.  All rights reserved.

Key pair installed into 'SigningKeyDeveloper'

c:\Users\hallam>del fred.snk

c:\Users\hallam>

3.2. Create (dummy) build action files

Visual Studio allows projects to specify batch files to be run before and after a project build. Since the actions to be taken are likely to change from developer to developer, these are specified in separate batch files. All that is necessary to build the code without warnings is to specify a set of dummy batch files with the following names and place them somewhere in the command line $PATH environment variable.¶

The files required are:¶

VSPreBuild.bat¶

VSPostBuild.bat¶

VSPostBuildWindows.bat¶

VSPostBuildOSX.bat¶

VSPostBuildLinux.bat¶

The following code will prevent error messages being thrown:¶

@echo off
SETLOCAL
exit /b 0

4.1. Starting the Server

On the Windows platform, the server runs in the context of the platform Web server and must be granted permission to bind to the range of server addresses used using the netsh command.¶

From a command prompt with administrator privileges, run the following command:¶

netsh http add urlacl http://<domain>/.well-known/mmm/
    \user=<machine>\<user>

Where <domain> is the DNS domain name under which the service is run, <machine> is the Windows domain name of the machine and <user> the account name.¶

To start the service from the command line type:¶

servermesh <domain>

The server does not require administration privileges.¶

4.2. The Profile Manager Wizard

The profile manager wizard demonstrates functions that are performed on an administration device. These include creating a completely new profile and initial configuration of applications, connecting a device to the profile and recovery of the profile from escrow data.¶

To run the client from the command line, place the executable image in a location that it will be found in the PATH variable and type:¶

meshclient

4.3. The Profile Connection Wizard

The Profile connection wizard demonstrates the much more restricted functionality that would be required in a Mesh connected application and/or a profile manager for a non-administration device.¶

To run the client from the command line, place the executable image in a location that it will be found in the PATH variable and type:¶

meshconnect

5.1. Windows

5.2. OSX and Linux

[[Not yet implemented, subject to change.]¶

All configuration information is stored in the user directory ~/.mmm¶

Keys are stored in SSH key file format [RFC4716] using the customary name and extension conventions for that application.¶

6.1. Portals, Sessions and Clients

The libraries are designed to support testing and development use. For this reason, the client side of the libraries is divided into the following main classes:¶

MeshClient

Provides a logical connection to a remote or simulated Mesh service.¶

MeshPortal

Provides the interface to a Mesh service which may be an actual remote service accessed via a network connection, or local code running in the same process as the client to simulate a Mesh service for testing purposes.¶

MeshMachine

Provides an interface to Mesh data stored on the local machine.¶

MeshSession / PersonalSession

Provide the high-level application interface to the Mesh combining access through the MeshClient and MeshMachine.¶

The relationship between these parts is shown below. The application programmer will typically need only the MeshSession class.¶

This division makes it possible to test Mesh clients and server implementations in a single process with a single debugger which is usually more convenient than spinning up a separate development session for the client and service.¶

6.2. Creating a Mesh Session

The primary interface for the application programmer is the MeshSession class. To create a mesh session class, the following steps are required:¶

0. Initialize the Mesh code for the intended platform¶
1. Request a new MeshSession instance.¶

Although C# code is nominally 'write once, run anywhere', this approach does not ensure use of platform specific features such as the Windows registry or protected storage for cryptographic keys. Calling MeshWindows.Initialize() causes the platform specific code for the Windows to be initialized in production mode. Alternatively, calls to MeshLinux.Initialize() or MeshOSX.Initialize() causes the platform specific code for those platforms to be initialized.¶

The code to initialize a production instance of the code is:¶

        static MeshSession MeshSession = null;

        static void ApplicationInit () {
            MeshWindows.Initialize();
            MeshSession = new MeshSession();
            }

If the user has already created a PersonalProfile and connected it to the machine, it will automatically be read from local storage. The instance will automatically create MeshClient instances as required to establish a web service using the default transport (HTTP) to the service as necessary.¶

The server implementation is managed in the same fashion. Internally, the MeshService and MeshClient classes are both descended from the same parent.¶

6.3. Creating a Mesh Session for Testing

Since the purpose of the ExampleGenerator is to create examples for the documentation, it is not necessary for the JSON Remote Procedure Calls to actually be 'Remote'. Instead the 'Local' Procedure Call mode is used in which the client and server both run in the same process with the client API invoking the server dispatch methods through an interface that performs JSON serialization and deserialization but does not invoke the network transport.¶

A direct connection to the service provider may be established by either specifying the portal to use in the initialization of MeshSession or by setting the default portal property of the MeshPortal class as is done here.¶

        static void DebugApplicationInit () {

            MeshPortal.Default = new MeshPortalDirect("example.com",
                "MeshLog.jlog", "PortalLog.jlog");

            MeshWindows.Initialize(true);
            MeshSession = new MeshSession();
            MeshSession.EraseTest();
            }

This time, we initialize a specific version of the platform dependent code and specify that it is to be initialized as test code rather than production. This will cause all persistent data stored on the machine (keys, profiles) to be stored in locations marked as test locations. The EraseTest() method causes all data stored in test locations to be erased from the machine, thus ensuring that the test begins from a known state with no results from previous runs.¶

When writing test code, it is frequently useful to create multiple independent MeshSessions to simulate multiple machines. To prevent data written to one machine interfering with another, a new simulated machine is created for each session using the MeshMachineCached class.¶

            MeshSession = new MeshSession(new MeshMachineCached());

6.4. Checking that a Portal Account name is acceptable

The user experience is improved if the application indicates whether their choice of portal account name is acceptable or not while they are entering it. The Validate method allows the user's choice of account name to be validated.¶

        PersonalProfile PersonalProfile;
        PersonalSession PersonalSession;
        OfflineEscrowEntry OfflineEscrowEntry;

        void DebugCreateProfile () {
            var Response = MeshSession.Validate("alice@example.com");
            if (!Response.Valid) {
                throw new Exception();
                }
            ...

The portal address is given in the usual username@domain format, for example alice@example.com.¶

6.5. Creating a Personal Profile

Creating a PersonalProfile has two steps:¶

0. Create a DeviceProfile (if necessary)¶
1. Create the PersonalProfile¶
2. Create an account bound to the profile at the portal.¶

These steps are shown in.¶

            var Device = MeshSession.CreateDevice();
            PersonalProfile = new PersonalProfile(
                Device.DeviceProfile);
            PersonalSession = MeshSession.CreateAccount(
                "alice@example.com", PersonalProfile);

The application could have overridden the default values of DeviceID and DeviceDescription when creating the device.¶

6.6. Creating an Offline Escrow Entry

Having created a potentially valuable profile, we probably want to back it up. To do this, we create an instance of the OfflineEscrowEntry class with the desired quorum and number of shares (2 out of 4).¶

            OfflineEscrowEntry = new OfflineEscrowEntry(
                PersonalProfile, 2, 4);
            PersonalSession.Escrow(OfflineEscrowEntry);

6.7. Deleting Profile Data

We can test our escrow parameters by deleting the profile from the current machine using the Delete method.¶

            PersonalSession.Delete();

6.8. Recovering Profile Data

Profile recovery has two steps:¶

0. Reconstruct the shared secret from the recovery shares.¶
1. Recover the profile.¶

In this case our recovery shares are the first and the third key shares we just generated. The Recover method recovers the profile and rebinds it to the existing portal.¶

            var RecoveryShares = new KeyShare[] {
                OfflineEscrowEntry.KeyShares[0],
                OfflineEscrowEntry.KeyShares[2] };

            var Secret = new Secret(RecoveryShares);
            PersonalSession = MeshSession.Recover(
                Secret, "alice@example.com");
            }

6.9. Connecting a New Device

Device connection involves two devices, the device to be connected and the device used to approve the request.¶

The new device:¶

0. Create a device profile for the new device.¶
1. Request connection to the new device¶
2. Wait for the result.¶

These calls are shown.¶

        void RequestConnect (string Address) {
            var DeviceRegistration = MeshSession.CreateDevice();
            var Connect = MeshSession.Connect(DeviceRegistration,
                    Address, out var Authenticator);
            PersonalSession = Connect.Await();
            }

In a real example, we would want to show the connection authentication code to the user so that they can verify that they are responding to the right request on the approval device.¶

On the approval device, the application¶

0. Requests a list of pending requests using ConnectPending.¶
1. Accepts or Rejects devices using ConnectClose.¶

        void AcceptPending () {

            var Pending = PersonalSession.ConnectPending();
            foreach (var Request in Pending.Pending) {
                var Result = PersonalSession.ConnectClose(Request,
                    ConnectionStatus.Accepted);
                }
            }

6.10. Managing Applications

Application profiles are created in the same manner as personal profiles.¶

            var PasswordProfile = new PasswordProfile(true);
            var RegistrationApplication =
                    RegistrationPersonal.Add(PasswordProfile, false);

Changes to the Application Profile are written to the RegistrationApplication instance and then committed using the Update() method.¶

7.1. Lightweight API

A lightweight API providing the minimal features required to Mesh enable an application is required. Such an API should exclude most account management features:¶

• Creating new Personal Profiles and portal accounts.¶
• Key escrow, recovery¶
• List, accept pending device connection requests¶

This leaves the following features:¶

• Create Device Profile¶
• Request device connection¶
• Get Personal Profile¶
• Get, Update, Application Profile¶

In addition to providing less functionality, an implementation of the lightweight binding is likely to be written in a 'flattened' style rather than the abstracted, object oriented approach of the reference code.¶

8.1. Reference Implementation

Organization: Threshold Secrets LLC.¶

Implementer: Phillip Hallam-Baker¶

Maturity: Experimental Prototype¶

This implementation was used to produce the reference section and all the examples in this document. Since the conversion of specification to code is automatic, there is a high degree of assurance that the reference implementation is consistent with this document.¶