Fonction AccessCheckByTypeResultListAndAuditAlarmByHandleA (winbase.h)

Article
08/27/2023

La fonction AccessCheckByTypeResultListAndAuditAlarmByHandle détermine si un descripteur de sécurité accorde un ensemble spécifié de droits d’accès au client que le thread appelant emprunte l’identité. La différence entre cette fonction et AccessCheckByTypeResultListAndAuditAlarm est que cette fonction permet au thread appelant d’effectuer l’accès case activée avant d’emprunter l’identité du client.

La fonction peut case activée accès à une hiérarchie d’objets, comme un objet, ses jeux de propriétés et ses propriétés. La fonction signale les droits d’accès accordés ou refusés à chaque type d’objet dans la hiérarchie. Si le descripteur de sécurité dispose d’une liste de contrôle d’accès système (SACL) avec des entrées de contrôle d’accès qui s’appliquent au client, la fonction génère tous les messages d’audit nécessaires dans le journal des événements de sécurité. Les alarmes ne sont actuellement pas prises en charge.

Syntaxe

BOOL AccessCheckByTypeResultListAndAuditAlarmByHandleA(
  [in]                LPCSTR               SubsystemName,
  [in]                LPVOID               HandleId,
  [in]                HANDLE               ClientToken,
  [in]                LPCSTR               ObjectTypeName,
  [in, optional]      LPCSTR               ObjectName,
  [in]                PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in, optional]      PSID                 PrincipalSelfSid,
  [in]                DWORD                DesiredAccess,
  [in]                AUDIT_EVENT_TYPE     AuditType,
  [in]                DWORD                Flags,
  [in, out, optional] POBJECT_TYPE_LIST    ObjectTypeList,
  [in]                DWORD                ObjectTypeListLength,
  [in]                PGENERIC_MAPPING     GenericMapping,
  [in]                BOOL                 ObjectCreation,
  [out]               LPDWORD              GrantedAccess,
  [out]               LPDWORD              AccessStatusList,
  [out]               LPBOOL               pfGenerateOnClose
);

Paramètres

[in] SubsystemName

Pointeur vers une chaîne terminée par null qui spécifie le nom du sous-système appelant la fonction . Cette chaîne apparaît dans tout message d’audit généré par la fonction.

[in] HandleId

Pointeur vers une valeur unique qui représente le handle du client vers l’objet . Si l’accès est refusé, le système ignore cette valeur.

[in] ClientToken

Handle vers un objet de jeton qui représente le client qui a demandé l’opération. Ce handle doit être obtenu via une couche de session de communication, telle qu’un canal nommé local, pour éviter d’éventuelles violations de stratégie de sécurité. L’appelant doit avoir un accès TOKEN_QUERY pour le jeton spécifié.

[in] ObjectTypeName

Pointeur vers une chaîne terminée par null qui spécifie le type d’objet en cours de création ou d’accès. Cette chaîne apparaît dans tout message d’audit généré par la fonction.

[in, optional] ObjectName

Pointeur vers une chaîne terminée par null qui spécifie le nom de l’objet en cours de création ou d’accès. Cette chaîne apparaît dans tout message d’audit généré par la fonction.

[in] SecurityDescriptor

Pointeur vers une structure SECURITY_DESCRIPTOR sur laquelle l’accès est vérifié.

[in, optional] PrincipalSelfSid

Pointeur vers un SID. Si le descripteur de sécurité est associé à un objet qui représente un principal (par exemple, un objet utilisateur), le paramètre PrincipalSelfSid doit être le SID de l’objet. Lors de l’évaluation de l’accès, ce SID remplace logiquement le SID dans tout ACE contenant le SID PRINCIPAL_SELF connu (S-1-5-10). Pour plus d’informations sur les SID connus, consultez Sids connus.

Définissez ce paramètre sur NULL si l’objet protégé ne représente pas de principal.

[in] DesiredAccess

Masque d’accès qui spécifie les droits d’accès à case activée. Ce masque doit avoir été mappé par la fonction MapGenericMask afin qu’il ne contienne aucun droit d’accès générique.

Si ce paramètre est MAXIMUM_ALLOWED, la fonction définit le masque d’accès dans GrantedAccess pour indiquer les droits d’accès maximum accordés par le descripteur de sécurité au client.

[in] AuditType

Type d’audit à générer. Il peut s’agir de l’une des valeurs du type d’énumération AUDIT_EVENT_TYPE .

[in] Flags

Indicateur qui contrôle le comportement de la fonction si le processus appelant n’a pas le privilège SE_AUDIT_NAME activé. Si l’indicateur AUDIT_ALLOW_NO_PRIVILEGE est défini, la fonction effectue l’case activée d’accès sans générer de messages d’audit lorsque le privilège n’est pas activé. Si ce paramètre est égal à zéro, la fonction échoue si le privilège n’est pas activé.

[in, out, optional] ObjectTypeList

