Encrypting Properties

Cloud CMS lets you encrypt properties within your API configuration files to protect sensitive passwords, secrets and credentials.

This encryption utilizes a public and private key. The private key is supplied to the Cloud CMS API server and the public key is provided to developers to encrypt sensitive data.

Getting Started

To get started, an administrator should generate a set of public/private keys. These are RSA encrypted keys.

docker run -v .:/data public.ecr.aws/gitana/admin:3.2.86 generate-certificate

The following files will be generated:

config/keys/properties.crt                      (public certificate)
config/keys/properties.pem                      (public key file)
config/keys/properties.key                      (private key file)

Now that you have these files:

  • The public certificate file (crt) and public key file (pem) can be distributed to the developer team for use in encrypting configuration properties.
  • The private key file (key) should be retained by your administrator. It should be made available to the Cloud CMS API server (next step).

Configuring the API Server with the Private Key

There are three ways to make the private key available to your API container:

First, you can supply the private key using the GITANA_PROPERTIES_PRIVATE_KEY environment variable. If you're using a secrets manager and the private key is stored within, you may opt to use this route.

Second, you can mount the properties.key file onto the volume of the running container at the following path:

/gitana/keys/properties.key

The API server will load this file off disk on startup.

Third, you can mount the properties.key file onto the volume of the running container at any path you like. You can then use the GITANA_PROPERTIES_PRIVATE_KEY_PATH environment variable to specify this path.

GITANA_PROPERTIES_PRIVATE_KEY_PATH=/custom/properties.key

The API server will load this file off disk on startup.

Restart your API container. When it starts up, you should something similar to the following in your log file:

Loaded private key file from classpath: gitana/keys/properties.key

Once again -- the private key should not be distributed to your development team. Keep it secret.

Working with Encrypted Properties

The command line tool used in the previous section supplies a number of commands that you can use to encrypt and decrypt properties. It is intended for administrators who wish to adjust the encrypted properties of the properties files that power Cloud CMS.

Run the following to learn about the available commands:

docker run -v .:/data public.ecr.aws/gitana/admin:3.2.86

You will see something like:

Gitana Administrator

Usage:
docker run -v .:/data public.ecr.aws/gitana/admin <command> [option1] [option2] ...

Properties Commands:
decrypt --privateKey <file path> [--value <encrypted value>] [--file <file path>] [--out <file path>] [--force]
encrypt --cert <file path> [--value <value>] [--file <file path>] [--out <file path>] [--force]
get-property --privateKey <file path> --file <file path> --property <key>
set-property --cert <file path> --value <value> --file <file path> --property <key>
validate --value <value> --encryptedValue <encrypted value> --privateKey <file path>

Generate Commands:
generate-certificate [--out <directory path>] [--name <name>] [--force]
generate-config [--out <directory path>] [--force]
generate-key-secret [--format <format>]
generate-root-properties --cert <file path> --name <name> [--out <directory path>] [--force]

These commands are broken into two groups - properties commands and generate commands.

Properties Commands

decrypt

Decrypts a value using a private key file.

Options:

  • privateKey (required) is the path to the private key file
  • value (optional) is the value to be decrypted
  • file (optional) the path to the source file to decrypt
  • out (optional) if you're decrypting a file, the output path to the target file to be written
  • force (optional) causes any output files on disk to be overwritten

Example - decrypt a value:

docker run -v .:/data public.ecr.aws/gitana/admin:3.2.86 decrypt --value MIAGCSqGSIb3DQEHA6CAMIACAQAxggFsMIIBaAIBADBQMEsxEzARBgNVBAMMCnByb3BlcnRpZXMxEDAOBgNVBAoMB1Vua25vd24xEDAOBgNVBAcMB1Vua25vd24xEDAOBgNVBAYTB1Vua25vd24CAQEwDQYJKoZIhvcNAQEBBQAEggEASJMGX6XTjvGIsTDfXkGI69edFyurIWEfqceJNPXDlW8rFLYs68yjCWmJ9rmEJLoC8paNf1i/l4z9DjSR2OEfsuXbLHtqAVd72IFpa/OQbCR/h75N9oizGL7lNvOx9NXvrnupgfncMEQBXGb3BRHm+w3a0t0hayyZCeh1vnv6/+M/hxUDO44UKJhFa6oKj+++6+O5TniiNa0eWU9vF8zhGHrBt4lIkxVafjY0ANISO7I11njEz9u9lVVQS+GKNHUjNQ/ymORNyv86ju4cpVFeTuigWWBtXxE0mKDqi0BDM3MpszcQ4rCofujL/ymhRHYvzQtwJI4x07i2ZVIQpzcKDTCABgkqhkiG9w0BBwEwHQYJYIZIAWUDBAEqBBBJkb6DYashm98ym+6wTmPhoIAEEGyKY1NMzeeAVHH0FA7be0EAAAAAAAAAAAAA --privateKey config/keys/properties.key

