Compartilhar via


Função CryptGetProvParam (wincrypt.h)

Importante Essa API foi preterida. O software novo e existente deve começar a usar APIs de Criptografia de Próxima Geração. A Microsoft pode remover essa API em versões futuras.
 
A função CryptGetProvParam recupera parâmetros que regem as operações de um CSP ( provedor de serviços criptográficos ).

Sintaxe

BOOL CryptGetProvParam(
  [in]      HCRYPTPROV hProv,
  [in]      DWORD      dwParam,
  [out]     BYTE       *pbData,
  [in, out] DWORD      *pdwDataLen,
  [in]      DWORD      dwFlags
);

Parâmetros

[in] hProv

Um identificador do destino CSP da consulta. Esse identificador deve ter sido criado usando a função CryptAcquireContext .

[in] dwParam

A natureza da consulta. As consultas a seguir são definidas.

Valor Significado
PP_ADMIN_PIN
31 (0x1F)
Retorna o PIN (número de identificação pessoal) do administrador no parâmetro pbData como um LPSTR.
PP_APPLI_CERT
18 (0x12)
Essa constante não é usada.
PP_CHANGE_PASSWORD
7 (0x7)
Essa constante não é usada.
PP_CERTCHAIN
9 (0x9)
Retorna a cadeia de certificados associada ao identificador hProv . A cadeia de certificados retornada é X509_ASN_ENCODING codificada.
PP_CONTAINER
6 (0x6)
O nome do contêiner de chave atual como uma cadeia de caracteres CHAR terminada em nulo. Essa cadeia de caracteres é exatamente a mesma que a passada no parâmetro pszContainer da função CryptAcquireContext para especificar o contêiner de chave a ser usado. O parâmetro pszContainer pode ser lido para determinar o nome do contêiner de chave padrão.
PP_CRYPT_COUNT_KEY_USE
41 (0x29)
Não implementado pelos CSPs da Microsoft. Esse comportamento pode ser implementado por outros CSPs.

Windows XP: Não há suporte para esse parâmetro.

PP_ENUMALGS
1 (0x1)
Uma estrutura PROV_ENUMALGS que contém informações sobre um algoritmo compatível com o CSP que está sendo consultado.

Na primeira vez que esse valor for lido, o parâmetro dwFlags deve conter o sinalizador CRYPT_FIRST . Isso faz com que essa função recupere o primeiro elemento na enumeração. Os elementos subsequentes podem ser recuperados definindo o sinalizador CRYPT_NEXT no parâmetro dwFlags . Quando essa função falha com o código de erro ERROR_NO_MORE_ITEMS , o final da enumeração foi atingido.

Essa função não é thread-safe e todos os algoritmos disponíveis podem não ser enumerados se essa função for usada em um contexto multithread.

PP_ENUMALGS_EX
22 (0x16)
Uma estrutura PROV_ENUMALGS_EX que contém informações sobre um algoritmo compatível com o CSP que está sendo consultado. A estrutura retornada contém mais informações sobre o algoritmo do que a estrutura retornada para PP_ENUMALGS.

Na primeira vez que esse valor for lido, o parâmetro dwFlags deve conter o sinalizador CRYPT_FIRST . Isso faz com que essa função recupere o primeiro elemento na enumeração. Os elementos subsequentes podem ser recuperados definindo o sinalizador CRYPT_NEXT no parâmetro dwFlags . Quando essa função falha com o código de erro ERROR_NO_MORE_ITEMS , o final da enumeração foi atingido.

Essa função não é thread-safe e todos os algoritmos disponíveis podem não ser enumerados se essa função for usada em um contexto multithread.

PP_ENUMCONTAINERS
2 (0x2)
O nome de um dos contêineres de chave mantidos pelo CSP na forma de uma cadeia de caracteres CHAR terminada em nulo.

Na primeira vez que esse valor for lido, o parâmetro dwFlags deve conter o sinalizador CRYPT_FIRST . Isso faz com que essa função recupere o primeiro elemento na enumeração. Os elementos subsequentes podem ser recuperados definindo o sinalizador CRYPT_NEXT no parâmetro dwFlags . Quando essa função falha com o código de erro ERROR_NO_MORE_ITEMS , o final da enumeração foi atingido.

Para enumerar contêineres de chave associados a um computador, primeiro chame CryptAcquireContext usando o sinalizador CRYPT_MACHINE_KEYSET e use o identificador retornado de CryptAcquireContext como o parâmetro hProv na chamada para CryptGetProvParam.

