Función InitializeSecurityContext (General)

Artículo
03/18/2023

La función InitializeSecurityContext (General) inicia el contexto de seguridad saliente del lado cliente desde un controlador de credenciales. La función se usa para crear un contexto de seguridad entre la aplicación cliente y un elemento del mismo nivel remoto. InitializeSecurityContext (General) devuelve un token que el cliente debe pasar al elemento del mismo nivel remoto, que, a su vez, este envía a la implementación de seguridad local mediante la llamada a AcceptSecurityContext (General).. Todos los autores de llamada deben considerar opaco el token generado.

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

Para información sobre el uso de esta función con un proveedor de soporte de seguridad (SSP) específico, consulte los temas siguientes.

Tema	Descripción
InitializeSecurityContext (CredSSP)	Inicia el contexto de seguridad saliente del lado cliente desde un controlador de credenciales mediante el paquete de seguridad del proveedor de soporte de seguridad de credenciales (CredSSP).
InitializeSecurityContext (Digest)	Inicia el contexto de seguridad saliente del lado cliente desde un controlador de credenciales mediante el paquete de seguridad de Digest.
InitializeSecurityContext (Kerberos)	Inicia el contexto de seguridad saliente del lado cliente desde un controlador de credenciales mediante el paquete de seguridad de Kerberos.
InitializeSecurityContext (Negotiate)	Inicia el contexto de seguridad saliente del lado cliente desde un controlador de credenciales mediante el paquete de seguridad de Negotiate.
InitializeSecurityContext (NTLM)	Inicia el contexto de seguridad saliente del lado cliente desde un controlador de credenciales mediante el paquete de seguridad de NTML.
InitializeSecurityContext (Schannel)	Inicia el contexto de seguridad saliente del lado cliente desde un controlador de credenciales mediante el paquete de seguridad de Schannel.

Sintaxis

SECURITY_STATUS SEC_Entry InitializeSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _In_opt_    PCtxtHandle    phContext,
  _In_opt_    SEC_CHAR       *pszTargetName,
  _In_        ULONG          fContextReq,
  _In_        ULONG          Reserved1,
  _In_        ULONG          TargetDataRep,
  _In_opt_    PSecBufferDesc pInput,
  _In_        ULONG          Reserved2,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Inout_opt_ PSecBufferDesc pOutput,
  _Out_       PULONG         pfContextAttr,
  _Out_opt_   PTimeStamp     ptsExpiry
);

Parámetros

phCredential[in, optional]

Controlador de las credenciales devueltas por AcquireCredentialsHandle (General). Este controlador se usa para compilar el contexto de seguridad. La función InitializeSecurityContext (General) requiere al menos credenciales OUTBOUND.

phContext[in, optional]

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

Este parámetro es opcional con el SSP de Microsoft Digest y se puede establecer en NULL.

Al usar el SSP de Schannel, en la primera llamada a InitializeSecurityContext (General), 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 (General). 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 indica el destino del contexto. El contenido de la cadena es específico del paquete de seguridad, como se describe en la tabla siguiente. Esta lista no es exhaustiva. Se pueden agregar SSP adicionales del sistema y SSP de terceros a un sistema.

SSP en uso	Significado
Digest	Cadena terminada en NULL que identifica de forma única el URI del recurso solicitado. La cadena debe estar compuesta de caracteres permitidos en un URI y que el conjunto de código ASCII de EE. UU. debe representar. La codificación porcentual se puede usar para representar caracteres fuera del conjunto de código ASCII de EE. UU.
Kerberos o Negotiate	Nombre de la entidad de seguridad de servicio (SPN) o el contexto de seguridad del servidor de destino.
NTLM	Nombre de la entidad de seguridad de servicio (SPN) o el contexto de seguridad del servidor de destino.
Schannel/SSL	Cadena terminada en NULL que identifica de forma única el servidor de destino. Schannel usa este valor para comprobar el certificado del servidor. Schannel también usa este valor para buscar la sesión en la caché de sesiones 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 credencial es el mismo.

