Network Map Service

Purpose

The Network Map Service acts as a directory for all participants on the network. It is responsible for recording essential information of each participant such as connection address and available services. See Network Map Overview for an in-depth explanation.

Running The Network Map Service

The Network Map Service currently has to be initialised in two stages. First, the network parameters for the global network have to be loaded into the database. Once complete, the service can be started.

Setting the Network Parameters

The initial network parameters file can be loaded into the Network Map Service database using the --set-network-parameters flag. The complete list of flags required to set the network parameters is as follows:

• [–set-network-parameters] or [-s]: This flag specifies that you wish to set or update the network parameters, and should be followed by the new network parameters configuration file.

• [–network-truststore] or [-t]: This is used to define the network trustStore, which should contain the root certificate (similar to the network-root-truststore.jks file for Corda nodes). This is needed to validate that the notaries that have been set in the network parameters have a valid certificate issued by the Identity Manager.

• [–truststore-password] or [-p]: The password for the above trustStore.

• [–root-alias] or [-a]: The alias for the root certificate within the above trustStore.

An example of setting the network parameters is:

java -jar network-map-<VERSION>.jar --config-file <CONFIG_FILE> \
--set-network-parameters <NETWORK_PARAMS_CONFIG_FILE> \
--network-truststore <NETWORK_ROOT_TRUSTSTORE_FILE> \
--truststore-password <TRUSTSTORE_PASSWORD> \
--root-alias <ROOT_ALIAS>

The server will terminate once this process is complete. Upon completion the following message should be displayed:

Saved initial network parameters to be signed:
...

Starting The Network Map Service

The Network Map Service can now be started via:

java -jar network-map-<VERSION>.jar --config-file <CONFIG_FILE>

Optional parameter:

--working-dir=<DIR>

This will set the working directory to the specified folder. The service will look for files in that folder. This means certificates, config files etc. should be under the working directory. If not specified it will default to the current working directory (the directory from which the service has been started).

Configuration

Similar to the Identity Manager the main elements that need to be configured for the Network Map Service are:

• Address
• Database
• Embedded shell (optional)
• Network Data Signing Mechanism
• Cache Timeout
• Node Certificate Revocation Checking
• ENM Internal Server
• Identity Manager and Revocation Communication
• Restricting A Node’s Corda Version (optional)

Address

The address parameter must be included in the top level of the configuration and represents the host and port number that the Network Map Service will bind to upon startup. The host can either be the IP address or the hostname of the machine that Network Map Service is running on. For example:

address = "<SERVER_IP/SERVER_HOST>:<PORT_NUMBER>"

Database

The Network Map Service is backed by a SQL database which it uses to store the network map along with node infos. The connection settings must be included within the database configuration block in the config file. The main options that should be included here are:

• driverClassName - the DB driver class name (e.g com.microsoft.sqlserver.jdbc.SQLServerDriver for Microsoft SQL Server, org.postgresql.Driver for postgres)
• jdbcDriver - the path to the appropriate JDBC driver jar (e.g path/to/mssql-jdbc-7.2.2.jre8.jar)
• url - the connection string for the DB
• user - the username for the DB
• password - the password for the DB

Database Setup

The database can either be setup prior to running the Network Map Service or, alternatively, it can be automatically prepared on startup via the built-in migrations. To enable the running of database migrations on startup set the runMigration parameter within the database configuration to true.

If the Network Map Service is being run using the same DB instance as the Identity Manager Service then the Network Map schema name must be specified via the schema parameter within the database configuration block:

database {
    ...
    runMigration = true
    schema = networkmap
}

Additional Properties

Additional database properties can be loaded by including an optional additionalProperties config block. In CENM 1.0 these are restricted to HikariCP configuration settings.

database {
    ...
    additionalProperties {
        connectionTimeout = 60000
        maxLifetime = 3200000
        poolName = "myPool123"
    }
}

Example

An example configuration for a Network Map Service using a Microsoft SQL Service database, configured to run the migrations on startup is:

database {
    driverClassName = "com.microsoft.sqlserver.jdbc.SQLServerDriver"
    jdbcDriver = "path/to/mssql-<EXAMPLE_JDBC_DRIVER>.jar"
    url = "jdbc:sqlserver://<EXAMPLE_CONNECTION_STRING>"
    user = "example-user"
    password = "example-password"
    schema = "network-map"
    runMigration = true
    database {
        additionalProperties {
            connectionTimeout = 60000
            maxLifetime = 3200000
            poolName = "myPool123"
        }
    }
}

Embedded shell (optional)

See Shell Configuration for more information on how to configure the shell.

Network Data Signing Mechanism

Before any changes to the network data (e.g. Network Map or Network Parameter updates) can be broadcast to the participants on the network, they first need to be signed. Similarly to the Identity Manager, there are currently two mechanisms for this:

• Local Signing Service
• External Signing Service

Local Signing Service

The local Signing Service is recommended for testing and toy environments. Given a local key store containing the relevant signing keys, it provides the functionality to automatically sign all approved Network Map and Parameter updates on a configured schedule. No human interaction is needed and the credentials for the key stores have to be provided upfront. The service is an integrated signer that is a cut-down version of the standalone Signing Services and provides no HSM integration or ability to manually verify changes. It is strongly recommended against using this for production environments.

In order for the local signer to function, it needs to be able to access Network Map’s certificate and keypair which should have been previously generated (see Certificate Hierarchy Guide for more information). The local signer uses local key stores which should include the necessary signing keys along with their full certificate chains.

