Função NCryptCreatePersistedKey (ncrypt.h)

  • Artigo

A função NCryptCreatePersistedKey cria uma nova chave e a armazena no provedor de armazenamento de chaves especificado. Depois de criar uma chave usando essa função, você pode usar a função NCryptSetProperty para definir suas propriedades; no entanto, a chave não pode ser usada até que a função NCryptFinalizeKey seja chamada.

Sintaxe

SECURITY_STATUS NCryptCreatePersistedKey(
  [in]           NCRYPT_PROV_HANDLE hProvider,
  [out]          NCRYPT_KEY_HANDLE  *phKey,
  [in]           LPCWSTR            pszAlgId,
  [in, optional] LPCWSTR            pszKeyName,
  [in]           DWORD              dwLegacyKeySpec,
  [in]           DWORD              dwFlags
);

Parâmetros

[in] hProvider

O identificador do provedor de armazenamento de chaves no qual criar a chave. Esse identificador é obtido usando a função NCryptOpenStorageProvider .

[out] phKey

O endereço de uma variável NCRYPT_KEY_HANDLE que recebe o identificador da chave. Quando terminar de usar esse identificador, libere-o passando-o para a função NCryptFreeObject . Para excluir o arquivo de chave no disco, passe o identificador para a função NCryptDeleteKey . Isso também liberará o identificador. Portanto, os aplicativos podem passar o identificador para NCryptFreeObject ou NCryptDeleteKey, mas não ambos.

[in] pszAlgId

Um ponteiro para uma cadeia de caracteres Unicode terminada em nulo que contém o identificador do algoritmo criptográfico para criar a chave. Esse pode ser um dos Identificadores de Algoritmo CNG padrão ou o identificador de outro algoritmo registrado.

[in, optional] pszKeyName

Um ponteiro para uma cadeia de caracteres Unicode terminada em nulo que contém o nome da chave. Se esse parâmetro for NULL, essa função criará uma chave efêmera que não é persistente.

[in] dwLegacyKeySpec

Um identificador herdado que especifica o tipo de chave. Esse valor pode ser um dos seguintes:

Valor Significado
AT_KEYEXCHANGE A chave é uma chave de troca de chaves.
AT_SIGNATURE A chave é uma chave de assinatura.
0 A chave não é nenhum dos tipos acima.

[in] dwFlags

Um conjunto de sinalizadores que modificam o comportamento dessa função. Isso pode ser zero ou uma combinação de um ou mais dos seguintes valores:

Valor Significado
NCRYPT_MACHINE_KEY_FLAG A chave se aplica ao computador local. Se esse sinalizador não estiver presente, a chave se aplicará ao usuário atual.
NCRYPT_OVERWRITE_KEY_FLAG Se já existir uma chave no contêiner com o nome especificado, a chave existente será substituída. Se esse sinalizador não for especificado e uma chave com o nome especificado já existir, essa função retornará NTE_EXISTS.
NCRYPT_REQUIRE_VBS_FLAG Indica que uma chave deve ser protegida com a VBS (segurança baseada em virtualização).

A operação falhará se a VBS não estiver disponível. (*Ver comentários)
NCRYPT_PREFER_VBS_FLAG Indica que uma chave deve ser protegida com a VBS (segurança baseada em virtualização).

A operação gerará uma chave isolada de software se a VBS não estiver disponível. (*Ver comentários)

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:

Código de retorno Descrição
ERROR_SUCCESS A função foi bem-sucedida.
NTE_BAD_FLAGS O parâmetro dwFlags contém um valor que não é válido.
NTE_EXISTS Já existe uma chave com o nome especificado e o NCRYPT_OVERWRITE_KEY_FLAG não foi especificado.
NTE_INVALID_HANDLE O parâmetro hProvider não é válido.
NTE_INVALID_PARAMETER Um ou mais dos parâmetros não são válidos.
NTE_NO_MEMORY Ocorreu uma falha de alocação de memória.
NTE_VBS_UNAVAILABLE A VBS não está disponível.

Comentários

Importante

As informações sobre sinalizadores VBS referem-se ao produto de pré-lançamento que pode ser substancialmente modificado antes de ser lançado comercialmente. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.

Se você estiver criando um par de chaves RSA, também poderá ter a chave armazenada no armazenamento herdado para que ela possa ser usada com a CryptoAPI passando o sinalizador NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG para a função NCryptFinalizeKey quando a chave for finalizada.

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 de hardware adicionais para chaves VBS

Embora você possa ter o sistema operacional apropriado instalado em seu computador, os requisitos de hardware adicionais a seguir devem ser atendidos para usar a VBS para gerar e proteger chaves.

  • VBS habilitado (consulte Segurança baseada em virtualização (VBS))
  • TPM habilitado
    • Para ambientes bare-metal, o TPM 2.0 é necessário.
    • Para ambientes de VM, há suporte para vTPM (TPM Virtual).
  • O BIOS deve ser atualizado para UEFI com o perfil SecureBoot

Para obter mais informações sobre os requisitos de hardware:

  • A VBS tem vários requisitos de hardware para execução, incluindo Hyper-V (hipervisor do Windows), arquitetura de 64 bits e suporte a IOMMU. A lista completa de requisitos de hardware do VBS pode ser encontrada aqui.
  • Os requisitos para um dispositivo altamente seguro podem ser encontrados aqui.

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

NCryptDeleteKey

NCryptFinalizeKey