Função RpcGetAuthorizationContextForClient (rpcasync.h)

  • Artigo

A função RpcGetAuthorizationContextForClient retorna o contexto Authz para um cliente RPC que pode ser usado com funções Authz para autenticação de alto desempenho. Com suporte apenas para sequências de protocolo ncalrpc e ncacn_* .

Sintaxe

RPC_STATUS RpcGetAuthorizationContextForClient(
  [in, optional] RPC_BINDING_HANDLE ClientBinding,
  [in]           BOOL               ImpersonateOnReturn,
  [in]           PVOID              Reserved1,
  [in, optional] PLARGE_INTEGER     pExpirationTime,
  [in]           LUID               Reserved2,
  [in]           DWORD              Reserved3,
  [in]           PVOID              Reserved4,
  [out]          PVOID              *pAuthzClientContext
);

Parâmetros

[in, optional] ClientBinding

Identificador de associação no servidor que representa uma associação a um cliente. O servidor representa o cliente indicado por esse identificador. Se um valor igual a zero for especificado, o servidor representará o cliente que está sendo atendido por esse thread de servidor.

[in] ImpersonateOnReturn

Direciona a função para representar o cliente no retorno e, em seguida, retorna uma estrutura AUTHZ_CLIENT_CONTEXT_HANDLE . Defina esse parâmetro como diferente de zero para representar o cliente. Consulte Observações.

[in] Reserved1

Reservado. Precisa ser NULL.

[in, optional] pExpirationTime

Ponteiro para a data de validade e a hora do token. Se nenhum valor for passado, o token nunca expirará. O tempo de expiração não é imposto no momento.

[in] Reserved2

Reservado. Deve ser uma estrutura LUID com cada membro definido como zero.

[in] Reserved3

Reservado. Deve ser zero.

[in] Reserved4

Reservado. Precisa ser NULL.

[out] pAuthzClientContext

Ponteiro para uma estrutura AUTHZ_CLIENT_CONTEXT_HANDLE que pode ser passada diretamente para as funções Authz. Se a função falhar, o conteúdo desse parâmetro será indefinido.

Valor retornado

Valor Significado
RPC_S_OK
 A chamada foi bem-sucedida.
RERROR_INVALID_PARAMETER
 Um parâmetro reservado é diferente do valor prescrito.
RPC_S_NO_CONTEXT_AVAILABLE
O cliente RPC não foi autenticado com êxito.
 

Falha retorna um código de erro RPC_S_* ou um código de erro do Windows. As informações de erro estendidas estão disponíveis por meio de mecanismos de recuperação de código de erro padrão do RPC ou do Windows. Para obter uma lista de códigos de erro válidos, consulte RPC Return Values.

Comentários

A função RpcGetAuthorizationContextForClient pode ser chamada no mesmo contexto que a função RpcImpersonateClient . Todas as funções que representam marcar para determinar se o chamador tem o privilégio SeImpersonatePrivilege. Se o chamador tiver o SeImpersonatePrivilege ou se a identidade autenticada for a mesma que o chamador, a representação solicitada será permitida. Caso contrário, a representação terá êxito apenas no nível de Identificação.

Nota O privilégio SeImpersonatePrivilege não tem suporte até o Windows XP com Service Pack 2 (SP2).

A função RpcGetAuthorizationContextForClient tem suporte apenas para sequências de protocolo ncalrpc e ncacn_* e não tem suporte em pipes nomeados que implementam apenas a segurança de transporte.

A função RpcGetAuthorizationContextForClient é thread-safe e pode ser chamada de vários threads. O contexto retornado em pAuthzClientContext é independente da chamada de função e pode ser usado após sua conclusão. O chamador é responsável por liberar o contexto com uma chamada para a função RpcFreeAuthorizationContext .

A melhoria de desempenho observada usando a função RpcGetAuthorizationContextForClient, quando comparada aos métodos anteriores de representação ou acesso marcar ou reverter a si mesmo, depende dos seguintes fatores:

  • Quantas vezes a função é chamada para uma determinada identidade de cliente.
  • Sequência de protocolo e acompanhamento de identidade em vigor para a chamada de função.
As chamadas subsequentes para a função RpcGetAuthorizationContextForClient para a mesma identidade do cliente têm um custo extremamente baixo. Essa eficiência é obtida pelos resultados de consultas anteriores sendo armazenadas em cache e respostas retornadas do cache sempre que possível.

Chamadas sobre ncalrpc com acompanhamento de identidade estático executam a função RpcGetAuthorizationContextForClient mais rapidamente do que chamadas por ncalrpc com acompanhamento dinâmico de identidade. Chamadas por ncacn_* são executadas com aproximadamente a mesma velocidade para uma determinada sequência de protocolo, independentemente de o rastreamento de identidade ser estático ou dinâmico.

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 rpcasync.h (inclua Rpc.h)
Biblioteca Rpcrt4.lib
DLL Rpcrt4.dll

Confira também

Funções de Controle de Acesso de cliente/servidor

LUID

Valores retornados de RPC

RpcFreeAuthorizationContext

RpcImpersonateClient