EncryptMessage (Kerberos) function
The EncryptMessage (Kerberos) function encrypts a message to provide privacy. EncryptMessage (Kerberos) allows an application to choose among cryptographic algorithms supported by the chosen mechanism. The EncryptMessage (Kerberos) 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.
Note
EncryptMessage (Kerberos) and DecryptMessage (Kerberos) can be called at the same time from two different threads in a single security support provider interface (SSPI) context if one thread is encrypting and the other is decrypting. If more than one thread is encrypting, or more than one thread is decrypting, each thread should obtain a unique context.
Syntax
SECURITY_STATUS SEC_Entry EncryptMessage(
_In_ PCtxtHandle phContext,
_In_ ULONG fQOP,
_Inout_ PSecBufferDesc pMessage,
_In_ ULONG MessageSeqNo
);
Parameters
-
phContext [in]
-
A handle to the security context to be used to encrypt the message.
-
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.
This parameter can be the following flag.
Value Meaning SECQOP_WRAP_NO_ENCRYPT Produce a header or trailer but do not encrypt the message.
Note: KERB_WRAP_NO_ENCRYPT has the same value and the same meaning. -
pMessage [in, out]
-
A pointer to a SecBufferDesc structure. On input, the structure references one or more SecBuffer structures that can be of type SECBUFFER_DATA. That buffer contains the message to be encrypted. The message is encrypted in place, overwriting the original contents of the structure.
The function does not process buffers with the SECBUFFER_READONLY attribute.
The length of the SecBuffer structure that contains the message must be no greater than cbMaximumMessage, which is obtained from the QueryContextAttributes (Kerberos) (SECPKG_ATTR_STREAM_SIZES) function.
Applications that do not use SSL must supply a SecBuffer of type SECBUFFER_PADDING.
-
MessageSeqNo [in]
-
The sequence number that the transport application assigned to the message. If the transport application does not maintain sequence numbers, this parameter must be zero.
Return value
If the function succeeds, the function returns SEC_E_OK.
If the function fails, it returns one of the following error codes.
| Return code | Description |
|---|---|
|
The output buffer is too small. For more information, see Remarks. |
|
The application is referencing a context that has already been closed. A properly written application should not receive this error. |
|
The cipher chosen for the security context is not supported. |
|
There is not enough memory available to complete the requested action. |
|
A context handle that is not valid was specified in the phContext parameter. |
|
No SECBUFFER_DATA type buffer was found. |
|
Neither confidentiality nor integrity are supported by the security context. |
Remarks
The EncryptMessage (Kerberos) function encrypts a message based on the message and the session key from a security context.
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.
Note
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. |
For optimal performance, the pMessage structures should be allocated from contiguous memory.
Windows XP: This function was also known as SealMessage. Applications should now use EncryptMessage (Kerberos) only.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Header | Sspi.h (include Security.h) |
| Library | Secur32.lib |
| DLL | Secur32.dll |