DecryptMessage

A version of this page is also available for

Windows Embedded CE 6.0 R3

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

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 Mobile did not export this function.

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

See Also

Reference

Authentication Services Functions