Função InitializeSecurityContext (CredSSP)

Artigo
03/18/2023

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

Normalmente, a função InitializeSecurityContext (CredSSP) é 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_        unsigned long  fContextReq,
  _Reserved_  unsigned long  Reserved1,
  _In_        unsigned long  TargetDataRep,
  _Inout_opt_ PSecBufferDesc pInput,
  _In_        unsigned long  Reserved2,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Out_opt_   PSecBufferDesc pOutput,
  _Out_       unsigned long  *pfContextAttr,
  _Out_opt_   PTimeStamp     ptsExpiry
);

Parâmetros

phCredential[in, optional]

Um identificador para as credenciais retornadas por AcquireCredentialsHandle (CredSSP). Esse identificador é usado para criar o contexto de segurança. A função InitializeSecurityContext (CredSSP) requer pelo menos credenciais OUTBOUND.

phContext[in, optional]

Um ponteiro para uma estrutura CtxtHandle . Na primeira chamada para InitializeSecurityContext (CredSSP), esse ponteiro é NULL. Na segunda chamada, esse parâmetro é um ponteiro para o identificador para o contexto parcialmente formado retornado no parâmetro phNewContext pela primeira chamada.

Na primeira chamada para InitializeSecurityContext (CredSSP), especifique NULL. Em chamadas futuras, especifique o token recebido no parâmetro phNewContext após a primeira chamada para essa função.

Aviso

Não use o mesmo identificador de contexto em chamadas simultâneas para InitializeSecurityContext (CredSSP). A implementação da API nos provedores de serviços de segurança não é thread-safe.

pTargetName[in, optional]

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

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

fContextReq[in]

Sinalizadores de bit 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
ISC_REQ_ALLOCATE_MEMORY `0x100`	O pacote de segurança aloca buffers de saída para o chamador. Quando terminar de usar os buffers de saída, libere-os chamando a função FreeContextBuffer .
ISC_REQ_CONNECTION `0x800`	O contexto de segurança não manipulará a formatação de mensagens.
ISC_REQ_EXTENDED_ERROR `0x4000`	Quando ocorrerem erros, a parte remota será notificada.
ISC_REQ_MANUAL_CRED_VALIDATION `0x80000`	O CredSSP (Provedor de Suporte à Segurança de Credencial) não deve autenticar o servidor automaticamente. Esse sinalizador sempre é definido ao usar CredSSP.
ISC_REQ_SEQUENCE_DETECT `0x8`	Detectar mensagens recebidas fora da sequência.
ISC_REQ_STREAM `0x8000`	Suporte a uma conexão orientada a fluxo.
ISC_REQ_USE_SUPPLIED_CREDS `0x80`	CredSSP não deve tentar fornecer credenciais para o cliente automaticamente.
ISC_REQ_DELEGATE `0x1`	Indica que as credenciais do usuário devem ser delegadas ao servidor. Se esse sinalizador não for especificado, um conjunto vazio de credenciais será delegado ao servidor. Windows Server 2008 e Windows Vista: Esse sinalizador é necessário.
ISC_REQ_MUTUAL_AUTH `0x2`	Indica que a autenticação do servidor não é necessária. As políticas de delegação ainda serão impostas se esse sinalizador não for especificado. Windows Server 2008 e Windows Vista: Esse sinalizador é ignorado.

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.

Reservado1[in]

Reservado. Esse parâmetro deve ser definido como zero.

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.

