Adaptive Code via C#. Agile coding with design patterns and SOLID principles (2014)

---

^[5^] In particular, RMAC makes more assumptions about the underlying block cipher than other MACs need to make. The extra assumptions are a bit unreasonable, because they require the block cipher to resist related-key attacks, which are not well studied.

6.5. Incrementally Hashing Data

Problem

You want to use a hash function to process data incrementally, returning a result when the last of the data is finally available.

Solution

Most hash functions use a standard interface for operation, following these steps:

1. The user creates a "context" object to hold intermediate state.

2. The context object gets initialized.

3. The context is "updated" by passing in the data to be hashed.

4. When the data is updated, "finalization" returns the output of the cryptographic hash function.

Discussion

WARNING

Hash functions are not secure by themselves—not for a password system, not for message authentication, not for anything! If you do need a hash function by itself, be sure to at least protect against length extension attacks, as described in Recipe 6.7 and Recipe 6.8.

Libraries with cryptographic hash functions tend to support incremental operation using a standard structure. In fact, this structure is standardized for cryptographic hardware APIs in PKCS (Public Key Cryptography Standard) #11. There are four steps:

1. Allocate a context object. The context object holds the internal state of the hash until data processing is complete. The type can be specific to the hash function, or it can be a single type that works for all hash functions in a library (such as the EVP_MD_CTX type in the OpenSSL library orHCRYPTHASH in Microsoft's CryptoAPI).

2. Initialize the context object, resetting internal parameters of the hash function. Generally, this function takes no arguments other than a pointer to the context object, unless you're using a generic API, in which case you will need to specify which hash algorithm to use.

3. "Update" the context object by passing in data to be hashed and the associated length of that input. The results of the hash will be dependent on the order of the data you pass, but you can pass in all the partial data you wish. That is, calling the update routine with the string "he" then "llo" would produce the same results as calling it once with the string "hello". The update function generally takes the context object, the data to process, and the associated length of that data as arguments.

4. "Finalize" the context object and produce the message digest. Most APIs take as arguments the context object and a buffer into which the message digest is placed.

The OpenSSL API has both a single generic interface to all its hash functions and a separate API for each hash function. Here's an example using the SHA1 API:

#include <stdio.h>

#include <string.h>

#include <openssl/sha.h>

int main(int argc, char *argv[ ]) {

int i;

SHA_CTX ctx;

unsigned char result[SHA_DIGEST_LENGTH]; /* SHA1 has a 20-byte digest. */

unsigned char *s1 = "Testing";

unsigned char *s2 = "...1...2...3...";

SHA1_Init(&ctx);

SHA1_Update(&ctx, s1, strlen(s1));

SHA1_Update(&ctx, s2, strlen(s2));

/* Yes, the context object is last. */

SHA1_Final(result, &ctx);

printf("SHA1(\"%s%s\") = ", s1, s2);

for (i = 0; i < SHA_DIGEST_LENGTH; i++) printf("%02x", result[i]);

printf("\n");

return 0;

}

Every hash function that OpenSSL supports has a similar API. In addition, every such function has an "all-in-one" API that allows you to combine the work of calls for initialization, updating, and finalization, obviating the need for a context object:

unsigned char *SHA1(unsigned char *in, unsigned long len, unsigned char *out);

This function returns a pointer to the out argument.

Both the incremental API and the all-in-one API are very standard, even beyond OpenSSL. The reference versions of most hash algorithms look incredibly similar. In fact, Microsoft's CryptoAPI for Windows provides a very similar API. Any of the Microsoft CSPs provide implementations of MD2, MD5, and SHA1. The following code is the CryptoAPI version of the OpenSSL code presented previously:

#include <windows.h>

#include <wincrypt.h>

#include <stdio.h>

int main(int argc, char *argv[ ]) {

BYTE *pbData;

DWORD cbData = sizeof(DWORD), cbHashSize, i;

HCRYPTHASH hSHA1;

HCRYPTPROV hProvider;

unsigned char *s1 = "Testing";

unsigned char *s2 = "...1...2...3...";

CryptAcquireContext(&hProvider, 0, MS_DEF_PROV, PROV_RSA_FULL, 0);

CryptCreateHash(hProvider, CALG_SHA1, 0, 0, &hSHA1);

CryptHashData(hSHA1, s1, strlen(s1), 0);

CryptHashData(hSHA1, s2, strlen(s2), 0);

CryptGetHashParam(hSHA1, HP_HASHSIZE, (BYTE *)&cbHashSize, &cbData, 0);

pbData = (BYTE *)LocalAlloc(LMEM_FIXED, cbHashSize);

CryptGetHashParam(hSHA1, HP_HASHVAL, pbData, &cbHashSize, 0);

CryptDestroyHash(hSHA1);

CryptReleaseContext(hProvider, 0);

printf("SHA1(\"%s%s\") = ", s1, s2);

for (i = 0; i < cbHashSize; i++) printf("%02x", pbData[i]);

printf("\n");

LocalFree(pbData);

return 0;

}

The preferred API for accessing hash functions from OpenSSL, though, is the EVP API, which provides a generic API to all of the hash functions OpenSSL supports. The following code does the same thing as the first example with the EVP interface instead of the SHA1 interface:

#include <stdio.h>

#include <string.h>

#include <openssl/evp.h>

int main(int argc, char *argv[ ]) {

int i, ol;

EVP_MD_CTX ctx;

unsigned char result[EVP_MAX_MD_SIZE]; /* enough for any hash function */

unsigned char *s1 = "Testing";

unsigned char *s2 = "...1...2...3...";

/* Note the extra parameter */

EVP_DigestInit(&ctx, EVP_sha1( ));

EVP_DigestUpdate(&ctx, s1, strlen(s1));

EVP_DigestUpdate(&ctx, s2, strlen(s2));

/* Here, the context object is first. Notice the pointer to the output length */

EVP_DigestFinal(&ctx, result, &ol);

printf("SHA1(\"%s%s\") = ", s1, s2);

for (i = 0; i < ol; i++) printf("%02x", result[i]);

printf("\n");

return 0;

}

Note particularly that EVP_DigestFinal( ) requires you to pass in a pointer to an integer, into which the output length is stored. You should use this value in your computations instead of hardcoding SHA1's digest size, under the assumption that you might someday have to replace crypto algorithms in a hurry, in which case the digest size may change. For that reason, allocate EVP_MAX_MD_SIZE bytes for any buffer into which you store a message digest, even if some of that space may go unused.

Alternatively, if you'd like to allocate a buffer of the correct size for output dynamically (which is a good idea if you're space-constrained, because if SHA-512 is ever added to OpenSSL, EVP_MAX_MD_SIZE will become 512 bits), you can use the function EVP_MD_CTX_size( ) , which takes a context object and returns the size of the digest. For example:

