CryptGetProvParam (Windows CE 5.0)

Article
09/14/2012

This function retrieves parameters that govern the operations of a cryptographic service provider (CSP).

BOOL WINAPI CryptGetProvParam( HCRYPTPROVhProv,DWORDdwParam,BYTE* pbData,DWORD* pdwDataLen,DWORDdwFlags);

Parameters

hProv
[in] HCRYPTPROV handle to a CSP created by a call to CryptAcquireContext.

dwParam
[in] Specifies the nature of the query. The following table shows defined queries.

Parameter value	pbData content
PP_CONTAINER	Name of the current key container as a wide-character string. This string is exactly the same as the one passed in the pszContainer parameter of the CryptAcquireContext function to specify the key container to use. The pszContainer parameter can be read to determine the name of the default key container.
PP_ENUMALGS	A PROV_ENUMALGS structure containing information about one algorithm supported by the CSP being queried. PP_ENUMALGS values must be read repeatedly to list all of the supported algorithms. The algorithms are not enumerated in any particular order. The first time that the PP_ENUMALGS value 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. The PP_ENUMALGS value can then be repeatedly read with dwFlags set to 0 to retrieve the information about the rest of the supported algorithms. When this 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 might not be enumerated if this function is used in a multithread context. For additional information, see the Remarks section at the end of this topic.
PP_ENUMALGS_EX	PROV_ENUMALGS_EX structure containing information about one 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 enumerate all the supported algorithms. The algorithms are not enumerated in any particular order. The first time that the PP_ENUMALGS_EX value 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. The PP_ENUMALGS_EX value can then be repeatedly read with dwFlags set to 0 to retrieve the information about the rest of the supported algorithms. When this 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 might not be enumerated if this function is used in a multithread context.
PP_ENUMCONTAINERS	Name of one of the key containers maintained by the CSP in the form of a wide-character string. The PP_ENUMCONTAINERS value must be read repeatedly to enumerate all the container names. Container names are enumerated in the same way as the CSP's supported algorithms. All of the available container names might not be enumerated if this function is used in a multithread context.
PP_IMPTYPE	DWORD value that indicates CSP implementation. Common values are: CRYPT_IMPL_HARDWARE CRYPT_IMPL_SOFTWARE CRYPT_IMPL_MIXED CRYPT_IMPL_UNKNOWN CRYPT_IMPL_REMOVABLE
PP_KEYSPEC	Returns information on the key specifiers the CSP supports. Key specifier values are joined in a logical OR and returned as a DWORD value in pbData. For example, the Microsoft Base Cryptographic Provider version 1.0 returns a DWORD value of AT_SIGNATURE \| AT_KEYEXCHANGE.
PP_KEYX_KEYSIZE_INC	The number of bits for the increment length of AT_KEYEXCHANGE. This information is used with information returned in the PP_ENUMALGS_EX value. With the information returned when using PP_ENUMALGS_EX and PP_KEYX_KEYSIZE_INC, the valid key lengths for AT_KEYEXCHANGE can be determined. These key lengths can then be used with CryptGenKey. For example if a CSP enumerates CALG_RSA_KEYX (AT_KEYEXCHANGE) with a minimum key length of 512 bits and a maximum of 1024 bits, and returns the increment length as 64 bits, then valid key lengths are 512, 576, 640, ... 1024.
PP_NAME	The name of the CSP in the form of a wide-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	DWORD value that indicates the provider type of the CSP.
PP_SIG_KEYSIZE_INC	The number of bits for the increment length of AT_SIGNATURE. This information is used with information returned in the PP_ENUMALGS_EX value. With the information returned when using PP_ENUMALGS_EX and PP_SIG_KEYSIZE_INC, the valid key lengths for AT_SIGNATURE can be determined. These key lengths can then be used with CryptGenKey. For example, if a CSP enumerates CALG_RSA_SIGN (AT_SIGNATURE) with a minimum key length of 512 bits and a maximum of 1024 bits, and returns the increment length as 64 bits, then valid key lengths are 512, 576, 640, ... 1024.
PP_VERSION	The version number of the CSP. The least significant byte contains the minor version number and the next most significant byte 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 the Microsoft Enhanced Cryptographic Provider, the provider names retain the v1.0 designation in later versions.

