Compartilhar via


Função AccessCheckByTypeAndAuditAlarmA (winbase.h)

A função AccessCheckByTypeAndAuditAlarm determina se um descritor de segurança concede um conjunto especificado de direitos de acesso ao cliente que está sendo representado pelo thread de chamada. A função pode marcar o acesso do cliente a uma hierarquia de objetos, como um objeto, seus conjuntos de propriedades e propriedades. A função concede ou nega acesso à hierarquia como um todo. Se o descritor de segurança tiver uma SACL ( lista de controle de acesso do sistema ) com ACEs (entradas de controle de acesso ) que se aplicam ao cliente, a função gerará todas as mensagens de auditoria necessárias no log de eventos de segurança.

Atualmente, não há suporte para alarmes.

Sintaxe

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

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do subsistema que chama a função. Essa cadeia de caracteres aparece em qualquer mensagem de auditoria gerada pela função.

[in] HandleId

Um ponteiro para um valor exclusivo que representa o identificador do cliente para o objeto . Se o acesso for negado, o sistema ignorará esse valor.

[in] ObjectTypeName

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o tipo de objeto que está sendo criado ou acessado. Essa cadeia de caracteres aparece em qualquer mensagem de auditoria gerada pela função.

[in, optional] ObjectName

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do objeto que está sendo criado ou acessado. Essa cadeia de caracteres aparece em qualquer mensagem de auditoria gerada pela função.

[in] SecurityDescriptor

Um ponteiro para uma estrutura de SECURITY_DESCRIPTOR na qual o acesso é verificado.

[in, optional] PrincipalSelfSid

Um ponteiro para um SID ( identificador de segurança ). Se o descritor de segurança estiver associado a um objeto que representa uma entidade de segurança (por exemplo, um objeto de usuário), o parâmetro PrincipalSelfSid deverá ser o SID do objeto. Ao avaliar o acesso, esse SID substitui logicamente o SID em qualquer ACE que contenha o sid PRINCIPAL_SELF conhecido (S-1-5-10). Para obter informações sobre SIDs conhecidos, consulte SIDs conhecidos.

Se o objeto protegido não representar uma entidade de segurança, defina esse parâmetro como NULL.

[in] DesiredAccess

Uma máscara de acesso que especifica os direitos de acesso para marcar. Essa máscara deve ter sido mapeada pela função MapGenericMask para não conter direitos de acesso genéricos.

Se esse parâmetro for MAXIMUM_ALLOWED, a função definirá a máscara de acesso GrantedAccess para indicar os direitos máximos de acesso que o descritor de segurança permite ao cliente.

[in] AuditType

O tipo de auditoria a ser gerado. Esse pode ser um dos valores do tipo de enumeração AUDIT_EVENT_TYPE .

[in] Flags

Um sinalizador que controla o comportamento da função se o processo de chamada não tiver o privilégio SE_AUDIT_NAME habilitado. Se o sinalizador AUDIT_ALLOW_NO_PRIVILEGE estiver definido, a função executará o marcar de acesso sem gerar mensagens de auditoria quando o privilégio não estiver habilitado. Se esse parâmetro for zero, a função falhará se o privilégio não estiver habilitado.

[in, out, optional] ObjectTypeList

Um ponteiro para uma matriz de estruturas de OBJECT_TYPE_LIST que identificam a hierarquia de tipos de objeto para os quais marcar acesso. Cada elemento na matriz especifica um GUID que identifica o tipo de objeto e um valor que indica o nível do tipo de objeto na hierarquia de tipos de objeto. A matriz não deve ter dois elementos com o mesmo GUID.

A matriz deve ter pelo menos um elemento. O primeiro elemento na matriz deve estar no nível zero e identificar o próprio objeto. A matriz pode ter apenas um elemento de nível zero. O segundo elemento é um subobjeto, como um conjunto de propriedades, no nível 1. Seguindo cada entrada de nível 1 estão entradas subordinadas para os subobjetos de nível 2 a 4. Assim, os níveis para os elementos na matriz podem ser {0, 1, 2, 2, 1, 2, 3}. Se a lista de tipos de objeto estiver fora de ordem, AccessCheckByTypeAndAuditAlarm falhará e GetLastError retornará ERROR_INVALID_PARAMETER.

[in] ObjectTypeListLength