MyPassword

Example - decrypt the contents of a file:

docker run -v .:/data public.ecr.aws/gitana/admin:3.2.86 decrypt --file bar.txt --privateKey config/keys/properties.key

hello world

Example - encrypt the contents of a file (and write to output file):

docker run -v .:/data public.ecr.aws/gitana/admin:3.2.86 decrypt --file bar.txt --privateKey config/keys/properties.key --out foo2.txt

encrypt

Encrypts a value using a public certificate file.

Options:

  • cert (required) is the path to the certificate file
  • value (optional) is the value to be encrypted
  • file (optional) the path to the source file to encrypt
  • out (optional) if you're encrypting a file, the output path to the target file to be written
  • force (optional) causes any output files on disk to be overwritten

Example - encrypt a value:

docker run -v .:/data public.ecr.aws/gitana/admin:3.2.86 encrypt --value MyPassword --cert config/keys/properties.crt

MIAGCSqGSIb3DQEHA6CAMIACAQAxggFsMIIBaAIBADBQMEsxEzARBgNVBAMMCnByb3BlcnRpZXMxEDAOBgNVBAoMB1Vua25vd24xEDAOBgNVBAcMB1Vua25vd24xEDAOBgNVBAYTB1Vua25vd24CAQEwDQYJKoZIhvcNAQEBBQAEggEASJMGX6XTjvGIsTDfXkGI69edFyurIWEfqceJNPXDlW8rFLYs68yjCWmJ9rmEJLoC8paNf1i/l4z9DjSR2OEfsuXbLHtqAVd72IFpa/OQbCR/h75N9oizGL7lNvOx9NXvrnupgfncMEQBXGb3BRHm+w3a0t0hayyZCeh1vnv6/+M/hxUDO44UKJhFa6oKj+++6+O5TniiNa0eWU9vF8zhGHrBt4lIkxVafjY0ANISO7I11njEz9u9lVVQS+GKNHUjNQ/ymORNyv86ju4cpVFeTuigWWBtXxE0mKDqi0BDM3MpszcQ4rCofujL/ymhRHYvzQtwJI4x07i2ZVIQpzcKDTCABgkqhkiG9w0BBwEwHQYJYIZIAWUDBAEqBBBJkb6DYashm98ym+6wTmPhoIAEEGyKY1NMzeeAVHH0FA7be0EAAAAAAAAAAAAA

Example - encrypt the contents of a file:

echo "hello world" > foo.txt
docker run -v .:/data public.ecr.aws/gitana/admin:3.2.86 encrypt --file foo.txt --cert config/keys/properties.crt

MIAGCSqGSIb3DQEHA6CAMIACAQAxggFsMIIBaAIBADBQMEsxEzARBgNVBAMMCnByb3BlcnRpZXMxEDAOBgNVBAoMB1Vua25vd24xEDAOBgNVBAcMB1Vua25vd24xEDAOBgNVBAYTB1Vua25vd24CAQEwDQYJKoZIhvcNAQEBBQAEggEAFXJdIM29ulm1ieeaQ+SCNAXBPtbUOKcz7OLFj6P85BLGE2+t2MlqmxQrzJQ7quua7mM1w/CElcCjATrENggQmFuc11gvTB0ZkjdrbRzdf4fnIYdWHNDi+ez/hf15nspfY4GMoBItduhoGKeQSdGBpnk3tFEqoxnwVNS/LEpmJ4Ms1LbkS4OjIkag3t2+6gfjhjvJIqYG8YXVXn+oR4lW4Pf1GsdzDaMVwvGboNHx3NoglfhBorEPz8EmLJ3PpNJbcdQJBDzpnYZZHxrBeJl6/GS97uWcS6oejFzlGOLqXGHBLE82ewHN+515SW5S+9aYKhrPdQPT+NeSldynxjTsPTCABgkqhkiG9w0BBwEwHQYJYIZIAWUDBAEqBBBCWBUgl7vK8F3LMg7aZEz5oIAEELwdiF9YyzSJfHKNvmJWOLsAAAAAAAAAAAAA

