Função BCryptDeriveKey (bcrypt.h)
A função BCryptDeriveKey deriva uma chave de um valor de contrato secreto.
Para obter a derivação de chave de um determinado segredo, consulte BCryptKeyDerivation.
Sintaxe
NTSTATUS BCryptDeriveKey(
[in] BCRYPT_SECRET_HANDLE hSharedSecret,
[in] LPCWSTR pwszKDF,
[in, optional] BCryptBufferDesc *pParameterList,
[out, optional] PUCHAR pbDerivedKey,
[in] ULONG cbDerivedKey,
[out] ULONG *pcbResult,
[in] ULONG dwFlags
);
Parâmetros
[in] hSharedSecret
O identificador do contrato secreto do qual criar a chave. Esse identificador é obtido da função BCryptSecretAgreement .
[in] pwszKDF
Um ponteiro para uma cadeia de caracteres Unicode terminada em nulo que identifica a função de derivação de chave (KDF) a ser usada para derivar a chave. Essa pode ser uma das cadeias de caracteres a seguir.
BCRYPT_KDF_HASH (L"HASH")
Use a função de derivação de chave de hash.
Se o parâmetro cbDerivedKey for menor que o tamanho da chave derivada, essa função copiará apenas o número especificado de bytes para o buffer pbDerivedKey . Se o parâmetro cbDerivedKey for maior que o tamanho da chave derivada, essa função copiará a chave para o buffer pbDerivedKey e definirá a variável apontada pelo pcbResult para o número real de bytes copiados.
Os parâmetros identificados pelo parâmetro pParameterList podem ou devem conter os parâmetros a seguir, conforme indicado pela coluna Obrigatório ou opcional.
| Parâmetro | Descrição | Obrigatório ou opcional |
|---|---|---|
| KDF_HASH_ALGORITHM |
Uma cadeia de caracteres Unicode terminada em nulo que identifica o algoritmo de hash a ser usado. Esse pode ser um dos identificadores de algoritmo hash padrão de Identificadores de Algoritmo CNG ou o identificador de outro algoritmo de hash registrado.
Se esse parâmetro não for especificado, o algoritmo de hash SHA1 será usado. |
Opcional |
| KDF_SECRET_PREPEND | Um valor a ser adicionado ao início da entrada da mensagem à função de hash. Para obter mais informações, consulte Comentários. | Opcional |
| KDF_SECRET_APPEND | Um valor a ser adicionado ao final da entrada da mensagem à função de hash. Para obter mais informações, consulte Comentários. | Opcional |
A chamada para o KDF é feita conforme mostrado no pseudocódigo a seguir.
KDF-Prepend = KDF_SECRET_PREPEND[0] +
KDF_SECRET_PREPEND[1] +
... +
KDF_SECRET_PREPEND[n]
KDF-Append = KDF_SECRET_APPEND[0] +
KDF_SECRET_APPEND[1] +
... +
KDF_SECRET_APPEND[n]
KDF-Output = Hash(
KDF-Prepend +
hSharedSecret +
KDF-Append)
BCRYPT_KDF_HMAC (L"HMAC")
Use a função de derivação de chave HMAC ( Código de Autenticação de Mensagem Baseado em Hash ).
Se o parâmetro cbDerivedKey for menor que o tamanho da chave derivada, essa função copiará apenas o número especificado de bytes para o buffer pbDerivedKey . Se o parâmetro cbDerivedKey for maior que o tamanho da chave derivada, essa função copiará a chave para o buffer pbDerivedKey e definirá a variável apontada pelo pcbResult para o número real de bytes copiados.
Os parâmetros identificados pelo parâmetro pParameterList podem ou devem conter os parâmetros a seguir, conforme indicado pela coluna Obrigatório ou opcional.
| Parâmetro | Descrição | Obrigatório ou opcional |
|---|---|---|
| KDF_HASH_ALGORITHM |
Uma cadeia de caracteres Unicode terminada em nulo que identifica o algoritmo de hash a ser usado. Esse pode ser um dos identificadores de algoritmo hash padrão de Identificadores de Algoritmo CNG ou o identificador de outro algoritmo de hash registrado.
Se esse parâmetro não for especificado, o algoritmo de hash SHA1 será usado. |
Opcional |
| KDF_HMAC_KEY | A chave a ser usada para a PRF ( função pseudo-aleatória ). | Opcional |
| KDF_SECRET_PREPEND | Um valor a ser adicionado ao início da entrada da mensagem à função de hash. Para obter mais informações, consulte Comentários. | Opcional |
| KDF_SECRET_APPEND | Um valor a ser adicionado ao final da entrada da mensagem à função de hash. Para obter mais informações, consulte Comentários. | Opcional |
A chamada para o KDF é feita conforme mostrado no pseudocódigo a seguir.
KDF-Prepend = KDF_SECRET_PREPEND[0] +
KDF_SECRET_PREPEND[1] +
... +
KDF_SECRET_PREPEND[n]
KDF-Append = KDF_SECRET_APPEND[0] +
KDF_SECRET_APPEND[1] +
... +
KDF_SECRET_APPEND[n]
KDF-Output = HMAC-Hash(
KDF_HMAC_KEY,
KDF-Prepend +
hSharedSecret +
KDF-Append)
BCRYPT_KDF_TLS_PRF (L"TLS_PRF")
Use a função de derivação de chave PRF (função pseudo-aleatória) de segurança de camada de transporte (PRF). O tamanho da chave derivada é sempre 48 bytes, portanto, o parâmetro cbDerivedKey deve ser 48.
Os parâmetros identificados pelo parâmetro pParameterList podem ou devem conter os parâmetros a seguir, conforme indicado pela coluna Obrigatório ou opcional.
| Parâmetro | Descrição | Obrigatório ou opcional |
|---|---|---|
| KDF_TLS_PRF_LABEL | Uma cadeia de caracteres ANSI que contém o rótulo PRF. | Obrigatório |
| KDF_TLS_PRF_SEED | A semente prf. A semente deve ter 64 bytes de comprimento. | Obrigatório |
| KDF_TLS_PRF_PROTOCOL |
Um valor DWORD que especifica a versão do protocolo TLS cujo algoritmo PRF deve ser usado.
Os valores válidos são:
Windows Server 2008 e Windows Vista: não há suporte para TLS1_1_PROTOCOL_VERSION, TLS1_2_PROTOCOL_VERSION e DTLS1_0_PROTOCOL_VERSION. Windows Server 2008 R2, Windows 7, Windows Server 2008 e Windows Vista: não há suporte para DTLS1_0_PROTOCOL_VERSION. |
Opcional |
| KDF_HASH_ALGORITHM | A ID do algoritmo CNG do hash a ser usado com o HMAC no PRF, para a versão do protocolo TLS 1.2. As opções válidas são SHA-256 e SHA-384. Se não for especificado, SHA-256 será usado. | Opcional |
A chamada para o KDF é feita conforme mostrado no pseudocódigo a seguir.
KDF-Output = PRF(
hSharedSecret,
KDF_TLS_PRF_LABEL,
KDF_TLS_PRF_SEED)
BCRYPT_KDF_SP80056A_CONCAT (L"SP800_56A_CONCAT")
Use a função de derivação de chave SP800-56A.
Os parâmetros identificados pelo parâmetro pParameterList podem ou devem conter os parâmetros a seguir, conforme indicado pela coluna Obrigatório ou opcional. Todos os valores de parâmetro são tratados como matrizes de bytes opacas.
| Parâmetro | Descrição | Obrigatório ou opcional |
|---|---|---|
| KDF_ALGORITHMID | Especifica o subcampo AlgorithmID do campo OtherInfo na função de derivação de chave SP800-56A. Indica a finalidade pretendida da chave derivada. | Obrigatório |
| KDF_PARTYUINFO | Especifica o subcampo PartyUInfo do campo OtherInfo na função de derivação de chave SP800-56A. O campo contém informações públicas contribuidas pelo iniciador. | Obrigatório |
| KDF_PARTYVINFO | Especifica o subcampo PartyVInfo do campo OtherInfo na função de derivação de chave SP800-56A. O campo contém informações públicas contribuidas pelo respondente. | Obrigatório |
| KDF_SUPPPUBINFO | Especifica o subcampo SuppPubInfo do campo OtherInfo na função de derivação de chave SP800-56A. O campo contém informações públicas conhecidas pelo iniciador e pelo respondente. | Opcional |
| KDF_SUPPPRIVINFO | Especifica o subcampo SuppPrivInfo do campo OtherInfo na função de derivação de chave SP800-56A. Ele contém informações privadas conhecidas pelo iniciador e pelo respondente, como um segredo compartilhado. | Opcional |
A chamada para o KDF é feita conforme mostrado no pseudocódigo a seguir.
KDF-Output = SP_800-56A_KDF(
hSharedSecret,
KDF_ALGORITHMID,
KDF_PARTYUINFO,
KDF_PARTYVINFO,
KDF_SUPPPUBINFO,
KDF_SUPPPRIVINFO)
Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Não há suporte para esse valor.
BCRYPT_KDF_RAW_SECRET (L"TRUNCATE")
Retorna a representação little-endian do segredo bruto sem nenhuma modificação.
Se o parâmetro cbDerivedKey for menor que o tamanho da chave derivada, essa função copiará apenas o número especificado de bytes para o buffer pbDerivedKey . Se o parâmetro cbDerivedKey for maior que o tamanho da chave derivada, essa função copiará a chave para o buffer pbDerivedKey e definirá a variável apontada pelo pcbResult para o número real de bytes copiados.
Windows 8, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: não há suporte para esse valor.
[in, optional] pParameterList
O endereço de uma estrutura BCryptBufferDesc que contém os parâmetros KDF. Esse parâmetro é opcional e pode ser NULL se não for necessário.
[out, optional] pbDerivedKey
O endereço de um buffer que recebe a chave. O parâmetro cbDerivedKey contém o tamanho desse buffer. Se esse parâmetro for NULL, essa função colocará o tamanho necessário, em bytes, no ULONG apontado pelo parâmetro pcbResult .
[in] cbDerivedKey
O tamanho, em bytes, do buffer pbDerivedKey .
[out] pcbResult
Um ponteiro para um ULONG que recebe o número de bytes que foram copiados para o buffer pbDerivedKey . Se o parâmetro pbDerivedKey for NULL, essa função colocará o tamanho necessário, em bytes, no ULONG apontado por esse parâmetro.
[in] dwFlags
Um conjunto de sinalizadores que modificam o comportamento dessa função. Isso pode ser zero ou o valor a seguir.
Retornar valor
Retorna um código status que indica o êxito ou a falha da função.
Os códigos de retorno possíveis incluem, mas não se limitam a, o seguinte.
| Código de retorno | Descrição |
|---|---|
|
A função foi bem-sucedida. |
|
Ocorreu um erro interno. |
|
O identificador no parâmetro hSharedSecret não é válido. |
|
Um ou mais dos parâmetros não são válidos. |
Comentários
A estrutura BCryptBufferDesc no parâmetro pParameterList pode conter mais de um dos parâmetros KDF_SECRET_PREPEND e KDF_SECRET_APPEND . Se mais de um desses parâmetros for especificado, os valores de parâmetro serão concatenados na ordem em que estão contidos na matriz antes que o KDF seja chamado. Por exemplo, suponha que os valores de parâmetro a seguir sejam especificados.
BYTE pbValue0[1] = {0x01};
BYTE pbValue1[2] = {0x04, 0x05};
BYTE pbValue2[3] = {0x10, 0x11, 0x12};
BYTE pbValue3[4] = {0x20, 0x21, 0x22, 0x23};
Parameter[0].type = KDF_SECRET_APPEND
Parameter[0].value = pbValue0;
Parameter[0].length = sizeof (pbValue0);
Parameter[1].type = KDF_SECRET_PREPEND
Parameter[1].value = pbValue1;
Parameter[1].length = sizeof (pbValue1);
Parameter[2].type = KDF_SECRET_APPEND
Parameter[2].value = pbValue2;
Parameter[2].length = sizeof (pbValue2);
Parameter[3].type = KDF_SECRET_PREPEND
Parameter[3].value = pbValue3;
Parameter[3].length = sizeof (pbValue3);
Se os valores de parâmetro acima forem especificados, os valores concatenados para o KDF real serão os seguintes.
Type: KDF_SECRET_PREPEND
Value: {0x04, 0x05, 0x20, 0x21, 0x22, 0x23}, length 6
Type: KDF_SECRET_APPEND
Value: {0x01, 0x10, 0x11, 0x12}, length 4
Se o parâmetro pwszKDF for definido como BCRYPT_KDF_RAW_SECRET, o segredo retornado (ao contrário dos outros valores pwszKDF ) será codificado no formato little-endian. É importante tomar nota disso ao usar o segredo bruto em qualquer outra função CNG, pois a maioria delas recebe entradas codificadas em big-endian.
Dependendo de quais modos de processador um provedor dá suporte, BCryptDeriveKey pode ser chamado do modo de usuário ou do modo kernel. Os chamadores do modo kernel podem ser executados em PASSIVE_LEVELIRQL ou DISPATCH_LEVEL IRQL. Se o nível IRQL atual for DISPATCH_LEVEL, o identificador fornecido no parâmetro hSharedSecret deverá estar localizado na memória não paga (ou bloqueada) e deve ser derivado de um identificador de algoritmo retornado por um provedor que foi aberto usando o sinalizador BCRYPT_PROV_DISPATCH .
Para chamar essa função no modo kernel, use Cng.lib, que faz parte do DDK (Driver Development Kit). Windows Server 2008 e Windows Vista: Para chamar essa função no modo kernel, use Ksecdd.lib.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows Vista [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2008 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | bcrypt.h |
| Biblioteca | Bcrypt.lib |
| DLL | Bcrypt.dll |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de