Función InitializeSecurityContext (Digest)

La función InitializeSecurityContext (Digest) inicia el contexto de seguridad saliente del lado cliente desde un identificador 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 (Digest) devuelve un token que el cliente debe pasar al mismo nivel remoto, que a su vez el mismo nivel envía a la implementación de seguridad local a través de la llamada AcceptSecurityContext (Digest). Todos los autores de llamada deben considerar el token generado como opaco.

Normalmente, se llama a la función InitializeSecurityContext (Digest) 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_        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

phCredencial[in, optional]

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

phContext (Contexto de la traducción automática)[in, optional]

Puntero a una estructura CtxtHandle. En la primera llamada a InitializeSecurityContext (Digest), 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.

pszTargetName[in, optional]

Puntero a una 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 us debe representar. La codificación porcentual se puede usar para representar caracteres fuera del conjunto de código ASCII de EE. UU.

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 como prefijo ISC_REQ_, por ejemplo, ISC_REQ_DELEGATE. Este parámetro puede ser una o varias de las marcas de atributos siguientes.

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

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

Reservado1[in]

Este parámetro está reservado y debe establecerse en cero.

TargetDataRep[in]

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

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

Para obtener información sobre la configuración del búfer, consulte Búferes de entrada para la respuesta de desafío de resumen.

Reservado2[in]

Este parámetro está reservado y debe establecerse en cero.

phNewContext[in, out, optional]

Puntero a una estructura CtxtHandle. En la primera llamada a InitializeSecurityContext (Digest), 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.

pSalida[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 para el token de seguridad si se solicita (a través de ISC_REQ_ALLOCATE_MEMORY) y rellena la dirección en el descriptor de búfer para el token de seguridad.

Este parámetro recibe la respuesta de desafío que se debe enviar al servidor.

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 de ASC_RET_ALLOCATED_MEMORY, se pueden comprobar antes de la devolución final.

ptsCaducidad[out, optional]

Puntero a una estructura TimeStamp que recibe la hora de expiración del contexto.

No hay ninguna hora de expiración para las credenciales o el contexto de seguridadde SSP de Microsoft Digest.

Valor devuelto

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

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

Observaciones

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 (Digest) para inicializar un contexto de salida.

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

1. El cliente llama a la función con phContext establecido NULL en y rellena el descriptor de búfer con el mensaje de entrada.
2. 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.
3. El cliente envía el token devuelto en el búfer de 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 (Digest).
4. AcceptSecurityContext (Digest) puede devolver un token, que el servidor envía al cliente para una segunda llamada a InitializeSecurityContext (Digest) si la primera llamada devolvió SEC_I_CONTINUE_NEEDED.

Para los contextos de seguridadde varias piernas, como la autenticación mutua, la secuencia de llamada es la siguiente:

1. El cliente llama a la función como se ha descrito anteriormente, pero el paquete devuelve el código de SEC_I_CONTINUE_NEEDED correcto.
2. El cliente envía el token de salida al servidor y espera la respuesta del servidor.
3. Tras la recepción de la respuesta del servidor, el cliente llama a InitializeSecurityContext (Digest) de nuevo, con phContext establecido en el identificador que se devolvió desde la última llamada. El token recibido del servidor se proporciona en el parámetro pInput .
4. No use el valor phContext en llamadas simultáneas a InitializeSecurityContext (Digest). 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 debe 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 de esta función. Si el código devuelto es SEC_E_OK, no habrá ninguna segunda llamada a InitializeSecurityContext (Digest) 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 (Digest). El SEC_I_COMPLETE_NEEDED código devuelto 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 (Digest) 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 una fase posterior del intercambio de autenticación.

El cliente puede llamar a InitializeSecurityContext (Digest) de nuevo después de que se haya completado correctamente. Esto indica al paquete de seguridad que se quiere 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 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 memoria virtual, no en el grupo.

Requisitos

Consulte también

Funciones SSPI

AcceptSecurityContext (Resumen)

AcquireCredentialsHandle (resumen)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer

SecBuffer

SecBufferDesc