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

  Windows NT: Requires version 4.0 or later.
  Windows: Requires Windows 95 OSR2 or later (or Windows 95 with IE 3.02 or later).
  Windows CE: Unsupported.
  Header: Declared in wincrypt.h.
  Import Library: Use advapi32.lib.

See Also

CryptAcquireContext, CryptGetProvParam, CryptSetKeyParam