Função CryptGetKeyParam (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 CryptGetKeyParam recupera dados que regem as operações de uma chave. Se o Provedor de Serviços Criptográficos da Microsoft for usado, o material de chave simétrica base não poderá ser obtido por essa ou por qualquer outra função.

Sintaxe

BOOL CryptGetKeyParam(
  [in]      HCRYPTKEY hKey,
  [in]      DWORD     dwParam,
  [out]     BYTE      *pbData,
  [in, out] DWORD     *pdwDataLen,
  [in]      DWORD     dwFlags
);

Parâmetros

[in] hKey

O identificador da chave que está sendo consultada.

[in] dwParam

Especifica o tipo de consulta que está sendo feita.

Para todos os tipos de chave, esse parâmetro pode conter um dos valores a seguir.

Valor	Significado
KP_ALGID	Recupere o algoritmo de chave. O parâmetro pbData é um ponteiro para um valor ALG_ID que recebe o identificador do algoritmo especificado quando a chave foi criada. Quando AT_KEYEXCHANGE ou AT_SIGNATURE é especificado para o parâmetro Argel da função CryptGenKey , os identificadores de algoritmo usados para gerar a chave dependem do provedor usado. Para obter mais informações, consulte ALG_ID.
KP_BLOCKLEN	Se uma chave de sessão for especificada pelo parâmetro hKey , recupere o comprimento do bloco da codificação da chave. O parâmetro pbData é um ponteiro para um valor DWORD que recebe o comprimento do bloco, em bits. Para criptografias de fluxo, esse valor é sempre zero. Se um par de chaves pública/privada for especificado por hKey, recupere a granularidade de criptografia do par de chaves. O parâmetro pbData é um ponteiro para um valor DWORD que recebe a granularidade de criptografia, em bits. Por exemplo, o Provedor Criptográfico base da Microsoft gera pares de chaves RSA de 512 bits, portanto, um valor de 512 é retornado para essas chaves. Se o algoritmo de chave pública não der suporte à criptografia, o valor recuperado será indefinido.
KP_CERTIFICATE	pbData é o endereço de um buffer que recebe o certificado X.509 que foi codificado usando Distinguished Encoding Rules (DER). A chave pública no certificado deve corresponder à assinatura correspondente ou à chave de troca.
KP_GET_USE_COUNT	Este valor não é usado.
KP_KEYLEN	Recupere o comprimento real da chave. O parâmetro pbData é um ponteiro para um valor DWORD que recebe o comprimento da chave, em bits. KP_KEYLEN pode ser usado para obter o comprimento de qualquer tipo de chave. Os CSPs ( provedores de serviços criptográficos ) da Microsoft retornam um comprimento de chave de 64 bits para CALG_DES, 128 bits para CALG_3DES_112 e 192 bits para CALG_3DES. Esses comprimentos são diferentes dos comprimentos retornados quando você está enumerando algoritmos com o valor dwParam da função CryptGetProvParam definida como PP_ENUMALGS. O comprimento retornado por essa chamada é o tamanho real da chave, incluindo os bits de paridade incluídos na chave. Os CSPs da Microsoft que dão suporte ao CALG_CYLINK_MEKALG_ID retornam 64 bits para esse algoritmo. CALG_CYLINK_MEK é uma chave de 40 bits, mas tem paridade e bits de chave zero para tornar o comprimento da chave 64 bits.
KP_SALT	Recupere o valor de sal da chave. O parâmetro pbData é um ponteiro para uma matriz BYTE que recebe o valor de sal na forma little-endian . O tamanho do valor de sal varia dependendo do CSP e do algoritmo que está sendo usado. Os valores de sal não se aplicam a pares de chaves públicas/privadas.
KP_PERMISSIONS	Recupere as permissões de chave. O parâmetro pbData é um ponteiro para um valor DWORD que recebe os sinalizadores de permissão para a chave. Os identificadores de permissão a seguir estão definidos no momento. As permissões de chave podem ser zero ou uma combinação de um ou mais dos valores a seguir. CRYPT_ARCHIVE Permitir a exportação durante o tempo de vida do identificador da chave. Essa permissão só poderá ser definida se ela já estiver definida no campo permissões internas da chave. As tentativas de limpar essa permissão são ignoradas. CRYPT_DECRYPT Permitir descriptografia. CRYPT_ENCRYPT Permitir criptografia. CRYPT_EXPORT Permitir que a chave seja exportada. CRYPT_EXPORT_KEY Permitir que a chave seja usada para exportar chaves. CRYPT_IMPORT_KEY Permitir que a chave seja usada para importar chaves. CRYPT_MAC Permitir que os MACs ( Códigos de Autenticação de Mensagem) sejam usados com chave. CRYPT_READ Permitir que os valores sejam lidos. CRYPT_WRITE Permitir que os valores sejam definidos.

 

Se uma chave DSS ( Digital Signature Standard ) for especificada pelo parâmetro hKey , o valor dwParam também poderá ser definido como um dos valores a seguir.

Valor	Significado
KP_P	Recupere o número principal P do módulo da chave DSS. O parâmetro pbData é um ponteiro para um buffer que recebe o valor no formato little-endian. O parâmetro pdwDataLen contém o tamanho do buffer, em bytes.
KP_Q	Recupere o número principal do módulo Q da chave DSS. O parâmetro pbData é um ponteiro para um buffer que recebe o valor no formato little-endian. O parâmetro pdwDataLen contém o tamanho do buffer, em bytes.
KP_G	Recupere o gerador G da chave DSS. O parâmetro pbData é um ponteiro para um buffer que recebe o valor no formato little-endian. O parâmetro pdwDataLen contém o tamanho do buffer, em bytes.

 

Se uma chave de sessãode criptografia de bloco for especificada pelo parâmetro hKey, o valor dwParam também poderá ser definido como um dos valores a seguir.

Valor	Significado
KP_EFFECTIVE_KEYLEN	Recupere o comprimento efetivo da chave de uma chave RC2. O parâmetro pbData é um ponteiro para um valor DWORD que recebe o comprimento efetivo da chave.
KP_IV	Recupere o vetor de inicialização da chave. O parâmetro pbData é um ponteiro para uma matriz BYTE que recebe o vetor de inicialização. O tamanho dessa matriz é o tamanho do bloco, em bytes. Por exemplo, se o comprimento do bloco for de 64 bits, o vetor de inicialização consistirá em 8 bytes.
KP_PADDING	Recupere o modo de preenchimento. O parâmetro pbData é um ponteiro para um valor DWORD que recebe um identificador numérico que identifica o método de preenchimento usado pela criptografia. Esse pode ser um dos valores a seguir. PKCS5_PADDING Especifica o método de preenchimento PKCS 5 (s 6.2). RANDOM_PADDING O preenchimento usa números aleatórios. Não há suporte para esse método de preenchimento pelos CSPs fornecidos pela Microsoft. ZERO_PADDING O preenchimento usa zeros. Não há suporte para esse método de preenchimento pelos CSPs fornecidos pela Microsoft.
KP_MODE	Recupere o modo de criptografia. O parâmetro pbData é um ponteiro para um valor DWORD que recebe um identificador de modo de criptografia. Para obter mais informações sobre modos de criptografia, consulte Criptografia e descriptografia de dados. Os seguintes identificadores do modo de criptografia estão definidos no momento. CRYPT_MODE_CBC O modo de criptografia é o encadeamento de blocos de criptografia. CRYPT_MODE_CFB O modo de criptografia é cfb (comentários de criptografia ). Atualmente, os CSPs da Microsoft dão suporte apenas a comentários de 8 bits no modo de comentários de criptografia. CRYPT_MODE_ECB O modo de criptografia é um codebook eletrônico. CRYPT_MODE_OFB O modo de criptografia é OFB ( Comentários de Saída ). Atualmente, os CSPs da Microsoft não dão suporte ao Modo de Comentários de Saída. CRYPT_MODE_CTS O modo de criptografia é o modo de roubo de texto cifrado .
KP_MODE_BITS	Recupere o número de bits a serem alimentados novamente. O parâmetro pbData é um ponteiro para um valor DWORD que recebe o número de bits processados por ciclo quando os modos de criptografia OFB ou CFB são usados.

 

Se um algoritmo Diffie-Hellman ou uma chave DSA ( Algoritmo de Assinatura Digital ) for especificado por hKey, o valor dwParam também poderá ser definido como o valor a seguir.

Valor	Significado
KP_VERIFY_PARAMS	Verifica os parâmetros de um algoritmo de Diffie-Hellman ou chave DSA. O parâmetro pbData não é usado e o valor apontado por pdwDataLen recebe zero. Essa função retornará um valor diferente de zero se os parâmetros de chave forem válidos ou zero caso contrário.
KP_KEYVAL	Este valor não é usado. Windows Vista, Windows Server 2003 e Windows XP: Recupere o valor do contrato secreto de uma chave de algoritmo Diffie-Hellman importada do tipo CALG_AGREEDKEY_ANY. O parâmetro pbData é o endereço de um buffer que recebe o valor do contrato secreto, no formato little-endian. Esse buffer deve ter o mesmo comprimento que a chave. O parâmetro dwFlags deve ser definido como 0xF42A19B6. Essa propriedade só pode ser recuperada por um thread em execução na conta do sistema local. Essa propriedade está disponível para uso nos sistemas operacionais listados acima. Ele poderá ser alterado ou ficar indisponível em versões subsequentes.

 

Se um certificado for especificado por hKey, o valor dwParam também poderá ser definido como o valor a seguir.

Valor	Significado
KP_CERTIFICATE	Um buffer que contém o certificado X.509 codificado em DER. O parâmetro pbData não é usado e o valor apontado por pdwDataLen recebe zero. Essa função retornará um valor diferente de zero se os parâmetros de chave forem válidos ou zero caso contrário.

[out] pbData

Um ponteiro para um buffer que recebe os dados. A forma desses dados depende do valor de dwParam.

Se o tamanho desse buffer não for conhecido, o tamanho necessário poderá ser recuperado em tempo de execução passando NULL para esse parâmetro e definindo o valor apontado por pdwDataLen como zero. Essa função colocará o tamanho necessário do buffer, em bytes, no valor apontado por pdwDataLen. Para obter mais informações, consulte Recuperando dados de comprimento desconhecido.

[in, out] pdwDataLen

Um ponteiro para um valor DWORD que, na entrada, contém 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 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 às vezes são especificados grandes o suficiente para garantir que os maiores dados de saída possíveis caibam 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.

 

[in] dwFlags

Esse parâmetro é reservado para uso futuro e deve ser definido como zero.

Retornar valor

Se a função for bem-sucedida, a função retornará diferente de zero.

Se a função falhar, ela retornará zero. Para obter informações de erro estendidas, chame GetLastError.

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

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.
NTE_BAD_FLAGS	O parâmetro dwFlags é diferente de zero.
NTE_BAD_KEY ou NTE_NO_KEY	A chave especificada pelo parâmetro hKey não é válida.
NTE_BAD_TYPE	O parâmetro dwParam especifica um número de valor desconhecido.
NTE_BAD_UID	O contexto CSP especificado quando a chave foi criada não pode ser encontrado.

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

Cryptsetkeyparam

Funções de Geração de Chaves e Exchange