Función NCryptImportKey (ncrypt.h)

  • Artículo

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 del BLOB de clave importada. Debe ser un identificador para 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, consulte 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 de 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 Significado
NCRYPT_SILENT_FLAG Solicita que el proveedor de servicios clave (KSP) no muestre ninguna interfaz de usuario. Si el proveedor debe mostrar la interfaz de usuario para funcionar, se produce un error en la llamada y el KSP debe establecer el código de error NTE_SILENT_CONTEXT como último error.
NCRYPT_REQUIRE_VBS_FLAG Indica que se debe proteger una clave con seguridad basada en virtualización (VBS). De forma predeterminada, esto crea una clave persistente de arranque cruzado almacenada en el disco que persiste en los ciclos de reinicio.

Se producirá un error en la operación si VBS no está disponible. (*Ver comentarios)
NCRYPT_PREFER_VBS_FLAG Indica que se debe proteger una clave con seguridad basada en virtualización (VBS). De forma predeterminada, esto crea una clave persistente de arranque cruzado almacenada en el disco que persiste en los ciclos de reinicio.

La operación generará una clave aislada de software si VBS no está disponible. (*Ver comentarios)
NCRYPT_USE_PER_BOOT_KEY_FLAG Marca adicional que se puede usar junto con NCRYPT_REQUIRE_VBS_FLAG o NCRYPT_PREFER_VBS_FLAG. Indica a la seguridad basada en virtualización (VBS) que proteja la clave de cliente con una clave por arranque almacenada en el disco, pero que no se puede reutilizar en ciclos de arranque. (*Ver comentarios)

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:

Código devuelto Descripción
ERROR_SUCCESS La función se realizó correctamente.
NTE_BAD_FLAGS El parámetro dwFlags contiene un valor que no es válido.
NTE_EXISTS Ya existe una clave con el nombre especificado y no se especificó el NCRYPT_OVERWRITE_KEY_FLAG .
NTE_INVALID_HANDLE El parámetro hProvider no es válido.
NTE_INVALID_PARAMETER Uno o más parámetros no son válidos.
NTE_NO_MEMORY Error de asignación de memoria.
NTE_VBS_UNAVAILABLE VBS no está disponible.
NTE_VBS_CANNOT_DECRYPT_KEY Error en la operación de descifrado de VBS.

Comentarios

Importante

La información relacionada con las marcas de VBS se relaciona con el producto de versión preliminar que puede modificarse sustancialmente antes de su lanzamiento comercial. Microsoft no otorga ninguna garantía, explícita o implícita, con respecto a la información proporcionada aquí.

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

Las siguientes constantes son compatibles con el KSP de software de Microsoft para el parámetro pszBlobType .

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.

Término Descripción
NCRYPT_NO_KEY_VALIDATION No valide la parte pública del par de claves. Esta marca solo se aplica a pares de claves públicas y privadas.
NCRYPT_DO_NOT_FINALIZE_FLAG No finalice la clave. Esta opción es útil cuando necesita agregar o modificar propiedades de la clave después de importarla. Debe finalizar la clave para poder usarla pasando el identificador de clave a la función NCryptFinalizeKey . Esta marca es compatible con las claves privadas PKCS #7 y PKCS #8, pero no para las claves públicas.
NCRYPT_MACHINE_KEY_FLAG La clave se aplica al equipo local. Si esta marca no está presente, la clave se aplica al usuario actual.
NCRYPT_OVERWRITE_KEY_FLAG Si ya existe una clave en el contenedor con el nombre especificado, se sobrescribirá la clave existente. Si no se especifica esta marca y ya existe una clave con el nombre especificado, esta función devolverá NTE_EXISTS.
NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG Guarde también la clave en el almacenamiento heredado. Esto permite usar la clave con CryptoAPI. Esta marca solo se aplica a las claves RSA.

KSP de tarjeta inteligente de Microsoft

El conjunto de formatos y marcas 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 las instrucciones de la sección anterior se aplican 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 condiciones siguientes:

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

Requisito Value
Cliente mínimo compatible Windows Vista [aplicaciones de escritorio | aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2008 [aplicaciones de escritorio | aplicaciones para UWP]
Plataforma de destino Windows
Encabezado ncrypt.h
Library Ncrypt.lib
Archivo DLL Ncrypt.dll

Consulte también

NCryptBuffer

NCryptCreatePersistedKey