Compartir a través de

Función AcceptSecurityContext (Digest)

  • Artículo

La función AcceptSecurityContext (Digest) permite al componente de servidor de una aplicación de transporte establecer un contexto de seguridad entre el servidor y un cliente remoto. El cliente remoto usa la función InitializeSecurityContext (Digest) para iniciar el proceso de establecimiento de un contexto de seguridad. El servidor puede requerir uno o varios tokens de respuesta del cliente remoto para completar el establecimiento del contexto de seguridad.

Sintaxis

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]

Identificador de las credenciales del servidor. El servidor llama a la función AcquireCredentialsHandle (Digest) con la marca SECPKG_CRED_INBOUND o SECPKG_CRED_BOTH establecida para recuperar este identificador.

phContext [in, out, optional]

Puntero a una estructura CtxtHandle. En la primera llamada a AcceptSecurityContext (Digest), este puntero es NULL. En las llamadas posteriores, phContext es el identificador del contexto parcialmente formado devuelto por la primera llamada en el parámetro phNewContext.

Advertencia

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

pInput [in, optional]

Puntero a una estructura SecBufferDesc generada por una llamada de cliente a InitializeSecurityContext (Digest) que contiene el descriptor de búfer de entrada.

En la tabla siguiente se muestra la configuración del búfer para HTTP de Digest. El primer búfer debe ser de tipo SECBUFFER_TOKEN y el resto debe ser de tipo SECBUFFER_PKG_PARAMS. SASL solo requiere el búfer cero.

Número de búfer/tipo de búfer Significado
0
SECBUFFER_TOKEN		 Vacía para la primera llamada y respuesta de desafío recibida del cliente para la segunda llamada.
1
SECBUFFER_PKG_PARAMS		 Método. Los caracteres tienen el formato de línea de conexión de la línea de solicitud. Caracteres de un solo byte de US ASCII.
2
SECBUFFER_PKG_PARAMS		 Reservado.
3
SECBUFFER_PKG_PARAMS		 HEntity. Representación hexadecimal de H(entity-body). Caracteres de un solo byte de US ASCII.
4
SECBUFFER_PKG_PARAMS		 Realm (Territorio) Cadena de territorio para el desafío. Cadena Unicode que se debe representar en US ASCII.
5
SECBUFFER_CHANNEL_BINDINGS | SECBUFFER_READONLY		 Contiene el valor del token de enlace de canal.
Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: Este valor no se admite.

fContextReq [in]

Marcas de bits que especifican los atributos requeridos por el servidor para establecer el contexto. Las marcas de bits se pueden combinar usando operaciones OR bit a bit. Este parámetro puede ser uno o más de los siguientes valores.

Value Significado
ASC_REQ_ALLOCATE_MEMORY Digest asigna los búferes de salida. Cuando haya terminado de usar los búferes de salida, puede liberarlos llamando a la función FreeContextBuffer.
ASC_REQ_ALLOW_MISSING_BINDINGS Indica que Digest no requiere enlaces de canal para canales internos y externos. Este valor se usa para la compatibilidad con versiones anteriores cuando no se conoce la compatibilidad con el enlace de canal del punto de conexión.
Este valor es mutuamente excluyente con ASC_REQ_PROXY_BINDINGS.
Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: Este valor no se admite.
ASC_REQ_CONFIDENTIALITY Cifra y descifra mensajes.
El SSP de Digest solo admite esta marca para SASL.
ASC_REQ_PROXY_BINDINGS Indica que Digest requiere enlace de canal.
Este valor es mutuamente excluyente con ASC_REQ_ALLOW_MISSING_BINDINGS.
Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: Este valor no se admite.
ASC_REQ_CONNECTION El contexto de seguridad no controlará el formato de los mensajes.
ASC_REQ_EXTENDED_ERROR Cuando se produzcan errores, se notificará a la entidad remota.
ASC_REQ_HTTP (0x10000000) Usar Digest para HTTP. Omita esta marca para usar Digest como un mecanismo SASL.
ASC_REQ_INTEGRITY Firma mensajes y comprueba firmas.
ASC_REQ_REPLAY_DETECT Detecta paquetes reproducidos.
ASC_REQ_SEQUENCE_DETECT Detectar los mensajes recibidos fuera de la secuencia.

