Función NCryptCreatePersistedKey (ncrypt.h)

La función NCryptCreatePersistedKey crea una nueva clave y la almacena en el proveedor de almacenamiento de claves especificado. Después de crear una clave mediante esta función, puede usar la función NCryptSetProperty para establecer sus propiedades; sin embargo, la clave no se puede usar hasta que se llame a la función NCryptFinalizeKey .

Sintaxis

SECURITY_STATUS NCryptCreatePersistedKey(
  [in]           NCRYPT_PROV_HANDLE hProvider,
  [out]          NCRYPT_KEY_HANDLE  *phKey,
  [in]           LPCWSTR            pszAlgId,
  [in, optional] LPCWSTR            pszKeyName,
  [in]           DWORD              dwLegacyKeySpec,
  [in]           DWORD              dwFlags
);

Parámetros

[in] hProvider

Identificador del proveedor de almacenamiento de claves en el que se va a crear la clave. Este identificador se obtiene mediante la función NCryptOpenStorageProvider .

[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 . Para eliminar el archivo de clave en el disco, pase el identificador a la función NCryptDeleteKey . Esto también liberará el identificador. Por lo tanto, las aplicaciones pueden pasar el identificador a NCryptFreeObject o NCryptDeleteKey, pero no a ambos.

[in] pszAlgId

Puntero a una cadena Unicode terminada en null que contiene el identificador del algoritmo criptográfico para crear la clave. Puede ser uno de los identificadores de algoritmo CNG estándar o el identificador de otro algoritmo registrado.

[in, optional] pszKeyName

Puntero a una cadena Unicode terminada en null que contiene el nombre de la clave. Si este parámetro es NULL, esta función creará una clave efímera que no se conserva.

[in] dwLegacyKeySpec

Identificador heredado que especifica el tipo de clave. Puede ser uno de los siguientes valores:

Valor	Significado
AT_KEYEXCHANGE	La clave es una clave de intercambio de claves.
AT_SIGNATURE	La clave es una clave de firma.
0	La clave no es ninguno de los tipos anteriores.

[in] dwFlags

Conjunto de marcas que modifican el comportamiento de esta función. Puede ser cero o una combinación de uno o varios de los valores siguientes:

Valor	Significado
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_REQUIRE_VBS_FLAG	Indica que una clave debe protegerse con seguridad basada en virtualización (VBS). 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). La operación generará una clave aislada de software si VBS no está disponible. (*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.

Comentarios

Importante

La información relacionada con las marcas 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í.

Si va a crear un par de claves RSA, también puede tener la clave almacenada en el almacenamiento heredado para que se pueda usar con CryptoAPI pasando la marca NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG a la función NCryptFinalizeKey cuando se finalice la clave.

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.

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

NCryptDeleteKey

NCryptFinalizeKey