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.

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:

Comentários

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.

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

Confira também

NCryptBuffer

NCryptCreatePersistedKey