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

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).

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.

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.

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.

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

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

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

Consulte também

BCryptSecretAgreement