Función InitializeSecurityContext (CredSSP)

Artículo
03/18/2023

La función InitializeSecurityContext (CredSSP) inicia el contexto de seguridad saliente del lado cliente desde un identificador de credenciales. La función crea un contexto de seguridad entre la aplicación cliente y un elemento del mismo nivel remoto. InitializeSecurityContext (CredSSP) devuelve un token que el cliente debe pasar al mismo nivel remoto; a su vez, el elemento del mismo nivel envía ese token a la implementación de seguridad local a través de la llamada a AcceptSecurityContext (CredSSP). Todos los autores de llamada deben considerar el token generado como opaco.

Normalmente, se llama a la función InitializeSecurityContext (CredSSP) en un bucle hasta que se establece un contexto de seguridad suficiente.

Sintaxis

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]

Identificador de las credenciales devueltas por AcquireCredentialsHandle (CredSSP) . Este identificador se usa para crear el contexto de seguridad. La función InitializeSecurityContext (CredSSP) requiere al menos credenciales OUTBOUND.

phContext[in, optional]

Puntero a una estructura CtxtHandle . En la primera llamada a InitializeSecurityContext (CredSSP), este puntero es NULL. En la segunda llamada, este parámetro es un puntero al identificador del contexto parcialmente formado devuelto en el parámetro phNewContext por la primera llamada.

En la primera llamada a InitializeSecurityContext (CredSSP), especifique NULL. En futuras llamadas, especifique el token recibido en el parámetro phNewContext después de la primera llamada a esta función.

Advertencia

No use el mismo identificador de contexto en llamadas simultáneas a InitializeSecurityContext (CredSSP) . La implementación de api en los proveedores de servicios de seguridad no es segura para subprocesos.

pTargetName[in, optional]

Puntero a una cadena terminada en null que identifica de forma única el servidor de destino. Schannel usa este valor para comprobar el certificado de servidor. Schannel también usa este valor para buscar la sesión en la memoria caché de sesión al restablecer una conexión. La sesión almacenada en caché solo se usa si se cumplen todas las condiciones siguientes:

El nombre de destino es el mismo.
La entrada de caché no ha expirado.
El proceso de aplicación que llama a la función es el mismo.
La sesión de inicio de sesión es la misma.
El identificador de credenciales es el mismo.

fContextReq[in]

Marcas de bits que indican solicitudes para el contexto. No todos los paquetes pueden admitir todos los requisitos. Las marcas usadas para este parámetro tienen el prefijo ISC_REQ_, por ejemplo, ISC_REQ_DELEGATE.

Este parámetro puede ser una o varias de las marcas de atributos siguientes.

Valor	Significado
ISC_REQ_ALLOCATE_MEMORY `0x100`	El paquete de seguridad asigna búferes de salida para el autor de la llamada. Cuando haya terminado de usar los búferes de salida, liberelos llamando a la función FreeContextBuffer .
ISC_REQ_CONNECTION `0x800`	El contexto de seguridad no controlará los mensajes de formato.
ISC_REQ_EXTENDED_ERROR `0x4000`	Cuando se produzcan errores, se notificará a la entidad remota.
ISC_REQ_MANUAL_CRED_VALIDATION `0x80000`	El proveedor de soporte técnico de seguridad de credenciales (CredSSP) no debe autenticar el servidor automáticamente. Esta marca siempre se establece cuando se usa CredSSP.
ISC_REQ_SEQUENCE_DETECT `0x8`	Detectar mensajes recibidos fuera de secuencia.
ISC_REQ_STREAM `0x8000`	Compatibilidad con una conexión orientada a flujos.
ISC_REQ_USE_SUPPLIED_CREDS `0x80`	CredSSP no debe intentar proporcionar credenciales para el cliente automáticamente.
ISC_REQ_DELEGATE `0x1`	Indica que las credenciales del usuario se van a delegar en el servidor. Si no se especifica esta marca, se delega un conjunto vacío de credenciales al servidor. Windows Server 2008 y Windows Vista: Esta marca es necesaria.
ISC_REQ_MUTUAL_AUTH `0x2`	Indica que no se requiere la autenticación del servidor. Las directivas de delegación se siguen aplicando si no se especifica esta marca. Windows Server 2008 y Windows Vista: Esta marca se omite.

Es posible que el cliente no admita los atributos solicitados. Para obtener más información, consulte el parámetro pfContextAttr .

