Splinter Certificates

This document describes:

Each of the certificates and key files used by splinterd
How to use Let’s Encrypt certificates with Splinter

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.

ca.pem

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.

Prerequisites

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.

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.

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

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

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

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.
-----BEGIN CERTIFICATE-----
MIICyTCCAbGgAwIBAgIBADANBgkqhkiG9w0BAQsFADAXMRUwEwYDVQQDDAxnZW5l
cmF0ZWRfY2EwHhcNMjEwNjI0MTk0MjM5WhcNMjIwNjI0MTk0MjM5WjAXMRUwEwYD
VQQDDAxnZW5lcmF0ZWRfY2EwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB
AQDgR/Yj6SJbh/VFC76v+JwiB59ehsNsCu4Hp2jVrDEEyi2b5BHsRFDbNbLsjj5t
mfQ5sbv34xsIweN+kqZwLL1XcEDFBygx1Aa+kB4ZkzJqu1Amz4D3k8Ak29d1izA4
k5/UHzunUd9klL9DceYVqRYGpN//dqf9PohLZZ76tvGWdnxZlY0mFP1SdsklgG97
zxDjRTjpGfLgJSrmvl3jyf/bqjsKKaKr+Rr+b+zys+hDO+py+M5wQ23VQpeyoTYD
2cVp6yurUyImbg83YPgAfBkHutlGA1ShWdYJNXUckI/bf+HO5wJihJc3PVeES5pT
Bv+9gtp/bcRDqQewN1lsJostAgMBAAGjIDAeMA8GA1UdEwEB/wQFMAMBAf8wCwYD
VR0PBAQDAgIEMA0GCSqGSIb3DQEBCwUAA4IBAQA02LBE4hO3U/YxQNIlkUmqjQnS
VfXk6rxHkAwClukmGtvTocBaIzPCB2ljpFpU0FhXgnWBAwgOY7lt3PIs+WY8Hb1l
DAIKNiZO7X7ahqwP8o/MVg60IR7hGeIN51NxU0XIUWfqPP3civQpi6ZicGCOmM3+
CF0s6k3TthiPCyKmadbS/zsf2EVXsLC9MH/hJznxZaWtxn3m0FB288QOR/DXWt0L
AReGQk4fuFG7Lx/CU4MSn9ENi3AklWkN7Qrhzn3Q3mjQRpQc7Y4dy+bCjmXSV5e+
7iHuMfoiAZ4ddwD5EHjbRzyuBaR1rzYdl8vmSVoT5S+nwLVVs1gh5coM24bA
-----END CERTIFICATE-----

Save the file and exit

Grant the splinterd group read rights

$ sudo chown root:splinterd /etc/splinter/certs/ca.pem

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
```

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