Função RpcBindingSetAuthInfoExW (rpcdce.h)

Artigo
11/20/2024

A função RpcBindingSetAuthInfoEx define as informações de autenticação, autorização e qualidade de serviço de um identificador de associação.

Sintaxe

RPC_STATUS RpcBindingSetAuthInfoExW(
  RPC_BINDING_HANDLE       Binding,
  RPC_WSTR                 ServerPrincName,
  unsigned long            AuthnLevel,
  unsigned long            AuthnSvc,
  RPC_AUTH_IDENTITY_HANDLE AuthIdentity,
  unsigned long            AuthzSvc,
  RPC_SECURITY_QOS         *SecurityQOS
);

Parâmetros

Binding

Identificador de associação de servidor no qual as informações de autenticação e autorização estão definidas.

ServerPrincName

Ponteiro para o nome de entidade de segurança esperado do servidor referenciado por Binding. O conteúdo do nome e sua sintaxe são definidos pelo serviço de autenticação em uso.

Observação Para o conjunto de nomes de destino permitidos para SSPs, consulte os comentários na documentação InitializeSecurityContext.

AuthnLevel

Nível de autenticação a ser executado em chamadas de procedimento remoto feitas usando Binding. Para obter uma lista dos níveis de autenticação com suporte para RPC, consulte Authentication-Level Constants.

AuthnSvc

Serviço de autenticação a ser usado.

Especifique RPC_C_AUTHN_NONE para desativar a autenticação para chamadas de procedimento remoto feitas usando de associação.

Se RPC_C_AUTHN_DEFAULT for especificado, a biblioteca de tempo de execução do RPC usará o serviço de autenticação RPC_C_AUTHN_WINNT para chamadas de procedimento remoto feitas usando Binding.

AuthIdentity

Manipule a estrutura que contém as credenciais de autenticação e autorização do cliente apropriadas para o serviço de autenticação e autorização selecionado.

Ao usar o serviço de autenticação RPC_C_AUTHN_WINNTAuthIdentity deve ser um ponteiro para uma estrutura de SEC_WINNT_AUTH_IDENTITY (definida em Rpcdce.h). Os serviços de autenticação Kerberos e Negotiate também usam a estrutura de SEC_WINNT_AUTH_IDENTITY.

Especifique um valor nulo para usar o contexto de logon de segurança para o espaço de endereço atual. Passe o valor RPC_C_NO_CREDENTIALS para usar um contexto de logon anônimo. Observe que RPC_C_NO_CREDENTIALS só será válido se RPC_C_AUTHN_GSS_SCHANNEL for selecionado como o serviço de autenticação.

AuthzSvc

Serviço de autorização implementado pelo servidor para a interface de interesse. A validade e a confiabilidade dos dados de autorização, como qualquer dado do aplicativo, dependem do serviço de autenticação e do nível de autenticação selecionados. Esse parâmetro é ignorado ao usar o serviço de autenticação RPC_C_AUTHN_WINNT. Consulte a Observação.

SecurityQOS

Ponteiro para a estrutura de RPC_SECURITY_QOS, que define a qualidade de serviço de segurança.

Observação Para obter uma lista dos serviços de autenticação compatíveis com RPC, consulte Authentication-Service Constants.

Valor de retorno

Valor	Significado
RPC_S_OK	A chamada foi bem-sucedida.
RPC_S_INVALID_BINDING	O identificador de associação era inválido.
RPC_S_WRONG_KIND_OF_BINDING	Este foi o tipo errado de associação para a operação.
RPC_S_UNKNOWN_AUTHN_SERVICE	Serviço de autenticação desconhecido.

Observação Para obter uma lista de códigos de erro válidos, consulte RPC Return Values.

Observações

Um aplicativo cliente chama a função RpcBindingSetAuthInfoEx para configurar um identificador de associação de servidor para fazer chamadas de procedimento remoto autenticados. Essa função fornece a capacidade de definir informações de qualidade de serviço de segurança no identificador de associação. De outra forma, é idêntico a RpcBindingSetAuthInfo.

A menos que um cliente chame RpcBindingSetAuthInfoEx, todas as chamadas de procedimento remoto em de associação não serão autenticadas. Um cliente não é necessário para chamar essa função.

A função RpcBindingSetAuthInfoEx tira um instantâneo das credenciais. Portanto, a memória dedicada ao parâmetro AuthIdentity pode ser liberada antes do identificador de associação. A exceção a isso é quando seu aplicativo usa RpcBindingSetAuthInfoEx com RPC_C_QOS_IDENTITY_DYNAMIC e também especifica um valor de NULL nãopara AuthIdentity.

Observação a função RpcBindingSetAuthInfo não deve ser chamada em um identificador de associação enquanto uma chamada RPC no mesmo identificador estiver em andamento. Isso produz resultados indefinidos.

Devido aos requisitos variados de diferentes versões do Microsoft RPC, a Microsoft recomenda que um aplicativo mantenha um ponteiro para o parâmetro AuthIdentity desde que o identificador de associação exista. Isso aumenta a portabilidade dos aplicativos.

Windows Server 2003 com SP1 e Windows XP com SP2: para Windows XP SP2 e Windows Server 2003 SP1, o ponteiro para o parâmetro AuthIdentity não precisa ser mantido durante a vida útil do identificador de associação. Esse ponteiro só deverá ser mantido se as chamadas subsequentes para RpcBindingInqAuthInfo ou RpcBindingInqAuthInfoEx forem feitas.

Observação a sequência de protocolo ncalrpc dá suporte apenas a RPC_C_AUTHN_WINNT, mas dá suporte à autenticação mútua; forneça um SPN e solicite autenticação mútua por meio do parâmetro SecurityQOS para conseguir isso.

Nota

O cabeçalho rpcdce.h define RpcBindingSetAuthInfoEx como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do 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 2000 Professional [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows 2000 Server [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	rpcdce.h (inclua Rpc.h)
biblioteca	Rpcrt4.lib
de DLL	Rpcrt4.dll

Consulte também

RPC_SECURITY_QOS

RpcBindingInqAuthInfoEx

RpcServerRegisterAuthInfo

Compartilhar via