DecryptMessage (Windows CE 5.0)
This function decrypts a message. Some packages do not encrypt and decrypt messages, but rather perform and check an integrity hash.
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 Values
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 CE 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:
- Call EncryptMessage, passing in an empty input buffer.
- Send the output buffers from the EncryptMessage call to the remote party (the sender of the decrypted message).
- 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
Pocket PC: Pocket PC 2000 and later.
Smartphone: Smartphone 2002 and later.
OS Versions: Windows CE .NET 4.2 and later.
Header: Sspi.h.
Link Library: Secur32.lib.
See Also
Authentication Services Functions
Send Feedback on this topic to the authors