Função NCryptImportKey (ncrypt.h)

A função NCryptImportKey importa uma chave CNG (API de Criptografia: Próxima Geração) de um BLOB de memória.

Sintaxe

SECURITY_STATUS NCryptImportKey(
  [in]           NCRYPT_PROV_HANDLE hProvider,
  [in, optional] NCRYPT_KEY_HANDLE  hImportKey,
  [in]           LPCWSTR            pszBlobType,
  [in, optional] NCryptBufferDesc   *pParameterList,
  [out]          NCRYPT_KEY_HANDLE  *phKey,
  [in]           PBYTE              pbData,
  [in]           DWORD              cbData,
  [in]           DWORD              dwFlags
);

Parâmetros

[in] hProvider

O identificador do provedor de armazenamento de chaves.

[in, optional] hImportKey

O identificador da chave criptográfica com a qual os dados de chave no BLOB de chave importada foram criptografados. Esse deve ser um identificador para a mesma chave que foi passada no parâmetro hExportKey da função NCryptExportKey . Se esse parâmetro for NULL, presume-se que o BLOB de chave não seja criptografado.

[in] pszBlobType

Uma cadeia de caracteres Unicode terminada em nulo que contém um identificador que especifica o formato do BLOB de chave. Esses formatos são específicos para um provedor de armazenamento de chaves específico. Para os formatos BLOB com suporte por provedores da Microsoft, consulte Comentários.

[in, optional] pParameterList

O endereço de uma estrutura NCryptBufferDesc que aponta para uma matriz de buffers que contêm informações de parâmetro para a chave.

[out] phKey

O endereço de uma variável NCRYPT_KEY_HANDLE que recebe o identificador da chave. Quando terminar de usar esse identificador, solte-o passando-o para a função NCryptFreeObject .

[in] pbData

O endereço de um buffer que contém o BLOB de chave a ser importado. O parâmetro cbData contém o tamanho desse buffer.

[in] cbData

O tamanho, em bytes, do buffer pbData .

[in] dwFlags

Sinalizadores que modificam o comportamento da função. Isso pode ser zero ou uma combinação de um ou mais dos valores a seguir. O conjunto de sinalizadores válidos é específico para cada provedor de armazenamento de chaves.

Valor Significado
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.
NCRYPT_REQUIRE_VBS_FLAG Indica que uma chave deve ser protegida com a VBS (segurança baseada em virtualização). Por padrão, isso cria uma chave persistente de inicialização cruzada armazenada no disco que persiste entre ciclos de reinicialização.

A operação falhará se o VBS não estiver disponível. (*Consulte Comentários)
NCRYPT_PREFER_VBS_FLAG Indica que uma chave deve ser protegida com a VBS (segurança baseada em virtualização). Por padrão, isso cria uma chave persistente de inicialização cruzada armazenada no disco que persiste entre ciclos de reinicialização.

A operação gerará uma chave isolada de software se o VBS não estiver disponível. (*Consulte Comentários)
NCRYPT_USE_PER_BOOT_KEY_FLAG Um sinalizador adicional que pode ser usado junto com NCRYPT_REQUIRE_VBS_FLAG ou NCRYPT_PREFER_VBS_FLAG. Instrui a VBS (segurança baseada em virtualização) a proteger a chave do cliente com uma chave por inicialização armazenada em disco, mas que não pode ser reutilizada em ciclos de inicialização. (*Consulte Comentários)

Retornar valor

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, o seguinte:

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 a NCRYPT_OVERWRITE_KEY_FLAG não foi especificada.
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 O VBS não está disponível.
NTE_VBS_CANNOT_DECRYPT_KEY Falha na operação de descriptografia do VBS.

Comentários

Importante

As informações sobre sinalizadores de VBS estão relacionadas 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.

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.

As seções a seguir descrevem comportamentos específicos dos provedores de armazenamento de chaves da Microsoft:

  • Microsoft Software KSP
  • Microsoft Smart Card KSP

Microsoft Software KSP

As constantes a seguir têm suporte do KSP de software da Microsoft para o parâmetro pszBlobType .

Se um nome de chave não for fornecido, o KSP do Microsoft Software tratará a chave como efêmera e não a armazenará persistentemente. Para o tipo NCRYPT_OPAQUETRANSPORT_BLOB , o nome da chave é armazenado no BLOB quando ele é exportado. Para outros formatos BLOB, o nome pode ser fornecido em um parâmetro de buffer NCRYPTBUFFER_PKCS_KEY_NAME dentro do parâmetro pParameterList .

No Windows Server 2008 e no Windows Vista, somente as chaves importadas como BLOBs de envelope PKCS nº 7 (NCRYPT_PKCS7_ENVELOPE_BLOB) ou BLOBs de chave privada PKCS #8 (NCRYPT_PKCS8_PRIVATE_KEY_BLOB) podem ser persistidas usando o método acima. Para manter as chaves importadas por meio de outros tipos de BLOB nessas plataformas, use o método documentado em Importação e Exportação de Chaves.

Os sinalizadores a seguir têm suporte neste KSP.

Termo Descrição
NCRYPT_NO_KEY_VALIDATION Não valide a parte pública do par de chaves. Esse sinalizador só se aplica a pares de chaves públicas/privadas.
NCRYPT_DO_NOT_FINALIZE_FLAG Não finalize a chave. Essa opção é útil quando você precisa adicionar ou modificar propriedades da chave depois de importá-la. Você deve finalizar a chave antes que ela possa ser usada passando o identificador de chave para a função NCryptFinalizeKey . Esse sinalizador tem suporte para as chaves privadas PKCS nº 7 e PKCS #8, mas não para chaves públicas.
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 uma chave já existir 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_WRITE_KEY_TO_LEGACY_STORE_FLAG Salve também a chave no armazenamento herdado. Isso permite que a chave seja usada com a CryptoAPI. Esse sinalizador só se aplica a chaves RSA.

KSP do Cartão Inteligente da Microsoft

O conjunto de principais formatos de BLOB e sinalizadores com suporte por esse KSP é idêntico ao conjunto compatível com o KSP de Software da Microsoft.

No Windows Server 2008 e no Windows Vista, o KSP do Cartão Inteligente da Microsoft importa todas as chaves para o Microsoft Software KSP. Portanto, as chaves não podem ser mantidas em um cartão inteligente usando essa API, e as diretrizes na seção acima se aplicam ao tentar persistir chaves no KSP do Software Microsoft.

No Windows Server 2008 R2 e no Windows 7, o Provedor de Armazenamento de Chaves de Cartão Inteligente da Microsoft pode importar uma chave privada para um cartão inteligente, desde que as seguintes condições sejam atendidas:

  • O nome do contêiner de chave no cartão é válido.
  • A importação de chaves privadas é compatível com o cartão inteligente.
  • As duas chaves do Registro a seguir são definidas como um DWORD de 0x1:
    • HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base Smart Card Crypto Provider\AllowPrivateExchangeKeyImport
    • HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base Smart Card Crypto Provider\AllowPrivateSignatureKeyImport

Se o nome do contêiner de chave for NULL, o KSP do Cartão Inteligente da Microsoft tratará a chave como efêmera e a importará para o KSP do Microsoft Software.

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

NCryptBuffer

NCryptCreatePersistedKey