/*++
Copyright (C) Microsoft Corporation, 2000
Module Name:
cspdk
Abstract:
This header file contains the definitions and references that every CSP
needs to know.
Author:
Doug Barlow (dbarlow) 1/27/2000
--*/
#ifndef _CSPDK_H_
#define _CSPDK_H_
#ifdef __cplusplus
extern "C" {
#endif
#define CRYPT_PROVSTRUC_VERSION_V3 3
#define CRYPT_MAX_PROVIDER_ID 999
#define CRYPT_SIG_RESOURCE_VERSION 0x00000100
#define CRYPT_EXTERNAL_SIGNATURE_LENGTH 136
#define CRYPT_SIG_RESOURCE_NUMBER 0x29A
#define CRYPT_SIG_RESOURCE TEXT("#666")
#define CRYPT_MAC_RESOURCE_NUMBER 0x29B
#define CRYPT_MAC_RESOURCE TEXT("#667")
// Exponentiation Offload Reg Location
#define EXPO_OFFLOAD_REG_VALUE "ExpoOffload"
#define EXPO_OFFLOAD_FUNC_NAME "OffloadModExpo"
typedef struct _OFFLOAD_PRIVATE_KEY
{
DWORD dwVersion;
DWORD cbPrime1;
DWORD cbPrime2;
PBYTE pbPrime1; // "p"
PBYTE pbPrime2; // "q"
} OFFLOAD_PRIVATE_KEY, *POFFLOAD_PRIVATE_KEY;
#define CUR_OFFLOAD_VERSION 1
//
// Callback prototypes
//
typedef BOOL (WINAPI *CRYPT_VERIFY_IMAGE_A)(LPCSTR szImage, CONST BYTE *pbSigData);
typedef BOOL (WINAPI *CRYPT_VERIFY_IMAGE_W)(LPCWSTR szImage, CONST BYTE *pbSigData);
typedef void (*CRYPT_RETURN_HWND)(HWND *phWnd);
//
// Structures for CSPs
//
typedef struct _VTableProvStruc {
DWORD Version;
CRYPT_VERIFY_IMAGE_A FuncVerifyImage;
CRYPT_RETURN_HWND FuncReturnhWnd;
DWORD dwProvType;
BYTE *pbContextInfo;
DWORD cbContextInfo;
LPSTR pszProvName;
} VTableProvStruc, *PVTableProvStruc;
typedef struct _VTableProvStrucW {
DWORD Version;
CRYPT_VERIFY_IMAGE_W FuncVerifyImage;
CRYPT_RETURN_HWND FuncReturnhWnd;
DWORD dwProvType;
BYTE *pbContextInfo;
DWORD cbContextInfo;
LPWSTR pszProvName;
} VTableProvStrucW, *PVTableProvStrucW;
typedef struct {
DWORD dwVersion;
DWORD dwCrcOffset;
BYTE rgbSignature[88]; // 1024-bit key, plus 2 DWORDs of padding.
} InFileSignatureResource;
//
// ===========================================================================
// CSP Entry points.
// ===========================================================================
//
/*
- CPAcquireContext
-
* Purpose:
* The CPAcquireContext function is used to acquire a context
* handle to a cryptographic service provider (CSP).
*
*
* Parameters:
* OUT phProv - Handle to a CSP
* IN szContainer - Pointer to a string which is the
* identity of the logged on user
* IN dwFlags - Flags values
* IN pVTable - Pointer to table of function pointers
*
* Returns:
*/
extern BOOL WINAPI
CPAcquireContext(
OUT HCRYPTPROV *phProv,
IN LPCSTR szContainer,
IN DWORD dwFlags,
IN PVTableProvStruc pVTable);
/*
- CPAcquireContextW
-
* Purpose:
* The CPAcquireContextW function is used to acquire a context
* handle to a cryptographic service provider (CSP). using
* UNICODE strings. This is an optional entry point for a CSP.
* It is not used prior to Whistler. There it is used if
* exported by the CSP image, otherwise any string conversions
* are done, and CPAcquireContext is called.
*
*
* Parameters:
* OUT phProv - Handle to a CSP
* IN szContainer - Pointer to a string which is the
* identity of the logged on user
* IN dwFlags - Flags values
* IN pVTable - Pointer to table of function pointers
*
* Returns:
*/
extern BOOL WINAPI
CPAcquireContextW(
OUT HCRYPTPROV *phProv,
IN LPCWSTR szContainer,
IN DWORD dwFlags,
IN PVTableProvStrucW pVTable);
/*
- CPReleaseContext
-
* Purpose:
* The CPReleaseContext function is used to release a
* context created by CryptAcquireContext.
*
* Parameters:
* IN phProv - Handle to a CSP
* IN dwFlags - Flags values
*
* Returns:
*/
extern BOOL WINAPI
CPReleaseContext(
IN HCRYPTPROV hProv,
IN DWORD dwFlags);
/*
- CPGenKey
-
* Purpose:
* Generate cryptographic keys
*
*
* Parameters:
* IN hProv - Handle to a CSP
* IN Algid - Algorithm identifier
* IN dwFlags - Flags values
* OUT phKey - Handle to a generated key
*
* Returns:
*/
extern BOOL WINAPI
CPGenKey(
IN HCRYPTPROV hProv,
IN ALG_ID Algid,
IN DWORD dwFlags,
OUT HCRYPTKEY *phKey);
/*
- CPDeriveKey
-
* Purpose:
* Derive cryptographic keys from base data
*
*
* Parameters:
* IN hProv - Handle to a CSP
* IN Algid - Algorithm identifier
* IN hBaseData - Handle to base data
* IN dwFlags - Flags values
* OUT phKey - Handle to a generated key
*
* Returns:
*/
extern BOOL WINAPI
CPDeriveKey(
IN HCRYPTPROV hProv,
IN ALG_ID Algid,
IN HCRYPTHASH hHash,
IN DWORD dwFlags,
OUT HCRYPTKEY *phKey);
/*
- CPDestroyKey
-
* Purpose:
* Destroys the cryptographic key that is being referenced
* with the hKey parameter
*
*
* Parameters:
* IN hProv - Handle to a CSP
* IN hKey - Handle to a key
*
* Returns:
*/
extern BOOL WINAPI
CPDestroyKey(
IN HCRYPTPROV hProv,
IN HCRYPTKEY hKey);
/*
- CPSetKeyParam
-
* Purpose:
* Allows applications to customize various aspects of the
* operations of a key
*
* Parameters:
* IN hProv - Handle to a CSP
* IN hKey - Handle to a key
* IN dwParam - Parameter number
* IN pbData - Pointer to data
* IN dwFlags - Flags values
*
* Returns:
*/
extern BOOL WINAPI
CPSetKeyParam(
IN HCRYPTPROV hProv,
IN HCRYPTKEY hKey,
IN DWORD dwParam,
IN CONST BYTE *pbData,
IN DWORD dwFlags);
/*
- CPGetKeyParam
-
* Purpose:
* Allows applications to get various aspects of the
* operations of a key
*
* Parameters:
* IN hProv - Handle to a CSP
* IN hKey - Handle to a key
* IN dwParam - Parameter number
* OUT pbData - Pointer to data
* IN pdwDataLen - Length of parameter data
* IN dwFlags - Flags values
*
* Returns:
*/
extern BOOL WINAPI
CPGetKeyParam(
IN HCRYPTPROV hProv,
IN HCRYPTKEY hKey,
IN DWORD dwParam,
OUT LPBYTE pbData,
IN OUT LPDWORD pcbDataLen,
IN DWORD dwFlags);
/*
- CPSetProvParam
-
* Purpose:
* Allows applications to customize various aspects of the
* operations of a provider
*
* Parameters:
* IN hProv - Handle to a CSP
* IN dwParam - Parameter number
* IN pbData - Pointer to data
* IN dwFlags - Flags values
*
* Returns:
*/
extern BOOL WINAPI
CPSetProvParam(
IN HCRYPTPROV hProv,
IN DWORD dwParam,
IN CONST BYTE *pbData,
IN DWORD dwFlags);
/*
- CPGetProvParam
-
* Purpose:
* Allows applications to get various aspects of the
* operations of a provider
*
* Parameters:
* IN hProv - Handle to a CSP
* IN dwParam - Parameter number
* OUT pbData - Pointer to data
* IN OUT pdwDataLen - Length of parameter data
* IN dwFlags - Flags values
*
* Returns:
*/
extern BOOL WINAPI
CPGetProvParam(
IN HCRYPTPROV hProv,
IN DWORD dwParam,
OUT LPBYTE pbData,
IN OUT LPDWORD pcbDataLen,
IN DWORD dwFlags);
/*
- CPSetHashParam
-
* Purpose:
* Allows applications to customize various aspects of the
* operations of a hash
*
* Parameters:
* IN hProv - Handle to a CSP
* IN hHash - Handle to a hash
* IN dwParam - Parameter number
* IN pbData - Pointer to data
* IN dwFlags - Flags values
*
* Returns:
*/
extern BOOL WINAPI
CPSetHashParam(
IN HCRYPTPROV hProv,
IN HCRYPTHASH hHash,
IN DWORD dwParam,
IN CONST BYTE *pbData,
IN DWORD dwFlags);
/*
- CPGetHashParam
-
* Purpose:
* Allows applications to get various aspects of the
* operations of a hash
*
* Parameters:
* IN hProv - Handle to a CSP
* IN hHash - Handle to a hash
* IN dwParam - Parameter number
* OUT pbData - Pointer to data
* IN pdwDataLen - Length of parameter data
* IN dwFlags - Flags values
*
* Returns:
*/
extern BOOL WINAPI
CPGetHashParam(
IN HCRYPTPROV hProv,
IN HCRYPTHASH hHash,
IN DWORD dwParam,
OUT LPBYTE pbData,
IN OUT LPDWORD pcbDataLen,
IN DWORD dwFlags);
/*
- CPExportKey
-
* Purpose:
* Export cryptographic keys out of a CSP in a secure manner
*
*
* Parameters:
* IN hProv - Handle to the CSP user
* IN hKey - Handle to the key to export
* IN hPubKey - Handle to exchange public key value of
* the destination user
* IN dwBlobType - Type of key blob to be exported
* IN dwFlags - Flags values
* OUT pbData - Key blob data
* IN OUT pdwDataLen - Length of key blob in bytes
*
* Returns:
*/
extern BOOL WINAPI
CPExportKey(
IN HCRYPTPROV hProv,
IN HCRYPTKEY hKey,
IN HCRYPTKEY hPubKey,
IN DWORD dwBlobType,
IN DWORD dwFlags,
OUT LPBYTE pbData,
IN OUT LPDWORD pcbDataLen);
/*
- CPImportKey
-
* Purpose:
* Import cryptographic keys
*
*
* Parameters:
* IN hProv - Handle to the CSP user
* IN pbData - Key blob data
* IN dwDataLen - Length of the key blob data
* IN hPubKey - Handle to the exchange public key value of
* the destination user
* IN dwFlags - Flags values
* OUT phKey - Pointer to the handle to the key which was
* Imported
*
* Returns:
*/
extern BOOL WINAPI
CPImportKey(
IN HCRYPTPROV hProv,
IN CONST BYTE *pbData,
IN DWORD cbDataLen,
IN HCRYPTKEY hPubKey,
IN DWORD dwFlags,
OUT HCRYPTKEY *phKey);
/*
- CPEncrypt
-
* Purpose:
* Encrypt data
*
*
* Parameters:
* IN hProv - Handle to the CSP user
* IN hKey - Handle to the key
* IN hHash - Optional handle to a hash
* IN Final - Boolean indicating if this is the final
* block of plaintext
* IN dwFlags - Flags values
* IN OUT pbData - Data to be encrypted
* IN OUT pdwDataLen - Pointer to the length of the data to be
* encrypted
* IN dwBufLen - Size of Data buffer
*
* Returns:
*/
extern BOOL WINAPI
CPEncrypt(
IN HCRYPTPROV hProv,
IN HCRYPTKEY hKey,
IN HCRYPTHASH hHash,
IN BOOL fFinal,
IN DWORD dwFlags,
IN OUT LPBYTE pbData,
IN OUT LPDWORD pcbDataLen,
IN DWORD cbBufLen);
/*
- CPDecrypt
-
* Purpose:
* Decrypt data
*
*
* Parameters:
* IN hProv - Handle to the CSP user
* IN hKey - Handle to the key
* IN hHash - Optional handle to a hash
* IN Final - Boolean indicating if this is the final
* block of ciphertext
* IN dwFlags - Flags values
* IN OUT pbData - Data to be decrypted
* IN OUT pdwDataLen - Pointer to the length of the data to be
* decrypted
*
* Returns:
*/
extern BOOL WINAPI
CPDecrypt(
IN HCRYPTPROV hProv,
IN HCRYPTKEY hKey,
IN HCRYPTHASH hHash,
IN BOOL fFinal,
IN DWORD dwFlags,
IN OUT LPBYTE pbData,
IN OUT LPDWORD pcbDataLen);
/*
- CPCreateHash
-
* Purpose:
* initate the hashing of a stream of data
*
*
* Parameters:
* IN hUID - Handle to the user identifcation
* IN Algid - Algorithm identifier of the hash algorithm
* to be used
* IN hKey - Optional handle to a key
* IN dwFlags - Flags values
* OUT pHash - Handle to hash object
*
* Returns:
*/
extern BOOL WINAPI
CPCreateHash(
IN HCRYPTPROV hProv,
IN ALG_ID Algid,
IN HCRYPTKEY hKey,
IN DWORD dwFlags,
OUT HCRYPTHASH *phHash);
/*
- CPHashData
-
* Purpose:
* Compute the cryptograghic hash on a stream of data
*
*
* Parameters:
* IN hProv - Handle to the user identifcation
* IN hHash - Handle to hash object
* IN pbData - Pointer to data to be hashed
* IN dwDataLen - Length of the data to be hashed
* IN dwFlags - Flags values
*
* Returns:
*/
extern BOOL WINAPI
CPHashData(
IN HCRYPTPROV hProv,
IN HCRYPTHASH hHash,
IN CONST BYTE *pbData,
IN DWORD cbDataLen,
IN DWORD dwFlags);
/*
- CPHashSessionKey
-
* Purpose:
* Compute the cryptograghic hash on a key object.
*
*
* Parameters:
* IN hProv - Handle to the user identifcation
* IN hHash - Handle to hash object
* IN hKey - Handle to a key object
* IN dwFlags - Flags values
*
* Returns:
* CRYPT_FAILED
* CRYPT_SUCCEED
*/
extern BOOL WINAPI
CPHashSessionKey(
IN HCRYPTPROV hProv,
IN HCRYPTHASH hHash,
IN HCRYPTKEY hKey,
IN DWORD dwFlags);
/*
- CPSignHash
-
* Purpose:
* Create a digital signature from a hash
*
*
* Parameters:
* IN hProv - Handle to the user identifcation
* IN hHash - Handle to hash object
* IN dwKeySpec - Key pair to that is used to sign with
* IN sDescription - Description of data to be signed
* IN dwFlags - Flags values
* OUT pbSignature - Pointer to signature data
* IN OUT dwHashLen - Pointer to the len of the signature data
*
* Returns:
*/
extern BOOL WINAPI
CPSignHash(
IN HCRYPTPROV hProv,
IN HCRYPTHASH hHash,
IN DWORD dwKeySpec,
IN LPCWSTR szDescription,
IN DWORD dwFlags,
OUT LPBYTE pbSignature,
IN OUT LPDWORD pcbSigLen);
/*
- CPDestroyHash
-
* Purpose:
* Destroy the hash object
*
*
* Parameters:
* IN hProv - Handle to the user identifcation
* IN hHash - Handle to hash object
*
* Returns:
*/
extern BOOL WINAPI
CPDestroyHash(
IN HCRYPTPROV hProv,
IN HCRYPTHASH hHash);
/*
- CPVerifySignature
-
* Purpose:
* Used to verify a signature against a hash object
*
*
* Parameters:
* IN hProv - Handle to the user identifcation
* IN hHash - Handle to hash object
* IN pbSignture - Pointer to signature data
* IN dwSigLen - Length of the signature data
* IN hPubKey - Handle to the public key for verifying
* the signature
* IN sDescription - String describing the signed data
* IN dwFlags - Flags values
*
* Returns:
*/
extern BOOL WINAPI
CPVerifySignature(
IN HCRYPTPROV hProv,
IN HCRYPTHASH hHash,
IN CONST BYTE *pbSignature,
IN DWORD cbSigLen,
IN HCRYPTKEY hPubKey,
IN LPCWSTR szDescription,
IN DWORD dwFlags);
/*
- CPGenRandom
-
* Purpose:
* Used to fill a buffer with random bytes
*
*
* Parameters:
* IN hProv - Handle to the user identifcation
* IN dwLen - Number of bytes of random data requested
* IN OUT pbBuffer - Pointer to the buffer where the random
* bytes are to be placed
*
* Returns:
*/
extern BOOL WINAPI
CPGenRandom(
IN HCRYPTPROV hProv,
IN DWORD cbLen,
OUT LPBYTE pbBuffer);
/*
- CPGetUserKey
-
* Purpose:
* Gets a handle to a permanent user key
*
*
* Parameters:
* IN hProv - Handle to the user identifcation
* IN dwKeySpec - Specification of the key to retrieve
* OUT phUserKey - Pointer to key handle of retrieved key
*
* Returns:
*/
extern BOOL WINAPI
CPGetUserKey(
IN HCRYPTPROV hProv,
IN DWORD dwKeySpec,
OUT HCRYPTKEY *phUserKey);
/*
- CPDuplicateHash
-
* Purpose:
* Duplicates the state of a hash and returns a handle to it.
* This is an optional entry. Typically it only occurs in
* SChannel related CSPs.
*
* Parameters:
* IN hUID - Handle to a CSP
* IN hHash - Handle to a hash
* IN pdwReserved - Reserved
* IN dwFlags - Flags
* IN phHash - Handle to the new hash
*
* Returns:
*/
extern BOOL WINAPI
CPDuplicateHash(
IN HCRYPTPROV hProv,
IN HCRYPTHASH hHash,
IN LPDWORD pdwReserved,
IN DWORD dwFlags,
OUT HCRYPTHASH *phHash);
/*
- CPDuplicateKey
-
* Purpose:
* Duplicates the state of a key and returns a handle to it.
* This is an optional entry. Typically it only occurs in
* SChannel related CSPs.
*
* Parameters:
* IN hUID - Handle to a CSP
* IN hKey - Handle to a key
* IN pdwReserved - Reserved
* IN dwFlags - Flags
* IN phKey - Handle to the new key
*
* Returns:
*/
extern BOOL WINAPI
CPDuplicateKey(
IN HCRYPTPROV hProv,
IN HCRYPTKEY hKey,
IN LPDWORD pdwReserved,
IN DWORD dwFlags,
OUT HCRYPTKEY *phKey);
#ifdef __cplusplus
}
#endif
#endif // _CSPDK_H_