Knowledge Base/Engine Yard Cloud Documentation/Customize

Obtain and Install SSL Certificates for Applications

Engine Yard
posted this on February 16, 2012 10:03 AM

Updated: September 10th, 2013

This page describes how to obtain an SSL certificate from a third-party vendor and how to install the SSL certificate on an Engine Yard Cloud environment. The process is:

This page also describes how to install a self-signed certificate. A self-signed certificate is a good choice for a staging or development environment where you want to test SSL features, but aren't ready to purchase an SSL certificate.

Additional topics on this page are:

Types of SSL certificates

Engine Yard supports single-domain and wildcard-domain certificates. Get a single-domain certificate if you anticipate having one application running on one domain address. If you use sub-domains, then you'll need a wildcard-domain certificate.

Important! Engine Yard does not support multiple-domain certificates.

SSL certificate type              Example
Single domain https://www.mydomain.com

Wildcard domain [*.mydomain.com]
(A single domain, with subdomains.)
Note: Not all vendors include the root domain (e.g. mydomain.com) in the wildcard-domain certificate.                 

https://www.mydomain.com
https://mydomain.com
https://app.mydomain.com
https://help.mydomain.com
Multiple domain,
also called UCC (Unified Communications Certificate)
https://www.mydomain.com
https://www.myotherdomain.com                                                                  
https://www.yourdomain.com
https://app.mydomain.com

Prerequisite: A chosen SSL-certificate vendor

The workflow described on this page assumes that you have chosen a vendor to host your SSL certificate. If you haven't yet chosen a vendor, consider reviewing this Wikipedia article comparing SSL certificates.

Here are some vendors who have hosted SSL certificates deployed on Engine Yard Cloud:

Create the key file and the signing request file needed by the vendor

To create the key file and signing request file, follow one of these procedures:

Important! The key file cannot have a passphrase associated with it. If you have already generated a key file with a passphrase, see Removing a passphrase from a key file below.

For a single-domain certificate: To generate the key file and the signing request file needed by the vendor

  1. Open a UNIX shell, for example, by SSHing into one of your Engine Yard Cloud instances.

  2. Generate a key file. Type:

     openssl genrsa -out mydomain.com.key 2048 
    You get a response like this:
    Generating RSA private key, 2048 bit long modulus ...+++
    ...........................................................................................................+++
    e is 65537 (0x10001)

    This creates a key file (mydomain.com.key) without a passphrase.

  3. Generate a signing request file.

    a. Type:

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

    b. Important! Make sure to enter your domain name for the Common Name. For example, mydomain.com.

  4. Confirm that you have two files in the current directory:

     * `mydomain.com.key` - the key file 
    * `mydomain.com.csr` - the certificate signing request

For a wildcard-domain certificate: To generate the key file and the signing request file needed by the vendor

Engine Yard convention for wildcard domains is to prefix the key file name with an underscore.

  1. Generate a key file. Type:

     openssl genrsa -out _.mydomain.com.key 2048 
    You get a response like this:
    Generating RSA private key, 2048 bit long modulus
    ...+++
    ...........................................................................................................+++
    e is 65537 (0x10001)

    This creates a key file (_.mydomain.com.key) without a passphrase.

  2. Generate a signing request file.

    a. Type:

     openssl req -new -key _.mydomain.com.key -out _.mydomain.com.csr 

    b. Make sure to enter your domain name (e.g. *.mydomain.com) for the Common Name.

  3. Confirm that you have two files in the current directory:

    • _.mydomain.com.key - the key file
    • _.mydomain.com.csr - the certificate signing request

Purchase the SSL certificate from chosen vendor

Now that you have the key file and the certificate signing request file, you can purchase your SSL certificate.

To purchase an SSL certificate

  1. Follow the instructions provided by your chosen vendor. (See Prerequisite above for a list of vendors.)

  2. Consider these tips:

    • Always use a plain text editor like Notepad on Windows or equivalent on Mac or Linux to copy and paste the contents of the key file and the certificate signing request files into the form fields.
    • If Nginx is not available as a server type, choose Apache.
    • Make sure to get a CRT file from the vendor.
    • If you are offered a "certificate chain file," make sure to get that too. (The certificate chain file is sometimes referred to as an intermediate certificate or key.)

Install an SSL certificate in your Engine Yard account

To add an SSL certificate to your Engine Yard account, you need your key file, the CRT file from your vendor, and if your vendor provided one, the certificate chain file.

Note: If you are testing the SSL features in a development or staging environment, see Install a self-signed certificate. If your key file contains a passphrase, see Remove a passphrase from a key file.

To install an SSL certificate in your Engine Yard account

  1. In your Dashboard, select SSL Certificates from the Tools menu.
    The SSL Certificates page appears.

  2. Click Add SSL Certificate.
    The Create New SSL Certificate page appears.

    create_new_ssl.png

  3. If you have access to more than one Engine Yard account, select an account.

  4. Enter a name in the SSL Certificate Name field.

  5. Click Upload SSL Certificate.

  6. In the SSL Certificate text box, paste the contents of the CRT file.

    The SSL certificate must be in the pem format. If your vendor did not provide it in the pem format, use a conversion tool such as SSL Shopper to convert the SSL certificate.

  7. In the SSL Certificate Key text box, paste the SSL Certificate Key.

  8. If you have a certificate chain file, paste it into the SSL Certificate Chain field.

  9. Click Add Certificates.

Apply the certificate to an application in an environment

After you've configured your SSL Certificate, tell Engine Yard Cloud which environment to use it in.

