Certificate Essentials

An X.509 security certificate (also called an "SSL Certificate") needs to be added so Swarm can be trusted for a secure connection if the Swarm site collects or transmits personally identifiable information or otherwise needs to protect the traffic. TLS (Transport Layer Security ) or SSL (Secure Sockets Layer) security is made up of two parts:

• Encryption - data is made unreadable (using an encryption key) and then sent over an HTTPS connection (SSL). A client can read it using the needed key.

• Identification - transmission is certified (with a security certificate) as coming from the authentic (trusted) site.

There are two options for certificates:

• Pay a trusted CA (Certificate Authority, such as Verisign) to approve (sign) a certificate. This is needed for e-commerce.

• Create a self-signed certificate. 

Both certificate types encrypt data to create a secure website, third parties cannot read.

Making a Self-Signed SSL Certificate

There are many ways and tools for creating trusted certificates. Here is one way for making a self-signed certificate to add to a proxy for use in front of a Swarm cluster:

1. Set up a secure (root-only access) directory for holding the private key and certificate files.

2. Generate a unique private key (KEY). 

   $ openssl genrsa -out mydomain.key 2048

   File contents start with: -----BEGIN RSA PRIVATE KEY-----

3. Generate a Certificate Signing Request (CSR).

   $ openssl req -new -key mydomain.key -out mydomain.csr

   File contents start with: -----BEGIN CERTIFICATE REQUEST-----

4. Create a self-signed certificate (CRT), filling out the openssl prompts appropriately (most importantly, the Common Name, which may be a domain name or public IP address).

   $ openssl x509 -req -days 365 -in mydomain.csr -signkey mydomain.key -out mydomain.crt

   File contents start with: -----BEGIN CERTIFICATE-----

5. Concatenate the .crt and .key files (in that order) into a mydomain.pem file.

PEM file gains multiple sections: -----BEGIN CERTIFICATE----- and  -----BEGIN RSA PRIVATE KEY-----
Repeat this step to create another .pem file if a wildcard cert was created.

6. Specify the PEM in the configuration file of the proxy, such as HAProxy.

Locate: bind 0.0.0.0:443 ssl crt /etc/pki/tls/certs/selfsignedcert.pem

Update to: bind 0.0.0.0:443 ssl crt /etc/pki/tls/certs/mydomain.pem crt /etc/pki/tls/certs/mydomain-wildcard.pem

7. Restart the proxy.

Uploading Certificates into Swarm

The trusted certificate (public key) needs to be uploaded to Swarm, which is performed by inserting it into Swarm's settings to protect Swarm traffic over untrusted networks. The startup.certificates setting holds all certificates, formatted as a single line.

Platform Only: Upload a certificate directly to the Cluster Settings page of the Swarm UI if running Platform Server 10.0 or higher. The UI handles the conversion of the certificate file to the single-line format required by Swarm. (v2.1)

No Platform: Certificates need to be prepared and uploaded by hand if not using Platform Server. Activating the certificate requires a reboot because it requires editing of the configuration file.

1. Modify PEM certificate(s) so the key is a single line, with all carriage returns replaced with the newline character: \n.
   The following awk command converts a PEM file into the needed string:

   awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' mydomain.pem

2. Edit the Swarm configuration file (node.cfg, cluster.cfg).

3. Insert the Certificates setting at the end of the file:

   [startup] certificates=

4. Directly after the equal sign, paste in the single-line string (shown here abridged), which contains all needed newline characters (\n):

   [startup] certificates=----BEGIN CERTIFICATE----- {snip} ----END CERTIFICATE-----

5. Reboot the node. The value provided may not be a valid x.509 public certificate if Swarm does not boot, so check the formatting.

Swarm appends the key value to /etc/ssl/certs/ca-certificates.crt when it reboots.