From b74ff4f6df28405222752fb2b1089f11e96e5406 Mon Sep 17 00:00:00 2001 From: Travis Jensen Date: Fri, 6 May 2011 12:36:38 -0600 Subject: Add true streaming AES (CTR) encryption and streaming HMAC operations The current crypto module implementations require all of the data being encrypted or authenticated to be in memory at one time. When trying to encrypt or authenticate a large file (on order of GBs), this is problematic. The implementation of AES CTR uses the same underlying implementation as aes_ctr_[en|de]crypt, but hands the state back to the client after every operation. The HMAC implementation differs from the previous implementations of sha_mac and md5_mac. The old implementations did not utilize the OpenSSL HMAC implementation. In order to ensure that I didn't implement something incorrectly, I chose to use the OpenSSL HMAC implementation directly, since it handles streaming as well. This has the added side benefit of allowing other hash functions to be used as desired (for instances, I added support for ripemd160 hashing). While I haven't done this, it seems like the existing md5_mac and sha_mac functions could either be depricated or redefined in terms of the new hmac_ functions. Update AES CTR and HMAC streaming with code review input Ensure that memcpy operations in hmac operations are being size checked properly. Rename aes_ctr_XXX_with_state to aes_ctr_stream_XXX. Remove redundant hmac_init_[sha|md5|ripemd160] functions. Fix documentation for hmac_final_n. Fix possible error using negative value as a marker on an unsigned int Now, use a separate marker and add a unit test to test specifically for a case where HashLen is larger than the underlying resultant hash. Revert "Fix possible error using negative value as a marker on an unsigned int" This reverts commit 59cb177aa96444c0fd3ace6d01f7b8a70dd69cc9. Resolve buffer overflow posibility on an unsigned int. Change handling the marker for HashLen to use the fact that a second parameter that has to be the the HashLen was passed. Also, ensure that HashLen parameter is positive. --- lib/crypto/doc/src/crypto.xml | 100 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) (limited to 'lib/crypto/doc') diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml index 1ccea6df79..179ba4498c 100644 --- a/lib/crypto/doc/src/crypto.xml +++ b/lib/crypto/doc/src/crypto.xml @@ -281,6 +281,57 @@ Mpint() = >]]> is 96 bits (12 bytes).

+ + hmac_init(Type, Key) -> Context + + + Type = sha | md5 | ripemd160 + Key = iolist() | binary() + Context = binary() + + +

Initializes the context for streaming HMAC operations. Type determines + which hash function to use in the HMAC operation. Key is the authentication + key. The key can be any length.

+ + + + hmac_update(Context, Data) -> NewContext + + + Context = NewContext = binary() + Data = iolist() | binary() + + +

Updates the HMAC represented by Context using the given Data. Context + must have been generated using an HMAC init function (such as + hmac_init). Data can be any length. NewContext + must be passed into the next call to hmac_update.

+ + + + hmac_final(Context) -> Mac + + + Context = Mac = binary() + + +

Finalizes the HMAC operation referenced by Context. The size of the resultant MAC is + determined by the type of hash function used to generate it.

+ + + + hmac_final_n(Context, HashLen) -> Mac + + + Context = Mac = binary() + HashLen = non_neg_integer() + + +

Finalizes the HMAC operation referenced by Context. HashLen must be greater than + zero. Mac will be a binary with at most HashLen bytes. Note that if HashLen is greater than the actual number of bytes returned from the underlying hash, the returned hash will have fewer than HashLen bytes.

+ + sha_mac(Key, Data) -> Mac Compute an MD5 MACmessage authentification code @@ -588,6 +639,55 @@ Mpint() = >]]> (16 bytes).

 + + aes_ctr_stream_init(Key, IVec) -> State + + + State = { K, I, E, C } + Key = K = iolist() + IVec = I = E = binary() + C = integer() + + +

Initializes the state for use in streaming AES encryption using Counter mode (CTR). + Key is the AES key and must be either 128, 192, or 256 bts long. IVec is + an arbitrary initializing vector of 128 bits (16 bytes). This state is for use with + aes_ctr_stream_encrypt and + aes_ctr_stream_decrypt.

+ + + + aes_ctr_stream_encrypt(State, Text) -> { NewState, Cipher} + + + Text = iolist() | binary() + Cipher = binary() + + +

Encrypts Text according to AES in Counter mode (CTR). This function can be + used to encrypt a stream of text using a series of calls instead of requiring all + text to be in memory. Text can be any number of bytes. State is initialized using + aes_ctr_stream_init. NewState is the new streaming + encryption state that must be passed to the next call to aes_ctr_stream_encrypt. + Cipher is the encrypted cipher text.

+ + + + aes_ctr_stream_decrypt(State, Cipher) -> { NewState, Text } + + + Cipher = iolist() | binary() + Text = binary() + + +

Decrypts Cipher according to AES in Counter mode (CTR). This function can be + used to decrypt a stream of ciphertext using a series of calls instead of requiring all + ciphertext to be in memory. Cipher can be any number of bytes. State is initialized using + aes_ctr_stream_init. NewState is the new streaming + encryption state that must be passed to the next call to aes_ctr_stream_encrypt. + Text is the decrypted data.

+ + erlint(Mpint) -> N mpint(N) -> Mpint -- cgit v1.2.3