Classe CAccessToken

Essa classe é um wrapper para um token de acesso.

Importante

Essa classe e os respectivos membros não podem ser usados em aplicativos executados no Windows Runtime.

Sintaxe

class CAccessToken

Membros

Construtores públicos

Nome	Descrição
CAccessToken::~CAccessToken	O destruidor.

Métodos públicos

Nome	Descrição
CAccessToken::Attach	Chame esse método para assumir a propriedade do identificador de token de acesso fornecido.
CAccessToken::CheckTokenMembership	Chame esse método para determinar se um SID (identificador de segurança) especificado está habilitado no objeto CAccessToken.
CAccessToken::CreateImpersonationToken	Chame esse método para criar um novo token de acesso de representação.
CAccessToken::CreatePrimaryToken	Chame esse método para criar um novo token primário.
CAccessToken::CreateProcessAsUser	Chame esse método para criar um novo processo em execução no contexto de segurança do usuário representado pelo objeto CAccessToken.
CAccessToken::CreateRestrictedToken	Chame esse método para criar um objeto CAccessToken novo e restrito.
CAccessToken::Detach	Chame esse método para revogar a propriedade do token de acesso.
CAccessToken::DisablePrivilege	Chame esse método para desabilitar um privilégio no objeto CAccessToken.
CAccessToken::DisablePrivileges	Chame esse método para desabilitar um ou mais privilégios no objeto CAccessToken.
CAccessToken::EnablePrivilege	Chame esse método para habilitar um privilégio no objeto CAccessToken.
CAccessToken::EnablePrivileges	Chame esse método para habilitar um ou mais privilégios no objeto CAccessToken.
CAccessToken::GetDefaultDacl	Chame esse método para retornar a DACL padrão do objeto CAccessToken.
CAccessToken::GetEffectiveToken	Chame esse método para obter o objeto CAccessToken igual ao token de acesso em vigor para o thread atual.
CAccessToken::GetGroups	Chame esse método para retornar os grupos de tokens do objeto CAccessToken.
CAccessToken::GetHandle	Chame esse método para recuperar um identificador para o token de acesso.
CAccessToken::GetImpersonationLevel	Chame esse método para obter o nível de representação do token de acesso.
CAccessToken::GetLogonSessionId	Chame esse método para obter a ID da sessão de logon associada ao objeto CAccessToken.
CAccessToken::GetLogonSid	Chame esse método para obter o SID de logon associado ao objeto CAccessToken.
CAccessToken::GetOwner	Chame esse método para obter o proprietário associado ao objeto CAccessToken.
CAccessToken::GetPrimaryGroup	Chame esse método para obter o grupo primário associado ao objeto CAccessToken.
CAccessToken::GetPrivileges	Chame esse método para obter os privilégios associados ao objeto CAccessToken.
CAccessToken::GetProcessToken	Chame esse método para inicializar o CAccessToken com o token de acesso do processo fornecido.
CAccessToken::GetProfile	Chame esse método para obter o identificador apontando para o perfil de usuário associado ao objeto CAccessToken.
CAccessToken::GetSource	Chame esse método para obter a origem do objeto CAccessToken.
CAccessToken::GetStatistics	Chame esse método para obter informações associadas ao objeto CAccessToken.
CAccessToken::GetTerminalServicesSessionId	Chame esse método para obter a ID de sessão dos serviços de terminal associada ao objeto CAccessToken.
CAccessToken::GetThreadToken	Chame esse método para inicializar o CAccessToken com o token do thread fornecido.
CAccessToken::GetTokenId	Chame esse método para obter a ID do token associada ao objeto CAccessToken.
CAccessToken::GetType	Chame esse método para obter o tipo de token do objeto CAccessToken.
CAccessToken::GetUser	Chame esse método para identificar o usuário associado ao objeto CAccessToken.
CAccessToken::HKeyCurrentUser	Chame esse método para obter o identificador apontando para o perfil de usuário associado ao objeto CAccessToken.
CAccessToken::Impersonate	Chame esse método para atribuir uma representação CAccessToken a um thread.
CAccessToken::ImpersonateLoggedOnUser	Chame esse método para permitir que o thread de chamada represente o contexto de segurança de um usuário conectado.
CAccessToken::IsTokenRestricted	Chame esse método para testar se o objeto CAccessToken contém uma lista de SIDs restritos.
CAccessToken::LoadUserProfile	Chame esse método para carregar o perfil de usuário associado ao objeto CAccessToken.
CAccessToken::LogonUser	Chame esse método para criar uma sessão de logon para o usuário associado às credenciais fornecidas.
CAccessToken::OpenCOMClientToken	Chame esse método de dentro de um servidor COM que está tratando uma chamada de um cliente para inicializar o CAccessToken com o token de acesso do cliente COM.
CAccessToken::OpenNamedPipeClientToken	Chame esse método de dentro de um servidor que recebe solicitações em um pipe nomeado para inicializar o CAccessToken com o token de acesso do cliente.
CAccessToken::OpenRPCClientToken	Chame esse método de dentro de um servidor que está tratando uma chamada de um cliente RPC para inicializar o CAccessToken com o token de acesso do cliente.
CAccessToken::OpenThreadToken	Chame esse método para definir o nível de representação e, em seguida, inicialize o CAccessToken com o token do thread fornecido.
CAccessToken::PrivilegeCheck	Chame esse método para determinar se um conjunto especificado de privilégios está habilitado no objeto CAccessToken.
CAccessToken::Revert	Chame esse método para interromper um thread que esteja usando um token de representação.
CAccessToken::SetDefaultDacl	Chame esse método para definir a DACL padrão do objeto CAccessToken.
CAccessToken::SetOwner	Chame esse método para definir o proprietário do objeto CAccessToken.
CAccessToken::SetPrimaryGroup	Chame esse método para definir o grupo primário do objeto CAccessToken.

