Skip to content

Latest commit

 

History

History
92 lines (74 loc) · 5.21 KB

README.md

File metadata and controls

92 lines (74 loc) · 5.21 KB
Raw

commons-encryption

Pre-Requisites

Prior to making use of the commons-encryption library it may be necessary to install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files.

Versions and Backwards compatibility

This is the 2.x release of the code which IS NOT backwards compatible with the 1.x releases. Many underlying things have changed such as encryption algorithms (AES-CBC to AES-GCM) as well as changes to key formats. See upgrading section below for details. If you are continuing to use the 1.x versions (which is fine), you will need to use readme on in that branch of code rather than this one. I plan on maintaining the 1.x versions for the foreseeable future.

Upgrading

If you are upgrading from 1.x to 2.x you will need to A) Replace all 1.x keys with 2.x keys using the keygen tool. B) Decrypt 1.x encrypted values and re-encrypt with 2.x encrypted values. The exception to this is output from the Whirlpool SHA256 password encryptions. These implementations havent changed in the 2.x branch and will be backwards compatible.

Usage

In order to make use of the commons-encryption library you first need to download the jars from here on github, or alternatively if you use maven you are able to download the dependency from maven central repository.

Maven Dependency
<dependency>
	<groupId>net.theblackchamber</groupId>
	<artifactId>commons-encryption</artifactId>
	<version>2.0.0</version>
</dependency>

After the commons-encryption library has been added to your project usage is pretty straight forward. Generally the classes you will be interacting with will be in the implementations, util, and providers packages. Specific examples of use can be found in the API documents located on the project website and in the unit tests under src/test/java.

Examples:

Key Generation

The following snippet of code is an example of generating an AES key and writing it to disk.

KeyConfig config = new KeyConfig(keyStoreFile);
KeystoreUtils.generateSecretKey(config);
SecureProperties

SecureProperties2 is an attempt to provide a transparent extension of the native java Properties class which allows property values to be encrypted at rest. Be aware of the exceptions thrown by methods as described in the API... Methods throw a custom unchecked runtime exception. Also note that its possible to pass Key Password, Keystore Path, and Key Entry name to the SecureProperties2 constructor rather than specifying them in the properties file.

test.properties
key-path=/my/key/location
key1=My Unencrypted Property Value
key2-encrypted=FAB123DE7A012FCD

The following snippet of code is an example of loading a properties file from disk into a SecureProperties2 object which can be used in existing java classes.

FileReader reader = new FileReader(propertiesFile);
Properties sProperties = new SecureProperties2();
sProperties.load(reader);
String clearKey2 = sProperties.getProperty("key2-encrypted");
sProperties.setProperty("key3-unencrypted","cleartext value");

The following snippet of code is an example of configuring the SecureProperties2 by parameter rather than having configuration in the same file as the secured values (This is the recommended use)

FileReader reader = new FileReader(propertiesFile);
SecureProperties2 sProperties = new SecureProperties2(propertiesFile,keyfile.getPath());
sProperties.load(reader);
String decryptedProperty = sProperties.getProperty("test-encrypted");
EncryptionProvider

If you find yourself needing to build your own "implementation" using encryption or just want to manually encrypt/decrypt values. The providers can be used directly.

SecretKey2 key = KeystoreUtils2.getSecretKey(keyfile);
EncryptionProvider2 encryptionProvider = EncryptionProviderFactory2.getProvider(key);
String cipherText = encryptionProvider.encode("clear text");
SecurePropertiesUtils

The SecurePropertiesUtils2 is a utility class primarily used to initially encrypt a clear text properties file in preperation of deploying it to a server. This is so that you can keep a clear text version in your project, edit it, and then easily in one step encrypt the fields which need to be secured and then deploy. Important to note that while a SecureProperties2 instance is returned the file IS changed on disk as well, the returned SecureProperties2 is just a convenience. Also note that its possible to pass Keystore Path to the encryptPropertiesFile method rather than specifying them in the properties file.

key-path=/my/key/location
key1=My Unencrypted Property Value
key2-unencrypted=This Will Be Encrypted
SecureProperties2 sProperties = SecurePropertiesUtils2.encryptPropertiesFile(propertiesFile);
Message Digest

SHA256 and Whirlpool are the currently implemented Digest Providers. Usage for both is the same:

SHA256DigestProvider provider = new SHA256DigestProvider();
String hashedString = provider.digest("CLEARTEXT");
Further Examples

More examples of usage can be found in the src/test/java folder.