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

---

^[14^] EVP stands for "envelope."

5.18. Using Variable Key-Length Ciphers in OpenSSL

Problem

You're using a cipher with an adjustable key length, yet OpenSSL provides no default cipher configuration for your desired key length.

Solution

Initialize the cipher without a key, call EVP_CIPHER_CTX_set_key_length( ) to set the appropriate key length, then set the key.

Discussion

Many of the ciphers supported by OpenSSL support variable key lengths. Whereas some, such as AES, have an available call for each possible key length, others (in particular, RC4) allow for nearly arbitrary byte-aligned keys. Table 5-7 lists ciphers supported by OpenSSL, and the varying key lengths those ciphers can support.

Table 5-7. Variable key sizes

Cipher	OpenSSL-supported key sizes	Algorithm's possible key sizes
AES	128, 192, and 256 bits	128, 192, and 256 bits
Blowfish	Up to 256 bits	Up to 448 bits
CAST5	40-128 bits	40-128 bits
RC2	Up to 256 bits	Up to 1,024 bits
RC4	Up to 256 bits	Up to 2,048 bits
RC5	Up to 256 bits	Up to 2,040 bits

While RC2, RC4, and RC5 support absurdly high key lengths, it really is overkill to use more than a 256-bit symmetric key. There is not likely to be any greater security, only less efficiency. Therefore, OpenSSL puts a hard limit of 256 bits on key sizes.

When calling the OpenSSL cipher initialization functions, you can set to NULL any value you do not want to provide immediately. If the cipher requires data you have not yet provided, clearly encryption will not work properly.

Therefore, we can choose a cipher using EVP_EncryptInit_ex( ) without specifying a key, then set the key size using EVP_CIPHER_CTX_set_key_length( ) , which takes two arguments: the first is the context initialized by the call to EVP_EncryptInit_ex( ), and the second is the new key length in bytes.

Finally, we can set the key by calling EVP_EncryptInit_ex( ) again, passing in the context and any new data, along with NULL for any parameters we've already set. For example, the following code would set up a 256-bit version of Blowfish in CBC mode:

#include <openssl/evp.h>

EVP_CIPHER_CTX *blowfish_256_cbc_setup(char *key, char *iv) {

EVP_CIPHER_CTX *ctx;

if (!(ctx = (EVP_CIPHER_CTX *)malloc(sizeof(EVP_CIPHER_CTX)))) return 0;

EVP_CIPHER_CTX_init(ctx);

/* Uses 128-bit keys by default. We pass in NULLs for the parameters that we'll

* fill in after properly setting the key length.

*/

EVP_EncryptInit_ex(ctx, EVP_bf_cbc( ), 0, 0, 0);

EVP_CIPHER_CTX_set_key_length(ctx, 32);

EVP_EncryptInit_ex(ctx, 0, 0, key, iv);

return ctx;

}

5.19. Disabling Cipher Padding in OpenSSL in CBC Mode

Problem

You're encrypting in CBC or ECB mode, and the length of your data to encrypt is always a multiple of the block size. You would like to avoid padding because it adds an extra, unnecessary block of output.

Solution

OpenSSL has a function that can turn padding on and off for a context object:

int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *ctx, int pad);

Discussion

Particularly when you are implementing another encryption mode, you may always be operating on block-sized chunks, and it can be inconvenient to deal with padding. Alternatively, some odd protocol may require a nonstandard padding scheme that causes you to pad the data manually before encryption (and to remove the pad manually after encryption).

The second argument of this function should be zero to turn padding off, and non-zero to turn it on.

5.20. Performing Additional Cipher Setup in OpenSSL

Problem

Using OpenSSL, you want to adjust a configurable parameter of a cipher other than the key length.

Solution

OpenSSL provides an obtuse, ioctl()-style API for setting uncommon cipher parameters on a context object:

int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr);

Discussion

OpenSSL doesn't provide much flexibility in adjusting cipher characteristics. For example, the three AES configurations are three specific instantiations of a cipher called Rijndael, which has nine different configurations. However, OpenSSL supports only the three standard ones.

Nevertheless, there are two cases in which OpenSSL does allow for configurability. In the first case, it allows for setting the "effective key bits" in RC2. As a result, the RC2 key is crippled so that it is only as strong as the effective size set. We feel that this functionality is completely useless.

In the second case, OpenSSL allows you to set the number of rounds used internally by the RC5 algorithm. By default, RC5 uses 12 rounds. And while the algorithm should take absolutely variable-length rounds, OpenSSL allows you to set the number only to 8, 12, or 16.

The function EVP_CIPHER_CTX_ctrl( ) can be used to set or query either of these values, given a cipher of the appropriate type. This function has the following arguments:

ctx

Pointer to the cipher context to be modified.

type

Value indicating which operation to perform (more on this a little later).

arg

Numerical value to set, if appropriate (it is otherwise ignored).

ptr

Pointer to an integer for querying the numerical value of a property, if appropriate (the result is placed in the integer being pointed to).

The type argument can be one of the four macros defined in openssl/evp.h:

EVP_CTRL_GET_RC2_KEY_BITS

EVP_CTRL_SET_RC2_KEY_BITS

EVP_CTRL_GET_RC5_ROUNDS

EVP_CTRL_SET_RC5_ROUNDS

For example, to set an RC5 context to use 16 rounds:

EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, 16, NULL);

To query the number of rounds, putting the result into an integer named r:

EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &r);

5.21. Querying Cipher Configuration Properties in OpenSSL

Problem

