TLS

Orion supports the Transport Layer Security (TLS) protocol to enable secure communications. TLS is used between Orion nodes only. TLS is not used between Besu and Orion nodes.

Enable TLS by setting the tls property to strict in the Orion configuration file.

Generating certificates using Orion

To have Orion generate certificates, start the nodes with the TLS trust mode set to insecure-no-validation for tlsclienttrust and tlsservertrust until the tlsknownclients and tlsknownservers files are populated. When the files are populated, restart the nodes with the TLS trust mode set to whitelist for tlsclienttrust and tlsservertrust.

Generating certificates using OpenSSL

These procedures explain how to use OpenSSL to generate certificates when the Common Name (CN) is either the public DNS or an IP address. Before you begin, ensure OpenSSL is installed.

Public DNS is CN

To use a public DNS as CN:

Generating a CA certificate

  1. Generate a key file called orion_ca.key:

    openssl genrsa -out orion_ca.key 2048

  2. Generate a certificate authority (CA) certificate called orion_ca.pem that uses orion_ca.key:

    openssl req -x509 -new -nodes -key orion_ca.key -sha256 -days 1024 -out orion_ca.pem

Generating a new certificate for a node

We recommend each node has its own certificate. To generate the certificate:

  1. Generate a key file called orion_cer.key:

    openssl genrsa -out orion_cer.key 2048

  2. Generate a certificate signing request (CSR) called orion_cer.csr:

    openssl req -new -key orion_cer.key -out orion_cer.csr

  3. Answer each prompt for information to be added to the certificate request. Ensure the value you specify for Common Name (CN) matches the host public DNS so the requests from the server are accepted. The name is also specified in the configuration file for the nodeurl and clienturl options.

  4. Generate a certificate called orion_cer.pem signed by the CA certificate:

    openssl x509 -req -in orion_cer.csr -CA orion_ca.pem -CAkey orion_ca.key -CAcreateserial -out orion_cer.pem -days 500 -sha256

Example Orion configuration file using the created certificates

nodeurl = "<YOUR-COMMON-NAME>:8080/"
nodeport = 8080

clienturl = "<YOUR-COMMON-NAME>:8888/"
clientport = 8888

othernodes = ["<YOUR-COMMON-NAME>:8080"]

workdir = "<PATH-TO>/orion/bin"

publickeys = ["orion.pub"]
privatekeys = ["orion.key"]

tls = "strict"

tlsservercert = "<PATH-TO>/orion/bin/orion_cer.pem"
tlsserverchain = ["<PATH-TO>/orion/bin/orion_ca.pem"]
tlsserverkey = "<PATH-TO>/orion/bin/orion_cer.key"

tlsclientcert = "<PATH-TO>/orion/bin/orion_cer.pem"
tlsclientchain = ["<PATH-TO>/orion/bin/orion_ca.pem"]
tlsclientkey = "<PATH-TO>/orion/bin/orion_cer.key"

tlsclienttrust = "ca"
tlsservertrust = "ca"

nodenetworkinterface = "0.0.0.0"
clientnetworkinterface = "0.0.0.0"

IP address is CN

To use a public IP address as CN:

Updating the openssl.cfn file

  1. Find the openssl.cfn file, and create a copy of it.
  2. In your copy of the openssl.cfn file, find the [req] section, and add:

    req_extensions = v3_req
    
    [ v3_req ]
    basicConstraints = CA:FALSE
    keyUsage = nonRepudiation, digitalSignature, keyEncipherment
    subjectAltName = @alt_names
    
    [alt_names]
    DNS.1 = <DNS-PUBLIC-RECORD>
    DNS.2 = <DNS-PRIVATE-RECORD>
    IP.1 = <PUBLIC-IP-ADDRESS>
    IP.2 = <PRIVATE-IP-ADDRESS>
    
  3. For each DNS you want to use as an alternate name, specify a DNS.n entry.

  4. For each IP address you want as an alternate IP address, specify an IP.n entry.

Generating a new CSR for a node

  1. Run the following command. Substitute your values for all variables.

    openssl req -new -key orion_cer.key -out orion_cer.csr -config <PATH-TO>/openssl.cnf

  2. Test whether the certificate was generated with the expected subject alternative names:

    openssl req -text -noout -in orion_cer.csr

    Example of command output

    [...]
    Requested Extensions:
          X509v3 Subject Alternative Name:            
    DNS:<DNS-PUBLIC-RECORD>,
    DNS:<DNS-PRIVATE-RECORD>, 
    IP Address:<PUBLIC-IP-ADDRESS>, 
    IP Address:<PRIVATE-IP-ADDRESS>
    [...]
    