Para obtener más descripciones de los distintos atributos, vea Requisitos de contexto.

Reserved1[in]

Reservado. Este parámetro debe establecerse en cero.

TargetDataRep[in]

Representación de datos, como el orden de bytes, en el destino. Este parámetro puede ser SECURITY_NATIVE_DREP o SECURITY_NETWORK_DREP.

pInput[in, out, optional]

Puntero a una estructura SecBufferDesc que contiene punteros a los búferes proporcionados como entrada al paquete. A menos que el servidor inicie el contexto de cliente, el valor de este parámetro debe estar NULL en la primera llamada a la función. En las llamadas posteriores a la función o cuando el servidor inició el contexto de cliente, el valor de este parámetro es un puntero a un búfer asignado con suficiente memoria para contener el token devuelto por el equipo remoto.

En las llamadas a esta función después de la llamada inicial, debe haber dos búferes. El primero tiene el tipo SECBUFFER_TOKEN y contiene el token recibido del servidor. El segundo búfer tiene SECBUFFER_EMPTY de tipo; establezca los miembros pvBuffer y cbBuffer en cero.

Reserved2[in]

Reservado. Este parámetro debe establecerse en cero.

phNewContext[in, out, optional]

Puntero a una estructura CtxtHandle . En la primera llamada a InitializeSecurityContext (CredSSP), este puntero recibe el nuevo identificador de contexto. En la segunda llamada, phNewContext puede ser el mismo que el identificador especificado en el parámetro phContext . phNewContext nunca debe ser NULL.

pOutput[out, optional]

Puntero a una estructura SecBufferDesc . Esta estructura a su vez contiene punteros a la estructura SecBuffer que recibe los datos de salida. Si se ha escrito un búfer como SEC_READWRITE en la entrada, estará allí en la salida. El sistema asignará un búfer para el token de seguridad si se solicita (a través de ISC_REQ_ALLOCATE_MEMORY) y rellena la dirección en el descriptor del búfer para el token de seguridad.

Si se especifica la marca ISC_REQ_ALLOCATE_MEMORY , CredSSP asignará memoria para el búfer y colocará la información adecuada en SecBufferDesc.

pfContextAttr[out]

Puntero a un conjunto de marcas de bits que indican los atributos del contexto establecido. Para obtener una descripción de los distintos atributos, vea Requisitos de contexto.

Las marcas usadas para este parámetro tienen el prefijo ISC_RET, como ISC_RET_DELEGATE. Para obtener una lista de valores válidos, consulte el parámetro fContextReq .

No compruebe los atributos relacionados con la seguridad hasta que la llamada de función final se devuelva correctamente. Las marcas de atributo que no están relacionadas con la seguridad, como la marca de ASC_RET_ALLOCATED_MEMORY , se pueden comprobar antes de la devolución final.

Nota:

Los atributos de contexto concretos pueden cambiar durante la negociación con un elemento del mismo nivel remoto.

ptsExpiry[out, optional]

Puntero a una estructura TimeStamp que recibe la hora de expiración del contexto. Se recomienda que el paquete de seguridad devuelva siempre este valor en la hora local. Este parámetro es opcional y NULL debe pasarse para clientes de corta duración.

Valor devuelto

Si la función se ejecuta correctamente, devuelve uno de los siguientes códigos de operación correcta.

Código devuelto	Descripción
SEC_E_INCOMPLETE_MESSAGE	Los datos de todo el mensaje no se leyeron de la conexión. Cuando se devuelve este valor, el búfer pInput contiene una estructura SecBuffer con un miembro BufferType de SECBUFFER_MISSING. El miembro cbBuffer de SecBuffer especifica el número de bytes adicionales que la función debe leer del cliente antes de que esta función se realice correctamente. Aunque este número no siempre es preciso, su uso puede ayudar a mejorar el rendimiento evitando varias llamadas a esta función.
SEC_E_OK	El contexto de seguridad se inicializó correctamente. No es necesario realizar otra llamada a InitializeSecurityContext (CredSSP). Si la función devuelve un token de salida, es decir, si el SECBUFFER_TOKEN de pOutput es de longitud distinta de cero, ese token se debe enviar al servidor.
SEC_I_COMPLETE_AND_CONTINUE	El cliente debe llamar a CompleteAuthToken y, a continuación, pasar la salida al servidor. A continuación, el cliente espera un token devuelto y lo pasa, en otra llamada, a InitializeSecurityContext (CredSSP) .
SEC_I_COMPLETE_NEEDED	El cliente debe terminar de compilar el mensaje y, a continuación, llamar a la función CompleteAuthToken .
SEC_I_CONTINUE_NEEDED	El cliente debe enviar el token de salida al servidor y esperar un token de retorno. El cliente pasa el token devuelto en otra llamada a InitializeSecurityContext (CredSSP). El token de salida puede estar vacío.
SEC_I_INCOMPLETE_CREDENTIALS	El servidor ha solicitado la autenticación de cliente, pero las credenciales proporcionadas no incluyen un certificado o el certificado no lo emitió una entidad de certificación en la que confía el servidor. Para obtener más información, vea la sección Comentarios.

