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 |