Función BCryptOpenAlgorithmProvider (bcrypt.h)

Artículo
07/16/2024

La función BCryptOpenAlgorithmProvider carga e inicializa un proveedor de CNG.

Sintaxis

NTSTATUS BCryptOpenAlgorithmProvider(
  [out] BCRYPT_ALG_HANDLE *phAlgorithm,
  [in]  LPCWSTR           pszAlgId,
  [in]  LPCWSTR           pszImplementation,
  [in]  ULONG             dwFlags
);

Parámetros

[out] phAlgorithm

Puntero a una variable BCRYPT_ALG_HANDLE que recibe el identificador del proveedor CNG. Cuando haya terminado de usar este identificador, suéltelo pasando a la función BCryptCloseAlgorithmProvider.

[in] pszAlgId

Puntero a una cadena Unicode terminada en null que identifica el algoritmo criptográfico solicitado. Puede ser uno de los identificadores de algoritmo de CNG estándar o el identificador de otro algoritmo registrado.

[in] pszImplementation

Puntero a una cadena Unicode terminada en null que identifica el proveedor específico que se va a cargar. Este es el alias registrado del proveedor primitivo criptográfico. Este parámetro es opcional y se puede NULL si no es necesario. Si este parámetro es NULL, se cargará el proveedor predeterminado para el algoritmo especificado.

Nota Si el valor del parámetro pszImplementation es NULL, CNG intenta abrir cada proveedor registrado, en orden de prioridad, para el algoritmo especificado por el parámetro pszAlgId y devuelve el identificador del primer proveedor que se abre correctamente. Durante la vigencia del identificador, las API criptográficas BCrypt*** usarán el proveedor que se abrió correctamente.

Windows Server 2008 y Windows Vista: CNG intenta revertir al proveedor de CNG de Microsoft.

A continuación se muestran los nombres de proveedor predefinidos.

Valor	Significado
MS_PRIMITIVE_PROVIDER "Proveedor primitivo de Microsoft"	Identifica el proveedor básico de Microsoft CNG.
MS_PLATFORM_CRYPTO_PROVIDER L"Proveedor criptográfico de plataforma de Microsoft"	Identifica el proveedor de almacenamiento de claves de TPM proporcionado por Microsoft.

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

Valor	Significado
BCRYPT_ALG_HANDLE_HMAC_FLAG	El proveedor realizará el algoritmo Hash-Based código de autenticación de mensajes (HMAC) con el algoritmo hash especificado. Esta marca solo la usan los proveedores de algoritmos hash.
BCRYPT_PROV_DISPATCH	Carga el proveedor en el grupo de memoria no paginado. Si esta marca no está presente, el proveedor se carga en el grupo de memoria paginada. Cuando se especifica esta marca, el identificador devuelto no debe cerrarse antes de que se libere todos los objetos dependientes. Nota Esta marca solo se admite en modo kernel y permite que las operaciones posteriores del proveedor se procesen en el nivel de distribución. Si el proveedor no admite la llamada en el nivel de distribución, devolverá un error cuando se abra con esta marca. Windows Server 2008 y Windows Vista: Esta marca solo es compatible con los proveedores de algoritmos de Microsoft y solo para los algoritmos hash de y clave simétrica algoritmos criptográficos.
BCRYPT_HASH_REUSABLE_FLAG	Crea un objeto hash reutilizable. El objeto se puede usar para una nueva operación hash inmediatamente después de llamar a BCryptFinishHash. Para obtener más información, vea Creación de un hash con CNG. Windows Server 2008 R2, Windows 7, Windows Server 2008 y Windows Vista: Esta marca no se admite.

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
STATUS_SUCCESS	La función se realizó correctamente.
STATUS_NOT_FOUND	No se encontró ningún proveedor para el identificador de algoritmo especificado.
STATUS_INVALID_PARAMETER	Uno o varios parámetros no son válidos.
STATUS_NO_MEMORY	Error de asignación de memoria.

Observaciones

Debido al número y tipo de operaciones necesarias para buscar, cargar e inicializar un proveedor de algoritmos, la función de BCryptOpenAlgorithmProvider es una función con un tiempo relativamente intensivo. Por este motivo, se recomienda almacenar en caché los identificadores de cualquier proveedor de algoritmos que usará más de una vez, en lugar de abrir y cerrar los proveedores de algoritmos sobre y más.

se puede llamar a BCryptOpenAlgorithmProvider desde el modo de usuario o el modo kernel. Los llamadores de modo kernel deben ejecutarse en PASSIVE_LEVELIRQL.

Para llamar a esta función en modo kernel, use Cng.lib, que forma parte del Kit de desarrollo de controladores (DDK). Windows Server 2008 y Windows Vista: Para llamar a esta función en modo kernel, use Ksecdd.lib.

A partir de Windows 10, CNG ya no sigue todas las actualizaciones a la configuración de criptografía. Algunos cambios, como agregar un nuevo proveedor predeterminado o cambiar el orden de preferencia de los proveedores de algoritmos, pueden requerir un reinicio. Por este motivo, debe reiniciar antes de llamar a BCryptOpenAlgorithmProvider con cualquier proveedor recién configurado.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows Vista [aplicaciones de escritorio \| Aplicaciones para UWP]
servidor mínimo admitido	Windows Server 2008 [aplicaciones de escritorio \| Aplicaciones para UWP]
de la plataforma de destino de	Windows
encabezado de	bcrypt.h
biblioteca de	Bcrypt.lib
DLL de	Bcrypt.dll

Consulte también

BCryptCloseAlgorithmProvider

Compartir a través de