org.miloss.fgsms.common

Class AesCbcWithIntegrity

java.lang.Object

org.miloss.fgsms.common.AesCbcWithIntegrity

public class AesCbcWithIntegrity
extends Object

Simple library for the "right" defaults for AES key generation, encryption, and decryption using 128-bit AES, CBC, PKCS5 padding, and a random 16-byte IV with SHA1PRNG. Integrity with HmacSHA256.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AesCbcWithIntegrity.CipherTextIvMac Holder class that allows us to bundle ciphertext and IV together.
static class	AesCbcWithIntegrity.PrngFixes Fixes for the RNG as per http://android-developers.blogspot.com/2013/08/some-securerandom-thoughts.html This software is provided 'as-is', without any express or implied warranty.
static class	AesCbcWithIntegrity.SecretKeys Holder class that has both the secret AES key for encryption (confidentiality) and the secret HMAC key for integrity.

Constructor Summary

Constructors

Constructor and Description
AesCbcWithIntegrity()

Method Summary

Methods

Modifier and Type	Method and Description
static boolean	constantTimeEq(byte[] a, byte[] b) Simple constant-time equality of two byte arrays.
static byte[]	decrypt(AesCbcWithIntegrity.CipherTextIvMac civ, AesCbcWithIntegrity.SecretKeys secretKeys) AES CBC decrypt.
static String	decryptString(AesCbcWithIntegrity.CipherTextIvMac civ, AesCbcWithIntegrity.SecretKeys secretKeys) AES CBC decrypt.
static String	decryptString(AesCbcWithIntegrity.CipherTextIvMac civ, AesCbcWithIntegrity.SecretKeys secretKeys, String encoding) AES CBC decrypt.
static AesCbcWithIntegrity.CipherTextIvMac	encrypt(byte[] plaintext, AesCbcWithIntegrity.SecretKeys secretKeys) Generates a random IV and encrypts this plain text with the given key.
static AesCbcWithIntegrity.CipherTextIvMac	encrypt(String plaintext, AesCbcWithIntegrity.SecretKeys secretKeys) Generates a random IV and encrypts this plain text with the given key.
static AesCbcWithIntegrity.CipherTextIvMac	encrypt(String plaintext, AesCbcWithIntegrity.SecretKeys secretKeys, String encoding) Generates a random IV and encrypts this plain text with the given key.
static byte[]	generateIv() Creates a random Initialization Vector (IV) of IV_LENGTH_BYTES.
static AesCbcWithIntegrity.SecretKeys	generateKey() A function that generates random AES & HMAC keys and prints out exceptions but doesn't throw them since none should be encountered.
static AesCbcWithIntegrity.SecretKeys	generateKeyFromPassword(String password, byte[] salt) A function that generates password-based AES & HMAC keys.
static AesCbcWithIntegrity.SecretKeys	generateKeyFromPassword(String password, String salt) A function that generates password-based AES & HMAC keys.
static byte[]	generateMac(byte[] byteCipherText, SecretKey integrityKey) Generate the mac based on HMAC_ALGORITHM
static byte[]	generateSalt() Generates a random salt.
static AesCbcWithIntegrity.SecretKeys	keys(String keysStr) An aes key derived from a base64 encoded key.
static String	keyString(AesCbcWithIntegrity.SecretKeys keys) Converts the given AES/HMAC keys into a base64 encoded string suitable for storage.
static String	saltString(byte[] salt) Converts the given salt into a base64 encoded string suitable for storage.
static boolean	validateKey(AesCbcWithIntegrity.SecretKeys key) return true is the supplied key is a valid aes key

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AesCbcWithIntegrity

public AesCbcWithIntegrity()

Method Detail

validateKey

public static boolean validateKey(AesCbcWithIntegrity.SecretKeys key)

return true is the supplied key is a valid aes key

Parameters:

key -

Returns:

keyString

public static String keyString(AesCbcWithIntegrity.SecretKeys keys)

Converts the given AES/HMAC keys into a base64 encoded string suitable for storage. Sister function of keys.

Parameters:

keys - The combined aes and hmac keys

Returns:

a base 64 encoded AES string & hmac key as base64(aesKey) : base64(hmacKey)

keys

public static AesCbcWithIntegrity.SecretKeys keys(String keysStr)
                                           throws InvalidKeyException

An aes key derived from a base64 encoded key. This does not generate the key. It's not random or a PBE key.

Parameters:

keysStr - a base64 encoded AES key / hmac key as base64(aesKey) : base64(hmacKey).

Returns:

an AES & HMAC key set suitable for other functions.

Throws:

InvalidKeyException

generateKey

public static AesCbcWithIntegrity.SecretKeys generateKey()
                                                  throws GeneralSecurityException

A function that generates random AES & HMAC keys and prints out exceptions but doesn't throw them since none should be encountered. If they are encountered, the return value is null.

Returns:

The AES & HMAC keys.

Throws:

GeneralSecurityException - if AES is not implemented on this system, or a suitable RNG is not available

generateKeyFromPassword

public static AesCbcWithIntegrity.SecretKeys generateKeyFromPassword(String password,
                                                     byte[] salt)
                                                              throws GeneralSecurityException

A function that generates password-based AES & HMAC keys. It prints out exceptions but doesn't throw them since none should be encountered. If they are encountered, the return value is null.

Parameters:

password - The password to derive the keys from.

Returns:

The AES & HMAC keys.

Throws:

GeneralSecurityException - if AES is not implemented on this system, or a suitable RNG is not available

generateKeyFromPassword

