Using the Pivotal SSL Service
Page last updated:
This topic contains instructions for using the Pivotal Secure Sockets Layer (SSL) Service.
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.
The Pivotal SSL Service does not provide certificates. Obtain an SSL certificate issued by a known Certificate Authority (CA) vendor. If you are managing services for a Pivotal-owned site, including on PWS, please request an SSL certificate by emailing firstname.lastname@example.org. Internal Pivotal projects can also send requests to the
#iops channel in the Pivotal Slack workspace.
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 about 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.
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.
$ cf create-service ssl basic ssl-myapp.example.com
To create the SSL Service instance using the Apps Manager, follow the procedure below:
- In a browser, open the App Manager dashboard.
- In the Apps Manager dashboard, navigate to the org and space where you want to create your SSL Service.
- In the left navigation panel, click Marketplace.
- In the Services Marketplace section, click the SSL tile.
- Click Select this plan to proceed with the basic plan.
- in the Instance Name field, enter a name for your SSL Service instance.
- 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.
Follow the steps below to access your Pivotal SSL dashboard from the cf CLI.
cf service SSL-SERVICE. Replace
SSL-SERVICEwith the name of your SSL Service instance.
$ cf service ssl-myapp.example.com
Copy the dashboard URL and open it in a browser.
Follow the steps below to access your Pivotal SSL dashboard from the Apps Manager.
In a browser, open the App Manager dashboard.
Click Manage Service on the service listing.
Complete the following steps in Apps Manager 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. 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.
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.
Click Submit. If you see an error message, refer to the Troubleshooting section of this topic.
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.
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 about 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 your 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 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-----
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>
Since January 2018, the Pivotal SSL Service supports WebSocket Secure connections (
wss:) over port 4443. The full wss URL is
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 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.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 the Secure URL of your App
|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.
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.