EncryptMessage (Schannel)

EncryptMessage (Schannel) function

The EncryptMessage (Schannel) function encrypts a message to provide privacy. EncryptMessage (Schannel) allows an application to choose among cryptographic algorithms supported by the chosen mechanism. The EncryptMessage (Schannel) function uses the security context referenced by the context handle. Some packages do not have messages to be encrypted or decrypted but rather provide an integrity hash that can be checked.

When using the Schannel SSP, this function encrypts messages by using a session key negotiated with the remote party that will receive the message. The encryption algorithm is determined by the cipher suite in use.



SECURITY_STATUS SEC_Entry EncryptMessage(
  _In_    PCtxtHandle    phContext,
  _In_    ULONG          fQOP,
  _Inout_ PSecBufferDesc pMessage,
  _In_    ULONG          MessageSeqNo


phContext [in]


fQOP [in]


This parameter can be the following flag.


Send an Schannel alert message. In this case, the pMessage parameter must contain a standard two-byte SSL/TLS event code. This value is supported only by the Schannel SSP.

For example, beginning with Windows Vista, the "server hello" message sent by the server during the re-authentication protocol must be encrypted as a TLS alert.


pMessage [in, out]

A pointer to a SecBufferDesc structure. On input, the structure references one or more SecBuffer structures. One of these can be of type SECBUFFER_DATA. That buffer contains the message to be encrypted. The message is encrypted in place, overwriting the original contents of the structure.

The function does not process buffers with the SECBUFFER_READONLY attribute.

The length of the SecBuffer structure that contains the message must be no greater than cbMaximumMessage, which is obtained from the QueryContextAttributes (Schannel) (SECPKG_ATTR_STREAM_SIZES) function.

MessageSeqNo [in]


When using the Schannel SSP, this parameter must be set to zero. The Schannel SSP does not use sequence numbers.

Return value

If the function succeeds, the function returns SEC_E_OK.


Return codeDescription





The cipher chosen for the security context is not supported.


There is not enough memory available to complete the requested action.




No SECBUFFER_DATA type buffer was found.


Neither confidentiality nor integrity are supported by the security context.



The EncryptMessage (Schannel) function encrypts a message based on the message and the session key from a security context.


When used with the Schannel SSP, the pMessage parameter must contain a SecBufferDesc structure with the following buffers.

Note  These buffers must be supplied in the order shown.
Buffer typeDescription
SECBUFFER_STREAM_HEADERUsed internally. No initialization required.
SECBUFFER_DATAContains the plaintext message to be encrypted.
SECBUFFER_STREAM_TRAILERUsed internally. No initialization required.
SECBUFFER_EMPTYUsed internally. No initialization required. Size can be zero.


When you use the Schannel SSP, determine the maximum size of each of the buffers by calling the QueryContextAttributes (Schannel) function and specifying the SECPKG_ATTR_STREAM_SIZES attribute. This function returns a SecPkgContext_StreamSizes structure whose members contain the maximum sizes for the header (cbHeader member), message (cbMaximumMessage member) and trailer (cbTrailer member) buffers.


Windows XP/2000:  This function was also known as SealMessage. Applications should now use EncryptMessage (Schannel) only.


Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]


Sspi.h (include Security.h)





See also

SSPI Functions
AcceptSecurityContext (Schannel)
DecryptMessage (Schannel)
InitializeSecurityContext (Schannel)
QueryContextAttributes (Schannel)



Community Additions

© 2015 Microsoft