#include <stdio.h>

#include <stdlib.h>

#include <string.h>

#include <openssl/evp.h>

int main(int argc, char *argv[ ]) {

int i, ol;

EVP_MD_CTX ctx;

unsigned char *result;

unsigned char *s1 = "Testing";

unsigned char *s2 = "...1...2...3...";

EVP_DigestInit(&ctx, EVP_sha1( ));

EVP_DigestUpdate(&ctx, s1, strlen(s1));

EVP_DigestUpdate(&ctx, s2, strlen(s2));

if (!(result = (unsigned char *)malloc(EVP_MD_CTX_block_size(&ctx))))abort();

EVP_DigestFinal(&ctx, result, &ol);

printf("SHA1(\"%s%s\") = ", s1, s2);

for (i = 0; i < ol; i++) printf("%02x", result[i]);

printf("\n");

free(result);

return 0;

}

The OpenSSL library supports only two cryptographic hash functions that we recommend, SHA1 and RIPEMD-160. It also supports MD2, MD4, MD5, and MDC-2-DES. MDC-2-DES is reasonable, but it is slow and provides only 64 bits of resistance to birthday attacks, whereas we recommend a minimum baseline of 80 bits of security. As an alternative, you could initialize the hash function with a nonce, as discussed in Recipe 6.8.

Nonetheless, Table 6-3 contains a summary of the necessary information on each hash function to use both the EVP and hash-specific APIs with OpenSSL.

Table 6-3. OpenSSL-supported hash functions

Message digest function	EVP function to specify MD	Context type for MD-specific API	Prefix for MD-specific API calls (i.e., XXX_Init, ...)	Include file for MD-specific API
MD2	EVP_md2()	MD2_CTX	MD2	openssl/md2.h
MD4	EVP_md4()	MD4_CTX	MD4	openssl/md4.h
MD5	EVP_md5()	MD5_CTX	MD5	openssl/md5.h
MDC-2-DES	EVP_mdc2()	MDC2_CTX	MDC2	openssl/mdc2.h
RIPEMD-160	EVP_ripemd160()	RIPEMD160_CTX	RIPEMD160	openssl/ripemd.h
SHA1	EVP_sha1()	SHA_CTX	SHA1	openssl/sha.h

Of course, you may want to use an off-the-shelf hash function that isn't supported by either OpenSSL or CryptoAPI—for example, SHA-256, SHA-384, or SHA-512. Aaron Gifford has produced a good, free library with implementations of these functions and released it under a BSD-style license. It is available from http://www.aarongifford.com/computers/sha.html.

That library exports an API that should look very familiar:

SHA256_Init(SHA256_CTX *ctx);

SHA256_Update(SHA256_CTX *ctx, unsigned char *data, size_t inlen);

SHA256_Final(unsigned char out[SHA256_DIGEST_LENGTH], SHA256_CTX *ctx);

SHA384_Init(SHA384_CTX *ctx);

SHA384_Update(SHA384_CTX *ctx, unsigned char *data, size_t inlen);

SHA384_Final(unsigned char out[SHA384_DIGEST_LENGTH], SHA384_CTX *ctx);

SHA512_Init(SHA512_CTX *ctx);

SHA512_Update(SHA512_CTX *ctx, unsigned char *data, size_t inlen);

SHA512_Final(unsigned char out[SHA512_DIGEST_LENGTH], SHA512_CTX *ctx);

All of the previous functions are prototyped in the sha2.h header file.

See Also

Implementations of SHA-256 and SHA-512 from Aaron Gifford: http://www.aarongifford.com/computers/sha.html

Recipe 6.7, Recipe 6.8

6.6. Hashing a Single String

Problem

You have a single string of data that you would like to hash, and you don't like the complexity of the incremental interface.

Solution

Use an "all-in-one" interface, if available, or write your own wrapper, as shown in Section 6.6.3.

Discussion

WARNING

Hash functions are not secure by themselves—not for a password system, not for message authentication, not for anything! If you do need a hash function by itself, be sure to at least protect against length extension attacks, as described in Recipe 6.7.

Complexity can certainly get you in trouble, and a simpler API can be better. While not every API provides a single function that can perform a cryptographic hash, many of them do. For example, OpenSSL provides an all-in-one API for each of the message digest algorithms it supports:

unsigned char *MD2(unsigned char *in, unsigned long n, unsigned char *md);

unsigned char *MD4(unsigned char *in, unsigned long n, unsigned char *md);

unsigned char *MD5(const unsigned char *in, unsigned long n, unsigned char *md);

unsigned char *MDC2(const unsigned char *in, unsigned long n, unsigned char *md);

unsigned char *RIPEMD160(const unsigned char *in, unsigned long n,

unsigned char *md);

unsigned char *SHA1(const unsigned char *in, unsigned long n, unsigned char *md);

