CPGetProvParam

The CPGetProvParam function is called by applications to retrieve various data about the 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 (or "context") within the CSP. This handle is obtained via a call to CPAcquireContext.

dwParam

Parameter number. See the "Remarks" section for the list of currently defined parameters.

pbData

Parameter data buffer. The function copies the specified parameter data to this buffer. The form of this data will vary, depending on the parameter number.

If this parameter is NULL, then no parameter data should be copied. Instead, the required buffer size (in bytes) should be returned in pdwDataLen. This is not an error.

As noted in CryptGetProvParam (in the CryptoAPI), when one of the enumeration parameters is being read, the value returned in pdwDataLen should be the size of the largest item in the enumeration list.

pdwDataLen

Address of the parameter data length. Upon function entry, this contains the number of bytes in the pbData buffer. Upon exit, this must be set to the number of bytes of parameter data copied to the pbData buffer.

If the buffer specified by pbData is not large enough to hold the requested data, the ERROR_MORE_DATA error code should be returned via 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, zero should be returned in this parameter.

dwFlags

Flag values. Currently, the following flag has been defined for this function:

CRYPT_FIRST

When an enumeration parameter is being read (for example, PP_ENUMALGS or PP_ENUMCONTAINERS) and 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 should be returned.

Note  The following flag values are specific to RSAbase use only. CSPs that use a hardware solution will not use these flags.

CRYPT_MACHINE_KEYSET

When the enumeration parameter PP_ENUMCONTAINERS is being read, then the CRYPT_MACHINE_KEYSET flag can be specified. This flag can be set if you want the enumeration to come from the HKEY_LOCAL_MACHINE portion of the registry rather than from the HKEY_CURRENT_USER portion of the registry (the default).

SECURITY_INFORMATION bit flags

When the dwParam is PP_KEYSET_SEC_DESCR, the security descriptor on the registry key where the keys are stored is being retrieved. For this case, dwFlags is used to pass in the SECURITY_INFORMATION bit flags (can be combined with a bitwise OR operation) that indicates the requested security information. For more information, search the Microsoft Platform SDK for SECURITY_INFORMATION. The following is specified there:

typedef DWORD SECURITY_INFORMATION;

Return Values

If the function succeeds, TRUE should be returned; otherwise, return FALSE. When FALSE is returned, the appropriate error code (see the following table) must be set via SetLastError.

Remarks

The dwParam parameter can be set to one of the following values:

PP_CONTAINER

The key container name. A zero-terminated CHAR string containing the name of the current key container should be placed in the pbData buffer. The length of the string (including the terminating zero) should be returned in pdwDataLen.

Applications will often use this string to acquire this key container in a subsequent session, by passing it into the pszContainer parameter of CryptAcquireContext (in the CryptoAPI).

If the CSP only supports one key container (for example, one based on a smartcard with limited memory), then key container names may not be used. If this is the case, a null string "\0" can be returned in the pbData buffer.

PP_ENUMALGS

Supported algorithms. See CryptGetProvParam (in the CryptoAPI) for a description of this parameter.

PP_ENUMCONTAINERS

Key container names. A zero-terminated CHAR string containing the name of one of the key containers maintained by the CSP should be placed in the pbData buffer.

Applications read this parameter repeatedly in order to enumerate all of the key containers maintained by the CSP, in a manner similar to the PP_ENUMALGS parameter.

If the CSP supports only one key container, this parameter is often not supported. In this case, an NTE_BAD_TYPE error code should be returned.

PP_IMPTYPE

The CSP implementation type. A DWORD value containing the CSP's implementation type should be placed in the pbData buffer. A value of 4 should be returned in pdwDataLen.

The following implementation types are currently defined (in Wincrypt.h):

• CRYPT_IMPL_HARDWARE
• CRYPT_IMPL_SOFTWARE
• CRYPT_IMPL_MIXED
• CRYPT_IMPL_UNKNOWN

PP_NAME

The CSP name. A zero-terminated CHAR string containing the name of the CSP should be placed in the pbData buffer, and the length of the string (including the terminating zero) placed in pdwDataLen. This string must exactly match the "CSP Name" entries that the CSP's setup program installs in the Windows® Registry.

Applications will often use this CSP name in order to connect to the CSP in a subsequent session, by passing the name for the pszProvider parameter of CryptAcquireContext (in the CryptoAPI).

Note  Since it is desirable to perpetuate the CSP name across versions for backward compatibility, you may want to use only general terms in the CSP name and avoid specifics such as version numbers.

PP_VERSION

The CSP version number. A DWORD value containing the version number of the CSP should be placed in the pbData buffer, and a value of 4 should be placed in pdwDataLen. The least significant byte should contain the minor version number and the next most significant byte the major version number. For example, version 1.0 would be represented here as 0x00000100.

PP_KEYSET_SEC_DESCR.

Indicates that the security descriptor is to be retrieved for the registry entry where the key set is stored.

Note  The PP_KEYSET_SEC_DESCR flag is not supported under Microsoft Windows 95.

The dwFlags parameter is used to pass in the SECURITY_INFORMATION bit flags that indicate the requested security information. 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. It may be helpful to look at the documentation on RegGetKeySecurity and RegSetKeySecurity (WIN32 calls).

In the Win32 SDK in MSTOOLS\samples\win32\winnt\security\secperf is sample code showing how to manipulate NT ACLs.

Algorithm Identifiers

When enumerating algorithms (dwParam == PP_ENUMALGS), your application may need to determine the class of a particular algorithm. For example, you may want to display a list of encryption algorithms to the user and disregard the rest. This can be done with the GET_ALG_CLASS(x) macro. This macro takes an algorithm identifier as an argument and returns a code indicating the general class of algorithm that the identifier belongs to. Possible return values include:

ALG_CLASS_DATA_ENCRYPT

ALG_CLASS_HASH

ALG_CLASS_KEY_EXCHANGE

ALG_CLASS_SIGNATURE

The following table lists the algorithms supported by the Microsoft RSA Base Provider along with the class of each algorithm.

Name Identifier Class

"MD2" CALG_MD2 ALG_CLASS_HASH

"MD5" CALG_MD5 ALG_CLASS_HASH

"SHA" CALG_SHA ALG_CLASS_HASH

"MAC" CALG_MAC ALG_CLASS_HASH

"RSA_SIGN" CALG_RSA_SIGN ALG_CLASS_SIGNATURE

"RSA_KEYX" CALG_RSA_KEYX ALG_CLASS_KEY_EXCHANGE

"RC2" CALG_RC2 ALG_CLASS_DATA_ENCRYPT

"RC4" CALG_RC4 ALG_CLASS_DATA_ENCRYPT

If your application does not recognize an algorithm identifier, it is not recommended that you use the algorithm. Making use of an unknown cryptographic algorithm can sometimes produce unpredictable results.

See Also

CPAcquireContext, CPSetProvParam, CryptGetProvParam