EncryptMessage (General) function

The EncryptMessage (General) function encrypts a message to provide privacy. EncryptMessage (General) allows an application to choose among cryptographic algorithms supported by the chosen mechanism. The EncryptMessage (General) 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 Digest security support provider (SSP), this function is available as a SASL mechanism only.

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.

Note  EncryptMessage (General) and DecryptMessage (General) can be called at the same time from two different threads in a single Security Support Provider Interface (SSPI) context if one thread is encrypting and the other is decrypting. If more than one thread is encrypting, or more than one thread is decrypting, each thread should obtain a unique context.

For information about using this function with a specific SSP, see the following topics.

TopicDescription
EncryptMessage (Digest) Encrypts a message to provide privacy by using Digest.
EncryptMessage (Kerberos) Encrypts a message to provide privacy by using Kerberos.
EncryptMessage (Negotiate) Encrypts a message to provide privacy by using Negotiate.
EncryptMessage (NTLM) Encrypts a message to provide privacy by using NTLM.
EncryptMessage (Schannel) Encrypts a message to provide privacy by using Schannel.

 

Syntax


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

Parameters

phContext [in]

A handle to the security context to be used to encrypt the message.

fQOP [in]

Package-specific flags that indicate the quality of protection. A security package can use this parameter to enable the selection of cryptographic algorithms.

When using the Digest SSP, this parameter must be set to zero.

This parameter can be one of the following flags.

ValueMeaning
SECQOP_WRAP_NO_ENCRYPT

Produce a header or trailer but do not encrypt the message.

Note  KERB_WRAP_NO_ENCRYPT has the same value and the same meaning.

SECQOP_WRAP_OOB_DATA

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.

 

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 (General) (SECPKG_ATTR_STREAM_SIZES) function.

When using the Digest SSP, there must be a second buffer of type SECBUFFER_PADDING or SEC_BUFFER_DATA to hold signature information. To get the size of the output buffer, call the QueryContextAttributes (General) function and specify SECPKG_ATTR_SIZES. The function will return a SecPkgContext_Sizes structure. The size of the output buffer is the sum of the values in the cbMaxSignature and cbBlockSize members.

Applications that do not use SSL must supply a SecBuffer of type SECBUFFER_PADDING.

MessageSeqNo [in]

The sequence number that the transport application assigned to the message. If the transport application does not maintain sequence numbers, this parameter must be zero.

When using the Digest SSP, this parameter must be set to zero. The Digest SSP manages sequence numbering internally.

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.

If the function fails, it returns one of the following error codes.

Return codeDescription
SEC_E_BUFFER_TOO_SMALL

The output buffer is too small. For more information, see Remarks.

SEC_E_CONTEXT_EXPIRED

The application is referencing a context that has already been closed. A properly written application should not receive this error.

SEC_E_CRYPTO_SYSTEM_INVALID

The cipher chosen for the security context is not supported.

SEC_E_INSUFFICIENT_MEMORY

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

SEC_E_INVALID_HANDLE

A context handle that is not valid was specified in the phContext parameter.

SEC_E_INVALID_TOKEN

No SECBUFFER_DATA type buffer was found.

SEC_E_QOP_NOT_SUPPORTED

Neither confidentiality nor integrity are supported by the security context.

 

Remarks

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

If the transport application created the security context to support sequence detection and the caller provides a sequence number, the function includes this information with the encrypted message. Including this information protects against replay, insertion, and suppression of messages. The security package incorporates the sequence number passed down from the transport application.

When you use the Digest SSP, get the size of the output buffer by calling the QueryContextAttributes (General) function and specifying SECPKG_ATTR_SIZES. The function will return a SecPkgContext_Sizes structure. The size of the output buffer is the sum of the values in the cbMaxSignature and cbBlockSize members.

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 (General) 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.

For optimal performance, the pMessage structures should be allocated from contiguous memory.

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

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Sspi.h (include Security.h)

Library

Secur32.lib

DLL

Secur32.dll

See also

SSPI Functions
AcceptSecurityContext (General)
DecryptMessage (General)
InitializeSecurityContext (General)
QueryContextAttributes (General)
SecBuffer
SecBufferDesc

 

 

Community Additions

ADD
Show:
© 2014 Microsoft