Função CryptGetProvParam (wincrypt.h)
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 |
|---|---|
|
Retorna o PIN (número de identificação pessoal) do administrador no parâmetro pbData como um LPSTR. |
|
Essa constante não é usada. |
|
Essa constante não é usada. |
|
Retorna a cadeia de certificados associada ao identificador hProv . A cadeia de certificados retornada é X509_ASN_ENCODING codificada. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
Essa constante não é usada. |
|
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 . |
|
Essa constante não é usada. |
|
Um valor DWORD que indica como o CSP é implementado. Para obter uma tabela de valores possíveis, consulte Comentários. |
|
Essa consulta não é usada. |
|
Especifica que o PIN de troca de chaves está contido em pbData. O PIN é representado como uma cadeia de caracteres ASCII terminada em nulo. |
|
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. |
|
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 . |
|
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. |
|
Retorna um valor DWORD de CRYPT_SEC_DESCR. |
|
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. |
|
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. |
|
Um valor DWORD que indica o tipo de provedor do CSP. |
|
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. |
|
O tamanho, em bits, da chave de sessão. |
|
Usado com criptografia restrita do servidor. |
|
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. |
|
Especifica que o PIN de assinatura de chave está contido em pbData. O PIN é representado como uma cadeia de caracteres ASCII terminada em nulo. |
|
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. |
|
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. |
|
O tamanho da chave simétrica. |
|
Essa consulta não é usada. |
|
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. |
|
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. |
|
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. |
|
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.
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.
Os valores a seguir são definidos para uso com PP_ENUMALGS, PP_ENUMALGS_EX e PP_ENUMCONTAINERS.
| Valor | Significado |
|---|---|
|
Recupere o primeiro elemento na enumeração . Isso tem o mesmo efeito que redefinir o enumerador. |
|
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. |
|
Recuperar certificados habilitados para SGC ( criptografia com portão de servidor ). Não há mais suporte para certificados habilitados para SGC. |
|
Esse sinalizador não é usado. |
|
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 |
|---|---|
|
Um dos parâmetros especifica um identificador que não é válido. |
|
Um dos parâmetros contém um valor que não é válido. Geralmente, esse é um ponteiro que não é válido. |
|
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. |
|
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. |
|
O parâmetro dwFlags especifica um sinalizador que não é válido. |
|
O parâmetro dwParam especifica um número de valor desconhecido. |
|
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 |