Função InitializeSecurityContext (Geral)

Artigo
10/24/2023

A função InitializeSecurityContext (Geral) inicia o contexto de segurança de saída do lado do cliente de um identificador de credencial. Essa função é usada para criar um contexto de segurança entre o aplicativo cliente e um par remoto. InitializeSecurityContext (Geral) retornará um token que o cliente deverá passar para o par remoto, que enviará o token para a implementação de segurança local por meio da chamada AcceptSecurityContext (Geral). O token gerado deve ser considerado opaco por todos os chamadores.

Normalmente, a função InitializeSecurityContext (Geral) é chamada em um loop até que seja estabelecido um contexto de segurança suficiente.

Para obter informações sobre como usar essa função com um SSP (provedor de suporte de segurança) específico, consulte os tópicos a seguir.

Tópico	Descrição
InitializeSecurityContext (CredSSP)	Inicia o contexto de segurança de saída do lado do cliente de um identificador de credencial usando o pacote de segurança CredSSP (Provedor de suporte de segurança de credencial).
InitializeSecurityContext (Digest)	Inicia o contexto de segurança de saída do lado do cliente de um identificador de credencial usando o pacote de segurança Digest.
InitializeSecurityContext (Kerberos)	Inicia o contexto de segurança de saída do lado do cliente de um identificador de credencial usando o pacote de segurança Kerberos.
InitializeSecurityContext (Negotiate)	Inicia o contexto de segurança de saída do lado do cliente de um identificador de credencial usando o pacote de segurança Negotiate.
InitializeSecurityContext (NTLM)	Inicia o contexto de segurança de saída do lado do cliente de um identificador de credencial usando o pacote de segurança NTLM.
InitializeSecurityContext (Schannel)	Inicia o contexto de segurança de saída do lado do cliente de um identificador de credencial usando o pacote de segurança Schannel.

Sintaxe

SECURITY_STATUS SEC_Entry InitializeSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _In_opt_    PCtxtHandle    phContext,
  _In_opt_    SEC_CHAR       *pszTargetName,
  _In_        ULONG          fContextReq,
  _In_        ULONG          Reserved1,
  _In_        ULONG          TargetDataRep,
  _In_opt_    PSecBufferDesc pInput,
  _In_        ULONG          Reserved2,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Inout_opt_ PSecBufferDesc pOutput,
  _Out_       PULONG         pfContextAttr,
  _Out_opt_   PTimeStamp     ptsExpiry
);

Parâmetros

phCredential[in, optional]

Um identificador para as credenciais retornadas por AcquireCredentialsHandle (Geral). Esse identificador é usado para criar o contexto de segurança. A função InitializeSecurityContext (Geral) exige credenciais de SAÍDA pelo menos.

phContext[in, optional]

Um ponteiro para uma estrutura CtxtHandle. Na primeira chamada para InitializeSecurityContext (Geral), esse ponteiro é NULL. Na segunda chamada, esse parâmetro é um ponteiro ao identificador para o contexto parcialmente formado retornado no parâmetro phNewContext pela primeira chamada.

Esse parâmetro é opcional com o SSP do Microsoft Digest e pode ser definido como NULL.

Ao usar esse SSP do Schannel, na primeira chamada para InitializeSecurityContext (Geral), especifique NULL. Em chamadas futuras, especifique o token recebido no parâmetro phNewContext após a primeira chamada para essa função.

Aviso

Não use o mesmo identificador de contexto em chamadas simultâneas para InitializeSecurityContext (Geral). A implementação da API nos provedores de serviços de segurança não é segura para thread.

pTargetName[in, optional]

Um ponteiro para uma cadeia de caracteres terminada em nulo que indica o destino do contexto. O conteúdo da cadeia de caracteres é específico do pacote de segurança, conforme descrito na tabela a seguir. Essa lista não é exaustiva. SSPs adicionais do sistema e de terceiros podem ser adicionados a um sistema.

