Security is of paramount importance for the AEC Deltas project, since the kind of information being exchanged between architects, designers, engineers and contractors is often sensitive in nature. Additionally, there are instances where access to certain types of data might be restricted only to a few select companies/individuals, such as the CCTV cameras package, security doors, etc.

This page describes the AECDeltas approach to security, its requirements and strategies.

Summary

• Summary
• Introduction
• Encryption
  • Required Components
• User Authentication
  • 3D Repo
  • Speckle Works
  • BHoM
  • PassportJS
• Authorship Verification

Introduction

From a security standpoint, we need to consider three main requirements of the delta collaboration:

• Authentication - The ability to verify the source of the delta;
• Integrity - The ability to verify that the delta has not been altered during transmission;
• Non-repudiation - The ability to prevent the author from ever denying that they originated the delta.

Meeting these base requirements will ensure that each delta can be safely processed, it can be attributed to its respective author and the users of the system can be sure it has not been tampered with.

Encryption

A lot of inspiration has been taken from existing messaging and e-mail protocols. For our purposes, we propose the use of the RSA hashing via OpenSSL. MongoDB provides crypto utilities natively, however, those rely on symmetric encryption with a single key which would not be suitable for our use case, see https://docs.mongodb.com/stitch/functions/utilities/#utils-crypto for details. Each system user, also known as an actor, will establish a secure TLS connection with the HTTPS protocol and the centralised server in order to exchange individual deltas but also communicate via the REST API end-points.

Required Components

The main components of the security layer of the system are as follows:

• Digital signature. Each delta will be digitally signed in order to validate its authenticity and integrity.
• Public-private key pairs. Each actor within the system will distribute their public key in order for the other actors to validate the digital signatures of the deltas.
• Transport Security Layer (TLS) connection. Secure network connection for delta exchange between the actors.

Each delta will be accompanied by a digital signature which hashes the contents of the payload using an asymmetric private-key in order to validate the author of the delta and the integrity of the message. A central server will then store the respective deltas in order of receiving them so as to provide an independent audit trail of changes over time. Pushing a new delta will automatically trigger the creation of a new incremental revision within the system.

In order to obtain a public-private key certificate, there are readily-available and free to use certificate authorities such as https://letsencrypt.org Another solution to consider is a distributed cloud storage system EdgeFS which provides high throughout with on-write automatic synchronisation across geographically distributed locations.

User Authentication

User authentication is one of the main components of the AEC Deltas framework as it enables secure access to the system and at the same time prevents unauthorised users from accessing potentially sensitive data. In this context, an email address is considered a unique identifier while the Microsoft Active Directory (AD) is to eventually become the base system for authentication across the network. The ultimate goal is to enable remote access to client/server infrastructure of various interconnected systems within the network. The base case is being provided by 3D Repo, Speckle and BHoM library. Even though BHoM supports custom workflows and data transfers in a peer-to-peer fashion, it currently does not support user authentication. Instead, the respective connectivity toolkits have to either request user's credential on login or rely on user-supplied API keys.

• 3D Repo - Cookie-based authentication (username/password) + API keys
• Speckle - OCID openconnect
• BHoM - LDAP Toolkit (not yet implemented)

3D Repo

3D Repo supports a cookie-based authentication given a username/email and a password combination. To authentication subsequent API calls using the cookie-based authentication, each HTTP header needs to carry the following: Cookie: connect.sid=:sessionId as further explained in the API docs: https://3drepo.github.io/3drepo.io/#api-Authentication

Alternatively, it is possible to generate API keys for individual users which then need to be appended to the requests between the client and the server. This is a high-entropy automatically generated token which, however, increases the security risks since the same key is used for multiple sessions. See details here: https://3drepo.github.io/3drepo.io/#api-User-generateApiKey

For convenience and ease of access the use of API keys for authentication is currently the preferred way of integrating 3D Repo with other systems such as BHoM via the 3D Repo toolkit: https://github.com/BHoM/3DRepo_Toolkit

Speckle Works

Speckle implements several authentication strategies for end-user identity verification. Specifically, these are:

• Default (email + password)
• Active Directory
• Github
• Twitter
• Auth0 (integration gateway with others, such as Google Accounts).

All API requests are authenticated via a JWT token. A JWT token is obtained by a user upon successfully logging in/registering via the methods described above. They have a defined expiration date, after which a renewal is needed. For certain API endpoints, such as resource retrieval, authentication is optional. Nevertheless, access is refused if the resource is marked as private.

