Función NCryptImportKey (ncrypt.h)

La función NCryptImportKey importa una clave cryptography API: Next Generation (CNG) desde un BLOB de memoria.

Sintaxis

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

Identificador del proveedor de almacenamiento de claves.

[in, optional] hImportKey

Identificador de la clave criptográfica con la que se cifraron los datos de clave dentro de la clave importada BLOB . Debe ser un identificador de la misma clave que se pasó en el parámetro hExportKey de la función NCryptExportKey . Si este parámetro es NULL, se supone que el BLOB de clave no se cifra.

[in] pszBlobType

Cadena Unicode terminada en NULL que contiene un identificador que especifica el formato del BLOB de clave. Estos formatos son específicos de un proveedor de almacenamiento de claves determinado. Para conocer los formatos BLOB admitidos por los proveedores de Microsoft, vea Comentarios.

[in, optional] pParameterList

Dirección de una estructura NCryptBufferDesc que apunta a una matriz de búferes que contienen información de parámetros para la clave.

[out] phKey

Dirección de una variable NCRYPT_KEY_HANDLE que recibe el identificador de la clave. Cuando haya terminado de usar este identificador, suéltelo pasando a la función NCryptFreeObject .

[in] pbData

Dirección de un búfer que contiene la clave BLOB que se va a importar. El parámetro cbData contiene el tamaño de este búfer.

[in] cbData

Tamaño, en bytes, del búfer pbData .

[in] dwFlags

Marcas que modifican el comportamiento de la función. Puede ser cero o una combinación de uno o varios de los valores siguientes. El conjunto de marcas válidas es específico de cada proveedor de almacenamiento de claves.

Valor devuelto

Devuelve un código de estado que indica el éxito o error de la función.

Entre los códigos de retorno posibles se incluyen, entre otros, los siguientes:

Observaciones

Un servicio no debe llamar a esta función desde su función StartService. Si un servicio llama a esta función desde su función StartService , se puede producir un interbloqueo y el servicio puede dejar de responder.

En las secciones siguientes se describen los comportamientos específicos de los proveedores de almacenamiento de claves de Microsoft:

• Microsoft Software KSP
• KSP de tarjeta inteligente de Microsoft

Microsoft Software KSP

Consulte NCryptImportKey para obtener más información sobre la mayoría de los parámetros pszBlobType admitidos por el KSP de software de Microsoft.

Si no se proporciona un nombre de clave, el KSP de Software de Microsoft trata la clave como efímera y no la almacena de forma persistente. Para el tipo de NCRYPT_OPAQUETRANSPORT_BLOB , el nombre de clave se almacena dentro del BLOB cuando se exporta. Para otros formatos BLOB, el nombre se puede proporcionar en un parámetro de búfer de NCRYPTBUFFER_PKCS_KEY_NAME dentro del parámetro pParameterList .

En Windows Server 2008 y Windows Vista, solo se pueden conservar las claves importadas como blobs de sobre PKCS #7 (NCRYPT_PKCS7_ENVELOPE_BLOB) o blobs de clave privada PKCS #8 (NCRYPT_PKCS8_PRIVATE_KEY_BLOB) mediante el método anterior. Para conservar las claves importadas a través de otros tipos BLOB en estas plataformas, use el método documentado en Importación y exportación de claves.

Este KSP admite las siguientes marcas.

KSP de tarjeta inteligente de Microsoft

El conjunto de formatos y marcas de BLOB clave admitidos por este KSP es idéntico al conjunto admitido por el KSP de Software de Microsoft.

En Windows Server 2008 y Windows Vista, el KSP de tarjeta inteligente de Microsoft importa todas las claves en el KSP de software de Microsoft. Por lo tanto, las claves no se pueden conservar en una tarjeta inteligente mediante esta API y la guía de la sección anterior se aplica al intentar conservar las claves dentro del KSP de software de Microsoft.

En Windows Server 2008 R2 y Windows 7, el proveedor de almacenamiento de claves de tarjeta inteligente de Microsoft puede importar una clave privada a una tarjeta inteligente, siempre que se cumplan las siguientes condiciones:

• El nombre del contenedor de claves de la tarjeta es válido.
• La tarjeta inteligente admite la importación de claves privadas.
• Las dos claves del Registro siguientes se establecen en un 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

Si el nombre del contenedor de claves es NULL, el KSP de la tarjeta inteligente de Microsoft trata la clave como efímera e importa en el KSP de software de Microsoft.

Requisitos de hardware adicionales para las claves VBS

Aunque es posible que tenga el sistema operativo adecuado instalado en la máquina, se deben cumplir los siguientes requisitos de hardware adicionales para usar VBS para generar y proteger claves.

• VBS habilitado (consulte Seguridad basada en virtualización (VBS))
• TPM habilitado
  • Para entornos sin sistema operativo, se requiere TPM 2.0.
  • En el caso de los entornos de máquina virtual, se admite vTPM (TPM virtual).
• El BIOS debe actualizarse a UEFI con el perfil SecureBoot

Para obtener más información sobre los requisitos de hardware:

• VBS tiene varios requisitos de hardware para ejecutarse, como Hyper-V (hipervisor de Windows), arquitectura de 64 bits y compatibilidad con IOMMU. Puede encontrar la lista completa de los requisitos de hardware de VBS aquí.
• Los requisitos para un dispositivo altamente seguro se pueden encontrar aquí.

Requisitos

Consulte también

NCryptBuffer

NCryptCreatePersistedKey