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 CryptGetKeyParam recupera dados que regem as operações de uma chave. Se o 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.
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 de DWORD que recebe o comprimento do bloco, em bits. Para de 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 de 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 oferecer suporte a 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 DER (Distinguished Encoding Rules). A chave pública no certificado deve corresponder à assinatura ou à chave de troca correspondente.
KP_GET_USE_COUNT
Esse valor não é usado.
KP_KEYLEN
Recupere o comprimento real da chave. O parâmetro pbData é um ponteiro para um valor de DWORD que recebe o comprimento da chave, em bits.
KP_KEYLEN pode ser usado para obter o comprimento de qualquer tipo de chave. Os provedores de serviços criptográficos (CSPs) da Microsoft retornam um comprimento de chave de 64 bits para CALG_DES, 128 bits para CALG_3DES_112e 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 fazer 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 em forma de little-endian. O tamanho do valor do 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 de 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 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 de 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 MACs (Códigos de Autenticação de Mensagens) 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 do módulo P 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ãofor 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 de 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 será composto por 8 bytes.
KP_PADDING
Recupere o modo de preenchimento. O parâmetro pbData é um ponteiro para um valor de DWORD que recebe um identificador numérico que identifica o método de de preenchimento usado pelode 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. Esse método de preenchimento não tem suporte dos CSPs fornecidos pela Microsoft.
ZERO_PADDING
O preenchimento usa zeros. Esse método de preenchimento não tem suporte dos CSPs fornecidos pela Microsoft.
KP_MODE
Recuperar o modo de criptografia . O parâmetro pbData é um ponteiro para um valor de DWORD que recebe um identificador de modo de criptografia. Para obter mais informações sobre modos de criptografia, consulte de Criptografia e Descriptografia de Dados.
Os identificadores do modo de criptografia a seguir estão definidos no momento.
CRYPT_MODE_CBC
O modo de codificação é de encadeamento de blocos de criptografia.
CRYPT_MODE_CFB
O modo de codificação é CFB ( de comentários de codificação). 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 é de codebook eletrônico.
CRYPT_MODE_OFB
O modo de codificação é OFB ( de Comentários de Saída). Atualmente, os CSPs da Microsoft não dão suporte ao Modo de Comentários de Saída.
Recupere o número de bits a serem alimentados novamente. O parâmetro pbData é um ponteiro para um valor de 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 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
Esse valor não é usado.
Windows Vista, Windows Server 2003 e Windows XP: Recuperar o valor do contrato secreto de um algoritmo de Diffie-Hellman importado chave 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 pode estar alterado ou 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 dede 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.
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 às vezes são especificados grandes o suficiente para garantir que os maiores dados de saída possíveis se ajustem 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.
Valor de retorno
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. Isso geralmente é 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 não é 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 de CSP que foi especificado quando a chave foi criada não pode ser encontrado.
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]