EncryptMessage (Windows CE 5.0)
This function encrypts a message to help provide privacy.
SECURITY_STATUS SEC_ENTRY EncryptMessage( PCtxtHandle phContext, ULONG fQOP, PSecBufferDesc pMessage, ULONG MessageSeqNo);
Parameters
phContext
[in] Pointer to a CtxtHandle structure identifying the security context handle. For information on CtxtHandle, see SSPI Handles.fQOP
[in] Package-specific flags that indicate the quality of protection. A security package can use this parameter to enable the selection of cryptographic algorithms. For most security packages this parameter is not used and should be set to zero.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 the SecBuffer structure 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] The message sequence number that the transport application assigned to the message. If the transport application does not maintain sequence numbers, this parameter must be zero.The value of this parameter is not used with the Schannel SSPs. Zero should be used for this parameter when you use either of these SSPs.
Return Values
Returns SEC_E_OK to indicate success. If the function fails, the return value is one of the following error codes.
| Return Code | Description |
|---|---|
| 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 again. An empty input buffer is passed in the first call. |
| SEC_E_INVALID_HANDLE | The phContext parameter was passed an invalid context handle. |
| SEC_E_INVALID_TOKEN | A buffer of type SECBUFFER_DATA was not found. |
| 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. |
| SEC_E_BUFFER_TOO_SMALL | The output buffer is too small. For more information, see Remarks. |
| SEC_E_INSUFFICIENT_MEMORY | The requested action cannot be completed because of insufficient memory. |
| SEC_E_CONTEXT_EXPIRED | The application is referencing a context that has already been closed. A properly written application should not receive this error. |
Remarks
EncryptMessage enables 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 or decrypted, but rather provide an integrity hash that can be checked.
The Schannel SSP encrypts messages by using a session key negotiated with the remote party that will receive the message. The encryption algorithm is determined by the cipher suite in use.
Note When using the Schannel SSP in "streaming" mode, that is, when the ISC_REQ_STREAM or ASC_REQ_STREAM flag is specified during the handshake, neither EncryptMessage nor DecryptMessage can 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 server, the decryption operation fails.
The EncryptMessage function encrypts a message based on the message and the session key from a security context.
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, since earlier versions of Windows CE did not export this function.
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.
When used with the Schannel SSP, the pMessage parameter must contain a SecBufferDesc structure with the buffers described in the following table. These buffers must be supplied in the order shown.
| Buffer Type | Description |
|---|---|
| SECBUFFER_STREAM_HEADER | Used internally. No initialization required. |
| SECBUFFER_DATA | Contains the plaintext message to be encrypted. |
| SECBUFFER_STREAM_TRAILER | Used internally. No initialization required. |
| SECBUFFER_EMPTY | Used internally. No initialization required. Size can be zero. |
When you use the Schannel SSP, determine the maximum size of each of the buffers by calling the QueryContextAttributes function and specifying the SECPKG_ATTR_STREAM_SIZES attribute. This function retrieves a SecPkgContext_StreamSizes structure having members that contain the maximum sizes for the header (cbHeader member), message (cbMaximumMessage member), and trailer (cbTrailer member) buffers.
For optimal performance, the pMessage structures should be allocated from contiguous memory.
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