CryptEnumProvidersA function (wincrypt.h)

Important  This API is deprecated. New and existing software should start using Cryptography Next Generation APIs. Microsoft may remove this API in future releases.
 
The CryptEnumProviders function retrieves the first or next available cryptographic service providers (CSPs). Used in a loop, this function can retrieve in sequence all of the CSPs available on a computer.

Possible CSPs include Microsoft Base Cryptographic Provider version 1.0 and Microsoft Enhanced Cryptographic Provider version 1.0.

Syntax

BOOL CryptEnumProvidersA(
  [in]      DWORD dwIndex,
  [in]      DWORD *pdwReserved,
  [in]      DWORD dwFlags,
  [out]     DWORD *pdwProvType,
  [out]     LPSTR szProvName,
  [in, out] DWORD *pcbProvName
);

Parameters

[in] dwIndex

Index of the next provider to be enumerated.

[in] pdwReserved

Reserved for future use and must be NULL.

[in] dwFlags

Reserved for future use and must be zero.

[out] pdwProvType

Address of the DWORD value designating the type of the enumerated provider.

[out] szProvName

A pointer to a buffer that receives the data from the enumerated provider. This is a string including the terminating null character.

This parameter can be NULL to set the size of the name for memory allocation purposes. For more information, see Retrieving Data of Unknown Length.

[in, out] pcbProvName

A pointer to a DWORD value specifying the size, in bytes, of the buffer pointed to by the pszProvName parameter. When the function returns, the DWORD value contains the number of bytes stored in the buffer.

Note  When processing the data returned in the buffer, applications must use the actual size of the data returned. The actual size can 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 fits 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.
 

Return value

If the function succeeds, the return value is nonzero (TRUE).

If the function fails, the return value is zero (FALSE). For extended error information, call GetLastError.

The error codes prefaced by NTE are generated by the particular CSP being used. Some possible error codes follow.

Return code Description
ERROR_MORE_DATA
The pszProvName buffer was not large enough to hold the provider name.
ERROR_NO_MORE_ITEMS
There are no more items to enumerate.
ERROR_NOT_ENOUGH_MEMORY
The operating system ran out of memory.
NTE_BAD_FLAGS
The dwFlags parameter has an unrecognized value.
NTE_FAIL
Something was wrong with the type registration.

Remarks

This function enumerates the providers available on a computer. The provider types can be enumerated by using CryptEnumProviderTypes.

Examples

The following example shows a loop listing all available cryptographic service providers. For another example that uses the CryptEnumProviders function, see Example C Program: Enumerating CSP Providers and Provider Types.

#include <stdio.h>
#include <windows.h>
#include <Wincrypt.h>
#pragma comment(lib, "advapi32.lib")

void main()
{

    //---------------------------------------------------------------
    // Copyright (C) Microsoft.  All rights reserved.
    // Declare and initialize variables.

    DWORD       cbName;
    DWORD       dwType;
    DWORD       dwIndex;
    CHAR        *pszName = NULL; 

    // Print header lines for providers.
    printf("Listing Available Providers:\n");
    printf("Provider type\tProvider Name\n");
    printf("_____________\t__________________"
        "___________________\n");   

    //--------------------------------------------------------------- 
    // Loop through enumerating providers.
    dwIndex = 0;
    while(CryptEnumProviders(
           dwIndex,
           NULL,
           0,
           &dwType,
           NULL,
           &cbName
           ))
    {

        //-----------------------------------------------------------
        //  cbName returns the length of the name of the next 
        //  provider. Allocate memory in a buffer to retrieve 
        //  that name.

        if (!(pszName = (LPTSTR)LocalAlloc(LMEM_ZEROINIT, cbName)))
        {
           printf("ERROR - LocalAlloc failed\n");
           exit(1);
        }
        //-----------------------------------------------------------
        //  Get the provider name.
        if (CryptEnumProviders(
               dwIndex++,
               NULL,
               0,
               &dwType,
               pszName,
               &cbName
               ))
        {
            printf ("     %4.0d\t%s\n",dwType, pszName);
        }
        else
        {
            printf("ERROR - CryptEnumProviders failed.\n");
            exit(1);
        }
        LocalFree(pszName);

    } // End of while loop

    printf("\nProvider types and provider names "
        "have been listed.\n");
}

Note

The wincrypt.h header defines CryptEnumProviders as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement Value
Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header wincrypt.h
Library Advapi32.lib
DLL Advapi32.dll

See also

CryptEnumProviderTypes

Service Provider Functions