fContextReq[in]

Marcas de bits que indican solicitudes del contexto. No todos los paquetes pueden admitir todos los requisitos. Las marcas usadas para este parámetro tienen como 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	El paquete de seguridad asigna automáticamente búferes de salida. Cuando haya terminado de usar los búferes de salida, puede liberarlos llamando a la función FreeContextBuffer.
ISC_REQ_CONFIDENTIALITY	Cifre los mensajes mediante la función EncryptMessage.
ISC_REQ_CONNECTION	El contexto de seguridad no controlará el formato de los mensajes. Este valor es el valor predeterminado para las delegaciones restringidas de Kerberos, Negotiate y NTLM.
ISC_REQ_DELEGATE	El servidor puede usar el contexto para autenticarse en otros servidores como cliente. La marca ISC_REQ_MUTUAL_AUTH debe establecerse para que esta marca funcione. Válido para Kerberos. Omita esta marca para la delegación restringida.
ISC_REQ_EXTENDED_ERROR	Cuando se produzcan errores, se notificará a la entidad remota.
ISC_REQ_HTTP	Usar Digest para HTTP. Omita esta marca para usar Digest como mecanismo SASL.
ISC_REQ_INTEGRITY	Firmar mensajes y comprobar firmas mediante las funciones EncryptMessage y MakeSignature.
ISC_REQ_MANUAL_CRED_VALIDATION	Schannel no debe autenticar automáticamente el servidor.
ISC_REQ_MUTUAL_AUTH	Se cumplirá la directiva de autenticación mutua del servicio. PRECAUCIÓN: Esto no significa necesariamente que se realice la autenticación mutua, solo que se cumpla la directiva de autenticación del servicio. Para asegurarse de que se realiza la autenticación mutua, llame a la función QueryContextAttributes (General).
ISC_REQ_NO_INTEGRITY	Si se establece esta marca, se omite la marca ISC_REQ_INTEGRITY. Este valor solo es compatible con las delegaciones restringidas de Negotiate y Kerberos.
ISC_REQ_REPLAY_DETECT	Detectar los mensajes reproducidos que se han codificado mediante las funciones EncryptMessage o MakeSignature.
ISC_REQ_SEQUENCE_DETECT	Detectar los mensajes recibidos fuera de la secuencia.
ISC_REQ_STREAM	Compatibilidad con una conexión orientada a flujos.
ISC_REQ_USE_SESSION_KEY	Se debe negociar una nueva clave de sesión. Este valor solo es compatible con las delegaciones restringidas de Kerberos.
ISC_REQ_USE_SUPPLIED_CREDS	Schannel no debe intentar proporcionar credenciales para el cliente automáticamente.

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

Para descripciones adicionales de los distintos atributos, consulte Requisitos de contexto.

Reserved1[in]

Este parámetro está reservado y debe ser cero.

TargetDataRep[in]

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

Este parámetro no se usa con Digest o Schannel. Establézcalo en cero.

