Função AcceptSecurityContext (CredSSP)
A funçã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. O cliente remoto chama a função InitializeSecurityContext (CredSSP) 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.
Sintaxe
SECURITY_STATUS SEC_ENTRY AcceptSecurityContext(
_In_opt_ PCredHandle phCredential,
_In_opt_ PCtxtHandle phContext,
_In_opt_ PSecBufferDesc pInput,
_In_ unsigned long fContextReq,
_In_ unsigned long TargetDataRep,
_Inout_opt_ PCtxtHandle phNewContext,
_Inout_opt_ PSecBufferDesc pOutput,
_Out_ unsigned long *pfContextAttr,
_Out_opt_ PTimeStamp ptsExpiry
);
Parâmetros
phCredential [in, optional]
Um identificador para as credenciais do servidor. Para recuperar esse identificador, o servidor chama a função AcquireCredentialsHandle (CredSSP) com o sinalizador SECPKG_CRED_INBOUND ou SECPKG_CRED_BOTH definido.
phContext [in, optional]
Um ponteiro para uma estrutura CtxtHandle. Na primeira chamada para AcceptSecurityContext (CredSSP), esse ponteiro é NULL. Nas chamadas subsequentes, phContext especifica o contexto parcialmente formado retornado no parâmetro phNewContext pela primeira chamada.
Aviso
Não use o mesmo identificador de contexto em chamadas simultâneas para AcceptSecurityContext (CredSSP). A implementação da API nos provedores de serviços de segurança não é segura para thread.
pInput [in, optional]
Um ponteiro para uma estrutura SecBufferDesc gerada por uma chamada do cliente para InitializeSecurityContext (CredSSP). A estrutura contém o descritor do buffer de entrada.
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.
fContextReq [in]
-Sinalizadores de bits 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 | O Credential Security Support Provider (CredSSP) alocará buffers de saída. Quando terminar de usar os buffers de saída, libere-os chamando a função FreeContextBuffer. |
| ASC_REQ_CONNECTION | O contexto de segurança não identificará as mensagens de formatação. |
| ASC_REQ_DELEGATE | O servidor tem permissão para representar o cliente. Ignore esse sinalizador para delegação restrita. |
| ASC_REQ_EXTENDED_ERROR | A parte remota será notificada quando ocorrerem erros. |
| ASC_REQ_REPLAY_DETECT | Detecte pacotes repetidos. |
| ASC_REQ_SEQUENCE_DETECT | Detectar mensagens recebidas fora da sequência. |
| ASC_REQ_STREAM | Dê suporte a uma conexão orientada por fluxo. |
Para possíveis sinalizadores de atributos e seus significados, consulte Requisitos de contexto. Os sinalizadores usados para esse parâmetro recebem o prefixo 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 a ordenação de bytes, no destino. Esse parâmetro pode ser SECURITY_NATIVE_DREP ou SECURITY_NETWORK_DREP.
phNewContext [in, out, optional]
Um ponteiro para uma estrutura CtxtHandle. Na primeira chamada para AcceptSecurityContext (CredSSP), este ponteiro recebe o novo identificador de contexto. Nas chamadas subsequentes, phNewContext pode ser igual ao identificador especificado no parâmetro phContext.
pOutput [in, out, optional]
Um ponteiro para uma estrutura SecBufferDesc que contém o descritor do buffer de saída. Este buffer é enviado ao cliente para entrada em chamadas adicionais para InitializeSecurityContext (CredSSP). Um buffer de saída pode ser gerado mesmo se a função retornar SEC_E_OK. Qualquer buffer gerado deve ser enviado de volta ao aplicativo cliente.
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.
pfContextAttr [out]
Um ponteiro para 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 recebem o prefixo ASC_RET, por exemplo, ASC_RET_DELEGATE.
Não verifique se há atributos relacionados à segurança até que a chamada de função final retorne com êxito. Sinalizadores de atributos não relacionados à segurança, como o sinalizador ASC_RET_ALLOCATED_MEMORY, podem ser verificados antes do retorno final.
ptsExpiry [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.
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 nas etapas posteriores da negociação. Portanto, ptsTimeStamp deve ser NULL até a última chamada para a função.
Valor retornado
Essa função retorna um dos seguintes valores.
| Valor/código retornado | Descrição |
|---|---|
| SEC_E_INCOMPLETE_MESSAGE 0x80090318L |
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 (CredSSP) novamente. |
| SEC_E_INSUFFICIENT_MEMORY 0x80090300L |
A função falhou. Não há memória suficiente disponível para concluir a ação solicitada. |
| SEC_E_INTERNAL_ERROR 0x80090304L |
A função falhou. Ocorreu um erro que não foi mapeado para um código de erro SSPI. |
| SEC_E_INVALID_HANDLE 0x80100003L |
A função falhou. O identificador passado para a função não é válido. |
| SEC_E_INVALID_TOKEN 0x80090308L |
A função falhou. O token passado para a função não é válido. |
| SEC_E_LOGON_DENIED 0x8009030CL |
O logon falhou. |
| SEC_E_NO_AUTHENTICATING_AUTHORITY 0x80090311L |
A função falhou. Nenhuma autoridade pode ser contatada para obter autenticação. Isso pode ser devido às seguintes condições:
|
| SEC_E_NO_CREDENTIALS 0x8009030EL |
A função falhou. O identificador de credenciais especificado no parâmetro phCredential não é válido. |
| SEC_E_OK 0x00000000L |
A função foi bem-sucedida. O contexto de segurança recebido do cliente foi aceito. Se a função gerou um token de saída, o token deverá ser enviado ao processo cliente. |
| SEC_E_UNSUPPORTED_FUNCTION 0x80090302L |
A função falhou. O parâmetro fContextReq especificou um sinalizador de atributo de contexto (ASC_REQ_DELEGATE ou ASC_REQ_PROMPT_FOR_CREDS) que não era válido. |
| SEC_I_COMPLETE_AND_CONTINUE 0x00090314L |
A função foi bem-sucedida. O servidor deve chamar CompleteAuthToken e passar o token de saída ao cliente. O servidor deve então esperar por um token de retorno do cliente antes de fazer outra chamada para AcceptSecurityContext (CredSSP). |
| SEC_I_COMPLETE_NEEDED 0x00090313L |
A função foi bem-sucedida. O servidor deve terminar de construir a mensagem do cliente antes de chamar CompleteAuthToken |
| SEC_I_CONTINUE_NEEDED 0x00090312L |
A função foi bem-sucedida. O servidor deve enviar o token de saída ao cliente e aguardar um token retornado. O token retornado deve ser passado em pInput para outra chamada para AcceptSecurityContext (CredSSP). |
Comentários
A função AcceptSecurityContext (CredSSP) é a contraparte do servidor da função InitializeSecurityContext (CredSSP).
Quando o servidor recebe uma solicitação de um cliente, ele usa o parâmetro fContextReq para especificar o que é necessário da sessão. Dessa forma, um servidor pode exigir que os clientes sejam capazes de usar uma sessão confidencial ou com integridade verificada; pode rejeitar clientes que não conseguem atender a essa demanda. Alternativamente, um servidor não pode exigir nada; tudo o que o cliente exige ou pode fornecer é retornado no parâmetro pfContextAttr.
Os parâmetros fContextReq e pfContextAttr 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.
Observação
Embora o parâmetro pfContextAttr seja válido em qualquer retorno bem-sucedido, você deve examinar os sinalizadores relativos aos aspectos de segurança do contexto somente no retorno final bem-sucedido. 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 final são suficientes. Por exemplo, se a confidencialidade (criptografia) foi solicitada, mas não pôde ser estabelecida, alguns aplicativos podem optar por encerrar 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.
Após o contexto de segurança ter sido estabelecido, o aplicativo do servidor poderá usar a função QuerySecurityContextToken para recuperar um identificador para a conta do 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�Vista [somente aplicativos da área de trabalho] |
| Servidor com suporte mínimo | Windows Server�2008 [somente aplicativos da área de trabalho] |
| Cabeçalho | Sspi.h (inclui Security.h) |
| Biblioteca | Secur32.lib |
| DLL | Secur32.dll |