Securing your gRPC connections

This section will help advanced users create and setup TLS certificates to allow for secure gRPC connections to their beacon nodes.


The only practical use for using secure gRPC is in the case of connecting a beacon node that is being hosted remotely. For configurations in which the beacon node and validator reside on the same host system, these steps are not required nor recommended.

A beacon node, by default, hosts a gRPC server on host and port 4000, allowing any other process, such as a validator client, to establish an insecure connection on that port. The beacon node can also allow for secure, TLS connections if ran with the --tls-cert=/path/to/cert.pem and --tls-key=/path/to/cert.key flags, ensuring all connections via gRPC are secured.

A validator client will attempt to connect to a beacon node by default with an insecure connection, but can be a secure TLS connection by using a --tls-cert=/path/to/cert.pem flag, utilising either a server pem certificate or a ca.cert certificate authority file. Assuming a TLS certificate has already been set up with a trusted authority for your beacon node, use the commands below to launch the node and validator. Otherwise, review the following section on creating your own self-signed certificates.

To use secure gRPC with a beacon node:

./ beacon-node --tls-cert=server.pem --tls-key=server.key

and to use secure gRPC with a validator:

./ validator --tls-cert=server.pem

Alternatively, a ca.cert certificate authority file can be passed to the validator to attempt a connection without requiring the server's certificate itself:

./ validator --tls-cert=ca.cert

This will generate an output like so:

[2020-06-15 17:09:13] INFO validator: Established secure gRPC connection

Generating self-signed TLS certificates

NOTICE: Creating a self-signed certificate is fine for simple TLS connections, though if the deployment will see public usage, it is always recommended to obtain valid certificates from a trusted certificate authority instead.

  1. Install openssl for your operating system.

  2. Create a root signing key:

    openssl genrsa -out ca.key 4096
  3. Create a self-signed root certificate

    openssl req -new -x509 -key ca.key -sha256 -subj "/C=US/ST=NJ/O=CA, Inc." -days 365 -out ca.cert
  4. Create a key certificate for the beacon node:

    openssl genrsa -out beacon.key 4096
  5. Generate a signing CSR by first creating a certificate.conf configuration file containing the specifications. For reference, you can use something as follows with any of its fields customized to your needs:

    default_bits = 4096
    prompt = no
    default_md = sha256
    req_extensions = req_ext
    distinguished_name = dn
    C = US
    ST = NJ
    O = Test, Inc.
    CN = localhost
    subjectAltName = @alt_names
    DNS.1 = localhost
    IP.1 = ::1
    IP.2 =
  6. Generate the signing CSR:

    openssl req -new -key beacon.key -out beacon.csr -config certificate.conf
  7. Generate a certificate for the beacon node:

    openssl x509 -req -in beacon.csr -CA ca.cert -CAkey ca.key -CAcreateserial -out beacon.pem -days 365 -sha256 -extfile certificate.conf -extensions req_ext
  8. Verify your certificate is correct with openssl:

    openssl x509 -in beacon.pem -text -noout

    This will generate an output like so:

    Version: 3 (0x2)
    Serial Number: 12510557889986420634 (0xad9e6e1dfe99df9a)
    Signature Algorithm: sha256WithRSAEncryption
    Issuer: C=US, ST=NJ, O=CA, Inc.
    Not Before: Jun 15 21:12:24 2020 GMT
    Not After : Jun 15 21:12:24 2021 GMT
    Subject: C=US, ST=NJ, O=Test, Inc., CN=localhost
    Subject Public Key Info:
    Public Key Algorithm: rsaEncryption
    Public-Key: (4096 bit)

Using the new certificates

  1. Use the certificates to launch the beacon node:

    ./ beacon-node --tls-cert=beacon.pem --tls-key=beacon.key
  2. As well as a validator:

    ./ validator --tls-cert=ca.cert

    This will generate an output like so:

    [2020-06-15 17:09:13] INFO validator: Established secure gRPC connection