Função RpcBindingSetAuthInfoW (rpcdce.h)

Artigo
11/20/2024

A função RpcBindingSetAuthInfo define as informações de autenticação e autorização de um identificador de associação.

Sintaxe

RPC_STATUS RpcBindingSetAuthInfoW(
  RPC_BINDING_HANDLE       Binding,
  RPC_WSTR                 ServerPrincName,
  unsigned long            AuthnLevel,
  unsigned long            AuthnSvc,
  RPC_AUTH_IDENTITY_HANDLE AuthIdentity,
  unsigned long            AuthzSvc
);

Parâmetros

Binding

Identificador de associação de servidor ao qual as informações de autenticação e autorização devem ser aplicadas.

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 a lista de constantes Authentication-Level.

AuthnSvc

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

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 para 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_WINNT AuthIdentity 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.

Quando você seleciona o serviço de autenticação RPC_C_AUTHN_GSS_SCHANNEL, o parâmetro AuthIdentity deve ser um ponteiro para uma estrutura de SCHANNEL_CRED (definida em Schannel.h). 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.

Observação Ao selecionar o serviço de autenticação RPC_C_AUTHN_GSS_SCHANNEL, o parâmetro AuthIdentity também pode ser um ponteiro para uma estrutura de SCH_CRED. No entanto, no Windows XP e versões posteriores do Windows, a única estrutura aceitável a ser passada como o parâmetro AuthIdentity para o serviço de autenticação RPC_C_AUTHN_GSS_SCHANNEL é a estrutura SCHANNEL_CRED.

AuthzSvc

Serviço de autorização implementado pelo servidor para a interface de interesse. Consulte a Observação.

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.

Observação Para obter mais informações, 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 RpcBindingSetAuthInfo para configurar um identificador de associação de servidor para fazer chamadas de procedimento remoto autenticados. Um cliente não é necessário para chamar essa função.

A menos que um cliente chame RpcBindingSetAuthInfo, nenhuma chamada de procedimento remoto no identificador de associação do Binding será autenticada. Um servidor pode chamar RpcBindingInqAuthClient de dentro de uma chamada de procedimento remoto para determinar se essa chamada foi autenticada.

A função RpcBindingSetAuthInfo tira um instantâneo das credenciais. Portanto, a memória dedicada ao parâmetro AuthIdentity pode ser liberada antes do identificador de associação.

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

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 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.

Nota

O cabeçalho rpcdce.h define RpcBindingSetAuthInfo 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

dos Serviços de Segurança do MSMQ

RpcBindingInqAuthInfo

RpcBindingSetOption

RpcServerRegisterAuthInfo

Compartilhar via