Comentários

Um token de acesso é um objeto que descreve o contexto de segurança de um processo ou thread e é alocado para cada usuário conectado a um sistema Windows.

Para ver uma introdução ao modelo de controle de acesso no Windows, confira Controle de Acesso no SDK do Windows.

Requisitos

Cabeçalho: atlsecurity.h

CAccessToken::Attach

Chame esse método para assumir a propriedade do identificador de token de acesso fornecido.

void Attach(HANDLE hToken) throw();

Parâmetros

hToken
Um identificador para o token de acesso.

Comentários

Em builds de depuração, ocorrerá um erro de declaração caso o objeto CAccessToken já tenha a propriedade de um token de acesso.

CAccessToken::~CAccessToken

O destruidor.

virtual ~CAccessToken() throw();

Comentários

Libera todos os recursos alocados.

CAccessToken::CheckTokenMembership

Chame esse método para determinar se um SID (identificador de segurança) especificado está habilitado no objeto CAccessToken.

bool CheckTokenMembership(
    const CSid& rSid,
    bool* pbIsMember) const throw(...);

Parâmetros

rSid
Referência a um objeto Classe CSid.

pbIsMember
Ponteiro para uma variável que recebe os resultados da verificação.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

O método CheckTokenMembership verifica a presença do SID nos SIDs de usuário e de grupo do token de acesso. Se o SID estiver presente e tiver o atributo SE_GROUP_ENABLED, o pbIsMember será definido como TRUE; caso contrário, ele será definido como FALSE.

Em builds de depuração, ocorrerá um erro de declaração caso o pbIsMember não seja um ponteiro válido.

Observação

O objeto CAccessToken deve ser um token de representação e não um token primário.

CAccessToken::CreateImpersonationToken

Chame esse método para criar um token de acesso de representação.

bool CreateImpersonationToken(
    CAccessToken* pImp,
    SECURITY_IMPERSONATION_LEVEL sil = SecurityImpersonation) const throw(...);

Parâmetros

pImp
Ponteiro para o novo objeto CAccessToken.

sil
Especifica um tipo enumerado SECURITY_IMPERSONATION_LEVEL que fornece o nível de representação do novo token.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

CreateImpersonationToken chama o DuplicateToken para criar um novo token de representação.

CAccessToken::CreatePrimaryToken

Chame esse método para criar um novo token primário.

bool CreatePrimaryToken(
    CAccessToken* pPri,
    DWORD dwDesiredAccess = MAXIMUM_ALLOWED,
    const CSecurityAttributes* pTokenAttributes = NULL) const throw(...);

Parâmetros

pPri
Ponteiro para o novo objeto CAccessToken.

dwDesiredAccess
Especifica os direitos de acesso solicitados para o novo token. O padrão MAXIMUM_ALLOWED solicita todos os direitos de acesso válidos para o chamador. Confira Direitos de acesso e máscaras de acesso para obter mais informações sobre direitos de acesso.

pTokenAttributes
Ponteiro para uma estrutura SECURITY_ATTRIBUTES que especifica um descritor de segurança para o novo token e determina se os processos filho podem herdar o token. Se o pTokenAttributes for NULL, o token obterá um descritor de segurança padrão, e o identificador não poderá ser herdado.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

