Función AccessCheck (securitybaseapi.h)

Artículo
03/15/2023

La función AccessCheck determina si un descriptor de seguridad concede un conjunto especificado de derechos de acceso al cliente identificado por un token de acceso. Normalmente, las aplicaciones de servidor usan esta función para comprobar el acceso a un objeto privado.

Sintaxis

BOOL AccessCheck(
  [in]            PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in]            HANDLE               ClientToken,
  [in]            DWORD                DesiredAccess,
  [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 SECURITY_DESCRIPTOR en la que se comprueba el acceso.

[in] ClientToken

Identificador de un token de suplantación que representa el 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 GrantedAccess para indicar los derechos de acceso máximos que el descriptor de seguridad permite al cliente.

[in] GenericMapping

Puntero a la estructura de 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

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 AccessCheck 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. Si se concede acceso, la máscara de acceso solicitada se convierte en la máscara de acceso concedida del 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.

Se produce un error en la función AccessCheck con ERROR_INVALID_SECURITY_DESCR si el descriptor de seguridad no contiene SID de propietario y grupo.

La función AccessCheck no genera una auditoría. Si la aplicación requiere auditorías para comprobaciones de acceso, use funciones como AccessCheckAndAuditAlarm, AccessCheckByTypeAndAuditAlarm, AccessCheckByTypeResultListAndAuditAlarm o AccessCheckByTypeResultListResultListAndAuditAlarmByHandle, en lugar de AccessCheck.

Ejemplos

Para obtener un ejemplo que usa esta función, consulte Comprobación del acceso de cliente con ACL.

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