Configure Cargo for SSL/TLS

Introduction

Goal

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

Background

A standard Hippo project created using Hippo's 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, should you have this requirement.

Instructions

Prepare Certificate Keystore

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]:  Hippo
What is the name of your City or Locality?
  [Unknown]:  Boston
What is the name of your State or Province?
  [Unknown]:  MA
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.

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:

<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>****************</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, find the container system properties.

Add the following system property:

<javax.net.ssl.trustStore>${project.basedir}/conf/tomcatkeystore</javax.net.ssl.trustStore>

Build your project.

Configure Hippo's Delivery Tier

Run your project.

Point your web browser to the console at:

https://localhost:8443/cms/console/

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

Set the property hst:scheme to https:

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

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

Update the hst:cmslocation and hst:defaultport properties to use the HTTPS protocol and port 8443.

/hst:hst/hst:hosts/dev-localhost
  - hst:cmslocation = https://localhost:8443/cms
  - hst:defaultport = 8443

Browse to the node /hippo:configuration/hippo:frontend/cms/cms-services/hstRestProxyService.

Update the rest.uri property to use the HTTPS protocol and port 8443:

/hippo:configuration/hippo:frontend/cms/cms-services/hstRestProxyService
  - rest.uri = https://127.0.0.1:8443/site/_cmsrest

Write your changes to the repository.

Point your browser to the CMS at:

https://localhost:8443/cms/

Verify that the channel manager is working. If not double-check the hstRestProxyService configuration.