AcceptSecurityContext (General) function
The AcceptSecurityContext (General) function enables the server component of a transport application to establish a security context between the server and a remote client. The remote client uses the InitializeSecurityContext (General) function to start the process of establishing a security context. The server can require one or more reply tokens from the remote client to complete establishing the security context.
For information about using this function with a specific security support provider (SSP), see the following topics.
| Topic | Description |
|---|---|
| AcceptSecurityContext (CredSSP) | Allows the server component of a transport application establish a security context between the server and a remote client by using Credential Security Support Provider (CredSSP). |
| AcceptSecurityContext (Digest) | Enables the server component of a transport application to establish a security context between the server and a remote client that is using Digest. |
| AcceptSecurityContext (Kerberos) | Enables the server component of a transport application to establish a security context between the server and a remote client that is using Kerberos. |
| AcceptSecurityContext (Negotiate) | Enables the server component of a transport application to establish a security context between the server and a remote client that is using Negotiate. |
| AcceptSecurityContext (NTLM) | Enables the server component of a transport application to establish a security context between the server and a remote client that is using NTLM. |
| AcceptSecurityContext (Schannel) | Enables the server component of a transport application to establish a security context between the server and a remote client that is using Schannel. |
Syntax
SECURITY_STATUS SEC_Entry AcceptSecurityContext(
_In_opt_ PCredHandle phCredential,
_Inout_opt_ PCtxtHandle phContext,
_In_opt_ PSecBufferDesc pInput,
_In_ ULONG fContextReq,
_In_ ULONG TargetDataRep,
_Inout_opt_ PCtxtHandle phNewContext,
_Inout_opt_ PSecBufferDesc pOutput,
_Out_ PULONG pfContextAttr,
_Out_opt_ PTimeStamp ptsExpiry
);
Parameters
phCredential [in, optional]
A handle to the credentials of the server. The server calls the AcquireCredentialsHandle (General) function with either the SECPKG_CRED_INBOUND or SECPKG_CRED_BOTH flag set to retrieve this handle.
phContext [in, out]
A pointer to a CtxtHandle structure. On the first call to AcceptSecurityContext (General), this pointer is NULL. On subsequent calls, phContext is the handle to the partially formed context that was returned in the phNewContext parameter by the first call.
Warning
Do not use the same context handle in concurrent calls to AcceptSecurityContext (General). The API implementation in the security service providers is not thread-safe.
pInput [in, optional]
A pointer to a SecBufferDesc structure generated by a client call to InitializeSecurityContext (General) that contains the input buffer descriptor.
When using the Schannel SSP, the first buffer must be of type SECBUFFER_TOKEN and contain the security token received from the client. The second buffer should be of type SECBUFFER_EMPTY.
When using the Negotiate, Kerberos, or NTLM SSPs, channel binding information can be specified by passing in a SecBuffer structure of type SECBUFFER_CHANNEL_BINDINGS in addition to the buffers generated by the call to the InitializeSecurityContext (General) function. The channel binding information for the channel binding buffer can be obtained by calling the QueryContextAttributes (Schannel) function on the Schannel context the client used to authenticate.
fContextReq [in]
Bit flags that specify the attributes required by the server to establish the context. Bit flags can be combined by using bitwise-OR operations. This parameter can be one or more of the following values.
| Value | Meaning |
|---|---|
| ASC_REQ_ALLOCATE_MEMORY | Digest and Schannel will allocate output buffers for you. When you have finished using the output buffers, free them by calling the FreeContextBuffer function. |
| ASC_REQ_ALLOW_MISSING_BINDINGS | Indicates that Digest does not require channel bindings for both inner and outer channels. This value is used for backward compatibility when support for endpoint channel binding is not known. This value is mutually exclusive with ASC_REQ_PROXY_BINDINGS. This value is supported only by the Digest SSP. Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: This value is not supported. |
| ASC_REQ_CONFIDENTIALITY | Encrypt and decrypt messages. The Digest SSP supports this flag for SASL only. |
| ASC_REQ_CONNECTION | The security context will not handle formatting messages. |
| ASC_REQ_DELEGATE | The server is allowed to impersonate the client. Valid for Kerberos. Ignore this flag for constrained delegation. |
| ASC_REQ_EXTENDED_ERROR | When errors occur, the remote party will be notified. |
| ASC_REQ_HTTP (0x10000000) | Use Digest for HTTP. Omit this flag to use Digest as an SASL mechanism. |
| ASC_REQ_INTEGRITY | Sign messages and verify signatures. Schannel does not support this flag. |
| ASC_REQ_MUTUAL_AUTH | The client is required to supply a certificate to be used for client authentication. This flag is supported only by Schannel. |
| ASC_REQ_PROXY_BINDINGS | Indicates that Digest requires channel binding. This value is mutually exclusive with ASC_REQ_ALLOW_MISSING_BINDINGS. This value is supported only by the Digest SSP. Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: This value is not supported. |
| ASC_REQ_REPLAY_DETECT | Detect replayed packets. |
| ASC_REQ_SEQUENCE_DETECT | Detect messages received out of sequence. |
| ASC_REQ_STREAM | Support a stream-oriented connection. This flag is supported only by Schannel. |
For possible attribute flags and their meanings, see Context Requirements. Flags used for this parameter are prefixed with ASC_REQ, for example, ASC_REQ_DELEGATE.
The requested attributes may not be supported by the client. For more information, see the pfContextAttr parameter.
TargetDataRep [in]
The data representation, such as byte ordering, on the target. This parameter can be either SECURITY_NATIVE_DREP or SECURITY_NETWORK_DREP.
This parameter is not used with Schannel or Digest SSPs. When you use Schannel or Digest SSPs, specify zero for this parameter.
phNewContext [in, out, optional]
A pointer to a CtxtHandle structure. On the first call to AcceptSecurityContext (General), this pointer receives the new context handle. On subsequent calls, phNewContext can be the same as the handle specified in the phContext parameter. phNewContext should never be NULL.
pOutput [in, out, optional]
A pointer to a SecBufferDesc structure that contains the output buffer descriptor. This buffer is sent to the client for input into additional calls to InitializeSecurityContext (General). An output buffer may be generated even if the function returns SEC_E_OK. Any buffer generated must be sent back to the client application.
When using Schannel, on output, this buffer receives a token for the security context. The token must be sent to the client. The function can also return a buffer of type SECBUFFER_EXTRA. In addition, the caller must pass in a buffer of type SECBUFFER_ALERT. On output, if an alert is generated, this buffer contains information about that alert, and the function fails.
pfContextAttr [out]
A pointer to a variable that receives a set of bit flags that indicate the attributes of the established context. For a description of the various attributes, see Context Requirements. Flags used for this parameter are prefixed with ASC_RET, for example, ASC_RET_DELEGATE.
Do not check for security-related attributes until the final function call returns successfully. Attribute flags not related to security, such as the ASC_RET_ALLOCATED_MEMORY flag, can be checked before the final return.
ptsTimeStamp [out, optional]
A pointer to a TimeStamp structure that receives the expiration time of the context. We recommend that the security package always return this value in local time.
This parameter is set to a constant maximum time. There is no expiration time for Digest security contexts or credentials or when using the Digest SSP.
This is optional when using the Schannel SSP. When the remote party has supplied a certificate to be used for authentication, this parameter receives the expiration time for that certificate. If no certificate was supplied, a maximum time value is returned.
Note
Until the last call of the authentication process, the expiration time for the context can be incorrect because more information will be provided during later stages of the negotiation. Therefore, ptsTimeStamp must be NULL until the last call to the function.
Return value
This function returns one of the following values.
| Return code/value | Description |
|---|---|
| The function failed. Channel binding policy was not satisfied. |
| The function succeeded. The data in the input buffer is incomplete. The application must read additional data from the client and call [AcceptSecurityContext (General)](acceptsecuritycontext--general.md) again. This value can be returned when using the Schannel SSP. For more information about this return value, see [AcceptSecurityContext (Schannel)](acceptsecuritycontext--schannel.md). |
| The function failed. There is not enough memory available to complete the requested action. |
| The function failed. An error occurred that did not map to an SSPI error code. |
| The function failed. The handle passed to the function is not valid. |
| The function failed. The token passed to the function is not valid. |
| The logon failed. |
| The function failed. No authority could be contacted for authentication. This could be due to the following conditions:
|
| The function failed. The credentials handle specified in the phCredential parameter is not valid. This value can be returned when using the Digest or Schannel SSP. |
| The function succeeded. The [*security context*](../secgloss/s-gly.md) received from the client was accepted. If an output token was generated by the function, it must be sent to the client process. |
| The function failed. A context attribute flag that is not valid was specified in the fContextReq parameter. This value can be returned when using the Digest SSP. |
| The function failed. A context attribute flag that is not valid (ASC_REQ_DELEGATE or ASC_REQ_PROMPT_FOR_CREDS) was specified in the fContextReq parameter. This value can be returned when using the Schannel SSP. |
| The function succeeded. The server must call [CompleteAuthToken](/windows/win32/api/sspi/nf-sspi-completeauthtoken) and pass the output token to the client. The server then waits for a return token from the client and then makes another call to [AcceptSecurityContext (General)](acceptsecuritycontext--general.md). |
| The function succeeded. The server must finish building the message from the client and then call the [CompleteAuthToken](/windows/win32/api/sspi/nf-sspi-completeauthtoken) function. |
| The function succeeded. The server must send the output token to the client and wait for a returned token. The returned token should be passed in pInput for another call to [AcceptSecurityContext (General)](acceptsecuritycontext--general.md). |
| The function failed. The [AcceptSecurityContext (General)](acceptsecuritycontext--general.md) function was called after the specified context was established. This value can be returned when using the Digest SSP. |
Remarks
The AcceptSecurityContext (General) function is the server counterpart to the InitializeSecurityContext (General) function.
When the server receives a request from a client, the server uses the fContextReq parameter to specify what it requires of the session. In this fashion, a server can specify that clients must be capable of using a confidential or integrity-checked session, and it can reject clients that cannot meet that demand. Alternatively, a server can require nothing, and whatever the client can provide or requires is returned in the pfContextAttr parameter.
For a package that supports multiple-leg authentication, such as mutual authentication, the calling sequence is as follows:
- The client transmits a token to the server.
- The server calls AcceptSecurityContext (General) the first time, which generates a reply token that is then sent to the client.
- The client receives the token and passes it to InitializeSecurityContext (General). If InitializeSecurityContext (General) returns SEC_E_OK, mutual authentication has been completed and a secure session can begin. If InitializeSecurityContext (General) returns an error code, the mutual authentication negotiation ends. Otherwise, the security token returned by InitializeSecurityContext (General) is sent to the client, and steps 2 and 3 are repeated.
- Do not use the phContext value in concurrent calls to AcceptSecurityContext (General). The implementation in the security providers is not thread-safe.
The fContextReq and pfContextAttr parameters are bitmasks that represent various context attributes. For a description of the various attributes, see Context Requirements.
Note
The pfContextAttr parameter is valid on any successful return, but only on the final successful return should you examine the flags pertaining to security aspects of the context. Intermediate returns can set, for example, the ISC_RET_ALLOCATED_MEMORY flag.
The caller is responsible for determining whether the final context attributes are sufficient. If, for example, confidentiality (encryption) was requested, but could not be established, some applications may choose to shut down the connection immediately. If the security context cannot be established, the server must free the partially created context by calling the DeleteSecurityContext function. For information about when to call the DeleteSecurityContext function, see DeleteSecurityContext.
After the security context has been established, the server application can use the QuerySecurityContextToken function to retrieve a handle to the user account to which the client certificate was mapped. Also, the server can use the ImpersonateSecurityContext function to impersonate the user.
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 |
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for