About Us Blog
Submit a request
How can we help?
  1. Engine Yard Support
  2. Engine Yard Cloud
  3. Customizations

Obtain and Install SSL Certificates for Applications

Avatar AI Integration User
Follow

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.

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

Note: There is a limit of 20 SSL certificates per region, per account. If you need more than this, contact Engine Yard Support.

Error when Adding SSL Certificates

If you encounter an error message while adding the ELB SSL certificate, it is likely due to the key not using an encoding that is accepted by AWS. You can re-encode the key using the following command (run from any MacOS/Linux/Unix/BSD machine):

openssl rsa -in sslcert.key -out sslcert.new

After you have run this command, you can verify that the new key is compatible with the existing key and certificate file by running the following command over the three files and verifying the modulus is identical:

deploy$ openssl rsa -text -noout -modulus -in sslcert.key | grep Modulus
 Modulus=C0B5265F2DC6147476F1791C81...AE1A71293E64641471F9B1E4A6F
 deploy$ openssl rsa -text -noout -modulus -in sslcert.new | grep Modulus
 Modulus=C0B5265F2DC6147476F1791C81...AE1A71293E64641471F9B1E4A6F
 deploy$ openssl x509 -text -noout -modulus -in sslcert.crt | grep Modulus
 Modulus=C0B5265F2DC6147476F1791C81...AE1A71293E64641471F9B1E4A6F

During one rewrite, we found the original key was 1705 bytes long and the rewrite was 1679 bytes long. The difference came from the hex code, not just spacing or EOL's.

After the rewrite, the certificate was accepted (using the sslcert.new) by Amazon.

Prerequisite: A chosen SSL-certificate vendor

The workflow described on this page assumes that you have chosen a vendor to host your SSL certificate.

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 -nodes -sha256 -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 -nodes -sha256 -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.

Symptom Solution
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.

Was this article helpful? 0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Article is closed for comments.