Si se produce un error en la función, la función devuelve uno de los siguientes códigos de error.

Código devuelto	Descripción
SEC_E_INSUFFICIENT_MEMORY	No hay suficiente memoria disponible para completar la acción solicitada.
SEC_E_INTERNAL_ERROR	Error que no se asignación a un código de error de SSPI.
SEC_E_INVALID_HANDLE	El identificador pasado a la función no es válido.
SEC_E_INVALID_TOKEN	El token de entrada tiene un formato incorrecto. Entre las posibles causas se incluyen un token dañado en tránsito, un token de tamaño incorrecto y un token pasado al paquete de seguridad incorrecto. Esta última condición puede ocurrir si el cliente y el servidor no negociaron el paquete de seguridad adecuado.
SEC_E_LOGON_DENIED	Error en el inicio de sesión.
SEC_E_NO_AUTHENTICATING_AUTHORITY	No se pudo establecer contacto con ninguna autoridad para la autenticación. El nombre de dominio de la entidad de autenticación podría ser incorrecto, el dominio podría no ser accesible o podría haber habido un error en la relación de confianza.
SEC_E_NO_CREDENTIALS	No hay credenciales disponibles en el paquete de seguridad.
SEC_E_TARGET_UNKNOWN	No se reconoció el destino.
SEC_E_UNSUPPORTED_FUNCTION	El valor del parámetro fContextReq no es válido. No se especificó una marca necesaria o se especificó una marca que no es compatible con CredSSP.
SEC_E_WRONG_PRINCIPAL	La entidad de seguridad que recibió la solicitud de autenticación no es la misma que la que se pasa al parámetro pszTargetName . Este error indica un error en la autenticación mutua.
SEC_E_DELEGATION_POLICY	La directiva no admite la delegación de credenciales en el servidor de destino.
SEC_E_POLICY_NLTM_ONLY	No se permite la delegación de credenciales al servidor de destino cuando no se logra la autenticación mutua.
SEC_E_MUTUAL_AUTH_FAILED	Error de autenticación del servidor cuando se especifica la marca ISC_REQ_MUTUAL_AUTH en el parámetro fContextReq .

Comentarios

El autor de la llamada es responsable de determinar si los atributos de contexto finales son suficientes. Si, por ejemplo, se solicitó confidencialidad, pero no se pudo establecer, algunas aplicaciones pueden optar por apagar la conexión inmediatamente.

Si los atributos del contexto de seguridad no son suficientes, el cliente debe liberar el contexto parcialmente creado llamando a la función DeleteSecurityContext .

El cliente llama a la función InitializeSecurityContext (CredSSP) para inicializar un contexto de salida.

Para un contexto de seguridad de dos piernas, la secuencia de llamada es la siguiente:

El cliente llama a la función con phContext establecido NULL en y rellena el descriptor de búfer con el mensaje de entrada.
El paquete de seguridad examina los parámetros y construye un token opaco, colocándolo en el elemento TOKEN de la matriz de búfer. Si el parámetro fContextReq incluye la marca ISC_REQ_ALLOCATE_MEMORY , el paquete de seguridad asigna la memoria y devuelve el puntero en el elemento TOKEN.
El cliente envía el token devuelto en el búfer pOutput al servidor de destino. A continuación, el servidor pasa el token como argumento de entrada en una llamada a la función AcceptSecurityContext (CredSSP).
AcceptSecurityContext (CredSSP) puede devolver un token. El servidor envía este token al cliente a través de una segunda llamada InitializeSecurityContext (CredSSP) si la primera llamada devolvió SEC_I_CONTINUE_NEEDED.

