Função BuildSecurityDescriptorA (aclapi.h)

Artigo
11/20/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 BuildSecurityDescriptorA(
  [in, optional] PTRUSTEE_A           pOwner,
  [in, optional] PTRUSTEE_A           pGroup,
  [in]           ULONG                cCountOfAccessEntries,
  [in, optional] PEXPLICIT_ACCESS_A   pListOfAccessEntries,
  [in]           ULONG                cCountOfAuditEntries,
  [in, optional] PEXPLICIT_ACCESS_A   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 ( de identificador de segurança) associado ao nome do administrador especificado.

Se esse parâmetro for NULL, a função usará o SID proprietário do descritor de segurança original apontado por pOldSD. Se pOldSD estiver NULL ou se o SID proprietário em pOldSD for NULL, o SID 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 do 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 lista de controle de acesso discricionário (DACL) 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 o DACL em pOldSD for NULL, a função criará um novo 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 de EXPLICIT_ACCESS, consulte a função SetEntriesInAcl.

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

[in] cCountOfAuditEntries

O número de estruturas de EXPLICIT_ACCESS na matriz pListOfAuditEntries .

[in, optional] pListOfAuditEntries

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

Se pListOfAuditEntries for NULL, o novo descritor de segurança obterá o SACL de pOldSD. Nesse caso, se pOldSD for NULL ou o SACL em pOldSD for NULL, o novo 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. Esse 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.

Valor de retorno

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.

Observações

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.

Nota

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. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2003 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	aclapi.h
biblioteca	Advapi32.lib
de DLL	Advapi32.dll