Generating and Applying SSL Certificates¶
In most cases, a variety of users and applications will be accessing the SwiftStack managed cluster, so it is a best practice to always use SSL/TLS certificates to protect data and authentication tokens. We recommend using commercially signed certificates, as those typically don’t require that certificates are manually installed on clients connecting to the storage system. If you don’t use HTTPS on your cluster, all the data sent to and from the cluster is readable in plain text to anyone with access to the networks between the clients and the cluster. This is of course especially true and sensitive if your cluster is exposed to the Internet. If it is open to the Internet, then it’s irresponsible to leave a cluster operating on port 80 (HTTP) instead of 443 (HTTPS).
Note
If you are already quite familiar with certificates, skip to step 5 of this tutorial to get to the gist of assembling your PEM certificate for a SwiftStack cluster.
Overview¶
Getting a certificate generated can be a daunting task, especially if it’s something you don’t do on a daily basis. Most instructions around the web, although plentiful, are written for different purposes and using different examples that don’t always match your situation. At first glance it appears to be a straightforward process:
- Create a private key (to be kept secret and securely stored).
- Generate a Certificate Signing Request (CSR, .csr).
- Use your CSR to buy a commercially signed certificate.
- Receive your server cert and intermediate certs from the certificate issuer.
- Assemble and apply the certs to your cluster.
As it turns out, the first four steps are relatively straightforward. The last step, however, can be significantly harder to figure out because many times you don’t always get all the certs you might need from your certificate issuer and specific instructions for how to apply the certs to a specific product, like SwiftStack.
To make your journey into properly securing your SwiftStack managed cluster a bit easier, this document will outline every step of the process, including command line examples where necessary.
Assume that we’ve built a cluster and the cluster API hostname is
swift.example.com. Since your cluster won’t use that API hostname, substitute your
cluster's Fully Qualified Domain Name (FQDN), wherever you see swift.example.com.
1. Create a private key¶
You need a private key before you get started.
Important
Once generated, the private key is the secret that keeps everything secure. If you lose the private key or its security is compromised, you will have to regenerate all your certificates that rely on that key. So, make sure you:
- Store the key in a place where others can’t easily get to it.
- Have a backup of the key somewhere, in case the machine on which you store it dies.
- Put the proper permissions on the key file. (Typically owned by your user with 600 permissions.)
Alright, let’s generate the key on a secure machine that only limited people have access to:
$ openssl genrsa -des3 -out swift_example_com.key 2048
It will prompt you to provide a passphrase and verify it:
Generating RSA private key, 2048 bit long modulus
...
Enter pass phrase for swift_example_com.key:
Verifying - Enter pass phrase for swift_example_com.key:
This will generate a 2048-bit key, which is the smallest key allowed by certificate authorities. So, don’t use a smaller bit-count for your key.
Important
Make sure you store the key’s passphrase in a good place. Every time you need to use and unlock it, you will need the key passphrase. If you forget it, it’s the same as having lost the key, and you’ll need to regenerate all your certs.
One problem with having a passphrase on the key is that it would be needed every
time you restart a server. Clearly, that’s not very convenient or practical.
Therefore, we should ensure that we have a copy of the key that doesn’t
require a passphrase. This is the same copy of the key that we will use later on.
To remove the passphrase on the key, first rename the key with a passphrase
to swift_example_com.key.orig:
$ mv swift_example_com.key swift_example_com.key.orig
Then use the key to remove the passphrase:
$ openssl rsa -in swift_example_com.key.orig -out swift_example_com.key
If you list the files in your directory now, you should have:
$ ls -la
-rw-rw-r-- 1 user user 1675 Dec 24 15:34 swift_example_com.key
-rw-rw-r-- 1 user user 1743 Dec 24 15:33 swift_example_com.key.orig
2. Generate a Certificate Signing Request (CSR, .csr)¶
Now that the key has been generated, it’s time to create the CSR. You will provide the CSR to your certificate signing provider in order for them to generate your certificate. Use the following commands to create the CSR:
$ openssl req -new -key swift_example_com.key -out swift_example_com.csr
During CSR generation, you will be prompted to provide several pieces of information. It should look something like:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:California
Locality Name (eg, city) []:San Francisco
Organization Name (eg, company) [Internet Widgits Pty Ltd]:SwiftExperts
Organizational Unit Name (eg, section) []:IT
Common Name (e.g. server FQDN or YOUR name) []:swift.example.com
Email Address []:it@example.com
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
For the last ‘extra’ attributes, you don’t have to put in a password.
You should now have the following:
$ ls -la
-rw-rw-r-- 1 user user 1074 Dec 24 15:36 swift_example_com.csr
-rw-rw-r-- 1 user user 1675 Dec 24 15:34 swift_example_com.key
-rw-rw-r-- 1 user user 1743 Dec 24 15:33 swift_example_com.key.orig
3. Use your CSR to buy a commercially signed certificate¶
Pick your certificate signing provider. Chances are you already have one, so inquire within your organization about which one it is. (You probably don’t want to have multiple cert providers.) The cert provider can be a commercial Certificate Authority (CA) or some firm selling certificates based on a relationship they have with a commercial CA.
Caution
A CA can also be run by your own company/organization, which would then act as your certificate provider. This is less common, however, and typically requires that every machine that will interact with your cluster needs to have your internal CA’s certificates installed manually. Therefore, using internal CA’s is many times not much different than using locally generated self-signed certificates. It is also worth noting that using an internal CA is in most cases not a viable solution if a cluster will be available on the Internet. Consequently, unless you want to take up a job as CA maintainer, or you already have an entire team supporting you in that effort, AND the cluster will never be Internet-facing, do yourself a favor and go with a commercial certificate vendor.
OK, so with all those caveats, log in to your chosen certificate vendor and go to the ‘Purchase SSL certificates’ section. Pick the certificate you want/need. Once you’ve done that, you’ll be asked to provide:
- your CSR
- number of years the cert should be valid for
- the name of the certificate
- name and contact info for your organization …
- a credit card number
Normally you can just copy and paste the contents of the CSR file from the
server into a provided field. For the name of the certificate, in our example,
that would be swift.example.com. If you’re generating and buying a so-called
wildcard certificate, instead of swift.example.com, you’d use *.example.com.
Lastly, provide your company information, as well as an email address to which
the server certificate will be sent. Make sure you should pick an email address
that you have access to. It might be a good idea to have the email associated
with the cert be something like webmaster@, it@, or sysadmin@, whatever is best
for your organization.
4. Receive your server cert and intermediate certs from the certificate issuer¶
Once step 3, above, has been completed, getting the certificates is usually just
a matter of minutes, sometimes hours. You will normally get a zip file
containing a bunch of certificates in PEM (.pem, .crt) format, including your
server certificate. The server certificate is commonly named based on the
FQDN, as defined when generating the key. For instance, using our example, it
might be named something along the lines of swift_example_com.crt. The rest of
the certs provided are typically intermediate certificates. That is,
certificates that are required to link the server cert to the ultimate signing
authority, the CA. The number of intermediate certificates can vary, but
there’s commonly at least one, sometimes more.
One thing that many times isn’t obvious is the order of the intermediate certs. However, the order in which certificates are chained is critical for your server cert to be identified properly. Unfortunately, the order of the cert chain is also not straight forward, as different servers, like Apache, Nginx, etc., tend to want the order in their specific way, which isn’t always the same as that of other servers.
In the next section, we will assemble the certs for a SwiftStack cluster.
5. Assemble and apply the certs to your cluster.¶
What certs need to be in the ‘ultimate’ cert can sometimes be a trial and error exercise. This outlines how certs need to be assembled for a SwiftStack cluster with the API hostname of swift.example.com. What you will need is:
- swift_example_com.crt
- intermediate_1.crt
- intermediate_2.crt (This isn’t always required)
Now, go ahead and put them all together in the right order:
$ cat swift_example_com.crt intermediate_1.crt intermediate_2.crt > swift_example_com_chain.pem
Of course, if you are only provided one intermediate cert, you don’t need to include intermediate_2.crt above.
Note
- If using a commercial cert, as assumed above, you don’t need to include the CA root cert in your PEM file.
- If using an internal CA, you will most likely also need to include your internal CA root cert in the .pem file, thus:
cat server.crt intermediate.crt ca-root.crt > cert-chain.pem.
When using SwiftStack, it’s important to use the .pem file extension for the cert. Usually, the contents of a .crt and .pem are in PEM format, but the SwiftStack Controller expects a .pem file extension.
At this point you should have:
- swift_example_com_chain.pem
- swift_example_com.key
This is all you need. Now go to the SwiftStack Controller, find your cluster, and go to the ’Configure > Network Configuration’ section. Go ahead and make the following changes:
- Will your external clients need to connect with HTTPS? and select Yes.
- Most operators select to terminate SSL on the proxy servers. If that’s what you want to do, in the How will you terminate SSL? section, select SSL should be terminated on the Swift node. (Terminating SSL on the proxy servers is usually a good approach, as it distributes SSL termination across all your proxy machines, and as such doesn’t create a single point of failure. If you prefer, you can terminate SSL on your load balancer in front of the cluster. However, SwiftStack can’t test every load balancer configuration there is. Still, your load balancer probably comes with instructions for how to do it, if that’s what you want to do.)
- Lower down on the screen you should have two fields: SSL Certificate and SSL Private Key. Use the Choose File upload buttons to upload your .pem and .key files.
- Lastly, go ahead and Submit Changes at the bottom of the page, and when that’s done, on the Deploy page, do a Deploy Config to Swift Nodes.
