BCryptOpenAlgorithmProvider, fonction (bcrypt.h)

Article
07/16/2024

La fonction BCryptOpenAlgorithmProvider charge et initialise un fournisseur CNG.

Syntaxe

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

Paramètres

[out] phAlgorithm

Pointeur vers une variable BCRYPT_ALG_HANDLE qui reçoit le handle du fournisseur CNG. Lorsque vous avez terminé d’utiliser ce handle, relâchez-le en le transmettant à la fonction BCryptCloseAlgorithmProvider.

[in] pszAlgId

Pointeur vers une chaîne Unicode terminée par null qui identifie l’algorithme de chiffrement demandé. Il peut s’agir de l’un des identificateurs d’algorithme CNG standard ou de l’identificateur d’un autre algorithme inscrit.

[in] pszImplementation

Pointeur vers une chaîne Unicode terminée par null qui identifie le fournisseur spécifique à charger. Il s’agit de l’alias inscrit du fournisseur de primitives de chiffrement. Ce paramètre est facultatif et peut être NULL s’il n’est pas nécessaire. Si ce paramètre est NULL, le fournisseur par défaut de l’algorithme spécifié est chargé.

Remarque Si la valeur du paramètre pszImplementation est NULL, CNG tente d’ouvrir chaque fournisseur inscrit, par ordre de priorité, pour l’algorithme spécifié par le paramètre pszAlgId et retourne le handle du premier fournisseur qui a été correctement ouvert. Pendant la durée de vie du handle, toutes les API de chiffrement BCrypt*** utilisent le fournisseur qui a été correctement ouvert.

Windows Server 2008 et Windows Vista : CNG tente de revenir au fournisseur Microsoft CNG.

Voici les noms de fournisseurs prédéfinis.

Valeur	Signification
MS_PRIMITIVE_PROVIDER « Fournisseur Primitif Microsoft »	Identifie le fournisseur Microsoft CNG de base.
MS_PLATFORM_CRYPTO_PROVIDER L"Fournisseur de chiffrement de plateforme Microsoft »	Identifie le fournisseur de stockage de clés TPM fourni par Microsoft.

[in] dwFlags

Indicateurs qui modifient le comportement de la fonction. Il peut s’agir de zéro ou d’une combinaison d’une ou plusieurs des valeurs suivantes.

Valeur	Signification
BCRYPT_ALG_HANDLE_HMAC_FLAG	Le fournisseur effectue l’algorithme Hash-Based code d’authentification de message (HMAC) avec l’algorithme de hachage spécifié. Cet indicateur est utilisé uniquement par les fournisseurs d’algorithmes de hachage.
BCRYPT_PROV_DISPATCH	Charge le fournisseur dans le pool de mémoires non paginés. Si cet indicateur n’est pas présent, le fournisseur est chargé dans le pool de mémoire paginé. Lorsque cet indicateur est spécifié, le handle retourné ne doit pas être fermé avant que tous les objets dépendants aient été libérés. Remarque Cet indicateur est uniquement pris en charge en mode noyau et permet aux opérations suivantes sur le fournisseur d’être traitées au niveau dispatch. Si le fournisseur ne prend pas en charge l’appel au niveau de répartition, il retourne une erreur lors de l’ouverture à l’aide de cet indicateur. Windows Server 2008 et Windows Vista : Cet indicateur est pris en charge uniquement par les fournisseurs d’algorithmes Microsoft et uniquement pour les algorithmes de hachage et des algorithmes de chiffrement symétriques .
BCRYPT_HASH_REUSABLE_FLAG	Crée un objet de hachage réutilisable. L’objet peut être utilisé pour une nouvelle opération de hachage immédiatement après avoir appelé BCryptFinishHash. Pour plus d’informations, consultez Création d’un hachage avec CNG. Windows Server 2008 R2, Windows 7, Windows Server 2008 et Windows Vista : cet indicateur n’est pas pris en charge.

Valeur de retour

Retourne un code d’état qui indique la réussite ou l’échec de la fonction.

Les codes de retour possibles incluent, mais ne sont pas limités à, les éléments suivants.

Retourner le code	Description
STATUS_SUCCESS	La fonction a réussi.
STATUS_NOT_FOUND	Aucun fournisseur n’a été trouvé pour l’ID d’algorithme spécifié.
STATUS_INVALID_PARAMETER	Un ou plusieurs paramètres ne sont pas valides.
STATUS_NO_MEMORY	Un échec d’allocation de mémoire s’est produit.

Remarques

En raison du nombre et du type d’opérations nécessaires pour rechercher, charger et initialiser un fournisseur d’algorithmes, la fonction BCryptOpenAlgorithmProvider est une fonction relativement longue. En raison de cela, nous vous recommandons de mettre en cache tous les handles de fournisseur d’algorithmes que vous utiliserez plusieurs fois, plutôt que d’ouvrir et de fermer les fournisseurs d’algorithmes sur et plus.

BCryptOpenAlgorithmProvider peut être appelé en mode utilisateur ou en mode noyau. Les appelants en mode noyau doivent s’exécuter à PASSIVE_LEVELIRQL.

Pour appeler cette fonction en mode noyau, utilisez Cng.lib, qui fait partie du Kit de développement de pilotes (DDK). Windows Server 2008 et Windows Vista : Pour appeler cette fonction en mode noyau, utilisez Ksecdd.lib.

À compter de Windows 10, CNG ne suit plus chaque mise à jour de la configuration de chiffrement. Certaines modifications, telles que l’ajout d’un nouveau fournisseur par défaut ou la modification de l’ordre de préférence des fournisseurs d’algorithmes, peuvent nécessiter un redémarrage. Pour cette raison, vous devez redémarrer avant d’appeler BCryptOpenAlgorithmProvider avec n’importe quel fournisseur nouvellement configuré.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows Vista [applications de bureau \| Applications UWP]
serveur minimum pris en charge	Windows Server 2008 [applications de bureau \| Applications UWP]
plateforme cible	Windows
d’en-tête	bcrypt.h
bibliothèque	Bcrypt.lib
DLL	Bcrypt.dll

Voir aussi

BCryptCloseAlgorithmProvider

Partager via