Funzione CreateRestrictedToken (securitybaseapi.h)

Articolo
11/08/2024

La funzione di CreateRestrictedToken crea un nuovo token di accesso che è una versione limitata di un token di accesso esistente. Il token con restrizioni può avere disabilitato identificatori di sicurezza (SID), 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 primario o token 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 regole di Di AppLocker o applica i criteri di restrizione software . Per AppLocker, questo flag disabilita i controlli per tutte e quattro le raccolte 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 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 o 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. 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 durante la valutazione dell'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 Attributes membro 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 contenuti nel token esistente.

La funzione ignora i Attributi membri delle strutture di 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 dei 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 limitato.

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 alcun SID limitato.

[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, come 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 ottenere informazioni estese sull'errore, chiamare GetLastError.

Osservazioni

La funzione CreateRestrictedToken può limitare il token nei modi seguenti:

Applicare l'attributo deny-only ai SID nel token in modo che non possano essere usati per accedere a oggetti protetti. Per altre informazioni sull'attributo deny-only, vedere attributi SID in un token di accesso.
Rimuovere privilegi dal token.
Specificare un elenco di SID limitati, 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 limitati. 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.

Avvertimento

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

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [solo app desktop]
server minimo supportato	Windows Server 2003 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	securitybaseapi.h (include Windows.h)
libreria	Advapi32.lib
dll	Advapi32.dll