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 filevalue
(optional) is the value to be decryptedfile
(optional) the path to the source file to decryptout
(optional) if you're decrypting a file, the output path to the target file to be writtenforce
(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 filevalue
(optional) is the value to be encryptedfile
(optional) the path to the source file to encryptout
(optional) if you're encrypting a file, the output path to the target file to be writtenforce
(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 filefile
(required) the path to the properties fileproperty
(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 filefile
(required) the path to the properties fileproperty
(required) is the properties file key to be setvalue
(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 encryptedencryptedValue
(required) the desired encrypted valueprivateKey
(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 isconfig/keys
).name
(optional) defines the base name of the generated files (default isproperties
).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 isconfig
).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 - eitherjson
,text
orxml
(defaults tojson
).
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 filename
(required) the filename of the generated propertiesout
(optional) the output directory where the file will be written (default isconfig
)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=