Issues with node bringup while using own certificates after turning off devMode

Question

We are facing following issues in bringing up Corda code while using our own generated certificates (not the ones generated by Corda node in devMode=true).

Following are the steps we did:

• Generated certificates as per https://docs.corda.net/permissioning.html
• Copied the certificates to /certificates directory .
• Deleted cordadevcakeys.jks and cordatruststore.jks in the resources directory

Started the node. We got the following error:

Exception during node startup {} java.lang.IllegalArgumentException: Couldn't find network parameters file and compatibility zone wasn't configured/isn't reachable at net.corda.node.internal.NetworkParametersReader.retrieveNetworkParameters(NetworkParametersReader.kt:53) ~[corda-node-corda-4.0-SNAPSHOT.jar:?] at net.corda.node.internal.NetworkParametersReader.access$retrieveNetworkParameters(NetworkParametersReader.kt:17) ~[corda-node-corda-4.0-SNAPSHOT.jar:?] at net.corda.node.internal.NetworkParametersReader$networkParameters$2.invoke(NetworkParametersReader.kt:26) ~[corda-node-corda-4.0-SNAPSHOT.jar:?] at

Now if we keep cordadevcakeys.jks and cordatruststore.jks in the resources directory, the node comes up.

Queries:

1. Do we need to provide a compatibility zone url in the above case?
2. If so could you please help us to understand the requirements for configuring the same?
3. How does corda doorman sends certificates? Using HTTPS/HTTP GET method? Or any other protocol?
4. Could you please explain the dependency on cordadevcakeys.jks and cordatruststore.jks in the resources directory for the node bringup, devmode=false & the compatibility zone
5. Could you please explain the need for and structure of network-parameters?
6. We were not able to find the proper use or document for network-parameters. Could you please help to understand the same?
7. Is configuring compatibility zone different from configuring network map service?
8. Doorman is different from network map and doorman is an offline entity and certificates are generated and circulated out of band? Is this understanding right?
9. Is network-map a single file or discrete different node-info files. If it is a single file, could you please share the format and encoding? What does the hash in /network-map/node-info/{hash} represent?
10. I am confused with the usage of /network-map/ack-parameters. Could you please explain the same?
11. In https://docs.corda.net/corda-configuration-file.html example compatibilityZoneUrl is given with scheme “https://“. Is this example wrong?
12. How to create network-parameters file? I got a sense of the file. But exact encoding I don’t know. Is this file created by a standalone program? Who signs this? Does the node operator need to manually accept the new set of network parameter each time? How do I know the hash of /network-map/network-parameters/{hash}?
13. Please see the attached picture of my understanding. Kindly let me know whether the understanding and the process is the right.

14. Could you please specify the end point to which nodes send certificate requests? I saw the following: https://github.com/corda/corda/blob/a3d88f752d964d3768e153be189f196c600c8d7d/docs/source/example-code/src/main/resources/example-node-with-networkservices.conf:

    networkServices : {
       doormanURL = "https://registration.corda.net"
       networkMapURL = "https://cz.corda.net"
    }
    

    Could you please explain the rest endpoints served by the doorman URL? Is it /certificate?

15. Since the network map has the following structure:

    data class NetworkMap(  
        val nodeInfoHashes: List<SecureHash>,
        val networkParameterHash: SecureHash,
        val parametersUpdate: ParametersUpdate?
    ) 
    

    And it does not contain a nodeinfo. Is the following the right procedure?

    1. The node first gets the hashes of all the nodeinfos from the network map
    2. The node then downloads all the nodeInfos one by one

    Could you please explain when the nodeInfo is uploaded? Also, if a given node is the first node, the network map may be empty. Will the node fail to boot up because there is nothing in the network map (since there are no nodeinfos)?

Answer 1

NB: As well as looking at these answers, you should refer to:

• The test network map server implementation here: https://github.com/corda/corda/blob/24fa695ca0ef72fa851abc5b1630d722f32577ec/testing/node-driver/src/main/kotlin/net/corda/testing/node/internal/network/NetworkMapServer.kt

• The test doorman-request handler here: https://github.com/corda/corda/blob/a3d88f752d964d3768e153be189f196c600c8d7d/node/src/integration-test/kotlin/net/corda/node/utilities/registration/NodeRegistrationTest.kt

Answers below:

1. Yes. This error message is thrown either because you haven't provided a compatibility zone URL, or because the server at the URL you provided cannot be reached

2. You need to provide a network map server that listens on the address listed in the node's configuration file as the compatibility zone URL and implements the following protocol: https://docs.corda.net/network-map.html#http-network-map-protocol

3. The doorman sends the network map parameters and node information using HTTP, in response to HTTP GET requests that obey this protocol: https://docs.corda.net/network-map.html#http-network-map-protocol. HTTPS is not used, but because the network parameters and node information objects are signed, they cannot be tampered with

4. These .jks files are development keystores that are only used when running the nodes in dev mode (i.e. when devMode=true)

5. The need for the network parameters is documented here: https://docs.corda.net/network-map.html#network-parameters. The structure of the network parameters is a serialised instance of the following class: https://github.com/corda/corda/blob/8504b65e7b14a95fc4486c82d1e3e77d1c4e3562/core/src/main/kotlin/net/corda/core/node/NetworkParameters.kt#L27

6. The network parameters are documented here: https://docs.corda.net/network-map.html#network-parameters

7. No. They are the same thing

8. Yes, they are different entities. The doorman provides node CA certificates, while the network map is used to allow nodes to discover other nodes on the network. The root network CA certificate is circulated out-of-band. Nodes then use the --initial-registration flag (see https://docs.corda.net/permissioning.html#connecting-to-a-compatibility-zone) to perform a certificate signing request and create their node CA certificate. The node will then create its identity certificates and TLS certificates when it first starts up, and send its NodeInfo to the network map

9. The network map is a single file. It's a serialised instance of the SignedDataWithCert<NetworkMap> class. The hash in the URL is the SecureHash of a SerialisedBytes<NodeInfo>

10. The node will handle sending the acknowledgment automatically if you use the acceptNewNetworkParameters RPC operation, documented here: https://docs.corda.net/network-map.html#network-parameters-update-process

11. Using HTTPS is fine, but optional

12. The network-parameters file is a serialised instance of the SignedDataWithCert<NetworkParameters> class. It must be signed by the same certificate that signed the network map object (i.e. the entity with the doorman CA role). Yes, the node needs to accept the new network parameters - see the docs here: https://docs.corda.net/network-map.html#network-parameters-update-process. You get the hash by requesting the network map object itself. This object has a networkParameterHash field, which is the hash you need.

13. The diagram is slightly wrong. You need to make the GET /network-map request as the first step, not the last. This will provide the required network-parameters hash

14. That's correct. You need to hit the /certificate endpoint

15. The procedure you describe is correct. The node uploads its nodeInfo at node startup. It checks if its nodeInfo has changed and if it has, it submits the new one to the network map. If the network map is currently empty when a node boots up, the node will always add its own nodeInfo to its local cache, even if the network map it downloads doesn’t contain it. However, it will still boot up even if the network map is initially empty