Pointeur vers un tableau de structures OBJECT_TYPE_LIST qui identifient la hiérarchie des types d’objets auxquels case activée accès. Chaque élément du tableau spécifie un GUID qui identifie le type d’objet et une valeur qui indique le niveau du type d’objet dans la hiérarchie des types d’objets. Le tableau ne doit pas avoir deux éléments avec le même GUID.

Le tableau doit avoir au moins un élément. Le premier élément du tableau doit être au niveau zéro et identifier l’objet lui-même. Le tableau ne peut avoir qu’un seul élément de niveau zéro. Le deuxième élément est un sous-objet, tel qu’un jeu de propriétés, au niveau 1. Après chaque entrée de niveau 1 se trouvent des entrées subordonnées pour les sous-objets de niveau 2 à 4. Ainsi, les niveaux des éléments du tableau peuvent être {0, 1, 2, 2, 1, 2, 3}. Si la liste des types d’objets est dans le désordre, AccessCheckByTypeResultListAndAuditAlarmByHandle échoue et GetLastError retourne ERROR_INVALID_PARAMETER.

[in] ObjectTypeListLength

Nombre d’éléments dans le tableau ObjectTypeList .

[in] GenericMapping

Pointeur vers la structure GENERIC_MAPPING associée à l’objet pour lequel l’accès est vérifié.

[in] ObjectCreation

Indicateur qui détermine si l’application appelante crée un objet lorsque l’accès est accordé. La valeur TRUE indique que l’application va créer un objet. La valeur FALSE indique que l’application ouvre un objet existant.

[out] GrantedAccess

Pointeur vers un tableau de masques d’accès. La fonction définit chaque masque d’accès pour indiquer les droits d’accès accordés à l’élément correspondant dans la liste des types d’objets. Si la fonction échoue, elle ne définit pas les masques d’accès.

[out] AccessStatusList

Pointeur vers un tableau de codes status pour les éléments correspondants dans la liste des types d’objets. La fonction définit un élément sur zéro pour indiquer la réussite ou sur une valeur différente de zéro pour indiquer l’erreur spécifique pendant la case activée d’accès. Si la fonction échoue, elle ne définit aucun des éléments du tableau.

[out] pfGenerateOnClose

Pointeur vers un indicateur défini par la routine de génération d’audit lorsque la fonction retourne. Transmettez cet indicateur à la fonction ObjectCloseAuditAlarm lorsque le handle d’objet est fermé.

Valeur retournée

Si la fonction réussit, la fonction retourne une valeur différente de zéro.

Si la fonction échoue, elle retourne zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Pour plus d’informations, consultez la vue d’ensemble du fonctionnement d’AccessCheck .

Comme AccessCheckByTypeResultListAndAuditAlarm, la fonction AccessCheckByTypeResultListAndAuditAlarmByHandle est une combinaison des fonctions AccessCheckByTypeResultList et AccessCheckAndAuditAlarm . Toutefois, AccessCheckByTypeResultListAndAuditAlarmByHandle nécessite également un handle de jeton client pour fournir des informations de sécurité sur le client.

Le tableau ObjectTypeList ne représente pas nécessairement la totalité de l’objet défini. Il représente plutôt le sous-ensemble de l’objet auquel case activée accès. Pour instance, pour case activée l’accès à deux propriétés dans un jeu de propriétés, spécifiez une liste de types d’objets avec quatre éléments : l’objet lui-même au niveau zéro, la propriété définie au niveau 1 et les deux propriétés au niveau 2.

La fonction AccessCheckByTypeResultListAndAuditAlarmByHandle évalue les ACL qui s’appliquent à l’objet lui-même et les ACL spécifiques à l’objet pour les types d’objets répertoriés dans le tableau ObjectTypeList . La fonction ignore les ACL spécifiques à l’objet pour les types d’objets non répertoriés dans le tableau ObjectTypeList .

Pour plus d’informations sur la façon dont une hiérarchie d’ACL contrôle l’accès à un objet et à ses sous-objets, consultez ACL pour contrôler l’accès aux propriétés d’un objet.

Pour générer des messages d’audit dans le journal des événements de sécurité, le privilège SE_AUDIT_NAME doit être activé pour le processus appelant. Le système vérifie ce privilège dans le jeton principal du processus appelant, et non dans le jeton d’emprunt d’identité du thread. Si le paramètre Flags inclut l’indicateur AUDIT_ALLOW_NO_PRIVILEGE, la fonction effectue l’case activée d’accès sans générer de messages d’audit lorsque le privilège n’est pas activé.

La fonction AccessCheckByTypeResultListAndAuditAlarmByHandle échoue si le thread appelant n’emprunte pas l’identité d’un client.

Si le descripteur de sécurité ne contient pas de SID de propriétaire et de groupe, AccessCheckByTypeResultListAndAuditAlarmByHandle échoue avec ERROR_INVALID_SECURITY_DESCR.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winbase.h (inclure Windows.h)
Bibliothèque	Advapi32.lib
DLL	Advapi32.dll