You want to get information about a particular cipher context in OpenSSL.

Solution

For most properties, OpenSSL provides macros for accessing them. For other things, we can access the members of the cipher context structure directly.

To get the actual object representing the cipher:

EVP_CIPHER *EVP_CIPHER_CTX_cipher(EVP_CIPHER_CTX *ctx);

To get the block size of the cipher:

int EVP_CIPHER_CTX_block_size(EVP_CIPHER_CTX *ctx);

To get the key length of the cipher:

int EVP_CIPHER_CTX_key_length(EVP_CIPHER_CTX *ctx);

To get the length of the initialization vector:

int EVP_CIPHER_CTX_iv_length(EVP_CIPHER_CTX *ctx);

To get the cipher mode being used:

int EVP_CIPHER_CTX_mode(EVP_CIPHER_CTX *ctx);

To see if automatic padding is disabled:

int pad = (ctx->flags & EVP_CIPH_NO_PADDING);

To see if we are encrypting or decrypting:

int encr = (ctx->encrypt);

To retrieve the original initialization vector:

char *iv = (ctx->oiv);

Discussion

The EVP_CIPHER_CTX_cipher( ) function is actually implemented as a macro that returns an object of type EVP_CIPHER. The cipher itself can be queried, but interesting queries can also be made on the context object through appropriate macros.

All functions returning lengths return them in bytes.

The EVP_CIPHER_CTX_mode( ) function returns one of the following predefined values:

EVP_CIPH_ECB_MODE

EVP_CIPH_CBC_MODE

EVP_CIPH_CFB_MODE

EVP_CIPH_OFB_MODE

5.22. Performing Low-Level Encryption and Decryption with OpenSSL

Problem

You have set up your cipher and want to perform encryption and decryption.

Solution

Use the following suite of functions:

int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl,

unsigned char *in, int inl);

int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);

int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl,

unsigned char *in, int inl);

int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);

Discussion

WARNING

As a reminder, use a raw mode only if you really know what you're doing. For general-purpose use, we recommend a high-level abstraction, such as that discussed in Recipe 5.16. Additionally, be sure to include some sort of integrity validation whenever encrypting, as we discuss throughout Chapter 6.

The signatures for the encryption and decryption routines are identical, and the actual routines are completely symmetric. Therefore, we'll only discuss the behavior of the encryption functions, and you can infer the behavior of the decryption functions from that.

EVP_EncryptUpdate( ) has the following arguments:

ctx

Pointer to the cipher context previously initialized with EVP_EncryptInit_ex( ).

out

Buffer into which any output is placed.

outl

Pointer to an integer, into which the number of bytes written to the output buffer is placed.

in

Buffer containing the data to be encrypted.

inl

Number of bytes contained in the input buffer.

EVP_EncryptFinal_ex( ) takes the following arguments:

ctx

Pointer to the cipher context previously initialized with EVP_EncryptInit_ex( ).

out

Buffer into which any output is placed.

outl

Pointer to an integer, into which the number of bytes written to the output buffer is placed.

There are two phases to encryption in OpenSSL: update, and finalization. The basic idea behind update mode is that you're feeding in data to encrypt, and if there's incremental output, you get it. Calling the finalization routine lets OpenSSL know that all the data to be encrypted with this current context has already been given to the library. OpenSSL then does any cleanup work necessary, and it will sometimes produce additional output. After a cipher is finalized, you need to reinitialize it if you plan to reuse it, as described in Recipe 5.17.

In CBC and ECB modes, the cipher cannot always encrypt all the plaintext you give it as that plaintext arrives, because it requires block-aligned data to operate. In the finalization phase, those algorithms add padding if appropriate, then yield the remaining output. Note that, because of the internal buffering that can happen in these modes, the output to any single call of EVP_EncryptUpdate( ) or EVP_EncryptFinal_ex( ) can be about a full block larger or smaller than the actual input. If you're encrypting data into a single buffer, you can always avoid overflow if you make the output buffer an entire block bigger than the input buffer. Remember, however, that if padding is turned off (as described in Recipe 5.19), the library will be expecting block-aligned data, and the output will always be the same size as the input.

In OFB and CFB modes, the call to EVP_EncryptUpdate( ) will always return the amount of data you passed in, and EVP_EncryptFinal_ex( ) will never return any data. This is because these modes are stream-based modes that don't require aligned data to operate. Therefore, it is sufficient to call only EVP_EncryptUpdate( ), skipping finalization entirely. Nonetheless, you should always call the finalization function so that the library has the chance to do any internal cleanup that may be necessary. For example, if you're using a cryptographic accelerator, the finalization call essentially gives the hardware license to free up resources for other operations.

These functions all return 1 on success, and 0 on failure. EVP_EncryptFinal_ex( ) will fail if padding is turned off and the data is not block-aligned. EVP_DecryptFinal_ex( ) will fail if the decrypted padding is not in the proper format. Additionally, any of these functions may fail if they are using hardware acceleration and the underlying hardware throws an error. Beyond those problems, they should not fail. Note again that when decrypting, this API has no way of determining whether the data decrypted properly. That is, the data may have been modified in transit; other means are necessary to ensure integrity (i.e., use a MAC, as we discuss throughout Chapter 6).

Here's an example function that, when given an already instantiated cipher context, encrypts an entire plaintext message 100 bytes at a time into a single heap-allocated buffer, which is returned at the end of the function. This example demonstrates how you can perform multiple encryption operations over time and keep encrypting into a single buffer. This code will work properly with any of the OpenSSL-supported cipher modes.