Essa função não é thread-safe e todos os algoritmos disponíveis podem não ser enumerados se essa função for usada em um contexto multithread.

PP_ENUMELECTROOTS
26 (0x1A)
Essa constante não é usada.
PP_ENUMEX_SIGNING_PROT
40 (0x28)
Indica que o CSP atual dá suporte ao membro dwProtocols da estrutura PROV_ENUMALGS_EX . Se essa função for bem-sucedida, o CSP dará suporte ao membro dwProtocols da estrutura PROV_ENUMALGS_EX . Se essa função falhar com um código de erro NTE_BAD_TYPE , o CSP não dará suporte ao membro dwProtocols .
PP_ENUMMANDROOTS
25 (0x19)
Essa constante não é usada.
PP_IMPTYPE
3 (0x3)
Um valor DWORD que indica como o CSP é implementado. Para obter uma tabela de valores possíveis, consulte Comentários.
PP_KEY_TYPE_SUBTYPE
10 (0xA)
Essa consulta não é usada.
PP_KEYEXCHANGE_PIN
32 (0x20)
Especifica que o PIN de troca de chaves está contido em pbData. O PIN é representado como uma cadeia de caracteres ASCII terminada em nulo.
PP_KEYSET_SEC_DESCR
8 (0x8)
Recupera o descritor de segurança para o contêiner de armazenamento de chaves. O parâmetro pbData é o endereço de uma estrutura SECURITY_DESCRIPTOR que recebe o descritor de segurança para o contêiner de armazenamento de chaves. O descritor de segurança é retornado em formato auto-relativo.
PP_KEYSET_TYPE
27 (0x1B)
Determina se o parâmetro hProv é um conjunto de chaves do computador. O parâmetro pbData deve ser um DWORD; O DWORD será definido como o sinalizador CRYPT_MACHINE_KEYSET se esse sinalizador tiver sido passado para a função CryptAcquireContext .
PP_KEYSPEC
39 (0x27)
Retorna informações sobre os valores do especificador de chave compatíveis com o CSP. Os valores do especificador de chave são unidos em um OR lógico e retornados no parâmetro pbData da chamada como um DWORD. Por exemplo, o Microsoft Base Cryptographic Provider versão 1.0 retorna um valor DWORD de AT_SIGNATURE | AT_KEYEXCHANGE.
PP_KEYSTORAGE
17 (0x11)
Retorna um valor DWORD de CRYPT_SEC_DESCR.
PP_KEYX_KEYSIZE_INC
35 (0x23)
O número de bits para o comprimento de incremento de AT_KEYEXCHANGE. Essas informações são usadas com informações retornadas no valor PP_ENUMALGS_EX. Com as informações retornadas ao usar PP_ENUMALGS_EX e PP_KEYX_KEYSIZE_INC, os comprimentos de chave válidos para AT_KEYEXCHANGE podem ser determinados. Esses comprimentos de chave podem ser usados com CryptGenKey. Por exemplo, se um CSP enumerar CALG_RSA_KEYX (AT_KEYEXCHANGE) com um comprimento mínimo de chave de 512 bits e um máximo de 1024 bits e retornar o comprimento de incremento como 64 bits, os comprimentos de chave válidos serão 512, 576, 640,... 1024.
PP_NAME
4 (0x4)
O nome do CSP na forma de uma cadeia de caracteres CHAR terminada em nulo. Essa cadeia de caracteres é idêntica à passada no parâmetro pszProvider da função CryptAcquireContext para especificar que o CSP atual seja usado.
PP_PROVTYPE
16 (0x10)
Um valor DWORD que indica o tipo de provedor do CSP.
PP_ROOT_CERTSTORE
46 (0x2E)
Obtém o repositório de certificados raiz para a cartão inteligente. Esse repositório de certificados contém todos os certificados raiz armazenados na cartão inteligente.

O parâmetro pbData é o endereço de uma variável HCERTSTORE que recebe o identificador do repositório de certificados. Quando esse identificador não for mais necessário, o chamador deverá fechá-lo usando a função CertCloseStore .

Windows Server 2003 e Windows XP: Não há suporte para esse parâmetro.

