使用 CNG 的密碼編譯組態功能

CNG API 提供函式來列舉和取得已註冊提供者的相關資訊。

列舉提供者

您可以使用 BCryptEnumRegisteredProviders 函 式來列舉已註冊的提供者。 BCryptEnumRegisteredProviders函式可以透過下列兩種方式之一呼叫:

  1. 第一個是讓 BCryptEnumRegisteredProviders 函 式配置記憶體。 這可藉由傳遞ppBuffer參數的Null指標位址來完成。 此程式碼會配置 CRYPT_PROVIDERS 結構和相關聯字串所需的記憶體。 以這種方式使用 BCryptEnumRegisteredProviders 函式時,您必須將 ppBuffer 傳遞給 BCryptFreeBuffer 函式,以釋放不再需要的記憶體。

    下列範例示範如何使用 BCryptEnumRegisteredProviders 函 式為您配置緩衝區。

    #include <windows.h>
    
    #ifndef NT_SUCCESS
    #define NT_SUCCESS(Status) ((NTSTATUS)(Status) >= 0)
    #endif
    
    void EnumProviders1()
    {
        NTSTATUS status;
        ULONG cbBuffer = 0;
        PCRYPT_PROVIDERS pBuffer = NULL;
    
        /*
        Get the providers, letting the BCryptEnumRegisteredProviders 
        function allocate the memory.
        */
        status = BCryptEnumRegisteredProviders(&cbBuffer, &pBuffer);
    
        if (NT_SUCCESS(status))
        {
            if (pBuffer != NULL)
            {
                // Enumerate the providers.
                for (ULONG i = 0; i < pBuffer->cProviders; i++)
                {
                    printf("%S\n", pBuffer->rgpszProviders[i]);
                }
            }
        }
        else
        {
            printf("BCryptEnumRegisteredProviders failed with error " 
                "code 0x%08x\n", status);
        }
    
        if (NULL != pBuffer)
        {
            /*
            Free the memory allocated by the 
            BCryptEnumRegisteredProviders function.
            */
            BCryptFreeBuffer(pBuffer);
        }
    }
    
    
  2. 第二種方法是自行配置所需的記憶體。 若要達成此目的,請使用ppBuffer參數的Null呼叫BCryptEnumRegisteredProviders函式。 BCryptEnumRegisteredProviders函式會放在由CRYPT_PROVIDERS結構和所有字串CRYPT_PROVIDERS參數所指向的值中。 接著,您會配置必要的記憶體,並在第二次呼叫BCryptEnumRegisteredProviders函式時,為ppBuffer參數傳遞這個緩衝區指標的位址。

    下列範例示範如何使用 BCryptEnumRegisteredProviders 函 式來配置及使用您自己的緩衝區。

    #include <windows.h>
    #include <stdio.h>
    
    #ifndef NT_SUCCESS
    #define NT_SUCCESS(Status) ((NTSTATUS)(Status) >= 0)
    #endif
    
    void EnumProviders2()
    {
        NTSTATUS status;
        ULONG cbBuffer = 0;
    
        // Get the required size of the buffer.
        status = BCryptEnumRegisteredProviders(&cbBuffer, NULL);
    
        if (STATUS_BUFFER_TOO_SMALL == status)
        {
            // Allocate the buffer.
            PCRYPT_PROVIDERS pBuffer = 
                (PCRYPT_PROVIDERS)LocalAlloc(LPTR, cbBuffer);
            if (NULL != pBuffer)
            {
                // Get the providers in the buffer that was allocated.
                status = BCryptEnumRegisteredProviders(
                    &cbBuffer, 
                    &pBuffer);
                if (NT_SUCCESS(status))
                {
                    for (ULONG i = 0; i < pBuffer->cProviders; i++)
                    {
                        // Enumerate the providers.
                        printf("%S\n", pBuffer->rgpszProviders[i]);
                    }
                }
    
                // Free the memory that was allocated.
                LocalFree(pBuffer);
            }
        }
    }
    
    

取得提供者註冊資訊

BCryptQueryProviderRegistration函式可用來取得提供者的其他註冊特定資訊。 此函式會採用您想要取得資訊的提供者名稱、所需的提供者模式 (核心模式、使用者模式或兩者) ,以及提供者介面的識別碼,以擷取註冊資訊。 例如,若要取得 「Microsoft Primitive Provider」 提供者之加密介面的使用者模式註冊資訊,您會進行類似下列的呼叫。

BCryptQueryProviderRegistration(
    MS_PRIMITIVE_PROVIDER,
    CRYPT_UM,
    BCRYPT_CIPHER_INTERFACE,
    //...
    );

如同 BCryptEnumRegisteredProviders 函 式, BCryptQueryProviderRegistration 函式可以為您配置記憶體,也可以自行配置記憶體。 這兩個函式的程式相同。