Network/TLS

From NURDspace

TLS

We run a functional autosigning CA server based on the cloudflare ssl toolkit, and all managed machines get a certificate which can be used for both client and server authentication. All managed machines are also able to verify certificates belonging to the NURDspace CA, and have an unique diffie-hellman key to be used for optimum forward secrecy. You can use the generated certificates to secure applications you deploy on the NURDspace infra.

Certificate details

We generate ECDSA certificates with a 256-bit key and a lifetime of 3 months. The SAN for this certificate by default contains the hostname, the fqdn, the primary ipv4 address, and if configured, the ipv6 address. It is possible to configure additional SANs for a server.

Server

On nurdservices we run the multirootca process which autosigns certificates given the correct pre-shared key. This service is running as user cfssl and is managed by systemd. It does not need any further configuration apart from the configuration it is currently using. This service is running on the following location:

https://pki.lan.nurd.space:8888

Client

During bootstrapping of a managed machine, ansible fetches the CA certificate and installs this into the system certificate store. Furthermore, a client configuration for cfssl together with certificate configuration will be installed, and a certificate will be fetched from the pki server. This certificate can be used by all applications that are part of the tls group. If you ever need to update the certificates and secrets for a machine you can always run the fetch_certs.sh script. This will not perform any certificate update until the certificate is two weeks away from expiry. You can override this behaviour by specifying the force flag.

Usage

File locations

Path Description
/etc/tls/dhparams.pem Unique diffie-hellman parameters
/etc/tls/ca.pem NURDspace root ca certificate
/etc/tls/host/host.pem Host certificate in pem format
/etc/tls/host/host-key.pem Host key in pem format

Using the certificate

In order to use the certificate for your application, there are a couple of steps required:

  1. Add additional SANs if required
  2. Add the user you run your application under to the tls group.
  3. Add the certificate configuration
  4. Add a restart cronjob

Adding a restart cronjob

Since the certificate will be renewed approx every 3 months, you need to add a cronjob that will restart your service whenever the certificate is changed. To make this job easier, a shellscript is available called cert-updated, which will return a 0 exit code if the certificate has been modified today. This allows you to add a cronjob like the following:

23 9 * * * cert-updated && systemctl restart servicename

Adding additional SANs

You can add additional SANs to a machine using the tls_alternative_names ansible variable. Start off by editing host_vars/yourmachine.yaml, and add a block like below:

tls_alternative_names:
  - "application1.vm.nurd.space"
  - "application2.vm.nurd.space"

Apply this change by running ansible as follows (where yourmachine is the fqdn for your system):

$ cd ansible
$ ./scripts/ansible-playbook manage.yml -t tls -l yourmachine -e force_cert_update=true

Once this step is done you can use the generated certificate for the additional SANs you defined.

Grabbing a copy of the root CA

You can add the NURDspace root CA to your certificate store. By doing this, you will be able to validate all certificates that have been signed by this CA. Copy and paste the following certificate into a file:

-----BEGIN CERTIFICATE-----
MIICTTCCAfSgAwIBAgIUEC1jd7tBK15aZaSF9m1psXQn7KEwCgYIKoZIzj0EAwIw
gYQxGDAWBgNVBAYTD1RoZSBOZXRoZXJsYW5kczETMBEGA1UECBMKR2VsZGVybGFu
ZDETMBEGA1UEBxMKV2FnZW5pbmdlbjESMBAGA1UEChMJTlVSRHNwYWNlMQ4wDAYD
VQQLEwVJbmZyYTEaMBgGA1UEAxMRTlVSRHNwYWNlIFJvb3QgQ0EwHhcNMjMwNDEx
MTcyNDAwWhcNMjgwNDA5MTcyNDAwWjCBhDEYMBYGA1UEBhMPVGhlIE5ldGhlcmxh
bmRzMRMwEQYDVQQIEwpHZWxkZXJsYW5kMRMwEQYDVQQHEwpXYWdlbmluZ2VuMRIw
EAYDVQQKEwlOVVJEc3BhY2UxDjAMBgNVBAsTBUluZnJhMRowGAYDVQQDExFOVVJE
c3BhY2UgUm9vdCBDQTBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABDtBdfyD4pZT
dX5/rkEszGwRI/0FI3KgcjnTw2x2gJ7vnocZQ6FF2M2GCm20eUp3sLKVkH2cirFe
qsn2CbvvobOjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMBAf8EBTADAQH/MB0G
A1UdDgQWBBRER31083wuoQK2A+n8rp66VaumZTAKBggqhkjOPQQDAgNHADBEAiB8
RNnsWTOYaSr+jHcfo9Z21TIrtrd9pFCsm6gHJ4zR4wIgRYCyPLLINeKZ8IHbFI2M
MHAjsDiACUey6MWHUlH1pHg=
-----END CERTIFICATE-----