SSP em uso	Significado
Digest	Cadeia de caracteres terminada em nulo que identifica exclusivamente o URI do recurso solicitado. A cadeia de caracteres deve ser composta de caracteres permitidos em um URI e deve ser representável pelo conjunto de códigos ASCII dos EUA. A codificação porcentual pode ser usada para representar caracteres de fora do conjunto de códigos ASCII dos EUA.
Kerberos ou Negotiate	Nome da entidade de serviço (SPN) ou o contexto de segurança do servidor de destino.
NTLM	Nome da entidade de serviço (SPN) ou o contexto de segurança do servidor de destino.
Schannel/SSL	Cadeia de caracteres terminada em nulo que identifica exclusivamente o servidor de destino. O Schannel usa esse valor para verificar o certificado do servidor. O Schannel também usa esse valor para localizar a sessão no cache de sessão ao restabelecer uma conexão. A sessão armazenada em cache será usada somente se todas as condições a seguir forem atendidas: – O nome de destino é o mesmo. – A entrada de cache não expirou. – O processo de aplicativo que chama a função é o mesmo. – A sessão de logon é a mesma. – O identificador de credencial é o mesmo.

fContextReq[in]

Sinalizadores de bits que indicam solicitações para o contexto. Nem todos os pacotes podem dar suporte a todos os requisitos. Os sinalizadores usados para esse parâmetro recebem o prefixo ISC_REQ_, por exemplo, ISC_REQ_DELEGATE. Esse parâmetro pode ser um ou mais dos sinalizadores de atributos a seguir.

Valor	Significado
ISC_REQ_ALLOCATE_MEMORY	O pacote de segurança aloca buffers de saída para você. Quando terminar de usar os buffers de saída, libere-os chamando a função FreeContextBuffer.
ISC_REQ_CONFIDENTIALITY	Criptografar mensagens usando a função EncryptMessage.
ISC_REQ_CONNECTION	O contexto de segurança não identificará as mensagens de formatação. Esse valor é o padrão para as delegações restritas de Kerberos, Negotiate e NTLM.
ISC_REQ_DELEGATE	O servidor pode usar o contexto para autenticar em outros servidores como o cliente. O sinalizador ISC_REQ_MUTUAL_AUTH deve ser definido para que esse sinalizador funcione. Válido para Kerberos. Ignore esse sinalizador para delegação restrita.
ISC_REQ_EXTENDED_ERROR	A parte remota será notificada quando ocorrerem erros.
ISC_REQ_HTTP	Use o Digest para HTTP. Omita esse sinalizador para usar o Digest como um mecanismo SASL.
ISC_REQ_INTEGRITY	Assine mensagens e verifique as assinaturas usando as funções EncryptMessage e MakeSignature.
ISC_REQ_MANUAL_CRED_VALIDATION	O Schannel não deve autenticar o servidor automaticamente.
ISC_REQ_MUTUAL_AUTH	A política de autenticação mútua do serviço será atendida. CUIDADO: isso não significa necessariamente que a autenticação mútua foi executada, apenas que a política de autenticação do serviço foi suficiente. Para garantir que a autenticação mútua seja executada, chame a função QueryContextAttributes (Geral).
ISC_REQ_NO_INTEGRITY	Se esse sinalizador estiver definido, o sinalizador ISC_REQ_INTEGRITY será ignorado. Esse valor tem suporte apenas nas delegações restritas de Negotiate e Kerberos.
ISC_REQ_REPLAY_DETECT	Detecte mensagens reproduzidas que foram codificadas usando as funções EncryptMessage ou MakeSignature.
ISC_REQ_SEQUENCE_DETECT	Detectar mensagens recebidas fora da sequência.
ISC_REQ_STREAM	Dê suporte a uma conexão orientada por fluxo.
ISC_REQ_USE_SESSION_KEY	Uma nova chave de sessão deve ser negociada. Esse valor tem suporte apenas na delegação restrita de Kerberos.
ISC_REQ_USE_SUPPLIED_CREDS	O Schannel não deve tentar fornecer credenciais para o cliente automaticamente.

Os atributos solicitados podem não ter suporte do cliente. Para obter mais informações, consulte o parâmetro pfContextAttr.

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

Reserved1[in]

Esse parâmetro é reservado e precisa ser definido como zero.

TargetDataRep[in]

A representação de dados, como a ordenação de bytes, no destino. Esse parâmetro pode ser SECURITY_NATIVE_DREP ou SECURITY_NETWORK_DREP.

