Função NCryptDeriveKey (ncrypt.h)
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.
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. |
|
O 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
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
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