ApplyControlToken function (sspi.h)

Article
10/13/2021

The ApplyControlToken function provides a way to apply a control token to a security context. A token can be received when the security context is being established by a call to the InitializeSecurityContext (Schannel) function or with a per-message security service, such as verify or unseal.

This function is supported only by the Schannel security support provider (SSP).

This function is not supported in kernel mode.

This function allows additional or replacement tokens to be applied to a context.

Syntax

KSECDDDECLSPEC SECURITY_STATUS SEC_ENTRY ApplyControlToken(
  [in] PCtxtHandle    phContext,
  [in] PSecBufferDesc pInput
);

Parameters

[in] phContext

A handle to the context to which the token is applied.

For information about the way the Schannel SSP notifies the remote party of the shutdown, see the Remarks section of DecryptMessage (Schannel). For additional information on the use of this function, see Shutting Down an Schannel Connection.

[in] pInput

A pointer to a SecBufferDesc structure that contains a pointer to a SecBuffer structure that contains the input token to apply to the context.

Return value

If the function succeeds, the function returns SEC_E_OK.

If the function fails, it returns a nonzero error code. The following error code is one of the possible error codes that can be returned.

Return code	Description
SEC_E_UNSUPPORTED_FUNCTION	This value is returned by Schannel kernel mode to indicate that this function is not supported.

Remarks

The ApplyControlToken function can modify the context based on this token. Among the tokens that this function can add to the client context are SCHANNEL_ALERT_TOKEN and SCHANNEL_SESSION_TOKEN.

This function can be used to shut down the security context that underlies an existing Schannel connection. For information about how to do this, see Shutting Down an Schannel Connection.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	sspi.h (include Security.h)
Library	Secur32.lib
DLL	Secur32.dll