Developing an App Under TLS

Apps that connect to a TLS-enabled PCC service instance require a truststore containing the Services CA certificate from CredHub, and they must set properties to configure the communication with the Pivotal GemFire components within the PCC service instance.

Have your PCF operator follow this procedure to acquire and provide you with the Services CA certificate:

1. From the Ops Manager VM, set the API target of the CredHub CLI to your CredHub server.
   
   Run the following command:

   credhub api https://BOSH-DIRECTOR:8844 --ca-cert=/var/tempest/workspaces/default/root_ca_certificate
   

   
   where BOSH-DIRECTOR is the IP address of the BOSH Director VM.
   
   For example:

   $ credhub api https://10.0.0.5:8844 --ca-cert=/var/tempest/workspaces/default/root_ca_certificate
   

2. Log in to CredHub.
   
   Run the following command:

   credhub login --client-name=credhub --client-secret=CLIENT-SECRET
   

   
   where CLIENT-SECRET is the client secret set in the creation of the UAA Client.
   
   For example:

   $ credhub login \
       --client-name=credhub \
       --client-secret=abcdefghijklm123456789
   

3. Run this command to print the Services CA certificate:

   $ credhub get --name="/services/tls_ca" -j | jq -r .value.certificate
   

Follow this procedure to set up the truststore:

1. Add the Services CA certificate to an existing truststore or create a new truststore in the app’s src/main/resources folder. See Create a Truststore for instructions. The location for this truststore is fixed. If the app uses a truststore located in a different spot than the src/main/resources folder, create a new truststore in this required location.

Four GemFire properties must be set to configure communication:

1. Set ssl-enabled-components to all.
2. Set ssl-truststore to the absolute path and file name of the truststore as it will exist within the expanded JAR file of the deployed app.
3. Set ssl-truststore-password to the password chosen when the truststore was created.
4. Set ssl-require-authentication to false, such that there will be one-way authentication of the GemFire component to the app.

For a Spring Data GemFire app that places its truststore in src/main/resources, these properties map to

spring.data.gemfire.security.ssl.truststore=/home/vcap/app/BOOT-INF/classes/truststore.jks
spring.data.gemfire.security.ssl.truststore.password=TRUSTSTORE-PASSWORD
spring.data.gemfire.security.ssl.require.authentication=false

where TRUSTSTORE-PASSWORD is the password chosen during truststore creation.

For other apps, the GemFire properties should be

ssl-enabled-components=all
ssl-truststore=/home/vcap/app/BOOT-INF/classes/truststore.jks
ssl-truststore-password=TRUSTSTORE-PASSWORD
ssl-require-authentication=false

where TRUSTSTORE-PASSWORD is the password chosen during truststore creation. An app may set these properties with the ClientCacheFactory.set() method, prior to creating a ClientCache instance.

The build and cf push of the app does not require any changes to work with a TLS-enabled PCC service instance.