Función CreateRestrictedToken (securitybaseapi.h)

Artículo
03/01/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 tener identificadores de seguridad deshabilitados (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 un token principal o 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, se omiten los parámetros DeletePrivilegeCount y PrivilegesToDelete .
SANDBOX_INERT 0x2	Si se usa este valor, el sistema no comprueba las reglas de AppLocker ni aplica las 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 los 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, vea "Puede eludir las reglas de AppLocker mediante una macro de Office en un equipo que ejecuta Windows 7 o Windows Server 2008 R2" en la Base de conocimiento ayuda y soporte técnico en http://support.microsoft.com/kb/2532445. 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 se consideran solo 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 mediante una llamada 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. Todos los demás atributos se omiten.

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 con el 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 miembro Attributes de la estructura 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 PrivilegesToDelete .

[in, optional] PrivilegesToDelete

Puntero a una matriz de estructuras de LUID_AND_ATTRIBUTES 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 el token existente no mantiene.

La función omite los miembros Attributes 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 estructuras de SID_AND_ATTRIBUTES que especifican una lista de restricciones de SID 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 miembro Attributes de la estructura SID_AND_ATTRIBUTES debe ser cero. La restricción de los 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 para el 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 realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

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

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, vea Atributos de SID en un token de acceso.
Quite privilegios del token.
Especifique una lista de restricciones de SID, que el sistema usa cuando comprueba el acceso del token a un objeto protegible. El sistema realiza dos comprobaciones de acceso: una con los SID habilitados del token y otra mediante 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 .

Precaución 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 parte de 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	Value
Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	securitybaseapi.h (incluya Windows.h)
Library	Advapi32.lib
Archivo DLL	Advapi32.dll