APIs in this style are commonly seen, even outside the context of OpenSSL. Note that these functions require you to pass in a buffer into which the digest is placed, but they also return a pointer to that same buffer.

OpenSSL does not provide an all-in-one API for calculating message digests with the EVP interface. However, here's a simple wrapper that even allocates its result with malloc( ):

#include <stdio.h>

#include <stdlib.h>

#include <openssl/evp.h>

/* Returns 0 when malloc() fails. */

unsigned char *spc_digest_message(EVP_MD *type, unsigned char *in,

unsigned long n, unsigned int *outlen) {

EVP_MD_CTX ctx;

unsigned char *ret;

EVP_DigestInit(&ctx, type);

EVP_DigestUpdate(&ctx, in, n);

if (!(ret = (unsigned char *)malloc(EVP_MD_CTX_size(&ctx))) return 0;

EVP_DigestFinal(&ctx, ret, outlen);

return ret;

}

Here's a simple example that uses the previous wrapper:

#include <stdio.h>

#include <stdlib.h>

#include <string.h>

#include <openssl/evp.h>

int main(int argc, char *argv[ ]) {

int i;

unsigned int ol;

unsigned char *s = "Testing...1...2...3...";

unsigned char *r;

r = spc_digest_message(EVP_sha1( ), s, strlen(s), &ol);

printf("SHA1(\"%s\") = ", s);

for (i = 0; i < ol; i++) printf("%02x", r[i]);

printf("\n");

free(r);

return 0;

}

Such a wrapper can be adapted easily to any incremental hashing API, simply by changing the names of the functions and the underlying data type, and removing the first argument of the wrapper if it is not necessary. Here is the same wrapper implemented using Microsoft's CryptoAPI:

#include <windows.h>

#include <wincrypt.h>

BYTE *SpcDigestMessage(ALG_ID Algid, BYTE *pbIn, DWORD cbIn, DWORD *cbOut) {

BYTE *pbOut;

DWORD cbData = sizeof(DWORD);

HCRYPTHASH hHash;

HCRYPTPROV hProvider;

CryptAcquireContext(&hProvider, 0, MS_DEF_PROV, PROV_RSA_FULL, 0);

CryptCreateHash(hProvider, Algid, 0, 0, &hHash);

CryptHashData(hHash, pbIn, cbIn, 0);

CryptGetHashParam(hHash, HP_HASHSIZE, (BYTE *)cbOut, &cbData, 0);

pbOut = (BYTE *)LocalAlloc(LMEM_FIXED, *cbOut);

CryptGetHashParam(hHash, HP_HASHVAL, pbOut, cbOut, 0);

CryptDestroyHash(hHash);

CryptReleaseContext(hProvider, 0);

return pbOut;

}

See Also

Recipe 6.7

6.7. Using a Cryptographic Hash

Problem

You need to use a cryptographic hash function outside the context of a MAC, and you want to avoid length-extension attacks, which are quite often possible.

Solution

A good way to thwart length-extension attacks is to run the hash function twice, once over the message, and once over the output of the first hash. This does not protect against birthday attacks, which probably aren't a major problem in most situations. If you need to protect against those attacks as well, use the advice in Recipe 6.8 on the first hash operation.

Discussion

WARNING

Hash functions are not secure by themselves—not for a password system, not for message authentication, not for anything!

Because all of the commonly used cryptographic hash functions break a message into blocks that get processed in an iterative fashion, it's often possible to extend the message and at the same time extend the associated hash, even if some sort of "secret" data was processed at the start of a message.

It's easy to get rid of this kind of problem at the application level. When you need a cryptographic hash, don't use SHA1 or something similar directly. Instead, write a wrapper that hashes the message with your cryptographic hash function, then takes that output and hashes it as well, returning the result.

For example, here's a wrapper for the all-in-one SHA1 interface discussed in Recipe 6.6:

#define SPC_SHA1_DGST_LEN (20)

/* Include anything else you need. */

void spc_extended_sha1(unsigned char *message, unsigned long n,unsigned char *md) {

unsigned char tmp[SPC_SHA1_DGST_LEN];

SHA1(message, n, tmp);

SHA1(tmp, sizeof(tmp), md);

}

Note that this solution does not protect against birthday attacks. When using SHA1, birthday attacks are generally considered totally impractical. However, to be conservative, you can use a nonce to protect against such attacks, as discussed in Recipe 6.8.

See Also

Recipe 6.6, Recipe 6.8

6.8. Using a Nonce to Protect Against Birthday Attacks

Problem

You want to harden a hash function against birthday attacks instead of switching to an algorithm with a longer digest.

Solution

Use a nonce or salt before and after your message (preferably a securely generated random salt), padding the nonce to the internal block size of the hash function.

Discussion

WARNING

Hash functions are not secure by themselves—not for a password system, not for message authentication, not for anything! If you do need a hash function by itself, be sure to at least protect against length extension attacks, as described in Recipe 6.7.

In most cases, when using a nonce or salt with a hash function, where the nonce is as large as the output length of the hash function, you double the effective strength of the hash function in circumstances where a birthday attack would apply. Even smaller nonces help improve security.

To ensure the best security, we strongly recommend that you follow these steps:

1. Select a nonce using a well-seeded cryptographic random number generator (see Chapter 11). If you're going to have multiple messages to process, select a random portion that is common to all messages (at least 64 bits) and use a counter for the rest. (The counter should be big enough to handle any possible number of messages. Here we also recommend dedicating at least 64 bits.)

2. Determine the internal block length of the hash function (discussed later in this section).

3. Pad the nonce to the internal block length by adding as many zero-bytes as necessary.

4. Add the padded nonce to both the beginning and the end of the message.

5. Hash, creating a value V.

6. Hash V to get the final output. This final step protects against length-extension attacks, as discussed in Recipe 6.7.

One thing that you need to be sure to avoid is a situation in which the attacker can control the nonce value. A nonce works well only if it cannot be reused. If an attacker can control the nonce, he can generally guarantee it gets reused, in which case problems like the birthday attack still apply.

In cases where having a nonce that the attacker can't control isn't appropriate, you can probably live with birthday attacks if you're using SHA1 or better. To protect against other attacks without using a nonce, see Recipe 6.7.

All hash functions have a compression function as an element. The size to which that function compresses is the internal block size of the function, and it is usually larger than the actual digest value. For hash functions based on block ciphers, the internal block size is the output length of the hash function (and the compression function is usually built around XOR'ing multiple pieces of block-sized data). Table 6-4 lists the internal block sizes of common message digest functions not based on block ciphers.

Table 6-4. Internal block sizes of common message digest functions

Algorithm	Digest size	Internal block size
MD2	128 bits	16 bytes (128 bits)
MD4	128 bits	64 bytes (512 bits)
MD5	128 bits	64 bytes (512 bits)
RIPEMD-160	160 bits	64 bytes (512 bits)
SHA1	160 bits	64 bytes (512 bits)
SHA-256	256 bits	64 bytes (512 bits)
SHA-384	384 bits	128 bytes (1,024 bits)
SHA-512	512 bits	128 bytes (1,024 bits)

Here's a pair of functions that do all-in-one wrapping of the OpenSSL EVP message digest interface:

#include <openssl/evp.h>

#include <openssl/rand.h>

#include <string.h>

unsigned char *spc_create_nonced_digest(EVP_MD *type, unsigned char *in,

unsigned long n, unsigned int *outlen) {

int bsz, dlen;

EVP_MD_CTX ctx;

unsigned char *pad, *ret;

EVP_DigestInit(&ctx, type);

dlen = EVP_MD_CTX_size(&ctx);

if (!(ret = (unsigned char *)malloc(dlen * 2))) return 0;

RAND_bytes(ret, dlen);

EVP_DigestUpdate(&ctx, ret, dlen);

bsz = EVP_MD_CTX_block_size(&ctx);

if (!(pad = (unsigned char *)malloc(bsz - dlen))) {

free(ret);

return 0;

}

memset(pad, 0, bsz - dlen);

EVP_DigestUpdate(&ctx, pad, bsz - dlen);

EVP_DigestUpdate(&ctx, in, n);

EVP_DigestUpdate(&ctx, ret, dlen);

EVP_DigestUpdate(&ctx, pad, bsz - dlen);

free(pad);

EVP_DigestFinal(&ctx, ret + dlen, outlen);

*outlen *= 2;

return ret;

}

int spc_verify_nonced_digest(EVP_MD *type, unsigned char *in, unsigned long n,

unsigned char *toverify) {

int dlen, outlen, bsz, i;

EVP_MD_CTX ctx;

unsigned char *pad, *vfy;

EVP_DigestInit(&ctx, type);

bsz = EVP_MD_CTX_block_size(&ctx);

dlen = EVP_MD_CTX_size(&ctx);

EVP_DigestUpdate(&ctx, toverify, dlen);

if (!(pad = (unsigned char *)malloc(bsz - dlen))) return 0;

memset(pad, 0, bsz - dlen);

EVP_DigestUpdate(&ctx, pad, bsz - dlen);

EVP_DigestUpdate(&ctx, in, n);

EVP_DigestUpdate(&ctx, toverify, dlen);

EVP_DigestUpdate(&ctx, pad, bsz - dlen);

free(pad);

if (!(vfy = (unsigned char *)malloc(dlen))) return 0;

EVP_DigestFinal(&ctx, vfy, &outlen);

in += dlen;

for (i = 0; i < dlen; i++)

if (vfy[i] != toverify[i + dlen]) {

free(vfy);

return 0;

}

free(vfy);

return 1;

}

The first function, spc_create_nonced_digest( ), automatically selects a nonce from the OpenSSL random number generator and returns twice the digest size in output, where the first digest-sized block is the nonce and the second is the hash. The second function, spc_verify_nonced_digest( ), takes data consisting of a nonce concatenated with a hash value, and returns 1 if the hash validates, and 0 otherwise.

Two macros can make extracting the nonce and the hash easier:

#include <stdio.h>

#include <string.h>

#include <openssl/evp.h>

/* Here, l is the output length of spc_create_nonced_digest( ) */

#define spc_extract_nonce(l, s) (s)

#define spc_extract_digest(l, s) ((s)+((l) / 2))

Here's a sample program using this API:

int main(int argc, char *argv[ ]) {

unsigned int i, ol;

unsigned char *s = "Testing hashes with nonces.";

unsigned char *dgst, *nonce, *ret;

ret = spc_create_nonced_digest(EVP_sha1( ), s, strlen(s), &ol);

nonce = spc_extract_nonce(ol, ret);

dgst = spc_extract_digest(ol, ret);

printf("Nonce = ");

for(i = 0; i < ol / 2; i++)

printf("%02x", nonce[i]);

printf("\nSHA1-Nonced(Nonce, \"%s\") = \n\t", s);

for(i = 0; i < ol / 2; i++)

printf("%02x", dgst[i]);

printf("\n");

if (spc_verify_nonced_digest(EVP_sha1( ), s, strlen(s), ret))

printf("Recalculation verified integrity.\n");

else

printf("Recalculation FAILED to match.\n");

return 0;

}

See Also

Recipe 6.7

6.9. Checking Message Integrity

Problem

You want to provide integrity for messages in such a way that people with a secret key can verify that the message has not changed since the integrity value (often called a tag) was first calculated.

Solution

Use a message integrity check. As with hash functions, there are somewhat standard interfaces, particularly an incremental interface.

Discussion

Libraries that support MACs tend to support incremental operation using a standard structure, very similar to that used by hash functions:

1. Allocate and key a context object. The context object holds the internal state of the MAC until data processing is complete. The type of the context object can be specific to the MAC, or there can be a single type that works for all hash functions in a library. OpenSSL supports only one MAC and has only the associated context type. The key can be reused numerous times without reallocating. Often, you will need to specify the underlying algorithm you are using for your MAC.

2. Reset the context object, setting the internal parameters of the MAC to their initial state so that another message's authentication tag can be calculated. Many MACs accept a nonce, and this is where you would pass that in. This is often combined with the "init" call when the algorithm does not take a nonce, such as with OMAC and HMAC.

3. "Update" the context object by passing in data to be authenticated and the associated length of that input. The results of the MAC'ing process will be dependent on the order of the data that you pass, but you can pass in all the partial data you wish. That is, calling the update routine with the strings "he" then "llo" would produce the same results as calling it once with the string "hello". The update function generally takes as arguments the context object, the data to process, and the associated length of that data.

4. "Finalize" the context object and produce the authentication tag. Most APIs will generally take as arguments the context object and a buffer into which the message digest is placed.

Often, you may have a block cipher or a hash function that you'd like to turn into a MAC, but no associated code comes with the cryptographic primitive. Alternately, you might use a library such as OpenSSL or CryptoAPI that provides very narrow choices. For this reason, the next several recipes provide implementations of MACs we recommend for general-purpose use, particularly OMAC, CMAC, and HMAC.

SECURITY RECOMMENDATIONS FOR MACS

MACs are not quite as low-level as cryptographic hash functions. Yet they are still fairly low-level constructs, and there are some common pitfalls associated with them. We discuss these elsewhere in the book, but here's a summary of steps you should take to defend yourself against common problems:

§ Don't use the same MAC key as an encryption key. If you'd like to have a system with a single key, key your MAC and encryption separately, using the technique from Recipe 4.11.

§ Use a securely generated, randomly chosen key for your MAC, not something hardcoded or otherwise predictable!

§ Be sure to read Recipe 6.18 on how to use a MAC and encryption together securely, as it can be difficult to do.

§ Use an always-increasing nonce, and use this to actively thwart capture replay attacks. Do this even if the MAC doesn't have built-in support for nonces. (See Recipe 6.21 for information on how to thwart capture replay attacks, and Recipe 6.12 for using a nonce with MACs that don't have direct support for them.)

§ It is of vital importance that any parties computing a MAC agree on exactly what data is to be processed. To that end, it pays to get very detailed in specifying the content of messages, including any fields you have and how they are encoded before the MAC is computed. Any encoding should be unambiguous.

Some MAC interfaces may not remove key material from memory when done. Be sure to check the particular implementation you're using.

OpenSSL provides only a single MAC implementation, HMAC, while CryptoAPI supports both CBC-MAC and HMAC. Neither quite follows the API outlined in this recipe, though they stray in different ways. OpenSSL performs the reset operation the same way as the initialization operation (you just pass in 0 in place of the key and the algorithm arguments). CryptoAPI does not allow resetting the context object, and instead requires that a completely new context object be created.

OMAC and HMAC do not take a nonce by default. See Recipe 6.12 to see how to use these algorithms with a nonce. To see how to use the incremental HMAC interface in OpenSSL and CryptoAPI, see Recipe 6.10. CryptoAPI does not have an all-in-one interface, but instead requires use of its incremental API.

Most libraries also provide an all-in-one interface to the MACs they provide. For example, the HMAC all-in-one function for OpenSSL looks like this:

unsigned char *HMAC(const EVP_MD *evp_md, const void *key, int key_len,

const unsigned char *msg, int msglen, unsigned char *tag,

unsigned int *tag_len);

There is some variation in all-in-one APIs. Some are single-pass, like the OpenSSL API described in this section. Others have a separate initialization step and a context object, so that you do not need to specify the underlying cryptographic primitive and rekey every single time you want to use the MAC. That is, such interfaces automatically call functions for resetting, updating, and finalization for you.

See Also

Recipe 4.11, Recipe 6.10, Recipe 6.12, Recipe 6.18, Recipe 6.21

6.10. Using HMAC

Problem

You want to provide message authentication using HMAC.

Solution

If you are using OpenSSL, you can use the HMAC API:

/* The incremental interface */

void HMAC_Init(HMAC_CTX *ctx, const void *key, int len, const EVP_MD *md);

void HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len);

