Função NCryptKeyDerivation (ncrypt.h)

  • Artigo

A função NCryptKeyDerivation cria uma chave de outra chave usando a função de derivação de chave especificada. A função retorna a chave em uma matriz de bytes.

Sintaxe

SECURITY_STATUS NCryptKeyDerivation(
  [in]  NCRYPT_KEY_HANDLE hKey,
  [in]  NCryptBufferDesc  *pParameterList,
  [out] PUCHAR            pbDerivedKey,
  [in]  DWORD             cbDerivedKey,
  [out] DWORD             *pcbResult,
  [in]  ULONG             dwFlags
);

Parâmetros

[in] hKey

Identificador da chave KDF (função de derivação de chave).

[in] pParameterList

O endereço de uma estrutura NCryptBufferDesc que contém os parâmetros KDF. Os parâmetros podem ser específicos para um KDF ou genérico. A tabela a seguir mostra os parâmetros obrigatórios e opcionais para KDFs específicos implementados pelo provedor de armazenamento de chaves de software da Microsoft.

KDF Parâmetro Obrigatório
SP800-108 HMAC no modo de contador KDF_LABEL sim
KDF_CONTEXT sim
KDF_HASH_ALGORITHM sim
SP800-56A KDF_ALGORITHMID sim
KDF_PARTYUINFO sim
KDF_PARTYVINFO sim
KDF_HASH_ALGORITHM sim
KDF_SUPPPUBINFO não
KDF_SUPPPRIVINFO não
PBKDF2 KDF_HASH_ALGORITHM sim
KDF_SALT sim
KDF_ITERATION_COUNT não
CAPI_KDF KDF_HASH_ALGORITHM sim
 

O seguinte parâmetro genérico pode ser usado:

  • KDF_GENERIC_PARAMETER
Parâmetros genéricos são mapeados para parâmetros específicos do KDF da seguinte maneira:

SP800-108 HMAC no modo de contador:

  • KDF_GENERIC_PARAMETER = KDF_LABEL||0x00||KDF_CONTEXT

SP800-56A

  • KDF_GENERIC_PARAMETER = KDF_ALGORITHMID || KDF_PARTYUINFO || KDF_PARTYVINFO {|| KDF_SUPPPUBINFO } {|| KDF_SUPPPRIVINFO }

PBKDF2

  • KDF_GENERIC_PARAMETER = KDF_SALT
  • KDF_ITERATION_COUNT – o padrão é 10000

CAPI_KDF

  • KDF_GENERIC_PARAMETER = Não usado

[out] pbDerivedKey

Endereço de um buffer que recebe a chave. O parâmetro cbDerivedKey contém o tamanho, em bytes, do buffer de chave.

[in] cbDerivedKey

Tamanho, em bytes, do buffer apontado pelo parâmetro pbDerivedKey .

[out] pcbResult

Ponteiro para um DWORD que recebe o número de bytes copiados para o buffer apontado pelo parâmetro pbDerivedKey .

[in] dwFlags

Sinalizadores que modificam o comportamento da função. O valor a seguir pode ser usado com o provedor de armazenamento de chaves de software da Microsoft.

Valor Significado
BCRYPT_CAPI_AES_FLAG
 Especifica que o algoritmo de destino é AES e que, portanto, a chave deve ser expandida duas vezes. Esse sinalizador só é válido com o algoritmo CAPI_KDF.
NCRYPT_SILENT_FLAG
 Solicita que o KSP (provedor de serviços de chave) não exiba nenhuma interface do usuário. Se o provedor precisar exibir a interface do usuário para operar, a chamada falhará e o KSP deverá definir o código de erro NTE_SILENT_CONTEXT como o último erro.

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
 Os identificadores hProvider ou hKey não são válidos.
NTE_INVALID_PARAMETER
 Os parâmetros pwszDerivedKeyAlg e pParameterList não podem ser NULL.
NTE_NO_MEMORY
 Não havia memória suficiente para criar a chave.
NTE_NOT_SUPPORTED
 Essa função não tem suporte do provedor de armazenamento de chaves.

Comentários

Você pode usar os seguintes identificadores de algoritmo na função NCryptCreatePersistedKey antes de chamar NCryptKeyDerivation:

  • BCRYPT_CAPI_KDF_ALGORITHM
  • BCRYPT_SP800108_CTR_HMAC_ALGORITHM
  • BCRYPT_SP80056A_CONCAT_ALGORITHM
  • BCRYPT_PBKDF2_ALGORITHM

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 8 [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows Server 2012 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho ncrypt.h
Biblioteca Ncrypt.lib
DLL Ncrypt.dll

Confira também

BCryptKeyDerivation

NCryptDeriveKey