NCryptCreateProtectionDescriptor-Funktion (ncryptprotect.h)

Artikel
08/25/2023

Die NCryptCreateProtectionDescriptor-Funktion ruft ein Handle für ein Schutzdeskriptorobjekt ab.

Syntax

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

Parameter

[in] pwszDescriptorString

Mit Null beendete Unicode-Zeichenfolge, die eine Schutzdeskriptorregelzeichenfolge oder einen registrierten Anzeigenamen für die Regel enthält.

Wenn Sie den Anzeigenamen angeben und diese Funktion in der Registrierung nach der zugeordneten Schutzdeskriptorregelzeichenfolge suchen soll, müssen Sie den dwFlags-Parameter auf NCRYPT_NAMED_DESCRIPTOR_FLAG festlegen.

[in] dwFlags

Flag, das angibt, ob die Zeichenfolge in pwszDescriptorString den Anzeigenamen eines Schutzdeskriptors darstellt, und wenn ja, wo in der Registrierung die Funktion nach der zugeordneten Schutzregelzeichenfolge suchen soll. Die folgenden Wertkombinationen können festgelegt werden:

Um anzugeben, dass der im parameter pwszDescriptorString festgelegte Wert eine vollständige Schutzdeskriptorregelzeichenfolge und nicht ein Anzeigename ist, legen Sie den dwFlags-Parameter auf Null (0) fest.
Um anzugeben, dass die Zeichenfolge ein Anzeigename ist und dass sie zusammen mit der zugeordneten Deskriptorregelzeichenfolge in der HKEY_LOCAL_MACHINE Registrierungsstruktur gespeichert wird, bitweise-OR den NCRYPT_NAMED_DESCRIPTOR_FLAG Wert und den NCRYPT_MACHINE_KEY_FLAG Wert.
Um anzugeben, dass die Zeichenfolge ein Anzeigename ist und zusammen mit der zugeordneten Deskriptorzeichenfolgenregel in der HKEY_CURRENT_USER Registrierungsstruktur gespeichert wird, legen Sie nur den wert NCRYPT_NAMED_DESCRIPTOR_FLAG fest. Das heißt, es gibt kein eindeutiges Flag, um die aktuelle Benutzerregistrierungsstruktur anzugeben.

Hinweis Um eine Deskriptorregel einem Anzeigenamen zuzuordnen und beide in der Registrierung zu speichern, rufen Sie die Funktion NCryptRegisterProtectionDescriptorName auf.

[out] phDescriptor

Zeiger auf ein Schutzdeskriptorobjekthandle.

Rückgabewert

Gibt einen status Code zurück, der den Erfolg oder Fehler der Funktion angibt. Mögliche Rückgabecodes sind u. a. die folgenden:

Rückgabecode	Beschreibung
ERROR_SUCCESS	Die Funktion war erfolgreich.
NTE_INVALID_PARAMETER	Der phDescriptor-Parameter darf nicht NULL sein. Der pwszDescriptorString-Parameter kann nicht NULL und kein leerer Stich sein.
NTE_BAD_FLAGS	Der dwFlags-Parameter muss NCRYPT_MACHINE_KEY_FLAG oder NCRYPT_NAMED_DESCRIPTOR_FLAG sein.
NTE_NO_MEMORY	Der Speicher konnte nicht zugeordnet werden, um die registrierte Schutzdeskriptorzeichenfolge abzurufen.
NTE_NOT_FOUND	Der im parameter pwszDescriptorString angegebene Schutzdeskriptorname konnte nicht gefunden werden.

Hinweise

Das von dieser Funktion erstellte Schutzdeskriptorobjekt ist eine interne Datenstruktur, die Informationen zum Deskriptor enthält. Sie können es nicht direkt verwenden. Ihre Anwendung kann jedoch das zurückgegebene Handle in den folgenden Funktionen verwenden:

Die folgenden Beispiele zeigen Schutzdeskriptorregelzeichenfolgen:

"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"

Sie können die NCryptRegisterProtectionDescriptorName-Funktion verwenden, um einen Anzeigenamen einer Regelzeichenfolge zuzuordnen und beide in der Registrierung zu speichern.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	ncryptprotect.h
Bibliothek	NCrypt.lib
DLL	NCrypt.dll

Weitere Informationen

CNG DPAPI-Funktionen

Freigeben über