Configure Cargo for SSL/TLS

Introduction

Goal

Configure your local Cargo-based development environment to use SSL/TLS.

Background

A standard implementation project created using the Bloomreach Experience Manager Maven archetype is configured to run in a local Cargo-based development environment. By default, the Tomcat container in this environment is configured to use an unencrypted HTTP connection, which is sufficient for most local development use cases. This page explains how you can configure Cargo to use an encrypted HTTPS connection instead, in case you need to develop or test an SSL/TLS setup locally.

Instructions

Prepare Keystore, Certificate, and Truststore

From within your project's root directory, change to the conf directory:

cd conf

Use the Java keytool command to create a keystore inside the conf directory:

keytool -keystore tomcatkeystore -genkey -alias 127.0.0.1 -keyalg RSA

When answering the questions asked by keytool, make sure to use the name (CN) "127.0.0.1":

Enter keystore password:
Re-enter new password:
What is your first and last name?
  [Unknown]:  127.0.0.1
What is the name of your organizational unit?
  [Unknown]:  Infra
What is the name of your organization?
  [Unknown]:  Bloomreach
What is the name of your City or Locality?
  [Unknown]:  Mountain View
What is the name of your State or Province?
  [Unknown]:  CA
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=127.0.0.1, OU=Infra, O=Hippo, L=Boston, ST=MA, C=US correct?
  [no]:  yes

Enter key password for <127.0.0.1>
        (RETURN if same as keystore password):
Re-enter new password:

There should now be a file called tomcatkeystore in your project's conf directory.

Next, use keytool to export a certificate from the keystore:

keytool -keystore tomcatkeystore -exportcert -alias 127.0.0.1 -file tomcat.cert

Finally, use keytool to create a truststore and import the certificate into it: 

keytool -import -file tomcat.cert -alias 127.0.0.1 -keystore tomcattruststore

When asked to trust the certificate, answer 'yes':

Trust this certificate? [no]:  yes

There should now be a file called tomcattruststore in your project's conf directory.

Configure Cargo Plugin

In your project's root pom.xml, find the cargo.run profile.

Inside the cargo.run profile, find the cargo-maven2-plugin plugin configuration properties.

Add the following plugin configuration properties to plugin/configuration/configuration/properties:

<cargo.servlet.port>8443</cargo.servlet.port>
<cargo.protocol>https</cargo.protocol>
<cargo.tomcat.connector.clientAuth>false</cargo.tomcat.connector.clientAuth>
<cargo.tomcat.connector.sslProtocol>TLS</cargo.tomcat.connector.sslProtocol>
<cargo.tomcat.connector.keystoreFile>${project.basedir}/conf/tomcatkeystore</cargo.tomcat.connector.keystoreFile>
<cargo.tomcat.connector.keystorePass>changeit</cargo.tomcat.connector.keystorePass>
<cargo.tomcat.connector.keyAlias>127.0.0.1</cargo.tomcat.connector.keyAlias>
<cargo.tomcat.httpSecure>true</cargo.tomcat.httpSecure>

Still inside the cargo.run profile, add the following system properties to plugin/configuration/container/systemProperties:

<javax.net.ssl.trustStore>${project.basedir}/conf/tomcattruststore</javax.net.ssl.trustStore>
<javax.net.ssl.trustStorePassword>changeit</javax.net.ssl.trustStorePassword>

Build your project.

Configure the HST

Run your project.

Point your web browser to the console at:

https://127.0.0.1:8443/cms/console/

Login as admin and browse to the node /hst:platform/hst:hosts.

Set the property hst:scheme to https:

/hst:platform/hst:hosts
  - hst:scheme = https

Browse to the node /hst:platform/hst:hosts/dev-localhost.

Set the hst:defaultport property to port 8443:

/hst:platform/hst:hosts/dev-localhost
  - hst:defaultport = 8443

Repeat the previous two steps for the site host configuration at /hst:myproject/hst:hosts/.

Set the property hst:scheme to https:

/hst:myproject/hst:hosts
  - hst:scheme = https

Set the hst:defaultport property to port 8443:

/hst:myproject/hst:hosts/dev-localhost
  - hst:defaultport = 8443

Write your changes to the repository.

Point your browser to the CMS at:

https://localhost:8443/cms/

Verify that the channel manager is working.