CryptGetProvParam

This function lets applications retrieve 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] Handle to the CSP on which to query parameters.

• dwParam
  [in] Specifies the parameter number. See the Remarks section for a list of valid parameters.

• pbData
  [out] Pointer to a buffer that receives the specified parameter data. The form of this data will vary, depending on the parameter number.

  This parameter can be NULL to set the size of this information for memory allocation purposes.

• pdwDataLen
  [in/out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pbData parameter. When the function returns, the variable pointed to by the pdwDataLen parameter contains the number of bytes stored in the buffer.

  Note   When processing the data returned in the buffer, applications need to 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.

  Note   When one of the enumeration parameters (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.

  When one of the enumeration parameters is read and the pbData parameter is NULL, the CRYPT_FIRST flag must be specified in order for the size information to be correctly retrieved.

• dwFlags
  [in] Specifies a bitmask of flags.

  When one of the enumeration parameters (PP_ENUMALGS or PP_ENUMCONTAINERS) is set, then the CRYPT_FIRST flag can be specified. When this flag is set, the first item in the enumeration list is returned. If this flag is not set, then the next item in the list is returned.

  When the enumeration parameter PP_ENUMCONTAINERS is set, then the CRYPT_MACHINE_KEYSET flag can be specified. This flag can be set to enumerate the key containers associated with a computer rather than the key containers associated with the current user.

  When the dwParam is PP_KEYSET_SEC_DESCR, the security descriptor on the key container where the keys are stored is retrieved. For this case, dwFlags is used to pass in the SECURITY_INFORMATION bit flags (can be combined with a bitwise OR operation).

  typedef DWORD SECURITY_INFORMATION;
  

  Value	Description
  OWNER_SECURITY_INFORMATION	Indicates the owner identifier of the object is being referenced.
  GROUP_SECURITY_INFORMATION	Indicates the primary group identifier of the object is being referenced.
  DACL_SECURITY_INFORMATION	Indicates the discretionary ACL of the object is being referenced.
  SACL_SECURITY_INFORMATION	Indicates the system ACL of the object is being referenced.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call GetLastError. Common values for GetLastError are described in the following table. The error values prefaced by "NTE" are generated by the particular CSP you are using.

Remarks

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

• PP_CONTAINER
  The key container name. When this parameter is specified, the function fills the pbData buffer with the name of the current key container. This name is in the form of a zero-terminated CHAR string.

  This string is exactly the same as the one passed in the pszContainer parameter of the CryptAcquireContext function in order to specify that the current key container be used. This parameter is often read in order to determine the name of the default key container.

• PP_ENUMALGS
  The algorithm information. When this parameter is specified, the function fills the pbData buffer with information about one of the algorithms supported by the CSP. The PP_ENUMALGS parameter 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 parameter is read, the CRYPT_FIRST flag should be specified. This will ensure that information about the first algorithm in the enumeration list is returned. The PP_ENUMALGS parameter can then be repeatedly read in order to retrieve the information about the rest of the algorithms. When the CryptGetProvParam function fails with ERROR_NO_MORE_ITEMS, then the end of the enumeration list has been reached. A code sample illustrating this is located in the "Example" section.

  When calling CryptGetProvParam with the PP_ENUMALGS flag in the dwParam parameter the dwBits field should be changed to 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;
  CHAR szName[dwNameLen];
  
  

  The following list defines each of these fields.

  Field	Description
  aiAlgid	Algorithm identifier. This is the value that is passed to the CryptGenKey, CryptDeriveKey, or CryptCreateHash functions in order to specify that a particular algorithm be used.
  DwBits	Specifies the number of bits in the keys used by the algorithm.
  	If this is 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.

• PP_ENUMCONTAINERS
  The key container names. When this parameter is specified, the function fills the pbData buffer with the name of one of the key containers maintained by the CSP. This name is in the form of a zero-terminated CHAR string. The PP_ENUMCONTAINERS parameter must be read repeatedly to enumerate all the container names.

  These container names are enumerated in the same way as are the CSP's supported algorithms. Refer to the PP_ENUMALGS entry for more information.

• PP_IMPTYPE
  The CSP implementation type. The pbData buffer will contain a DWORD value that indicates how the CSP is implemented. Common values are:

  • CRYPT_IMPL_HARDWARE
  • CRYPT_IMPL_SOFTWARE
  • CRYPT_IMPL_MIXED
  • CRYPT_IMPL_UNKNOWN

• PP_NAME
  The CSP name. When this parameter is specified, the function fills the pbData buffer with the name of the CSP. This name is in the form of a zero-terminated CHAR string.

  This string is identical to the one passed in the pszProvider parameter of the CryptAcquireContext function in order to specify that the current CSP be used. For example, the Microsoft Base Cryptographic Provider will return "Microsoft Base Cryptographic Provider v1.0" when this parameter is read.

• PP_VERSION
  The CSP version number. The pbData buffer will contain a DWORD value that indicates 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. For example, version 1.0 would be represented here as 0x00000100.

  To maintain backward compatibility with earlier versions of these providers, the name retains the "v1.0" designation in later versions. This can be seen in the wincrypt.h header file. Version 2.0 of this provider is currently shipping. To see which version of the provider you have, make a call to CryptGetProvParam with the dwParam argument set to PP_VERSION. For example, if 0x00000200 is returned in pbData, then you have version 2.0.

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. Common 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 Base Cryptographic Provider along with the class of each algorithm.

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.

Example

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

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

CryptAcquireContext, CryptCreateHash, CryptDeriveKey, CryptGenKey, CryptGetKeyParam, CryptSetProvParam

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.