SpSealMessageFn callback function (ntsecpkg.h)

Article
02/22/2024

Encrypts a message exchanged between a client and server.

The SpSealMessage function is the dispatch function for the EncryptMessage (General) function of the Security Support Provider Interface.

Syntax

SpSealMessageFn Spsealmessagefn;

NTSTATUS Spsealmessagefn(
  [in]      LSA_SEC_HANDLE ContextHandle,
  [in]      ULONG QualityOfProtection,
  [in, out] PSecBufferDesc MessageBuffers,
  [in]      ULONG MessageSequenceNumber
)
{...}

Parameters

[in] ContextHandle

Handle of the security context used to sign the message.

[in] QualityOfProtection

Specifies package-specific flags that indicate the quality of protection. An SSP/AP can use this parameter to enable the selection of cryptographic algorithms.

[in, out] MessageBuffers

Pointer to a SecBufferDesc structure that contains message buffers. Only one of these message buffers can be of type SECBUFFER_DATA, and it contains the message to be encrypted. The buffer cannot have the SECBUFFER_READONLY attribute because the encryption is done in-place.

[in] MessageSequenceNumber

Sequence number to assign to the message. Sequence numbers are optional and are used as protection against loss and insertion of messages. A value of zero indicates that sequence numbers are not in use.

Return value

If the function succeeds, return STATUS_SUCCESS.

If the function fails, return an NTSTATUS code that indicates the reason it failed. The following table lists common reasons for failure and the error codes that the function should return.

Return code	Description
STATUS_INVALID_HANDLE	The context could not be found or was not configured for message integrity.
STATUS_INVALID_PARAMETER	The signature buffer could not be found or was too small.

Remarks

Messages encrypted by the sender using the SpSealMessage function are decrypted using the SpUnsealMessage function.

SSP/APs must implement the SpSealMessage function; however, the actual name given to the implementation is up to the developer.

A pointer to the SpSealMessage function is available in the SECPKG_USER_FUNCTION_TABLE structure received from the SpUserModeInitialize function.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	ntsecpkg.h