void HMAC_Final(HMAC_CTX *ctx, unsigned char *tag, unsigned int *tag_len);

/* HMAC_cleanup erases the key material from memory. */

void HMAC_cleanup(HMAC_CTX *ctx);

/* The all-in-one interface. */

unsigned char *HMAC(const EVP_MD *evp_md, const void *key, int key_len,

const unsigned char *msg, int msglen, unsigned char *tag,

unsigned int *tag_len);

If you are using CryptoAPI, you can use the CryptCreateHash( ) , CryptHashData( ) , CryptGetHashParam( ) , CryptSetHashParam( ) , and CryptDestroyHash( ) functions:

BOOL WINAPI CryptCreateHash(HCRYPTPROV hProv, ALG_ID Algid, HCRYPTKEY hKey,

DWORD dwFlags, HCRYPTHASH *phHash);

BOOL WINAPI CryptHashData(HCRYPTHASH hHash, BYTE *pbData, DWORD cbData,

DWORD dwFlags);

BOOL WINAPI CryptGetHashParam(HCRYPTHASH hHash, DWORD dwParam, BYTE *pbData,

DWORD *pcbData, DWORD dwFlags);

BOOL WINAPI CryptSetHashParam(HCRYPTHASH hHash, DWORD dwParam, BYTE *pbData,

DWORD dwFlags);