PP_SESSION_KEYSIZE
20 (0x14)
O tamanho, em bits, da chave de sessão.
PP_SGC_INFO
37 (0x25)
Usado com criptografia restrita do servidor.
PP_SIG_KEYSIZE_INC
34 (0x22)
O número de bits para o comprimento de incremento de AT_SIGNATURE. Essas informações são usadas com informações retornadas no valor PP_ENUMALGS_EX. Com as informações retornadas ao usar PP_ENUMALGS_EX e PP_SIG_KEYSIZE_INC, os comprimentos de chave válidos para AT_SIGNATURE podem ser determinados. Esses comprimentos de chave podem ser usados com CryptGenKey.

Por exemplo, se um CSP enumerar CALG_RSA_SIGN (AT_SIGNATURE) com um comprimento mínimo de chave de 512 bits e um máximo de 1024 bits e retornar o comprimento de incremento como 64 bits, os comprimentos de chave válidos serão 512, 576, 640,... 1024.

PP_SIGNATURE_PIN
33 (0x21)
Especifica que o PIN de assinatura de chave está contido em pbData. O PIN é representado como uma cadeia de caracteres ASCII terminada em nulo.
PP_SMARTCARD_GUID
45 (0x2D)
Obtém o identificador do cartão inteligente. O parâmetro pbData é o endereço de uma estrutura GUID que recebe o identificador da cartão inteligente.

Windows Server 2003 e Windows XP: Não há suporte para esse parâmetro.

PP_SMARTCARD_READER
43 (0x2B)
Obtém o nome do leitor de cartão inteligente. O parâmetro pbData é o endereço de uma matriz de caracteres ANSI que recebe uma cadeia de caracteres ANSI terminada em nulo que contém o nome do leitor de cartão inteligente. O tamanho desse buffer, contido na variável apontada pelo parâmetro pdwDataLen , deve incluir o terminador NULL .

Windows Server 2003 e Windows XP: Não há suporte para esse parâmetro.

PP_SYM_KEYSIZE
19 (0x13)
O tamanho da chave simétrica.
PP_UI_PROMPT
21 (0x15)
Essa consulta não é usada.
PP_UNIQUE_CONTAINER
36 (0x24)
O nome do contêiner exclusivo do contêiner de chave atual na forma de uma cadeia de caracteres CHAR terminada em nulo. Para muitos CSPs, esse nome é o mesmo nome retornado quando o valor PP_CONTAINER é usado. A função CryptAcquireContext deve funcionar com esse nome de contêiner.
PP_USE_HARDWARE_RNG
38 (0x26)
Indica se há suporte para um RNG (gerador de número aleatório de hardware). Quando PP_USE_HARDWARE_RNG for especificado, a função terá êxito e retornará TRUE se houver suporte para um RNG de hardware. A função falhará e retornará FALSE se não houver suporte para um RNG de hardware. Se houver suporte para um RNG, PP_USE_HARDWARE_RNG poderá ser definido em CryptSetProvParam para indicar que o CSP deve usar exclusivamente o RNG de hardware para esse contexto de provedor. Quando PP_USE_HARDWARE_RNG é usado, o parâmetro pbData deve ser NULL e dwFlags deve ser zero.

Nenhum dos CSPs da Microsoft atualmente dá suporte ao uso de um RNG de hardware.

PP_USER_CERTSTORE
42 (0x2A)
Obtém o repositório de certificados do usuário para o cartão inteligente. Esse repositório de certificados contém todos os certificados de usuário armazenados na cartão inteligente. Os certificados neste repositório são codificados usando PKCS_7_ASN_ENCODING ou codificação X509_ASN_ENCODING e devem conter a propriedade CERT_KEY_PROV_INFO_PROP_ID .

O parâmetro pbData é o endereço de uma variável HCERTSTORE que recebe o identificador de um repositório de certificados na memória. Quando esse identificador não for mais necessário, o chamador deverá fechá-lo usando a função CertCloseStore .

Windows Server 2003 e Windows XP: Não há suporte para esse parâmetro.

PP_VERSION
5 (0x5)
O número de versão do CSP. O byte menos significativo contém o número de versão secundária e o próximo byte mais significativo do número de versão principal. A versão 2.0 é representada como 0x00000200. Para manter a compatibilidade com versões anteriores do Provedor Criptográfico de Base da Microsoft e do Provedor criptográfico avançado da Microsoft, os nomes dos provedores mantêm a designação "v1.0" em versões posteriores.

[out] pbData

