Función BCryptOpenAlgorithmProvider (bcrypt.h)

  • Artículo

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 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 puede ser 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 la plataforma 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 de código de autenticación de mensajes basado en hash (HMAC) con el algoritmo hash especificado. Los proveedores de algoritmos hash solo usan esta marca.
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 paginado. 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 en el proveedor se procesen en el nivel de distribución. Si el proveedor no admite la llamada en el nivel de envío, 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 algoritmos hash y algoritmoscriptográficos de clave simétrica.
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, consulte 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 posibles códigos de retorno 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 más parámetros no son válidos.
STATUS_NO_MEMORY
 Error de asignación de memoria.

Comentarios

Debido al número y el tipo de operaciones necesarias para buscar, cargar e inicializar un proveedor de algoritmos, la función 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 autores de llamadas en 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 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 bcrypt.h
Library Bcrypt.lib
Archivo DLL Bcrypt.dll

Consulte también

BCryptCloseAlgorithmProvider