CreatePrimaryToken chama o DuplicateTokenEx para criar um novo token primário.

CAccessToken::CreateProcessAsUser

Chame esse método para criar um novo processo em execução no contexto de segurança do usuário representado pelo objeto CAccessToken.

bool CreateProcessAsUser(
    LPCTSTR pApplicationName,
    LPTSTR pCommandLine,
    LPPROCESS_INFORMATION pProcessInformation,
    LPSTARTUPINFO pStartupInfo,
    DWORD dwCreationFlags = NORMAL_PRIORITY_CLASS,
    bool bLoadProfile = false,
    const CSecurityAttributes* pProcessAttributes = NULL,
    const CSecurityAttributes* pThreadAttributes = NULL,
    bool bInherit = false,
    LPCTSTR pCurrentDirectory = NULL) throw();

Parâmetros

pApplicationName
Ponteiro para uma cadeia de caracteres terminada em nulo que especifica o módulo a ser executado. Esse parâmetro pode não ser NULL.

pCommandLine
Ponteiro para uma cadeia de caracteres terminada em nulo que especifica a linha de comando a ser executada.

pProcessInformation
Ponteiro para uma estrutura PROCESS_INFORMATION que recebe informações de identificação sobre o novo processo.

pStartupInfo
Ponteiro para uma estrutura STARTUPINFO que especifica como a janela principal do novo processo deve aparecer.

dwCreationFlags
Especifica sinalizadores adicionais que controlam a classe de prioridade e a criação do processo. Confira a função CreateProcessAsUser do Win32 para obter uma lista de sinalizadores.

bLoadProfile
Se for TRUE, o perfil do usuário será carregado com LoadUserProfile.

pProcessAttributes
Ponteiro para uma estrutura SECURITY_ATTRIBUTES que especifica um descritor de segurança para o novo processo e determina se os processos filho podem herdar o identificador retornado. Se o pProcessAttributes for NULL, o processo obterá um descritor de segurança padrão, e o identificador não poderá ser herdado.

pThreadAttributes
Ponteiro para uma estrutura SECURITY_ATTRIBUTES que especifica um descritor de segurança para o novo thread e determina se os processos filho podem herdar o identificador retornado. Se o pThreadAttributes for NULL, o thread obterá um descritor de segurança padrão, e o identificador não poderá ser herdado.

bInherit
Indica se o novo processo herda identificadores do processo de chamada. Se for TRUE, cada identificador aberto herdável no processo de chamada será herdado pelo novo processo. Os identificadores herdados têm o mesmo valor e privilégios de acesso que os identificadores originais.

pCurrentDirectory
Ponteiro para uma cadeia de caracteres terminada em nulo que especifica a unidade e o diretório atuais do novo processo. A cadeia de caracteres deve ser um caminho completo que inclui uma letra da unidade. Se este parâmetro for NULL, o novo processo terá a mesma unidade e diretório atual que o processo de chamada.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

CreateProcessAsUser usa a função CreateProcessAsUser do Win32 para criar um novo processo que é executado no contexto de segurança do usuário representado pelo objeto CAccessToken. Confira a descrição da função CreateProcessAsUser para ver uma discussão completa sobre os parâmetros necessários.

Para que esse método tenha êxito, o objeto CAccessToken deve manter o AssignPrimaryToken (a menos que seja um token restrito) e os privilégios IncreaseQuota.

CAccessToken::CreateRestrictedToken

Chame esse método para criar um objeto CAccessToken novo e restrito.

bool CreateRestrictedToken(
    CAccessToken* pRestrictedToken,
    const CTokenGroups& SidsToDisable,
    const CTokenGroups& SidsToRestrict,
    const CTokenPrivileges& PrivilegesToDelete = CTokenPrivileges()) const throw(...);

Parâmetros

pRestrictedToken
O novo objeto restrito CAccessToken.

SidsToDisable
Um objeto CTokenGroups que especifica os SIDs somente negação.

SidsToRestrict
Um objeto CTokenGroups que especifica os SIDs restritivos.

PrivilegesToDelete
Um objeto CTokenPrivileges que especifica os privilégios a serem excluídos no token restrito. O padrão cria um objeto vazio.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

CreateRestrictedToken usa a função CreateRestrictedToken do Win32 para criar um novo objeto CAccessToken, com restrições.

Importante