#include <stdlib.h>

#include <openssl/evp.h>

/* The integer pointed to by rb receives the number of bytes in the output.

* Note that the malloced buffer can be realloced right before the return.

*/

char *encrypt_example(EVP_CIPHER_CTX *ctx, char *data, int inl, int *rb) {

int i, ol, tmp;

char *ret;

ol = 0;

if (!(ret = (char *)malloc(inl + EVP_CIPHER_CTX_block_size(ctx)))) abort( );

for (i = 0; i < inl / 100; i++) {

if (!EVP_EncryptUpdate(ctx, &ret[ol], &tmp, &data[ol], 100)) abort( );

ol += tmp;

}

if (inl % 100) {

if (!EVP_EncryptUpdate(ctx, &ret[ol], &tmp, &data[ol], inl % 100)) abort( );

ol += tmp;

}

if (!EVP_EncryptFinal_ex(ctx, &ret[ol], &tmp)) abort( );

ol += tmp;

if (rb) *rb = ol;

return ret;

}

Here's a simple function for decryption that decrypts an entire message at once:

#include <stdlib.h>

#include <openssl/evp.h>

char *decrypt_example(EVP_CIPHER_CTX *ctx, char *ct, int inl) {

/* We're going to null-terminate the plaintext under the assumption that it's

* non-null terminated ASCII text. The null can otherwise be ignored if it

* wasn't necessary, though the length of the result should be passed back in

* such a case.

*/

int ol;

char *pt;

if (!(pt = (char *)malloc(inl + EVP_CIPHER_CTX_block_size(ctx) + 1))) abort( );

EVP_DecryptUpdate(ctx, pt, &ol, ct, inl);

if (!ol) { /* There is no data to decrypt */

free(pt);

return 0;

}

pt[ol] = 0;

return pt;

}

See Also

Recipe 5.16, Recipe 5.17

5.23. Setting Up and Using RC4

Problem

You want to use RC4 securely.

Solution

You can't be very confident about the security of RC4 for general-purpose use, owing to theoretical weaknesses. However, if you're willing to use only a very few RC4 outputs (a limit of about 100,000 bytes of output), you can take a risk, as long as you properly set it up.

Before using the standard initialization functions provided by your cryptographic library, take one of the following two steps:

§ Cryptographically hash the key material before using it.

§ Discard the first 256 bytes of the generated keystream.

After initialization, RC4 is used just as any block cipher in a streaming mode is used.

Most libraries implement RC4, but it is so simple that we provide an implementation in the following section.

Discussion

RC4 is a simple cipher that is really easy to use once you have it set up securely, which is actually difficult to do! Due to this key-setup problem, RC4's theoretical weaknesses, and the availability of faster solutions that look more secure, we recommend you just not use RC4. If you're looking for a very fast solution, we recommend SNOW 2.0.

In this recipe, we'll start off ignoring the RC4 key-setup problem. We'll show you how to use RC4 properly, giving a complete implementation. Then, after all that, we'll discuss how to set it up securely.

WARNING

As with any other symmetric encryption algorithm, it is particularly important to use a MAC along with RC4 to ensure data integrity. We discuss MACs extensively in Chapter 6.

RC4 requires a little bit of state, including a 256-byte buffer and two 8-bit counters. Here's a declaration for an RC4_CTX data type:

typedef struct {

unsigned char sbox[256];

unsigned char i, j;

} RC4_CTX;

In OpenSSL, the same sort of context is named RC4_KEY, which is a bit of a misnomer. Throughout this recipe, we will use RC4_CTX, but our implementation is otherwise compatible with OpenSSL's (our functions have the same names and parameters). You'll only need to include the correct header file, and alias RC4_CTX to RC4_KEY.

The "official" RC4 key setup function isn't generally secure without additional work, but we need to have it around anyway:

#include <stdlib.h>

void RC4_set_key(RC4_CTX *c, size_t keybytes, unsigned char *key) {

int i, j;

unsigned char keyarr[256], swap;

c->i = c->j = 0;

for (i = j = 0; i < 256; i++, j = (j + 1) % keybytes) {

c->sbox[i] = i;

keyarr[i] = key[j];

}

for (i = j = 0; i < 256; i++) {

j += c->sbox[i] + keyarr[i];

j %= 256;

swap = c->sbox[i];

c->sbox[i] = c->sbox[j];

c->sbox[j] = swap;

}

}

The RC4 function has the following arguments:

c

Pointer to an RC4_CTX object.

n

Number of bytes to encrypt.

in

Buffer to encrypt.

out

Output buffer.

void RC4(RC4_CTX *c, size_t n, unsigned char *in, unsigned char *out) {

unsigned char swap;

while (n--) {

c->j += c->sbox[++c->i];

swap = c->sbox[c->i];

c->sbox[c->i] = c->sbox[c->j];

c->sbox[c->j] = swap;

swap = c->sbox[c->i] + c->sbox[c->j];

*out++ = *in++ ^ c->sbox[swap];

}

}

That's it for an RC4 implementation. This function can be used incrementally or as an "all-in-one" solution.

Now let's look at how to key RC4 properly.

Without going into the technical details of the problems with RC4 key setup, it's sufficient to say that the real problem occurs when you key multiple RC4 instances with related keys. For example, in some circles it is common to use a truncated base key, then concatenate a counter for each message (which is not a good idea in and of itself because it reduces the effective key strength).

The first way to solve this problem is to use a cryptographic hash function to randomize the key. If your key is 128 bits, you can use MD5 and take the entire digest value, or you can use a hash function with a larger digest, such as SHA1 or SHA-256, truncating the result to the appropriate size.