Esse parâmetro não é usado com Digest ou Schannel. Defina-o como zero.

pInput[in, optional]

Um ponteiro para uma estrutura SecBufferDesc que contém ponteiros para os buffers fornecidos como entrada ao pacote. A menos que o contexto do cliente tenha sido iniciado pelo servidor, o valor desse parâmetro deve estar NULL na primeira chamada para a função. Em chamadas subsequentes para a função ou quando o contexto do cliente foi iniciado pelo servidor, o valor desse parâmetro é um ponteiro para um buffer alocado com memória suficiente para manter o token retornado pelo computador remoto.

Reserved2[in]

Esse parâmetro é reservado e precisa ser definido como zero.

phNewContext[in, out, optional]

Um ponteiro para uma estrutura CtxtHandle. Na primeira chamada para InitializeSecurityContext (Geral), esse ponteiro recebe o novo identificador de contexto. Na segunda chamada, phNewContext pode ser o mesmo que o identificador especificado no parâmetro phContext. phNewContext nunca deverá ser NULL.

pOutput[in, out, optional]

Um ponteiro para uma estrutura SecBufferDesc contendo ponteiros para a estrutura SecBuffer que recebe os dados de saída. Se um buffer for digitado como SEC_READWRITE na entrada, ele estará lá na saída. Se solicitado, o sistema alocará um buffer para o token de segurança (por meio de ISC_REQ_ALLOCATE_MEMORY) e preencherá o endereço no descritor de buffer para o token de segurança.

Ao usar o SSP do Microsoft Digest, esse parâmetro recebe a resposta de desafio que deve ser enviada ao servidor.

Ao usar o SSP do Schannel, se o sinalizador ISC_REQ_ALLOCATE_MEMORY for especificado, o SSP do Schannel alocará memória para o buffer e colocará as informações apropriadas no SecBufferDesc. Além disso, o chamador deve passar um buffer de tipo SECBUFFER_ALERT. Na saída, se um alerta for gerado, esse buffer conterá informações sobre esse alerta e a função falhará.

pfContextAttr[out]

Um ponteiro para uma variável 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 recebem o prefixo 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 que não estã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 a negociação com um par remoto.

ptsExpiry[out, optional]

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

Credenciais ou contextos de segurança de SSP do Microsoft Digest não possuem tempo de validade.

Retornar valor

Se a função for bem-sucedida, ela retornará um dos seguintes códigos de êxito.

Código de retorno	Descrição
SEC_I_COMPLETE_AND_CONTINUE	O cliente deve chamar CompleteAuthToken e, em seguida, passar a saída para o servidor. Em seguida, o cliente aguardará um token retornado e o passará, em outra chamada, para InitializeSecurityContext (Geral).
SEC_I_COMPLETE_NEEDED	O cliente deve concluir a criação da mensagem e chamar a função CompleteAuthToken.
SEC_I_CONTINUE_NEEDED	O cliente deve enviar o token de saída para o servidor e aguardar um token de retorno. Em seguida, o token retornado é passado em outra chamada para InitializeSecurityContext (Geral). O token de saída pode estar vazio.
SEC_I_INCOMPLETE_CREDENTIALS	Use com o Schannel. O servidor solicitou a autenticação do cliente e as credenciais fornecidas não incluem um certificado ou ele não foi emitido por uma autoridade de certificação confiável para o servidor. Para obter mais informações, consulte Comentários.
SEC_E_INCOMPLETE_MESSAGE	Use com o Schannel. Os dados de toda a mensagem não foram lidos da transmissão. Quando esse valor é retornado, o buffer pInput contém uma estrutura SecBuffer com um membro BufferType de SECBUFFER_MISSING. O membro cbBuffer do SecBuffer contém um valor que indica o número de bytes adicionais que a função deve ler do cliente antes que essa função obtenha êxito. Embora esse número nem sempre esteja correto, usá-lo pode ajudar a melhorar o desempenho evitando chamadas múltiplas para essa função.
SEC_E_OK	O contexto de segurança foi inicializado com êxito. Não há necessidade de fazer outra chamada InitializeSecurityContext (Geral). Se a função retornar um token de saída, ou seja, se SECBUFFER_TOKEN em pOutput tiver o comprimento diferente de zero, esse token deverá ser enviado para o servidor.

