AcceptSecurityContext function (sspi.h)
The AcceptSecurityContext (CredSSP) function lets the server component of a transport application establish a security context between the server and a remote client. The remote client calls the InitializeSecurityContext (CredSSP) 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.
Syntax
KSECDDDECLSPEC SECURITY_STATUS SEC_ENTRY AcceptSecurityContext(
[in, optional] PCredHandle phCredential,
[in, optional] PCtxtHandle phContext,
[in, optional] PSecBufferDesc pInput,
[in] unsigned long fContextReq,
[in] unsigned long TargetDataRep,
[in, out, optional] PCtxtHandle phNewContext,
[in, out, optional] PSecBufferDesc pOutput,
[out] unsigned long *pfContextAttr,
[out, optional] PTimeStamp ptsExpiry
);
Parameters
[in, optional] phCredential
A handle to the server credentials. To retrieve this handle, the server calls the AcquireCredentialsHandle (CredSSP) function with either the SECPKG_CRED_INBOUND or SECPKG_CRED_BOTH flag set.
[in, optional] phContext
A pointer to a CtxtHandle structure. On the first call to AcceptSecurityContext (CredSSP), this pointer is NULL. On subsequent calls, phContext specifies the partially formed context returned in the phNewContext parameter by the first call.
[in, optional] pInput
A pointer to a SecBufferDesc structure generated by a client call to InitializeSecurityContext (CredSSP). The structure contains the input buffer descriptor.
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.
[in] fContextReq
-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 |
|---|---|
|
Credential Security Support Provider (CredSSP) will allocate output buffers. When you have finished using the output buffers, free them by calling the FreeContextBuffer function. |
|
The security context will not handle formatting messages. |
|
The server is allowed to impersonate the client. Ignore this flag for constrained delegation. |
|
When errors occur, the remote party will be notified. |
|
Detect replayed packets. |
|
Detect messages received out of sequence. |
|
Support a stream-oriented connection. |
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.
[in] TargetDataRep
The data representation, such as byte ordering, on the target. This parameter can be either SECURITY_NATIVE_DREP or SECURITY_NETWORK_DREP.
[in, out, optional] phNewContext
A pointer to a CtxtHandle structure. On the first call to AcceptSecurityContext (CredSSP), this pointer receives the new context handle. On subsequent calls, phNewContext can be the same as the handle specified in the phContext parameter.
[in, out, optional] pOutput
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 (CredSSP). 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.
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.
[out] pfContextAttr
A pointer to 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.
[out, optional] ptsExpiry
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.
Return value
This function returns one of the following values.
| Return code/value | Description |
|---|---|
|
The function succeeded. The data in the input buffer is incomplete. The application must read additional data from the client and call AcceptSecurityContext (CredSSP) again. |
|
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. |
|
The function succeeded. The security context received from the client was accepted. If the function generated an output token, the token must be sent to the client process. |
|
The function failed. The fContextReq parameter specified a context attribute flag (ASC_REQ_DELEGATE or ASC_REQ_PROMPT_FOR_CREDS) that was not valid. |
|
The function succeeded. The server must call CompleteAuthToken and pass the output token to the client. The server must then wait for a return token from the client before making another call to AcceptSecurityContext (CredSSP). |
|
The function succeeded. The server must finish building the message from the client before calling CompleteAuthToken. |
|
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 (CredSSP). |
Remarks
The AcceptSecurityContext (CredSSP) function is the server counterpart to the InitializeSecurityContext (CredSSP) function.
When the server receives a request from a client, it uses the fContextReq parameter to specify what it requires of the session. In this fashion, a server can require that clients be capable of using a confidential or integrity-checked session; it can reject clients that cannot meet that demand. Alternatively, a server can require nothing; whatever the client requires or can provide is returned in the pfContextAttr parameter.
The fContextReq and pfContextAttr parameters are bitmasks that represent various context attributes. For a description of the various attributes, see Context Requirements.
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 Vista [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Target Platform | Windows |
| Header | sspi.h (include Security.h) |
| Library | Secur32.lib |
| DLL | Secur32.dll |