pInput[in, 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 ha iniciado 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.

Reserved2[in]

Este parámetro está reservado y debe ser cero.

phNewContext[in, out, optional]

Puntero a una estructura CtxtHandle. En la primera llamada a InitializeSecurityContext (General), 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[in, out, optional]

Puntero a una estructura SecBufferDesc que 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 al token de seguridad si se solicita (mediante ISC_REQ_ALLOCATE_MEMORY) y rellenará la dirección en el descriptor del búfer del token de seguridad.

Cuando se usa el SSP de Microsoft Digest, este parámetro recibe la respuesta de desafío que se debe enviar al servidor.

Cuando se usa el SSP de Schannel, si se especifica la marca ISC_REQ_ALLOCATE_MEMORY, el SSP de Schannel asignará memoria al búfer y colocará la información adecuada en SecBufferDesc. Además, el autor de la llamada debe pasar un búfer de tipo SECBUFFER_ALERT. En la salida, si se genera una alerta, este búfer contiene información sobre esa alerta y se produce un error en la función.

pfContextAttr[out]

Puntero a una variable para recibir un conjunto de marcas de bits que indican los atributos del contexto establecido. Para ver descripciones adicionales de los distintos atributos, consulte 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 si hay 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 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.

No hay ninguna hora de expiración para las credenciales o los contextos de seguridad del SSP de Microsoft Digest.

Valor devuelto

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

Código devuelto	Descripción
SEC_I_COMPLETE_AND_CONTINUE	El cliente debe llamar a CompleteAuthToken y, luego, pasar la salida al servidor. A continuación, el cliente espera un token devuelto y lo pasa, en otra llamada, a InitializeSecurityContext (General).
SEC_I_COMPLETE_NEEDED	El cliente debe terminar de compilar el mensaje y, luego, 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. A continuación, el token devuelto se pasa en otra llamada a InitializeSecurityContext (General). El token de salida puede estar vacío.
SEC_I_INCOMPLETE_CREDENTIALS	Usar con Schannel. El servidor ha solicitado la autenticación cliente, y las credenciales proporcionadas no incluyen un certificado o el certificado no lo emitió una entidad de certificación en la que confíe el servidor. Para obtener más información, vea la sección Comentarios.
SEC_E_INCOMPLETE_MESSAGE	Usar con Schannel. No se leyeron los datos de todo el mensaje a través 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 contiene un valor que indica el número de bytes adicionales que la función debe leer del cliente antes de que esta función se ejecute correctamente. Aunque este número no siempre es preciso, su uso puede ayudar a mejorar el rendimiento al evitar varias llamadas a esta función.
SEC_E_OK	El contexto de seguridad se inicializó correctamente. No es necesario realizar otra llamada a InitializeSecurityContext (General). Si la función devuelve un token de salida, es decir, si SECBUFFER_TOKEN en pOutput es de una longitud distinta de cero, ese token debe enviarse al servidor.

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 realizar la acción solicitada.
SEC_E_INTERNAL_ERROR	Se produjo un error al que no se le ha asignado un código de error SSPI.
SEC_E_INVALID_HANDLE	La controlador pasado a la función no es válido.
SEC_E_INVALID_TOKEN	El error se debe a un token de entrada con formato incorrecto, como un token dañado en tránsito, un token de tamaño incorrecto o un token pasado al paquete de seguridad incorrecto. Pasar un token al paquete incorrecto puede ocurrir si el cliente y el servidor no negociaron el paquete de seguridad adecuado.
SEC_E_LOGON_DENIED	Error de 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 ser inaccesible o podría haber habido un error de relación de confianza.
SEC_E_NO_CREDENTIALS	No hay credenciales disponibles en el paquete de seguridad.
SEC_E_TARGET_UNKNOWN	No se reonoció el destino.
SEC_E_UNSUPPORTED_FUNCTION	Se especificó una marca de atributo de contexto que no es válida (ISC_REQ_DELEGATE o ISC_REQ_PROMPT_FOR_CREDS) en el parámetro fContextReq.
SEC_E_WRONG_PRINCIPAL	La entidad de seguridad que recibió la solicitud de autenticación no es la misma que la que se pasó al parámetro pszTargetName. Esto indica un error en la autenticación mutua.

Comentarios

El autor de la llamada es responsable de determinar si los atributos de contexto finales son suficientes. Si, por ejemplo, se solicitó la 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 creado parcialmente llamando a la función DeleteSecurityContext.

Un cliente usa la función InitializeSecurityContext (General) para inicializar un contexto de salida.

En un contexto de seguridad de dos fases, la secuencia de llamada es la siguiente:

El cliente llama a la función con phContext establecido en NULL y rellena el descriptor del búfer con el mensaje de entrada.
El paquete de seguridad examina los parámetros y construye un token opaco, y lo coloca 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 (General).
AcceptSecurityContext (General) puede devolver un token, que el servidor envía al cliente para una segunda llamada a InitializeSecurityContext (General) si la primera devolvió SEC_I_CONTINUE_NEEDED.

En el caso de contextos de seguridad de varias fases, como la autenticación mutua, la secuencia de llamada es la siguiente:

El cliente llama a la función como se ha descrito anteriormente, pero el paquete devuelve el código correcto de SEC_I_CONTINUE_NEEDED.
El cliente envía el token de salida al servidor y espera la respuesta.
Tras la recepción de la respuesta del servidor, el cliente llama a InitializeSecurityContext (General) de nuevo, con phContext establecido en el controlador que se devolvió en la última llamada. El token recibido del servidor se proporciona en el parámetro pInput.
No use el valor phContext en llamadas simultáneas a InitializeSecurityContext (General). La implementación en los proveedores de seguridad no es segura para subprocesos.

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.

Para inicializar un contexto de seguridad, se 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 ver descripciones adicionales de los distintos atributos, consulte Requisitos de contexto. El parámetro pfContextAttributes es válido en cualquier devolución correcta, pero solo en la devolución correcta final se deben examinar las marcas que pertenecen a los aspectos de seguridad del contexto. Las devoluciones intermedias pueden establecer, por ejemplo, la marca ISC_RET_ALLOCATED_MEMORY.

Si se establece la marca 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. Esta no es una solución genérica, pero permite un emparejamiento seguro de la aplicación y el paquete de seguridad cuando corresponda.

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 con NTLM al desafío.

La acción que realiza el cliente depende del código devuelto por esta función. Si el código devuelto es SEC_E_OK, no habrá ninguna segunda llamada InitializeSecurityContext (General) y no se espera ninguna respuesta del servidor. Si el código devuelto es SEC_I_CONTINUE_NEEDED, el cliente espera un token en respuesta del servidor y lo pasa en una segunda llamada a InitializeSecurityContext (General). El código devuelto SEC_I_COMPLETE_NEEDED 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 (General) se ejecute correctamente en la primera (o única) llamada, el autor de la llamada debe llamar finalmente a la función DeleteSecurityContext en el controlador devuelto, incluso si la llamada produce un error en una fase posterior del intercambio de autenticación.

El cliente puede llamar a InitializeSecurityContext (General) de nuevo después de que se haya ejecutado correctamente. Esto indica al paquete de seguridad que se quiere una nueva autenticació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 la memoria virtual mediante VirtualAlloc; no se debe asignar desde el grupo. Los búferes pasados y proporcionados en pInput y pOutput deben estar en la memoria virtual, no en el grupo.

Al usar el SSP de Schannel, si la función devuelve SEC_I_INCOMPLETE_CREDENTIALS, compruebe que haya especificado un certificado válido y de confianza en sus credenciales. El certificado se especifica al llamar a la función AcquireCredentialsHandle (General). El certificado debe ser un certificado de autenticación de cliente emitido por una entidad de certificación (CA) en la que confíe el servidor. Para obtener una lista de las CA de confianza del servidor, llame a la función QueryContextAttributes (General) y especifique el atributo SECPKG_ATTR_ISSUER_LIST_EX.

Cuando se usa el SSP de Schannel, después de que una aplicación cliente reciba un certificado de autenticación de una CA en la que confíe el servidor, la aplicación crea una nueva credencial; para ello, llama a la función AcquireCredentialsHandle (General) y, luego, de nuevo a InitializeSecurityContext (General), mediante la especificación de una nueva credencial en el parámetro phCredential.

Requisitos

Requisito	Valor
Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Encabezado	Sspi.h (incluya Security.h)
Biblioteca	Secur32.lib
Archivo DLL	Secur32.dll
Nombres Unicode y ANSI	InitializeSecurityContextW (Unicode) y InitializeSecurityContextA (ANSI)