Export (0) Print
Expand All
1 out of 1 rated this helpful - Rate this topic

CryptGetProvParam (Windows CE 5.0)

Windows CE 5.0
Send Feedback

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

BOOL WINAPI CryptGetProvParam( 
  HCRYPTPROV hProv,
  DWORD dwParam, 
  BYTE* pbData, 
  DWORD* pdwDataLen, 
  DWORD dwFlags
);

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 valuepbData content
PP_CONTAINERName 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_ENUMALGSA 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_ENUMCONTAINERSName 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_IMPTYPEDWORD value that indicates CSP implementation. Common values are:
  • CRYPT_IMPL_HARDWARE
  • CRYPT_IMPL_SOFTWARE
  • CRYPT_IMPL_MIXED
  • CRYPT_IMPL_UNKNOWN
  • CRYPT_IMPL_REMOVABLE
PP_KEYSPECReturns 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_INCThe 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_NAMEThe 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_PROVTYPEDWORD value that indicates the provider type of the CSP.
PP_SIG_KEYSIZE_INCThe 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_VERSIONThe 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.
ValueDescription
OWNER_SECURITY_INFORMATIONReferences the owner identifier of the object.
GROUP_SECURITY_INFORMATIONReferences the primary group identifier of the object.
DACL_SECURITY_INFORMATIONReferences the discretionary access-control list (ACL) of the object.
SACL_SECURITY_INFORMATIONReferences 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.

ValueDescription
ERROR_INVALID_HANDLEOne of the parameters specifies an invalid handle.
ERROR_INVALID_PARAMETEROne of the parameters contains an invalid value. This is most often an illegal pointer.
ERROR_MORE_DATAIf 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_ITEMSThe 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_FLAGSThe dwFlags parameter specifies an invalid flag.
NTE_BAD_TYPEThe dwParam parameter specifies an unknown parameter number.
NTE_BAD_UIDThe 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.

ParameterDescription
aiAlgidAlgorithm identifier. This is the value that is passed to the CryptGenKey, CryptDeriveKey, or CryptCreateHash function to specify a particular algorithm.
dwBitsSpecifies 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.
dwNameLenSpecifies the number of characters in the algorithm name, including the terminating zero.
szNameNull-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.

NameIdentifierClass
"MD2"CALG_MD2ALG_CLASS_HASH
"MD5"CALG_MD5ALG_CLASS_HASH
"SHA"CALG_SHAALG_CLASS_HASH
"MAC"CALG_MACALG_CLASS_HASH
"RSA_SIGN"CALG_RSA_SIGNALG_CLASS_SIGNATURE
"RSA_KEYX"CALG_RSA_KEYXALG_CLASS_KEY_EXCHANGE
"RC2"CALG_RC2ALG_CLASS_DATA_ENCRYPT
"RC4"CALG_RC4ALG_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.

See Also

CryptAcquireContext | CryptCreateHash | CryptDeriveKey | CryptGenKey | CryptGetKeyParam | CryptSetProvParam


Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.


Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.