Função CryptSetKeyParam (wincrypt.h)

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 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 em uma única sessão.

O do 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 um ALG_IDapropriado. Isso é usado ao trocar chaves de sessão com o Microsoft Base Digital Signature Standard (DSS), 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 DER (Distinguished Encoding Rules). A chave pública no certificado deve corresponder à assinatura ou à chave de troca correspondente.
KP_PERMISSIONS	pbData aponta para um valor de 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 fazer parte da chave de sessão. O tamanho do valor do 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 dificulta os ataques de dicionário. 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 doblob de chave de 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 formulário de little-endian.
KP_P	pbData aponta para o módulo P principal de um BLOB de chave DSS. Os dados estão na forma de uma estrutura de 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 formulário de 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 formulário de little-endian.
KP_X	Depois que os valores P, Q e G tiverem sido definidos, uma chamada que especifica o valor KP_X para dwParam e NULL para o parâmetro pbData pode ser feita na função CryptSetKeyParam . Isso faz com que os valores X e Y sejam gerados.

 

Se um algoritmo Diffie-Hellman ou chave DSA ( Algoritmo de Assinatura Digital) for especificado por hKey, o valor de 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 de Diffie-Hellman importada. O parâmetro pbData é o endereço de uma estrutura de 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 dessa 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ã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	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 de DWORD com o valor de comprimento da 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 mais alta TLS (Transport Layer Security) 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 será composto por 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 padrão de criptografia de dados (DES) de . 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 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 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 de 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 de DWORD que indica o número de bits processados por ciclo quando o modo de criptografia de Comentários de Saída (OFB) ou CFB (Cipher Feedback) é 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.

Valor de retorno

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	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 de hKey foi criada não foi 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.

Observações

Se os parâmetros KP_Q, KP_P ou KP_X forem definidos em uma chave PREGEN Diffie-Hellman ou DSS, os comprimentos de chave deverão ser compatíveis com o comprimento da chave definido 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ódigos que usam essa função, consulte Exemplo de Programa C: Definindo e obtendo parâmetros de chave de sessão .

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]
da Plataforma de Destino	Windows
cabeçalho	wincrypt.h
biblioteca	Advapi32.lib
de DLL	Advapi32.dll

Consulte também

ALG_ID

CryptGenKey

CryptGetKeyParam

CryptImport Key

geração de chaves e funções do Exchange