Compartir a través de

Función EncryptMessage (Schannel)

  • Artículo

La función EncryptMessage (Schannel) cifra un mensaje para proporcionar privacidad. EncryptMessage (Schannel) permite a una aplicación elegir entre algoritmos criptográficos admitidos por el mecanismo elegido. La función EncryptMessage (Schannel) usa el contexto de seguridad al que hace referencia el identificador de contexto. Algunos paquetes no tienen mensajes que se van a cifrar o descifrar, sino que proporcionan un hash de integridad que se puede comprobar.

Al usar el SSP de Schannel, esta función cifra los mensajes mediante una clave de sesión negociada con la parte remota que recibirá el mensaje. El algoritmo de cifrado viene determinado por el [conjunto de cifrado ](cifrado-suites-in-schannel.md) en uso.

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 un subproceso está cifrando y el otro está descifrado. 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 EncryptMessage(
  _In_    PCtxtHandle    phContext,
  _In_    ULONG          fQOP,
  _Inout_ PSecBufferDesc pMessage,
  _In_    ULONG          MessageSeqNo
);

Parámetros

phContext [in]

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

fQOP [in]

Marcas específicas del paquete que indican la calidad de la protección. Un paquete de seguridad puede usar este parámetro para habilitar la selección de algoritmos criptográficos.

Este parámetro puede ser la marca siguiente.

Valor Significado
SECQOP_WRAP_OOB_DATA
 Envíe un mensaje de alerta de Schannel. En este caso, el parámetro pMessage debe contener un código de evento SSL/TLS estándar de dos bytes. Este valor solo es compatible con el SSP de Schannel.
Por ejemplo, a partir de Windows Vista, el mensaje "server hello" enviado por el servidor durante el protocolo de re-authentication debe cifrarse como una alerta TLS.

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 que se va a cifrar. El mensaje se cifra en contexto, sobrescribiendo el contenido original de la estructura.

La función no procesa búferes con el atributo SECBUFFER_READONLY.

La longitud de la estructura SecBuffer que contiene el mensaje no debe ser mayor que cbMaximumMessage, que se obtiene de la función QueryContextAttributes (Schannel) (SECPKG_ATTR_STREAM_SIZES).

MessageSeqNo [in]

Número de secuencia que la aplicación de transporte asignó al mensaje. Si la aplicación de transporte no mantiene números de secuencia, este parámetro debe ser cero.

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

Valor devuelto

Si la función se ejecuta correctamente, la función devuelve SEC_E_OK.

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

Código devuelto Descripción
SEC_E_BUFFER_TOO_SMALL
 El búfer de salida es demasiado pequeño. Para obtener más información, vea la sección Comentarios.
SEC_E_CONTEXT_EXPIRED
 La aplicación hace referencia a un contexto que ya se ha cerrado. Una aplicación escrita correctamente no debe recibir este error.
SEC_E_CRYPTO_SYSTEM_INVALID
 No se admite el cifrado elegido para el contexto de seguridad .
SEC_E_INSUFFICIENT_MEMORY
 No hay suficiente memoria disponible para completar la acción solicitada.
SEC_E_INVALID_HANDLE
 Se especificó un identificador de contexto que no es válido en el parámetro phContext .
SEC_E_INVALID_TOKEN
 No se encontró ningún búfer de tipo SECBUFFER_DATA.
SEC_E_QOP_NOT_SUPPORTED
 Ni la confidencialidad ni la integridad son compatibles con el contexto de seguridad.

Comentarios

La función EncryptMessage (Schannel) cifra un mensaje basado en el mensaje y la clave de sesión de un contexto de seguridad.

Si la aplicación de transporte creó el contexto de seguridad para admitir la detección de secuencias y el autor de la llamada proporciona un número de secuencia, la función incluye esta información con el mensaje cifrado. Incluir esta información protege contra la reproducción, inserción y supresión de mensajes. El paquete de seguridad incorpora el número de secuencia pasado desde la aplicación de transporte.

Cuando se usa con Schannel SSP, el parámetro pMessage debe contener una estructura SecBufferDesc con los siguientes búferes.

Nota

Estos búferes deben proporcionarse en el orden mostrado.

Tipo de búfer Descripción
SECBUFFER_STREAM_HEADER Utilizado de forma interna. No se requiere inicialización.
SECBUFFER_DATA Contiene el mensaje de texto no cifrado que se va a cifrar.
SECBUFFER_STREAM_TRAILER Utilizado de forma interna. No se requiere inicialización.
SECBUFFER_EMPTY Utilizado de forma interna. No se requiere inicialización. El tamaño puede ser cero.

Cuando use el SSP de Schannel, determine el tamaño máximo de cada uno de los búferes llamando a la función QueryContextAttributes (Schannel) y especificando el atributo SECPKG_ATTR_STREAM_SIZES. Esta función devuelve una estructura de SecPkgContext_StreamSizes cuyos miembros contienen los tamaños máximos del encabezado (miembro cbHeader ), el mensaje (miembro cbMaximumMessage ) y los búferes del finalizador (miembro cbTrailer ).

Para obtener un rendimiento óptimo, las estructuras pMessage deben asignarse desde memoria contigua.

Windows XP/2000: Esta función también se conoce como SealMessage. Las aplicaciones ahora solo deben usar EncryptMessage (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 (incluya Security.h)
Biblioteca Secur32.lib
Archivo DLL Secur32.dll

Consulte también