Si el servidor ha respondido correctamente, el paquete de seguridad devuelve SEC_E_OK y se establece una sesión segura.

Si la función devuelve una de las respuestas de error, no se acepta la respuesta del servidor y no se establece la sesión.

Si la función devuelve SEC_I_CONTINUE_NEEDED, SEC_I_COMPLETE_NEEDED o SEC_I_COMPLETE_AND_CONTINUE, se repiten los pasos 2 y 3.

La inicialización del contexto de seguridad puede requerir más de una llamada a esta función, según el mecanismo de autenticación subyacente, así como las opciones especificadas en el parámetro fContextReq .

Los parámetros fContextReq y pfContextAttributes son máscaras de bits que representan varios atributos de contexto. Para obtener una descripción de los distintos atributos, consulte Requisitos de contexto. Aunque el parámetro pfContextAttributes es válido en cualquier devolución correcta, debe examinar las marcas que pertenecen a aspectos de seguridad del contexto solo en la devolución correcta final. Los retornos intermedios pueden establecer, por ejemplo, la marca ISC_RET_ALLOCATED_MEMORY .

Si se establece la marca de ISC_REQ_USE_SUPPLIED_CREDS , el paquete de seguridad debe buscar un tipo de búfer SECBUFFER_PKG_PARAMS en el búfer de entrada pInput . Aunque no es una solución genérica, permite un emparejamiento seguro de paquete de seguridad y aplicación cuando sea necesario.

Si se especificó ISC_REQ_ALLOCATE_MEMORY, el autor de la llamada debe liberar la memoria llamando a la función FreeContextBuffer .

Por ejemplo, el token de entrada podría ser el desafío de un administrador de LAN. En este caso, el token de salida sería la respuesta cifrada NTLM al desafío.

La acción que realiza el cliente depende del código devuelto de esta función. Si el código de retorno es SEC_E_OK, no habrá ninguna segunda llamada a InitializeSecurityContext (CredSSP) y no se espera ninguna respuesta del servidor. Si el código de retorno es SEC_I_CONTINUE_NEEDED, el cliente espera un token en respuesta del servidor y lo pasa en una segunda llamada a InitializeSecurityContext (CredSSP). El SEC_I_COMPLETE_NEEDED código de retorno indica que el cliente debe terminar de compilar el mensaje y llamar a la función CompleteAuthToken . El código SEC_I_COMPLETE_AND_CONTINUE incorpora ambas acciones.

Si InitializeSecurityContext (CredSSP) devuelve éxito en la primera llamada (o solo), el autor de la llamada debe llamar finalmente a la función DeleteSecurityContext en el identificador devuelto, incluso si se produce un error en la llamada en una etapa posterior del intercambio de autenticación.

El cliente puede llamar a InitializeSecurityContext (CredSSP) de nuevo después de que se haya completado correctamente. Esto indica al paquete de seguridad que se desea una reautenticación.

Los autores de llamadas en modo kernel tienen las siguientes diferencias: el nombre de destino es una cadena Unicode que se debe asignar en memoria virtual mediante VirtualAlloc; no se debe asignar desde el grupo. Los búferes pasados y proporcionados en pInput y pOutput deben estar en memoria virtual, no en el grupo.

Si la función devuelve SEC_I_INCOMPLETE_CREDENTIALS, compruebe que las credenciales de r que se pasan a la función AcquireCredentialsHandle (CredSSP) especifican un certificado de autenticación válido y de confianza. El certificado debe ser un certificado de autenticación de cliente emitido por una entidad de certificación de confianza del servidor. Para obtener una lista de las CA de confianza del servidor, llame a la función QueryContextAttributes (CredSSP) con el atributo SECPKG_ATTR_ISSUER_LIST_EX .

Después de recibir un certificado de autenticación de una entidad de certificación en la que confía el servidor, la aplicación cliente crea una nueva credencial. Para ello, llama a la función AcquireCredentialsHandle (CredSSP) y, a continuación, llama a InitializeSecurityContext (CredSSP) de nuevo, especificando la nueva credencial en el parámetro phCredential .

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Encabezado	Sspi.h (incluya Security.h)
Biblioteca	Secur32.lib
Archivo DLL	Secur32.dll