Função PsImpersonateClient (ntifs.h)

  • Artigo

A rotina PsImpersonateClient faz com que um thread de servidor represente um cliente.

Sintaxe

NTSTATUS PsImpersonateClient(
  [in, out] PETHREAD                     Thread,
  [in]      PACCESS_TOKEN                Token,
  [in]      BOOLEAN                      CopyOnOpen,
  [in]      BOOLEAN                      EffectiveOnly,
  [in]      SECURITY_IMPERSONATION_LEVEL ImpersonationLevel
);

Parâmetros

[in, out] Thread

Ponteiro para o thread do servidor que deve representar o cliente.

[in] Token

Ponteiro para o token a ser atribuído como o token de representação. Esse token pode ser um token primário ou um token de representação. Defina como NULL para encerrar a representação.

[in] CopyOnOpen

Especifica se o token pode ser aberto diretamente. Defina como TRUE para especificar que o token não pode ser aberto diretamente. Nesse caso, o token deve ser duplicado e o token duplicado usado. Defina como FALSE para permitir que o token seja aberto diretamente.

[in] EffectiveOnly

Defina como FALSE para permitir que o servidor habilite grupos e privilégios que estão desabilitados no contexto de segurança do cliente, caso contrário, TRUE .

[in] ImpersonationLevel

Um valor SECURITY_IMPERSONATION_LEVEL que especifica o nível de representação no qual o servidor deve acessar o token.

Retornar valor

PsImpersonateClient retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado, como o seguinte:

Código de retorno Descrição
STATUS_ACCESS_DENIED
 Não foi possível representar um cliente devido a restrições de trabalho.
STATUS_NO_MEMORY
 Não havia memória suficiente para concluir a operação.

Comentários

PsImpersonateClient faz com que o thread de servidor especificado represente o cliente especificado.

O thread do servidor já pode estar representando um cliente quando PsImpersonateClient é chamado. Se esse for o caso, a contagem de referência no token que representa esse cliente será decrementada. Para preservar esse token para uso posterior, os drivers devem chamar PsReferenceImpersonationToken antes de chamar PsImpersonateClient e salvar o ponteiro retornado por PsReferenceImpersonationToken.

Para encerrar a nova representação e retornar o thread do servidor para a representação anterior, chame PsImpersonateClient novamente, passando o ponteiro salvo para o parâmetro Token . Para encerrar todas as representações, chame a rotina PsRevertToSelf .

Caso contrário, para encerrar a representação e retornar o thread do servidor para seu contexto de segurança original (ou seja, aquele representado por seu token primário), chame PsImpersonateClient novamente, passando um ponteiro NULL para o parâmetro Token .

A rotina PsImpersonateClient poderá falhar ao retornar com êxito o thread do servidor para a representação anterior se o thread já estiver representando ou houver restrições de trabalho.

A rotina garante se a representação do cliente pode realmente ocorrer verificando várias condições, incluindo as seguintes:

  • O token passado pelo chamador não tem uma ID de autenticação anônima
  • O token do processo referenciado do thread do servidor e o token fornecido têm SIDs (identificadores de segurança) iguais
  • Nenhum dos tokens é restrito

Se nenhuma das condições for atendida, a rotina fará uma cópia do token existente passado para a chamada e atribuirá o token recém-copiado como token de representação, embora com nível de representação de segurança limitado; ou seja, o thread do servidor só pode obter informações sobre o cliente. Se a cópia de token não for possível, a rotina falhará com um código NTSTATUS.

É extremamente inseguro gerar o estado de privilégio de um thread de usuário não confiável (pegue o thread de um usuário e represente LocalSystem, por exemplo). Se um thread de usuário não confiável tiver seu privilégio gerado, o usuário poderá pegar o token de thread depois de ter sido elevado e subverter a segurança de todo o sistema.

Nos casos em que um estado de privilégio mais alto é necessário, a tarefa deve ser enviada para uma fila de trabalho em que a tarefa pode ser tratada com segurança pelo thread de trabalho do sistema . Dessa forma, nenhuma representação é necessária.

A rotina SeImpersonateClientEx pode ser usada para fazer com que um thread represente um usuário.

Para obter mais informações sobre segurança e controle de acesso, consulte Modelo de segurança do Windows para desenvolvedores de driver e a documentação sobre esses tópicos no SDK do Windows.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP
Plataforma de Destino Universal
Cabeçalho ntifs.h (inclua Ntifs.h)
Biblioteca NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
Regras de conformidade de DDI HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)

Confira também

PsGetCurrentThread

PsReferenceImpersonationToken

PsRevertToSelf

SECURITY_IMPERSONATION_LEVEL

SeImpersonateClientEx