Um ponteiro para um buffer para receber os dados. A forma desses dados varia dependendo do valor de dwParam. Quando dwParam é definido como PP_USE_HARDWARE_RNG, pbData deve ser definido como NULL.

Esse parâmetro pode ser NULL para definir o tamanho dessas informações para fins de alocação de memória. Para obter mais informações, consulte Recuperando dados de comprimento desconhecido.

[in, out] pdwDataLen

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

Nota Ao processar os dados retornados no buffer, os aplicativos devem usar o tamanho real dos dados retornados. O tamanho real pode ser um pouco 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 encaixem no buffer.) Na saída, a variável apontada por esse parâmetro é atualizada para refletir o tamanho real dos dados copiados para o buffer.

Se PP_ENUMALGS ou PP_ENUMALGS_EX estiver definido, o parâmetro pdwDataLen funcionará de forma um pouco diferente. Se pbData for NULL ou o valor apontado por pdwDataLen for muito pequeno, o valor retornado nesse parâmetro será o tamanho do maior item na lista de enumeração em vez do tamanho do item que está sendo lido no momento.

Se PP_ENUMCONTAINERS for definido, a primeira chamada para a função retornará o tamanho do contêiner de chave máximo permitido pelo provedor atual. Isso contrasta com outros comportamentos possíveis, como retornar o comprimento do contêiner existente mais longo ou o comprimento do contêiner atual. As chamadas de enumeração subsequentes não alterarão o parâmetro dwLen . Para cada contêiner enumerado, o chamador pode determinar o comprimento da cadeia de caracteres terminada em nulo programaticamente, se desejado. Se um dos valores de enumeração for lido e o parâmetro pbData for NULL, o sinalizador CRYPT_FIRST deverá ser especificado para que as informações de tamanho sejam recuperadas corretamente.

 

[in] dwFlags

Se dwParam for PP_KEYSET_SEC_DESCR, o descritor de segurança no contêiner de chaves em que as chaves são armazenadas será recuperado. Para esse caso, dwFlags é usado para passar os sinalizadores de bits SECURITY_INFORMATION que indicam as informações de segurança solicitadas, conforme definido no SDK da Plataforma. SECURITY_INFORMATION sinalizadores de bits podem ser combinados com uma operação OR bit a bit.

Os valores a seguir são definidos para uso com PP_KEYSET_SEC_DESCR.

Valor Significado
OWNER_SECURITY_INFORMATION
O identificador de proprietário do objeto está sendo referenciado.
GROUP_SECURITY_INFORMATION
O identificador de grupo primário do objeto está sendo referenciado.
DACL_SECURITY_INFORMATION
A ACL discricionária do objeto está sendo referenciada.
SACL_SECURITY_INFORMATION
A ACL do sistema do objeto está sendo referenciada.
 

Os valores a seguir são definidos para uso com PP_ENUMALGS, PP_ENUMALGS_EX e PP_ENUMCONTAINERS.

Valor Significado
CRYPT_FIRST
1 (0x1)
Recupere o primeiro elemento na enumeração . Isso tem o mesmo efeito que redefinir o enumerador.
CRYPT_NEXT
2 (0x2)
Recupere o próximo elemento na enumeração . Quando não houver mais elementos a serem recuperados, essa função falhará e definirá o último erro como ERROR_NO_MORE_ITEMS.
CRYPT_SGC_ENUM
4 (0x4)
Recuperar certificados habilitados para SGC ( criptografia com portão de servidor ). Não há mais suporte para certificados habilitados para SGC.
CRYPT_SGC
Esse sinalizador não é usado.
CRYPT_FASTSGC
Esse sinalizador não é usado.

Retornar valor

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

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

Os códigos de erro precedidos pelo NTE são gerados pelo CSP específico que está sendo usado. Alguns códigos de erro possíveis seguem.

Código de retorno Descrição
ERROR_INVALID_HANDLE
Um dos parâmetros especifica um identificador que não é válido.
ERROR_INVALID_PARAMETER
Um dos parâmetros contém um valor que não é válido. Geralmente, esse é um ponteiro que não é válido.
ERROR_MORE_DATA
Se o buffer especificado pelo parâmetro pbData não for grande o suficiente para manter os dados retornados, a função definirá o código ERROR_MORE_DATA e armazenará o tamanho do buffer necessário, em bytes, na variável apontada por pdwDataLen.
ERROR_NO_MORE_ITEMS
O final da lista de enumeração foi atingido. Nenhum dado válido foi colocado no buffer pbData . Esse código de erro é retornado somente quando dwParam é igual a PP_ENUMALGS ou PP_ENUMCONTAINERS.
NTE_BAD_FLAGS
O parâmetro dwFlags especifica um sinalizador que não é válido.
NTE_BAD_TYPE
O parâmetro dwParam especifica um número de valor desconhecido.
NTE_BAD_UID
O contexto CSP especificado por hProv não é válido.