Permissions wise, Speckle implements a Discretionary Access Control protocol: each end-user is the owner of any data she or he creates, and can grant read or write permissions to whoever she or he needs to, based on the collaborative needs of the task at hand.

At a server deployment level, the recommended approach is to have a proxy server (e.g., nginx) in front of the server application. At this infrastructural level, server maintainers need to enable traffic encryption via standard protocols (SSL/TLS).

BHoM

Encryption is possible, however, user authentication is not implemented yet. One approach is to implement Speckle Works user authentication system for temporary verification of users using cookie based authentication: https://speckleworks.github.io/SpeckleSpecs/#userlogin

The problem spans from the fact that BHoM is currently used only as a local application. The long-term aim is to use BHoM via socket toolkit between two or more different machines across a network connection.

PassportJS

In order to bridge the various authentication methods currently employed by the respective project partners, we propose to utilise the PassportJS library: http://www.passportjs.org/ This library provides NojeJS authentication middleware which can easily be integrated with any Express-enabled web application to support over 500 different existing authentication strategies from GitHub, Google, Twitter, etc.

Figure 1.: Authentication and data flow example between different desktop and cloud applications driven by BHoM with PassportJS authentication.

An example of data flow with authentication provided by PassportJS could is shown in Figure 1.:

1. User relies on Grasshopper to set up the data and authentication flow via custom visual programming script that utilises the BHoM library underneath;
2. BHoM retrieves data from Revit into a unified in-memory representation. Those data fields that currently do not have a native BHoM representation are converted using reflection en masse;
3. BHoM then passes data into Tekla which generates its own native representation of structural elements originating from Revit;
4. Next, BHoM performs specific calculation and transformation within Tekla which is then retrieved back into a BHoM-specific unified in-memory representation;
5. This is then passed onto Robot for additional processing. Same as with Tekla, Robot generates its own native representation internally;
6. Structural analysis is performed in Robot whcih is then retrieved back into a BHoM-specific unified in-memory representation;
7. In order to pass the information from a local computer into a cloud-based environment, the BHoM library performs authentication against the PassportJS library;
8. This library authenticates against a number of pre-defined external authentication services, in this case GitHub;
9. Once authenticated, the BHoM library can pass data to Speckle Works;
10. The same authentication can also be used to send data to additional services such as 3D Repo.

The above is one such example of data flow and the necessary authentication within the AEC Deltas ecosystem even though many such combinations are possible. Ultimately, it is important to differentiate the localhost in-memory peer-to-peer data communication of the BHoM library which does not necessarily require any authentication, with the cloud-based services of Speckle Works and 3D Repo. There, it is important to uniquely identify and authenticate each user so that malicious activity can be prevented and history of actions stored. As designated in Figure 1., additional authentication and/or data processing services can be appended into the workflow. What is important is the ability for the user to authenticate only once against a trusted 3rd party authentication service provider, in this case GitHub, a token from which can then be passed around for communication between additional services. Once the token expires, a re-authentication is necessarily, however, that is far simpler than requesting potentially different user credentials each time a data transmission appears within the flow diagram.

Authorship Verification

The requirement of authorship verification covers two very specific use cases. Firstly, it enables other actors/users within the system to verify that the user claiming they are author of the delta are indeed who they claim to be. Secondly, it also prevents the author of the delta ever denying they have originated the delta in the first place. Supporting such basic principles is paramount for properly functioning system which will then prevent unnecessarily and lengthy legal litigation should problems with projects occur. There are clients of 3D Repo that use their patent-pending 3D Diff functionality to support legal cases when trying to reverse engineer the steps taken during the project that led to specific failures in design or processes.

The most basic information that can be used for authorship verification is:

• User and machine name;
• IP address;
• Username and password;
• Server-side project reference.

There are two strategies for verification of authorship:

1. Digital signature SSL encryption of individual streams/deltas;
2. Relying on single sign-on provider.

Both of the strategies listed above rely on a trusted 3rd party provider to certify the authenticity and validity of ownership on users' behalf. Digital signatures rely on a Root Certificate Authority which distributes a tree of certificated down to individual machines/web-browsers. Single sign-on providers such as the ones supported by PassportJS, on the other hand, provide a weaker form of authentication whereby the system actors all have to agree to rely on such 3rd party authentication as GitHub or Google. For simplicity and ease of implementation, the AEC Deltas project will support the latter during the course of the project until such time a more robust solution is required.