pInput[in, out, 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 manter o token retornado pelo computador remoto.

Em chamadas para essa 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 o tipo SECBUFFER_EMPTY; defina os membros pvBuffer e cbBuffer como zero.

Reservado2[in]

Reservado. Esse parâmetro deve ser definido como zero.

phNewContext[in, out, optional]

Um ponteiro para uma estrutura CtxtHandle . Na primeira chamada para InitializeSecurityContext (CredSSP), 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.

pOutput[out, optional]

Um ponteiro para uma estrutura SecBufferDesc . Essa estrutura, por sua vez, contém ponteiros para a estrutura SecBuffer que recebe os dados de saída. Se um buffer tiver sido 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 (por meio 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 CredSSP alocará memória para o buffer e colocará as informações apropriadas no SecBufferDesc.

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

Observação

Atributos de contexto específicos podem ser alterados durante a negociação com um par remoto.

ptsExpiry[out, optional]

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

Retornar valor

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

Código de retorno	Descrição
SEC_E_INCOMPLETE_MESSAGE	Os dados de toda a mensagem não foram lidos da transmissão. Quando esse valor é retornado, o buffer pInput contém uma estrutura SecBuffer com um membro BufferType de SECBUFFER_MISSING. O membro cbBuffer do SecBuffer especifica o número de bytes adicionais que a função deve ler do cliente antes que essa função seja bem-sucedida. Embora esse número nem sempre seja preciso, usá-lo pode ajudar a melhorar o desempenho evitando várias chamadas para essa função.
SEC_E_OK	O contexto de segurança foi inicializado com êxito. Não há necessidade de outra chamada InitializeSecurityContext (CredSSP ). 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 ao servidor.
SEC_I_COMPLETE_AND_CONTINUE	O cliente deve chamar CompleteAuthToken e, em seguida, passar a saída para o servidor. Em seguida, o cliente aguarda um token retornado e passa-o, em outra chamada, para InitializeSecurityContext (CredSSP).
SEC_I_COMPLETE_NEEDED	O cliente deve concluir a criação da mensagem e, em seguida, chamar a função CompleteAuthToken .
SEC_I_CONTINUE_NEEDED	O cliente deve enviar o token de saída para o servidor e aguardar um token de retorno. O cliente passa o token retornado em outra chamada para InitializeSecurityContext (CredSSP). O token de saída pode estar vazio.
SEC_I_INCOMPLETE_CREDENTIALS	O servidor solicitou a autenticação do cliente, mas as credenciais fornecidas não incluem um certificado ou o certificado não foi emitido por uma autoridade de certificação em que o servidor confia. Para obter mais informações, consulte Comentários.

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

Código de retorno	Descrição
SEC_E_INSUFFICIENT_MEMORY	Não há memória suficiente disponível para concluir a ação solicitada.
SEC_E_INTERNAL_ERROR	Ocorreu um erro que não foi mapeado para um código de erro SSPI.
SEC_E_INVALID_HANDLE	O identificador passado para a função não é válido.
SEC_E_INVALID_TOKEN	O token de entrada está malformado. As causas possíveis incluem um token corrompido em trânsito, um token de tamanho incorreto e um token passado para o pacote de segurança errado. Essa última condição pode acontecer se o cliente e o servidor não negociaram o pacote de segurança adequado.
SEC_E_LOGON_DENIED	Falha no logon.
SEC_E_NO_AUTHENTICATING_AUTHORITY	Nenhuma autoridade pode ser contatada para autenticação. O nome de domínio da parte autenticadora pode estar errado, o domínio pode estar inacessível ou pode ter havido uma falha na relação de confiança.
SEC_E_NO_CREDENTIALS	Nenhuma credencial está disponível no pacote de segurança.
SEC_E_TARGET_UNKNOWN	O destino não foi reconhecido.
SEC_E_UNSUPPORTED_FUNCTION	O valor do parâmetro fContextReq não é válido. Um sinalizador necessário não foi especificado ou um sinalizador que não tem suporte do CredSSP foi especificado.
SEC_E_WRONG_PRINCIPAL	A entidade de segurança que recebeu a solicitação de autenticação não é a mesma passada para o parâmetro pszTargetName . Esse erro indica uma falha na autenticação mútua.
SEC_E_DELEGATION_POLICY	A política não dá suporte à delegação de credenciais para o servidor de destino.
SEC_E_POLICY_NLTM_ONLY	A delegação de credenciais para o servidor de destino não é permitida quando a autenticação mútua não é obtida.
SEC_E_MUTUAL_AUTH_FAILED	Falha na autenticação do servidor quando o sinalizador ISC_REQ_MUTUAL_AUTH é especificado no parâmetro fContextReq .

Comentários

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 .

O cliente chama a função InitializeSecurityContext (CredSSP) para inicializar um contexto de saída.

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 buffers. 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 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 (CredSSP).
AcceptSecurityContext (CredSSP) pode retornar um token. O servidor envia esse token para o cliente por meio de uma segunda chamada InitializeSecurityContext (CredSSP) se a primeira chamada retornada SEC_I_CONTINUE_NEEDED.

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.

A inicialização de contexto de segurança pode exigir mais de uma chamada para essa função, 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 bitmasks que representam vários atributos de contexto. Para obter uma descrição dos vários atributos, consulte Requisitos de contexto. Embora o parâmetro pfContextAttributes seja válido em qualquer retorno bem-sucedido, você deve examinar os sinalizadores que pertencem a 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 .

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 . Embora essa não seja uma solução genérica, ela 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 FreeContextBuffer .

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 por 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á nenhuma segunda chamada InitializeSecurityContext (CredSSP) 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 (CredSSP). 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 essas duas ações.

Se InitializeSecurityContext (CredSSP) 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 (CredSSP) 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 caracteres Unicode que deve ser alocada na memória virtual usando VirtualAlloc; ele não deve ser alocado do pool. 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, marcar que as credenciais r passadas para a função AcquireCredentialsHandle (CredSSP) especificaram um certificado válido e confiável O certificado deve ser um certificado de autenticação de cliente emitido por uma autoridade de certificação confiável pelo servidor. Para obter uma lista das ACs confiáveis pelo servidor, chame a função QueryContextAttributes (CredSSP) com o atributo SECPKG_ATTR_ISSUER_LIST_EX .

Depois de receber um certificado de autenticação de uma autoridade de certificação em que o servidor confia, o aplicativo cliente cria uma nova credencial. Ele faz isso chamando a função AcquireCredentialsHandle (CredSSP) e, em seguida, chamando InitializeSecurityContext (CredSSP) novamente, especificando a nova credencial no parâmetro phCredential .

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Cabeçalho	Sspi.h (incluir Security.h)
Biblioteca	Secur32.lib
DLL	Secur32.dll