Edit

Share via

SpSealMessageFn callback function (ntsecpkg.h)

  • Article

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

See also

SECPKG_USER_FUNCTION_TABLE

SpUnsealMessage

SpUserModeInitialize