SSL Certificates

All of our APIs (as well as web front ends) are served via encrypted HTTPS. Doing so requires obtaining an SSL certificate from a certificate authority or one of its authorized resellers. There are many options for doing so (with varying costs and trust levels), but Vokal maintains a wholesale account through OpenSRS which allows us to purchase certs on a client's behalf from a handful of top providers.

There are some important considerations below, but feel free to skip ahead to generating a CSR, ordering a wildcard cert from OpenSRS, or uploading a cert for use in CloudFront.

Once your SSL cert is installed on a staging server and it has a proper domain name (e.g. staging.example.com), you can verify that the server is immune to common exploits by checking the domain with Qualys SSL Labs SSL Server Test. Ask your PO/AM if you should save a copy of the generated report to share with the client.

Some important considerations

When should I get a cert?

As soon as possible after kicking off the project. Ideally it should be mentioned at some point in discovery that the project requires an SSL cert, but be sure to let your PO know about the cert and other prerequisites during your project's first sprint at the latest. If you allow the PO or client to put this off it will almost certainly delay production deployment and cause show-stopping problems when mobile or web clients must switch from HTTP to HTTPS later. Ideally staging should never be deployed without an SSL cert in-hand.

Who should get the cert?

The client may possess sufficient technical knowledge to obtain a cert on their own, but whenever possible we prefer to obtain certs directly on their behalf. Invariably issues arise keeping track of and/or properly securing the private key, generating the certificate signing request (CSR), or properly formatting the cert and/or the intermediate CA certs.

Up-to-date information

Make sure you secure from the client valid and verifiable contact information. If this cannot be verified by the certificate authority, a certificate will not be issued. Furthermore, have the client verify that their business information is properly registered and in good standing with the Secretary of State or other agency. If the certificate authority cannot verify this information, or if a company is listed as "NGS" or "Not Good Standing", a certificate will not be issued. Finally, make sure any domain registration information is up-to-date. Most certificate authorities will send a verification email to the email address listed in a WHOIS record. If that email cannot be verified, a certificate will not be issued. (Sensing a pattern here?)

While there are CAs that will issue certs without verifying this information (e.g. RapidSSL only verifies that the email address in the WHOIS info is controlled by the person requesting the cert via an emailed verification link), Thawte is currently our preferred provider and will check to make sure that requesting organizations are legitimate. Any company we do business with should have these sorts of basic things in order anyway, but problems can be (and have been) revealed when certs aren't requested until the last minute, blocking and delaying production deploys.

Wildcard SSL cert

SSL certificates are pinned to a particular domain. For example, if I want to secure www.example.com, I request a cert for www.example.com. If I want to secure api.example.com, I need to obtain another cert. However, most CAs will issue wildcard certs if you generate a CSR for *.example.com, and that can be used to secure any subdomain (but not sub-subdomains) of example.com. This is much cheaper and much easier to manage than buying a separate cert for each service you plan to run, and is perfectly fine for non-public-facing services.

The client may want to obtain a separate certificate for any public-facing service, such as a website at www.example.com. In particular, they may want to pay extra for an extended validation cert for this purpose. It costs quite a bit more, but particularly if they accept payment or other sensitive private data, an EV cert will turn the location bar in the browser green to indicate that the CA has more thoroughly vetted the company as an added indicator of trust.

Obtaining an SSL cert via OpenSRS

Generate private key and CSR

Use the following command to generate a 2048-bit RSA private key and CSR:

openssl req -out example.com.csr -new -newkey rsa:2048 -nodes -keyout example.com.key

OpenSSL will ask for some information for the CSR; you must fill out the following fields, and hit enter to leave the rest blank:

Two-letter country code (usually US)
State (the full name, not the abbreviation, e.g. Illinois)
Locality Name, i.e. city (e.g. Chicago)
Organization, i.e. official company name (e.g. ExampleBiz LLC; Example, Inc)
Common Name, i.e. domain name (e.g. *.example.com)

You can and should skip the following by hitting enter:

Organizational Unit
Email Address
Challenge password
Optional company name

The contents of example.com.csr is what you will use to request an SSL cert; it should look like:

You can verify the information was entered correctly using:

openssl req -text -noout -verify -in example.com.csr

The ouptut should look something like:

verify OK
Certificate Request:
    Data:
        Version: 0 (0x0)
        Subject: C=US, ST=Illinois, L=Chicago, O=ExampleBiz LLC, CN=*.example.com

    Subject Public Key Info:
    ...

Place an order via OpenSRS

Obtain and secure the username and password for Vokal's OpenSRS account
Go to https://opensrs.com
Click on "Sign In" (in the upper left corner)
Click on the "Sign In" button for "Reseller Control Panel" and sign in
Click on "Trust" in the main navigation
Click the "+" icon to add a new order
Select "Thawte" for supplier and "SSL Web Server Certificate Wildcard" for service and click "Continue"
Choose a one- or two-year period, and leave server and count at the default.
Fill out the organization information with up-to-date client company info.
Fill out Administration with an authorized company contact
Fill out Billing with Austin Sheaffer's contact info
Fill out Technical with your contact info
Paste in the CSR generated above in the CSR box, and click "Save as Draft"
Verify that all the info was entered correctly and click "Add Service". If you make any errors after submitting, you must cancel the order and create a whole new order.

From here, Thawte will verify the client's information. Be sure the client is prepared to respond to emails or phone calls to verify information. You can request help via OpenSRS to find out what, if anything, might be holding up an order. Certs typically take between 2-5 business days to process. The issued cert may be emailed directly to you, but make sure the client contact is prepared to forward to you just in case.

Install the cert on staging

You'll need to copy the cert and private key to your staging server. You can use scp, but some find it easier to ssh into staging, cat the files locally, and paste into a new file created directly on the server using vim. Be sure to set the permissions for these files to 600. You can find more details in our nginx config documentation.

Using an SSL cert with AWS CloudFront

To upload an SSL cert for use with CloudFront, you must install and configure the awscli command line tool and use the following command to upload the cert into the IAM certificate store.

Notes:

The command requires the cert and intermediate CA cert be specified separately (as opposed to combined into the same file).
The server-certificate-name is the name that shows up in the drop down menu in the CloudFront console when you choose "custom SSL".
The path parameter must start with /cloudfront/ and can be anything; it's only used for organizing it internally within the certificate store in IAM.

aws iam upload-server-certificate --server-certificate-name Example_Cert --certificate-body file://example.crt --private-key file://example.key --certificate-chain file://rapidssl-ca.pem --path /cloudfront/example-cert/

Vokal Engineering

Quality, Integrity, and Efficiency.