Here's some code for setting up an RC4 context by hashing key material using MD5 (include openssl/md5.h to have this work directly with OpenSSL's implementation). MD5 is fine for this purpose; you can also use SHA1 and truncate to 16 bytes.

/* Assumes you have not yet initialized the context, but have allocated it. */

void secure_rc4_setup1(RC4_CTX *ctx, char *key) {

char res[16]; /* 16 is the size in bytes of the resulting MD5 digest. */

MD5(key, 16, res);

RC4_set_key(ctx, 16, res);

}

Note that RC4 does not use an initialization vector.

Another option is to start using RC4, but throw away the first 256 bytes worth of keystream. One easy way to do that is to encrypt 256 bits of garbage and ignore the results:

/* Assumes an already instantiated RC4 context. */

void secure_rc4_setup2(RC4_CTX *ctx) {

char buf[256] = {0,};

RC4(ctx, sizeof(buf), buf, buf);

spc_memset(buf, 0, sizeof(buf));

}

5.24. Using One-Time Pads

Problem

You want to use an encryption algorithm that has provable secrecy properties, and deploy it in a fashion that does not destroy the security properties of the algorithm.

Solution

Settle for more realistic security goals. Do not use a one-time pad.

Discussion

One-time pads are provably secure if implemented properly. Unfortunately, they are rarely used properly. A one-time pad is very much like a stream cipher. Encryption is simply XOR'ing the message with the keystream. The security comes from having every single bit of the keystream be truly random instead of merely cryptographically random. If portions of the keystream are reused, the security of data encrypted with those portions is incredibly weak.

There are a number of big hurdles when using one-time pads:

§ It is very close to impossible to generate a truly random keystream in software. (See Chapter 11 for more information.)

§ The keystream must somehow be shared between client and server. Because there can be no algorithm to produce the keystream, some entity will need to produce the keystream and transmit it securely to both parties.

§ The keystream must be as long as the message. If you have a message that's bigger than the keystream you have remaining, you can't send the entire message.

§ Integrity checking is just as important with one-time pads as with any other encryption technique. As with the output of any stream cipher, if you modify a bit in the ciphertext generated by a one-time pad, the corresponding bit of the plaintext will flip. In addition, one-time pads have no built-in mechanism for detecting truncation or additive attacks. Message authentication in a provably secure manner essentially requires a keystream twice the data length.

Basically, the secure deployment of one-time pads is almost always highly impractical. You are generally far better off using a good high-level interface to encryption and decryption, such as the one provided in Recipe 5.16.

See Also

Recipe 5.16

5.25. Using Symmetric Encryption with Microsoft's CryptoAPI

Problem

You are developing an application that will run on Windows and make use of symmetric encryption. You want to use Microsoft's CryptoAPI.

Solution

Microsoft's CryptoAPI is available on most versions of Windows that are widely deployed, so it is a reasonable solution for many uses of symmetric encryption. CryptoAPI contains a small, yet nearly complete, set of functions for creating and manipulating symmetric encryption keys (which the Microsoft documentation usually refers to as session keys ), exchanging keys, and encrypting and decrypting data. While the information in the following Section 5.25.3 will not provide you with all the finer details of using CryptoAPI, it will give you enough background to get started using the API successfully.

Discussion

CryptoAPI is designed as a high-level interface to various cryptographic constructs, including hashes, MACs, public key encryption, and symmetric encryption. Its support for public key cryptography makes up the majority of the API, but there is also a small subset of functions for symmetric encryption.

Before you can do anything with CryptoAPI, you first need to acquire a provider context. CryptoAPI provides a generic API that wraps around Cryptographic Service Providers (CSPs), which are responsible for doing all the real work. Microsoft provides several different CSPs that provide implementations of various algorithms. For symmetric cryptography, two CSPs are widely available and of interest: Microsoft Base Cryptographic Service Provider and Microsoft Enhanced Cryptographic Service Provider. A third, Microsoft AES Cryptographic Service Provider, is available only in the .NET framework. The Base CSP provides RC2, RC4, and DES implementations. The Enhanced CSP adds implementations for DES, two-key Triple-DES, and three-key Triple-DES. The AES CSP adds implementations for AES with 128-bit, 192-bit, and 256-bit key lengths.

For our purposes, we'll concentrate only on the enhanced CSP. Acquiring a provider context is done with the following code. We use the CRYPT_VERIFYCONTEXT flag here because we will not be using private keys with the context. It doesn't necessarily hurt to omit the flag (which we will do inRecipe 5.26 and Recipe 5.27, for example), but if you don't need public key access with the context, you should use the flag. Some CSPs may require user input when CryptAcquireContext( ) is called without CRYPT_VERIFYCONTEXT.

#include <windows.h>

#include <wincrypt.h>

HCRYPTPROV SpcGetCryptContext(void) {

HCRYPTPROV hProvider;

if (!CryptAcquireContext(&hProvider, 0, MS_ENHANCED_PROV, PROV_RSA_FULL,

CRYPT_VERIFYCONTEXT)) return 0;

return hProvider;

}

Once a provider context has been successfully acquired, you need a key. The API provides three ways to obtain a key object, which is stored by CryptoAPI as an opaque object to which you'll have only a handle:

CryptGenKey( )

Generates a random key.

CryptDeriveKey( )

Derives a key from a password or passphrase.

CryptImportKey( )

Creates a key object from key data in a buffer.

