New Algorithms in CNG

CNG also supports two kinds of random number generators (RNG), and both are allowed under SDL: BCRYPT_RNG_ALGORITHM and BCRYPT_RNG_FIPS186_DSA_ALGORITHM . Most applications should use the former, but if you are using DSA, then you should use the latter. Both RNGs conform to FIPS 186-2 and FIPS 140-2.

The Windows Vista Software Development includes complete CNG samples in the samples/ security/CNG folder. There is also a separate CNG SDK available that includes samples and documentation relating to CNG configuration and installing CNG plug-ins (Microsoft 2006a).

In all cases you must include <bcrypt.h> and link your code with bcryt.dll . Also, CNG returns various status values defined in ntstatus.h. You may also need to add this macro to your code:

#

ifndef

NT_SUCCESS # define NT_SUCCESS(Status) (((NTSTATUS)(Status)) >= 0) #endif

Encrypting Data

BCryptOpenAlgorithmProvider(&hAlg,...) BCryptGetProperty(hAlg,BCRYPT_BLOCK_LENGTH,&dwBlockSize,...) Allocate buffer, rounding up to

next

block

size

. BCryptGetProperty(hAlg,BCRYPT_OBJECT_LENGTH,&cbKeyObjectLen,...) Allocate buffer for key object. BCryptGenerateSymmetricKey(hAlg,&hKey,...) BCryptEncrypt(hKey,...) Data is now encrypted BCryptDestroyKey(hKey) BCryptCloseAlgorithmProvider(hAlg,0) Deallocate buffers

Note that like CryptAcquireContext in CAPI, BCryptOpenAlgorithmProvider is a reasonably expensive function call, and it might be helpful to cache the return handle in your code rather than constantly opening and closing a provider.

Hashing Data

BCryptOpenAlgorithmProvider(&hAlg,...) BCryptGetProperty(hAlg,BCRYPT_OBJECT_LENGTH,&cbHash,...) Allocate buffer for hash BCryptCreateHash(hAlg,&hHash,...) BCryptHashData(hHash,...) BCryptFinishHash(hHash,...) Use the hash data BCryptDestroyHash(hHash) BCryptCloseAlgorithmProvider(hAlg,0) Deallocate buffers

MACing Data

Creating a message authentication code is exactly the same as creating a hash, but there are two differences.

1. The last argument to BCryptOpenAlgorithmProvider should be BCRYPT_ALG_HANDLE_HMAC_FLAG .

2. The fifth and sixth arguments to BCryptCreateHash are the secret MAC key and the length of the MAC key. So the function call looks like this:

   BCRYPT_ALG_HANDLE hAlg = NULL; NTSTATUS status = STATUS_UNSUCCESSFUL; status = BCryptOpenAlgorithmProvider(&hAlg, GetPreferredHmacAlg(), NULL, BCRYPT_ALG_HANDLE_HMAC_FLAG)))
   

The call to GetPreferredHmacAlg is not a CNG function; it’s a function you would provide to get the preferred HMAC base algorithm, perhaps from a configuration setting.

BCRYPT_ALG_HANDLE hRngAlg = NULL; if (BCryptOpenAlgorithmProvider(&hRngAlg, BCRYPT_RNG_ALGORITHM, NULL, 0) == STATUS_SUCCESS) { BYTE buf[32]; if (BCryptGenRandom(hRngAlg, buf, sizeof buf, 0) == STATUS_SUCCESS) { // We have the random data } BCryptCloseAlgorithmProvider(hRngAlg,0); hRngAlg = NULL; }