Funzione CheckTokenMembership (securitybaseapi.h)

Articolo
08/25/2023

La funzione CheckTokenMembership determina se un SID (Security Identifier) specificato è abilitato in un token di accesso. Se si vuole determinare l'appartenenza al gruppo per i token del contenitore di app, è necessario usare la funzione CheckTokenMembershipEx .

Sintassi

BOOL CheckTokenMembership(
  [in, optional] HANDLE TokenHandle,
  [in]           PSID   SidToCheck,
  [out]          PBOOL  IsMember
);

Parametri

[in, optional] TokenHandle

Handle per un token di accesso. L'handle deve avere TOKEN_QUERY l'accesso al token. Il token deve essere un token di rappresentazione.

Se TokenHandle è NULL, CheckTokenMembership usa il token di rappresentazione del thread chiamante. Se il thread non rappresenta, la funzione duplica il token primario del thread per creare un token di rappresentazione.

[in] SidToCheck

Puntatore a una struttura SID . La funzione CheckTokenMembership verifica la presenza di questo SID negli ID utente e di gruppo del token di accesso.

[out] IsMember

Puntatore a una variabile che riceve i risultati del controllo. Se il SID è presente e ha l'attributo SE_GROUP_ENABLED, IsMember restituisce TRUE; in caso contrario, restituisce FALSE.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

La funzione CheckTokenMembership semplifica il processo di determinazione se un SID è presente e abilitato in un token di accesso.

Anche se un SID è presente nel token, il sistema potrebbe non usare il SID in un controllo di accesso. Il SID può essere disabilitato o avere l'attributo SE_GROUP_USE_FOR_DENY_ONLY . Il sistema usa solo i SID abilitati per concedere l'accesso durante l'esecuzione di un controllo di accesso. Per altre informazioni, vedere Attributi SID in un token di accesso.

Se TokenHandle è un token con restrizioni o se TokenHandle è NULL e il token effettivo corrente del thread chiamante è un token con restrizioni, CheckTokenMembership controlla anche se il SID è presente nell'elenco dei SID che limitano i SID.

Esempio

Nell'esempio seguente viene illustrato il controllo dell'appartenenza a un token nel gruppo locale Administrators.

BOOL IsUserAdmin(VOID)
/*++ 
Routine Description: This routine returns TRUE if the caller's
process is a member of the Administrators local group. Caller is NOT
expected to be impersonating anyone and is expected to be able to
open its own process and process token. 
Arguments: None. 
Return Value: 
   TRUE - Caller has Administrators local group. 
   FALSE - Caller does not have Administrators local group. --
*/ 
{
    BOOL b;
    SID_IDENTIFIER_AUTHORITY NtAuthority = SECURITY_NT_AUTHORITY;
    PSID AdministratorsGroup;
    b = AllocateAndInitializeSid(
        &NtAuthority,
        2,
        SECURITY_BUILTIN_DOMAIN_RID,
        DOMAIN_ALIAS_RID_ADMINS,
        0, 0, 0, 0, 0, 0,
        &AdministratorsGroup );

    if(b)
    {
        if (!CheckTokenMembership( NULL, AdministratorsGroup, &b))
        {
             b = FALSE;
        }
        FreeSid(AdministratorsGroup);
    }

    return(b);
}

Requisiti


Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	securitybaseapi.h (include Windows.h)
Libreria	Advapi32.lib
DLL	Advapi32.dll