Fonction BCryptOpenAlgorithmProvider (bcrypt.h)

  • Article

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 primitif de chiffrement. Ce paramètre est facultatif et peut être NULL s’il n’est pas nécessaire. Si ce paramètre a la valeur NULL, le fournisseur par défaut de l’algorithme spécifié est chargé.

Note 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é ouvert avec succès. Pendant la durée de vie du handle, toutes les API de chiffrement BCrypt*** utilisent le fournisseur qui a été ouvert.
 
Windows Server 2008 et Windows Vista : Le GNC tente de revenir au fournisseur Microsoft CNG.

Voici les noms de fournisseur prédéfinis.

Valeur Signification
MS_PRIMITIVE_PROVIDER
« Fournisseur Primitif Microsoft »
 Identifie le fournisseur CNG Microsoft de base.
MS_PLATFORM_CRYPTO_PROVIDER
L"Microsoft Platform Crypto Provider »
 Identifie le fournisseur de stockage de clé 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 HMAC ( Hash-Based Message Authentication Code ) 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émoire non paginé. Si cet indicateur n’est pas présent, le fournisseur est chargé dans le pool de mémoire paginée. 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.
Note Cet indicateur est uniquement pris en charge en mode noyau et permet de traiter les opérations suivantes sur le fournisseur au niveau Dispatch. Si le fournisseur ne prend pas en charge l’appel au niveau de la répartition, il retourne une erreur lors de l’ouverture à l’aide de cet indicateur.
 
Windows Server 2008 et Windows Vista : Cet indicateur est uniquement pris en charge par les fournisseurs d’algorithmes Microsoft et uniquement pour les algorithmes de hachage et les algorithmesde chiffrement declés 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 l’appel de 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 retournée

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

Les codes de retour possibles incluent, sans s’y limiter, les éléments suivants.

Code de retour 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’algorithme, la fonction BCryptOpenAlgorithmProvider est une fonction relativement longue. Pour cette raison, 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 encore et encore.

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 pilote (DDK). Windows Server 2008 et Windows Vista : Pour appeler cette fonction en mode noyau, utilisez Ksecdd.lib.

À compter de Windows 10, le GNC 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é.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows Vista [applications de bureau | applications UWP]
Serveur minimal pris en charge Windows Server 2008 [applications de bureau | applications UWP]
Plateforme cible Windows
En-tête bcrypt.h
Bibliothèque Bcrypt.lib
DLL Bcrypt.dll

Voir aussi

BCryptCloseAlgorithmProvider