Comentários

Essa função não deve ser usada em um thread de um programa multithreaded.

Os valores a seguir serão retornados em pbData se dwParam for PP_IMPTYPE.

Valor Significado
CRYPT_IMPL_HARDWARE
0x01
A implementação está no hardware.
CRYPT_IMPL_SOFTWARE
0x02
A implementação está no software.
CRYPT_IMPL_MIXED
0x03
A implementação envolve hardware e software.
CRYPT_IMPL_UNKNOWN
0x04
O tipo de implementação é desconhecido.
CRYPT_IMPL_REMOVABLE
0x08
A implementação está em mídia removível.
 

O parâmetro dwFlags é usado para passar os sinalizadores de bits SECURITY_INFORMATION que indicam as informações de segurança solicitadas. O ponteiro para o descritor de segurança é retornado no parâmetro pbData e o comprimento do descritor de segurança é retornado no parâmetro pdwDataLen . A segurança do contêiner de chaves é tratada com SetFileSecurity e GetFileSecurity.

A classe de um algoritmo enumerado com dwParam definido como PP_ENUMALGS ou PP_ENUMALGS_EX pode ser determinada. Isso pode ser feito para exibir uma lista de algoritmos de criptografia com suporte e ignorar o restante. A macro GET_ALG_CLASS(x) usa um identificador de algoritmo como um argumento e retorna um código que indica a classe geral desse algoritmo. Os possíveis valores retornados incluem:

  • ALG_CLASS_DATA_ENCRYPT
  • ALG_CLASS_HASH
  • ALG_CLASS_KEY_EXCHANGE
  • ALG_CLASS_SIGNATURE

A tabela a seguir lista os algoritmos compatíveis com o Provedor Criptográfico Base da Microsoft, juntamente com a classe de cada algoritmo.

Nome Identificador Classe
"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
 

Os aplicativos não devem usar um algoritmo com um identificador de algoritmo que não seja reconhecido. O uso de um algoritmo criptográfico desconhecido pode produzir resultados imprevisíveis.

Exemplos

O exemplo a seguir mostra como localizar o nome do CSP associado a um identificador do provedor de serviços criptográficos e o nome do contêiner de chave associado ao identificador. Para obter o contexto completo para este exemplo, consulte Exemplo de programa C: usando CryptAcquireContext.

Para obter outro exemplo que usa essa função, consulte Exemplo de Programa C: Enumerando provedores CSP e tipos de provedor.

//-----------------------------------------------------------------
//  Declare and initialize variables.

HCRYPTPROV hCryptProv;
BYTE       pbData[1000];       // 1000 will hold the longest 
                               // key container name.
DWORD cbData;

//-------------------------------------------------------------------
// An HCRYPTPROV must be acquired before using code like that in 
// "Example C Program Using CryptAcquireContext."

//-------------------------------------------------------------------
// Read the name of the default CSP.

cbData = 1000;
if(CryptGetProvParam(
    hCryptProv, 
    PP_NAME, 
    pbData, 
    &cbData, 
    0))
{
    printf("CryptGetProvParam succeeded.\n");
    printf("Provider name: %s\n", pbData);
}
else
{
    printf("Error reading CSP name. \n");
    exit(1);
}
//--------------------------------------------------------------------
// Read the name of the default key container.

cbData = 1000;
if(CryptGetProvParam(
    hCryptProv, 
    PP_CONTAINER, 
    pbData, 
    &cbData, 
    0))
{
    printf("CryptGetProvParam succeeded. \n");
    printf("Key Container name: %s\n", pbData);
}
else
{
    printf("Error reading key container name. \n");
    exit(1);
}

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho wincrypt.h
Biblioteca Advapi32.lib
DLL Advapi32.dll

Confira também

Descritores de segurança absolutos e Self-Relative

Cryptacquirecontext

Cryptcreatehash

Cryptderivekey

Cryptgenkey

Cryptgetkeyparam

Cryptsetprovparam

Funções do Provedor de Serviços