BOOL WINAPI CryptDestroyHash(HCRYPTHASH hHash);

Otherwise, you can use the HMAC implementation provided with this recipe in combination with any cryptographic hash function you have handy.

Discussion

TIP

Be sure to look at our generic recommendations for using a MAC (Recipe 6.9).

Here's an example of using OpenSSL's incremental interface to hash two messages using SHA1:

#include <stdio.h>

#include <openssl/hmac.h>

void spc_incremental_hmac(unsigned char *key, size_t keylen) {

int i;

HMAC_CTX ctx;

unsigned int len;

unsigned char out[20];

HMAC_Init(&ctx, key, keylen, EVP_sha1( ));

HMAC_Update(&ctx, "fred", 4);

HMAC_Final(&ctx, out, &len);

for (i = 0; i < len; i++) printf("%02x", out[i]);

printf("\n");

HMAC_Init(&ctx, 0, 0, 0);

HMAC_Update(&ctx, "fred", 4);

HMAC_Final(&ctx, out, &len);

for (i = 0; i < len; i++) printf("%02x", out[i]);

printf("\n");

HMAC_cleanup(&ctx); /* Remove key from memory */

}

To reset the HMAC context object, we call HMAC_Init( ) , passing in zeros (NULLs) in place of the key, key length, and digest type to use. The NULL argument when initializing in OpenSSL generally means "I'm not supplying this value right now; use what you already have."

