Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function decrypts a message. Some packages do not encrypt and decrypt messages, but rather perform and check an integrity hash.

Syntax 

SECURITY_STATUS SEC_ENTRY DecryptMessage(
  PCtxtHandle 
phContext,
  PSecBufferDesc 
pMessage,
  ULONG 
MessageSeqNo,
  PULONG 
pfQOP
);

Parameters

phContext

[in] Pointer to a CtxtHandlestructure identifying the context handle. For information on CtxtHandle, see SSPI Handles.

pMessage

[in, out] Pointer to a SecBufferDescstructure. On input, the structure references one or more SecBufferstructures. One of these can be of type SECBUFFER_DATA. That buffer contains the encrypted message. The encrypted message is decrypted in place, and overwrites the original contents of its buffer.

When used with the Microsoft Digest SSP, on input, the structure references one or more SecBufferstructures. One of these must be of type SECBUFFER_DATA or SECBUFFER_STREAM, and it must contain the encrypted message.

When used with the Schannel SSP with contexts that are not connection-oriented, on input, the structure must contain four SecBufferstructures. Exactly one buffer must be of type SECBUFFER_DATA and contain an encrypted message, which is decrypted in place. The remaining buffers are used for output and must be of type SECBUFFER_EMPTY. For connection-oriented contexts, a SECBUFFER_DATA type buffer must be supplied, as noted for non-connection-oriented contexts. Additionally, a second SECBUFFER_TOKEN type buffer that contains a security token must also be supplied.

MessageSeqNo

[in] The sequence number expected by the transport application, if any. If the transport application does not maintain sequence numbers, this parameter must be set to zero.

For the Microsoft Digest and Schannel SSPs, specify as zero. Microsoft Digest manages sequence numbering internally and sequence numbers are not used with Schannel.

pfQOP

[out] Pointer to a variable of type ULONG that receives package-specific flags that indicate the quality of protection. This parameter should be set to NULL if it is not used.

Return Value

The function returns SEC_E_OK if it verifies that the message was received in the correct sequence. If the function fails to decrypt the message, the return value can be one of the following error codes.

Return Code Description

SEC_E_OUT_OF_SEQUENCE

The message was not received in the correct sequence.

SEC_E_MESSAGE_ALTERED

The message has been altered.

SEC_E_INVALID_HANDLE

An invalid context handle was specified in the phContext parameter. Used with the Microsoft Schannel SSPs.

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. Used with the Microsoft Digest SSP.

SEC_E_BUFFER_TOO_SMALL

The message buffer is too small.

SEC_E_INVALID_TOKEN

The buffers are of wrong type or no buffer of type SECBUFFER_DATA was found. Use with the Schannel SSP.

SEC_E_INCOMPLETE_MESSAGE

The data in the input buffer is incomplete. The application needs to read more data from the server and call DecryptMessageagain.

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 AcceptSecurityContextor InitializeSecurityContext, passing empty input buffers.

SEC_I_CONTEXT_EXPIRED

The message sender has finished using the connection and has initiated a shutdown.

Remarks

The application can obtain the pointer to this function from the SecurityFunctionTablestructure that is returned by InitSecurityInterface. The function pointer should be checked to make sure it is not NULL, because earlier versions of Windows Mobile did not export this function.

Note:
When Schannel SSP is used in "streaming" mode, that is, when the ISC_REQ_STREAM or ASC_REQ_STREAM flag is specified during the handshake, neither EncryptMessagenor DecryptMessagecannot 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 on the server, the decryption operation fails.

Sometimes an application will read data from the remote party, attempt to decrypt it with DecryptMessage, and discover that DecryptMessagesucceeded but the output buffers are empty. This is normal behavior, and applications must be able to deal with it.

When you use the Schannel SSP, the DecryptMessagefunction returns SEC_I_CONTEXT_EXPIRED when the message sender has shut down the connection. After receiving this return value, your application must complete the following steps:

  1. Call EncryptMessage, passing in an empty input buffer.

  2. Send the output buffers from the EncryptMessagecall to the remote party (the sender of the decrypted message).

  3. Delete the security context by calling the DeleteSecurityContextfunction.

When you use the Schannel SSP, DecryptMessagereturns SEC_I_RENEGOTIATE when the message sender wants to renegotiate the connection for security reasons. An application handles a requested renegotiation by calling AcceptSecurityContext(server side) or InitializeSecurityContext(client side) and passing in empty input buffers. After this initial call retrieves a value, your application should proceed as if it is creating a new connection.

Requirements

Header sspi.h
Library secur32.lib
Windows Embedded CE Windows CE .NET 4.2 and later
Windows Mobile Pocket PC 2000 and later, Smartphone 2002 and later

See Also