Funzione CreateRestrictedToken (securitybaseapi.h)

Articolo
08/25/2023

La funzione CreateRestrictedToken crea un nuovo token di accesso che rappresenta una versione con restrizioni di un token di accesso esistente. Il token con restrizioni può avere disabilitato gli identificatori di sicurezza (SID), i privilegi eliminati e un elenco di SID limitati. Per altre informazioni, vedere Token con restrizioni.

Sintassi

BOOL CreateRestrictedToken(
  [in]           HANDLE               ExistingTokenHandle,
  [in]           DWORD                Flags,
  [in]           DWORD                DisableSidCount,
  [in, optional] PSID_AND_ATTRIBUTES  SidsToDisable,
  [in]           DWORD                DeletePrivilegeCount,
  [in, optional] PLUID_AND_ATTRIBUTES PrivilegesToDelete,
  [in]           DWORD                RestrictedSidCount,
  [in, optional] PSID_AND_ATTRIBUTES  SidsToRestrict,
  [out]          PHANDLE              NewTokenHandle
);

Parametri

[in] ExistingTokenHandle

Handle per un token primario o di rappresentazione. Il token può anche essere un token con restrizioni. L'handle deve avere TOKEN_DUPLICATE l'accesso al token.

[in] Flags

Specifica opzioni di privilegio aggiuntive. Questo parametro può essere zero o una combinazione dei valori seguenti.

Valore	Significato
DISABLE_MAX_PRIVILEGE 0x1	Disabilita tutti i privilegi nel nuovo token, ad eccezione del privilegio SeChangeNotifyPrivilege . Se questo valore viene specificato, i parametri DeletePrivilegeCount e PrivilegesToDelete vengono ignorati.
SANDBOX_INERT 0x2	Se questo valore viene usato, il sistema non controlla le regole di AppLocker o applica criteri di restrizione software. Per AppLocker, questo flag disabilita i controlli per tutte e quattro le raccolte di regole: Eseguibile, Windows Installer, Script e DLL. Quando si crea un programma di installazione che deve eseguire DLL estratte durante l'installazione, usare il flag SAFER_TOKEN_MAKE_INERT nella funzione SaferComputeTokenFromLevel . È possibile eseguire una query su un token per verificare l'esistenza di questo flag usando GetTokenInformation. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Nei sistemi con KB2532445 installato, il chiamante deve essere in esecuzione come LocalSystem o TrustedInstaller oppure il sistema ignora questo flag. Per altre informazioni, vedere "È possibile aggirare le regole di AppLocker usando una macro di Office in un computer che esegue Windows 7 o Windows Server 2008 R2" nella Guida e nella Knowledge Base del supporto tecnico all'indirizzo http://support.microsoft.com/kb/2532445. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: AppLocker non è supportato. AppLocker è stato introdotto in Windows 7 e Windows Server 2008 R2.
LUA_TOKEN 0x4	Il nuovo token è un token LUA. Windows Server 2003 e Windows XP: Questo valore non è supportato.
WRITE_RESTRICTED 0x8	Il nuovo token contiene la limitazione dei SID considerati solo quando si valuta l'accesso in scrittura. Windows XP con SP2 e versioni successive: Il valore di questa costante è 0x4. Affinché un'applicazione sia compatibile con Windows XP con SP2 e sistemi operativi successivi, l'applicazione deve eseguire una query sul sistema operativo chiamando la funzione GetVersionEx per determinare quale valore deve essere usato. Windows Server 2003 e Windows XP con SP1 e versioni precedenti: Questo valore non è supportato.

[in] DisableSidCount

Specifica il numero di voci nella matrice SidsToDisable .

[in, optional] SidsToDisable

Puntatore a una matrice di strutture SID_AND_ATTRIBUTES che specificano i SID di sola negazione nel token con restrizioni. Il sistema usa un SID di sola negazione per negare l'accesso a un oggetto a protezione diretta. L'assenza di un SID di sola negazione non consente l'accesso.

La disabilitazione di un SID attiva SE_GROUP_USE_FOR_DENY_ONLY e disattiva SE_GROUP_ENABLED e SE_GROUP_ENABLED_BY_DEFAULT. Tutti gli altri attributi vengono ignorati.