All three functions return a new key object that keeps the key data hidden and has associated with it a symmetric encryption algorithm and a set of flags that control the behavior of the key. The key data can be obtained from the key object using CryptExportKey( ) if the key object allows it. The CryptExportKey( ) and CryptImportKey( ) functions provide the means for exchanging keys.

NOTE

The CryptExportKey( ) function will only allow you to export a symmetric encryption key encrypted with another key. For maximum portability across all versions of Windows, a public key should be used. However, Windows 2000 introduced the ability to encrypt the symmetric encryption key with another symmetric encryption key. Similarly, CryptImportKey( ) can only import symmetric encryption keys that are encrypted.

If you need the raw key data, you must first export the key in encrypted form, then decrypt from it (see Recipe 5.27). While this may seem like a lot of extra work, the reason is that CryptoAPI was designed with the goal of making it very difficult (if not impossible) to unintentionally disclose sensitive information.

Generating a new key with CryptGenKey( ) that can be exported is very simple, as illustrated in the following code. If you don't want the new key to be exportable, simply remove the CRYPT_EXPORTABLE flag.

HCRYPTKEY SpcGetRandomKey(HCRYPTPROV hProvider, ALG_ID Algid, DWORD dwSize) {

DWORD dwFlags;

HCRYPTKEY hKey;

dwFlags = ((dwSize << 16) & 0xFFFF0000) | CRYPT_EXPORTABLE;

if (!CryptGenKey(hProvider, Algid, dwFlags, &hKey)) return 0;

return hKey;

}

Deriving a key with CryptDeriveKey( ) is a little more complex. It requires a hash object to be created and passed into it in addition to the same arguments required by CryptGenKey( ). Note that once the hash object has been used to derive a key, additional data cannot be added to it, and it should be immediately destroyed.

HCRYPTKEY SpcGetDerivedKey(HCRYPTPROV hProvider, ALG_ID Algid, LPTSTR password) {

BOOL bResult;

DWORD cbData;

HCRYPTKEY hKey;

HCRYPTHASH hHash;

if (!CryptCreateHash(hProvider, CALG_SHA1, 0, 0, &hHash)) return 0;

cbData = lstrlen(password) * sizeof(TCHAR);

if (!CryptHashData(hHash, (BYTE *)password, cbData, 0)) {

CryptDestroyHash(hHash);

return 0;

}

bResult = CryptDeriveKey(hProvider, Algid, hHash, CRYPT_EXPORTABLE, &hKey);

CryptDestroyHash(hHash);

return (bResult ? hKey : 0);

}

Importing a key with CryptImportKey( ) is, in most cases, just as easy as generating a new random key. Most often, you'll be importing data obtained directly from CryptExportKey( ), so you'll already have an encrypted key in the form of a SIMPLEBLOB, as required by CryptImportKey( ). If you need to import raw key data, things get a whole lot trickier—see Recipe 5.26 for details.

HCRYPTKEY SpcImportKey(HCRYPTPROV hProvider, BYTE *pbData, DWORD dwDataLen,

HCRYPTKEY hPublicKey) {

HCRYPTKEY hKey;

if (!CryptImportKey(hProvider, pbData, dwDataLen, hPublicKey, CRYPT_EXPORTABLE,

&hKey)) return 0;

return hKey;

}

When a key object is created, the cipher to use is tied to that key, and it must be specified as an argument to either CryptGenKey( ) or CryptDeriveKey( ). It is not required as an argument by CryptImportKey( ) because the cipher information is stored as part of the SIMPLEBLOB structure that is required. Table 5-8 lists the symmetric ciphers that are available using one of the three Microsoft CSPs.

Table 5-8. Symmetric ciphers supported by Microsoft Cryptographic Service Providers

Cipher	Cryptographic Service Provider	ALG_ID constant	Key length	Block size
RC2	Base, Enhanced, AES	CALG_RC2	40 bits	64 bits
RC4	Base	CALG_RC4	40 bits	n/a
RC4	Enhanced, AES	CALG_RC4	128 bits	n/a
DES	Enhanced, AES	CALG_DES	56 bits	64 bits
2-key Triple-DES	Enhanced, AES	CALG_3DES_112	112 bits (effective)	64 bits
3-key Triple-DES	Enhanced, AES	CALG_3DES	168 bits (effective)	64 bits
AES	AES	CALG_AES_128	128 bits	128 bits
AES	AES	CALG_AES_192	192 bits	128 bits
AES	AES	CALG_AES_256	256 bits	128 bits

The default cipher mode to be used depends on the underlying CSP and the algorithm that's being used, but it's generally CBC mode. The Microsoft Base and Enhanced CSPs provide support for CBC, CFB, ECB, and OFB modes (see Recipe 5.4 for a discussion of cipher modes). The mode can be set using the CryptSetKeyParam( ) function:

BOOL SpcSetKeyMode(HCRYPTKEY hKey, DWORD dwMode) {

return CryptSetKeyParam(hKey, KP_MODE, (BYTE *)&dwMode, 0);

}

#define SpcSetMode_CBC(hKey) SpcSetKeyMode((hKey), CRYPT_MODE_CBC)

#define SpcSetMode_CFB(hKey) SpcSetKeyMode((hKey), CRYPT_MODE_CFB)

#define SpcSetMode_ECB(hKey) SpcSetKeyMode((hKey), CRYPT_MODE_ECB)

#define SpcSetMode_OFB(hKey) SpcSetKeyMode((hKey), CRYPT_MODE_OFB)

