BuildSecurityDescriptorA-Funktion (aclapi.h)

Artikel
08/22/2023

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

Die BuildSecurityDescriptor-Funktion erstellt einen selbstrelativen Sicherheitsdeskriptor. Durch das selbstrelative Format eignet sich der Sicherheitsdeskriptor zum Speichern in einem Stream.

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 die neue Sicherheitsbeschreibung identifiziert. Wenn die Struktur das formular TRUSTEE_IS_NAME verwendet, sucht BuildSecurityDescriptor nach dem Sicherheitsbezeichner (SID), der dem angegebenen Treuhändernamen zugeordnet ist.

Wenn dieser Parameter NULL ist, verwendet die Funktion die Besitzer-SID aus dem ursprünglichen Sicherheitsdeskriptor, auf den pOldSD verweist. Wenn pOldSDNULL ist oder die Besitzer-SID in pOldSDNULL ist, ist die Besitzer-SID im neuen Sicherheitsdeskriptor NULL.

[in, optional] pGroup

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

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

[in] cCountOfAccessEntries

Die Anzahl der EXPLICIT_ACCESS Strukturen im pListOfAccessEntries-Array .

[in, optional] pListOfAccessEntries

Ein Zeiger auf ein Array von EXPLICIT_ACCESS Strukturen, die Zugriffssteuerungsinformationen für die diskretionäre Zugriffssteuerungsliste (DACL) der neuen Sicherheitsbeschreibung beschreiben. Die Funktion erstellt die neue DACL, indem sie die Informationen im Array mit der DACL in pOldSD zusammenführen, falls vorhanden. Wenn pOldSDNULL ist oder die DACL in pOldSDNULL 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 pOldSDNULL ist oder die DACL in pOldSDNULL ist, ist die neue DACL NULL.

[in] cCountOfAuditEntries

Die Anzahl der EXPLICIT_ACCESS Strukturen im pListOfAuditEntries-Array .

[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 sie die Informationen im Array mit der SACL in pOldSD zusammenführen, falls vorhanden. Wenn pOldSDNULL oder die SACL in pOldSDNULL 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 pOldSD ab. Wenn pOldSDNULL ist oder die SACL in pOldSDNULL ist, ist die neue SACL NULL.

[in, optional] pOldSD

Ein Zeiger auf eine vorhandene selbst relative SECURITY_DESCRIPTOR-Struktur und die zugehörigen Sicherheitsinformationen. Die Funktion erstellt den neuen Sicherheitsdeskriptor, indem sie die angegebenen Besitzer-, Gruppen-, Zugriffssteuerungs- und Überwachungssteuerungsinformationen mit den Informationen in diesem Sicherheitsdeskriptor zusammenführen. 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 die neue Sicherheitsbeschreibung empfängt. Die Funktion weist Arbeitsspeicher für die neue Sicherheitsbeschreibung 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, gibt sie einen nichtzero-Fehlercode zurück, der in WinError.h definiert ist.

Hinweise

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 Stream und zum Speichern auf dem Datenträger geeignet sind, wie es ein vertrauenswürdiger Server möglicherweise erfordert.

Hinweis

Der aclapi.h-Header definiert BuildSecurityDescriptor als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code 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
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	aclapi.h
Bibliothek	Advapi32.lib
DLL	Advapi32.dll