CPGetProvParam

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

BOOL CPGetProvParam(
  HCRYPTPROV hProv,  // in
  DWORD dwParam,     // in
  BYTE *pbData,      // out
  DWORD *pdwDataLen, // in, out
  DWORD dwFlags      // in
);

Parameters

hProv

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

dwParam

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

dwParam value	Contents returned in pbData
PP_CONTAINER	The name of the current key container as a NULL-terminated CHAR 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. pszContainer can be read to determine the name of the default key container.
PP_ENUMALGS	Information about an algorithm supported by the CSP being queried. PP_ENUMALGS values 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 0 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 all of the available algorithms may not be enumerated if this function is used in a multithread context.
PP_ENUMALGS_EX	Information about an algorithm supported by the CSP. 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 enumerate all 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 0 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. PP_ENUMALGS_EX is supported in Microsoft® Internet Explorer version 4.0 or later, Microsoft® Windows NT® version 4.0 SP4, Windows 98 or later, and Windows 2000. This function is not thread-safe and all of the available algorithms may not be enumerated if this function is used in a multithread context.
PP_ENUMCONTAINERS	The name of one of the key containers maintained by the CSP in the form of a NULL-terminated CHAR 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 CSP's supported algorithms. This function is not thread-safe and all of the available container names mayt not be enumerated if this function is used in a multithread context.
PP_IMPTYPE	A DWORD value indicating how the CSP is implemented. Predefined implementation types CRYPT_IMPL_HARDWARE, CRYPT_IMPL_SOFTWARE, CRYPT_IMPL_MIXED, and CRYPT_IMPL_UNKNOWN are supported.
PP_NAME	The name of the CSP in the form of a NULL-terminated CHAR 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_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 1.0 is represented as 0x00000100. 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. Version 2.0 of these providers is included in Windows 2000.
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_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. This flag is supported in Windows 98 and later and Windows NT 4.0 and later.
PP_UNIQUE_ CONTAINER	The unique container name of the current key container in the form of a NULL-terminated CHAR 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_PROVTYPE	A DWORD value indicating the provider type of the CSP.

pbData

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

Pointer to a buffer to hold length of pbData. Upon function entry, it points to a DWORD value indicating 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

The following flags are defined for this function:

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 non-enumeration 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 value 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 with 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 value is used only by RSA base CSPs. A hardware-based CSP will not use this flag value. For more information, see RegGetKeySecurity and RegSetKeySecurity.

The following table contains bit flags indicating the requested security information.

Value	Meaning
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 Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 or later.
  Windows 95/98: Requires Windows 95 OSR2 or later (or Windows 95 with Internet Explorer 3.02 or later).
  Header: Declared in Wincrypt.h.

See Also

CPAcquireContext, CPSetProvParam, CryptGetProvParam