The following example shows an implementation of the same code provided for OpenSSL, this time using CryptoAPI (with the exception of resetting the context, because CryptoAPI actually requires a new one to be created). This implementation requires the use of the code in Recipe 5.26 to convert raw key data into an HCRYPTKEY object as required by CryptCreateHash( ) . Note the difference in the arguments required between spc_incremental_hmac( ) as implemented for OpenSSL, and SpcIncrementalHMAC( ) as implemented for CryptoAPI. The latter requires an additional argument that specifies the encryption algorithm for the key. Although the information is never really used, CryptoAPI insists on tying an encryption algorithm to key data. In general, CALG_RC4 should work fine for arbitrary key data (the value will effectively be ignored).

#include <windows.h>

#include <wincrypt.h>

#include <stdio.h>

void SpcIncrementalHMAC(BYTE *pbKey, DWORD cbKey, ALG_ID Algid) {

BYTE out[20];

DWORD cbData = sizeof(out), i;

HCRYPTKEY hKey;

HMAC_INFO HMACInfo;

HCRYPTHASH hHash;

HCRYPTPROV hProvider;

hProvider = SpcGetExportableContext( );

hKey = SpcImportKeyData(hProvider, Algid, pbKey, cbKey);

CryptCreateHash(hProvider, CALG_HMAC, hKey, 0, &hHash);

HMACInfo.HashAlgid = CALG_SHA1;

HMACInfo.pbInnerString = HMACInfo.pbOuterString = 0;

HMACInfo.cbInnerString = HMACInfo.cbOuterString = 0;

CryptSetHashParam(hHash, HP_HMAC_INFO, (BYTE *)&HMACInfo, 0);

CryptHashData(hHash, (BYTE *)"fred", 4, 0);

CryptGetHashParam(hHash, HP_HASHVAL, out, &cbData, 0);

for (i = 0; i < cbData; i++) printf("%02x", out[i]);

printf("\n");

CryptDestroyHash(hHash);

CryptDestroyKey(hKey);

CryptReleaseContext(hProvider, 0);

}

If you aren't using OpenSSL or CryptoAPI, but you have a hash function that you'd like to use with HMAC, you can use the following HMAC implementation:

#include <stdlib.h>

#include <string.h>

typedef struct {

DGST_CTX mdctx;

unsigned char inner[DGST_BLK_SZ];

unsigned char outer[DGST_BLK_SZ];

} SPC_HMAC_CTX;

void SPC_HMAC_Init(SPC_HMAC_CTX *ctx, unsigned char *key, size_t klen) {

int i;

unsigned char dk[DGST_OUT_SZ];

DGST_Init(&(ctx->mdctx));

memset(ctx->inner, 0x36, DGST_BLK_SZ);

memset(ctx->outer, 0x5c, DGST_BLK_SZ);

if (klen <= DGST_BLK_SZ) {

for (i = 0; i < klen; i++) {

ctx->inner[i] ^= key[i];

ctx->outer[i] ^= key[i];

}

} else {

DGST_Update(&(ctx->mdctx), key, klen);

DGST_Final(dk, &(ctx->mdctx));

DGST_Reset(&(ctx->mdctx));

for (i = 0; i < DGST_OUT_SZ; i++) {

ctx->inner[i] ^= dk[i];

ctx->outer[i] ^= dk[i];

}

}

DGST_Update(&(ctx->mdctx), ctx->inner, DGST_BLK_SZ);

}

void SPC_HMAC_Reset(SPC_HMAC_CTX *ctx) {

DGST_Reset(&(ctx->mdctx));

DGST_Update(&(ctx->mdctx), ctx->inner, DGST_BLK_SZ);

}

void SPC_HMAC_Update(SPC_HMAC_CTX *ctx, unsigned char *m, size_t l) {

DGST_Update(&(ctx->mdctx), m, l);

}

void SPC_HMAC_Final(unsigned char *tag, SPC_HMAC_CTX *ctx) {

unsigned char is[DGST_OUT_SZ];

DGST_Final(is, &(ctx->mdctx));

DGST_Reset(&(ctx->mdctx));

DGST_Update(&(ctx->mdctx), ctx->outer, DGST_BLK_SZ);

DGST_Update(&(ctx->mdctx), is, DGST_OUT_SZ);

DGST_Final(tag, &(ctx->mdctx));

}

void SPC_HMAC_Cleanup(SPC_HMAC_CTX *ctx) {

volatile char *p = ctx->inner;

volatile char *q = ctx->outer;

int i;

for (i = 0; i < DGST_BLK_SZ; i++) *p++ = *q++ = 0;

}

