Função InitializeSecurityContextA (sspi.h)
A função
Normalmente, a função
Para obter informações sobre como usar essa função com um provedor de suporte de segurança específico (SSP), consulte os tópicos a seguir.
Sintaxe
SECURITY_STATUS SEC_ENTRY InitializeSecurityContextA(
[in, optional] PCredHandle phCredential,
[in, optional] PCtxtHandle phContext,
SEC_CHAR *pszTargetName,
[in] unsigned long fContextReq,
[in] unsigned long Reserved1,
[in] unsigned long TargetDataRep,
[in, optional] PSecBufferDesc pInput,
[in] unsigned long Reserved2,
[in, out, optional] PCtxtHandle phNewContext,
[in, out, optional] PSecBufferDesc pOutput,
[out] unsigned long *pfContextAttr,
[out, optional] PTimeStamp ptsExpiry
);
Parâmetros
[in, optional] phCredential
Um identificador para as credenciais retornados por AcquireCredentialsHandle (Geral). Esse identificador é usado para criar o contexto de segurança . A função
[in, optional] phContext
Um ponteiro para uma estrutura de
Esse parâmetro é opcional com o SSP do Microsoft Digest e pode ser definido como NULL.
Ao usar o SSP do Schannel, na primeira chamada para InitializeSecurityContext (Geral), especifique NULL. Em chamadas futuras, especifique o token recebido no parâmetro phNewContext
pszTargetName
TBD
[in] fContextReq
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 são prefixados com ISC_REQ_, por exemplo, ISC_REQ_DELEGATE. Esse parâmetro pode ser um ou mais dos sinalizadores de atributos a seguir.
| Valor | Significado |
|---|---|
|
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. |
|
Criptografar mensagens usando a função EncryptMessage. |
|
O contexto de segurança não tratará as mensagens de formatação. Esse valor é o padrão para os pacotes de segurança Kerberos, Negotiate e NTLM. |
|
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. |
|
Quando ocorrerem erros, a parte remota será notificada. |
|
Use o Digest para HTTP. Omita esse sinalizador para usar o Digest como um mecanismo SASL. |
|
Assine mensagens e verifique as assinaturas usando as funções EncryptMessage e MakeSignature. |
|
O Schannel não deve autenticar o servidor automaticamente. |
|
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 seja executada, apenas que a política de autenticação do serviço esteja satisfeita. Para garantir que a autenticação mútua seja executada, chame a função
|
|
Se esse sinalizador estiver definido, o sinalizador ISC_REQ_INTEGRITY será ignorado.
Esse valor só tem suporte nos pacotes de segurança negotiate e kerberos . |
|
Detecte mensagens reproduzidas que foram codificadas usando as funções EncryptMessage ou MakeSignature. |
|
Detectar mensagens recebidas fora da sequência. |
|
Dê suporte a uma conexão orientada a fluxo. |
|
Um novo chave de sessão deve ser negociado.
Esse valor é compatível apenas com o pacote de segurança Kerberos. |
|
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.
[in] Reserved1
Esse parâmetro é reservado e deve ser definido como zero.
[in] TargetDataRep
A representação de dados, como 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.
[in, optional] pInput
Um ponteiro para uma estrutura de
[in] Reserved2
Esse parâmetro é reservado e deve ser definido como zero.
[in, out, optional] phNewContext
Um ponteiro para uma estrutura de
Ao usar o SSP do Schannel, em chamadas após a primeira chamada, passe o identificador retornado aqui como o parâmetro phContext
[in, out, optional] pOutput
Um ponteiro para uma estrutura
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 do tipo SECBUFFER_ALERT. Na saída, se um alerta for gerado, esse buffer conterá informações sobre esse alerta e a função falhará.
[out] pfContextAttr
Um 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 que não estão relacionados à segurança, como o sinalizador ASC_RET_ALLOCATED_MEMORY, podem ser verificados antes do retorno final.
[out, optional] ptsExpiry
Um ponteiro para uma estrutura
Não há tempo de expiração para contextos de segurança do SSP do Microsoft Digest ou credenciais de .
Valor de retorno
Se a função for bem-sucedida, a função retornará um dos seguintes códigos de êxito.
| Código de retorno | Descrição |
|---|---|
|
O cliente deve chamar CompleteAuthToken e, em seguida, passar a saída para o servidor. Em seguida, o cliente aguarda um token retornado e o passa, em outra chamada, para InitializeSecurityContext (Geral). |
|
O cliente deve concluir a criação da mensagem e chamar a função CompleteAuthToken. |
|
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. |
|
Use com o Schannel. O servidor solicitou a autenticação do cliente e as credenciais fornecidas não incluem um certificado ou o certificado não foi emitido por uma autoridade de certificação confiável pelo servidor. Para obter mais informações, consulte Comentários. |
|
Use com o Schannel. Os dados de toda a mensagem não foram lidos do fio.
Quando esse valor é retornado, o buffer |
|
O contexto de segurança foi inicializado com êxito. Não há necessidade de outra chamada InitializeSecurityContext (Geral). Se a função retornar um token de saída, ou seja, se o SECBUFFER_TOKEN em pOutput for de 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.
Observações
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
Para um contexto de segurança de duas etapas, a sequência de chamadas é a seguinte:
- 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 de 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) pode retornar um token, que o servidor envia ao cliente para uma segunda chamada para InitializeSecurityContext (Geral) se a primeira chamada retornada SEC_I_CONTINUE_NEEDED.
- 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 para o identificador que foi retornado da última chamada. O token recebido do servidor é fornecido no parâmetro pInput.
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 , mais de uma chamada para essa função pode ser necessária, 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 máscaras de bits 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 qualquer retorno bem-sucedido, mas somente no retorno final bem-sucedido você deve examinar os sinalizadores que pertencem a aspectos de segurança do contexto. Os retornos intermediários podem definir, por exemplo, o sinalizador de ISC_RET_ALLOCATED_MEMORY.
Se o sinalizador de 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 forte emparelhamento de pacote de segurança e aplicativo quando apropriado.
Se ISC_REQ_ALLOCATE_MEMORY tiver sido especificado, o chamador deverá liberar a memória chamando a função
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á uma segunda chamada InitializeSecurityContext (Geral) e nenhuma resposta do servidor será esperada. Se o código de retorno for SEC_I_CONTINUE_NEEDED, o cliente espera um token em resposta do servidor e o passa em uma segunda chamada para InitializeSecurityContext (Geral). O código de retorno SEC_I_COMPLETE_NEEDED indica que o cliente deve concluir a criação da mensagem e chamar a função
Se InitializeSecurityContext (Geral) retornará êxito na primeira (ou somente) chamada, o chamador deverá eventualmente chamar a função DeleteSecurityContext no identificador retornado, mesmo que a chamada falhe em uma etapa posterior da troca de autenticação.
O cliente pode chamar InitializeSecurityContext (Geral) novamente depois de ter sido concluído com êxito. Isso indica ao pacote de segurança que uma reautenticação é desejada.
Os chamadores do modo kernel têm as seguintes diferenças: o nome de destino é uma cadeia de Unicode
Ao usar o SSP do Schannel, se a função retornar SEC_I_INCOMPLETE_CREDENTIALS, verifique se você especificou 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 autoridade de certificação (AC) confiável pelo servidor. Para obter uma lista dos CAs confiáveis pelo servidor, chame a função
Ao usar o SSP do Schannel, depois que um aplicativo cliente recebe um certificado de autenticação de uma AC confiável pelo servidor, o aplicativo cria uma nova credencial chamando a função
Nota
O cabeçalho sspi.h define InitializeSecurityContext 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 XP [somente aplicativos da área de trabalho] |
| 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 |