Función AccessCheckByType (securitybaseapi.h)

Artículo
03/15/2023

La función AccessCheckByType 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 concede o deniega el acceso a la jerarquía en su conjunto. Normalmente, las aplicaciones de servidor usan esta función para comprobar el acceso a un objeto privado.

Sintaxis

BOOL AccessCheckByType(
  [in]                PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in, optional]      PSID                 PrincipalSelfSid,
  [in]                HANDLE               ClientToken,
  [in]                DWORD                DesiredAccess,
  [in, out, optional] POBJECT_TYPE_LIST    ObjectTypeList,
  [in]                DWORD                ObjectTypeListLength,
  [in]                PGENERIC_MAPPING     GenericMapping,
  [out, optional]     PPRIVILEGE_SET       PrivilegeSet,
  [in, out]           LPDWORD              PrivilegeSetLength,
  [out]               LPDWORD              GrantedAccess,
  [out]               LPBOOL               AccessStatus
);

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 que contenga el SID de PRINCIPAL_SELF conocido (S-1-5-10). Para obtener información sobre los SID conocidos, consulte SID conocidos.

Establezca este parámetro en NULL si el objeto protegido no representa una entidad de seguridad.

[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 la máscara de acceso de GrantedAccess para indicar los derechos de acceso máximos que permite el cliente.

[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, AccessCheckByType produce un error y GetLastError devuelve ERROR_INVALID_PARAMETER.

Si ObjectTypeList es NULL, AccessCheckByType es el mismo que la función AccessCheck .

[in] ObjectTypeListLength

Especifica el número de elementos de la matriz ObjectTypeList .

[in] GenericMapping

Puntero a la estructura GENERIC_MAPPING asociada al objeto para el que se comprueba el acceso. El miembro GenericAll de la estructura GENERIC_MAPPING debe contener todos los derechos de acceso que puede conceder el administrador de recursos, incluidos STANDARD_RIGHTS_ALL y todos los derechos establecidos en los miembros GenericRead, GenericWrite y GenericExecute .

[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

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

[out] GrantedAccess

Puntero a una máscara de acceso que recibe los derechos de acceso concedidos. Si AccessStatus se establece en FALSE, la función establece la máscara de acceso en cero. Si se produce un error en la función, no establece la máscara de acceso.

[out] AccessStatus

Puntero a una variable que recibe los resultados de la comprobación de acceso. Si el descriptor de seguridad permite los derechos de acceso solicitados al cliente identificado por el token de acceso, AccessStatus se establece en TRUE. De lo contrario, AccessStatus se establece en FALSE y puede llamar a GetLastError para obtener información de error extendida.

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

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

La función AccessCheckByType compara el descriptor de seguridad especificado con el token de acceso especificado e indica, en el parámetro AccessStatus , si se concede o se deniega el acceso.

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 AccessCheckByType 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 en el parámetro AccessStatus 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 DACL del descriptor de seguridad es NULL, el parámetro AccessStatus devuelve TRUE, lo que indica que el cliente tiene el acceso solicitado.

Si el descriptor de seguridad no contiene SID de propietario y grupo, AccessCheckByType 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