Compartilhar via

Função NCryptDeriveKey (ncrypt.h)

  • Artigo

A função NCryptDeriveKey deriva uma chave de um valor de contrato secreto. Essa função destina-se a ser usada como parte de um procedimento de contrato secreto usando chaves de contrato secreto persistentes. Para derivar material de chave usando um segredo persistente, use a função NCryptKeyDerivation .

Sintaxe

SECURITY_STATUS NCryptDeriveKey(
  [in]            NCRYPT_SECRET_HANDLE hSharedSecret,
  [in]            LPCWSTR              pwszKDF,
  [in, optional]  NCryptBufferDesc     *pParameterList,
  [out, optional] PBYTE                pbDerivedKey,
  [in]            DWORD                cbDerivedKey,
  [out]           DWORD                *pcbResult,
  [in]            ULONG                dwFlags
);

Parâmetros

[in] hSharedSecret

O identificador do contrato secreto do qual criar a chave. Esse identificador é obtido da função NCryptSecretAgreement .

[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 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 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 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 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 protocolo TLS. 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ó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
 

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.

[in, optional] pParameterList

O endereço de uma estrutura NCryptBufferDesc 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 DWORD apontado pelo parâmetro pcbResult .

[in] cbDerivedKey

O tamanho, em bytes, do buffer pbDerivedKey .

[out] pcbResult

Um ponteiro para um DWORD 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 DWORD 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 só é usado pela função de derivação de chave BCRYPT_KDF_HMAC .

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
ERROR_SUCCESS
 A função foi bem-sucedida.
NTE_INVALID_HANDLE
 O parâmetro hSharedSecret não é válido.
NTE_INVALID_PARAMETER
 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

Um serviço não deve chamar essa função de sua função StartService. Se um serviço chamar essa função de sua função StartService, um deadlock poderá ocorrer e o serviço poderá parar de responder.

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 ncrypt.h
Biblioteca Ncrypt.lib
DLL Ncrypt.dll

Confira também

NCryptBufferDesc