pbData
[out] Pointer to a buffer that receives the specified parameter data. The form of this data varies depending on the dwParam value.

This parameter can be NULL to set the buffer size for memory allocation purposes.
pdwDataLen
[in, out] On input, pointer to a DWORD value that specifies the size, in bytes, of the buffer pointed to by the pbData parameter. On output, the function returns the DWORD value pointed to by the pdwDataLen parameter containing the number of bytes stored in the buffer.

When processing the data returned in the buffer, applications must use the actual size of the data returned. The actual size may be slightly smaller than the size of the buffer specified on input. On input, buffer sizes are usually specified large enough to ensure that the largest possible output data will fit in the buffer. On output, the variable pointed to by this parameter is updated to reflect the actual size of the data copied to the buffer.

If PP_ENUMALGS or PP_ENUMCONTAINERS is set, the pdwDataLen parameter works somewhat differently. If pbData is NULL or the value pointed to by pdwDataLen is too small, the value returned in this parameter is the size of the largest item in the enumeration list instead of the size of the item currently being read.

If PP_ENUMCONTAINERS is set, the first call to the function returns the size of the maximum key container allowed by the current provider. This is in contrast to other possible behaviors, like returning the length of the longest existing container or the length of the current container. Subsequent enumerating calls will not change the dwDataLen parameter. For each enumerated container, the caller can determine the length of the null-terminated string programmatically, if desired. If one of the enumeration values is read and the pbData parameter is NULL, the CRYPT_FIRST flag must be specified for the size information to be correctly retrieved.

dwFlags
[in] Bitmask of flags. The following table shows SECURITY_INFORMATION bit flags.

Value	Description
OWNER_SECURITY_INFORMATION	References the owner identifier of the object.
GROUP_SECURITY_INFORMATION	References the primary group identifier of the object.
DACL_SECURITY_INFORMATION	References the discretionary access-control list (ACL) of the object.
SACL_SECURITY_INFORMATION	References the system ACL of the object.

If PP_ENUMALGS or PP_ENUMCONTAINERS is set and the CRYPT_FIRST flag is specified in dwFlags, the functions returns the first item in the enumeration list; otherwise, the functions returns the next item in the list

If PP_ENUMCONTAINERS is set, the CRYPT_MACHINE_KEYSET flag in dwFlags can be specified to enumerate the key containers associated with a computer rather than the key containers associated with the current user.

If PP_KEYSET_SEC_DESCR is set, the function retrieves the security descriptor on the key container where the keys are stored. In this case, dwFlags passes the SECURITY_INFORMATION bit flags that can be combined with a bitwise OR operation.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the GetLastError function.

The following table shows the common values for the GetLastError function. The error values prefaced by NTE are generated by the particular CSP you are using.

Value	Description
ERROR_INVALID_HANDLE	One of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETER	One of the parameters contains an invalid value. This is most often an illegal pointer.
ERROR_MORE_DATA	If the buffer specified by the pbData parameter is not large enough to hold the returned data, the function sets the ERROR_MORE_DATA code, and stores the required buffer size, in bytes, into the variable pointed to by pdwDataLen.
ERROR_NO_MORE_ITEMS	The end of the enumeration list has been reached. No valid data has been placed in the pbData buffer. This error is returned only when dwParam equals PP_ENUMALGS or PP_ENUMCONTAINERS.
NTE_BAD_FLAGS	The dwFlags parameter specifies an invalid flag.
NTE_BAD_TYPE	The dwParam parameter specifies an unknown parameter number.
NTE_BAD_UID	The CSP context specified by hProv is invalid.

