CryptSetProvParam

The CryptSetProvParam function customizes the operations of a CSP.

#include <wincrypt.h>
BOOL WINAPI CryptSetProvParam(
  HCRYPTPROV hProv,  // in
  DWORD dwParam,     // in
  BYTE *pbData,      // in
  DWORD dwFlags      // in
);

Parameters

hProv

A handle to the CSP on which to set parameters.

dwParam

The parameter number to set. The currently defined parameter values are as follows (see "Remarks" for additional details).

Parameter	Description
PP_CLIENT_HWND	Specifies that a window handle is contained in pbData.
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.

pbData

The parameter data buffer. Place the parameter data in this buffer before calling CryptSetProvParam. 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), as defined in the Win32 Programmer's Reference. See CryptGetProvParam for additional details.

Return Values

If the function succeeds, the return value is TRUE. If it fails, the return value is FALSE. To retrieve extended error information, use the GetLastError function.

The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by "NTE" are generated by the particular CSP you are using.

Error code	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_BUSY	The CSP context is currently being used by another process.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
NTE_BAD_FLAGS	The dwFlags parameter is nonzero or the pbData buffer contains an invalid value.
NTE_BAD_TYPE	The dwParam parameter specifies an unknown parameter.
NTE_BAD_UID	The CSP context that was specified when the hKey key was created cannot be found.
NTE_FAIL	The function failed in some unexpected way.

Remarks

When dwParam is set to PP_CLIENT_HWND, the pbData buffer should contain a DWORD value specifying the window handle that the provider is to use when interacting directly with the user. When setting this parameter, applications should call the CryptSetProvParam function before calling CryptAcquireContext. This is necessary because many CSPs will display a user interface during the CryptAcquireContext function. Note that CSPs that do not ever display a user interface will ignore the value of this parameter.

When setting the security descriptor, the pbData parameter holds the pointer to the security descriptor to be set. It may be helpful to look at the documentation on RegGetKeySecurity and RegSetKeySecurity (WIN32 calls).

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

Example

#include <wincrypt.h>

// Set up the variables.
HCRYPTPROV hProv = 0;
HWND mainhwnd;
HINSTANCE hThisInst;
//Specify that a window handle is contained in pbData.
DWORD dwParam = PP_CLIENT_HWND;

mainhwnd = CreateWindow(
     szWinName,
     "Security Examples Program",
     WS_OVERLAPPEDWINDOW | WS_VSCROLL,
     CW_USEDEFAULT, CW_USEDEFAULT, // x,y
     700, 500,     // width,height
     HWND_DESKTOP, // parent window
     NULL,
     hThisInst,
     NULL);

BYTE * pbData = (BYTE *) mainhwnd;

// Get a handle to the default provider.
if(!CryptAcquireContext(&hProv, NULL, NULL, PROV_RSA_FULL, 0)) {
    printf("Error %x during CryptAcquireContext!\n", GetLastError());
}
// Set the PP_CLIENT_HWND parameter for the default provider.
CryptSetProvParam(hProv, dwParam, pbData, 0);

QuickInfo