Função BuildSecurityDescriptorW (aclapi.h)

Artigo
02/26/2024

A função BuildSecurityDescriptor aloca e inicializa um novo descritor de segurança. Essa função pode inicializar o novo descritor de segurança mesclando informações de segurança especificadas com as informações em um descritor de segurança existente. Se você não especificar um descritor de segurança existente, a função inicializará um novo descritor de segurança com base nas informações de segurança especificadas.

A função BuildSecurityDescriptor cria um descritor de segurança auto-relativo. O formato auto-relativo torna o descritor de segurança adequado para armazenar em um fluxo.

Sintaxe

DWORD BuildSecurityDescriptorW(
  [in, optional] PTRUSTEE_W           pOwner,
  [in, optional] PTRUSTEE_W           pGroup,
  [in]           ULONG                cCountOfAccessEntries,
  [in, optional] PEXPLICIT_ACCESS_W   pListOfAccessEntries,
  [in]           ULONG                cCountOfAuditEntries,
  [in, optional] PEXPLICIT_ACCESS_W   pListOfAuditEntries,
  [in, optional] PSECURITY_DESCRIPTOR pOldSD,
  [out]          PULONG               pSizeNewSD,
  [out]          PSECURITY_DESCRIPTOR *pNewSD
);

Parâmetros

[in, optional] pOwner

Um ponteiro para uma estrutura TRUSTEE que identifica o proprietário do novo descritor de segurança. Se a estrutura usar o formulário TRUSTEE_IS_NAME, BuildSecurityDescriptor procurará o SID ( identificador de segurança ) associado ao nome do objeto de confiança especificado.

Se esse parâmetro for NULL, a função usará o SID do proprietário do descritor de segurança original apontado por pOldSD. Se pOldSD for NULL ou se o SID do proprietário em pOldSD for NULL, o SID do proprietário será NULL no novo descritor de segurança.

[in, optional] pGroup

Um ponteiro para uma estrutura TRUSTEE que identifica o SID do grupo primário para o novo descritor de segurança. Se a estrutura usar o formulário TRUSTEE_IS_NAME, BuildSecurityDescriptor procurará o SID associado ao nome de administrador especificado.

Se esse parâmetro for NULL, a função usará o SID do grupo do descritor de segurança original apontado por pOldSD. Se pOldSD for NULL ou se o SID do grupo em pOldSD for NULL, o SID do grupo será NULL no novo descritor de segurança.

[in] cCountOfAccessEntries

O número de estruturas EXPLICIT_ACCESS na matriz pListOfAccessEntries .

[in, optional] pListOfAccessEntries

Um ponteiro para uma matriz de estruturas de EXPLICIT_ACCESS que descrevem informações de controle de acesso para a DACL ( lista de controle de acesso discricionário ) do novo descritor de segurança. A função cria a nova DACL mesclando as informações na matriz com a DACL em pOldSD, se houver. Se pOldSD for NULL ou se a DACL em pOldSD for NULL, a função criará uma nova DACL com base apenas nas informações na matriz. Para obter uma descrição das regras para criar uma ACL de uma matriz de estruturas EXPLICIT_ACCESS , consulte a função SetEntriesInAcl .

Se pListOfAccessEntries for NULL, o novo descritor de segurança obterá a DACL de pOldSD. Nesse caso, se pOldSD for NULL ou se a DACL em pOldSD for NULL, a nova DACL será NULL.

[in] cCountOfAuditEntries

O número de estruturas EXPLICIT_ACCESS na matriz pListOfAuditEntries .

[in, optional] pListOfAuditEntries

Um ponteiro para uma matriz de estruturas de EXPLICIT_ACCESS que descrevem informações de controle de auditoria para a SACL do novo descritor de segurança. A função cria a nova SACL mesclando as informações na matriz com a SACL em pOldSD, se houver. Se pOldSD for NULL ou a SACL em pOldSD for NULL, a função criará uma nova SACL com base apenas nas informações na matriz.

Se pListOfAuditEntries for NULL, o novo descritor de segurança obterá a SACL de pOldSD. Nesse caso, se pOldSD for NULL ou a SACL em pOldSD for NULL, a nova SACL será NULL.

[in, optional] pOldSD

Um ponteiro para uma estrutura de SECURITY_DESCRIPTOR auto-relativa existente e suas informações de segurança associadas. A função cria o novo descritor de segurança mesclando o proprietário, o grupo, o controle de acesso e as informações de controle de auditoria especificados com as informações neste descritor de segurança. Este parâmetro pode ser NULL.

[out] pSizeNewSD

Um ponteiro para uma variável que recebe o tamanho, em bytes, do descritor de segurança.

[out] pNewSD

Um ponteiro para uma variável que recebe um ponteiro para o novo descritor de segurança. A função aloca memória para o novo descritor de segurança. Você deve chamar a função LocalFree para liberar o buffer retornado.

Retornar valor

Se a função for bem-sucedida, a função retornará ERROR_SUCCESS.

Se a função falhar, ela retornará um código de erro diferente de zero definido em WinError.h.

Comentários

A função BuildSecurityDescriptor destina-se a servidores confiáveis que implementam ou expõem a segurança em seus próprios objetos. A função usa descritores de segurança auto-relativos adequados para serialização em um fluxo e armazenamento em disco, como um servidor confiável pode exigir.

Observação

O cabeçalho aclapi.h define BuildSecurityDescriptor como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
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	aclapi.h
Biblioteca	Advapi32.lib
DLL	Advapi32.dll