github.nisrulz.androidutils.crypto

Class AesCbcWithIntegrity

java.lang.Object

github.nisrulz.androidutils.crypto.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.

https://github.com/tozny/java-aes-crypto

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 The constant 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 & 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 & HMAC keys.
static AesCbcWithIntegrity.SecretKeys	generateKeyFromPassword(java.lang.String password, java.lang.String salt) A function that generates password-based AES & 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

The constant 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 & 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 & HMAC key set suitable for other functions.

Throws:

java.security.InvalidKeyException - the invalid key exception

generateKey

public static AesCbcWithIntegrity.SecretKeys generateKey()
                                                  throws java.security.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:

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 & 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:

java.security.GeneralSecurityException - the general security exception

generateKeyFromPassword

public static AesCbcWithIntegrity.SecretKeys generateKeyFromPassword(java.lang.String password,
                                                                     byte[] salt)
                                                              throws java.security.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.

salt - the salt

Returns:

The AES & HMAC keys.

Throws:

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

generateSalt

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

Generates a random salt.

Returns:

The random salt suitable for generateKeyFromPassword.

Throws:

java.security.GeneralSecurityException - the general security exception

saltString

public static java.lang.String saltString(byte[] salt)

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

Parameters:

salt - the salt

Returns:

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

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 & HMAC keys with which to encrypt

Returns:

a tuple of the IV, ciphertext, mac

Throws:

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

java.security.GeneralSecurityException - if AES is not implemented on 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 & HMAC keys with which to encrypt

encoding - the encoding

Returns:

a tuple of the IV, ciphertext, mac

Throws:

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

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

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 & 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

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

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:

byteCipherText - the cipher text

integrityKey - The key used for hmac

Returns:

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

Throws:

java.security.NoSuchAlgorithmException - the no such algorithm exception

java.security.InvalidKeyException - the invalid key exception

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 & HMAC keys

Returns:

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

Throws:

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

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 & 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.io.UnsupportedEncodingException - if the encoding is unsupported

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

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 & HMAC keys

Returns:

The raw decrypted bytes

Throws:

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

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 - the a

b - the b

Returns:

true iff the arrays are exactly equal.