Función CreateRestrictedToken (securitybaseapi.h)

Artículo
11/08/2024

La función CreateRestrictedToken crea un nuevo token de acceso que es una versión restringida de un token de acceso existente. El token restringido puede haber deshabilitado identificadores de seguridad (SID), privilegios eliminados y una lista de restricciones de SID. Para obtener más información, consulte tokens restringidos.

Sintaxis

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
);

Parámetros

[in] ExistingTokenHandle

Identificador de una principal o token de suplantación. El token también puede ser un token restringido. El identificador debe tener TOKEN_DUPLICATE acceso al token.

[in] Flags

Especifica opciones de privilegios adicionales. Este parámetro puede ser cero o una combinación de los valores siguientes.

Valor	Significado
DISABLE_MAX_PRIVILEGE `0x1`	Deshabilita todos los privilegios del nuevo token, excepto el privilegio SeChangeNotifyPrivilege. Si se especifica este valor, los parámetros de DeletePrivilegeCount y PrivilegesToDelete se omiten.
SANDBOX_INERT `0x2`	Si se usa este valor, el sistema no comprueba reglas de de AppLocker ni aplica directivas de restricción de software. Para AppLocker, esta marca deshabilita las comprobaciones de las cuatro colecciones de reglas: Ejecutable, Windows Installer, Script y DLL. Al crear un programa de instalación que debe ejecutar archivos DLL extraídos durante la instalación, use la marca SAFER_TOKEN_MAKE_INERT en la función SaferComputeTokenFromLevel. Se puede consultar un token para que exista esta marca mediante GetTokenInformation. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: En sistemas con KB2532445 instalados, el autor de la llamada debe ejecutarse como LocalSystem o TrustedInstaller o el sistema omite esta marca. Para obtener más información, consulte Puede eludir las reglas de AppLocker mediante una macro de Office en un equipo que ejecuta Windows 7 o Windows Server 2008 R2. Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: no se admite AppLocker. AppLocker se introdujo en Windows 7 y Windows Server 2008 R2.
LUA_TOKEN `0x4`	El nuevo token es un token LUA. Windows Server 2003 y Windows XP: Este valor no se admite.
WRITE_RESTRICTED `0x8`	El nuevo token contiene restricciones de SID que solo se consideran al evaluar el acceso de escritura. Windows XP con SP2 y versiones posteriores: El valor de esta constante es `0x4`. Para que una aplicación sea compatible con Windows XP con SP2 y sistemas operativos posteriores, la aplicación debe consultar el sistema operativo llamando a la función GetVersionEx para determinar qué valor se debe usar. Windows Server 2003 y Windows XP con SP1 y versiones anteriores: Este valor no se admite.

[in] DisableSidCount

Especifica el número de entradas de la matriz SidsToDisable.

[in, optional] SidsToDisable

Puntero a una matriz de estructuras de SID_AND_ATTRIBUTES que especifican los SID de solo denegación en el token restringido. El sistema usa un SID de solo denegación para denegar el acceso a un objeto protegible. La ausencia de un SID de solo denegación no permite el acceso.

Deshabilitar un SID activa SE_GROUP_USE_FOR_DENY_ONLY y desactiva SE_GROUP_ENABLED y SE_GROUP_ENABLED_BY_DEFAULT. Se omiten todos los demás atributos.

Los atributos de solo denegación se aplican a cualquier combinación de SID de un token existente, incluidos el SID de usuario y los SID de grupo que tienen el atributo SE_GROUP_MANDATORY. Para obtener los SID asociados al token existente, use la función GetTokenInformation con las marcas TokenUser y TokenGroups. La función omite los SID de la matriz que no se encuentran también en el token existente.

La función omite el atributo miembro de la estructura de SID_AND_ATTRIBUTES.

Este parámetro puede ser NULL si no se va a deshabilitar ningún SID.

[in] DeletePrivilegeCount

Especifica el número de entradas de la matriz de PrivilegesToDelete.

[in, optional] PrivilegesToDelete

Puntero a una matriz de LUID_AND_ATTRIBUTES estructuras que especifican los privilegios que se van a eliminar en el token restringido.

La función GetTokenInformation se puede usar con la marca TokenPrivileges para recuperar los privilegios mantenidos por el token existente. La función omite los privilegios de la matriz que no están mantenidos por el token existente.

La función omite los atributos miembros de las estructuras de LUID_AND_ATTRIBUTES.

Este parámetro puede ser NULL si no desea eliminar ningún privilegio.

Si el programa de llamada pasa demasiados privilegios en esta matriz, CreateRestrictedToken devuelve ERROR_INVALID_PARAMETER.

[in] RestrictedSidCount

Especifica el número de entradas de la matriz SidsToRestrict.

[in, optional] SidsToRestrict

Puntero a una matriz de SID_AND_ATTRIBUTES estructuras que especifican una lista de SID de restricción para el nuevo token. Si el token existente es un token restringido, la lista de SID de restricción para el nuevo token es la intersección de esta matriz y la lista de restricciones de SID para el token existente. No se realiza ninguna comprobación para quitar los SID duplicados que se colocaron en el parámetro SidsToRestrict. Los SID duplicados permiten que un token restringido tenga información redundante en la lista de SID de restricción.

El Atributos miembro de la estructura SID_AND_ATTRIBUTES debe ser cero. La restricción de SID siempre está habilitada para las comprobaciones de acceso.

Este parámetro puede ser NULL si no desea especificar ningún SID de restricción.

[out] NewTokenHandle

Puntero a una variable que recibe un identificador del nuevo token restringido. Este identificador tiene los mismos derechos de acceso que ExistingTokenHandle. El nuevo token es el mismo tipo, principal o suplantación , que el token existente. El identificador devuelto en NewTokenHandle se puede duplicar.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es distinto de cero.

Si se produce un error en la función, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Observaciones

La función CreateRestrictedToken puede restringir el token de las maneras siguientes:

Aplique el atributo de solo denegación a los SID del token para que no se puedan usar para acceder a objetos protegidos. Para obtener más información sobre el atributo de solo denegación, consulte atributos de SID en un token de acceso.
Quite privilegios del token.
Especifique una lista de restricciones de SID, que usa el sistema cuando comprueba el acceso del token a un objeto protegible. El sistema realiza dos comprobaciones de acceso: una mediante los SID habilitados del token y otra con la lista de restricciones de SID. Solo se concede acceso si ambas comprobaciones de acceso permiten los derechos de acceso solicitados.

Puede usar el token restringido en la función CreateProcessAsUser para crear un proceso que tenga privilegios y derechos de acceso restringidos. Si un proceso llama a CreateProcessAsUser mediante una versión restringida de su propio token, el proceso de llamada no necesita tener el privilegio SE_ASSIGNPRIMARYTOKEN_NAME.

Puede usar el token restringido en la función ImpersonateLoggedOnUser.

Advertencia

Las aplicaciones que usan tokens restringidos deben ejecutar la aplicación restringida en escritorios distintos del escritorio predeterminado. Esto es necesario para evitar un ataque por una aplicación restringida, mediante SendMessage o PostMessage, para aplicaciones sin restricciones en el escritorio predeterminado. Si es necesario, cambie entre escritorios con fines de aplicación.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2003 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	securitybaseapi.h (incluya Windows.h)
biblioteca de	Advapi32.lib
DLL de	Advapi32.dll