Compartilhar via

Função AcceptSecurityContext (Digest)

  • Artigo

A função 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. O cliente remoto usa a função InitializeSecurityContext (Digest) 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,
  _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. Para recuperar esse identificador, o servidor chama a função AcquireCredentialsHandle (Digest) com o sinalizador SECPKG_CRED_INBOUND ou SECPKG_CRED_BOTH definido.

phContext [in, out, optional]

Um ponteiro para uma estrutura CtxtHandle. Na primeira chamada para AcceptSecurityContext (Digest), esse ponteiro é NULL. Nas 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 (Digest). 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 (Digest) que contém o descritor do buffer de entrada.

A tabela a seguir mostra a configuração do buffer para Digest HTTP. O primeiro buffer deve ser do tipo SECBUFFER_TOKEN e o resto deve ser do tipo SECBUFFER_PKG_PARAMS. SASL requer apenas buffer zero.

Nº de buffer/tipo de buffer Significado
0
SECBUFFER_TOKEN		 Vazio para a primeira chamada e a resposta de desafio recebida do cliente para a segunda chamada.
1
SECBUFFER_PKG_PARAMS		 Método. Os caracteres estão no formato wireline da linha de solicitação. Caracteres US ASCII de byte único.
2
SECBUFFER_PKG_PARAMS		 Reservado.
3
SECBUFFER_PKG_PARAMS		 HEntity. Representação hexadecimal de H (corpo-entidade). Caracteres US ASCII de byte único.
4
SECBUFFER_PKG_PARAMS		 Realm. Cadeia de caracteres de realm para o desafio. Cadeia de caracteres Unicode que deve ser representável em US ASCII.
5
SECBUFFER_CHANNEL_BINDINGS | SECBUFFER_READONLY		 Contém o valor do token de associação do canal.
Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: esse valor não é compatível.

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 Digest aloca 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 ligação de canal de terminal não é conhecido.
Este valor é mutuamente exclusivo com ASC_REQ_PROXY_BINDINGS.
Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: esse valor não é compatível.
ASC_REQ_CONFIDENTIALITY Criptografe e descriptografe mensagens.
O Digest SSP oferece suporte a esse sinalizador apenas para SASL.
ASC_REQ_PROXY_BINDINGS Indica que o Digest requer associação de canal.
Este valor é mutuamente exclusivo com ASC_REQ_ALLOW_MISSING_BINDINGS.
Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: esse valor não é compatível.
ASC_REQ_CONNECTION O contexto de segurança não identificará as mensagens de formatação.
ASC_REQ_EXTENDED_ERROR A parte remota será notificada quando ocorrerem erros.
ASC_REQ_HTTP (0x10000000) Use o Digest para HTTP. Omita este sinalizador para usar o Digest como um mecanismo SASL.
ASC_REQ_INTEGRITY Assine mensagens e verifique assinaturas.
ASC_REQ_REPLAY_DETECT Detecte pacotes repetidos.
ASC_REQ_SEQUENCE_DETECT Detectar mensagens recebidas fora da sequência.

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.

Este parâmetro não é usado com Digest SSP. Ao usar o Digest SSP, especifique zero para esse parâmetro.

phNewContext [in, out, optional]

Um ponteiro para uma estrutura CtxtHandle. Na primeira chamada para AcceptSecurityContext (Digest), este ponteiro recebe o novo identificador de contexto. Nas chamadas subsequentes, phNewContext pode ser igual ao identificador especificado no parâmetro phContext. phNewContext nunca deverá ser NULL.

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 (Digest). 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.

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

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.

Este parâmetro é definido para um tempo máximo constante. Não há tempo de expiração para contextos ou credenciais ou credenciais de segurança do Digest ou ao usar o SSP do Digest.

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:

Código de retorno + valor Descrição
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:
-O nome de domínio da parte autenticadora está incorreto.
-O domínio não está disponível.
-A relação de confiança falhou.
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 um token de saída foi gerado pela função, ele deverá ser enviado ao processo cliente.
SEC_E_SECURITY_QOS_FAILED
0x80090332L		 A função falhou. Um sinalizador de atributo de contexto inválido foi especificado no parâmetro fContextReq.
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 então espera por um token de retorno do cliente e então faz outra chamada para AcceptSecurityContext (Digest).
SEC_I_COMPLETE_NEEDED
0x00090313L		 A função foi bem-sucedida. O servidor deve terminar de construir a mensagem do cliente e então chamar a função 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 (Digest).
STATUS_LOGON_FAILURE
0xC000006DL		 A função falhou. A função AcceptSecurityContext (Digest) foi chamada depois que o contexto especificado foi estabelecido.
SEC_E_BAD_BINDINGS
0x80090346L		 A função falhou. A política de associação de canal não foi atendida.

Comentários

A função AcceptSecurityContext (Digest) é a contraparte do servidor para a função InitializeSecurityContext (Digest).

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 especificar que os clientes devem ser capazes de usar uma informação confidencial ou com integridade verificada e pode rejeitar clientes que não conseguem atender a essa demanda. Como alternativa, um servidor não pode exigir nada e tudo o que o cliente pode fornecer ou exige é retornado no parâmetro pfContextAttr.

Para um pacote que permite autenticação de múltiplos trechos, como autenticação mútua, a sequência de chamada é a seguinte:

  1. O cliente transmite um token para o servidor.
  2. O servidor chama AcceptSecurityContext (Digest) pela primeira vez, o que gera um token de resposta que é então enviado ao cliente.
  3. O cliente recebe o token e o passa para InitializeSecurityContext (Digest). Se InitializeSecurityContext (Digest) retornar SEC_E_OK, a autenticação mútua foi concluída e uma sessão segura pode começar. Se InitializeSecurityContext (Digest) retornar um código de erro, a negociação de autenticação mútua será encerrada. Caso contrário, o token de segurança retornado por InitializeSecurityContext (Digest) é enviado ao cliente e as etapas 2 e 3 são repetidas.
  4. Não use o valor phContext em chamadas simultâneas para AcceptSecurityContext (Digest). A implementação nos provedores de segurança não é segura para thread.

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

O parâmetro pfContextAttr é válido em qualquer retorno bem-sucedido, mas, somente no retorno final bem-sucedido, você 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 final são suficientes. Se, 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 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

Confira também

Funções SSPI

DeleteSecurityContext

InitializeSecurityContext (Digest)