Função BCryptDeriveKey (bcrypt.h)

A função BCryptDeriveKey deriva uma chave de um BCRYPT_SECRET_HANDLE. Isso normalmente é feito como parte de um procedimento de contrato secreto.

Para obter a derivação de chave de um segredo fornecido diretamente pelo chamador, 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 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 . Geralmente, essa é uma má prática, pois pode reduzir significativamente a força de segurança da chave resultante.

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ória ou opcional.

A chamada para o KDF é feita conforme mostrado no pseudocódigo a seguir.

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

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 . Geralmente, essa é uma má prática, pois pode reduzir significativamente a força de segurança da chave resultante.

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ória ou opcional.

A chamada para o KDF é feita conforme mostrado no pseudocódigo a seguir.

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 da camada de transporte (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 parâmetros a seguir, 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. Isso também é conhecido como SP800-56C rev2 KDF de uma etapa.

O KDF usa uma função de hash aprovada como um parâmetro, mas essa API escolhe a função de hash internamente, correspondendo a força de segurança do algoritmo de hash ao algoritmo usado para gerar o identificador secreto. (ou seja, ECDH P-256 usa SHA256, ECDH P-384 usa SHA384)

Os parâmetros identificados pelo parâmetro pParameterList podem ou devem conter os parâmetros a seguir, 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. O uso dessa opção geralmente é uma má prática, mas pode ser necessário se você precisar interoperar com um KDF sem suporte.

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 . Geralmente, essa é uma má prática, pois pode reduzir significativamente a força de segurança da chave resultante.

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.

BCRYPT_KDF_HKDF (L"HKDF")

Use a função HKDF (KDF de extração e expansão baseada em HMAC) do RFC 5869.

No HKDF, uma distinção é feita entre derivar uma chave de:

1. A saída de uma função de contrato secreto, que não é uniformemente aleatória e é considerada material de chave de entrada (IKM). Quase todos os usuários do BCryptDeriveKey terão um identificador secreto desse formulário.
2. Um valor de segredo uniformemente aleatório.

A primeira etapa é "Extrair" uma PRK (chave pseudorandom) do identificador secreto.

Esta etapa é executada chamando BCryptSetProperty em um identificador secreto com BCRYPT_HKDF_HASH_ALGORITHM para definir o algoritmo de hash a ser usado em cálculos HMAC no HKDF. Isso é seguido por uma segunda chamada para BCryptSetProperty com uma delas:

1. Se o identificador secreto representar IKM, use BCRYPT_HKDF_SALT_AND_FINALIZE para fornecer o valor de sal opcional e extrair o PRK do IKM e finalizar o identificador secreto.
2. Caso contrário, use BCRYPT_HKDF_PRK_AND_FINALIZE para transformar diretamente o valor do segredo no PRK do HKDF e finalizar o identificador secreto.

A segunda etapa é "Expandir" o PRK em uma chave derivada de saída.

Esta etapa é executada chamando BCryptDeriveKey em um identificador de segredo finalizado.

Os parâmetros identificados pelo parâmetro pParameterList podem ou devem conter os parâmetros a seguir, 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 = HKDF-Expand(
    hSharedSecret.PRK,
    info,
    cbDerivedKey)

Windows 10: O suporte para HKDF começa.

[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 seguinte valor:

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:

Observações

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 abValue0[] = {0x01};
BYTE abValue1[] = {0x04, 0x05};
BYTE abValue2[] = {0x10, 0x11, 0x12};
BYTE abValue3[] = {0x20, 0x21, 0x22, 0x23};

Parameter[0].type = KDF_SECRET_APPEND
Parameter[0].value = abValue0;
Parameter[0].length = sizeof (abValue0);
Parameter[1].type = KDF_SECRET_PREPEND
Parameter[1].value = abValue1;
Parameter[1].length = sizeof (abValue1);
Parameter[2].type = KDF_SECRET_APPEND
Parameter[2].value = abValue2;
Parameter[2].length = sizeof (abValue2);
Parameter[3].type = KDF_SECRET_PREPEND
Parameter[3].value = abValue3;
Parameter[3].length = sizeof (abValue3);

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

Ao usar um provedor de algoritmo com suporte, bCryptDeriveKey pode ser chamado do modo de usuário ou do modo kernel. Os chamadores do modo kernel podem executar 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

BCryptBufferDesc

BCryptSecretAgreement