NCryptCreateProtectionDescriptor, fonction (ncryptprotect.h)

Article
03/04/2024

La fonction NCryptCreateProtectionDescriptor récupère un handle dans un objet de descripteur de protection.

Syntaxe

SECURITY_STATUS NCryptCreateProtectionDescriptor(
  [in]  LPCWSTR                  pwszDescriptorString,
  [in]  DWORD                    dwFlags,
  [out] NCRYPT_DESCRIPTOR_HANDLE *phDescriptor
);

Paramètres

[in] pwszDescriptorString

Chaîne Unicode terminée par null qui contient une chaîne de règle de descripteur de protection ou un nom complet inscrit pour la règle.

Si vous spécifiez le nom complet et que vous souhaitez que cette fonction recherche dans le Registre la chaîne de règle de descripteur de protection associée, vous devez définir le paramètre dwFlags sur NCRYPT_NAMED_DESCRIPTOR_FLAG.

[in] dwFlags

Indicateur qui spécifie si la chaîne dans pwszDescriptorString représente le nom complet d’un descripteur de protection et, le cas échéant, où, dans le Registre, la fonction doit rechercher la chaîne de règle de protection associée. Les combinaisons de valeurs suivantes peuvent être définies :

Pour indiquer que la valeur définie dans le paramètre pwszDescriptorString est une chaîne de règle de descripteur de protection complète plutôt qu’un nom complet, définissez le paramètre dwFlags sur zéro (0).
Pour indiquer que la chaîne est un nom complet et qu’elle est enregistrée, ainsi que la chaîne de règle de descripteur associée, dans la ruche de registre HKEY_LOCAL_MACHINE , au niveau du bit OU la valeur NCRYPT_NAMED_DESCRIPTOR_FLAG et la valeur NCRYPT_MACHINE_KEY_FLAG .
Pour indiquer que la chaîne est un nom d’affichage et qu’elle est enregistrée, avec la règle de chaîne de descripteur associée, dans la ruche HKEY_CURRENT_USER registre, définissez uniquement la valeur NCRYPT_NAMED_DESCRIPTOR_FLAG . Autrement dit, il n’existe aucun indicateur unique pour spécifier la ruche du registre d’utilisateurs actuel.

Note Pour associer une règle de descripteur à un nom complet et enregistrer les deux dans le Registre, appelez la fonction NCryptRegisterProtectionDescriptorName .

[out] phDescriptor

Pointeur vers un handle d’objet de descripteur de protection.

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
ERROR_SUCCESS	La fonction a réussi.
NTE_INVALID_PARAMETER	Le paramètre phDescriptor ne peut pas être NULL. Le paramètre pwszDescriptorString ne peut pas être NULL et il ne peut pas s’agir d’une sting vide.
NTE_BAD_FLAGS	Le paramètre dwFlags doit être NCRYPT_MACHINE_KEY_FLAG ou NCRYPT_NAMED_DESCRIPTOR_FLAG.
NTE_NO_MEMORY	Impossible d’allouer de la mémoire pour récupérer la chaîne de descripteur de protection inscrite.
NTE_NOT_FOUND	Le nom du descripteur de protection spécifié dans le paramètre pwszDescriptorString est introuvable.

Remarques

L’objet de descripteur de protection créé par cette fonction est une structure de données interne qui contient des informations sur le descripteur. Vous ne pouvez pas l’utiliser directement. Toutefois, votre application peut utiliser le handle retourné dans les fonctions suivantes :

Les exemples suivants montrent des chaînes de règles de descripteur de protection :

« SID=S-1-5-21-4392301 AND SID=S-1-5-21-3101812 »
« SDDL=O :S-1-5-5-0-290724G :SYD :(A ;; CCDC ;;; S-1-5-5-0-290724)(A ;; DC;;; WD) »
« LOCAL=user »
« LOCAL=machine »
« WEBCREDENTIALS=MyPasswordName »
« WEBCREDENTIALS=MyPasswordName,myweb.com »

Vous pouvez utiliser la fonction NCryptRegisterProtectionDescriptorName pour associer un nom complet à une chaîne de règle et enregistrer les deux dans le Registre.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2012 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	ncryptprotect.h
Bibliothèque	NCrypt.lib
DLL	NCrypt.dll

Voir aussi

Fonctions DPAPI CNG

Partager via