CryptSetProvParam function (wincrypt.h)
Syntax
BOOL CryptSetProvParam(
[in] HCRYPTPROV hProv,
[in] DWORD dwParam,
[in] const BYTE *pbData,
[in] DWORD dwFlags
);
Parameters
[in] hProv
The handle of a CSP for which to set values. This handle must have already been created by using the CryptAcquireContext function.
[in] dwParam
Specifies the parameter to set. This can be one of the following values.
| Value | Meaning |
|---|---|
|
Set the window handle that the provider uses as the parent of any dialog boxes it creates. pbData contains a pointer to an HWND that contains the parent window handle.
This parameter must be set before calling CryptAcquireContext because many CSPs will display a user interface when CryptAcquireContext is called. You can pass NULL for the hProv parameter to set this window handle for all cryptographic contexts subsequently acquired within this process. |
|
Delete the ephemeral key associated with a hash, encryption, or verification context. This will free memory and clear registry settings associated with the key. |
|
This constant is not used. |
|
Specifies that the key exchange PIN is contained in pbData. The PIN is represented as a null-terminated ASCII string. |
|
This constant is not used. |
|
Sets the security descriptor on the key storage container. The pbData parameter is the address of a SECURITY_DESCRIPTOR structure that contains the new security descriptor for the key storage container. |
|
Sets an alternate prompt string to display to the user when the user's PIN is requested. The pbData parameter is a pointer to a null-terminated Unicode string. |
|
Sets the root certificate store for the smart card. The provider will copy the root certificates from this store onto the smart card.
The pbData parameter is an HCERTSTORE variable that contains the handle of the new certificate store. The provider will copy the certificates from the store during this call, so it is safe to close this store after this function is called. Windows XP and Windows Server 2003: This parameter is not supported. |
|
This constant is not used. |
|
Specifies the signature PIN. The pbData parameter is a null-terminated ASCII string that represents the PIN. |
|
This constant is not used. |
|
For a smart card provider, sets the search string that is displayed to the user as a prompt to insert the smart card. This string is passed as the lpstrSearchDesc member of the OPENCARDNAME_EX structure that is passed to the SCardUIDlgSelectCard function. This string is used for the lifetime of the calling process.
The pbData parameter is a pointer to a null-terminated Unicode string. |
|
Specifies that the CSP must exclusively use the hardware random number generator (RNG). When PP_USE_HARDWARE_RNG is set, random values are taken exclusively from the hardware RNG and no other sources are used. If a hardware RNG is supported by the CSP and it can be exclusively used, the function succeeds and returns TRUE; otherwise, the function fails and returns FALSE. The pbData parameter must be NULL and dwFlags must be zero when using this value.
None of the Microsoft CSPs currently support using a hardware RNG. |
|
Specifies the user certificate store for the smart card. This certificate store contains all of the user certificates that are stored on the smart card. The certificates in this store are encoded by using PKCS_7_ASN_ENCODING or X509_ASN_ENCODING encoding and should contain the CERT_KEY_PROV_INFO_PROP_ID property.
The pbData parameter is an HCERTSTORE variable that receives the handle of an in-memory certificate store. When this handle is no longer needed, the caller must close it by using the CertCloseStore function. Windows Server 2003 and Windows XP: This parameter is not supported. |
|
Specifies that an encrypted key exchange PIN is contained in pbData. The pbData parameter contains a DATA_BLOB. |
|
Specifies that an encrypted signature PIN is contained in pbData. The pbData parameter contains a DATA_BLOB. |
|
Specifies the name of the smart card reader. The pbData parameter is the address of an ANSI character array that contains a null-terminated ANSI string that contains the name of the smart card reader.
Windows Server 2003 and Windows XP: This parameter is not supported. |
|
Specifies the identifier of the smart card. The pbData parameter is the address of a GUID structure that contains the identifier of the smart card.
Windows Server 2003 and Windows XP: This parameter is not supported. |
[in] pbData
A pointer to a data buffer that contains the value to be set as a provider parameter. The form of this data varies depending on the dwParam value. If dwParam contains PP_USE_HARDWARE_RNG, this parameter must be NULL.
[in] dwFlags
If dwParam contains PP_KEYSET_SEC_DESCR, dwFlags contains the SECURITY_INFORMATION applicable bit flags, as defined in the Platform SDK. Key-container security is handled by using SetFileSecurity and GetFileSecurity.
These bit flags can be combined by using a bitwise-OR operation. For more information, see CryptGetProvParam.
If dwParam is PP_USE_HARDWARE_RNG or PP_DELETEKEY, dwFlags must be set to zero.
Return value
If the function succeeds, the return value is nonzero (TRUE).
If the function fails, the return value is zero (FALSE). For extended error information, call GetLastError.
The error codes prefaced by "NTE" are generated by the particular CSP being used. Error codes include the following.
| Return code | Description |
|---|---|
|
The CSP context is currently being used by another process. |
|
One of the parameters specifies a handle that is not valid. |
|
One of the parameters contains a value that is not valid. This is most often a pointer that is not valid. |
|
The dwFlags parameter is nonzero or the pbData buffer contains a value that is not valid. |
|
The dwParam parameter specifies an unknown parameter. |
|
The CSP context that was specified when the hKey key was created cannot be found. |
|
The function failed in some unexpected way. |
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | wincrypt.h |
| Library | Advapi32.lib |
| DLL | Advapi32.dll |
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for