Fonction AccessCheckByTypeAndAuditAlarmA (winbase.h)
La fonction AccessCheckByTypeAndAuditAlarm détermine si un descripteur de sécurité accorde un ensemble spécifié de droits d’accès au client impersonné par le thread appelant. La fonction peut case activée l’accès du client à une hiérarchie d’objets, comme un objet, ses jeux de propriétés et ses propriétés. La fonction accorde ou refuse l’accès à la hiérarchie dans son ensemble. Si le descripteur de sécurité a 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 AccessCheckByTypeAndAuditAlarmA(
[in] LPCSTR SubsystemName,
[in] LPVOID HandleId,
[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] LPBOOL AccessStatus,
[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] 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 identificateur de sécurité (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 n’importe quel ACE contenant le SID bien connu PRINCIPAL_SELF (S-1-5-10). Pour plus d’informations sur les SID connus, consultez SiDs connus.
Si l’objet protégé ne représente pas de principal, définissez ce paramètre sur NULL.
[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 pour ne contenir aucun droit d’accès générique.
Si ce paramètre est MAXIMUM_ALLOWED, la fonction définit le masque d’accès GrantedAccess pour indiquer les droits d’accès maximaux 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 pour lesquels 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 se trouver 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. Par conséquent, les niveaux des éléments du tableau peuvent être {0, 1, 2, 2, 1, 2, 3}. Si la liste des types d’objets est désordonnées, AccessCheckByTypeAndAuditAlarm é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 nouvel objet lorsque l’accès est accordé. La valeur TRUE indique que l’application va créer un nouvel objet. La valeur FALSE indique que l’application va ouvrir un objet existant.
[out] GrantedAccess
Pointeur vers un masque d’accès qui reçoit les droits d’accès accordés. Si AccessStatus a la valeur FALSE, la fonction définit le masque d’accès sur zéro. Si la fonction échoue, elle ne définit pas le masque d’accès.
[out] AccessStatus
Pointeur vers une variable qui reçoit les résultats du case activée d’accès. Si le descripteur de sécurité autorise les droits d’accès demandés au client, AccessStatus a la valeur TRUE. Sinon, AccessStatus est défini sur FALSE et vous pouvez appeler GetLastError pour obtenir des informations d’erreur étendues.
[out] pfGenerateOnClose
Pointeur vers un indicateur défini par la routine de génération d’audit lorsque la fonction retourne. Passez 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 Vue d’ensemble du fonctionnement d’AccessCheck .
Si les paramètres PrincipalSelfSid et ObjectTypeList sont NULL, que le paramètre AuditType est AuditEventObjectAccess et que le paramètre Flags est égal à zéro, AccessCheckByTypeAndAuditAlarm fonctionne de la même manière que la fonction AccessCheckAndAuditAlarm .
Le tableau ObjectTypeList ne représente pas nécessairement l’ensemble 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 AccessCheckByTypeAndAuditAlarm évalue les AOC qui s’appliquent à l’objet lui-même et les AOC spécifiques à l’objet pour les types d’objets répertoriés dans le tableau ObjectTypeList . La fonction ignore les ADE spécifiques aux objets pour les types d’objets non répertoriés dans le tableau ObjectTypeList . Ainsi, les résultats retournés dans le paramètre AccessStatus indiquent l’accès autorisé au sous-ensemble de l’objet défini par le paramètre ObjectTypeList , et non à l’objet entier.
Pour plus d’informations sur la façon dont une hiérarchie d’ACRE contrôle l’accès à un objet et à ses sous-objets, consultez ADE 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 recherche 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 AccessCheckByTypeAndAuditAlarm é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, AccessCheckByTypeAndAuditAlarm échoue avec ERROR_INVALID_SECURITY_DESCR.
Configuration requise
| 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 |
Voir aussi
AccessCheckByTypeResultListAndAuditAlarm