The previous code does require a particular interface to a hash function interface. First, it requires two constants: DGST_BLK_SZ, which is the internal block size of the underlying hash function (see Recipe 6.3), and DGST_OUT_SZ, which is the size of the resulting message digest. Second, it requires a context type for the message digest, which you should typedef to DGST_CTX. Finally, it requires an incremental interface to the hash function:

void DGST_Init(DGST_CTX *ctx);

void DGST_Reset(DGST_CTX *ctx);

void DGST_Update(DGST_CTX *ctx, unsigned char *m, size_t len);

void DGST_Final(unsigned char *tag. DGST_CTX *ctx);

Some hash function implementations won't have an explicit reset implementation, in which case you can implement the reset functionality by calling DGST_Init( ) again.

Even though OpenSSL already has an HMAC implementation, here is an example of binding the previous HMAC implementation to OpenSSL's SHA1 implementation:

typedef SHA_CTX DGST_CTX;

#define DGST_BLK_SZ 64

#define DGST_OUT_SZ 20

#define DGST_Init(x) SHA1_Init(x)

#define DGST_Reset(x) DGST_Init(x)

#define DGST_Update(x, m, l) SHA1_Update(x, m, l)

#define DGST_Final(o, x) SHA1_Final(o, x)

See Also

Recipe 5.26, Recipe 6.3, Recipe 6.4, Recipe 6.9

6.11. Using OMAC (a Simple Block Cipher-Based MAC)

Problem

You want to use a simple MAC based on a block cipher, such as AES.

Solution

Use the OMAC implementation provided in Section 6.11.3.

Discussion

TIP

Be sure to look at our generic recommendations for using a MAC (see Recipe 6.9).

OMAC is a straightforward message authentication algorithm based on the CBC-encryption mode. It fixes some security problems with the naïve implementation of a MAC from CBC mode (CBC-MAC). In particular, that MAC is susceptible to length-extension attacks, similar to the ones we consider for cryptographic hash functions in Recipe 6.7.

OMAC has been explicitly specified for AES, and it is easy to adapt to any 128-bit block cipher. It is possible, but a bit more work, to get it working with ciphers with 64-bit blocks. In this section, we only cover using OMAC with AES.

The basic idea behind using CBC mode as a MAC is to encrypt a message in CBC mode and throw away everything except the very last block of output. That's not generally secure, though. It only works when all messages you might possibly process are a particular size.

Besides OMAC, there are several MACs that try to fix the CBC-MAC problem, including XCBC-MAC, TMAC, and RMAC:

RMAC

RMAC (the R stands for randomized) has security issues in the general case, and is not favored by the cryptographic community.^[6^]

XCBC-MAC

XCBC-MAC (eXtended CBC-MAC) is the foundation for TMAC and OMAC, but it uses three different keys.

TMAC

TMAC uses two keys (thus the T in the name).

OMAC is the first good CBC-MAC derivative that uses a single key. OMAC works the same way CBC-MAC does until the last block, where it XORs the state with an additional value before encrypting. That additional value is derived from the result of encrypting all zeros, and it can be performed at key setup time. That is, the additional value is key-dependent, not message-dependent.

OMAC is actually the name of a family of MAC algorithms. There are two concrete versions, OMAC1 and OMAC2, which are slightly different but equally secure. OMAC1 is slightly preferable because its key setup can be done a few cycles more quickly than OMAC2's key setup. NIST is expected to standardize on OMAC1.