Ao usar CreateRestrictedToken, garanta o seguinte: o token existente é válido (e não inserido pelo usuário) e tanto o SidsToDisable e quanto o PrivilegesToDelete são válidos (e não inseridos pelo usuário). Se o método retornar FALSE, negue a funcionalidade.

CAccessToken::Detach

Chame esse método para revogar a propriedade do token de acesso.

HANDLE Detach() throw();

Valor de retorno

Retorna o identificador para CAccessToken, o qual foi desanexado.

Comentários

Esse método revoga a propriedade de CAccessToken do token de acesso.

CAccessToken::DisablePrivilege

Chame esse método para desabilitar um privilégio no objeto CAccessToken.

bool DisablePrivilege(
    LPCTSTR pszPrivilege,
    CTokenPrivileges* pPreviousState = NULL) throw(...);

Parâmetros

pszPrivilege
Ponteiro para uma cadeia de caracteres que contém o privilégio de desabilitar no objeto CAccessToken.

pPreviousState
Ponteiro para um objeto CTokenPrivileges que conterá o estado anterior dos privilégios.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

CAccessToken::DisablePrivileges

Chame esse método para desabilitar um ou mais privilégios no objeto CAccessToken.

bool DisablePrivileges(
    const CAtlArray<LPCTSTR>& rPrivileges,
    CTokenPrivileges* pPreviousState = NULL) throw(...);

Parâmetros

rPrivileges
Ponteiro para uma matriz de cadeias de caracteres que contêm os privilégios a serem desabilitados no objeto CAccessToken.

pPreviousState
Ponteiro para um objeto CTokenPrivileges que conterá o estado anterior dos privilégios.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

CAccessToken::EnablePrivilege

Chame esse método para habilitar um privilégio no objeto CAccessToken.

bool EnablePrivilege(
    LPCTSTR pszPrivilege,
    CTokenPrivileges* pPreviousState = NULL) throw(...);

Parâmetros

pszPrivilege
Ponteiro para uma cadeia de caracteres que contém o privilégio de habilitar no objeto CAccessToken.

pPreviousState
Ponteiro para um objeto CTokenPrivileges que conterá o estado anterior dos privilégios.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

CAccessToken::EnablePrivileges

Chame esse método para habilitar um ou mais privilégios no objeto CAccessToken.

bool EnablePrivileges(
    const CAtlArray<LPCTSTR>& rPrivileges,
    CTokenPrivileges* pPreviousState = NULL) throw(...);

Parâmetros

rPrivileges
Ponteiro para uma matriz de cadeias de caracteres que contêm os privilégios a serem habilitados no objeto CAccessToken.

pPreviousState
Ponteiro para um objeto CTokenPrivileges que conterá o estado anterior dos privilégios.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

CAccessToken::GetDefaultDacl

Chame esse método para retornar a DACL padrão do objeto CAccessToken.

bool GetDefaultDacl(CDacl* pDacl) const throw(...);

Parâmetros

pDacl
Ponteiro para o objeto Classe CDacl que receberá a DACL padrão do objeto CAccessToken.

Valor de retorno

Retornará TRUE se a DACL padrão tiver sido recuperada; caso contrário, FALSE.

CAccessToken::GetEffectiveToken

Chame esse método para obter o objeto CAccessToken igual ao token de acesso em vigor para o thread atual.

bool GetEffectiveToken(DWORD dwDesiredAccess) throw();

Parâmetros

dwDesiredAccess
Especifica uma máscara de acesso que define os tipos de acesso solicitados ao token de acesso. Esses tipos de acesso solicitados são comparados com a DACL do token para determinar quais acessos são concedidos ou negados.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

CAccessToken::GetGroups

Chame esse método para retornar os grupos de tokens do objeto CAccessToken.

bool GetGroups(CTokenGroups* pGroups) const throw(...);

Parâmetros

pGroups
Ponteiro para o objeto Classe CTokenGroups que receberá as informações do grupo.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

CAccessToken::GetHandle

Chame esse método para recuperar um identificador para o token de acesso.

HANDLE GetHandle() const throw();

Valor de retorno

Retorna um identificador para o token de acesso do objeto CAccessToken.

CAccessToken::GetImpersonationLevel

Chame esse método para obter o nível de representação do token de acesso.

bool GetImpersonationLevel(
    SECURITY_IMPERSONATION_LEVEL* pImpersonationLevel) const throw(...);

Parâmetros

pImpersonationLevel
Ponteiro para um tipo de enumeração SECURITY_IMPERSONATION_LEVEL que receberá as informações de nível de representação.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

CAccessToken::GetLogonSessionId