public static AesCbcWithIntegrity.SecretKeys generateKeyFromPassword(String password,
                                                     String salt)
                                                              throws GeneralSecurityException

A function that generates password-based AES & HMAC keys. See generateKeyFromPassword.

Parameters:

password - The password to derive the AES/HMAC keys from

salt - A string version of the salt; base64 encoded.

Returns:

The AES & HMAC keys.

Throws:

GeneralSecurityException

generateSalt

public static byte[] generateSalt()
                           throws GeneralSecurityException

Generates a random salt.

Returns:

The random salt suitable for generateKeyFromPassword.

Throws:

GeneralSecurityException

saltString

public static String saltString(byte[] salt)

Converts the given salt into a base64 encoded string suitable for storage.

Parameters:

salt -

Returns:

a base 64 encoded salt string suitable to pass into generateKeyFromPassword.

generateIv

public static byte[] generateIv()
                         throws GeneralSecurityException

Creates a random Initialization Vector (IV) of IV_LENGTH_BYTES.

Returns:

The byte array of this IV

Throws:

GeneralSecurityException - if a suitable RNG is not available

encrypt

public static AesCbcWithIntegrity.CipherTextIvMac encrypt(String plaintext,
                                          AesCbcWithIntegrity.SecretKeys secretKeys)
                                                   throws UnsupportedEncodingException,
                                                          GeneralSecurityException

Generates a random IV and encrypts this plain text with the given key. Then attaches a hashed MAC, which is contained in the CipherTextIvMac class.

Parameters:

plaintext - The text that will be encrypted, which will be serialized with UTF-8

secretKeys - The AES & HMAC keys with which to encrypt

Returns:

a tuple of the IV, ciphertext, mac

Throws:

GeneralSecurityException - if AES is not implemented on this system

UnsupportedEncodingException - if UTF-8 is not supported in this system

encrypt

public static AesCbcWithIntegrity.CipherTextIvMac encrypt(String plaintext,
                                          AesCbcWithIntegrity.SecretKeys secretKeys,
                                          String encoding)
                                                   throws UnsupportedEncodingException,
                                                          GeneralSecurityException

Generates a random IV and encrypts this plain text with the given key. Then attaches a hashed MAC, which is contained in the CipherTextIvMac class.

Parameters:

plaintext - The bytes that will be encrypted

secretKeys - The AES & HMAC keys with which to encrypt

Returns:

a tuple of the IV, ciphertext, mac

Throws:

GeneralSecurityException - if AES is not implemented on this system

UnsupportedEncodingException - if the specified encoding is invalid

encrypt

public static AesCbcWithIntegrity.CipherTextIvMac encrypt(byte[] plaintext,
                                          AesCbcWithIntegrity.SecretKeys secretKeys)
                                                   throws GeneralSecurityException

Generates a random IV and encrypts this plain text with the given key. Then attaches a hashed MAC, which is contained in the CipherTextIvMac class.

Parameters:

plaintext - The text that will be encrypted

secretKeys - The combined AES & HMAC keys with which to encrypt

Returns:

a tuple of the IV, ciphertext, mac

Throws:

GeneralSecurityException - if AES is not implemented on this system

decryptString

public static String decryptString(AesCbcWithIntegrity.CipherTextIvMac civ,
                   AesCbcWithIntegrity.SecretKeys secretKeys,
                   String encoding)
                            throws UnsupportedEncodingException,
                                   GeneralSecurityException

AES CBC decrypt.

Parameters:

civ - The cipher text, IV, and mac

secretKeys - The AES & HMAC keys

encoding - The string encoding to use to decode the bytes after decryption

Returns:

A string derived from the decrypted bytes (not base64 encoded)

Throws:

GeneralSecurityException - if AES is not implemented on this system

UnsupportedEncodingException - if the encoding is unsupported

decryptString

public static String decryptString(AesCbcWithIntegrity.CipherTextIvMac civ,
                   AesCbcWithIntegrity.SecretKeys secretKeys)
                            throws UnsupportedEncodingException,
                                   GeneralSecurityException

AES CBC decrypt.

Parameters:

civ - The cipher text, IV, and mac

secretKeys - The AES & HMAC keys

Returns:

A string derived from the decrypted bytes, which are interpreted as a UTF-8 String

Throws:

GeneralSecurityException - if AES is not implemented on this system

UnsupportedEncodingException - if UTF-8 is not supported

decrypt

public static byte[] decrypt(AesCbcWithIntegrity.CipherTextIvMac civ,
             AesCbcWithIntegrity.SecretKeys secretKeys)
                      throws GeneralSecurityException

AES CBC decrypt.

Parameters:

civ - the cipher text, iv, and mac

secretKeys - the AES & HMAC keys

Returns:

The raw decrypted bytes

Throws:

GeneralSecurityException - if MACs don't match or AES is not implemented

generateMac

public static byte[] generateMac(byte[] byteCipherText,
                 SecretKey integrityKey)
                          throws NoSuchAlgorithmException,
                                 InvalidKeyException

Generate the mac based on HMAC_ALGORITHM

Parameters:

integrityKey - The key used for hmac

byteCipherText - the cipher text

Returns:

A byte array of the HMAC for the given key & ciphertext

Throws:

NoSuchAlgorithmException

InvalidKeyException

constantTimeEq

public static boolean constantTimeEq(byte[] a,
                     byte[] b)

Simple constant-time equality of two byte arrays. Used for security to avoid timing attacks.

Parameters:

a -

b -

Returns:

true iff the arrays are exactly equal.