Gli attributi di sola negazione si applicano a qualsiasi combinazione dei SID di un token esistente, inclusi i SID utente e i SID di gruppo con l'attributo SE_GROUP_MANDATORY. Per ottenere i SID associati al token esistente, usare la funzione GetTokenInformation con i flag TokenUser e TokenGroups. La funzione ignora tutti i SID nella matrice che non vengono trovati anche nel token esistente.

La funzione ignora il membro Attributes della struttura SID_AND_ATTRIBUTES .

Questo parametro può essere NULL se non è necessario disabilitare alcun SID.

[in] DeletePrivilegeCount

Specifica il numero di voci nella matrice PrivilegesToDelete .

[in, optional] PrivilegesToDelete

Puntatore a una matrice di strutture LUID_AND_ATTRIBUTES che specificano i privilegi da eliminare nel token con restrizioni.

La funzione GetTokenInformation può essere usata con il flag TokenPrivileges per recuperare i privilegi mantenuti dal token esistente. La funzione ignora tutti i privilegi nella matrice che non sono mantenuti dal token esistente.

La funzione ignora i membri Attributes delle strutture LUID_AND_ATTRIBUTES .

Questo parametro può essere NULL se non si desidera eliminare alcun privilegio.

Se il programma chiamante passa troppi privilegi in questa matrice, CreateRestrictedToken restituisce ERROR_INVALID_PARAMETER.

[in] RestrictedSidCount

Specifica il numero di voci nella matrice SidsToRestrict .

[in, optional] SidsToRestrict

Puntatore a una matrice di strutture SID_AND_ATTRIBUTES che specificano un elenco di SID limitati per il nuovo token. Se il token esistente è un token con restrizioni, l'elenco di SID limitati per il nuovo token è l'intersezione di questa matrice e l'elenco di limitazione dei SID per il token esistente. Non viene eseguito alcun controllo per rimuovere i SID duplicati inseriti nel parametro SidsToRestrict . I SID duplicati consentono a un token con restrizioni di avere informazioni ridondanti nell'elenco SID di limitazione.

Il membro Attributes della struttura SID_AND_ATTRIBUTES deve essere zero. La limitazione dei SID è sempre abilitata per i controlli di accesso.

Questo parametro può essere NULL se non si desidera specificare i SID limitati.

[out] NewTokenHandle

Puntatore a una variabile che riceve un handle per il nuovo token con restrizioni. Questo handle ha gli stessi diritti di accesso di ExistingTokenHandle. Il nuovo token è lo stesso tipo, primario o rappresentazione, del token esistente. L'handle restituito in NewTokenHandle può essere duplicato.

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 CreateRestrictedToken può limitare il token nei modi seguenti:

Applicare l'attributo di sola negazione ai SID nel token in modo che non possano essere usati per accedere a oggetti protetti. Per altre informazioni sull'attributo di sola negazione, vedere Attributi SID in un token di accesso.
Rimuovere i privilegi dal token.
Specificare un elenco di SID di limitazione, che il sistema usa quando controlla l'accesso del token a un oggetto a protezione diretta. Il sistema esegue due controlli di accesso: uno usando i SID abilitati del token e un altro usando l'elenco dei SID di limitazione. L'accesso viene concesso solo se entrambi i controlli di accesso consentono i diritti di accesso richiesti.

È possibile usare il token con restrizioni nella funzione CreateProcessAsUser per creare un processo con diritti di accesso e privilegi limitati. Se un processo chiama CreateProcessAsUser usando una versione con restrizioni del proprio token, il processo chiamante non deve avere il privilegio SE_ASSIGNPRIMARYTOKEN_NAME.

È possibile usare il token con restrizioni nella funzione ImpersonateLoggedOnUser .

Attenzione Le applicazioni che usano token con restrizioni devono eseguire l'applicazione con restrizioni nei desktop diversi dal desktop predefinito. Ciò è necessario per evitare un attacco da parte di un'applicazione con restrizioni, tramite SendMessage o PostMessage, per applicazioni senza restrizioni sul desktop predefinito. Se necessario, passare da un desktop all'altro ai fini dell'applicazione.

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	securitybaseapi.h (include Windows.h)
Libreria	Advapi32.lib
DLL	Advapi32.dll