Chame esse método para obter a ID da sessão de logon associada ao objeto CAccessToken.

bool GetLogonSessionId(LUID* pluid) const throw(...);

Parâmetros

pluid
Ponteiro para um LUID que receberá a ID da sessão de logon.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Em builds de depuração, ocorrerá um erro de declaração caso o pluid seja um valor inválido.

CAccessToken::GetLogonSid

Chame esse método para obter o SID de logon associado ao objeto CAccessToken.

bool GetLogonSid(CSid* pSid) const throw(...);

Parâmetros

pSid
Ponteiro para um objeto Classe CSid.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Em builds de depuração, ocorrerá um erro de declaração caso pSid seja um valor inválido.

CAccessToken::GetOwner

Chame esse método para obter o proprietário associado ao objeto CAccessToken.

bool GetOwner(CSid* pSid) const throw(...);

Parâmetros

pSid
Ponteiro para um objeto Classe CSid.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

O proprietário é definido por padrão em todos os objetos criados enquanto esse token de acesso estiver em vigor.

CAccessToken::GetPrimaryGroup

Chame esse método para obter o grupo primário associado ao objeto CAccessToken.

bool GetPrimaryGroup(CSid* pSid) const throw(...);

Parâmetros

pSid
Ponteiro para um objeto Classe CSid.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

O grupo é definido por padrão em todos os objetos criados enquanto esse token de acesso estiver em vigor.

CAccessToken::GetPrivileges

Chame esse método para obter os privilégios associados ao objeto CAccessToken.

bool GetPrivileges(CTokenPrivileges* pPrivileges) const throw(...);

Parâmetros

pPrivileges
Ponteiro para um objeto Classe CTokenPrivileges que receberá os privilégios.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

CAccessToken::GetProcessToken

Chame esse método para inicializar o CAccessToken com o token de acesso do processo fornecido.

bool GetProcessToken(DWORD dwDesiredAccess, HANDLE hProcess = NULL) throw();

Parâmetros

dwDesiredAccess
Especifica uma máscara de acesso que define os tipos de acesso solicitados ao token de acesso. Esses tipos de acesso solicitados são comparados com a DACL do token para determinar quais acessos são concedidos ou negados.

hProcess
Identificador para o processo cujo token de acesso está aberto. Se o valor padrão de NULL for usado, o processo atual será usado.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Chama a função OpenProcessToken do Win32.

CAccessToken::GetProfile

Chame esse método para obter o identificador apontando para o perfil de usuário associado ao objeto CAccessToken.

HANDLE GetProfile() const throw();

Valor de retorno

Retorna um identificador apontando para o perfil de usuário ou retorna NULL se nenhum perfil existir.

CAccessToken::GetSource

Chame esse método para obter a origem do objeto CAccessToken.

bool GetSource(TOKEN_SOURCE* pSource) const throw(...);

Parâmetros

pSource
Ponteiro para uma estrutura TOKEN_SOURCE.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

CAccessToken::GetStatistics

Chame esse método para obter informações associadas ao objeto CAccessToken.

bool GetStatistics(TOKEN_STATISTICS* pStatistics) const throw(...);

Parâmetros

pStatistics
Ponteiro para uma estrutura TOKEN_STATISTICS.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

CAccessToken::GetTerminalServicesSessionId

Chame esse método para obter a ID de sessão dos serviços de terminal associada ao objeto CAccessToken.

bool GetTerminalServicesSessionId(DWORD* pdwSessionId) const throw(...);

Parâmetros

pdwSessionId
A ID da sessão dos serviços de terminal.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

CAccessToken::GetThreadToken

Chame esse método para inicializar o CAccessToken com o token do thread fornecido.

bool GetThreadToken(
    DWORD dwDesiredAccess,
    HANDLE hThread = NULL,
    bool bOpenAsSelf = true) throw();

Parâmetros

dwDesiredAccess
Especifica uma máscara de acesso que define os tipos de acesso solicitados ao token de acesso. Esses tipos de acesso solicitados são comparados com a DACL do token para determinar quais acessos são concedidos ou negados.

hThread
Identificador para o thread cujo token de acesso está aberto.

bOpenAsSelf
Indica se a verificação de acesso deve ser feita no contexto de segurança do thread que chama o método GetThreadToken ou no contexto de segurança do processo para o thread de chamada.

Se esse parâmetro for FALSE, a verificação de acesso será executada usando o contexto de segurança do thread de chamada. Se o thread estiver representando um cliente, esse contexto de segurança poderá ser o de um processo do cliente. Se esse parâmetro for TRUE, a verificação de acesso será feita usando o contexto de segurança do processo para o thread de chamada.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

