Expand Minimize
EN
Deze inhoud is niet beschikbaar in uw taal, maar wel in het Engels.

CryptSetProvParam function

The CryptSetProvParam function customizes the operations of a cryptographic service provider (CSP). This function is commonly used to set a security descriptor on the key container associated with a CSP to control access to the private keys in that key container.

Syntax


BOOL WINAPI CryptSetProvParam(
  _In_  HCRYPTPROV hProv,
  _In_  DWORD dwParam,
  _In_  const BYTE *pbData,
  _In_  DWORD dwFlags
);

Parameters

hProv [in]

The handle of a CSP for which to set values. This handle must have already been created by using the CryptAcquireContext function.

dwParam [in]

Specifies the parameter to set. This can be one of the following values.

ValueMeaning
PP_CLIENT_HWND
1 (0x1)

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.

PP_DELETEKEY
24 (0x18)

Delete the ephemeral key associated with a hash, encryption, or verification context. This will free memory and clear registry settings associated with the key.

PP_KEYEXCHANGE_ALG

This constant is not used.

PP_KEYEXCHANGE_PIN
32 (0x20)

Specifies that the key exchange PIN is contained in pbData. The PIN is represented as a null-terminated ASCII string.

PP_KEYEXCHANGE_KEYSIZE

This constant is not used.

PP_KEYSET_SEC_DESCR
8 (0x8)

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.

PP_PIN_PROMPT_STRING
44 (0x2C)

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.

PP_ROOT_CERTSTORE
46 (0x2E)

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.

PP_SIGNATURE_ALG

This constant is not used.

PP_SIGNATURE_PIN
33 (0x21)

Specifies the signature PIN. The pbData parameter is a null-terminated ASCII string that represents the PIN.

PP_SIGNATURE_KEYSIZE

This constant is not used.

PP_UI_PROMPT
21 (0x15)

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.

PP_USE_HARDWARE_RNG
38 (0x26)

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.

PP_USER_CERTSTORE
42 (0x2A)

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.

PP_SECURE_KEYEXCHANGE_PIN
47 (0x2F)

Specifies that an encrypted key exchange PIN is contained in pbData. The pbData parameter contains a DATA_BLOB.

PP_SECURE_SIGNATURE_PIN
48 (0x30)

Specifies that an encrypted signature PIN is contained in pbData. The pbData parameter contains a DATA_BLOB.

PP_SMARTCARD_READER
43 (0x2B)

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.

PP_SMARTCARD_GUID
45 (0x2D)

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.

 

pbData [in]

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.

dwFlags [in]

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 codeDescription
ERROR_BUSY

The CSP context is currently being used by another process.

ERROR_INVALID_HANDLE

One of the parameters specifies a handle that is not valid.

ERROR_INVALID_PARAMETER

One of the parameters contains a value that is not valid. This is most often a pointer that is not valid.

NTE_BAD_FLAGS

The dwFlags parameter is nonzero or the pbData buffer contains a value that is not valid.

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.

 

Examples

For an example that uses this function, see Example C Program: Enumerating CSP Providers and Provider Types.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Wincrypt.h

Library

Advapi32.lib

DLL

Advapi32.dll

See also

Service Provider Functions
CryptAcquireContext
CryptGetProvParam
CryptSetKeyParam

 

 

Community-inhoud

Toevoegen
Weergeven:
© 2014 Microsoft