Cordite Network Map

September 11, 2018

(with apologies to Maroon 5)

Cordite Network Map

An open source Corda Network Map implementation

The Network Map design in Corda 3 has been a significant and very useful change. By defining a formal protocol, it has opened the possibility for compatibility zone operators to govern their zones in a manner suitable for their operations. If you’re interested to learn more, I highly recommend Mike Hearn’s excellent article:

Today, the Cordite Foundation have released an open source implementation of Corda’s Network Map and Doorman protocols.

We did this because we recognised that many teams, like ours, need an implementation they can use in their networks. The lack of one can sometimes be an impediment to the Corda adoption journey.

We’ve also added an innovation to help our journey towards greater decentralisation. More about this later.

The service is being used in the Cordite test networks and has been stable for a few months. The code quality, test coverage, and documentation is now suitable for open source distribution.

The admin user interface for Cordite’s Network Map Service.

Certification Protocols

“cause nothing compares to U”

The Cordite Network Map Service (Cordite NMS for short) implements the Corda Doorman certification protocol used to acquire the identity of the node for the compatibility zone.

It also innovates with a new certification protocol that we call CertMan. This allows for a node operator to register the node’s identity using a pre-existing EV PKI certificate. DV and OV certificates can also be used, depending on the configuration of the service.

How CertMan works

CertMan assumes that most organisations have acquired their own certificates to enable secure communications for their digital services. Assuming this is the case for your organisation, CertMan will issue Corda nodes certificates (as a set of JKS files) in exchange for a proof of ownership against the organisation’s certificate. These certificates can be issued indirectly from a number of well-known root certificate authorities (CAs). There are options to choose the exact set of trusted root CAs, for example, whether to bypass the PKIX verification, to turn off strict EV certificates, and more.

Here’s a generalised sequence for using CertMan:

A glimmer of the future

This work forms a small step towards a larger vision: we think that the adoption of Corda can be accelerated by allowing grass-roots growth of networks that coalesce under the one CordaNet. We think that the best way of achieving this is to decentralise governance and inter-connectivity between discreet compatibility zones. Regarding governance, R3 and the Corda community have been doing a fantastic job to allow for collaborative control. For connectivity, we think it may be possible to allow for the organic composition of inter-compatibile-zones from constituent zones. More on this in future posts.


“Fly me to the moon …”

Running the Cordite NMS using Docker

Starting up the Cordite NMS is very easy when using Docker:

$ docker run -e NMS_TLS=false -p 8080:8080 cordite/network-map

The service will run on http://localhost:8080. You can use this in your node.conf:

myLegalName="CN=cordite foundation,, L=Antarctica, C=AQ"
rpcSettings {
devMode : false
keyStorePassword : "cordacadevpass"
trustStorePassword : "trustpass"
compatibilityZoneURL : "http://localhost:8080"

The service will, by default, enable the doorman and certman protocols.

You can provide your own TLS certificate and key for the service using:

$ docker run 
-e NMS_TLS_CERT_PATH=<your-cert-path> 
-e NMS_TLS_KEY_PATH=<your-key-path> 
-p 8080:8080 cordite/network-map

Managing notaries and the whitelist

The Cordite NMS is designed to be simple to setup and maintain on commodity cloud hardware. One design choice is that its database is a simple filesystem. The location of the database is configurable (see Appendix A). Here’s the top level structure of the directory — note the inputs directory:

The inputs directory contains the whitelist.txt file required for zone constraints in Corda 3 and the validating and non-validating notary nodeInfo-* files. You alter these files directly at run-time. The NMS will watch the inputs directory for changes and will periodically publish changes to this directory as a network parameter update.

You can also use the Swagger API hosted on /swagger/.

Cordite NMS Swagger API

Finally, most (but not all) of the API is exposed in the NMS user interface.

Working with CertMan

Let’s say, as a node operator, you have a certificate and private key stored in the files domain.crt and domain.key respectively. We can receive our node’s JKS files using the following command line:

openssl dgst -sha256 -sign domain.key domain.crt | 
base64 | 
cat domain.crt - | 
curl -k -X POST -d @- http://<network-map-host-and-port>/certman/api/generate -o

Here we sign our public certificate with our private key and concatenate the certificate and signature as a payload to the API end-point /certman/api/generate. The returned zip file will contain the three jks files required by Corda. Unzip these into the Corda certificates directory and you’re good to go.

The certificate that’s presented to CertMan will be checked against the default set of root certificate authorities shipped with the JRE. If you’re not happy with this set, you can specify your own set of trusted authorities using NMS_CERTMAN_TRUSTSTORE and NMS_CERTMAN_TRUSTSTORE_PASSWORD. You can also control PKIX verification using NMS_CERTMAN_PKIX and whether strict EV certificates are required using NMS_CERTMAN_STRICT_EV.

What’s next?

We encourage the community to try it out and provide feedback! The source is Apache Licence v2 and we very much encourage contributions 🙂

Appendix A: Configuration parameters

Here’s the full list of system properties and environment variables you can use to control your instance.