Generating a new certificate

  1. Run the following command. Substitute your values for all variables.

    openssl x509 -req -in orion_cer.csr -CA orion_ca.pem -CAkey orion_ca.key -CAcreateserial -out orion_cer.pem -days 500 -sha256 -extfile <PATH-TO>/openssl.cnf -extensions v3_req

  2. Test whether the generated certificate contains the subject alternative names:

    openssl x509 -in orion_cer.pem -text -noout

    Example of command output

    [...]
    X509v3 extensions:
        X509v3 Subject Alternative Name:
    DNS:<DNS-PUBLIC-RECORD>,
    DNS:<DNS-PRIVATE-RECORD>, 
    IP Address:<PUBLIC-IP-ADDRESS>, 
    IP Address:<PRIVATE-IP-ADDRESS>
    [...]
    

TLS Properties in Orion Configuration File

TLS properties are specified in the configuration file.

tls

TLS status options are:

  • strict - All connections to and from this node must use TLS with mutual authentication. See tlsservertrust and tlsclienttrust.
  • off - Mutually authenticated TLS is not used for in- and outbound connections. Unauthenticated connections to HTTPS hosts are still possible. Use only if another transport security mechanism like WireGuard is in place.

tlsservercert

File containing the server TLS certificate in Apache format. The certificate identifies this node to other nodes when they connect to the node API. If the certificate does not exist, it is created.

tlsserverchain

List of files that make up the CA trust chain for the server certificate. The list can be empty for auto-generated/non-PKI-based certificates.

tlsserverkey

File containing the private key for the server TLS certificate. If the private key does not exist, it is created.

tlsservertrust

TLS trust mode for the server. The trust mode defines which nodes can connect to the server. Options:

  • whitelist - Only nodes that have previously connected to this node and have been added to tlsknownclients can connect. New clients are not added to tlsknownclients.

  • tofu - Trust-on-first-use. Only the first node that connects identifying as a certain host can connect as the same host in the future. Nodes identifying as other hosts can still connect. To restrict access, change the mode to whitelist after populating the tlsknownclients list.

  • ca - Only nodes with a valid certificate and chain of trust to one of the system root certificates can connect. Use the SYSTEM_CERTIFICATE_PATH environment variable to override the directory containing trusted root certificates.

  • ca-or-tofu - Combination of ca and tofu. If a certificate is valid, it is always allowed and added to the tlsknownclients list. If it is self-signed, it is allowed only if it is the first certificate this node has seen for that host.

  • insecure-no-validation - Any client can connect. Clients are added to the tlsknownclients file.

tlsknownclients

TLS known clients for the server. The tlsknownclients contains the fingerprints of public keys of other nodes that can connect to this node for the ca-or-tofu, tofu, and whitelist trust modes.

tlsclientcert

File containing the client TLS certificate in Apache format. The certificate identifies this node to other nodes when it is connecting to the node API. If the certificate does not exist, it is created.

tlsclientchain

List of files that make up the CA trust chain for the client certificate. The list can be empty for auto-generated/non-PKI-based certificates.

tlsclientkey

File containing the private key for the client TLS certificate. If the private key does not exist, it is created.

tlsclienttrust

TLS trust mode for the client. The trust mode defines the servers to which the client connects. Options:

  • whitelist - Nodes only connects to servers it has previously seen and have been added to tlsknownservers. New servers are not added to tlsknownservers.

  • tofu - Trust-on-first-use. Node only connects same server for any given host. This is similar to how OpenSSH works.

  • ca - Node only connects to servers with a valid certificate and chain of trust to one of the system root certificates. Use the SYSTEM_CERTIFICATE_PATH environment variable to override the directory containing trusted root certificates.

  • ca-or-tofu - Combination of ca and tofu. If a certificate is valid, it is always allowed and added to the tlsknownservers list. If it is self-signed, it is allowed only if it is the first certificate this node has seen for that host.

  • insecure-no-validation - Node connects to any server. Servers are added to the tlsknownservers file.

tlsknownservers

TLS known servers for the client. The tlsknownservers contains the fingerprints of public keys of other nodes that this node has encountered for the ca-or-tofu, tofu, and whitelist trust modes.