Função CryptSetKeyParam (wincrypt.h)

Artigo
08/27/2023

Importante Essa API foi preterida. O software novo e existente deve começar a usar APIs de Próxima Geração de Criptografia. A Microsoft pode remover essa API em versões futuras.

A função CryptSetKeyParam personaliza vários aspectos das operações de uma chave de sessão. Os valores definidos por essa função não são persistidos na memória e só podem ser usados com em uma única sessão.

O Provedor Criptográfico Base da Microsoft não permite definir valores para troca de chaves ou chaves de assinatura; no entanto, provedores personalizados podem definir valores que podem ser definidos para suas chaves.

Sintaxe

BOOL CryptSetKeyParam(
  [in] HCRYPTKEY  hKey,
  [in] DWORD      dwParam,
  [in] const BYTE *pbData,
  [in] DWORD      dwFlags
);

Parâmetros

[in] hKey

Um identificador para a chave para a qual os valores devem ser definidos.

[in] dwParam

As tabelas a seguir contêm valores predefinidos que podem ser usados.

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

Valor	Significado
KP_ALGID	pbData aponta para uma ALG_ID apropriada. Isso é usado ao trocar chaves de sessão com o DSS (Microsoft Base Digital Signature Standard), Diffie-Hellman Provedor Criptográfico ou CSPs compatíveis. Depois que uma chave é acordada com a função CryptImportKey , a chave de sessão é habilitada para uso definindo seu tipo de algoritmo.
KP_CERTIFICATE	pbData é o endereço de um buffer que contém o certificado X.509 que foi codificado usando Distinguished Encoding Rules (DER). A chave pública no certificado deve corresponder à assinatura ou à chave de troca correspondente.
KP_PERMISSIONS	pbData aponta para um valor DWORD que especifica zero ou mais sinalizadores de permissão. Para obter uma descrição desses sinalizadores, consulte CryptGetKeyParam.
KP_SALT	pbData aponta para uma matriz BYTE que especifica um novo valor de sal a ser feito parte da chave de sessão. O tamanho do valor de sal varia dependendo do CSP que está sendo usado. Antes de definir esse valor, determine o tamanho do valor de sal chamando a função CryptGetKeyParam . Os valores de sal são usados para tornar as chaves de sessão mais exclusivas, o que torna os ataques de dicionário mais difíceis. O valor de sal é zero por padrão para o Provedor Criptográfico Base da Microsoft.
KP_SALT_EX	pbData aponta para uma estrutura CRYPT_INTEGER_BLOB que contém o sal. Para obter mais informações, consulte Especificando um valor de sal.

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_G	pbData aponta para o gerador G do BLOB da chave DSS. Os dados estão na forma de uma estrutura CRYPT_INTEGER_BLOB , em que o membro pbData é o valor e o membro cbData é o comprimento do valor. O valor é esperado sem informações de cabeçalho e em formato little-endian .
KP_P	pbData aponta para o módulo principal P de um BLOB de chave DSS. Os dados estão na forma de uma estrutura CRYPT_INTEGER_BLOB . O membro pbData é o valor e o membro cbData é o comprimento do valor. O valor é esperado sem informações de cabeçalho e em formato little-endian .
KP_Q	pbData aponta para o Q principal de um BLOB de chave DSS. Os dados estão na forma de uma estrutura CRYPT_INTEGER_BLOB em que o membro pbData é o valor e o membro cbData é o comprimento do valor. O valor é esperado sem informações de cabeçalho e em formato little-endian .
KP_X	Depois que os valores P, Q e G tiverem sido definidos, uma chamada que especifica o valor de KP_X para dwParam e NULL para o parâmetro pbData pode ser feita para a função CryptSetKeyParam . Isso faz com que os valores X e Y sejam gerados.

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 um dos valores a seguir.

