com.tozny.crypto.android

Class AesCbcWithIntegrity

java.lang.Object

com.tozny.crypto.android.AesCbcWithIntegrity

public class AesCbcWithIntegrity
extends java.lang.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.

Field Summary

Fields

Modifier and Type	Field and Description
static int	BASE64_FLAGS

Constructor Summary

Constructors

Constructor and Description
AesCbcWithIntegrity()

Method Summary

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 java.lang.String	decryptString(AesCbcWithIntegrity.CipherTextIvMac civ, AesCbcWithIntegrity.SecretKeys secretKeys) AES CBC decrypt.
static java.lang.String	decryptString(AesCbcWithIntegrity.CipherTextIvMac civ, AesCbcWithIntegrity.SecretKeys secretKeys, java.lang.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(java.lang.String plaintext, AesCbcWithIntegrity.SecretKeys secretKeys) Generates a random IV and encrypts this plain text with the given key.
static AesCbcWithIntegrity.CipherTextIvMac	encrypt(java.lang.String plaintext, AesCbcWithIntegrity.SecretKeys secretKeys, java.lang.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 and HMAC keys and prints out exceptions but doesn't throw them since none should be encountered.
static AesCbcWithIntegrity.SecretKeys	generateKeyFromPassword(java.lang.String password, byte[] salt) A function that generates password-based AES and HMAC keys.
static AesCbcWithIntegrity.SecretKeys	generateKeyFromPassword(java.lang.String password, byte[] salt, int iterationCount) A function that generates password-based AES and HMAC keys.
static AesCbcWithIntegrity.SecretKeys	generateKeyFromPassword(java.lang.String password, java.lang.String salt) A function that generates password-based AES and HMAC keys.
static AesCbcWithIntegrity.SecretKeys	generateKeyFromPassword(java.lang.String password, java.lang.String salt, int iterationCount) A function that generates password-based AES and HMAC keys.
static byte[]	generateMac(byte[] byteCipherText, javax.crypto.SecretKey integrityKey) Generate the mac based on HMAC_ALGORITHM
static byte[]	generateSalt() Generates a random salt.
static AesCbcWithIntegrity.SecretKeys	keys(java.lang.String keysStr) An aes key derived from a base64 encoded key.
static java.lang.String	keyString(AesCbcWithIntegrity.SecretKeys keys) Converts the given AES/HMAC keys into a base64 encoded string suitable for storage.
static java.lang.String	saltString(byte[] salt) Converts the given salt into a base64 encoded string suitable for storage.

Methods inherited from class java.lang.Object

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

Field Detail

BASE64_FLAGS

public static final int BASE64_FLAGS

See Also:

Constant Field Values

Constructor Detail

AesCbcWithIntegrity

public AesCbcWithIntegrity()

Method Detail

keyString

public static java.lang.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 and hmac key as base64(aesKey) : base64(hmacKey)

keys

public static AesCbcWithIntegrity.SecretKeys keys(java.lang.String keysStr)
                                           throws java.security.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 and HMAC key set suitable for other functions.

Throws:

java.security.InvalidKeyException

generateKey

public static AesCbcWithIntegrity.SecretKeys generateKey()
                                                  throws java.security.GeneralSecurityException

A function that generates random AES and 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 and HMAC keys.

Throws:

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

generateKeyFromPassword

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

A function that generates password-based AES and 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. By default the keys are generated with 10000 iterations. Use #generateKeyFromPassword (String, byte[], int) if you want to use different iteration count.

Parameters:

password - The password to derive the keys from.

salt - The salt for the keys derived from the password.

Returns:

The AES and HMAC keys.

Throws:

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

generateKeyFromPassword

public static AesCbcWithIntegrity.SecretKeys generateKeyFromPassword(java.lang.String password,
                                                                     byte[] salt,
                                                                     int iterationCount)
                                                              throws java.security.GeneralSecurityException

A function that generates password-based AES and 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.

salt - The salt for the keys derived from the password.

iterationCount - The iteration count for the keys generation.

Returns:

The AES and HMAC keys.

Throws:

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

generateKeyFromPassword

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

A function that generates password-based AES and HMAC keys. See #generateKeyFromPassword (String, byte[]) for more details. By default the keys are generated with 10000 iterations. Use #generateKeyFromPassword (String, String, int) if you want to use different iteration count.

Parameters:

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

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

Returns:

The AES and HMAC keys.

Throws:

java.security.GeneralSecurityException

generateKeyFromPassword

public static AesCbcWithIntegrity.SecretKeys generateKeyFromPassword(java.lang.String password,
                                                                     java.lang.String salt,
                                                                     int iterationCount)
                                                              throws java.security.GeneralSecurityException

A function that generates password-based AES and HMAC keys. See generateKeyFromPassword(String, byte[], int) for more details.

Parameters:

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

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

iterationCount - The iteration count for the key generation.

Returns:

The AES and HMAC keys.

Throws:

java.security.GeneralSecurityException

generateSalt

public static byte[] generateSalt()
                           throws java.security.GeneralSecurityException

Generates a random salt.

Returns:

The random salt suitable for generateKeyFromPassword.

Throws:

java.security.GeneralSecurityException

saltString

public static java.lang.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 java.security.GeneralSecurityException

Creates a random Initialization Vector (IV) of IV_LENGTH_BYTES.

Returns:

The byte array of this IV

Throws:

java.security.GeneralSecurityException - if a suitable RNG is not available

encrypt

public static AesCbcWithIntegrity.CipherTextIvMac encrypt(java.lang.String plaintext,
                                                          AesCbcWithIntegrity.SecretKeys secretKeys)
                                                   throws java.io.UnsupportedEncodingException,
                                                          java.security.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 and HMAC keys with which to encrypt

Returns:

a tuple of the IV, ciphertext, mac

Throws:

java.security.GeneralSecurityException - if AES is not implemented on this system

java.io.UnsupportedEncodingException - if UTF-8 is not supported in this system

encrypt

public static AesCbcWithIntegrity.CipherTextIvMac encrypt(java.lang.String plaintext,
                                                          AesCbcWithIntegrity.SecretKeys secretKeys,
                                                          java.lang.String encoding)
                                                   throws java.io.UnsupportedEncodingException,
                                                          java.security.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 and HMAC keys with which to encrypt

Returns:

a tuple of the IV, ciphertext, mac

Throws:

java.security.GeneralSecurityException - if AES is not implemented on this system

java.io.UnsupportedEncodingException - if the specified encoding is invalid

encrypt

public static AesCbcWithIntegrity.CipherTextIvMac encrypt(byte[] plaintext,
                                                          AesCbcWithIntegrity.SecretKeys secretKeys)
                                                   throws java.security.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 and HMAC keys with which to encrypt

Returns:

a tuple of the IV, ciphertext, mac

Throws:

java.security.GeneralSecurityException - if AES is not implemented on this system

decryptString

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

AES CBC decrypt.

Parameters:

civ - The cipher text, IV, and mac

secretKeys - The AES and 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:

java.security.GeneralSecurityException - if AES is not implemented on this system

java.io.UnsupportedEncodingException - if the encoding is unsupported

decryptString

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

AES CBC decrypt.

Parameters:

civ - The cipher text, IV, and mac

secretKeys - The AES and HMAC keys

Returns:

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

Throws:

java.security.GeneralSecurityException - if AES is not implemented on this system

java.io.UnsupportedEncodingException - if UTF-8 is not supported

decrypt

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

AES CBC decrypt.

Parameters:

civ - the cipher text, iv, and mac

secretKeys - the AES and HMAC keys

Returns:

The raw decrypted bytes

Throws:

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

generateMac

public static byte[] generateMac(byte[] byteCipherText,
                                 javax.crypto.SecretKey integrityKey)
                          throws java.security.NoSuchAlgorithmException,
                                 java.security.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 and ciphertext

Throws:

java.security.NoSuchAlgorithmException

java.security.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.

Returns:

true iff the arrays are exactly equal.