Using the Pivotal SSL Service

Page last updated:

This topic contains instructions for using the Pivotal Secure Sockets Layer (SSL) Service.

Updating a Certificate

Note: If you update a certificate in an existing instance of the Pivotal SSL Service, you must include all intermediate chain certificates in the correct order, even if they are not changing, then proceed to the Access the Dashboard step in this topic. Refer to the Concatenating Certificates section of this topic for instructions about combining chain files.

Installing a Certificate

Step 1: Obtain a Certificate and Prepare for Upload

The Pivotal SSL Service does not provide certificates. Obtain an SSL certificate issued by a known Certificate Authority (CA) vendor. The SSL Service supports both wildcard and domain-specific certificates.

Note: The Pivotal SSL Service requires that your certificate uses a minimum of SHA-2 encryption to help ensure security for you and the platform. Most vendors provide this level of encryption by default.

  1. You create a private key during the purchase process. Do not discard or lose this key.
  2. Use the table below to determine what preparations to take, depending on what your CA vendor provides.

    Vendor-provided Files Preparation
    A single .crt or .pem file containing the entire chain of trust

    OR

    An email containing the plain text representation of your certificate and the chain of trust
    No preparation needed. You need this file or text in addition to the private key that you used to create your certificate.
    A single .crt or .pem file containing only your domain certificate

    OR

    An email containing the plain text representation of only your certificate
    Obtain the intermediate chain files for your certificate from your certificate vendor. Combine these chain files with your certificate to create a single file containing the entire chain of trust.
    A .zip file or multiple files containing your domain certificate, and the chain of trust Unzip the files and combine the chain files with your certificate to create a single file containing the entire chain of trust.


    For instructions about combining chain files, see Concatenating Certificates below.

Step 2: Create the Service Instance

You can create the SSL Service instance using either the Cloud Foundry Command Line Interface (cf CLI) or the Apps Manager.

Note: Pivotal recommends that you create a new space for your SSL Service instance. Separating the SSL Service instance from your other apps allows you to control access to your certificates by managing Space Roles in the Apps Manager.

Create with the cf CLI

To create the SSL Service instance using the cf CLI, target the org and space where you want to create your SSL Service instance, then run the cf create-service command.

For example:

$ cf create-service ssl basic ssl-myapp.example.com

Create with Apps Manager

To create the SSL Service instance using the Apps Manager, follow the procedure below:

  1. In a browser, open the App Manager dashboard.
  2. In the Apps Manager dashboard, navigate to the org and space where you want to create your SSL Service.
  3. In the left navigation panel, click Marketplace.
  4. In the Services Marketplace section, click the SSL tile.
  5. Click Select this plan to proceed with the basic plan.
  6. in the Instance Name field, enter a name for your SSL Service instance. For example, ssl-myapp.example.com.
  7. If the space where you intend to create the SSL Service instance is not already selected, select it in the Add to Space dropdown menu.
  8. Click Add.

Step 3: Access the Dashboard

Access from the cf CLI

Follow the steps below to access your Pivotal SSL dashboard from the cf CLI.

  1. Run cf service SSL-SERVICE. Replace SSL-SERVICE with the name of your SSL Service instance.

    For example:

    $ cf service ssl-myapp.example.com
    

  2. Copy the dashboard URL and open it in a browser.

Access from Apps Manager

Follow the steps below to access your Pivotal SSL dashboard from the Apps Manager.

  1. In a browser, open the App Manager dashboard.

  2. Click Manage Service on the service listing.

Appsman manage

Step 4: Upload your Certificate

Complete the following steps in Apps Manager to upload your certificate:

  1. Provide your certificate. If you have a certificate file, which has either a .pem or .crt extension, click Upload .crt or .pem file and select your certificate file. Otherwise, if your certificate is in plain text, click Paste plain text certificate. Copy the plain text certificate into the window and click Save.

    Note: If you upload a new certificate to an existing instance of the Pivotal SSL Service, you must include all intermediate chain certificates in the correct order, even if they are not changing. Refer to the Concatenating Certificates section for instructions about combining chain files.

    Upload cert

  2. Provide your private key. If you have a key file, click Upload .key and select your key file. Otherwise, if your key is in plain text, click Paste plain text key. Copy the plain text key into the window and click Save.

  3. Click Submit. If you see an error message, refer to the Troubleshooting section of this topic.

