Função AcceptSecurityContext (Geral)
A função AcceptSecurityContext (Geral) permite que o componente de servidor de um aplicativo de transporte estabeleça um contexto de segurança entre o servidor e um cliente remoto. O cliente remoto usa a função InitializeSecurityContext (Geral) para iniciar o processo de estabelecimento de um contexto de segurança. O servidor pode exigir um ou mais tokens de resposta do cliente remoto para concluir o estabelecimento do contexto de segurança.
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 |
|---|---|
| AcceptSecurityContext (CredSSP) | Permite que o componente de servidor de um aplicativo de transporte estabeleça um contexto de segurança entre o servidor e um cliente remoto usando o CredSSP (Provedor de Suporte de Segurança de Credencial). |
| AcceptSecurityContext (Digest) | Permite que o componente de servidor de um aplicativo de transporte estabeleça um contexto de segurança entre o servidor e um cliente remoto que está usando o Digest. |
| AcceptSecurityContext (Kerberos) | Permite que o componente de servidor de um aplicativo de transporte estabeleça um contexto de segurança entre o servidor e um cliente remoto que está usando Kerberos. |
| AcceptSecurityContext (Negotiate) | Permite que o componente de servidor de um aplicativo de transporte estabeleça um contexto de segurança entre o servidor e um cliente remoto que está usando Negotiate. |
| AcceptSecurityContext (NTLM) | Permite que o componente de servidor de um aplicativo de transporte estabeleça um contexto de segurança entre o servidor e um cliente remoto que está usando o NTLM. |
| AcceptSecurityContext (Schannel) | Permite que o componente de servidor de um aplicativo de transporte estabeleça um contexto de segurança entre o servidor e um cliente remoto que está usando o Schannel. |
Sintaxe
SECURITY_STATUS SEC_Entry AcceptSecurityContext(
_In_opt_ PCredHandle phCredential,
_Inout_opt_ PCtxtHandle phContext,
_In_opt_ PSecBufferDesc pInput,
_In_ ULONG fContextReq,
_In_ ULONG TargetDataRep,
_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 do servidor. O servidor chama a função AcquireCredentialsHandle (Geral) com o sinalizador SECPKG_CRED_INBOUND ou SECPKG_CRED_BOTH definido para recuperar esse identificador.
phContext[in, out]
Um ponteiro para uma estrutura CtxtHandle . Na primeira chamada para AcceptSecurityContext (Geral), esse ponteiro é NULL. Em chamadas subsequentes, phContext é o identificador para o contexto parcialmente formado que foi retornado no parâmetro phNewContext pela primeira chamada.
Aviso
Não use o mesmo identificador de contexto em chamadas simultâneas para AcceptSecurityContext (Geral). A implementação da API nos provedores de serviços de segurança não é thread-safe.
pInput[in, optional]
Um ponteiro para uma estrutura SecBufferDesc gerada por uma chamada de cliente para InitializeSecurityContext (Geral) que contém o descritor do buffer de entrada.
Ao usar o SSP do Schannel, o primeiro buffer deve ser do tipo SECBUFFER_TOKEN e conter o token de segurança recebido do cliente. O segundo buffer deve ser do tipo SECBUFFER_EMPTY.
Ao usar os SSPs Negotiate, Kerberos ou NTLM, as informações de associação de canal podem ser especificadas passando uma estrutura SecBuffer do tipo SECBUFFER_CHANNEL_BINDINGS além dos buffers gerados pela chamada para a função InitializeSecurityContext (Geral ). As informações de associação de canal para o buffer de associação de canal podem ser obtidas chamando a função QueryContextAttributes (Schannel) no contexto Schannel que o cliente usou para autenticar.
fContextReq[in]
Sinalizadores de bit que especificam os atributos exigidos pelo servidor para estabelecer o contexto. Os sinalizadores de bits podem ser combinados usando operações OR bit a bit. Esse parâmetro pode usar um dos valores a seguir.
| Valor | Significado |
|---|---|
| ASC_REQ_ALLOCATE_MEMORY | Digest e Schannel alocarão buffers de saída para você. Quando terminar de usar os buffers de saída, libere-os chamando a função FreeContextBuffer . |
| ASC_REQ_ALLOW_MISSING_BINDINGS | Indica que o Digest não requer associações de canal para canais internos e externos. Esse valor é usado para compatibilidade com versões anteriores quando o suporte para associação de canal de ponto de extremidade não é conhecido. Esse valor é mutuamente exclusivo com ASC_REQ_PROXY_BINDINGS. Esse valor é compatível apenas com o SSP do Digest. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Não há suporte para esse valor. |
| ASC_REQ_CONFIDENTIALITY | Criptografar e descriptografar mensagens. O SSP do Digest dá suporte a esse sinalizador somente para SASL. |
| ASC_REQ_CONNECTION | O contexto de segurança não manipulará a formatação de mensagens. |
| ASC_REQ_DELEGATE | O servidor tem permissão para representar o cliente. Válido para Kerberos. Ignore esse sinalizador para delegação restrita. |
| ASC_REQ_EXTENDED_ERROR | Quando ocorrerem erros, a parte remota será notificada. |
| ASC_REQ_HTTP (0x10000000) | Use Digest para HTTP. Omita esse sinalizador para usar o Digest como um mecanismo SASL. |
| ASC_REQ_INTEGRITY | Assinar mensagens e verificar assinaturas. O Schannel não dá suporte a esse sinalizador. |
| ASC_REQ_MUTUAL_AUTH | O cliente é necessário para fornecer um certificado a ser usado para autenticação do cliente. Esse sinalizador tem suporte apenas pelo Schannel. |
| ASC_REQ_PROXY_BINDINGS | Indica que o Digest requer associação de canal. Esse valor é mutuamente exclusivo com ASC_REQ_ALLOW_MISSING_BINDINGS. Esse valor é compatível apenas com o SSP do Digest. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Não há suporte para esse valor. |
| ASC_REQ_REPLAY_DETECT | Detectar pacotes reproduzidos. |
| ASC_REQ_SEQUENCE_DETECT | Detectar mensagens recebidas fora da sequência. |
| ASC_REQ_STREAM | Suporte a uma conexão orientada a fluxo. Esse sinalizador tem suporte apenas pelo Schannel. |
Para possíveis sinalizadores de atributo e seus significados, consulte Requisitos de contexto. Os sinalizadores usados para esse parâmetro são prefixados com ASC_REQ, por exemplo, ASC_REQ_DELEGATE.
Os atributos solicitados podem não ter suporte do cliente. Para obter mais informações, consulte o parâmetro pfContextAttr .
TargetDataRep[in]
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 SSPs Schannel ou Digest. Quando você usa SSPs Schannel ou Digest, especifique zero para esse parâmetro.
phNewContext[in, out, optional]
Um ponteiro para uma estrutura CtxtHandle . Na primeira chamada para AcceptSecurityContext (Geral), esse ponteiro recebe o novo identificador de contexto. Em chamadas subsequentes, phNewContext pode ser o mesmo que o identificador especificado no parâmetro phContext .
phNewContext nunca deve ser NULL.
pOutput[in, out, optional]
Um ponteiro para uma estrutura SecBufferDesc que contém o descritor de buffer de saída. Esse buffer é enviado ao cliente para entrada em chamadas adicionais para InitializeSecurityContext (Geral). Um buffer de saída pode ser gerado mesmo que a função retorne SEC_E_OK. Qualquer buffer gerado deve ser enviado de volta para o aplicativo cliente.
Ao usar o Schannel, na saída, esse buffer recebe um token para o contexto de segurança. O token deve ser enviado ao cliente. A função também pode retornar um buffer do tipo SECBUFFER_EXTRA. 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á.
pfContextAttr[out]
Um ponteiro para uma variável que recebe 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 ASC_RET, por exemplo, ASC_RET_DELEGATE.
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.
ptsTimeStamp[out, optional]
Um ponteiro para uma estrutura TimeStamp que recebe o tempo de expiração do contexto. Recomendamos que o pacote de segurança sempre retorne esse valor no horário local.
Esse parâmetro é definido como um tempo máximo constante. Não há tempo de expiração para credenciais ou contextos de segurançadigest ou ao usar o SSP digest.
Isso é opcional ao usar o SSP do Schannel. Quando a parte remota fornece um certificado a ser usado para autenticação, esse parâmetro recebe o tempo de expiração desse certificado. Se nenhum certificado tiver sido fornecido, um valor de tempo máximo será retornado.
Observação
Até a última chamada do processo de autenticação, o tempo de expiração do contexto pode estar incorreto porque mais informações serão fornecidas durante os estágios posteriores da negociação. Portanto, ptsTimeStamp deve ser NULL até a última chamada para a função.
Retornar valor
Essa função retorna um dos valores a seguir.
| Código/valor de retorno | Descrição |
|---|---|
| A função falhou. A política de associação de canal não foi atendida. |
| A função foi bem-sucedida. Os dados no buffer de entrada estão incompletos. O aplicativo deve ler dados adicionais do cliente e chamar [AcceptSecurityContext (Geral)](acceptsecuritycontext--general.md) novamente. Esse valor pode ser retornado ao usar o SSP do Schannel. Para obter mais informações sobre esse valor retornado, consulte [AcceptSecurityContext (Schannel)](acceptsecuritycontext--schannel.md). |
| A função falhou. Não há memória suficiente disponível para concluir a ação solicitada. |
| A função falhou. Ocorreu um erro que não foi mapeado para um código de erro SSPI. |
| A função falhou. O identificador passado para a função não é válido. |
| A função falhou. O token passado para a função não é válido. |
| Falha no logon. |
| A função falhou. Nenhuma autoridade pode ser contatada para autenticação. Isso pode ocorrer devido às seguintes condições:
|
| A função falhou. O identificador de credenciais especificado no parâmetro phCredential não é válido. Esse valor pode ser retornado ao usar o Digest ou o SSP do Schannel. |
| A função foi bem-sucedida. O [*contexto de segurança*](.. /secgloss/s-gly.md) recebido do cliente foi aceito. Se um token de saída tiver sido gerado pela função , ele deverá ser enviado para o processo do cliente. |
| A função falhou. Um sinalizador de atributo de contexto que não é válido foi especificado no parâmetro fContextReq . Esse valor pode ser retornado ao usar o Digest SSP. |
| A função falhou. Um sinalizador de atributo de contexto que não é válido (ASC_REQ_DELEGATE ou ASC_REQ_PROMPT_FOR_CREDS) foi especificado no parâmetro fContextReq . Esse valor pode ser retornado ao usar o SSP do Schannel. |
| A função foi bem-sucedida. O servidor deve chamar [CompleteAuthToken](/windows/win32/api/sspi/nf-sspi-completeauthtoken) e passar o token de saída para o cliente. Em seguida, o servidor aguarda um token de retorno do cliente e faz outra chamada para [AcceptSecurityContext (Geral)](acceptsecuritycontext--general.md). |
| A função foi bem-sucedida. O servidor deve concluir a compilação da mensagem do cliente e, em seguida, chamar a função [CompleteAuthToken](/windows/win32/api/sspi/nf-sspi-completeauthtoken). |
| A função foi bem-sucedida. O servidor deve enviar o token de saída para o cliente e aguardar um token retornado. O token retornado deve ser passado em pInput para outra chamada para [AcceptSecurityContext (Geral)](acceptsecuritycontext--general.md). |
| A função falhou. A função [AcceptSecurityContext (Geral)](acceptsecuritycontext--general.md) foi chamada depois que o contexto especificado foi estabelecido. Esse valor pode ser retornado ao usar o Digest SSP. |
Comentários
A função AcceptSecurityContext (Geral) é a equivalente do servidor à função InitializeSecurityContext (Geral ).
Quando o servidor recebe uma solicitação de um cliente, o servidor usa o parâmetro fContextReq para especificar o que ele requer da sessão. Dessa forma, um servidor pode especificar que os clientes devem ser capazes de usar uma sessão confidencial ou com verificação de integridade e pode rejeitar clientes que não podem atender a essa demanda. Como alternativa, um servidor não pode exigir nada e tudo o que o cliente pode fornecer ou exigir é retornado no parâmetro pfContextAttr .
Para um pacote que dá suporte à autenticação de várias etapas, como autenticação mútua, a sequência de chamadas é a seguinte:
- O cliente transmite um token para o servidor.
- O servidor chama AcceptSecurityContext (Geral) pela primeira vez, o que gera um token de resposta que é enviado ao cliente.
- O cliente recebe o token e o passa para InitializeSecurityContext (Geral). Se InitializeSecurityContext (Geral) retornar SEC_E_OK, a autenticação mútua será concluída e uma sessão segura poderá começar. Se InitializeSecurityContext (Geral) retornar um código de erro, a negociação de autenticação mútua terminará. Caso contrário, o token de segurança retornado por InitializeSecurityContext (Geral) será enviado ao cliente e as etapas 2 e 3 serão repetidas.
- Não use o valor phContext em chamadas simultâneas para AcceptSecurityContext (Geral). A implementação nos provedores de segurança não é thread-safe.
Os parâmetros fContextReq e pfContextAttr são bitmasks que representam vários atributos de contexto. Para obter uma descrição dos vários atributos, consulte Requisitos de contexto.
Observação
O parâmetro pfContextAttr é válido em qualquer retorno bem-sucedido, mas somente no retorno final bem-sucedido deve examinar os sinalizadores relativos aos aspectos de segurança do contexto. Os retornos intermediários podem definir, por exemplo, o sinalizador ISC_RET_ALLOCATED_MEMORY.
O chamador é responsável por determinar se os atributos de contexto finais são suficientes. Se, por exemplo, a confidencialidade (criptografia) foi solicitada, mas não pôde ser estabelecida, alguns aplicativos podem optar por desligar a conexão imediatamente. Se o contexto de segurança não puder ser estabelecido, o servidor deverá liberar o contexto parcialmente criado chamando a função DeleteSecurityContext . Para obter informações sobre quando chamar a função DeleteSecurityContext , consulte DeleteSecurityContext.
Depois que o contexto de segurança for estabelecido, o aplicativo de servidor poderá usar a função QuerySecurityContextToken para recuperar um identificador para a conta de usuário para a qual o certificado do cliente foi mapeado. Além disso, o servidor pode usar a função ImpersonateSecurityContext para representar o usuário.
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 (incluir Security.h) |
| Biblioteca | Secur32.lib |
| DLL | Secur32.dll |