Funzione CreateRestrictedToken (securitybaseapi.h)
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 |
---|---|
|
Disabilita tutti i privilegi nel nuovo token, ad eccezione del privilegio SeChangeNotifyPrivilege . Se questo valore viene specificato, i parametri DeletePrivilegeCount e PrivilegesToDelete vengono ignorati. |
|
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. |
|
Il nuovo token è un token LUA.
Windows Server 2003 e Windows XP: Questo valore non è supportato. |
|
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 ImpersonateLoggedOnUser .
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 |
Vedi anche
Panoramica di Controllo di accesso