To apply an SSL certificate to an environment

  1. In your Dashboard, click the application environment that you want to add the certificate to.

  2. Click Assign SSL Certificate to app_name.

  3. From the SSL Certificate drop-down, select the certificate.

    ssl-pane-on-environment-page.png

  4. Click Update SSL Settings.

    Each time you build an application instance for this environment, the certificate is added.

  5. Deploy the application with the SSL certificate: Click Apply.

Verify your SSL certificate

After deploying your application, Engine Yard recommends that you verify your SSL certificate using a site like SSL Shopper.

To verify your SSL certificate

  1. Navigate to an SSL certificate checking site such as SSL Shopper.

  2. Enter your application URL.
    The site checks your certificate and all chain files involved.

Install a self-signed certificate

Use a self-signed certificate when you want to test out SSL features in a development or staging environment.

For general information about self-signed certificates, see this article about self-signed certificates in Wikipedia.

To install a self-signed certificate

  1. In your Dashboard, select SSL Certificates from the Tools menu.
    The SSL Certificates page appears.

  2. Click Add SSL Certificate.
    The Create New SSL Certificate page appears.

  3. If you have access to more than one Engine Yard account, select an account.

  4. Enter your domain name in the SSL Certificate Name field.
    For example, staging.mydomain.com

  5. Click Generate Self-Signed SSL Certificate.

  6. Click Add Certificates.

  7. Follow the steps in Apply the certificate to an application in an environment to add the certificate to an environment.

Remove a passphrase from a key file

If your key file contains a passphrase, you need to remove it before entering the key file on the SSL Certificate page.

To remove a passphrase from a key file

  1. Locate your key file and look at it to see if it contains a passphrase.

     head mydomain.com.key 
    The key file contains a passphrase if it begins with text like this (with Proc-Type: and DEK-Info:):
    -----BEGIN RSA PRIVATE KEY----- 
    Proc-Type: 4,ENCRYPTED
    DEK-Info: DES-EDE3-CBC,91B305001070B5FD

    4/3Oaf8n4XyhUG6Q07/HWuqEkCcXujrJ+dJXgzPAleuKKjxOtN7LHZTvGlXQge/V
  2. If the key file contains a passphrase, remove it with these commands:

    cp mydomain.com.key temp.key 
    openssl rsa -in temp.key -out mydomain.com.key
  3. Enter the original key's passphrase when prompted.

Renew an SSL Certificate

If your SSL certificate expires, you will need to renew it.

To renew an SSL certificate

  1. Generate a new CSR.
  2. Send the new CSR to your certificate vendor.

    Your vendor gives you the new certificate.

  3. Install the new certificate in your Engine Yard account using the instructions in the Install an SSL certificate in your Engine Yard account section of this document.
  4. Apply the certificate to your applications using the instructions in the Apply the certificate to an application in an environment section of this document.

Troubleshooting

This table contains troubleshooting tips.

SymptomSolution
I applied an SSL certificate and clicking Add Certificates throws no errors, *however* the certificate does not appear installed (or the old certificate is still in place) and Nginx is not restarting. Ensure that your key file does not use a passphrase; see How to remove a passphrase from a key file). Then you can paste the key file into the SSL Certificate Key text box; see Install an SSL certificate in your Engine Yard account.
Nginx complains about the private key file. The first line of the private key file ensures that the private key is not actually a CSR. It should contain:
-----BEGIN RSA PRIVATE KEY-----

If you have feedback or questions about this page, add a comment below. If you need help, submit a ticket with Engine Yard Support.

 

Comments

User photo
Nic Rosental
FPCU2

It's not clear at all what should be done with the certificate from the vendor and the key creation, etc. That may because of my lack of experience, but a bit more clarification would go a long way.

December 30, 2012 04:43 PM
User photo
Keri Meredith
Engine Yard Inc.

Hi Nic, We've made some improvements to this article based on customer feedback. If you have specific areas that you believe we still need to address, please add another comment here. Thanks! kjm

June 25, 2013 01:47 PM
User photo
Michael O'Boyle
ProvaSystems

After installing a certificate, does the application respond on http port 80 and on https port 443 or just the latter. My hope is that it supports both simultaneously. Are steps beyond those outlined above required to make it respond on both ports?

Thanks!

August 23, 2013 12:09 PM
User photo
James Paterni
Engine Yard Inc.

Michael,

 

Your application master will listen on both ports 80 and 443.  You should not require any further action to make your application available on both ports.

 

Thank you,

 

James Paterni

August 23, 2013 12:19 PM
User photo
Jay Scott
ArnoldClark

For a wildcard domain you have said the following: 

b. Make sure to enter your domain name (e.g. mydomain.com) for the Common Name.

Should that not be *.mydomain.com ? 

September 04, 2013 03:30 AM
User photo
Diana Lam
Engine Yard Inc.

Hi Jay. You're correct, it should be *.mydomain.com. I will update the doc.

Thank you,

-diana

September 10, 2013 11:59 AM
User photo
Andrew Rogoff
ResourceGuru

We have a Thawte wildcard certificate that covers all subdomains EXCEPT the root. Is it now possible to install multiple certificates on EY? One wildcard and another to secure the root?

January 30, 2014 02:57 AM
User photo
Andrew Rogoff
ResourceGuru

We are solving our problem by switching to a certificate from RapidSSL which covers both *.example.com and example.com. I have no idea why Thawte couldn't offer that.

February 07, 2014 08:41 AM