Se a função falhar, a função retornará um dos seguintes códigos de erro.

Código de retorno	Descrição
SEC_E_INSUFFICIENT_MEMORY	Não há memória suficiente disponível para concluir a ação solicitada.
SEC_E_INTERNAL_ERROR	Ocorreu um erro que não foi mapeado para um código de erro SSPI.
SEC_E_INVALID_HANDLE	O identificador passado para a função não é válido.
SEC_E_INVALID_TOKEN	Ocorreu um erro devido a um token de entrada malformado, como um token corrompido em trânsito, um token de tamanho incorreto ou um token passado para o pacote de segurança incorreto. Pode acontecer do cliente e o servidor passarem um token para o pacote errado, se eles não negociarem o pacote de segurança adequado.
SEC_E_LOGON_DENIED	O logon falhou.
SEC_E_NO_AUTHENTICATING_AUTHORITY	Nenhuma autoridade pode ser contatada para obter autenticação. O nome de domínio da parte de autenticação pode estar errado, o domínio pode estar inacessível ou pode ter havido uma falha de relação de confiança.
SEC_E_NO_CREDENTIALS	Nenhuma credencial está disponível no pacote de segurança.
SEC_E_TARGET_UNKNOWN	O destino não foi reconhecido.
SEC_E_UNSUPPORTED_FUNCTION	Um sinalizador de atributo de contexto inválido, (ISC_REQ_DELEGATE ou ISC_REQ_PROMPT_FOR_CREDS), foi especificado no parâmetro fContextReq.
SEC_E_WRONG_PRINCIPAL	A entidade de segurança que recebeu a solicitação de autenticação não é a mesma passada para o parâmetro pszTargetName. Isso indica uma falha na autenticação mútua.

Comentários

O chamador é responsável por determinar se os atributos de contexto final são suficientes. Se, por exemplo, a confidencialidade foi solicitada, mas não pôde ser estabelecida, alguns aplicativos podem optar por desligar a conexão imediatamente.

Se os atributos do contexto de segurança não forem suficientes, o cliente deverá liberar o contexto parcialmente criado chamando a função DeleteSecurityContext.

A função InitializeSecurityContext (Geral) é usada por um cliente para inicializar um contexto de saída.

Para um contexto de segurança de duas etapas, esta é a sequência de chamadas:

O cliente chama a função com phContext definido como NULL e preenche o descritor de buffer com a mensagem de entrada.
O pacote de segurança examina os parâmetros e constrói um token opaco, colocando-o no elemento TOKEN na matriz de buffer. Se o parâmetro fContextReq incluir o sinalizador ISC_REQ_ALLOCATE_MEMORY, o pacote de segurança alocará a memória e retornará o ponteiro no elemento TOKEN.
O cliente envia o token retornado no buffer pOutput para o servidor de destino. Em seguida, o servidor passa o token como um argumento de entrada em uma chamada para a função AcceptSecurityContext (Geral).
AcceptSecurityContext (Geral) poderá retornar um token, que o servidor enviará ao cliente para uma segunda chamada para InitializeSecurityContext (Geral) se a primeira chamada retornar SEC_I_CONTINUE_NEEDED.

Para contextos de segurança de várias etapas, como a autenticação mútua, esta é a sequência de chamadas:

O cliente chama a função conforme descrito anteriormente, mas o pacote retorna o código de êxito SEC_I_CONTINUE_NEEDED.
O cliente envia o token de saída para o servidor e aguarda a resposta do servidor.
Após o recebimento da resposta do servidor, o cliente chama InitializeSecurityContext (Geral) novamente, com phContext definido como o identificador que foi retornado da última chamada. O token recebido do servidor é fornecido no parâmetro pInput.
Não use o valor phContext em chamadas simultâneas para InitializeSecurityContext (Geral). A implementação nos provedores de segurança não é segura para thread.

Se o servidor responder com êxito, o pacote de segurança retornará SEC_E_OK e será estabelecida uma sessão segura.