O número de elementos na matriz ObjectTypeList .

[in] GenericMapping

Um ponteiro para a estrutura GENERIC_MAPPING associada ao objeto para o qual o acesso está sendo verificado.

[in] ObjectCreation

Um sinalizador que determina se o aplicativo de chamada criará um novo objeto quando o acesso for concedido. Um valor true indica que o aplicativo criará um novo objeto. Um valor false indica que o aplicativo abrirá um objeto existente.

[out] GrantedAccess

Um ponteiro para uma máscara de acesso que recebe os direitos de acesso concedidos. Se AccessStatus estiver definido como FALSE, a função definirá a máscara de acesso como zero. Se a função falhar, ela não definirá a máscara de acesso.

[out] AccessStatus

Um ponteiro para uma variável que recebe os resultados da marcar de acesso. Se o descritor de segurança permitir os direitos de acesso solicitados ao cliente, AccessStatus será definido como TRUE. Caso contrário, AccessStatus será definido como FALSE e você poderá chamar GetLastError para obter informações de erro estendidas.

[out] pfGenerateOnClose

Um ponteiro para um sinalizador definido pela rotina de geração de auditoria quando a função retorna. Passe esse sinalizador para a função ObjectCloseAuditAlarm quando o identificador do objeto for fechado.

Valor retornado

Se a função for bem-sucedida, a função retornará diferente de zero.

Se a função falhar, ela retornará zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Para obter mais informações, consulte a visão geral como o AccessCheck funciona .

Se os parâmetros PrincipalSelfSid e ObjectTypeList forem NULL, o parâmetro AuditType será AuditEventObjectAccess e o parâmetro Flags for zero, AccessCheckByTypeAndAuditAlarm será executado da mesma forma que a função AccessCheckAndAuditAlarm .

A matriz ObjectTypeList não representa necessariamente todo o objeto definido. Em vez disso, ele representa esse subconjunto do objeto para o qual marcar acesso. Por exemplo, para marcar acesso a duas propriedades em um conjunto de propriedades, especifique uma lista de tipos de objeto com quatro elementos: o próprio objeto no nível zero, a propriedade definida no nível 1 e as duas propriedades no nível 2.

A função AccessCheckByTypeAndAuditAlarm avalia ACEs que se aplicam ao próprio objeto e ACEs específicos do objeto para os tipos de objeto listados na matriz ObjectTypeList . A função ignora ACEs específicos do objeto para tipos de objeto não listados na matriz ObjectTypeList . Assim, os resultados retornados no parâmetro AccessStatus indicam o acesso permitido ao subconjunto do objeto definido pelo parâmetro ObjectTypeList , não ao objeto inteiro.

Para obter mais informações sobre como uma hierarquia de ACEs controla o acesso a um objeto e seus subobjetos, consulte ACEs para controlar o acesso às propriedades de um objeto.

Para gerar mensagens de auditoria no log de eventos de segurança, o processo de chamada deve ter o privilégio SE_AUDIT_NAME habilitado. O sistema verifica esse privilégio no token primário do processo de chamada, não o token de representação do thread. Se o parâmetro Flags incluir o sinalizador AUDIT_ALLOW_NO_PRIVILEGE, a função executará o marcar de acesso sem gerar mensagens de auditoria quando o privilégio não estiver habilitado.

A função AccessCheckByTypeAndAuditAlarm falhará se o thread de chamada não estiver representando um cliente.

Se o descritor de segurança não contiver SIDs de proprietário e grupo, AccessCheckByTypeAndAuditAlarm falhará com ERROR_INVALID_SECURITY_DESCR.

Requisitos

   
Cliente mínimo com suporte Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho winbase.h (inclua Windows.h)
Biblioteca Advapi32.lib
DLL Advapi32.dll

Confira também

AUDIT_EVENT_TYPE

AccessCheck

AccessCheckAndAuditAlarm

AccessCheckByType

AccessCheckByTypeResultList

AccessCheckByTypeResultListAndAuditAlarm

Controle de Acesso cliente/servidor

Funções de Controle de Acesso de cliente/servidor

GENERIC_MAPPING

Como o AccessCheck funciona

MakeAbsoluteSD

MapGenericMask

OBJECT_TYPE_LIST

ObjectCloseAuditAlarm

PRIVILEGE_SET

SECURITY_DESCRIPTOR