EncryptMessage (Compact 2013)

  • Article

3/28/2014

This function encrypts a message to help provide privacy.

Syntax

SECURITY_STATUS SEC_ENTRY EncryptMessage(
  PCtxtHandle phContext,
  ULONG fQOP,
  PSecBufferDesc pMessage,
  ULONG MessageSeqNo
);

Parameters

  • phContext
    [in] Pointer to a CtxtHandle structure identifying the security context handle. For information on CtxtHandle, see SSPI Handles.
  • 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. For most security packages this parameter is not used and should be set to zero.

  • pMessage
    [in, out] Pointer to a SecBufferDesc structure. On input, the structure references one or more SecBuffer structures. Only one of these can be of type SECBUFFER_DATA. That buffer contains the message to be encrypted. The function does not process buffers with the SECBUFFER_READONLY attribute.

    The message in the SecBuffer structure is encrypted in place. That is, the encrypted message overwrites the original data in the structure. Only one SecBuffer structure of type SECBUFFER_DATA is permitted.

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

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

    The value of this parameter is not used with the Schannel SSPs. Zero should be used for this parameter when you use either of these SSPs.

Return Value

Returns SEC_E_OK to indicate success. If the function fails, the return value is one of the following error codes.

Return Code

Description

SEC_I_RENEGOTIATE

The remote party requires a new handshake sequence or the application has just initiated a shutdown. The application should return to the negotiation loop and call AcceptSecurityContext or InitializeSecurityContext again. An empty input buffer is passed in the first call.

SEC_E_INVALID_HANDLE

The phContext parameter was passed an invalid context handle.

SEC_E_INVALID_TOKEN

A buffer of type SECBUFFER_DATA was not found.

SEC_E_QOP_NOT_SUPPORTED

The security context does not support confidentiality or integrity.

SEC_E_CRYPTO_SYSTEM_INVALID

The cipher chosen for the security context is not supported.

SEC_E_BUFFER_TOO_SMALL

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

SEC_E_INSUFFICIENT_MEMORY

The requested action cannot be completed because of insufficient memory.

SEC_E_CONTEXT_EXPIRED

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

Remarks

EncryptMessage enables the application to choose among cryptographic algorithms supported by the chosen mechanism. The EncryptMessage 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.

The Schannel SSP 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

When using the Schannel SSP in "streaming" mode, that is, when the ISC_REQ_STREAM or ASC_REQ_STREAM flag is specified during the handshake, neither EncryptMessage nor DecryptMessage can be called at the same time from multiple threads unless each thread has its own SSPI context. This is because each encryption or decryption operation changes the internal state of the encryption key. If the encryption key states are not synchronized on the client and server, the decryption operation fails.

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

The application can obtain the pointer to this function from the SecurityFunctionTable structure that is returned by InitSecurityInterface. The function pointer should be checked to make sure it is not NULL, since earlier versions of Windows Embedded Compact did not export this function.

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 used with the Schannel SSP, the pMessage parameter must contain a SecBufferDesc structure with the buffers described in the following table. These buffers must be supplied in the order shown.

Buffer Type

Description

SECBUFFER_STREAM_HEADER

Used internally. No initialization required.

SECBUFFER_DATA

Contains the plaintext message to be encrypted.

SECBUFFER_STREAM_TRAILER

Used internally. No initialization required.

SECBUFFER_EMPTY

Used 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 function and specifying the SECPKG_ATTR_STREAM_SIZES attribute. This function retrieves a SecPkgContext_StreamSizes structure having members that 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.

Requirements

Header

sspi.h

Library

secur32.lib

See Also

Reference

Authentication Services Functions