Splinter Certificates

This document describes:

Splinter Certificate Definitions

The splinter cert generate command creates the following certificates and keys:

  • client.crt
  • client.key
  • server.crt
  • server.key
  • generated_ca.pem
  • generated_ca.key

client.crt, client.key

Used by the Splinter node when initiating a connection to a peer. They are normally signed by the local certificate authority(CA) generated_ca.pem. This certificate is validated by remote peers using their ca.pem file, described below.

server.crt, server.key

Used when accepting incoming connections from peers. The generated files are adequate for development purposes but in a production scenario, these should be signed by a CA trusted by peers, such as Let’s Encrypt or Digicert. This should be the full chain certificate.

generated_ca.pem, generated_ca.key

This local CA key pair is generated by the splinter cert generate command and is used to sign client and server certificates generated with the splinter cert generate command. In a production setup, only the client would be signed with this CA, as the server cert should be signed by a CA trusted by peers such as Let’s Encrypt or Digicert.

The contents of generated_ca.pem will end up in each remote peer’s ca.pem file so that they trust your client certificate for peering.


This file is not created by splinter cert generate, but is required when operating without --tls-insecure. It should contain the CA certificates that were used to sign client certificates for remote peers. This is usually each peer’s generated_ca.pem file. This has the effect of determining which nodes you can peer with. It does not need to contain the CA certificate which signed the local certificates (client or server), but it can not be empty. It is ignored when --tls-insecure is used.

Each of these files can be specified either in the splinter.toml config file or as command line arguments to splinterd.


This document assumes you have an Ubuntu Focal environment with the stable versions of the splinter CLI and the Splinter daemon (splinterd) installed, as well as sudo permissions.

Installation instructions can be found here.

Using Let’s Encrypt Certificates with Splinter

In general, Let’s Encrypt certificates are used to encrypt HTTP traffic, but they can also be used as server certificates for Splinter.

There are many methods for obtaining TLS certificates from Let’s Encrypt but this guide will focus on using certs obtained with certbot. If a different client is used, the resulting files may be in different directories or named differently.

  1. Follow the instructions here to install certbot and get certificates.

    By default, the Let’s Encrypt certificates are located in various directories in /etc/letsencrypt. Symlinks to the most current certificates are created in /etc/letsencrypt/live/$domain. Because these symlinks are updated during the automated renewal process, which is enabled by default for Ubuntu Focal, it is not advisable to move or copy the certificates from /etc/letsencrypt.

  2. Verify the cerificates were installed.

    $ sudo ls -l /etc/letsencrypt/live/foo.splinter.dev
    total 4
    -rw-r--r-- 1 root root 692 May 26 14:34 README
    lrwxrwxrwx 1 root root  42 May 27 16:47 cert.pem -> ../../archive/foo.splinter.dev/cert1.pem
    lrwxrwxrwx 1 root root  43 May 27 16:47 chain.pem -> ../../archive/foo.splinter.dev/chain1.pem
    lrwxrwxrwx 1 root root  47 May 27 16:47 fullchain.pem -> ../../archive/foo.splinter.dev/fullchain1.pem
    lrwxrwxrwx 1 root root  45 May 27 16:47 privkey.pem -> ../../archive/foo.splinter.dev/privkey1.pem
  3. Grant splinterd read rights to the certificates.

    $ sudo chmod 0750 /etc/letsencrypt/{live,archive}
    $ sudo chgrp splinterd /etc/letsencrypt/{live,archive}
    $ sudo chgrp splinterd /etc/letsencrypt/live/foo.splinter.dev/privkey.pem
    $ sudo chmod 0640 /etc/letsencrypt/live/foo.splinter.dev/privkey.pem
    $ sudo chgrp splinterd /etc/letsencrypt/live/foo.splinter.dev/fullchain.pem
    $ sudo chmod 0640 /etc/letsencrypt/live/foo.splinter.dev/fullchain.pem
  4. Use the Splinter CLI to generate certificates. While this command generates both client and server certificates, we will be ignoring the server certs and using the Let’s Encrypt certrificates instead.

    $ sudo splinter cert generate
    Writing file: /etc/splinter/certs/generated_ca.pem
    Writing file: /etc/splinter/certs/private/generated_ca.key
    Writing file: /etc/splinter/certs/client.crt
    Writing file: /etc/splinter/certs/private/client.key
    Writing file: /etc/splinter/certs/server.crt
    Writing file: /etc/splinter/certs/private/server.key
  5. Create a ca.pem file. Splinterd will not start without at least one valid certificate in the ca.pem file. Since we don’t have any peers yet, an example certificate is provided below as a workaround for this guide only. In a real-world scenario, this file should be populated with the contents of the generated_ca.pem from each of your peers.

    $ sudo vi /etc/splinter/certs/ca.pem

    Paste the example certificate

    # Example only, do not use in production.
    -----END CERTIFICATE-----

    Save the file and exit

    Grant the splinterd group read rights

    $ sudo chown root:splinterd /etc/splinter/certs/ca.pem
  6. Create a splinterd config file. This step is only necessary if you haven’t previously configured splinterd.

    $ sudo cp -p /etc/splinter/splinterd.toml.example /etc/splinter/splinterd.toml
  7. Update the config file with correct certificate paths

    $ sudo vi /etc/splinter/splinterd.toml
    # List of certificate authority certificates (*.pem files).
    tls_ca_file = "/etc/splinter/certs/ca.pem"
    # A certificate signed by a certificate authority. Used by the daemon when it
    # is acting as a client (sending messages)
    tls_client_cert = "/etc/splinter/certs/client.crt"
    # Private key used by daemon when it is acting as a client
    tls_client_key = "/etc/splinter/certs/private/client.key"
    # A certificate signed by a certificate authority. Used by the daemon when it
    # is acting as a server (receiving messages).
    tls_server_cert = "/etc/letsencrypt/live/foo.splinter.dev/fullchain.pem"
    # Private key used by daemon when it is acting as a server.
    tls_server_key = "/etc/letsencrypt/live/foo.splinter.dev/privkey.pem"

That’s it! The next time you start Splinter, your traffic will be encrypted with production-ready Let’s Encrypt certificates that will automatically renew every 90 days.

For More Information

splinterd man page

Example splinterd.toml config file