Example - encrypt the contents of a file (and write to output file):

echo "hello world" > foo.txt
docker run -v .:/data public.ecr.aws/gitana/admin:3.2.86 encrypt --file foo.txt --cert config/keys/properties.crt --out bar.txt

get-property

Gets an encrypted property from a Gitana properties file and decrypts it to extract the value.

Options:

  • privateKey (required) is the path to the private key file
  • file (required) the path to the properties file
  • property (required) is the properties file key to be decrypted

Example - set a value directly:

docker run -v .:/data public.ecr.aws/gitana/admin:3.2.86 get-property --privateKey config/keys/properties.key --file custom.properties --property "custom.username"

joe123

set-property

Sets a single encrypted property into a Gitana properties file.

Options:

  • cert (required) is the path to the certificate file
  • file (required) the path to the properties file
  • property (required) is the properties file key to be set
  • value (required) is the value to be encrypted

Example - set a value directly:

docker run -v .:/data public.ecr.aws/gitana/admin:3.2.86 set-property --cert config/keys/properties.crt --file custom.properties --property "custom.username" --value joe123

The custom.properties file will now contain the entry:

custom.username=ENC(MIAGCSqGSIb3DQEHA6CAMIACAQAxggFsMIIBaAIBADBQMEsxEzARBgNVBAMMCnByb3BlcnRpZXMxEDAOBgNVBAoMB1Vua25vd24xEDAOBgNVBAcMB1Vua25vd24xEDAOBgNVBAYTB1Vua25vd24CAQEwDQYJKoZIhvcNAQEBBQAEggEAOnQHRw/yM7cAGQamBXcsQNTkK1f+HyaJkRWWvnTT0y0g6F5ff1gZWgSK1T0J3MF2n8BzalQhR7vaJaqMKgCbt53RcvTGUUSWLSlMYaZRSs3yeEEPhBPm924rjFuuLTCL5Hpod/rQuYciwfNWQtp9wg0rIUcByqPi5p7jKJ8iiWPvOt34Uep+77bETVHSP7Tb+u9HSASRFb3yXgWvcUYNq2EFGV5vGAWjaom+J1AZK8sBhFAJ9mnFN/GYW75lzSre18nXg/AV0k2Qm+rwKz1TNzpCdcaJdSwF0ehyBfQ1sVzthyBdGb159FoZ8nNVW9qf5Q+jqQpLLAJ9VuAT8j5fwDCABgkqhkiG9w0BBwEwHQYJYIZIAWUDBAEqBBC0YqRWmc4quw/8V/NISzt4oIAEEFEqoZ6ZKqXT4KEROGPIJXUAAAAAAAAAAAAA)

validate

Validates the encryption of a given value produces the given encrypted result.

Options:

  • value (required) is the value to be encrypted
  • encryptedValue (required) the desired encrypted value
  • privateKey (required) is the path to the private key file

This command returns either: true or false

It will also return an error code of 0 if successful. It will return 127 if there is a failure.

Example:

