Função InitializeSecurityContext (Schannel)

A função InitializeSecurityContext (Schannel) inicia o contexto de segurança de saída do lado do cliente a partir de um identificador de credencial. A função é usada para criar um contexto de segurança entre o aplicativo cliente e um par remoto. InitializeSecurityContext (Schannel) retorna um token que o cliente deve passar para o peer remoto, que o peer, por sua vez, envia para a implementação de segurança local por meio da chamada AcceptSecurityContext (Schannel ). O token gerado deve ser considerado opaco por todos os chamadores.

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

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

phCredencial[in, optional]

Um identificador para as credenciais retornadas por AcquireCredentialsHandle (Schannel). Esse identificador é usado para criar o contexto de segurança. A função InitializeSecurityContext (Schannel) requer pelo menos credenciais OUTBOUND na primeira chamada. Em chamadas subsequentes, isso pode ser NULL.

phContexto[in, optional]

Um ponteiro para um CtxtHandle estrutura. Na primeira chamada para InitializeSecurityContext (Schannel), esse ponteiro é NULL. Em chamadas futuras, esse parâmetro é um ponteiro para o identificador para o contexto parcialmente formado retornado no parâmetro phNewContext pela primeira chamada para essa função.

pszTargetName[in, optional]

Um ponteiro para uma cadeia de caracteres terminada em nulo que identifica exclusivamente o servidor de destino. Schannel usa esse valor para verificar o certificado do servidor. Schannel também usa esse valor para localizar a sessão no cache de sessão ao restabelecer uma conexão. A sessão em cache é usada somente se todas as seguintes condições forem atendidas:

• O nome do destino é o mesmo.
• A entrada de cache não expirou.
• O processo de aplicação que chama a função é o mesmo.
• A sessão de logon é a mesma.
• O identificador de credenciais é o mesmo.

fContextReq[in]

Sinalizadores de bits que indicam solicitações para o contexto. Nem todos os pacotes suportam todos os requisitos. Os sinalizadores usados para este parâmetro são prefixados com ISC_REQ_, por exemplo, ISC_REQ_DELEGATE. Esse parâmetro pode ser um ou mais dos seguintes sinalizadores de atributos.

Os atributos solicitados podem não ser suportados pelo cliente. Para obter mais informações, consulte o parâmetro pfContextAttr.

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

Reservado1[in]

Este parâmetro é reservado e deve ser definido como zero.

[in] TargetDataRep

Este parâmetro não é usado com Schannel. Defina como zero.

pEntrada[in, optional]

Um ponteiro para uma estrutura SecBufferDesc que contém ponteiros para os buffers fornecidos como entrada para o 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 armazenar o token retornado pelo computador remoto.

Em chamadas para esta função após a chamada inicial, deve haver dois buffers. O primeiro tem o tipo SECBUFFER_TOKEN e contém o token recebido do servidor. O segundo buffer tem tipo SECBUFFER_EMPTY; defina os membros pvBuffer e cbBuffer como zero.

Reservado2[in]

Este parâmetro é reservado e deve ser definido como zero.

phNewContexto[in, out, optional]

Um ponteiro para um CtxtHandle estrutura. Na primeira chamada para InitializeSecurityContext (Schannel), 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 deve ser NULL.

pSaída[in, out, optional]

Um ponteiro para uma estrutura SecBufferDesc que contém ponteiros para a estrutura SecBuffer que recebe os dados de saída. Se um buffer foi 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 (através de ISC_REQ_ALLOCATE_MEMORY) e preencherá o endereço no descritor de buffer para o token de segurança.

Se o sinalizador ISC_REQ_ALLOCATE_MEMORY for especificado, o SSP Schannel alocará memória para o buffer e colocará as informações apropriadas no SecBufferDesc. Além disso, o chamador deve passar em 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á.

pfContextAttr[out]

Um ponteiro para uma variável para receber um conjunto de sinalizadores de bit 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 verifique se há atributos relacionados à segurança até que a chamada de função final retorne com êxito. Os sinalizadores de atributos que não estão relacionados à segurança, como o sinalizador ASC_RET_ALLOCATED_MEMORY, podem ser verificados antes do retorno final.

ptsExpiração[out, optional]

Um ponteiro para um TimeStamp estrutura 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. Este parâmetro é opcional e NULL deve ser passado para clientes de curta duração.

Valor de retorno

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

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

Observações

O chamador é responsável por determinar se os atributos de contexto finais 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 (Schannel) é usada por um cliente para inicializar um contexto de saída.

Para um contexto de segurança de duas pernas, a sequência de chamada é a seguinte:

1. O cliente chama a função com phContext definido como NULL e preenche o descritor de buffer com a mensagem de entrada.
2. 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.
3. 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 (Schannel ).
4. AcceptSecurityContext (Schannel) pode retornar um token, que o servidor envia ao cliente para uma segunda chamada para InitializeSecurityContext (Schannel) se a primeira chamada retornou SEC_I_CONTINUE_NEEDED.

Para contextos de segurançade várias pernas, como autenticação mútua, a sequência de chamada é a seguinte:

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

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

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 bem-sucedido final você deve examinar os sinalizadores que pertencem aos aspetos 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 . Esta não é uma solução genérica, mas permite um forte emparelhamento de pacote de segurança e aplicação quando apropriado.

Se ISC_REQ_ALLOCATE_MEMORY foi especificado, o chamador deve liberar a memória chamando a função FreeContextBuffer .

Por exemplo, o token de entrada pode ser o desafio de um LAN Manager. Nesse caso, o token de saída seria a resposta criptografada por NTLM ao desafio.

A ação que o cliente toma depende do código de retorno desta função. Se o código de retorno for SEC_E_OK, não haverá segunda chamada InitializeSecurityContext (Schannel) 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 (Schannel). 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 CompleteAuthToken . O código SEC_I_COMPLETE_AND_CONTINUE incorpora ambas as ações.

Se InitializeSecurityContext (Schannel) retornar êxito na primeira (ou única) 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 (Schannel) novamente depois de ter sido concluído 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; não deve ser atribuído a partir da piscina. Os buffers passados e fornecidos em pInput e pOutput devem estar na memória virtual, não no pool.

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 (Schannel ). O certificado deve ser um certificado de autenticação de cliente emitido por uma autoridade de certificação (CA) confiável pelo servidor. Para obter uma lista das autoridades de certificação confiáveis pelo servidor, chame a função QueryContextAttributes (Schannel) e especifique o atributo SECPKG_ATTR_ISSUER_LIST_EX.

Depois que um aplicativo cliente recebe um certificado de autenticação de uma autoridade de certificação confiável pelo servidor, o aplicativo cria uma nova credencial chamando a função AcquireCredentialsHandle (Schannel) e, em seguida, chamando InitializeSecurityContext (Schannel) novamente, especificando a nova credencial no parâmetro phCredential .

Requerimentos

Ver também

Funções SSPI

AcceptSecurityContext (Schannel)

AcquireCredentialsHandle (Schannel)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer

SecBuffer

SecBufferDesc