The CPGetProvParam function returns data about a cryptographic service provider (CSP).

Syntax

BOOL CPGetProvParam(
  __in     HCRYPTPROV hProv,
  __in     DWORD dwParam,
  __out    BYTE *pbData,
  __inout  DWORD *pdwDataLen,
  __in     DWORD dwFlags
);

Parameters

hProv [in]

A handle to a particular key container within the CSP. This handle is obtained by a previous call to CPAcquireContext.

dwParam [in]

A DWORD value that determines the nature of the query. The following queries are defined.

Value	Meaning
PP_CONTAINER	The name of the current key container as a null-terminated character string. The returned string is identical to the one passed in the pszContainer parameter of the CryptAcquireContext function to specify the key container to use. The value of the pszContainer parameter can be read to determine the name of the default key container.
PP_ENUMALGS	Information about an algorithm supported by the CSP being queried. The PP_ENUMALGS value must be read repeatedly to list all of the supported algorithms (not enumerated in any particular order). The first time that PP_ENUMALGS is read, the CRYPT_FIRST flag must be specified in dwFlags. Doing so ensures that information about the first algorithm in the enumeration list is returned. PP_ENUMALGS can then be repeatedly read with dwFlags set to zero to retrieve the information about the rest of the supported algorithms. When the CPGetProvParam function fails with the ERROR_NO_MORE_ITEMS error code, the end of the enumeration list has been reached. This function is not thread safe, and, if this function is used in a multithreaded context, all of the available algorithms may not be enumerated.
PP_ENUMALGS_EX	Information about an algorithm supported by the CSP being queried. The structure returned contains more information about the algorithm than the structure returned for PP_ENUMALGS. The PP_ENUMALGS_EX value must be read repeatedly to list all of the supported algorithms (not enumerated in any particular order). The first time that PP_ENUMALGS_EX is read, the CRYPT_FIRST flag must be specified in dwFlags. Doing so ensures that information about the first algorithm in the enumeration list is returned. PP_ENUMALGS_EX can then be repeatedly read with dwFlags set to zero to retrieve the information about the rest of the supported algorithms. When the CryptGetProvParam function fails with the ERROR_NO_MORE_ITEMS error code, the end of the enumeration list has been reached. This function is not thread safe, and, if this function is used in a multithreaded context, all of the available algorithms may not be enumerated.
PP_ENUMCONTAINERS	The name of one of the key containers maintained by the CSP in the form of a null-terminated character string. The PP_ENUMCONTAINERS value can be read repeatedly to enumerate all the container names. Container names are enumerated in the same way as the algorithms supported by the CSP. This function is not thread safe, and, if this function is used in a multithreaded context, all of the available container names may not be enumerated.
PP_IMPTYPE	A DWORD value that indicates how the CSP is implemented. The following predefined implementation types are supported: CRYPT_IMPL_HARDWARE CRYPT_IMPL_SOFTWARE CRYPT_IMPL_MIXED CRYPT_IMPL_UNKNOWN
PP_KEYX_KEYSIZE_INC	The number of bits for the increment length of AT_KEYEXCHANGE keys. This information is used with information returned with PP_ENUMALGS_EX to determine valid AT_KEYEXCHANGE key lengths. These key lengths can then be used with CPGenKey. For example, if a CSP enumerated CALG_RSA_SIGN (AT_KEYEXCHANGE) with a minimum key length of 512 bits, a maximum of 1024 bits, and returned the increment length as 64 bits, then valid key lengths would be 512, 576, 640, and other lengths at 512-bit intervals up to 1024 bits.
PP_KEYSET_SEC_DESCR	The security descriptor of the registry entry where the key set is stored.
PP_NAME	The name of the CSP in the form of a null-terminated character string. This string is identical to the one passed in the pszProvider parameter of the CryptAcquireContext function to specify that the current CSP be used.
PP_PROVTYPE	A DWORD value that indicates the provider type of the CSP.
PP_ROOT_CERTSTORE	Obtains the root certificate store for the smart card. This certificate store contains all of the root certificates that are stored on the smart card. This certificate store is most commonly used for joining to a domain by using a smart card. The pbData parameter is the address of an HCERTSTORE variable that receives the handle of the certificate store. When this handle is no longer needed, the caller will close it by using the CertCloseStore function. You can create a certificate store in memory by using the CertOpenStore function with the CERT_STORE_PROV_MEMORY option. You can then add certificates to this store by using the CertCreateCertificateContext and CertAddCertificateContextToStore functions. Windows XP, Windows Server 2003, and Windows 2000:  This parameter is not supported.
PP_SIG_KEYSIZE_INC	The number of bits for the increment length of AT_SIGNATURE keys. This information is used with information returned with PP_ENUMALGS_EX to determine valid AT_SIGNATURE key lengths. These key lengths can then be used with CPGenKey. For example, if a CSP enumerated CALG_RSA_SIGN (AT_SIGNATURE) with a minimum key length of 512 bits, a maximum of 1024 bits, and returned the increment length as 64 bits, then valid key lengths would be 512, 576, 640, and other lengths at 512-bit intervals up to 1024 bits.
PP_SMARTCARD_GUID	Obtains the identifier of the smart card. The pbData parameter is the address of a GUID structure that receives the identifier of the smart card. This identifier is used by the certificate propagation service to track the source of a root certificate. Windows XP, Windows Server 2003, and Windows 2000:  This parameter is not supported.
PP_SMARTCARD_READER	Obtains the name of the smart card reader. The pbData parameter is the address of an ANSI character array that receives a null-terminated ANSI string that contains the name of the smart card reader. The size of this buffer, contained in the variable pointed to by the pdwDataLen parameter, must include the NULL terminator. Windows XP, Windows Server 2003, and Windows 2000:  This parameter is not supported.
PP_UNIQUE_CONTAINER	The unique container name of the current key container in the form of a null-terminated character string. For many CSPs, this name is the same as the name returned when PP_CONTAINER is used. The CryptAcquireContext function must work with this container name.
PP_USER_CERTSTORE	Obtains 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 pbData parameter is the address of an HCERTSTORE variable that receives the handle of an in-memory certificate store. When this handle is no longer needed, the caller will close it by using the CertCloseStore function. You can create a certificate store in memory by using the CertOpenStore function with the CERT_STORE_PROV_MEMORY option. You can then add certificates to this store by using the CertCreateCertificateContext and CertAddCertificateContextToStore functions. The certificates in this store must meet the following criteria: They must be encoded by using PKCS_7_ASN_ENCODING or X509_ASN_ENCODING encoding. They must contain the CERT_KEY_PROV_INFO_PROP_ID property. For more information, see CertSetCertificateContextProperty. Windows XP, Windows Server 2003, and Windows 2000:  This parameter is not supported.
PP_VERSION	The version number of the CSP. The least significant byte contains the minor version number and the next most significant byte contains the major version number. Version 2.0 is represented as 0x00000200. To maintain backward compatibility with earlier versions of the Microsoft Base Cryptographic Provider and Microsoft Enhanced Cryptographic Provider, the provider names retain the "v1.0" designation in later versions.

 