Step 5: Configure your DNS

When your certificate uploads successfully, the dashboard displays an alias for your SSL Elastic Load Balancer (ELB) and instructions for associating the alias with your website.

Ssl alias

  1. In your DNS, create a CNAME entry for the same domain that your certificate covers. Point the CNAME record to the alias that you are provided. The following is an example from AWS:

    Aws dns cname

  2. Confirm that you have secure traffic by visiting your app’s secure URL and verifying that you see the green lock in your browser.

Concatenate Certificates

If you are using the Linux or OSX Command Line, see this document for instructions about using the cat command.

$ cat example.com.crt mycervendor/CA.crt > example.com-chain.crt

If you are using a GUI text editor on Windows, OSX, or Linux, follow the instructions below:

  1. Open your text editor.
  2. Copy and paste the entire body of both certificates into a single text file in the following order:

    1. The Primary Certificate: YOUR-DOMAIN-NAME.crt
    2. The Intermediate Certificate: YOUR-VENDOR/CA.crt

      Note: You must include the beginning and end tags on each certificate.

  3. Save the combined file as YOUR-DOMAIN-NAME.pem.

The result should be in the following format:

-----BEGIN CERTIFICATE-----
(Your Primary SSL certificate: YOUR-DOMAIN-NAME.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Your Intermediate certificate: YOUR-VENDOR/CA.crt)
-----END CERTIFICATE-----

Dig Tool DNS Verification

For additional verification that you have properly configured your DNS, you can use the Google Dig tool. Enter the domain protected by your app on the Google Apps Toolbox web page.

The following is an example of the answer section in the output:

;; ANSWER SECTION:
<YOUR-APP-DOMAIN>. 300 IN CNAME <YOUR-PIVOTAL-SSL-ALIAS>

Troubleshooting

Consult the following tables to diagnose problems that you might encounter.

Problems Uploading your Certificate

Problem Solution
Invalid Certificate - SHA1 Error Pivotal SSL Service requires that your certificate uses a minimum of SHA-2 encryption. Contact your certificate provider or visit https://shaaaaaaaaaaaaa.com/ for more information.
Provisioning Error - AWS 400 This error is commonly caused by a problem with your certificate, the wrong order or failure to include concatenated certificates, or a certificate/key mismatch. See Step 1: Obtain a Certificate and Prepare for Upload section of this topic for instruction about preparing your certificate and key.
If you continue to see this error during the upload of your certificate, delete your service instance and create a new one. For example:
$ cf delete-service ssl basic ssl-myapp.example.com
This triggers a billing charge, and you will need to contact customer support for a refund. Also, the new or updated DNS name needs time to propagate.

If you continue to have this issue, contact Pivotal Support.

Problems at the Secure URL of your App

Problem Solution
You cannot see anything when visiting your app’s secure URL. Ensure you have configured your DNS correctly. For more information, see Step 5: Configure your DNS.
You see a yellow or orange lock when you visit your app’s secure URL. You are missing the full chain of trust in your certificate. You must provide the full chain of trust by concatenating all of the certificates that you have obtained into a single file. For more information, see Concatenate Certificates below. If you continue to see this issue, contact your certificate provider.
You see a red lock and an SSL warning when you visit your app’s secure URL. Ensure that you have properly created a CNAME entry to your ELB alias in your DNS as described in Step 5: Configure your DNS. You can further verify that you have correctly created a CNAME entry by following the procedure in the Dig Tool DNS Verification.

OR

You might be missing the full chain of trust for your certificate. For instructions about combining your certificates into the full chain of trust, see Concatenate Certificates section of this topic.
Create a pull request or raise an issue on the source for this page in GitHub