EncryptMessage

The EncryptMessage function encrypts a message to provide privacy. EncryptMessage allows 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/decrypted, but rather an integrity hash to be provided and checked.

SECURITY_STATUS EncryptMessage(
  PCtxtHandle phContext,     // context to use
  ULONG fQOP,                // quality of protection
  PSecBufferDesc pMessage,   // message to encrypt
  ULONG MessageSeqNo         // message sequence number
);

Parameters

phContext

[in] Handle to the security context to be used to encrypt the message.

fQOP

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

The following flag is defined for use with the Kerberos protocol.

Flag	Description
KERB_WRAP_NO_ENCRYPT	Message is not to be encrypted, but a header/trailer is to be produced.

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 SecBuffer 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] Specifies a sequence number that the transport application assigned to the message. If the transport application does not maintain sequence numbers, this parameter must be zero.

Return Values

If the function succeeds, the return value is SEC_E_OK.

If the function fails, the return value is a nonzero error code.

This function can return the error code SEC_I_RENEGOTIATE, indicating that the remote party requires a new handshake sequence or that the application has just initiated a shutdown. Return to the negotiation loop and call AcceptSecurityContext or InitializeSecurityContext again. An empty input buffer is passed in the first call.

Remarks

The EncryptMessage 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.

The prototype for this function can be found in Sspi.h.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in Sspi.h; include Security.h.
  Library: Use Secur32.lib.

See Also

AcceptSecurityContext, DecryptMessage, InitializeSecurityContext, QueryContextAttributes, SecBuffer, SecBufferDesc