CAccessToken::GetTokenId

Chame esse método para obter a ID do token associada ao objeto CAccessToken.

bool GetTokenId(LUID* pluid) const throw(...);

Parâmetros

pluid
Ponteiro para um LUID, o qual receberá a ID do token.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

CAccessToken::GetType

Chame esse método para obter o tipo de token do objeto CAccessToken.

bool GetType(TOKEN_TYPE* pType) const throw(...);

Parâmetros

pType
Endereço da variável TOKEN_TYPE que, se tiver êxito, recebe o tipo do token.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

O tipo de enumeração TOKEN_TYPE contém valores que diferenciam entre um token primário e um token de representação.

CAccessToken::GetUser

Chame esse método para identificar o usuário associado ao objeto CAccessToken.

bool GetUser(CSid* pSid) const throw(...);

Parâmetros

pSid
Ponteiro para um objeto Classe CSid.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

CAccessToken::HKeyCurrentUser

Chame esse método para obter o identificador apontando para o perfil de usuário associado ao objeto CAccessToken.

HKEY HKeyCurrentUser() const throw();

Valor de retorno

Retorna um identificador apontando para o perfil de usuário ou retorna NULL se nenhum perfil existir.

CAccessToken::Impersonate

Chame esse método para atribuir uma representação CAccessToken a um thread.

bool Impersonate(HANDLE hThread = NULL) const throw(...);

Parâmetros

hThread
Identificador para o thread ao qual atribuir o token de representação. Esse identificador deve ter sido aberto com direitos de acesso TOKEN_IMPERSONATE. Se hThread for NULL, o método fará com que o thread pare de usar um token de representação.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Em builds de depuração, ocorrerá um erro de declaração caso CAccessToken não tenha um ponteiro válido para um token.

A Classe CAutoRevertImpersonation pode ser usada para reverter automaticamente os tokens de acesso representados.

CAccessToken::ImpersonateLoggedOnUser

Chame esse método para permitir que o thread de chamada represente o contexto de segurança de um usuário conectado.

bool ImpersonateLoggedOnUser() const throw(...);

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Importante

Se uma chamada para uma função de representação falhar por qualquer motivo, o cliente não será representado, e a solicitação do cliente será feita no contexto de segurança do processo do qual a chamada foi feita. Se o processo estiver em execução como uma conta altamente privilegiada ou como membro de um grupo administrativo, o usuário poderá executar ações que, de outra forma, não seriam permitidas. Portanto, o valor retornado para essa função deverá ser sempre confirmado.

CAccessToken::IsTokenRestricted

Chame esse método para testar se o objeto CAccessToken contém uma lista de SIDs restritos.

bool IsTokenRestricted() const throw();

Valor de retorno

Retornará TRUE se o objeto contiver uma lista de SIDs restritivos e FALSE se não houver SIDs restritivos ou se o método falhar.

CAccessToken::LoadUserProfile

Chame esse método para carregar o perfil de usuário associado ao objeto CAccessToken.

bool LoadUserProfile() throw(...);

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Em builds de depuração, ocorrerá um erro de declaração caso o token CAccessToken não contenha um token válido ou caso já exista um perfil de usuário.

CAccessToken::LogonUser

Chame esse método para criar uma sessão de logon para o usuário associado às credenciais fornecidas.

bool LogonUser(
    LPCTSTR pszUserName,
    LPCTSTR pszDomain,
    LPCTSTR pszPassword,
    DWORD dwLogonType = LOGON32_LOGON_INTERACTIVE,
    DWORD dwLogonProvider = LOGON32_PROVIDER_DEFAULT) throw();

Parâmetros

pszUserName
Ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do usuário. Esse é o nome da conta de usuário na qual fazer logon.

pszDomain
Ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do domínio ou servidor cujo banco de dados da conta contém a conta pszUserName.

pszPassword
Ponteiro para uma cadeia de caracteres terminada em nulo que especifica a senha de texto limpo para a conta de usuário especificada por pszUserName.

dwLogonType
Especifica o tipo de operação de logon a ser executada. Confira LogonUser para obter mais detalhes.

dwLogonProvider
Especifica o provedor de logon. Confira LogonUser para obter mais detalhes.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

O token de acesso resultante do logon será associado ao CAccessToken. Para que esse método tenha êxito, o objeto CAccessToken deve conter privilégios SE_TCB_NAME, identificando o titular como parte da base do computador confiável. Confira LogonUser para obter mais informações sobre os privilégios necessários.

