Función DecryptMessage (Schannel)

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

Use esta función con el proveedor de soporte técnico de seguridad (SSP) de Schannel para indicar una solicitud desde un remitente del mensaje para una renegociación (rehacer) de los atributos de conexión o para un apagado de la conexión.

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 búferes puede ser de tipo SECBUFFER_DATA. Ese búfer contiene el mensaje cifrado. La función descifra el mensaje cifrado en su lugar, sobrescribir el contenido original de su búfer.

Cuando se usa el SSP de Schannel con contextos que no están orientados a la conexión, la estructura debe contener cuatro estructuras SecBuffer en la entrada. Exactamente un búfer debe ser de tipo SECBUFFER_DATA y contener un mensaje cifrado, que la función 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, debe proporcionar un búfer de tipo SECBUFFER_DATA, como se indica para contextos no orientados a la conexión. Además, 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, establezca este parámetro en cero.

Cuando use el SSP de Schannel, establezca este parámetro en cero. Schannel SSP 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.

Cuando use el SSP de Schannel, no use este parámetro. Establézcalo en NULL.

Este parámetro puede ser la marca siguiente.

Valor devuelto

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

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

Observaciones

A veces, una aplicación lee datos de la entidad remota, intenta descifrarlos mediante DecryptMessage (Schannel) y detecta que DecryptMessage (Schannel) se realiza correctamente, pero los búferes de salida están vacíos. Este comportamiento es normal y las aplicaciones deben poder controlarlo.

Cuando se usa el SSP de Schannel, la función DecryptMessage (General) devuelve SEC_I_CONTEXT_EXPIRED cuando el remitente del mensaje cierra 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 recibe un mensaje de protocolo TLS posterior al protocolo de enlace distinto de los datos de la aplicación. Una vez que DecryptMessage (Schannel) devuelve SEC_I_RENEGOTIATE, se produce un error en las llamadas DecryptMessage() y DecryptMessage() adicionales con SEC_E_CONTEXT_EXPIRED. Una aplicación controla esta situación llamando a AcceptSecurityContext (Schannel) (servidor) o InitializeSecurityContext ( lado cliente) y pasando el mismo búfer modificado por DecryptMessage, asegurándose de que el SecBuffer tipo está establecido SECBUFFER_TOKENen . Tenga en cuenta que DecryptMessage no siempre devuelve un SECBUFFER_EXTRA búfer cuando SEC_I_RENEGOTIATE se devuelve. Después de que esta llamada inicial devuelva 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

Contenido relacionado

• Funciones SSPI
• EncryptMessage (Schannel)
• SecBuffer