Função PsImpersonateClient (ntifs.h)
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 |
|---|---|
|
Não foi possível representar um cliente devido a restrições de trabalho. |
|
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) |