Se a função retornar uma das respostas de erro, a resposta do servidor não será aceita e a sessão não será estabelecida.

Se a função retornar SEC_I_CONTINUE_NEEDED, SEC_I_COMPLETE_NEEDED ou SEC_I_COMPLETE_AND_CONTINUE, as etapas 2 e 3 serão repetidas.

Para inicializar um contexto de segurança, pode ser necessária mais de uma chamada para essa função, dependendo do mecanismo de autenticação subjacente, bem como das opções especificadas no parâmetro fContextReq.

Os parâmetros fContextReq e pfContextAttributes são bitmasks que representam vários atributos de contexto. Para obter uma descrição dos vários atributos, consulte Requisitos de contexto. O parâmetro pfContextAttributes é válido em todo retorno com êxito, mas somente no retorno final com êxito você deve examinar os sinalizadores que pertencem a aspectos de segurança do contexto. Os retornos intermediários podem definir, por exemplo, o sinalizador ISC_RET_ALLOCATED_MEMORY.

Se o sinalizador ISC_REQ_USE_SUPPLIED_CREDS estiver definido, o pacote de segurança deverá procurar um tipo de buffer SECBUFFER_PKG_PARAMS no buffer de entrada pInput. Essa não é uma solução genérica, mas permite um emparelhamento sólido de pacote de segurança e aplicativo, quando adequado.

Se ISC_REQ_ALLOCATE_MEMORY tiver sido especificado, o chamador deverá liberar a memória chamando a função FreeContextBuffer.

Por exemplo, o token de entrada pode ser o desafio de um Gerenciador de LAN. Nesse caso, o token de saída seria a resposta criptografada em NTLM para o desafio.

A ação que o cliente executa depende do código de retorno dessa função. Se o código de retorno for SEC_E_OK, não haverá segunda chamada de InitializeSecurityContext (Geral) e não será esperada resposta do servidor. Se o código de retorno for SEC_I_CONTINUE_NEEDED, o cliente esperará um token em resposta do servidor e o passará em uma segunda chamada para InitializeSecurityContext (Geral). O código de retorno SEC_I_COMPLETE_NEEDED indica que o cliente deve concluir a compilação da mensagem e chamar a função CompleteAuthToken. O código SEC_I_COMPLETE_AND_CONTINUE incorpora estas duas ações.

Se InitializeSecurityContext (Geral) retornar com êxito na primeira (ou única) chamada, o chamador deverá chamar a função DeleteSecurityContext no identificador retornado, mesmo que a chamada falhe em uma etapa posterior da troca de autenticação.

O cliente poderá chamar InitializeSecurityContext (Geral) novamente depois de concluir isso com êxito. Isso indica ao pacote de segurança que uma nova autenticação é desejada.

Os chamadores do modo kernel têm as seguintes diferenças: o nome de destino é uma cadeia de caracteres Unicode que deve ser alocada na memória virtual usando VirtualAlloc e ela não deve ser alocada a partir do pool. Os buffers passados e fornecidos em pInput e pOutput devem estar na memória virtual, não no pool.

Ao usar o SSP do Schannel, se a função retornar SEC_I_INCOMPLETE_CREDENTIALS, verifique se foi especificado um certificado válido e confiável em suas credenciais. O certificado é especificado ao chamar a função AcquireCredentialsHandle (Geral). O certificado deve ser um certificado de autenticação de cliente emitido por uma AC (autoridade de certificação) confiável para o servidor. Para obter uma lista dos ACs confiáveis para o servidor, chame a função QueryContextAttributes (Geral) e especifique o atributo SECPKG_ATTR_ISSUER_LIST_EX.

Ao usar o SSP do Schannel, depois que um aplicativo cliente recebe um certificado de autenticação de uma AC confiável para o servidor, o aplicativo cria uma nova credencial chamando a função AcquireCredentialsHandle (Geral) e chamando InitializeSecurityContext (Geral) novamente, especificando a credencial nova no parâmetro phCredential.

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]
Cabeçalho	Sspi.h (inclui Security.h)
Biblioteca	Secur32.lib
DLL	Secur32.dll
Nomes Unicode e ANSI	InitializeSecurityContextW (Unicode) e InitializeSecurityContextA (ANSI)