Para ver las posibles marcas de atributos y sus significados, consulte Requisitos de contexto. Las marcas usadas para este parámetro tienen como prefijo ASC_REQ, por ejemplo, ASC_REQ_DELEGATE.

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

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 utiliza con el SSP de Digest. Cuando use el SSP de Digest, especifique cero para este parámetro.

phNewContext [in, out, optional]

Puntero a una estructura CtxtHandle. En la primera llamada a AcceptSecurityContext (Digest),, este puntero recibe el nuevo identificador de contexto. En llamadas posteriores, phNewContext puede coincidir con el identificador especificado en el parámetro phContext. phNewContext nunca debe ser NULL.

pOutput [in, out, optional]

Puntero a una estructura SecBufferDesc que contiene el descriptor de búfer de salida. Este búfer se envía al cliente para la entrada en llamadas adicionales a InitializeSecurityContext (Digest). Se puede generar un búfer de salida incluso si la función devuelve SEC_E_OK. Cualquier búfer generado se debe devolver a la aplicación cliente.

pfContextAttr [out]

Puntero a una variable que recibe 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 como prefijo ASC_RET, por ejemplo, ASC_RET_DELEGATE.

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

ptsTimeStamp [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 hora local.

Este parámetro se establece en un tiempo máximo constante. No hay tiempo de caducidad para los contextos de seguridad o las credenciales de Digest o al usar el SSP de Digest.

Nota:

Hasta la última llamada del proceso de autenticación, la hora de caducidad del contexto puede ser incorrecta, ya que se proporcionará más información durante las fases posteriores de la negociación. Por lo tanto, ptsTimeStamp debe ser NULL hasta la última llamada a la función.

Valor devuelto

Esta función devuelve uno de los siguientes valores:

Código + valor devuelto Descripción
SEC_E_INSUFFICIENT_MEMORY
0x80090300L		 Se produjo un error en la función. No hay suficiente memoria disponible para realizar la acción solicitada.
SEC_E_INTERNAL_ERROR
0x80090304L		 Se produjo un error en la función. Se produjo un error al que no se le ha asignado un código de error SSPI.
SEC_E_INVALID_HANDLE
0x80100003L		 Se produjo un error en la función. La controlador pasado a la función no es válido.
SEC_E_INVALID_TOKEN
0x80090308L		 Se produjo un error en la función. El token transferido a la función no es válido.
SEC_E_LOGON_DENIED
0x8009030CL		 Error de inicio de sesión.
SEC_E_NO_AUTHENTICATING_AUTHORITY
0x80090311L		 Se produjo un error en la función. No se pudo establecer contacto con ninguna autoridad para la autenticación. Esto puede deberse a los siguientes motivos:
- El nombre de dominio de la entidad de autenticación es incorrecto.
- El dominio no está disponible.
- Se ha producido un error en la relación de confianza.
SEC_E_NO_CREDENTIALS
0x8009030EL		 Se produjo un error en la función. El identificador de credenciales especificado en el parámetro phCredential no es válido.
SEC_E_OK
0x00000000L		 La función se ha realizado correctamente. Se aceptó el contexto de seguridad recibido del cliente. Si la función generó un token de salida, se debe enviar al proceso de cliente.
SEC_E_SECURITY_QOS_FAILED
0x80090332L		 Se produjo un error en la función. Se ha especificado una marca de atributo de contexto que no es válida en el parámetro fContextReq.
SEC_I_COMPLETE_AND_CONTINUE
0x00090314L		 La función se ha realizado correctamente. El servidor debe llamar a CompleteAuthToken y transferir el token de salida al cliente. A continuación, el servidor espera un token de devolución del cliente y después realiza otra llamada a AcceptSecurityContext (Digest).
SEC_I_COMPLETE_NEEDED
0x00090313L		 La función se ha realizado correctamente. El servidor debe terminar de compilar el mensaje desde el cliente y, a continuación, llamar a la función CompleteAuthToken.
SEC_I_CONTINUE_NEEDED
0x00090312L		 La función se ha realizado correctamente. El servidor debe enviar el token de salida al cliente y esperar a que se devuelva un token. El token devuelto se debe transferir en pInput para otra llamada a AcceptSecurityContext (Digest).
STATUS_LOGON_FAILURE
0xC000006DL		 Se produjo un error en la función. Se llamó a la función AcceptSecurityContext (Digest) después de establecer el contexto especificado.
SEC_E_BAD_BINDINGS
0x80090346L		 Se produjo un error en la función. No se cumplió la directiva de enlace de canales.

Comentarios

La función AcceptSecurityContext (Digest) es el equivalente del servidor de la función InitializeSecurityContext (Digest).

Cuando el servidor recibe una solicitud de un cliente, el servidor usa el parámetro fContextReq para especificar lo que requiere de la sesión. De este modo, un servidor puede especificar que los clientes deben ser capaces de usar una sesión confidencial o con comprobación de integridad, y puede rechazar los clientes que no puedan satisfacer esa demanda. Como alternativa, un servidor puede no requerir nada, y lo que el cliente pueda proporcionar o requiera se devuelve en el parámetro pfContextAttr.

Para un paquete que admita la autenticación múltiple, como la autenticación mutua, la secuencia de llamadas es la siguiente:

  1. El cliente transmite un token al servidor.
  2. La primera vez, el servidor llama a AcceptSecurityContext (Digest), que genera un token de respuesta que se envía al cliente.
  3. El cliente recibe el token y lo transfiere a InitializeSecurityContext (Digest). Si InitializeSecurityContext (Digest) devuelve SEC_E_OK, se ha completado la autenticación mutua y se puede iniciar una sesión segura. Si InitializeSecurityContext (Digest) devuelve un código de error, finaliza la negociación de autenticación mutua. De lo contrario, el token de seguridad devuelto por InitializeSecurityContext (Digest) se envía al cliente y se repiten los pasos 2 y 3.
  4. No use el valor phContext en llamadas simultáneas a AcceptSecurityContext (Digest). La implementación en los proveedores de seguridad no es segura para subprocesos.

Los parámetros fContextReq y pfContextAttr son máscaras de bits que representan varios atributos de contexto. Para ver descripciones adicionales de los distintos atributos, consulte Requisitos de contexto.

Nota:

El parámetro pfContextAttr es válido en cualquier devolución correcta, pero las marcas relacionadas con los aspectos de seguridad del contexto solo se deben examinar en la devolución correcta final. Las devoluciones intermedias pueden establecer, por ejemplo, la marca ISC_RET_ALLOCATED_MEMORY.

El autor de la llamada es responsable de determinar si los atributos de contexto finales son suficientes. Si, por ejemplo, se solicitó la confidencialidad (cifrado), pero no se pudo establecer, algunas aplicaciones pueden optar por cerrar la conexión inmediatamente. Si no se puede establecer el contexto de seguridad, el servidor debe liberar el contexto creado parcialmente llamando a la función DeleteSecurityContext. Para obtener información sobre cuándo llamar a la función DeleteSecurityContext, consulte DeleteSecurityContext.

Una vez establecido el contexto de seguridad, la aplicación de servidor puede usar la función QuerySecurityContextToken para recuperar un identificador de la cuenta de usuario a la que se asignó el certificado de cliente. Además, el servidor puede usar la función ImpersonateSecurityContext para suplantar al usuario.

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 (incluye Security.h)
Biblioteca Secur32.lib
Archivo DLL Secur32.dll

Consulte también

Funciones SSPI

DeleteSecurityContext

InitializeSecurityContext (Digest)