Função SaslInitializeSecurityContextA (sspi.h)

  • Artigo

A função SaslInitializeSecurityContext encapsula uma chamada padrão para a função InitializeSecurityContext (General) da interface do provedor de suporte de segurança e processa cookies de servidor SASL do servidor.

Sintaxe

SECURITY_STATUS SEC_ENTRY SaslInitializeSecurityContextA(
  [in]            PCredHandle    phCredential,
  [in]            PCtxtHandle    phContext,
  [in]            LPSTR          pszTargetName,
  [in]            unsigned long  fContextReq,
  [in]            unsigned long  Reserved1,
  [in]            unsigned long  TargetDataRep,
  [in]            PSecBufferDesc pInput,
  [in]            unsigned long  Reserved2,
  [out]           PCtxtHandle    phNewContext,
  [in, out]       PSecBufferDesc pOutput,
  [out]           unsigned long  *pfContextAttr,
  [out, optional] PTimeStamp     ptsExpiry
);

Parâmetros

[in] phCredential

Um identificador para as credenciais retornadas pelo
Função AcquireCredentialsHandle usada para criar o contexto de segurança. O uso da função SaslInitializeSecurityContext requer pelo menos credenciais OUTBOUND.

[in] phContext

Ponteiro para uma estrutura CtxtHandle . Na primeira chamada para a função SaslInitializeSecurityContext , esse ponteiro é NULL. Na segunda chamada, esse parâmetro é um ponteiro para o identificador para o contexto parcialmente formado retornado no parâmetro phNewContext pela primeira chamada.

[in] pszTargetName

Ponteiro para uma cadeia de caracteres Unicode ou ANSI que indica o destino do contexto.

[in] fContextReq

Sinalizadores de bits que indicam os requisitos do contexto. Os sinalizadores usados para esse parâmetro são prefixados com ISC_REQ_; por exemplo: ISC_REQ_DELEGATE. Especifique combinações dos seguintes sinalizadores de atributos.

Valor Significado
ISC_REQ_REPLAY_DETECT
 Detectar pacotes reproduzidos.
ISC_REQ_SEQUENCE_DETECT
 Detectar mensagens recebidas fora da sequência.
ISC_REQ_CONFIDENTIALITY
 Criptografar mensagens.
ISC_REQ_STREAM
 Suporte a uma conexão orientada a fluxo.
ISC_REQ_EXTENDED_ERROR
 Quando ocorrerem erros, a parte remota será notificada.
ISC_REQ_CONNECTION
 O contexto de segurança não manipulará mensagens de formatação.
ISC_REQ_MUTUAL_AUTH
 O cliente e o servidor serão autenticados.
ISC_REQ_INTEGRITY
 Assine mensagens e verifique as assinaturas.
 

Para obter mais descrições dos vários atributos, consulte Requisitos de contexto.

[in] Reserved1

Valor reservado; deve ser zero.

[in] TargetDataRep

Indica a representação de dados, como ordenação de bytes, no destino. Pode ser SECURITY_NATIVE_DREP ou SECURITY_NETWORK_DREP.

[in] pInput

Ponteiro para uma estrutura SecBufferDesc que contém ponteiros para os buffers fornecidos como entrada para o pacote. O ponteiro deve ser NULL na primeira chamada para a função. Em chamadas subsequentes para a função, é um ponteiro para um buffer alocado com memória suficiente para manter o token retornado pelo par remoto.

A SASL requer um único buffer do tipo SECBUFFER_TOKEN que contém o desafio recebido do servidor.

[in] Reserved2

Valor reservado; deve ser zero.

[out] phNewContext

Ponteiro para uma estrutura CtxtHandle . Na primeira chamada para a função SaslInitializeSecurityContext , esse ponteiro recebe o novo identificador de contexto. Na segunda chamada, phNewContext pode ser o mesmo que o identificador especificado no parâmetro phContext .

[in, out] pOutput

Ponteiro para uma estrutura SecBufferDesc que contém ponteiros para a estrutura SecBuffer que recebe os dados de saída. Se um buffer tiver sido digitado como SEC_READWRITE na entrada, ele estará lá na saída. O sistema alocará um buffer para o token de segurança se solicitado (por meio de ISC_REQ_ALLOCATE_MEMORY) e preencherá o endereço no descritor de buffer para o token de segurança.

[out] pfContextAttr

Ponteiro para uma variável para receber um conjunto de sinalizadores de bits que indicam os atributos do contexto estabelecido. Para obter uma descrição dos vários atributos, consulte Requisitos de contexto.

Os sinalizadores usados para esse parâmetro são prefixados com ISC_RET_, como ISC_RET_DELEGATE.

Para obter uma lista de valores válidos, consulte o parâmetro fContextReq .

Não marcar para atributos relacionados à segurança até que a chamada de função final retorne com êxito. Sinalizadores de atributo não relacionados à segurança, como o sinalizador ASC_RET_ALLOCATED_MEMORY, podem ser verificados antes do retorno final.

Nota Atributos de contexto específicos podem ser alterados durante uma negociação com um par remoto.
 

[out, optional] ptsExpiry

Ponteiro para uma estrutura TimeStamp que recebe o tempo de expiração do contexto. É recomendável que o pacote de segurança sempre retorne esse valor no horário local. Esse parâmetro é opcional e NULL deve ser passado para clientes de curta duração.

Retornar valor

Se a chamada for concluída com êxito, essa função retornará SEC_E_OK. A tabela a seguir mostra alguns valores de retorno de falha possíveis.

Código de retorno Descrição
SEC_E_ALGORITHM_MISMATCH
 O processamento Authz não é permitido.
SEC_E_INSUFFICIENT_MEMORY
 Não há memória suficiente disponível para concluir a solicitação.
SEC_E_INVALID_TOKEN
 Nenhum buffer de token está localizado no parâmetro pOutput ou a mensagem falhou ao descriptografar.

Comentários

Observação

O cabeçalho sspi.h define SaslInitializeSecurityContext como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito Valor
Cliente mínimo com suporte Nenhum compatível
Servidor mínimo com suporte Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho sspi.h (inclua Security.h)
Biblioteca Secur32.lib
DLL Secur32.dll