Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
256 lines (191 sloc) 12.3 KB
---
title: Using the Pivotal SSL Service
owner: Core Services
---
<strong><%= modified_date %></strong>
This topic contains instructions for using the Pivotal Secure Sockets Layer (SSL) Service.
## <a id='prepare'></a>Updating a Certificate
<p class="note"><strong>Note</strong>: 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 <a href="#access-dashboard">Access the Dashboard</a> step in this topic. Refer to the <a href="#concatenate-certificates">Concatenating Certificates</a> section of this topic for instructions about combining chain files.</p>
## <a id='prepare'></a>Installing a Certificate
### <a id='prepare-step1'></a>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. If you are managing services for a Pivotal-owned site, including on PWS, please request an SSL certificate by emailing [ask@pivotal.io](mailto:ask@pivotal.io). Internal Pivotal projects can also send requests to the `#iops` channel in the [Pivotal Slack](http://pivotal.slack.com) workspace.
The SSL Service supports both wildcard and domain-specific certificates.
<p class='note'><strong>Note</strong>: 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.
</p>
1. You create a private key during the purchase process. Do not discard or lose this key.
1. Use the table below to determine what preparations to take, depending on what your CA vendor provides.
<table border="1" class="nice">
<tr>
<th><strong>Vendor-provided Files</strong></th>
<th><strong>Preparation</strong></th>
</tr>
<tr>
<td>A single <code>.crt</code> or <code>.pem</code> file containing the
entire chain of trust
<br><br>OR<br><br>
An email containing the plain text representation of your certificate
and the chain of trust
</td>
<td>No preparation needed. You need this file or text in addition to
the private key that you used to create your certificate.
</td>
</tr>
<tr>
<td>A single <code>.crt</code> or <code>.pem</code> file containing
only your domain certificate
<br><br>OR<br><br>
An email containing the plain text representation of only your
certificate
</td>
<td>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.
</td>
</tr>
<tr>
<td>A <code>.zip</code> file or multiple files containing your domain
certificate, and the chain of trust
</td>
<td>Unzip the files and combine the chain files with your certificate
to create a single file containing the entire chain of trust.
</td>
</tr>
</table>
<br>
For instructions about combining chain files, see [Concatenating Certificates](#concatenate-certificates) below.
### <a id='create-instance'></a>Step 2: Create the Service Instance
You can create the SSL Service instance using either the [Cloud Foundry Command Line Interface](../cf-cli/index.html) (cf CLI) or the [Apps Manager](../console/index.html).
<p class='note'><strong>Note</strong>: 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 <a href="../concepts/roles.html#roles">Space Roles</a> in the <a href="../console/index.html">Apps Manager</a>.</p>
#### <a id='cli-create'></a>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:
<pre class='terminal'>
$ cf create-service ssl basic ssl-myapp.example.com
</pre>
#### <a id='console-create'></a>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.
1. In the Apps Manager dashboard, navigate to the org and space where you
want to create your SSL Service.
1. In the left navigation panel, click **Marketplace**.
1. In the **Services Marketplace** section, click the **SSL** tile.
1. Click **Select this plan** to proceed with the basic plan.
1. in the **Instance Name** field, enter a name for your SSL Service instance.
For example, `ssl-myapp.example.com`.
1. 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.
1. Click **Add**.
### <a id='access-dashboard'></a>Step 3: Access the Dashboard
#### <a id='cli-access'></a>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.
<br><br>
For example:
<pre class='terminal'>
$ cf service ssl-myapp.example.com
</pre>
1. Copy the dashboard URL and open it in a browser.
#### <a id='consol-access'></a>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.
1. Click **Manage Service** on the service listing.
<%= image_tag('ssl/appsman-manage.png') %>
### <a id='upload-certificate'></a>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**.
<p class="note"><strong>Note</strong>: 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 <a href="#concatenate-certificates">Concatenating Certificates</a> section for instructions about combining chain files.</p>
<%= image_tag('ssl/upload-cert.png') %>
1. 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**.
1. Click **Submit**. If you see an error message, refer to the [Troubleshooting](#troubleshooting) section of this topic.
### <a id='config-dns'></a>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.
<%= image_tag('ssl/ssl-alias.png') %>
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:
<%= image_tag('ssl/aws-dns-cname.png') %>
1. Confirm that you have secure traffic by visiting your app's secure URL and verifying that you see the green lock in your browser.
## <a id='concatenate-certificates'></a>Concatenate Certificates
If you are using the Linux or OSX Command Line, see [this document](https://support.comodo.com/index.php?/Default/Knowledgebase/Article/View/789/37/cert-installation-nginx) for instructions about using the `cat` command.
<pre class='terminal'>
$ cat example.com.crt mycervendor/CA.crt > example.com-chain.crt
</pre>
If you are using a GUI text editor on Windows, OSX, or Linux, follow the
instructions below:
1. Open your text editor.
1. 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`
1. The Intermediate Certificate: `YOUR-VENDOR/CA.crt`
<p class='note'><strong>Note</strong>: You must include the beginning and end tags on each certificate.</p>
1. 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-----
```
## <a id='dig-tool'></a>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](https://toolbox.googleapps.com/apps/dig/) web page.
The following is an example of the answer section in the output:
<pre>
;; ANSWER SECTION:
&lt;YOUR-APP-DOMAIN&gt;. 300 IN CNAME &lt;YOUR-PIVOTAL-SSL-ALIAS&gt;
</pre>
## <a id='websocket'></a>WebSocket Support
Since January 2018, the Pivotal SSL Service supports WebSocket Secure connections (<code>wss:</code>) over port 4443. The full wss URL is <code>wss://YOUR-APP-DOMAIN:4443/YOUR-ENDPOINT</code> .
## <a id='troubleshooting'></a>Troubleshooting
Consult the following tables to diagnose problems that you might encounter.
### Problems Uploading your Certificate
<table border="1" class="nice">
<tr>
<th><strong>Problem</th>
<th><strong>Solution</th>
</tr>
<tr>
<td>Invalid Certificate - SHA1 Error</td>
<td>Pivotal SSL Service requires that your certificate uses a minimum of SHA-2 encryption. Contact your certificate provider or visit <a href="https://shaaaaaaaaaaaaa.com/">https://shaaaaaaaaaaaaa.com/</a> for more information.</td>
</tr>
<tr>
<td>Provisioning Error - AWS 400</td>
<td>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 <a href="#prepare">Step 1: Obtain a Certificate and Prepare for Upload</a> section of this topic for instruction about preparing your certificate and key. <br> If you continue to see this error during the upload of your certificate, delete your service instance and create a new one.
For example:
<pre class='terminal'>
$ cf delete-service ssl basic ssl-myapp.example.com
</pre>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. <br><br>
If you continue to have this issue, contact <a href="mailto:support@run.pivotal.io">Pivotal Support</a>.</td>
</tr>
</table>
### Problems at the Secure URL of your App
<table border="1" class="nice">
<tr>
<th><strong>Problem</strong></th>
<th><strong>Solution</strong></th>
</tr>
<tr>
<td>You cannot see anything when visiting your app's secure
URL.
</td>
<td>Ensure you have configured your DNS correctly. For more information, see <a href='#config-dns'>Step 5: Configure your DNS</a>.
</td>
</tr>
<tr>
<td>You see a yellow or orange lock when you visit your app's
secure URL.
</td>
<td>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 <a href='#concatenate-certificates'>Concatenate Certificates</a> below. If you continue to see this issue, contact your certificate provider.
</td>
</tr>
<tr>
<td>You see a red lock and an SSL warning when you visit your app's secure URL.
</td>
<td>Ensure that you have properly created a CNAME entry to your ELB alias in your DNS as described in <a href='#config-dns'>Step 5: Configure your DNS</a>. You can further verify that you have correctly created a CNAME entry by following the procedure in the <a href='#dig-tool'>Dig Tool DNS Verification</a>.
<br><br>OR<br><br>
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 <a href='#concatenate-certificates'>Concatenate Certificates</a> section of this topic.
</td>
</tr>
</table>