Função CryptGetDefaultProviderA (wincrypt.h)

Artigo
11/20/2024

Importante essa API foi preterida. O software novo e existente deve começar a usar APIs de Próxima Geração da Criptografia. Microsoft pode remover essa API em versões futuras.

A função CryptGetDefaultProvider localiza o padrão CSP ( provedor de serviços criptográficos) padrão de um tipo de provedor especificado para o computador local ou o usuário atual. O nome do CSP padrão para o tipo de provedor especificado no parâmetro dwProvType é retornado no buffer pszProvName.

Sintaxe

BOOL CryptGetDefaultProviderA(
  [in]      DWORD dwProvType,
  [in]      DWORD *pdwReserved,
  [in]      DWORD dwFlags,
  [out]     LPSTR pszProvName,
  [in, out] DWORD *pcbProvName
);

Parâmetros

[in] dwProvType

O tipo de provedor para o qual o nome CSP padrão deve ser encontrado.

Os tipos de provedor definidos são os seguintes:

[in] pdwReserved

Esse parâmetro é reservado para uso futuro e deve ser NULL.

[in] dwFlags

Os valores de sinalizador a seguir são definidos.

Valor	Significado
CRYPT_USER_DEFAULT 0x00000002	Retorna o CSP padrão de contexto do usuário do tipo especificado.
CRYPT_MACHINE_DEFAULT 0x00000001	Retorna o CSP padrão do computador do tipo especificado.

[out] pszProvName

Um ponteiro para um buffer de cadeia de caracteres com término nulo para receber o nome do CSP padrão.

Para localizar o tamanho do buffer para fins de alocação de memória, esse parâmetro pode ser NULL. Para obter mais informações, consulte Recuperando dados dede comprimento desconhecido.

[in, out] pcbProvName

Um ponteiro para um valor DWORD que especifica o tamanho, em bytes, do buffer apontado pelo parâmetro pszProvName. Quando a função retorna, o valor DWORD contém o número de bytes armazenados ou a serem armazenados no buffer.

Observação Ao processar os dados retornados no buffer, os aplicativos devem usar o tamanho real dos dados retornados. O tamanho real pode ser ligeiramente menor do que o tamanho do buffer especificado na entrada. (Na entrada, os tamanhos de buffer geralmente são especificados grandes o suficiente para garantir que os maiores dados de saída possíveis se ajustem ao buffer.) Na saída, a variável apontada por esse parâmetro é atualizada para refletir o tamanho real dos dados copiados para o buffer.

Valor de retorno

Se a função for bem-sucedida, o valor retornado não será zero (TRUE).

Se a função falhar, o valor retornado será zero (false). Para obter informações de erro estendidas, chame GetLastError.

O código de erro precedido pelo NTE é gerado pelo CSP específico que está sendo usado. Os códigos de erro possíveis incluem o seguinte.

Código de retorno	Descrição
ERROR_INVALID_PARAMETER	Um dos parâmetros contém um valor que não é válido. Isso geralmente é um ponteiro que não é válido.
ERROR_MORE_DATA	O buffer para o nome não é grande o suficiente.
ERROR_NOT_ENOUGH_MEMORY	O sistema operacional ficou sem memória.
NTE_BAD_FLAGS	O parâmetro dwFlags tem um valor não reconhecido.

Observações

Essa função determina qual CSP instalado está atualmente definido como o padrão para o computador local ou o usuário atual. Essas informações geralmente são exibidas para o usuário.

Exemplos

O exemplo a seguir recupera o nome do CSP padrão para o tipo de provedor PROV_RSA_FULL. Para outro exemplo que usa essa função, consulte Exemplo de Programa C: Enumerando provedores CSP e tipos de provedor.

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

void main()
{

    DWORD       cbProvName=0;
    LPTSTR      pbProvName=NULL;
    // Copyright (C) Microsoft.  All rights reserved.
    // Get the length of the RSA_FULL default provider name.
    if (!(CryptGetDefaultProvider(
         PROV_RSA_FULL, 
         NULL, 
         CRYPT_MACHINE_DEFAULT,
         NULL, 
         &cbProvName))) 
    { 
      printf("Error getting the length of the default "
          "provider name.\n");
      exit(1);
    }

    // Allocate local memory for the name of the default provider.
    if (!(pbProvName = (LPTSTR)LocalAlloc(LMEM_ZEROINIT, 
        cbProvName)))
    {
        printf("Error during memory allocation for "
            "provider name.\n");
        exit(1);
    }

    // Get the default provider name.
    if (CryptGetDefaultProvider(
        PROV_RSA_FULL, 
        NULL, 
        CRYPT_MACHINE_DEFAULT,
        pbProvName,
        &cbProvName)) 
    {
        printf("The default provider name is %s\n",pbProvName);
    }
    else
    {
        printf("Getting the name of the provider failed.\n");
        exit(1);
    }

    // Free resources when done.
    LocalFree(pbProvName);

}

Nota

O cabeçalho wincrypt.h define CryptGetDefaultProvider como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2003 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	wincrypt.h
biblioteca	Advapi32.lib
de DLL	Advapi32.dll

Consulte também

CryptSetProvider

CryptSetProviderEx

Funções do provedor de serviços

Compartilhar via