corda/docs/source/permissioning.rst

Network permissioning (Doorman)

The keystore located in <workspace>/certificates/sslkeystore.jks is required to connect to the Corda network securely. In development mode (when devMode = true, see "corda-configuration-file" for more information) a pre-configured keystore will be used if the keystore does not exist. This is to ensure developers can get the nodes working as quickly as possible.

However this is not secure for the real network. This documentation will explain the procedure of obtaining a signed certificate for TestNet.

Initial Registration

The certificate signing request will be created based on node information obtained from the node configuration. The following information from the node configuration file is needed to generate the request.

myLegalName

Your company's legal name. e.g. "Mega Corp LLC". This needs to be unique on the network. If another node has already been permissioned with this name then the permissioning server will automatically reject the request. The request will also be rejected if it violates legal name rules, see Legal Name Constraints for more information.

Note

In a future version the uniqueness requirement will be relaxed to a X.500 name. This will allow differentiation between entities with the same name.

emailAddress

e.g. "admin@company.com"

certificateSigningService

Doorman server URL. A doorman server will be hosted by R3 in the near future. e.g."https://testnet.certificate.corda.net"

A new pair of private and public keys generated by the Corda node will be used to create the request.

The utility will submit the request to the doorman server and poll for a result periodically to retrieve the certificates. Once the request has been approved and the certificates downloaded from the server, the node will create the keystore and trust store using the certificates and the generated private key.

Note

You can exit the utility at any time if the approval process is taking longer than expected. The request process will resume on restart.

This process only is needed when the node connects to the network for the first time, or when the certificate expires.

Legal Name Constraints

The legal name is the unique identifier in the Corda network, so constraints have been set out to prevent encoding attacks and visual spoofing.

The legal name validator (see LegalNameValidator.kt) is used to enforce rules on Corda's legal names, it is intended to be used by the network operator and Corda node during the node registration process. It has two functions, a function to normalize legal names, and a function to validate legal names.

The normalize function performs the following transformations:

• Remove leading and trailing whitespaces.
• Replace multiple whitespaces with a single space.
• Normalize the string according to NFKC normalization form.

The validation function will validate the input string using the following rules:

• No blacklisted words like "node", "server".
• Restrict names to Latin scripts for now to avoid right-to-left issues, debugging issues when we can't pronounce names over the phone, and character confusability attacks.
• Should start with a capital letter.
• No commas or equals signs.
• No dollars or quote marks, although we may relax the quote mark constraint in future to handle Irish company names.

Starting the Registration

You will need to specify the working directory of your Corda node using --base-dir flag. This is defaulted to current directory if left blank. You can also specify the location of node.conf with --config-file flag if it's not in the working directory.

To start the registration:

java -jar corda.jar --initial-registration --base-dir <<optional>> --config-file <<optional>>

A certificates folder containing the keystore and trust store will be created in the base directory when the process is completed.

Warning

The keystore is protected by the keystore password from the node configuration file. The password should kept safe to protect the private key and certificate.

Protocol Design

Note

This section is intended for developers who want to implement their own doorman service.

The certificate signing protocol:

• Generate a keypair, save it to disk.
• Generate a CSR using Bouncy Castle or the java crypto APIs containing myLegalName from the config file. We should also have an admin email address in the config file and CSR so we know who to email if anything goes wrong. Sign it with the private key.
• HTTPS POST the CSR to the doorman. It creates the server-side records of this request, allocates an ID for it, and then sends back an HTTP redirect to another URL that contains that request ID (which should be sufficiently large that it's not predictable or brute forceable).
• Store that URL to disk.
• Server goes into a slow polling loop, in which every 10 minutes or so it fetches the URL it was given in the redirect. Mostly it will get 204 No Content. Eventually it will get 200 OK and download the signed certificate in binary form, which it can then stash in its local keystore file.

The initial registration process uses the following web api to communicate with the doorman service:

Request method	Path	Description
POST	/api/certificate	Create new certificate request record and stored for further approval process, server will response with a request ID if the request has been accepted.
GET	/api/certificate/{requestId}	Retrieve certificates for requestId, the server will return HTTP 204 if request is not yet approved or HTTP 401 if it has been rejected.

See NetworkRegistrationHelper and X509Utilities for examples of certificate signing request creation and certificate signing using Bouncy Castle.