pbData [out]

A pointer to a data buffer. The dwParam parameter specifies the type of data to be copied to this buffer.

It is not an error if this parameter is NULL. If pbData is NULL, no parameter data is copied. Instead, the required buffer size, in bytes, is returned in pdwDataLen and a second call to the function with the correct number of bytes allocated for the pbData buffer is expected. For a detailed discussion and examples, see Retrieving Data of Unknown Length.

pdwDataLen [in, out]

A pointer to a buffer to hold the length of pbData. Upon function entry, it points to a DWORD value that indicates the number of bytes allocated for the pbData buffer. Upon exit, the DWORD value must be set to the number of bytes needed to hold pbData. When one of the enumeration parameters is being read, the value returned in pdwDataLen must indicate the size of the largest item in the enumeration list.

If the buffer specified by pbData is not large enough to hold the requested data, the ERROR_MORE_DATA error code is returned by the SetLastError function. In this case, the required buffer size must be returned in pdwDataLen.

If this function fails with any error code other than ERROR_MORE_DATA, this parameter returns zero.

dwFlags [in]

This parameter can be one of the following flags.

Value	Meaning
CRYPT_FIRST	Used only with an enumeration parameter such as PP_ENUMALGS, PP_ENUMALGS_EX, or PP_ENUMCONTAINERS. If this flag is set, the first item in the enumeration list is to be returned; otherwise, the next item in the list is returned. If this flag is set when a nonenumeration parameter is being read, the NTE_BAD_FLAGS error code is returned.
CRYPT_MACHINE_KEYSET	Can be set along with PP_ENUMCONTAINERS. If set, the key containers associated with a computer are enumerated, rather than those associated with the logged-in user. This flag is used by the Microsoft CSPs. Other CSPs may ignore this flag.
SECURITY_INFORMATION	If dwParam is set to PP_KEYSET_SEC_DESCR, the security descriptor of the key container is retrieved. For this case, dwFlags is used to pass in bit flags that can be combined by using a bitwise-OR operation. The pointer to the security descriptor is returned in the pbData parameter and the length of the security descriptor is returned in the pcbData parameter. This flag is used only by RSA base CSPs. A hardware-based CSP will not use this flag. For more information, see RegGetKeySecurity and RegSetKeySecurity. The following list defines the bit flags for the requested security information. OWNER_SECURITY_INFORMATION Indicates the owner identifier of the object being referenced. GROUP_SECURITY_INFORMATION Indicates the primary group identifier of the object being referenced. DACL_SECURITY_INFORMATION Indicates the discretionary ACL of the object being referenced. SACL_SECURITY_INFORMATION Indicates the system ACL of the object being referenced.

 

Return Value

If the function succeeds, the function returns TRUE.

If the function fails, it returns FALSE, and the following appropriate error code must be set using SetLastError.

Remarks

The required header file, Cspdk.h, is available only by downloading the Cryptographic Service Provider Developer's Kit (CSPDK). It can be downloaded from the Microsoft Download Center.

Requirements

See Also

CPAcquireContext

CPSetProvParam

CryptGetProvParam

Send comments about this topic to Microsoft

Build date: 11/16/2009