First, we provide an incremental API for using OMAC. This code requires linking against an AES implementation, and also that the macros developed in Recipe 5.5 be defined (they bridge the API of your AES implementation with this book's API). The secure memory function spc_memset( )from Recipe 13.2 is also required.

To use this API, you must instantiate an SPC_OMAC_CTX object and pass it to the various API functions. To initialize the context, call either spc_omac1_init( ) or spc_omac2_init( ) , depending on whether you want to use OMAC1 or OMAC2. The initialization functions always return success unless the key length is invalid, in which case they return 0. Successful initialization is indicated by a return value of 1.

int spc_omac1_init(SPC_OMAC_CTX *ctx, unsigned char *key, int keylen);

int spc_omac2_init(SPC_OMAC_CTX *ctx, unsigned char *key, int keylen);

These functions have the following arguments:

ctx

Context object to be initialized.

key

Block cipher key.

keylen

Length of the key in bytes. The length of the key must be 16, 24, or 32 bytes; any other key length is invalid.

Once initialized, spc_omac_update( ) can be used to process data. Note that the only differences between OMAC1 and OMAC2 in this implementation are handled at key setup time, so they both use the same functions for updating and finalization. Multiple calls to spc_omac_update( ) act just like making a single call where all of the data was concatenated together. Here is its signature:

void spc_omac_update(SPC_OMAC_CTX *ctx, unsigned char *in, size_t il);

This function has the following arguments:

ctx

Context object to use for the current message.

in

Buffer that contains the data to be processed.

il

Length of the data buffer to be processed in bytes.

To obtain the output of the MAC operation, call spc_omac_final( ) , which has the following signature:

int spc_omac_final(SPC_OMAC_CTX *ctx, unsigned char *out);

This function has the following arguments:

ctx

Context object to be finalized.

out

Buffer into which the output will be placed. This buffer must be at least 16 bytes in size. No more than 16 bytes will ever be written to it.

Here is the code implementing OMAC:

#include <stdlib.h>

typedef struct {

SPC_KEY_SCHED ks;

int ix;

unsigned char iv[SPC_BLOCK_SZ];

unsigned char c1[SPC_BLOCK_SZ]; /* L * u */

unsigned char c2[SPC_BLOCK_SZ]; /* L / u */

} SPC_OMAC_CTX;

int spc_omac1_init(SPC_OMAC_CTX *ctx, unsigned char *key, int keylen) {

int condition, i;

unsigned char L[SPC_BLOCK_SZ] = {0,};

if (keylen != 16 && keylen != 24 && keylen != 32) return 0;

SPC_ENCRYPT_INIT(&(ctx->ks), key, keylen);

SPC_DO_ENCRYPT(&(ctx->ks), L, L);

spc_memset(ctx->iv, 0, SPC_BLOCK_SZ);

ctx->ix = 0;

/* Compute L * u */

condition = L[0] & 0x80;

ctx->c1[0] = L[0] << 1;

for (i = 1; i < SPC_BLOCK_SZ; i++) {

ctx->c1[i - 1] |= L[i] >> 7;

ctx->c1[i] = L[i] << 1;

}

if (condition) ctx->c1[SPC_BLOCK_SZ - 1] ^= 0x87;

/* Compute L * u * u */

condition = ctx->c1[0] & 0x80;

ctx->c2[0] = ctx->c1[0] << 1;

for (i = 1; i < SPC_BLOCK_SZ; i++) {

ctx->c2[i - 1] |= ctx->c1[i] >> 7;

ctx->c2[i] = ctx->c1[i] << 1;

}

if (condition) ctx->c2[SPC_BLOCK_SZ - 1] ^= 0x87;

spc_memset(L, 0, SPC_BLOCK_SZ);

return 1;

}

int spc_omac2_init(SPC_OMAC_CTX *ctx, unsigned char *key, int keylen) {

int condition, i;

unsigned char L[SPC_BLOCK_SZ] = {0,};

if (keylen != 16 && keylen != 24 && keylen != 32) return 0;

SPC_ENCRYPT_INIT(&(ctx->ks), key, keylen);

SPC_DO_ENCRYPT(&(ctx->ks), L, L);

spc_memset(ctx->iv, 0, SPC_BLOCK_SZ);

ctx->ix = 0;

/* Compute L * u, storing it in c1 */

condition = L[0] >> 7;

ctx->c1[0] = L[0] << 1;

for (i = 1; i < SPC_BLOCK_SZ; i++) {

ctx->c1[i - 1] |= L[i] >> 7;

ctx->c1[i] = L[i] << 1;

}

if (condition) ctx->c1[SPC_BLOCK_SZ - 1] ^= 0x87;

/* Compute L * u ^ -1, storing it in c2 */

condition = L[SPC_BLOCK_SZ - 1] & 0x01;

i = SPC_BLOCK_SZ;

while (--i) ctx->c2[i] = (L[i] >> 1) | (L[i - 1] << 7);

ctx->c2[0] = L[0] >> 1;

L[0] >>= 1;

if (condition) {

ctx->c2[0] ^= 0x80;

ctx->c2[SPC_BLOCK_SZ - 1] ^= 0x43;

}

spc_memset(L, 0, SPC_BLOCK_SZ);

return 1;

}

void spc_omac_update(SPC_OMAC_CTX *ctx, unsigned char *in, size_t il) {

int i;

if (il < SPC_BLOCK_SZ - ctx->ix) {

while (il--) ctx->iv[ctx->ix++] ^= *in++;

return;

}

if (ctx->ix) {

while (ctx->ix < SPC_BLOCK_SZ) --il, ctx->iv[ctx->ix++] ^= *in;

SPC_DO_ENCRYPT(&(ctx->ks), ctx->iv, ctx->iv);

}

while (il > SPC_BLOCK_SZ) {

for (i = 0; i < SPC_BLOCK_SZ / sizeof(int); i++)

((unsigned int *)(ctx->iv))[i] ^= ((unsigned int *)in)[i];

SPC_DO_ENCRYPT(&(ctx->ks), ctx->iv, ctx->iv);

in += SPC_BLOCK_SZ;

il -= SPC_BLOCK_SZ;

}

for (i = 0; i < il; i++) ctx->iv[i] ^= in[i];

ctx->ix = il;

}

int spc_omac_final(SPC_OMAC_CTX *ctx, unsigned char *out) {

int i;

if (ctx->ix != SPC_BLOCK_SZ) {

ctx->iv[ctx->ix] ^= 0x80;

for (i = 0; i < SPC_BLOCK_SZ / sizeof(int); i++)

((int *)ctx->iv)[i] ^= ((int *)ctx->c2)[i];

} else {

for (i = 0; i < SPC_BLOCK_SZ / sizeof(int); i++)

((int *)ctx->iv)[i] ^= ((int *)ctx->c1)[i];

}

SPC_DO_ENCRYPT(&(ctx->ks), ctx->iv, out);

return 1;

}

For those interested in the algorithm itself, note that we precompute two special values at key setup time, both of which are derived from the value we get from encrypting the all-zero data block. Each precomputed value is computed by using a 128-bit shift and a conditional XOR. The last block of data is padded, if necessary, and XOR'd with one of these two values, depending on its length.

Here is an all-in-one wrapper to OMAC, exporting both OMAC1 and OMAC2:

int SPC_OMAC1(unsigned char key[ ], int keylen, unsigned char in[ ], size_t l,

unsigned char out[16]) {

SPC_OMAC_CTX c;

if (!spc_omac1_init(&c, key, keylen)) return 0;

spc_omac_update(&c, in, l);

spc_omac_final(&c, out);

return 1;

}

int SPC_OMAC2(unsigned char key[ ], int keylen, unsigned char in[ ], size_t l,

unsigned char out[16]) {

SPC_OMAC_CTX c;

if (!spc_omac2_init(&c, key, keylen)) return 0;

spc_omac_update(&c, in, l);

spc_omac_final(&c, out);

return 1;

}

See Also

Recipe 5.5, Recipe 6.7, Recipe 6.9, Recipe 13.2