Valor	Significado
KP_CMS_DH_KEY_INFO	Define as informações de uma chave Diffie-Hellman importada. O parâmetro pbData é o endereço de uma estrutura CMS_DH_KEY_INFO que contém as informações de chave a serem definidas.
KP_PUB_PARAMS	Define os parâmetros públicos (P, Q, G e assim por diante) de uma chave DSS ou Diffie-Hellman. O identificador de chave para essa chave deve estar no estado PREGEN, gerado com o sinalizador CRYPT_PREGEN. O parâmetro pbData deve ser um ponteiro para uma estrutura DATA_BLOB em que os dados nessa estrutura são um blob DHPUBKEY_VER3 ou DSSPUBKEY_VER3. A função copia os parâmetros públicos dessa estrutura CRYPT_INTEGER_BLOB para o identificador de chave. Depois que essa chamada for feita, o valor do parâmetro KP_X deverá ser usado com CryptSetKeyParam para criar a chave privada real. O parâmetro KP_PUB_PARAMS é usado como uma chamada em vez de várias chamadas com os valores de parâmetro KP_P, KP_Q e KP_G.

Valor

Significado

KP_CMS_DH_KEY_INFO

Define as informações de uma chave Diffie-Hellman importada. O parâmetro pbData é o endereço de uma estrutura CMS_DH_KEY_INFO que contém as informações de chave a serem definidas.

KP_PUB_PARAMS

Define os parâmetros públicos (P, Q, G e assim por diante) de uma chave DSS ou Diffie-Hellman. O identificador de chave para essa chave deve estar no estado PREGEN, gerado com o sinalizador CRYPT_PREGEN. O parâmetro pbData deve ser um ponteiro para uma estrutura DATA_BLOB em que os dados nessa estrutura são um blob DHPUBKEY_VER3 ou DSSPUBKEY_VER3. A função copia os parâmetros públicos dessa estrutura CRYPT_INTEGER_BLOB para o identificador de chave. Depois que essa chamada for feita, o valor do parâmetro KP_X deverá ser usado com CryptSetKeyParam para criar a chave privada real. O parâmetro KP_PUB_PARAMS é usado como uma chamada em vez de várias chamadas com os valores de parâmetro KP_P, KP_Q e KP_G.

Se uma chave de sessão de 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	Esse tipo de valor só pode ser usado com chaves RC2 e foi adicionado devido à implementação da função CryptSetKeyParam no Provedor criptográfico avançado da Microsoft antes do Windows 2000. Na implementação anterior, as chaves RC2 no Provedor Avançado tinham 128 bits de força, mas o comprimento de chave efetivo usado para expandir as chaves para a tabela de chaves era de apenas 40 bits. Isso reduziu a força do algoritmo para 40 bits. Para manter a compatibilidade com versões anteriores, a implementação anterior permanecerá como está. No entanto, o comprimento efetivo da chave pode ser definido como maior que 40 bits usando KP_EFFECTIVE_KEYLEN na chamada CryptSetKeyParam . O comprimento efetivo da chave é passado no parâmetro pbData como um ponteiro para um valor DWORD com o valor de comprimento de chave efetivo. O comprimento mínimo da chave efetiva no Provedor Criptográfico Base da Microsoft é um e o máximo é 40. No Provedor Criptográfico Avançado da Microsoft, o mínimo é um e o máximo é 1.024. O comprimento da chave deve ser definido antes de criptografar ou descriptografar com a chave.
KP_HIGHEST_VERSION	Define a versão de TLS ( Transport Layer Security ) mais alta permitida. Essa propriedade só se aplica a chaves SSL e TLS. O parâmetro pbData é o endereço de uma variável DWORD que contém o número de versão TLS mais alto com suporte.
KP_IV	pbData aponta para uma matriz BYTE que especifica o vetor de inicialização. Essa matriz deve conter elementos BlockLength/8. Por exemplo, se o comprimento do bloco for de 64 bits, o vetor de inicialização consistirá em 8 bytes. O vetor de inicialização é definido como zero por padrão para o Provedor Criptográfico Base da Microsoft.
KP_KEYVAL	Defina o valor da chave para uma chave DES ( Data Encryption Standard ). O parâmetro pbData é o endereço de um buffer que contém a chave. Esse buffer deve ter o mesmo comprimento que a chave. Essa propriedade só se aplica a chaves DES.
KP_PADDING	Defina 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 um número aleatório. 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	pbData aponta para um valor DWORD que especifica o modo de criptografia a ser usado. Para obter uma lista dos modos de criptografia definidos, consulte CryptGetKeyParam. O modo de criptografia é definido como CRYPT_MODE_CBC por padrão para o Provedor Criptográfico base da Microsoft.
KP_MODE_BITS	pbData aponta para um valor DWORD que indica o número de bits processados por ciclo quando o modo de criptografia comentários de saída (OFB) ou cfb (comentários de criptografia ) é usado. O número de bits processados por ciclo é definido como 8 por padrão para o Provedor Criptográfico base da Microsoft.