In addition, the initialization vector for block ciphers will be set to zero, which is almost certainly not what you want. The function presented below, SpcSetIV( ) , will allow you to set the IV for a key explicitly or will generate a random one for you. The IV should always be the same size as the block size for the cipher in use.

BOOL SpcSetIV(HCRYPTPROV hProvider, HCRYPTKEY hKey, BYTE *pbIV) {

BOOL bResult;

BYTE *pbTemp;

DWORD dwBlockLen, dwDataLen;

if (!pbIV) {

dwDataLen = sizeof(dwBlockLen);

if (!CryptGetKeyParam(hKey, KP_BLOCKLEN, (BYTE *)&dwBlockLen, &dwDataLen, 0))

return FALSE;

dwBlockLen /= 8;

if (!(pbTemp = (BYTE *)LocalAlloc(LMEM_FIXED, dwBlockLen))) return FALSE;

bResult = CryptGenRandom(hProvider, dwBlockLen, pbTemp);

if (bResult)

bResult = CryptSetKeyParam(hKey, KP_IV, pbTemp, 0);

LocalFree(pbTemp);

return bResult;

}

return CryptSetKeyParam(hKey, KP_IV, pbIV, 0);

}

Once you have a key object, it can be used for encrypting and decrypting data. Access to the low-level algorithm implementation is not permitted through CryptoAPI. Instead, a high-level OpenSSL EVP-like interface is provided (see Recipe 5.17 and Recipe 5.22 for details on OpenSSL's EVP API), though it's somewhat simpler. Both encryption and decryption can be done incrementally, but there is only a single function for each.

The CryptEncrypt( ) function is used to encrypt data all at once or incrementally. As a convenience, the function can also pass the plaintext to be encrypted to a hash object to compute the hash as data is passed through for encryption. CryptEncrypt( ) can be somewhat tricky to use because it places the resulting ciphertext into the same buffer as the plaintext. If you're using a stream cipher, this is no problem because the ciphertext is usually the same size as the plaintext, but if you're using a block cipher, the ciphertext can be up to a whole block longer than the plaintext. The following convenience function handles the buffering issues transparently for you. It requires the spc_memcpy( ) function from Recipe 13.2.

BYTE *SpcEncrypt(HCRYPTKEY hKey, BOOL bFinal, BYTE *pbData, DWORD *cbData) {

BYTE *pbResult;

DWORD dwBlockLen, dwDataLen;

ALG_ID Algid;

dwDataLen = sizeof(ALG_ID);

if (!CryptGetKeyParam(hKey, KP_ALGID, (BYTE *)&Algid, &dwDataLen, 0)) return 0;

if (GET_ALG_TYPE(Algid) != ALG_TYPE_STREAM) {

dwDataLen = sizeof(DWORD);

if (!CryptGetKeyParam(hKey, KP_BLOCKLEN, (BYTE *)&dwBlockLen, &dwDataLen, 0))

return 0;

dwDataLen = ((*cbData + (dwBlockLen * 2) - 1) / dwBlockLen) * dwBlockLen;

if (!(pbResult = (BYTE *)LocalAlloc(LMEM_FIXED, dwDataLen))) return 0;

CopyMemory(pbResult, pbData, *cbData);

if (!CryptEncrypt(hKey, 0, bFinal, 0, pbResult, &dwDataLen, *cbData)) {

LocalFree(pbResult);

return 0;

}

*cbData = dwDataLen;

return pbResult;

}

if (!(pbResult = (BYTE *)LocalAlloc(LMEM_FIXED, *cbData))) return 0;

CopyMemory(pbResult, pbData, *cbData);

if (!CryptEncrypt(hKey, 0, bFinal, 0, pbResult, cbData, *cbData)) {

LocalFree(pbResult);

return 0;

}

return pbResult;

}

The return from SpcEncrypt( ) will be a buffer allocated with LocalAlloc( ) that contains the ciphertext version of the plaintext that's passed as an argument into the function as pbData. If the function fails for some reason, the return from the function will be NULL, and a call to GetLastError( )will return the error code. This function has the following arguments:

hKey

Key to use for performing the encryption.

bFinal

Boolean value that should be passed as FALSE for incremental encryption except for the last piece of plaintext to be encrypted. To encrypt all at once, pass TRUE for bFinal in the single call to SpcEncrypt( ). When CryptEncrypt( ) gets the final plaintext to encrypt, it performs any cleanup that is needed to reset the key object back to a state where a new encryption or decryption operation can be performed with it.

pbData

Plaintext.

cbData

Pointer to a DWORD type that should hold the length of the plaintext pbData buffer. If the function returns successfully, it will be modified to hold the number of bytes returned in the ciphertext buffer.

Decryption works similarly to encryption. The function CryptDecrypt( ) performs decryption either all at once or incrementally, and it also supports the convenience function of passing plaintext data to a hash object to compute the hash of the plaintext as it is decrypted. The primary difference between encryption and decryption is that when decrypting, the plaintext will never be any longer than the ciphertext, so the handling of data buffers is less complicated. The following function, SpcDecrypt( ) , mirrors the SpcEncrypt( ) function presented previously.

BYTE *SpcDecrypt(HCRYPTKEY hKey, BOOL bFinal, BYTE *pbData, DWORD *cbData) {

BYTE *pbResult;

DWORD dwBlockLen, dwDataLen;

ALG_ID Algid;

dwDataLen = sizeof(ALG_ID);

if (!CryptGetKeyParam(hKey, KP_ALGID, (BYTE *)&Algid, &dwDataLen, 0)) return 0;

if (GET_ALG_TYPE(Algid) != ALG_TYPE_STREAM) {

dwDataLen = sizeof(DWORD);

if (!CryptGetKeyParam(hKey, KP_BLOCKLEN, (BYTE *)&dwBlockLen, &dwDataLen, 0))

return 0;

dwDataLen = ((*cbData + dwBlockLen - 1) / dwBlockLen) * dwBlockLen;

if (!(pbResult = (BYTE *)LocalAlloc(LMEM_FIXED, dwDataLen))) return 0;

} else {

if (!(pbResult = (BYTE *)LocalAlloc(LMEM_FIXED, *cbData))) return 0;

}

CopyMemory(pbResult, pbData, *cbData);

if (!CryptDecrypt(hKey, 0, bFinal, 0, pbResult, cbData)) {

LocalFree(pbResult);

return 0;

}

return pbResult;

}

Finally, when you're finished using a key object, be sure to destroy the object by calling CryptDestroyKey( ) and passing the handle to the object to be destroyed. Likewise, when you're done with a provider context, you must release it by calling CryptReleaseContext( ) .

See Also

Recipe 5.4, Recipe 5.17, Recipe 5.22, Recipe 5.26, Recipe 5.27, Recipe 13.2

5.26. Creating a CryptoAPI Key Object from Raw Key Data

Problem

You have a symmetric key from another API, such as OpenSSL, that you would like to use with CryptoAPI. Therefore, you must create a CryptoAPI key object with the key data.

Solution

The Microsoft CryptoAPI is designed to prevent unintentional disclosure of sensitive key information. To do this, key information is stored in opaque data objects by the Cryptographic Service Provider (CSP) used to create the key object. Key data is exportable from key objects, but the data must be encrypted with another key to prevent accidental disclosure of the raw key data.

Discussion

In Recipe 5.25, we created a convenience function, SpcGetCryptContext( ) , for obtaining a handle to a CSP context object. This function uses the CRYPT_VERIFYCONTEXT flag with the underlying CryptAcquireContext( ) function, which serves to prevent the use of private keys with the obtained context object. To be able to import and export symmetric encryption keys, you need to obtain a handle to a CSP context object without that flag, and use that CSP context object for creating the keys you wish to use. We'll create a new function called SpcGetExportableContext( ) that will return a CSP context object suitable for creating, importing, and exporting symmetric encryption keys.

#include <windows.h>

#include <wincrypt.h>

HCRYPTPROV SpcGetExportableContext(void) {

HCRYPTPROV hProvider;

if (!CryptAcquireContext(&hProvider, 0, MS_ENHANCED_PROV, PROV_RSA_FULL, 0)) {

if (GetLastError( ) != NTE_BAD_KEYSET) return 0;

if (!CryptAcquireContext(&hProvider, 0, MS_ENHANCED_PROV, PROV_RSA_FULL,

CRYPT_NEWKEYSET)) return 0;

}

return hProvider;

}

SpcGetExportableContext( ) will obtain a handle to the Microsoft Enhanced Cryptographic Service Provider that allows for the use of private keys. Public key pairs are stored in containers by the underlying CSP. This function will use the default container, creating it if it doesn't already exist.

Every public key container can have a special public key pair known as an exchange key , which is the key that we'll use to encrypt the exported key data. The function CryptGetUserKey( ) is used to obtain the exchange key. If it doesn't exist, SpcImportKeyData( ) , listed later in this section, will create a 1,024-bit exchange key, which will be stored as the exchange key in the public key container so future attempts to get the key will succeed. The special algorithm identifier AT_KEYEXCHANGE is used to reference the exchange key.

Symmetric keys are always imported via CryptImportKey( ) in "simple blob" format, specified by the SIMPLEBLOB constant passed to CryptImportKey( ). A simple blob is composed of a BLOBHEADER structure, followed by an ALG_ID for the algorithm used to encrypt the key data. The raw key data follows the BLOBHEADER and ALG_ID header information. To import the raw key data into a CryptoAPI key, a simple blob structure must be constructed and passed to CryptImportKey( ).

Finally, the raw key data must be encrypted using CryptEncrypt( ) and the exchange key. (The CryptEncrypt( ) function is described in more detail in Recipe 5.25.) The return from SpcImportKeyData( ) will be a handle to a CryptoAPI key object if the operation was performed successfully; otherwise, it will be 0. The CryptoAPI makes a copy of the key data internally in the key object it creates, so the key data passed into the function may be safely freed. The spc_memset( ) function from Recipe 13.2 is used here to destroy the unencrypted key data before returning.

HCRYPTKEY SpcImportKeyData(HCRYPTPROV hProvider, ALG_ID Algid, BYTE *pbKeyData,

DWORD cbKeyData) {

BOOL bResult = FALSE;

BYTE *pbData = 0;

DWORD cbData, cbHeaderLen, cbKeyLen, dwDataLen;

ALG_ID *pAlgid;

HCRYPTKEY hImpKey = 0, hKey;

BLOBHEADER *pBlob;

if (!CryptGetUserKey(hProvider, AT_KEYEXCHANGE, &hImpKey)) {

if (GetLastError( ) != NTE_NO_KEY) goto done;

if (!CryptGenKey(hProvider, AT_KEYEXCHANGE, (1024 << 16), &hImpKey))

goto done;

}

cbData = cbKeyData;

cbHeaderLen = sizeof(BLOBHEADER) + sizeof(ALG_ID);

if (!CryptEncrypt(hImpKey, 0, TRUE, 0, 0, &cbData, cbData)) goto done;

if (!(pbData = (BYTE *)LocalAlloc(LMEM_FIXED, cbData + cbHeaderLen)))

goto done;

CopyMemory(pbData + cbHeaderLen, pbKeyData, cbKeyData);

cbKeyLen = cbKeyData;

if (!CryptEncrypt(hImpKey, 0, TRUE, 0, pbData + cbHeaderLen, &cbKeyLen, cbData))

goto done;

pBlob = (BLOBHEADER *)pbData;

pAlgid = (ALG_ID *)(pbData + sizeof(BLOBHEADER));

pBlob->bType = SIMPLEBLOB;

pBlob->bVersion = 2;

pBlob->reserved = 0;

pBlob->aiKeyAlg = Algid;

dwDataLen = sizeof(ALG_ID);

if (!CryptGetKeyParam(hImpKey, KP_ALGID, (BYTE *)pAlgid, &dwDataLen, 0))

goto done;

bResult = CryptImportKey(hProvider, pbData, cbData + cbHeaderLen, hImpKey, 0,

&hKey);

if (bResult) spc_memset(pbKeyData, 0, cbKeyData);

done:

if (pbData) LocalFree(pbData);

CryptDestroyKey(hImpKey);

return (bResult ? hKey : 0);

}

See Also

Recipe 5.25, Recipe 13.2

5.27. Extracting Raw Key Data from a CryptoAPI Key Object

Problem

You have a symmetric key stored in a CryptoAPI key object that you want to use with another API, such as OpenSSL.

Solution

The Microsoft CryptoAPI is designed to prevent unintentional disclosure of sensitive key information. To do this, key information is stored in opaque data objects by the Cryptographic Service Provider (CSP) used to create the key object. Key data is exportable from key objects, but the data must be encrypted with another key to prevent accidental disclosure of the raw key data.

To extract the raw key data from a CryptoAPI key, you must first export the key using the CryptoAPI function CryptoExportKey( ) . The key data obtained from this function will be encrypted with another key, which you can then use to decrypt the encrypted key data to obtain the raw key data that another API, such as OpenSSL, can use.

Discussion

To export a key using the CryptoExportKey( ) function, you must provide the function with another key that will be used to encrypt the key data that's to be exported. Recipe 5.26 includes a function, SpcGetExportableContext( ), that obtains a handle to a CSP context object suitable for exporting keys created with it. The CSP context object uses a "container" to store public key pairs. Every public key container can have a special public key pair known as an exchange key, which is the key that we'll use to decrypt the exported key data.

The function CryptGetUserKey( ) is used to obtain the exchange key. If it doesn't exist, SpcExportKeyData( ) , listed later in this section, will create a 1,024-bit exchange key, which will be stored as the exchange key in the public key container so future attempts to get the key will succeed. The special algorithm identifier AT_KEYEXCHANGE is used to reference the exchange key.

Symmetric keys are always exported via CryptExportKey( ) in "simple blob" format, specified by the SIMPLEBLOB constant passed to CryptExportKey( ). The data returned in the buffer from CryptExportKey( ) will have a BLOBHEADER structure, followed by an ALG_ID for the algorithm used to encrypt the key data. The raw key data will follow the BLOBHEADER and ALG_ID header information. For extracting the raw key data from a CryptoAPI key, the data in the BLOBHEADER structure and the ALG_ID are of no interest, but you must be aware of their existence so that you can skip over them to find the encrypted key data.

Finally, the encrypted key data can be decrypted using CryptDecrypt( ) and the exchange key. The CryptDecrypt( ) function is described in more detail in Recipe 5.25. The decrypted data is the raw key data that can now be passed off to other APIs or used in protocols that already provide their own protection for the key. The return from SpcExportKeyData( ) will be a buffer allocated with LocalAlloc( ) that contains the unencrypted symmetric key if no errors occur; otherwise, NULL will be returned.

#include <windows.h>

#include <wincrypt.h>

BYTE *SpcExportKeyData(HCRYPTPROV hProvider, HCRYPTKEY hKey, DWORD *cbData) {

BOOL bResult = FALSE;

BYTE *pbData = 0, *pbKeyData;

HCRYPTKEY hExpKey = 0;

if (!CryptGetUserKey(hProvider, AT_KEYEXCHANGE, &hExpKey)) {

if (GetLastError( ) != NTE_NO_KEY) goto done;

if (!CryptGenKey(hProvider, AT_KEYEXCHANGE, (1024 << 16), &hExpKey))

goto done;

}

if (!CryptExportKey(hKey, hExpKey, SIMPLEBLOB, 0, 0, cbData)) goto done;

if (!(pbData = (BYTE *)LocbalAlloc(LMEM_FIXED, *cbData))) goto done;

if (!CryptExportKey(hKey, hExpKey, SIMPLEBLOB, 0, pbData, cbData))

goto done;

pbKeyData = pbData + sizeof(BLOBHEADER) + sizeof(ALG_ID);

(*cbData) -= (sizeof(BLOBHEADER) + sizeof(ALG_ID));

bResult = CryptDecrypt(hExpKey, 0, TRUE, 0, pbKeyData, cbData);

done:

if (hExpKey) CryptDestroyKey(hExpKey);

if (!bResult && pbData) LocalFree(pbData);

else if (pbData) MoveMemory(pbData, pbKeyData, *cbData);

return (bResult ? (BYTE *)LocalReAlloc(pbData, *cbData, 0) : 0);

}

See Also

Recipe 5.25, Recipe 5.26