BuildSecurityDescriptorA-Funktion (aclapi.h)

Artikel
11/20/2024

Die BuildSecurityDescriptor--Funktion weist eine neue Sicherheitsbeschreibungzu und initialisiert diese. Diese Funktion kann den neuen Sicherheitsdeskriptor initialisieren, indem angegebene Sicherheitsinformationen mit den Informationen in einem vorhandenen Sicherheitsdeskriptor zusammengeführt werden. Wenn Sie keinen vorhandenen Sicherheitsdeskriptor angeben, initialisiert die Funktion einen neuen Sicherheitsdeskriptor basierend auf den angegebenen Sicherheitsinformationen.

Die BuildSecurityDescriptor--Funktion erstellt einen selbstrelativen Sicherheitsdeskriptor. Das selbstrelative Format macht den Sicherheitsdeskriptor zum Speichern in einem Datenstrom geeignet.

Syntax

DWORD BuildSecurityDescriptorA(
  [in, optional] PTRUSTEE_A           pOwner,
  [in, optional] PTRUSTEE_A           pGroup,
  [in]           ULONG                cCountOfAccessEntries,
  [in, optional] PEXPLICIT_ACCESS_A   pListOfAccessEntries,
  [in]           ULONG                cCountOfAuditEntries,
  [in, optional] PEXPLICIT_ACCESS_A   pListOfAuditEntries,
  [in, optional] PSECURITY_DESCRIPTOR pOldSD,
  [out]          PULONG               pSizeNewSD,
  [out]          PSECURITY_DESCRIPTOR *pNewSD
);

Parameter

[in, optional] pOwner

Ein Zeiger auf eine TRUSTEE--Struktur, die den Besitzer für den neuen Sicherheitsdeskriptor identifiziert. Wenn die Struktur das TRUSTEE_IS_NAME Formular verwendet, sucht BuildSecurityDescriptor den Sicherheitsbezeichner (SID), der dem angegebenen Trustee-Namen zugeordnet ist.

Wenn dieser Parameter NULL-ist, verwendet die Funktion die Besitzer-SID aus der ursprünglichen Sicherheitsbeschreibung, auf die pOldSD-verweist. Wenn pOldSD-NULL-ist oder wenn die Besitzer-SID in pOldSD-NULL-ist, wird die Besitzer-SID im neuen Sicherheitsdeskriptor NULL-.

[in, optional] pGroup

Ein Zeiger auf eine TRUSTEE- Struktur, die die primäre Gruppen-SID für den neuen Sicherheitsdeskriptor identifiziert. Wenn die Struktur das TRUSTEE_IS_NAME Formular verwendet, sucht BuildSecurityDescriptor die SID nach, die dem angegebenen Trustee-Namen zugeordnet ist.

Wenn dieser Parameter NULL-ist, verwendet die Funktion die Gruppen-SID aus der ursprünglichen Sicherheitsbeschreibung, auf die pOldSD-verweist. Wenn pOldSD-NULL-ist oder wenn die Gruppen-SID in pOldSD-NULL-ist, ist die Gruppen-SID im neuen Sicherheitsdeskriptor NULL.

[in] cCountOfAccessEntries

Die Anzahl der EXPLICIT_ACCESS Strukturen im pListOfAccessEntries Arrays.

[in, optional] pListOfAccessEntries

Ein Zeiger auf ein Array von EXPLICIT_ACCESS Strukturen, die Zugriffssteuerungsinformationen für die diskretionäre Zugriffssteuerungsliste (DACL) des neuen Sicherheitsdeskriptors beschreiben. Die Funktion erstellt die neue DACL durch Zusammenführen der Informationen im Array mit der DACL in pOldSD-( falls vorhanden). Wenn pOldSD-NULL-ist oder wenn die DACL in pOldSD-NULL-ist, erstellt die Funktion eine neue DACL, die ausschließlich auf den Informationen im Array basiert. Eine Beschreibung der Regeln zum Erstellen einer ACL- aus einem Array von EXPLICIT_ACCESS Strukturen finden Sie in der SetEntriesInAcl-funktion.

Wenn pListOfAccessEntriesNULL-ist, ruft der neue Sicherheitsdeskriptor die DACL von pOldSD-ab. Wenn pOldSD- in diesem Fall NULL-ist oder die DACL in pOldSD-NULL-ist, ist die neue DACL NULL.

[in] cCountOfAuditEntries

Die Anzahl der EXPLICIT_ACCESS Strukturen im pListOfAuditEntries Arrays.

[in, optional] pListOfAuditEntries

Ein Zeiger auf ein Array von EXPLICIT_ACCESS Strukturen, die Überwachungssteuerungsinformationen für die SACL des neuen Sicherheitsdeskriptors beschreiben. Die Funktion erstellt die neue SACL, indem die Informationen im Array mit der SACL in pOldSD-zusammengeführt werden, falls vorhanden. Wenn pOldSD-NULL-ist oder die SACL in pOldSD-NULL-ist, erstellt die Funktion eine neue SACL, die ausschließlich auf den Informationen im Array basiert.

Wenn pListOfAuditEntriesNULL-ist, ruft der neue Sicherheitsdeskriptor die SACL von pOldSDab. Wenn pOldSD- in diesem Fall NULL-ist oder die SACL in pOldSD-NULL-ist, ist die neue SACL NULL.

[in, optional] pOldSD

Ein Zeiger auf eine vorhandene selbstrelative SECURITY_DESCRIPTOR Struktur und zugehörige Sicherheitsinformationen. Die Funktion erstellt den neuen Sicherheitsdeskriptor, indem der angegebene Besitzer, die Gruppe, die Zugriffssteuerung und die Überwachungssteuerungsinformationen mit den Informationen in dieser Sicherheitsbeschreibung zusammengeführt werden. Dieser Parameter kann NULL-sein.

[out] pSizeNewSD

Ein Zeiger auf eine Variable, die die Größe des Sicherheitsdeskriptors in Bytes empfängt.

[out] pNewSD

Ein Zeiger auf eine Variable, die einen Zeiger auf den neuen Sicherheitsdeskriptor empfängt. Die Funktion weist Speicher für den neuen Sicherheitsdeskriptor zu. Sie müssen die funktion LocalFree aufrufen, um den zurückgegebenen Puffer freizugeben.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion ERROR_SUCCESS zurück.

Wenn die Funktion fehlschlägt, wird ein nichtzero-Fehlercode zurückgegeben, der in WinError.h definiert ist.

Bemerkungen

Die BuildSecurityDescriptor--Funktion ist für vertrauenswürdige Server vorgesehen, die Sicherheit für ihre eigenen Objekte implementieren oder verfügbar machen. Die Funktion verwendet selbstrelative Sicherheitsdeskriptoren, die zum Serialisieren in einen Datenstrom und zum Speichern auf einem Datenträger geeignet sind, da ein vertrauenswürdiger Server möglicherweise erforderlich ist.

Anmerkung

Der Header "aclapi.h" definiert BuildSecurityDescriptor als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	aclapi.h
Library	Advapi32.lib
DLL-	Advapi32.dll