Funzione AccessCheckByTypeResultListAndAuditAlarmByHandleA (winbase.h)
La funzione AccessCheckByTypeResultListAndAuditAlarmByHandle determina se un descrittore di sicurezza concede un set specificato di diritti di accesso al client che il thread chiamante rappresenta. La differenza tra questa funzione e AccessCheckByTypeResultListAndAuditAlarm è che questa funzione consente al thread chiamante di eseguire il controllo di accesso prima di rappresentare il client.
La funzione può controllare l'accesso a una gerarchia di oggetti, ad esempio un oggetto, i set di proprietà e le proprietà. La funzione segnala i diritti di accesso concessi o negati a ogni tipo di oggetto nella gerarchia. Se il descrittore di sicurezza ha un elenco di controllo di accesso del sistema (SACL) con voci di controllo di accesso (ACES) che si applicano al client, la funzione genera eventuali messaggi di controllo necessari nel registro eventi di sicurezza. Gli avvisi non sono attualmente supportati.
Sintassi
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
);
Parametri
[in] SubsystemName
Puntatore a una stringa con terminazione null che specifica il nome del sottosistema che chiama la funzione. Questa stringa viene visualizzata in qualsiasi messaggio di controllo generato dalla funzione.
[in] HandleId
Puntatore a un valore univoco che rappresenta l'handle del client all'oggetto. Se l'accesso viene negato, il sistema ignora questo valore.
[in] ClientToken
Handle a un oggetto token che rappresenta il client che ha richiesto l'operazione. Questo handle deve essere ottenuto tramite un livello sessione di comunicazione, ad esempio una pipe denominata locale, per evitare possibili violazioni dei criteri di sicurezza. Il chiamante deve avere TOKEN_QUERY accesso per il token specificato.
[in] ObjectTypeName
Puntatore a una stringa con terminazione null che specifica il tipo di oggetto creato o accessibile. Questa stringa viene visualizzata in qualsiasi messaggio di controllo generato dalla funzione.
[in, optional] ObjectName
Puntatore a una stringa con terminazione null che specifica il nome dell'oggetto creato o a cui si accede. Questa stringa viene visualizzata in qualsiasi messaggio di controllo generato dalla funzione.
[in] SecurityDescriptor
Puntatore a una struttura SECURITY_DESCRIPTOR su cui viene controllato l'accesso.
[in, optional] PrincipalSelfSid
Puntatore a un SID. Se il descrittore di sicurezza è associato a un oggetto che rappresenta un'entità (ad esempio un oggetto utente), il parametro PrincipalSelfSid deve essere il SID dell'oggetto . Quando si valuta l'accesso, questo SID sostituisce logicamente il SID in qualsiasi ACE contenente il SID noto PRINCIPAL_SELF SID (S-1-5-10). Per informazioni sui SID noti, vedere SID noti.
Impostare questo parametro su NULL se l'oggetto protetto non rappresenta un'entità.
[in] DesiredAccess
Maschera di accesso che specifica i diritti di accesso da controllare. Questa maschera deve essere stata mappata dalla funzione MapGenericMask in modo che non contenga diritti di accesso generici.
Se questo parametro è MAXIMUM_ALLOWED, la funzione imposta la maschera di accesso in GrantedAccess per indicare i diritti di accesso massimi consentiti dal descrittore di sicurezza.
[in] AuditType
Tipo di controllo da generare. Questo può essere uno dei valori del tipo di enumerazione AUDIT_EVENT_TYPE .
[in] Flags
Flag che controlla il comportamento della funzione se il processo chiamante non ha il privilegio SE_AUDIT_NAME abilitato. Se il flag AUDIT_ALLOW_NO_PRIVILEGE è impostato, la funzione esegue il controllo di accesso senza generare messaggi di controllo quando il privilegio non è abilitato. Se questo parametro è zero, la funzione ha esito negativo se il privilegio non è abilitato.
[in, out, optional] ObjectTypeList
Puntatore a una matrice di strutture OBJECT_TYPE_LIST che identificano la gerarchia dei tipi di oggetto per cui controllare l'accesso. Ogni elemento della matrice specifica un GUID che identifica il tipo di oggetto e un valore che indica il livello del tipo di oggetto nella gerarchia dei tipi di oggetto. La matrice non deve avere due elementi con lo stesso GUID.
La matrice deve avere almeno un elemento. Il primo elemento della matrice deve essere a livello zero e identificare l'oggetto stesso. La matrice può avere un solo elemento zero di livello. Il secondo elemento è un oggetto secondario, ad esempio un set di proprietà, a livello 1. Dopo ogni voce di livello 1 sono voci subordinate per il livello 2 a 4 oggetti secondari. Pertanto, i livelli per gli elementi nella matrice potrebbero essere {0, 1, 2, 2, 1, 2, 2, 3}. Se l'elenco dei tipi di oggetto non è in ordine, AccessCheckByTypeResultListAndAuditAlarmByHandle ha esito negativo e GetLastError restituisce ERROR_INVALID_PARAMETER.
[in] ObjectTypeListLength
Numero di elementi nella matrice ObjectTypeList .
[in] GenericMapping
Puntatore alla struttura GENERIC_MAPPING associata all'oggetto per cui viene controllato l'accesso.
[in] ObjectCreation
Flag che determina se l'applicazione chiamante creerà un nuovo oggetto quando viene concesso l'accesso. Un valore true indica che l'applicazione creerà un nuovo oggetto. Un valore false indica che l'applicazione aprirà un oggetto esistente.
[out] GrantedAccess
Puntatore a una matrice di maschere di accesso. La funzione imposta ogni maschera di accesso per indicare i diritti di accesso concessi all'elemento corrispondente nell'elenco dei tipi di oggetto. Se la funzione ha esito negativo, non imposta le maschere di accesso.
[out] AccessStatusList
Puntatore a una matrice di codici di stato per gli elementi corrispondenti nell'elenco dei tipi di oggetto. La funzione imposta un elemento su zero per indicare l'esito positivo o un valore diverso da zero per indicare l'errore specifico durante il controllo di accesso. Se la funzione ha esito negativo, non imposta alcun elemento nella matrice.
[out] pfGenerateOnClose
Puntatore a un flag impostato dalla routine di generazione di controllo quando la funzione restituisce. Passare questo flag alla funzione ObjectCloseAuditAlarm quando l'handle dell'oggetto viene chiuso.
Valore restituito
Se la funzione ha esito positivo, la funzione restituisce un valore diverso da zero.
Se la funzione ha esito negativo, restituisce zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.
Commenti
Per altre informazioni, vedere la panoramica su Come AccessCheck Works .
Come AccessCheckByTypeResultListAndAuditAlarm, la funzione AccessCheckByTypeResultListAndAuditAlarmByHandle è una combinazione delle funzioni AccessCheckByTypeResultList e AccessCheckAndAuditAlarm . Tuttavia, AccessCheckByTypeResultListAndAuditAlarmByHandle richiede anche un handle token client per fornire informazioni di sicurezza nel client.
La matrice ObjectTypeList non rappresenta necessariamente l'intero oggetto definito. Invece, rappresenta il subset dell'oggetto per cui controllare l'accesso. Ad esempio, per controllare l'accesso a due proprietà in un set di proprietà, specificare un elenco di tipi di oggetto con quattro elementi: l'oggetto stesso a livello zero, la proprietà impostata a livello 1 e le due proprietà a livello 2.
La funzione AccessCheckByTypeResultListAndAuditAlarmByHandle valuta gli ACL che si applicano all'oggetto stesso e gli ACL specifici dell'oggetto per i tipi di oggetto elencati nella matrice ObjectTypeList . La funzione ignora gli ACL specifici dell'oggetto per i tipi di oggetto non elencati nella matrice ObjectTypeList .
Per altre informazioni sul modo in cui una gerarchia degli ACL controlla l'accesso a un oggetto e ai relativi oggetti secondari, vedere ACL per controllare l'accesso alle proprietà di un oggetto.
Per generare messaggi di controllo nel registro eventi di sicurezza, il processo di chiamata deve avere il privilegio SE_AUDIT_NAME abilitato. Il sistema verifica questo privilegio nel token primario del processo chiamante, non il token di rappresentazione del thread. Se il parametro Flags include il flag AUDIT_ALLOW_NO_PRIVILEGE, la funzione esegue il controllo di accesso senza generare messaggi di controllo quando il privilegio non è abilitato.
La funzione AccessCheckByTypeResultListAndAuditAlarmByHandle non riesce se il thread chiamante non rappresenta un client.
Se il descrittore di sicurezza non contiene i SID del proprietario e del gruppo, AccessCheckByTypeResultListAndAuditAlarmByHandle ha esito negativo con ERROR_INVALID_SECURITY_DESCR.
Requisiti
Requisito | Valore |
---|---|
Client minimo supportato | Windows XP [solo app desktop] |
Server minimo supportato | Windows Server 2003 [solo app desktop] |
Piattaforma di destinazione | Windows |
Intestazione | winbase.h (include Windows.h) |
Libreria | Advapi32.lib |
DLL | Advapi32.dll |
Vedi anche
AccessCheckByTypeResultListAndAuditAlarm
Controllo di accesso client/server
Commenti e suggerimenti
https://aka.ms/ContentUserFeedback.
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedereInvia e visualizza il feedback per