The CryptGetProvParam function lets applications retrieve parameters that govern the operations of a CSP.
BOOL CRYPTFUNC CryptGetProvParam(
HCRYPTPROV hProv, | |
DWORD dwParam, | |
BYTE *pbData, | |
DWORD *pdwDataLen, | |
DWORD dwFlags | |
); |
This parameter can be NULL if all you are doing is determining the number of
bytes required for the returned parameter data.
If the buffer specified by pbData is not large enough to hold the data, the function returns the ERROR_MORE_DATA error code through the GetLastError function, and stores the required buffer size in bytes into the variable pointed to by pdwDataLen.
If pbData is NULL, then no error is returned and the function stores the size of the data in bytes in the variable pointed to by pdwDataLen.
Note When one of the enumeration parameters (PP_ENUMALGS or PP_ENUMCONTAINERS) is being read, the pdwDataLen parameter works somewhat differently. If pbData is NULL or the value pointed to 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.
When one of the enumeration parameters (PP_ENUMALGS or PP_ENUMCONTAINERS) is being read, 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.
The dwParam parameter can be set to one of the following values:
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.
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 the 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.
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 table defines each of these fields.
Field |
Description |
aiAlgid |
The 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 |
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 |
The number of characters in the algorithm name, including the terminating zero. |
szName |
The zero-terminated name of the algorithm. |
These container names are enumerated in the same way as are the CSP’s
supported algorithms. Refer to the PP_ENUMALGS for more information.
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 RSA Base Provider will return “Microsoft Base Cryptographic Provider
v1.0” when this parameter is read.
When enumerating algorithms, 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:
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 it use the algorithm. Making use of an unknown cryptographic algorithm can sometimes produce unpredictable results.
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To retrieve extended error information, use the GetLastError function.
The following table lists the error codes most commonly returned by the GetLastError function. The error codes prefaced by “NTE” are generated by the particular CSP you are using.
Error |
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_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 only returned when dwParam equals PP_ENUMALGS or PP_ENUMCONTAINERS. |
NTE_BAD_FLAGS |
The dwFlags parameter is nonzero. |
NTE_BAD_TYPE |
The dwParam parameter specifies an unknown parameter number. |
NTE_BAD_UID |
The CSP context specified by hProv is invalid. |
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 dwDataLen; 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. dwDataLen = 1000; if(!CryptGetProvParam(hProv, PP_ENUMALGS, pbData, &dwDataLen, 0)) { if(GetLastError() == ERROR_NO_MORE_ITEMS) { // Exit the loop. break; } else { printf("Error %x reading algorithm!\n", GetLastError()); return; } } // Extract algorithm information from ‘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 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 algorithm. printf(“Algid:%8.8xh, Bits:%-4d, Type:%s, NameLen:%-2d, Name:%s\n”, aiAlgid, dwBits, pszAlgType, dwNameLen, szName ); }
CryptAcquireContext, CryptCreateHash, CryptDeriveKey, CryptGenKey, CryptGetKeyParam, CryptSetProvParam
file: /Techref/os/win/api/win32/func/src/f12_9.htm, 18KB, , updated: 2000/4/7 12:19, local time: 2024/8/16 14:38,
18.117.172.240:LOG IN
|
©2024 These pages are served without commercial sponsorship. (No popup ads, etc...).Bandwidth abuse increases hosting cost forcing sponsorship or shutdown. This server aggressively defends against automated copying for any reason including offline viewing, duplication, etc... Please respect this requirement and DO NOT RIP THIS SITE. Questions? <A HREF="http://sxlist.com/TECHREF/os/win/api/win32/func/src/f12_9.htm"> CryptGetProvParam Release 2]</A> |
Did you find what you needed? |
Welcome to sxlist.com!sales, advertizing, & kind contributors just like you! Please don't rip/copy (here's why Copies of the site on CD are available at minimal cost. |
Welcome to sxlist.com! |
.