To enable the local signer, the top level localSigner configuration block should be added to the config file:

localSigner {
    keyStore {
        file = exampleKeyStore.jks
        password = "example-keystore-password"
    }
    keyAlias = "example-key-alias"
    keyPassword = "example-key-password" # optional - defaults to key store password
    signInterval = 15000 # signing interval in millis
}

In this example, the key store defined within the local signer should contain the Network Map’s key pair used for signing any network map or parameter changes along with the full certificate chain back to the root of the network.

External Signing Service

The production grade signing mechanism is the external Signing Services. This has all the functionality of the integrated local signer as well as HSM integration and the ability for a user to interactively verify and sign incoming network map or parameter changes. It should be used in all production environments where maximum security and validation checks are required.

In order to retrieve the network map and parameter data, the Signing Service will communicate with the Network Map service via its ENM internal server. This is the only configuration option that is needed if signing is being done via the external Signing Service.

Cache Timeout

The Network Map Service configuration contains a single required top-level parameter pollingInterval. This determines how often the server should poll the database for newly signed network map and parameter changes. It also determines how often nodes should poll the Network Map Service for a new network map (by including this value in the HTTP response header).

It takes a numerical value and represents the number of milliseconds between each refresh. An example of how this should be added to the config file is:

...
pollingInterval = 600000
...

Node Certificate Revocation Checking

In cases when the certificate revocation list infrastructure (See Certificate Revocation List for more information) is provided, the additional validation for the node’s certificates can be enabled in the Network Map Service. This is achieved via the top-level checkRevocation flag set in the configuration file. This ensures that any node within the Network Map has a valid, trusted certificate.

Setting this flag will result in the nodes legal identities certificate paths being validated against the certificate revocation lists whenever the Network Map is updated. Any node that has a revoked certificate will be removed from the Network Map. The certificates are also checked when the node submits its information to the Network Map Service to publish for the first time.

An example of how this should be added to the config file is:

...
checkRevocation = true
...

ENM Internal Server

To enable communication between the Network Map Service and other network management services, such as Revocation and Identity Manager servers, upon start up the Network Map Service will create an internal long running listening server. The configuration block enmListener can be used to define the properties of this listener, such as the port it listens on as well as the retrying and logging behaviour.

...
enmListener {
    port = 5050
    reconnect = true
}
...

Identity Manager and Revocation Communication

The Network Map Service may need to speak to both the Identity Manager and Revocation services. For example, the Network Map service may need to communicate with the Revocation service for CRL related information. This is configured via the identityManager and revocation configuration options within the networkMap configuration block:

...
identityManager {
    host = <IDENTITY_MANAGER_HOST> # e.g. identity-manager-url.com
    port = <IDENTITY_MANAGER_LISTENER_PORT>
}
revocation {
    host = <REVOCATION_HOST> # e.g. identity-manager-url.com
    port = <REVOCATION_LISTENER_PORT>
}
...

The host should correspond to the host part of the address value in the Identity Manager configuration. The port parameter for each service should correspond with the port value within the enmListener config block in the service’s configuration. See Network Map Configuration Parameters for more information.

Restricting A Node’s Corda Version (optional)

The optional tpo-level configuration versionInfoValidation can be added to the configuration to exclude nodes running an old version of Corda from successfully publishing their node info to the network map. The configuration parameter minimumPlatformVersion represents the minimum platform version that a node has to be running to be able to successfully publish. If this is set, then any node that attempts to publish its node info whilst running a version of Corda with a platform version less than this will be automatically rejected. This can be used to ensure that all nodes that join the network have access to certain features.

...
versionInfoValidation {
    minimumPlatformVersion = 4
}
...

Example Configuration

address = "localhost:20000"

database {
    driverClassName = org.h2.Driver
    url = "jdbc:h2:file:./network-map-persistence;DB_CLOSE_ON_EXIT=FALSE;LOCK_TIMEOUT=10000;WRITE_DELAY=0;AUTO_SERVER_PORT=0"
    user = "example-db-user"
    password = "example-db-password"
    runMigration = true
}

pollingInterval = 10000


localSigner {
    keyStore {
        file = exampleKeyStore.jks
        password = "example-password"
    }
    keyAlias = "example-key-alias"
    signInterval = 15000
}

enmListener {
    port = 20001
}

checkRevocation = false

shell {
  sshdPort = 20002
  user = "testuser"
  password = "example-password"
}

Network Parameters

Along with the above configuration, a network-parameters configuration file also needs to be created. This defines the basic settings for communication across the network along with references to the notaries node info files. Therefore it is advisable to register the notaries with the Identity Manager Service and generate their node info files prior to starting the network map.

The network parameters should contain reference to the notaries node info files. The notary node info files should be copied over to the Network Map Service.

Example Network Parameters File

notaries : [
    {
        notaryNodeInfoFile: "/Path/To/NodeInfo/File1"
        validating: true
    },
    {
        notaryNodeInfoFile: "/Path/To/NodeInfo/File2"
        validating: false
    }
]
minimumPlatformVersion = 1
maxMessageSize = 10485760
maxTransactionSize = 10485760
whitelistContracts = {
    cordappsJars = [
        "/Path/To/CorDapp/JarFile1",
    ],
    exclude = [
        "com.cordapp.contracts.ContractToExclude1",
    ]
}
eventHorizonDays = 30 # Duration in days

Node’s host IP address

The Network Map Service provides an endpoint that can be used to determine the IP address of the querying host. This is useful especially when dealing with node’s deployment in environments with IP address translation.