CPSetProvParam

The CPSetProvParam function allows applications to customize the operations of a CSP.

BOOL CPSetProvParam(
  HCRYPTPROV hProv,  // in
  DWORD dwParam,     // in
  BYTE *pbData,      // in
  DWORD dwFlags      // in
);
 

Parameters

hProv
Handle to a particular key container (or "context") within the CSP. This handle is obtained via a call to CPAcquireContext.
dwParam
The parameter number to set. The currently defined parameter values are as follows (see "Remarks" for additional details).
PP_KEYSET_SEC_DESCR
Specifies that the security descriptor on the registry entry where the stored key set is being assigned, and its value is contained in pbData. See secperf.c in the Microsoft Platform SDK which shows how to manipulate Microsoft Windows NT ACLs
pbData
Parameter data buffer. Upon entry to the function, this buffer will contain the data that corresponds to the dwParam parameter number. The form of this data will vary, depending on the parameter number.
dwFlags
The flag values. When dwParam is PP_KEYSET_SEC_DESCR, dwFlags contains the SECURITY_INFORMATION applicable bit flags (can be combined with a bitwise OR operation. See CryptGetProvParam (in the CryptoAPI) for additional details.

Note  The PP_KEYSET_SEC_DESCR flag is not supported under Microsoft Windows 95.

Return Values

If the function succeeds, TRUE should be returned; otherwise, return FALSE. When FALSE is returned, the appropriate error code (see the following table) must be set via SetLastError.

Error Description
NTE_BAD_FLAGS The value of the dwFlags parameter is invalid.
NTE_BAD_TYPE The dwParam parameter specifies an unknown parameter number.
NTE_BAD_UID The context specified by hProv is invalid.
NTE_FAIL The function failed in some unexpected way.

Remarks

It is expected that CSP authors will define parameters for this function as necessary. If these are general-purpose in nature, rather than applying to a single provider type, they should be defined in coordination with Microsoft. This will promote cross-vendor standardization, and allow the new parameter numbers to be added to the standard Win32 header files.

Note  Some applications will call the CryptSetProvParam function (in the CryptoAPI) with the dwParam parameter set to PP_CLIENT_HWND, in order to specify the window handle that the CSP is to use when interacting with the user. In this case, the application passes in the window handle as a DWORD in the pbData buffer. Applications will typically make this CryptSetProvParam function call before calling CryptAcquireContext (in the CryptoAPI). Because of this, the CryptSetProvParam function is not passed down to the CSP when the parameter is PP_CLIENT_HWND. The CSP obtains this window handle via a virtual function pointer obtained from the CPAcquireContext function call.

See Also

CPAcquireContext, CPGetProvParam, CryptSetProvParam