CAccessToken::OpenCOMClientToken

Chame esse método de dentro de um servidor COM que está tratando uma chamada de um cliente para inicializar o CAccessToken com o token de acesso do cliente COM.

bool OpenCOMClientToken(
    DWORD dwDesiredAccess,
    bool bImpersonate = false,
    bool bOpenAsSelf = true) throw(...);

Parâmetros

dwDesiredAccess
Especifica uma máscara de acesso que define os tipos de acesso solicitados ao token de acesso. Esses tipos de acesso solicitados são comparados com a DACL do token para determinar quais acessos são concedidos ou negados.

bImpersonate
Se for TRUE, o thread atual representará o cliente COM de chamada se essa chamada for concluída com êxito. Se for FALSE, o token de acesso será aberto, mas o thread não terá um token de representação quando essa chamada for concluída.

bOpenAsSelf
Indica se a verificação de acesso deve ser feita no contexto de segurança do thread que chama o método GetThreadToken ou no contexto de segurança do processo para o thread de chamada.

Se esse parâmetro for FALSE, a verificação de acesso será executada usando o contexto de segurança do thread de chamada. Se o thread estiver representando um cliente, esse contexto de segurança poderá ser o de um processo do cliente. Se esse parâmetro for TRUE, a verificação de acesso será feita usando o contexto de segurança do processo para o thread de chamada.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

A Classe CAutoRevertImpersonation pode ser usada para reverter automaticamente tokens de acesso representados criados ao definir o sinalizador bImpersonate como TRUE.

CAccessToken::OpenNamedPipeClientToken

Chame esse método de dentro de um servidor que recebe solicitações em um pipe nomeado para inicializar o CAccessToken com o token de acesso do cliente.

bool OpenNamedPipeClientToken(
    HANDLE hPipe,
    DWORD dwDesiredAccess,
    bool bImpersonate = false,
    bool bOpenAsSelf = true) throw(...);

Parâmetros

hPipe
Identificador para um pipe nomeado.

dwDesiredAccess
Especifica uma máscara de acesso que define os tipos de acesso solicitados ao token de acesso. Esses tipos de acesso solicitados são comparados com a DACL do token para determinar quais acessos são concedidos ou negados.

bImpersonate
Se for TRUE, o thread atual representará o cliente do pipe de chamada se essa chamada for concluída com êxito. Se for FALSE, o token de acesso será aberto, mas o thread não terá um token de representação quando essa chamada for concluída.

bOpenAsSelf
Indica se a verificação de acesso deve ser feita no contexto de segurança do thread que chama o método GetThreadToken ou no contexto de segurança do processo para o thread de chamada.

Se esse parâmetro for FALSE, a verificação de acesso será executada usando o contexto de segurança do thread de chamada. Se o thread estiver representando um cliente, esse contexto de segurança poderá ser o de um processo do cliente. Se esse parâmetro for TRUE, a verificação de acesso será feita usando o contexto de segurança do processo para o thread de chamada.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

A Classe CAutoRevertImpersonation pode ser usada para reverter automaticamente tokens de acesso representados criados ao definir o sinalizador bImpersonate como TRUE.

CAccessToken::OpenRPCClientToken

Chame esse método de dentro de um servidor que está tratando uma chamada de um cliente RPC para inicializar o CAccessToken com o token de acesso do cliente.

bool OpenRPCClientToken(
    RPC_BINDING_HANDLE BindingHandle,
    DWORD dwDesiredAccess,
    bool bImpersonate = false,
    bool bOpenAsSelf = true) throw(...);

Parâmetros

BindingHandle
Identificador de associação no servidor que representa uma associação a um cliente.

dwDesiredAccess
Especifica uma máscara de acesso que define os tipos de acesso solicitados ao token de acesso. Esses tipos de acesso solicitados são comparados com a DACL do token para determinar quais acessos são concedidos ou negados.

bImpersonate
Se for TRUE, o thread atual representará o cliente RPC de chamada se essa chamada for concluída com êxito. Se for FALSE, o token de acesso será aberto, mas o thread não terá um token de representação quando essa chamada for concluída.

bOpenAsSelf
Indica se a verificação de acesso deve ser feita no contexto de segurança do thread que chama o método GetThreadToken ou no contexto de segurança do processo para o thread de chamada.