Se uma chave RSA for especificada no parâmetro hKey , o valor do parâmetro dwParam poderá ser o valor a seguir.

Valor	Significado
KP_OAEP_PARAMS	Defina os parâmetros OAEP (Preenchimento de Criptografia Assimétrica Ideal) (PKCS nº 1 versão 2) para a chave. O parâmetro pbData é o endereço de uma estrutura CRYPT_DATA_BLOB que contém o rótulo OAEP. Essa propriedade só se aplica a chaves RSA.

Observe que os seguintes valores não são usados:

KP_ADMIN_PIN
KP_CMS_KEY_INFO
KP_INFO
KP_KEYEXCHANGE_PIN
KP_PRECOMP_MD5
KP_PRECOMP_SHA
KP_PREHASH
KP_PUB_EX_LEN
KP_PUB_EX_VAL
KP_RA
KP_RB
KP_ROUNDS
KP_RP
KP_SIGNATURE_PIN
KP_Y

[in] pbData

Um ponteiro para um buffer inicializado com o valor a ser definido antes de chamar CryptSetKeyParam. A forma desses dados varia dependendo do valor de dwParam.

[in] dwFlags

Usado somente quando dwParam é KP_ALGID. O parâmetro dwFlags é usado para passar valores de sinalizador para a chave habilitada. O parâmetro dwFlags pode conter valores como o tamanho da chave e os outros valores de sinalizador permitidos ao gerar o mesmo tipo de chave com CryptGenKey. Para obter informações sobre valores de sinalizador permitidos, consulte CryptGenKey.

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 por "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_BUSY	No momento, o contexto CSP está sendo usado por outro processo.
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.
NTE_BAD_FLAGS	O parâmetro dwFlags não é zero ou o buffer pbData contém um valor que não é válido.
NTE_BAD_TYPE	O parâmetro dwParam especifica um parâmetro desconhecido.
NTE_BAD_UID	O contexto CSP especificado quando a chave hKey foi criada não pode ser encontrado.
NTE_FAIL	A função falhou de alguma forma inesperada.
NTE_FIXEDPARAMETER	Alguns CSPs têm valores P, Q e G codificados. Se esse for o caso, usar KP_P, KP_Q e KP_G para o valor de dwParam causará esse erro.

Comentários

Se os parâmetros KP_Q, KP_P ou KP_X forem definidos em uma tecla PREGEN Diffie-Hellman ou DSS, os comprimentos de chave deverão ser compatíveis com o conjunto de comprimento de chave usando os 16 bits superiores do parâmetro dwFlags quando a chave foi criada usando CryptGenKey. Se nenhum comprimento de chave foi definido em CryptGenKey, o comprimento da chave padrão foi usado. Isso criará um erro se um comprimento de chave não padrão for usado para definir P, Q ou X.

Exemplos

Para obter um exemplo que usa essa função, consulte Exemplo de programa C: duplicando uma chave de sessão. Para obter mais código que usa essa função, consulte Exemplo de Programa C: Definindo e obtendo parâmetros de chave de sessão .

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