Función EncryptMessage (General)

La función EncryptMessage (General) cifra un mensaje para proporcionar privacidad. EncryptMessage (General) permite a una aplicación elegir entre algoritmos criptográficos admitidos por el mecanismo elegido. La función EncryptMessage (General) 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.

Cuando se usa el proveedor de compatibilidad de seguridad implícita (SSP), esta función solo está disponible como un mecanismo SASL.

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

Para obtener información sobre el uso de esta función con un SSP específico, consulte los temas siguientes.

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.

Al usar el SSP de síntesis, este parámetro debe establecerse en cero.

Este parámetro puede ser una de las marcas siguientes.

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 y sobrescribe el contenido original de la estructura.

La función no procesa los 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 (General) (SECPKG_ATTR_STREAM_SIZES).

Al usar el SSP de resumen, debe haber un segundo búfer de tipo SECBUFFER_PADDING o SEC_BUFFER_DATA para contener información de firma . Para obtener el tamaño del búfer de salida, llame a la función QueryContextAttributes (General) y especifique SECPKG_ATTR_SIZES. La función devolverá una estructura SecPkgContext_Sizes . El tamaño del búfer de salida es la suma de los valores de los miembros cbMaxSignature y cbBlockSize .

Las aplicaciones que no usan SSL deben proporcionar un secBuffer de tipo SECBUFFER_PADDING.

MessageSeqNo [in]

Número de secuencia asignado a la aplicación de transporte 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 síntesis, este parámetro debe establecerse en cero. El SSP de resumen administra la numeración de secuencia internamente.

Al usar 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.

Observaciones

La función EncryptMessage (General) cifra un mensaje en función del 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. La inclusión de 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 el SSP de resumen, obtenga el tamaño del búfer de salida llamando a la función QueryContextAttributes (General) y especificando SECPKG_ATTR_SIZES. La función devolverá una estructura SecPkgContext_Sizes . El tamaño del búfer de salida es la suma de los valores de los miembros cbMaxSignature y cbBlockSize .

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

Cuando se usa el SSP de Schannel, determine el tamaño máximo de cada uno de los búferes llamando a la función QueryContextAttributes (General) 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 ), message (miembro cbMaximumMessage ) y búferes de finalizador (miembro cbTrailer ).

Para obtener un rendimiento óptimo, las estructuras pMessage deben asignarse a partir de la memoria contigua.

Windows XP/2000: Esta función también se conoce como SealMessage. Las aplicaciones ahora solo deben usar EncryptMessage (General).

Requisitos

Consulte también

• Funciones SSPI
• AcceptSecurityContext (General)
• DecryptMessage (General)
• InitializeSecurityContext (General)
• QueryContextAttributes (General)
• SecBuffer
• SecBufferDesc