Se esse parâmetro for FALSE, a verificação de acesso será executada usando o contexto de segurança do thread de chamada. Se o thread estiver representando um cliente, esse contexto de segurança poderá ser o de um processo do cliente. Se esse parâmetro for TRUE, a verificação de acesso será feita usando o contexto de segurança do processo para o thread de chamada.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

A Classe CAutoRevertImpersonation pode ser usada para reverter automaticamente tokens de acesso representados criados ao definir o sinalizador bImpersonate como TRUE.

CAccessToken::OpenThreadToken

Chame esse método para definir o nível de representação e, em seguida, inicialize o CAccessToken com o token do thread fornecido.

bool OpenThreadToken(
    DWORD dwDesiredAccess,
    bool bImpersonate = false,
    bool bOpenAsSelf = true,
    SECURITY_IMPERSONATION_LEVEL sil = SecurityImpersonation) throw(...);

Parâmetros

dwDesiredAccess
Especifica uma máscara de acesso que define os tipos de acesso solicitados ao token de acesso. Esses tipos de acesso solicitados são comparados com a DACL do token para determinar quais acessos são concedidos ou negados.

bImpersonate
Se for TRUE, o thread será deixado no nível de representação solicitado após a conclusão desse método. Se for FALSE, o thread será revertido para seu nível de representação original.

bOpenAsSelf
Indica se a verificação de acesso deve ser feita no contexto de segurança do thread que chama o método GetThreadToken ou no contexto de segurança do processo para o thread de chamada.

Se esse parâmetro for FALSE, a verificação de acesso será executada usando o contexto de segurança do thread de chamada. Se o thread estiver representando um cliente, esse contexto de segurança poderá ser o de um processo do cliente. Se esse parâmetro for TRUE, a verificação de acesso será feita usando o contexto de segurança do processo para o thread de chamada.

sil
Especifica um tipo enumerado SECURITY_IMPERSONATION_LEVEL que fornece o nível de representação do token.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

OpenThreadToken é semelhante a CAccessToken::GetThreadToken, mas define o nível de representação antes de inicializar o CAccessToken do token de acesso do thread.

A Classe CAutoRevertImpersonation pode ser usada para reverter automaticamente tokens de acesso representados criados ao definir o sinalizador bImpersonate como TRUE.

CAccessToken::PrivilegeCheck

Chame esse método para determinar se um conjunto especificado de privilégios está habilitado no objeto CAccessToken.

bool PrivilegeCheck(
    PPRIVILEGE_SET RequiredPrivileges,
    bool* pbResult) const throw();

Parâmetros

RequiredPrivileges
Ponteiro para uma estrutura PRIVILEGE_SET.

pbResult
Ponteiro para um valor que o método define para indicar se qualquer um ou todos os privilégios especificados estão habilitados no objeto CAccessToken.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Quando PrivilegeCheck é retornado, o membro Attributes de cada estrutura LUID_AND_ATTRIBUTES será definido como SE_PRIVILEGE_USED_FOR_ACCESS se o privilégio correspondente estiver habilitado. Esse método chama a função PrivilegeCheck do Win32.

CAccessToken::Revert

Chame esse método para interromper o uso de um token de representação por um thread.

bool Revert(HANDLE hThread = NULL) const throw();

Parâmetros

hThread
Identificador para o thread para reverter da representação. Se o hThread for NULL, assume-se o thread atual.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

A reversão de tokens de representação pode ser executada automaticamente com a Classe CAutoRevertImpersonation.

CAccessToken::SetDefaultDacl

Chame esse método para definir a DACL padrão do objeto CAccessToken.

bool SetDefaultDacl(const CDacl& rDacl) throw(...);

Parâmetros

rDacl
As novas informações padrão da Classe CDacl.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

A DACL padrão é aquela usada por padrão quando novos objetos são criados com esse token de acesso em vigor.

CAccessToken::SetOwner

Chame esse método para definir o proprietário do objeto CAccessToken.

bool SetOwner(const CSid& rSid) throw(...);

Parâmetros

rSid
O objeto Classe CSid que contém as informações do proprietário.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

O proprietário é o proprietário padrão usado para os novos objetos criados enquanto esse token de acesso estiver em vigor.

CAccessToken::SetPrimaryGroup

Chame esse método para definir o grupo primário do objeto CAccessToken.

bool SetPrimaryGroup(const CSid& rSid) throw(...);

Parâmetros

rSid
O objeto Classe CSid que contém as informações do grupo primário.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

O grupo primário é o grupo padrão para novos objetos criados enquanto esse token de acesso estiver em vigor.

Confira também

Exemplo de ATLSecurity
Tokens de acesso
Visão geral da aula