Remarks

When calling this function with the PP_ENUMALGS flag in the dwParam parameter, the dwBits parameter should contain the length of the default key sizes.

The following code fragment indicates the format of the data that the function returns in the pbData buffer.

ALG_ID aiAlgid;
DWORD dwBits;
DWORD dwNameLen;
WCHAR szName[dwNameLen];

The following table shows each of these parameters.

Parameter	Description
aiAlgid	Algorithm identifier. This is the value that is passed to the CryptGenKey, CryptDeriveKey, or CryptCreateHash function to specify a particular algorithm.
dwBits	Specifies the number of bits in the keys used by the algorithm. For a hash algorithm, this value indicates the number of bits in the hash values generated by this algorithm.
dwNameLen	Specifies the number of characters in the algorithm name, including the terminating zero.
szName	Null-terminated string that contains the name of the algorithm.

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. The following list shows the common return values for the GET_ALG_CLASS macro:

ALG_CLASS_ANY
ALG_CLASS_DATA_ENCRYPT
ALG_CLASS_HASH
ALG_CLASS_KEY_EXCHANGE
ALG_MSG_ENCRYPT
ALG_CLASS_SIGNATURE

The following table shows the algorithms supported by the Microsoft Base Cryptographic 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. Using an unknown cryptographic algorithm can sometimes produce unpredictable results.

Example Code

This example shows how the list of algorithms supported by a particular CSP is accessed by an application.

HCRYPTPROV hProv; // Handle to CSP
DWORD dwAlgCount;
BYTE *ptr = NULL;
DWORD i;
ALG_ID aiAlgid;
DWORD dwBits;
DWORD dwNameLen;
CHAR szName[100]; // Often allocated dynamically
BYTE pbData[1000]; // Often allocated dynamically
DWORD cbData;
DWORD dwFlags;
CHAR *pszAlgType = NULL;

// Enumerate the supported algorithms.
for(i=0 ; ; i++) {
 // Set the CRYPT_FIRST flag the first time through the loop.
 if(i == 0) {
 dwFlags = CRYPT_FIRST;
 } else {
 dwFlags = 0;
 }

// Retrieve information about an algorithm.
 cbData = 1000;
 if(!CryptGetProvParam(hProv, PP_ENUMALGS, pbData, &cbData, dwFlags)) {
 if(GetLastError() == ERROR_NO_MORE_ITEMS) {
 // Exit the loop.
 break;
 } else {
 printf("Error %x reading algorithm!\n", GetLastError());
 return;
 }
 }

 // Extract algorithm information from the 'pbData' buffer.
 ptr = pbData;
 aiAlgid = *(ALG_ID *)ptr;
 ptr += sizeof(ALG_ID);
 dwBits = *(DWORD *)ptr;
 ptr += sizeof(DWORD);
 dwNameLen = *(DWORD *)ptr;
 ptr += sizeof(DWORD);
 strncpy(szName, ptr, dwNameLen);

 // Determine the algorithm type.
 switch(GET_ALG_CLASS(aiAlgid)) {
 case ALG_CLASS_DATA_ENCRYPT: pszAlgType = "Encrypt ";
  break;
 case ALG_CLASS_HASH: pszAlgType = "Hash ";
  break;
 case ALG_CLASS_KEY_EXCHANGE: pszAlgType = "Exchange ";
  break;
 case ALG_CLASS_SIGNATURE: pszAlgType = "Signature";
  break;
 default: pszAlgType = "Unknown ";
 }

 // Print information about the algorithm.
 printf("Algid:%8.8xh, Bits:%-4d, Type:%s, NameLen:%-2d, Name:%s\n",
 aiAlgid, dwBits, pszAlgType, dwNameLen, szName
 );
}

Requirements

OS Versions: Windows CE 2.10 and later.
Header: Wincrypt.h.
Link Library: Coredll.lib.