Share via

DecryptMessage (Compact 2013)

  • Article

3/28/2014

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 CtxtHandle structure identifying the context handle. For information on CtxtHandle, see SSPI Handles.

  • pMessage
    [in, out] 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 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 SecBuffer structures. 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 SecBuffer structures. 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 DecryptMessage again.

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, 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 SecurityFunctionTable structure that is returned by InitSecurityInterface. The function pointer should be checked to make sure it is not NULL, because earlier versions of Windows Embedded Compact 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 EncryptMessage nor DecryptMessage cannot 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 DecryptMessage succeeded 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 DecryptMessage function 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 EncryptMessage call to the remote party (the sender of the decrypted message).
  3. Delete the security context by calling the DeleteSecurityContext function.

When you use the Schannel SSP, DecryptMessage returns 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

See Also

Reference

Authentication Services Functions