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 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 |