Using CNG

What follows are a series of small code function outlines that show how to use CNG to perform various cryptographic tasks. Consider the examples as pseudocode using real API names. The intent is not to demonstrate every possible algorithm or cryptographic operation, nor do we want to show huge swaths of code; rather, we want to show the general API call order.

Note 

CAPI1 APIs don’t have access to CNG providers and keys, but CNG has access to CAPI1 keys used by Microsoft Cryptographic Service Providers.

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.

Generating Random Numbers

Because the code to generate random data is very small, we have included all the code here:

 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; }