Función AccessCheckByTypeResultList (securitybaseapi.h)

Artículo
03/01/2024

La función AccessCheckByTypeResultList determina si un descriptor de seguridad concede un conjunto especificado de derechos de acceso al cliente identificado por un token de acceso. La función puede comprobar el acceso del cliente a una jerarquía de objetos, como un objeto, sus conjuntos de propiedades y propiedades. La función informa de los derechos de acceso concedidos o denegados a cada tipo de objeto de la jerarquía. Normalmente, las aplicaciones de servidor usan esta función para comprobar el acceso a un objeto privado.

Sintaxis

BOOL AccessCheckByTypeResultList(
  [in]                PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in, optional]      PSID                 PrincipalSelfSid,
  [in]                HANDLE               ClientToken,
  [in]                DWORD                DesiredAccess,
  [in, out, optional] POBJECT_TYPE_LIST    ObjectTypeList,
  [in]                DWORD                ObjectTypeListLength,
  [out]               PGENERIC_MAPPING     GenericMapping,
  [out, optional]     PPRIVILEGE_SET       PrivilegeSet,
  [in, out]           LPDWORD              PrivilegeSetLength,
  [out]               LPDWORD              GrantedAccessList,
  [out]               LPDWORD              AccessStatusList
);

Parámetros

[in] pSecurityDescriptor

Puntero a una estructura de SECURITY_DESCRIPTOR en la que se comprueba el acceso.

[in, optional] PrincipalSelfSid

Puntero a un identificador de seguridad (SID). Si el descriptor de seguridad está asociado a un objeto que representa una entidad de seguridad (por ejemplo, un objeto de usuario), el parámetro PrincipalSelfSid debe ser el SID del objeto. Al evaluar el acceso, este SID reemplaza lógicamente el SID en cualquier entrada de control de acceso (ACE) que contenga el SID de PRINCIPAL_SELF conocido (S-1-5-10). Para obtener información sobre los SID conocidos, consulte SID conocidos.

Si el objeto protegido no representa una entidad de seguridad, establezca este parámetro en NULL.

[in] ClientToken

Identificador de un token de suplantación que representa al cliente que intenta obtener acceso. El identificador debe tener TOKEN_QUERY acceso al token; de lo contrario, se produce un error en la función con ERROR_ACCESS_DENIED.

[in] DesiredAccess

Máscara de acceso que especifica los derechos de acceso que se van a comprobar. La función MapGenericMask debe haber asignado esta máscara para que no contenga derechos de acceso genéricos.

Si este parámetro es MAXIMUM_ALLOWED, la función establece las máscaras de acceso en la matriz GrantedAccess para indicar los derechos de acceso máximo del cliente a cada elemento de la lista de tipos de objeto.

[in, out, optional] ObjectTypeList

Puntero a una matriz de estructuras de OBJECT_TYPE_LIST que identifican la jerarquía de tipos de objetos para los que se va a comprobar el acceso. Cada elemento de la matriz especifica un GUID que identifica el tipo de objeto y un valor que indica el nivel del tipo de objeto en la jerarquía de tipos de objeto. La matriz no debe tener dos elementos con el mismo GUID.

La matriz debe tener al menos un elemento . El primer elemento de la matriz debe estar en el nivel cero e identificar el propio objeto. La matriz solo puede tener un elemento de nivel cero. El segundo elemento es un subobjeto, como un conjunto de propiedades, en el nivel 1. Después de cada entrada de nivel 1, hay entradas subordinadas para los subobjetos de nivel 2 a 4. Por lo tanto, los niveles de los elementos de la matriz pueden ser {0, 1, 2, 2, 1, 2, 3}. Si la lista de tipos de objeto no está ordenada, AccessCheckByTypeResultList produce un error y GetLastError devuelve ERROR_INVALID_PARAMETER.

[in] ObjectTypeListLength

Número de elementos de la matriz ObjectTypeList . También es el número de elementos de las matrices a las que apuntan los parámetros GrantedAccessList y AccessStatusList .

[out] GenericMapping

Puntero a la estructura GENERIC_MAPPING asociada al objeto para el que se comprueba el acceso.

[out, optional] PrivilegeSet

Puntero a una estructura de PRIVILEGE_SET que recibe los privilegios usados para realizar la validación de acceso. Si no se usaron privilegios, la función establece el miembro PrivilegeCount en cero.

[in, out] PrivilegeSetLength

Tamaño, en bytes, del búfer al que apunta el parámetro PrivilegeSet .

[out] GrantedAccessList

Puntero a una matriz de máscaras de acceso. La función establece cada máscara de acceso para indicar los derechos de acceso concedidos al elemento correspondiente de la lista de tipos de objeto. Si se produce un error en la función, no establece las máscaras de acceso.

[out] AccessStatusList

Puntero a una matriz de códigos de estado para los elementos correspondientes de la lista de tipos de objeto. La función establece un elemento en cero para indicar que se ha realizado correctamente o un valor distinto de cero para indicar el error específico durante la comprobación de acceso. Si se produce un error en la función, no establece ninguno de los elementos de la matriz.

Valor devuelto

Si la función se ejecuta correctamente, la función devuelve un valor distinto de cero.

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

Comentarios

Para obtener más información, consulte La información general sobre cómo funciona AccessCheck .

La función AccessCheckByTypeResultList compara el descriptor de seguridad especificado con el token de acceso especificado e indica, en el parámetro AccessStatusList , si se concede o deniega el acceso para cada uno de los elementos de la lista de tipos de objeto.

La matriz ObjectTypeList no representa necesariamente todo el objeto definido. En su lugar, representa ese subconjunto del objeto para el que se va a comprobar el acceso. Por ejemplo, para comprobar el acceso a dos propiedades de un conjunto de propiedades, especifique una lista de tipos de objeto con cuatro elementos: el propio objeto en el nivel cero, la propiedad establecida en el nivel 1 y las dos propiedades en el nivel 2.

La función AccessCheckByTypeResultList evalúa los ASE que se aplican al propio objeto y a los ASE específicos del objeto para los tipos de objeto enumerados en la matriz ObjectTypeList . La función omite las ACE específicas del objeto para los tipos de objeto que no aparecen en la matriz ObjectTypeList . Por lo tanto, los resultados devueltos para el elemento cero en el parámetro AccessStatusList indican el acceso permitido al subconjunto del objeto definido por el parámetro ObjectTypeList , no al objeto completo.

Para obtener más información sobre cómo una jerarquía de ASE controla el acceso a un objeto y sus subobjetos, vea ACA para controlar el acceso a las propiedades de un objeto.

Si la lista de control de acceso discrecional (DACL) del descriptor de seguridad es NULL, la función concede el acceso solicitado a todos los elementos de la lista de tipos de objeto.

Si el descriptor de seguridad no contiene SID de propietario y grupo, AccessCheckByTypeResultList produce un error con ERROR_INVALID_SECURITY_DESCR.

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