Security and Encryption

Overview

The org.openmrs.util.Security class provides basic encryption and decryption methods for use in the API.

Single Direction Encryption or Hash Validation

The following public methods provide access to single direction encryption utilities:

public static boolean hashMatches(String hashedPassword, String passwordToHash);

This is mostly helpful with password validation and checks against both SHA1 and SHA-512 + 128 character salt algorithms.

 

public static String encodeString(String strToEncode);

The returned value is the parameter after being encoded using the OpenMRS default encryption (currently hardcoded to SHA-512).

 

public static String getRandomToken();

This simply returns an encoded string using the current time in milliseconds plus a random long value.

Two Way Encryption

OpenMRS utilizes the AES/CBC/PKCS5Padding method for block cipher encryption and decryption. The initialization vector is an array of 16 bytes (typically random) and it will only properly encrypt or decrypt if paired with a specific secret key byte array. Following are the OpenMRS Constants involved:

The encryption vector and key are necessary to form a reliable two way hash, and can be overridden by runtime properties.

 

Warning

Changing the init vector and secret key values in the runtime properties file after data is encrypted will invalidate encrypted data!

 

These methods encrypt and decrypt text using provided or stored initialization vectors and secret keys. The most common API users should not have to provide initVector and secretKey; the methods requiring those values only do so for convenience in testing and special circumstances.

 

The only time these methods should be used is during the initialization wizard's rendering of runtime properties, although they are available for public use.