Compartir a través de

Función DecryptMessage (Schannel)

  • Artículo

La función DecryptMessage (Schannel) descifra un mensaje. Algunos paquetes no cifran y descifran mensajes, sino que realizan y comprueban un hash de integridad.

Esta función también se usa con el proveedor de compatibilidad de seguridad (SSP) de Schannel para indicar una solicitud de un remitente del mensaje para una renegociación (rehacer) de los atributos de conexión o para un apagado de la conexión.

Nota:

Se puede llamar a EncryptMessage (Schannel) y DecryptMessage (Schannel) al mismo tiempo desde dos subprocesos diferentes en un único contexto de interfaz del proveedor de compatibilidad de seguridad (SSPI) si se cifra un subproceso y el otro se descifra. Si se cifra más de un subproceso o se descifra más de un subproceso, cada subproceso debe obtener un contexto único.

Sintaxis

SECURITY_STATUS SEC_Entry DecryptMessage(
  _In_    PCtxtHandle    phContext,
  _Inout_ PSecBufferDesc pMessage,
  _In_    ULONG          MessageSeqNo,
  _Out_   PULONG         pfQOP
);

Parámetros

phContext [in]

Identificador del contexto de seguridad que se va a usar para descifrar el mensaje.

pMessage [in, out]

Puntero a una estructura SecBufferDesc . En la entrada, la estructura hace referencia a una o varias estructuras SecBuffer . Uno de estos puede ser de tipo SECBUFFER_DATA. Ese búfer contiene el mensaje cifrado. El mensaje cifrado se descifra en su lugar, sobrescribiendo el contenido original de su búfer.

Al usar el SSP de Schannel con contextos que no están orientados a la conexión, en la entrada, la estructura debe contener cuatro estructuras SecBuffer . Exactamente un búfer debe ser de tipo SECBUFFER_DATA y contener un mensaje cifrado, que se descifra en su lugar. Los búferes restantes se usan para la salida y deben ser de tipo SECBUFFER_EMPTY. En el caso de los contextos orientados a la conexión, se debe proporcionar un búfer de tipo SECBUFFER_DATA, como se indica para contextos no orientados a la conexión. Además, también se debe proporcionar un segundo búfer de tipo SECBUFFER_TOKEN que contenga un token de seguridad.

MessageSeqNo [in]

Número de secuencia esperado por la aplicación de transporte, si existe. Si la aplicación de transporte no mantiene números de secuencia, este parámetro debe establecerse en cero.

Al usar el SSP de Schannel, este parámetro debe establecerse en cero. El SSP de Schannel no usa números de secuencia.

pfQOP [out]

Puntero a una variable de tipo ULONG que recibe marcas específicas del paquete que indican la calidad de la protección.

Al usar el SSP de Schannel, este parámetro no se usa y debe establecerse en NULL.

Este parámetro puede ser la marca siguiente.

Value Significado
SECQOP_WRAP_NO_ENCRYPT
 El mensaje no se cifró, pero se generó un encabezado o finalizador.
Nota: KERB_WRAP_NO_ENCRYPT tiene el mismo valor y el mismo significado.

Valor devuelto

Si la función comprueba que el mensaje se recibió en la secuencia correcta, la función devuelve SEC_E_OK.

Si la función no puede descifrar el mensaje, devuelve uno de los siguientes códigos de error.

Código devuelto Descripción
SEC_E_INVALID_HANDLE Se especificó un identificador de contexto que no es válido en el parámetro phContext . Se usa con el SSP de Schannel.
SEC_E_INVALID_TOKEN Los búferes son del tipo incorrecto o no se encontró ningún búfer de tipo SECBUFFER_DATA. Se usa con el SSP de Schannel.
SEC_E_MESSAGE_ALTERED El mensaje se ha modificado. Se usa con el SSP de Schannel.
SEC_E_OUT_OF_SEQUENCE El mensaje no se recibió en la secuencia correcta.
SEC_I_CONTEXT_EXPIRED El remitente del mensaje ha terminado de usar la conexión y ha iniciado un apagado. Para obtener información sobre cómo iniciar o reconocer un apagado, consulte Apagar una conexión Schannel. Se usa con el SSP de Schannel.
SEC_I_RENEGOTIATE La parte remota requiere una nueva secuencia de protocolo de enlace o la aplicación acaba de iniciar un apagado. Vuelva al bucle de negociación y llame a AcceptSecurityContext (Schannel) o InitializeSecurityContext (Schannel), pase SECBUFFER_EXTRA devuelto desde DecryptMessage().

Observaciones

A veces, una aplicación leerá datos de la entidad remota, intentará descifrarlos mediante DecryptMessage (Schannel) y detectará que DecryptMessage (Schannel) se realizó correctamente, pero los búferes de salida están vacíos. Este es un comportamiento normal y las aplicaciones deben ser capaces de tratar con él.

Cuando se usa el SSP de Schannel, la función DecryptMessage (General) devuelve SEC_I_CONTEXT_EXPIRED cuando el remitente del mensaje ha cerrado la conexión. Para obtener información sobre cómo iniciar o reconocer un apagado, consulte Apagar una conexión Schannel.

Si usa TLS 1.0, es posible que tenga que llamar a esta función varias veces, ajustando el búfer de entrada en cada llamada, para descifrar un mensaje completo.

La función DecryptMessage (Schannel) devuelve SEC_I_RENEGOTIATE cuando se recibe un mensaje de protocolo TLS posterior al protocolo de enlace distinto de los datos de la aplicación. Una vez que la función DecryptMessage (Schannel) ha devuelto SEC_I_RENEGOTIATE, se producirá un error en cualquier llamada a EncryptMessage() y DecryptMessage() con SEC_E_CONTEXT_EXPIRED. Una aplicación controla esta situación llamando a AcceptSecurityContext (Schannel) (servidor) o InitializeSecurityContext (Schannel) (cliente) y pasando SECBUFFER_EXTRA devueltos desde DecryptMessage(). Después de esta llamada inicial devuelve un valor, continúe como si la aplicación creara una nueva conexión. A continuación, la aplicación puede seguir llamando a EncryptMessage() y DecryptMessage(). Para obtener más información, consulte Creación de un contexto de seguridad de Schannel.

Requisitos

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

Consulte también