docker run -v .:/data public.ecr.aws/gitana/admin:3.2.86 validate --value MyPassword --encryptedValue MIAGCSqGSIb3DQEHA6CAMIACAQAxggFsMIIBaAIBADBQMEsxEzARBgNVBAMMCnByb3BlcnRpZXMxEDAOBgNVBAoMB1Vua25vd24xEDAOBgNVBAcMB1Vua25vd24xEDAOBgNVBAYTB1Vua25vd24CAQEwDQYJKoZIhvcNAQEBBQAEggEASJMGX6XTjvGIsTDfXkGI69edFyurIWEfqceJNPXDlW8rFLYs68yjCWmJ9rmEJLoC8paNf1i/l4z9DjSR2OEfsuXbLHtqAVd72IFpa/OQbCR/h75N9oizGL7lNvOx9NXvrnupgfncMEQBXGb3BRHm+w3a0t0hayyZCeh1vnv6/+M/hxUDO44UKJhFa6oKj+++6+O5TniiNa0eWU9vF8zhGHrBt4lIkxVafjY0ANISO7I11njEz9u9lVVQS+GKNHUjNQ/ymORNyv86ju4cpVFeTuigWWBtXxE0mKDqi0BDM3MpszcQ4rCofujL/ymhRHYvzQtwJI4x07i2ZVIQpzcKDTCABgkqhkiG9w0BBwEwHQYJYIZIAWUDBAEqBBBJkb6DYashm98ym+6wTmPhoIAEEGyKY1NMzeeAVHH0FA7be0EAAAAAAAAAAAAA --privateKey config/keys/properties.key

true

Generate Commands

generate-certificate

This command generates a public certificate, a public key file and private key file.

Options:

  • out (optional) defines the output directory where the files will be written (default is config/keys).
  • name (optional) defines the base name of the generated files (default is properties).
  • force (optional) causes any output files on disk to be overwritten

Example:

docker run -v .:/data public.ecr.aws/gitana/admin:3.2.86 generate-certificate

The following files are generated:

config/keys/properties.key                      (private key file)
config/keys/properties.pem                      (public key file)
config/keys/properties.crt                      (certificate)

generate-config

This command scaffolds out configuration files that can be used to customize and extend your Cloud CMS API servers.

Options:

  • out (optional) defines the output directory where the files will be written (default is config).
  • force (optional) causes any output files on disk to be overwritten

Example:

docker run -v .:/data public.ecr.aws/gitana/admin:3.2.86 generate-config

The following files are generated:

config/api/classes/container.properties
config/api/classes/gitana-container-context.xml
config/api/classes/log4j2-container.xml
config/api/setup.sh

generate-key-secret

Generates a Gitana UUID key/secret pair.

Options:

  • format (optional) the output format - either json, text or xml (defaults to json).

Example:

docker run -v .:/data public.ecr.aws/gitana/admin:3.2.86 generate-key-secret

{'key': 'df45179c-a9ed-44f2-81e3-95aa5304d8f5', 'secret': 'CgYv/PaA6mgNFxRwLfWHWfWUHM049/+pku0ZmgE/OosETP8nVmifO0AEcfzrcUzHa9lrTjHmtJv6g8ldXOeIztG3ykP3BwrdCvrwXAP62cA='}

Example - as XML:

docker run -v .:/data public.ecr.aws/gitana/admin:3.2.86 generate-key-secret --format xml

<keypair><key>80ced2df-dde0-4dac-b96d-2229a5a27238</key><secret>lwrf+7xHU/g4Kg2tSz2EqP5EEmu7U0N5zknDPWRSVWA5l2DFAaqngO8hnsMInyEKiP1QZgQ+28eTHdAR4nGq2P0fOdP/uy8UohA9hBSscxc=</secret></keypair>

generate-root-properties

Generates a root properties configuration properties for use with your Cloud CMS installation (should you choose to use one). The generated root properties file contains generated encrypted values for common secure properties.

Options:

  • cert (required) is the path to the certificate file
  • name (required) the filename of the generated properties
  • out (optional) the output directory where the file will be written (default is config)
  • force (optional) causes any output files on disk to be overwritten

Example:

 docker run -v .:/data public.ecr.aws/gitana/admin:3.2.86 generate-root-properties --cert ./config/keys/properties.crt --name root.properties

This generates a root.properties file in the config directory

The root.properties file will have encrypted values for the following keys:

admin.client.key=
admin.client.secret=
admin.authenticationGrant.key=
admin.authenticationGrant.secret=
cloudcms.user.username=
cloudcms.user.password=
cloudcms.client.key=
cloudcms.client.secret=
cloudcms.authenticationGrant.key=
cloudcms.authenticationGrant.secret=
virtualdriver.user.username=
virtualdriver.user.password=
virtualdriver.client.key=
virtualdriver.client.secret=
virtualdriver.authenticationGrant.key=
virtualdriver.authenticationGrant.secret=
encryption.secret=
ticket.secret=