Função SaslInitializeSecurityContextA (sspi.h)

Artigo
07/16/2024

A função SaslInitializeSecurityContext encapsula uma chamada padrão para a interface do provedor de suporte de segurança função InitializeSecurityContext (Geral) 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 de retornados pelo
função AcquireCredentialsHandle usada para criar o contexto de segurança . Usar a função SaslInitializeSecurityContext requer pelo menos credenciais OUTBOUND.

[in] phContext

Ponteiro para uma estrutura de 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 sinalizadores de atributos a seguir.

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	Dê 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 tratará as 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 de CtxtHandle. Na primeira chamada para a função SaslInitializeSecurityContext, esse ponteiro recebe o novo identificador de contexto. Na segunda chamada, phNewContext pode ser igual ao 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.

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 verifique se há 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.

Observação 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.

Valor de retorno

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 do 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 não foi descriptografada.

Observações

Nota

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 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	Nenhum com suporte
servidor com suporte mínimo	Windows Server 2003 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	sspi.h (inclua Security.h)
biblioteca	Secur32.lib
de DLL	Secur32.dll

Compartilhar via