Función AccessCheckByTypeAndAuditAlarmA (winbase.h)

Artículo
03/08/2023

La función AccessCheckByTypeAndAuditAlarm determina si un descriptor de seguridad concede un conjunto especificado de derechos de acceso al cliente suplantado por el subproceso que realiza la llamada. 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. Si el descriptor de seguridad tiene una lista de control de acceso del sistema (SACL) con entradas de control de acceso (ACE) que se aplican al cliente, la función genera los mensajes de auditoría necesarios en el registro de eventos de seguridad.

Actualmente no se admiten alarmas.

Sintaxis

BOOL AccessCheckByTypeAndAuditAlarmA(
  [in]                LPCSTR               SubsystemName,
  [in]                LPVOID               HandleId,
  [in]                LPCSTR               ObjectTypeName,
  [in, optional]      LPCSTR               ObjectName,
  [in]                PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in, optional]      PSID                 PrincipalSelfSid,
  [in]                DWORD                DesiredAccess,
  [in]                AUDIT_EVENT_TYPE     AuditType,
  [in]                DWORD                Flags,
  [in, out, optional] POBJECT_TYPE_LIST    ObjectTypeList,
  [in]                DWORD                ObjectTypeListLength,
  [in]                PGENERIC_MAPPING     GenericMapping,
  [in]                BOOL                 ObjectCreation,
  [out]               LPDWORD              GrantedAccess,
  [out]               LPBOOL               AccessStatus,
  [out]               LPBOOL               pfGenerateOnClose
);

Parámetros

[in] SubsystemName

Puntero a una cadena terminada en null que especifica el nombre del subsistema que llama a la función. Esta cadena aparece en cualquier mensaje de auditoría que genere la función.

[in] HandleId

Puntero a un valor único que representa el identificador del cliente para el objeto . Si se deniega el acceso, el sistema omite este valor.

[in] ObjectTypeName

Puntero a una cadena terminada en null que especifica el tipo de objeto que se crea o se accede a él. Esta cadena aparece en cualquier mensaje de auditoría que genere la función.

[in, optional] ObjectName

Puntero a una cadena terminada en null que especifica el nombre del objeto al que se va a crear o tener acceso. Esta cadena aparece en cualquier mensaje de auditoría que genere la función.

[in] SecurityDescriptor

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 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] 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] AuditType

Tipo de auditoría que se va a generar. Puede ser uno de los valores del tipo de enumeración AUDIT_EVENT_TYPE .

[in] Flags

Marca que controla el comportamiento de la función si el proceso de llamada no tiene habilitado el privilegio SE_AUDIT_NAME. Si se establece la marca AUDIT_ALLOW_NO_PRIVILEGE, la función realiza la comprobación de acceso sin generar mensajes de auditoría cuando el privilegio no está habilitado. Si este parámetro es cero, se produce un error en la función si el privilegio no está habilitado.

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

[in] ObjectTypeListLength

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.

[in] ObjectCreation

Marca que determina si la aplicación que realiza la llamada creará un nuevo objeto cuando se conceda acceso. Un valor de TRUE indica que la aplicación creará un nuevo objeto. Un valor false indica que la aplicación abrirá un objeto existente.

[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, 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.

[out] pfGenerateOnClose

Puntero a una marca establecida por la rutina de generación de auditoría cuando la función devuelve. Pase esta marca a la función ObjectCloseAuditAlarm cuando se cierre el identificador del objeto.

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 .

Si los parámetros PrincipalSelfSid y ObjectTypeList son NULL, el parámetro AuditType es AuditEventObjectAccess y el parámetro Flags es cero, AccessCheckByTypeAndAuditAlarm realiza de la misma manera que la función AccessCheckAndAuditAlarm.

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 AccessCheckByTypeAndAuditAlarm evalúa las ACE 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.

Para generar mensajes de auditoría en el registro de eventos de seguridad, el proceso de llamada debe tener habilitado el privilegio SE_AUDIT_NAME. El sistema comprueba este privilegio en el token principal del proceso de llamada, no el token de suplantación del subproceso . Si el parámetro Flags incluye la marca AUDIT_ALLOW_NO_PRIVILEGE, la función realiza la comprobación de acceso sin generar mensajes de auditoría cuando el privilegio no está habilitado.

Se produce un error en la función AccessCheckByTypeAndAuditAlarm si el subproceso que realiza la llamada no suplanta a un cliente.

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

Requisitos


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	winbase.h (incluya Windows.h)
Library	Advapi32.lib
Archivo DLL	Advapi32.dll