Função BCryptDeriveKey (bcrypt.h)

Artigo
07/16/2024

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 de 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 seguintes parâmetros, conforme indicado pela coluna Obrigatória 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 de 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 de código de autenticação de mensagem Hash-Based (HMAC).

Os parâmetros identificados pelo parâmetro pParameterList podem ou devem conter os seguintes parâmetros, conforme indicado pela coluna Obrigatória 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 de 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 de função pseudo-aleatória (PRF).	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 o de segurança da camada de transporte (TLS) função pseudo-aleatória de função (PRF). O tamanho da chave derivada é sempre de 48 bytes, portanto, o parâmetro cbDerivedKey deve ser 48.

Os parâmetros identificados pelo parâmetro pParameterList podem ou devem conter os seguintes parâmetros, conforme indicado pela coluna Obrigatória 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.	Necessário
KDF_TLS_PRF_SEED	A semente prf. A semente deve ter 64 bytes de comprimento.	Necessá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: SSL2_PROTOCOL_VERSION (0x0002) SSL3_PROTOCOL_VERSION (0x0300) TLS1_PROTOCOL_VERSION (0x0301) TLS1_0_PROTOCOL_VERSION (0x0301) TLS1_1_PROTOCOL_VERSION (0x0302) TLS1_2_PROTOCOL_VERSION (0x0303) DTLS1_0_PROTOCOL_VERSION (0xfeff) 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 seguintes parâmetros, conforme indicado pela coluna Obrigatória 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.	Necessá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.	Necessá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.	Necessá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.

Windows 8, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Esse valor não tem suporte.

[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 de 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.

Valor	Significado
KDF_USE_SECRET_AS_HMAC_KEY_FLAG	O valor do contrato secreto também servirá como a chave HMAC. Se esse sinalizador for especificado, o parâmetro KDF_HMAC_KEY não deverá ser incluído no conjunto de parâmetros no parâmetro pParameterList . Esse sinalizador é usado apenas pela função de derivação de chave BCRYPT_KDF_HMAC.

Valor de retorno

Retorna um código de 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
STATUS_SUCCESS	A função foi bem-sucedida.
STATUS_INTERNAL_ERROR	Ocorreu um erro interno.
STATUS_INVALID_HANDLE	O identificador no parâmetro hSharedSecret não é válido.
STATUS_INVALID_PARAMETER	Um ou mais parâmetros não são válidos.

Observações

A estrutura de 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 estiver definido como BCRYPT_KDF_RAW_SECRET, o segredo retornado (diferentemente dos outros valores de pwszKDF de ) será codificado no formato little-endian. É importante observar isso ao usar o segredo bruto em qualquer outra função CNG, pois a maioria delas usa 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
de cliente com suporte mínimo	Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows Server 2008 [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	bcrypt.h
biblioteca	Bcrypt.lib
de DLL	Bcrypt.dll

Consulte também

BCryptSecretAgreement

Compartilhar via

Função BCryptDeriveKey (bcrypt.h)

Sintaxe

Parâmetros

BCRYPT_KDF_HASH (L"HASH")

BCRYPT_KDF_HMAC (L"HMAC")

BCRYPT_KDF_TLS_PRF (L"TLS_PRF")

BCRYPT_KDF_SP80056A_CONCAT (L"SP800_56A_CONCAT")

BCRYPT_KDF_RAW_SECRET (L"TRUNCATE")

Valor de retorno

Observações

Requisitos

Consulte também

Comentários

Recursos adicionais