Using the Pivotal SSL Service
Page last updated:
This topic contains instructions for using the Pivotal Secure Sockets Layer (SSL) Service.
Note: If you are updating 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 this step. Refer to the Concatenating Certificates section for instructions on combining chain files.
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.
- You create a private key during the purchase process. Do not discard or lose this key.
Use the table below to determine what preparations to take, depending on what your CA vendor provides.
Vendor-provided Files Preparation A single
.pemfile containing the entire chain of trust
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
.pemfile containing only your domain certificate
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
.zipfile 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 on combining chain files, see Concatenating Certificates below.
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 Console.
If you are creating the SSL Service instance using the cf CLI, target the org and space in which you want to create your SSL Service instance and run the
cf create-service command.
$ cf create-service ssl basic ssl-myapp.example.com
If you are creating the SSL Service instance using the Apps Manager Console, follow the procedure below:
- Navigate to the org and space in which you want to create your SSL Service instance in the Apps Manager dashboard.
- Click Marketplace from the left navigation.
- In the Services Marketplace section, click the SSL tile.
- Click Select this plan to proceed with the basic plan.
- Enter a name for your SSL Service instance in the Instance Name field.
- 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.
- Click Add.
To access your Pivotal SSL dashboard from the cf CLI, run the following command:
$ cf service ssl-myapp.example.com
Copy the dashboard URL and open it in a browser.
To access your Pivotal SSL dashboard from Apps Manager, click Manage Service on the service listing.
Complete the following steps in your Apps Manager Console to upload your certificate:
Provide your certificate. If you have a certificate file, which has either a
.crtextension, click Upload .crt or .pem file and select your certificate file. Otherwise, if your certificate is in plain text, click Paste plain text certificate. Paste the plain text certificate into the window and click Save.
Note: If you are uploading 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 on combining chain files.
Provide your private key by clicking Upload .key or Paste plain text key.
Click Submit. If you get an error, see Troubleshooting below.
When your certificate uploads successfully, the dashboard displays an alias for your SSL ELB and instructions for associating the alias with your website.
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:
Confirm that you have secure traffic by visiting your app’s secure URL and verifying that you see the green lock in your browser.
If you are using the Linux or OSX Command Line, see this document for instructions on using the
$ 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:
- Open a text editor.
Copy and paste the entire body of both certificates into a single text file in the following order:
- The Primary Certificate:
- The Intermediate Certificate:
Note: You must include the beginning and end tags on each certificate.
- The Primary Certificate:
Save the combined file as
The result should look like this:
-----BEGIN CERTIFICATE----- (Your Primary SSL certificate: YOUR-DOMAIN-NAME.crt) -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- (Your Intermediate certificate: YOUR-VENDOR/CA.crt) -----END CERTIFICATE-----
For additional verification that your DNS is properly configured, 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>
Consult the following tables to diagnose problems that you might encounter.
Problems Uploading your Certificate
|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 for tips on preparing your certificate and key.
If you continue to have this error during uploading your certificate, delete your service instance and create a new one. For example:
$ cf delete-service ssl basic ssl-myapp.example.comThis 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 your App’s Secure URL
|You cannot see anything when visiting your app’s secure URL.||Ensure that your DNS is configured 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.
You might be missing the full chain of trust for your certificate. For instructions on combining your certificates into the full chain of trust, see Concatenate Certificates below.