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.

To help you do this, Cloud CMS provides a command line tool.

gitana-tools-encryptor.jar

The gitana-tools-encryptor.jar works with Java 8 and gives you commands that you can use to generate public / private keys as well as use those keys to encrypt, decrypt and validate your encrypted data.

To use this tool:

java -jar gitana-tools-encryptor.jar <command> [options...]

The following commands are supported:

generate-keys
encrypt
decrypt
validate

Getting Started - Generating Keys

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

java -jar gitana-tools-encryptor.jar generate-keys

The keys will be saved locally as:

gitana-properties.pub
gitana-properties.private

The public key file can be distributed to the developer team for use in encrypting configuration properties. The private key file should be kept secret and should be packaged into the Cloud CMS API server (next step).

Once you have your keys, copy the gitana-properties.private file into your Docker API container in the following location:

classes/gitana/keys/gitana-properties.private

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

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

Once you've copied that into place, you should delete other copies of the private key file. The private key should not be distributed to your development team.

Encrypting a Property

Anyone who seeks to encrypt a property should be given the gitana-properties.pub file. This is a public key file and can be distributed to anyone who wants to encrypt a value and have it get decrypted by the API when the API starts up.

Imagine that you (as a developer) are working with docker.properties and you have the following entry:

gitana.admin.password=admin

Suppose you want to encrypt this password so that it isn't just written out in plaintext.

Make sure the gitana-properties.pub file is in your current directory. And then run the following command:

java -jar gitana-tools-encryptor.jar encrypt --value admin

You might get something like:

S/3GXvZYOhr/jgBlTIpT1VSfi34WUeq1gu9JAMEyN3z2URnuEIHcpVwXMEn3ucvKOxHIlkjtyXYqDFqDjnhMP5x+Q0Wnf4Ov4fJ1FXHAom7pKxGJH0IHtvgXeJ1VJ7bYpPyPeOwG3hpBpBNbVIJBbGjv0MDxu8wgokMA7/qR7Vs=

Change your docker.properties so that it looks like this:

gitana.admin.password.enc=ENC(S/3GXvZYOhr/jgBlTIpT1VSfi34WUeq1gu9JAMEyN3z2URnuEIHcpVwXMEn3ucvKOxHIlkjtyXYqDFqDjnhMP5x+Q0Wnf4Ov4fJ1FXHAom7pKxGJH0IHtvgXeJ1VJ7bYpPyPeOwG3hpBpBNbVIJBbGjv0MDxu8wgokMA7/qR7Vs=)
gitana.admin.password=${gitana.admin.password.enc}

That's it. When the API starts up, it will see the ENC prefix to your password and will automatically decrypt the value using the private key file (gitana-properties.private) discovered by the API on its classpath when it starts up.

Administrative Functions

A few additional commands are available for administrators who have the private key file.

Decrypt a Property

If you are the system administrator and have access to the private key file, you can validate an existing encrypted property.

Suppose you know that the encrypted password is:

S/3GXvZYOhr/jgBlTIpT1VSfi34WUeq1gu9JAMEyN3z2URnuEIHcpVwXMEn3ucvKOxHIlkjtyXYqDFqDjnhMP5x+Q0Wnf4Ov4fJ1FXHAom7pKxGJH0IHtvgXeJ1VJ7bYpPyPeOwG3hpBpBNbVIJBbGjv0MDxu8wgokMA7/qR7Vs=

And you want to find out the actual value.

To do so, you need to have the private key file. Bear in mind that you shouldn't generally have this and this is something that only a system administrator would do.

Make sure the gitana-properties.private file is in your current directory. And then run the following command:

java -jar gitana-tools-encryptor.jar decrypt --encryptedValue S/3GXvZYOhr/jgBlTIpT1VSfi34WUeq1gu9JAMEyN3z2URnuEIHcpVwXMEn3ucvKOxHIlkjtyXYqDFqDjnhMP5x+Q0Wnf4Ov4fJ1FXHAom7pKxGJH0IHtvgXeJ1VJ7bYpPyPeOwG3hpBpBNbVIJBbGjv0MDxu8wgokMA7/qR7Vs=

And it will print out:

admin

Validate a Property

You may also want to run a simple test to verify whether an encrypted property matches what you expect.

Suppose you know that the encrypted password is:

S/3GXvZYOhr/jgBlTIpT1VSfi34WUeq1gu9JAMEyN3z2URnuEIHcpVwXMEn3ucvKOxHIlkjtyXYqDFqDjnhMP5x+Q0Wnf4Ov4fJ1FXHAom7pKxGJH0IHtvgXeJ1VJ7bYpPyPeOwG3hpBpBNbVIJBbGjv0MDxu8wgokMA7/qR7Vs=

And you want to see if this is, in fact, admin.

You can do so like this:

java -jar gitana-tools-encryptor.jar validate --value admin --encryptedValue S/3GXvZYOhr/jgBlTIpT1VSfi34WUeq1gu9JAMEyN3z2URnuEIHcpVwXMEn3ucvKOxHIlkjtyXYqDFqDjnhMP5x+Q0Wnf4Ov4fJ1FXHAom7pKxGJH0IHtvgXeJ1VJ7bYpPyPeOwG3hpBpBNbVIJBbGjv0MDxu8wgokMA7/qR7Vs=

This will print out:

true

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