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.

[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.

[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.

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.

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.

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.

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

Confira também

Descritores de segurança absolutos e Self-Relative

Cryptacquirecontext

Cryptcreatehash

Cryptderivekey

Cryptgenkey

Cryptgetkeyparam

Cryptsetprovparam

Funções do Provedor de Serviços