Windows API Reference - Cryptography

Cryptography API Overview

The Cryptography API (CryptoAPI) is a set of functions and interfaces that provide cryptographic services for Windows applications. It supports a wide range of cryptographic operations, including encryption, decryption, hashing, digital signatures, and certificate management.

This section covers key functions and structures related to secure data handling and identity verification.

Core Cryptographic Functions

CryptEncrypt

BOOL CryptEncrypt( HCRYPTKEY hKey, HCRYPTHASH hHash, BOOL fFinal, DWORD dwFlags, BYTE *pbData, DWORD *pdwDataLen, DWORD dwBufLen );

Encrypts or decrypts data using a specified session key. This function can be called multiple times to encrypt or decrypt large blocks of data.

Parameters:

  • hKey: Handle to the session key.
  • hHash: Handle to a hash object. If not NULL, data is also hashed.
  • fFinal: Boolean indicating if this is the final block of data.
  • dwFlags: Reserved for future use. Must be zero.
  • pbData: Pointer to the data to be encrypted or decrypted.
  • pdwDataLen: Pointer to the size of the data in bytes.
  • dwBufLen: Size of the buffer for the encrypted/decrypted data.

Returns TRUE on success, FALSE on failure. Use GetLastError for error information.

Note: For decryption, the same key used for encryption must be used. The fFinal parameter is crucial for proper padding and decryption of the last block.

CryptHashData

BOOL CryptHashData( HCRYPTHASH hHash, BYTE *pbData, DWORD dwDataLen, DWORD dwFlags );

Hashes a specified block of data and adds it to the current hash calculation.

Parameters:

  • hHash: Handle to the hash object.
  • pbData: Pointer to the data to be hashed.
  • dwDataLen: Size of the data in bytes.
  • dwFlags: Reserved for future use. Must be zero.

Returns TRUE on success, FALSE on failure. Use GetLastError for error information.

Note: This function can be called multiple times to hash large amounts of data. The hash is finalized by calling CryptHashCertificate or CryptGetHashParam with HP_HASHVAL.

CryptGenKey

BOOL CryptGenKey( HCRYPTPROV hProv, ALG_ID Algid, DWORD dwFlags, HCRYPTKEY *phKey );

Generates a random session key. This key can be used for symmetric encryption or as a public key for asymmetric encryption.

Parameters:

  • hProv: Handle to the cryptographic service provider (CSP).
  • Algid: Algorithm identifier for the key (e.g., CALG_AES_256, CALG_RSA_KEYX).
  • dwFlags: Flags that control key generation. Can include CRYPT_EXPORTABLE to allow key export.
  • phKey: Pointer to a variable that receives the handle to the generated key.

Returns TRUE on success, FALSE on failure. Use GetLastError for error information.

Key Structures

CRYPT_DATA_BLOB

typedef struct _CRYPT_DATA_BLOB { DWORD cbData; BYTE *pbData; } CRYPT_DATA_BLOB, *PCRYPT_DATA_BLOB;

A generic structure used to pass data blobs, such as certificates, keys, or private key information, between CryptoAPI functions.

Members:

  • cbData: The number of bytes in the buffer pointed to by pbData.
  • pbData: Pointer to the data buffer.

CERT_INFO

typedef struct _CERT_INFO { DWORD dwVersion; CRYPT_INTEGER_BLOB serialNumber; // ... other members ... } CERT_INFO, *PCERT_INFO;

Contains information about a certificate, including its serial number, issuer name, subject name, and validity period.

Members:

  • dwVersion: The certificate version.
  • serialNumber: The certificate's serial number.
  • ... other members ...
Warning: This is a simplified representation. The full CERT_INFO structure is extensive and detailed. Refer to official documentation for complete specifications.

Related Concepts