AcceptSecurityContext
This 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 function to start the process of establishing a security context. The server may need one or more reply tokens from the remote client to complete the establishment of the security context.
SECURITY_STATUS AcceptSecurityContext(
PCredHandle phCredential,
PCtxtHandle phContext,
PSecBufferDesc pInput,
ULONG fContextReq ,
ULONG TargetDataRep,
PCtxtHandle phNewContext,
PSecBufferDesc pOutput,
PULONG pfContextAttr ,
PTimeStamp ptsExpiry );
Parameters
phCredential
[in] Pointer to the handle to the server's credentials. The server calls the AcquireCredentialsHandle function to retrieve this handle.phContext
[in] Pointer to the handle of a CtxtHandle structure. On the first call to AcceptSecurityContext, this pointer is NULL. On the second call, this is the handle to the partially formed context that was returned in the phNewContext parameter by the first call.pInput
[in] Pointer to a SecBufferDesc structure that contains the input buffer descriptor. Depending on the security package, this parameter may be NULL if no initial token is ready.pfContextReq
[in] Set of bit flags that specify the attributes that the server requires for the context to be established. This value can include a combination of the following flags:ASC_REQ_ALLOCATE_MEMORY ASC_REQ_INTEGRITY ASC_REQ_CALL_LEVEL ASC_REQ_MUTUAL_AUTH ASC_REQ_CONFIDENTIALITY ASC_REQ_REPLAY_DETECT ASC_REQ_CONNECTION ASC_REQ_STREAM ASC_REQ_DATAGRAM ASC_REQ_SEQUENCE_DETECT ASC_REQ_DELEGATE ASC_REQ_USE_DCE_STYLE ASC_REQ_EXTENDED_ERROR ASC_REQ_USE_SESSION_KEY TargetDataRep
[in] Indicates the data representation (byte ordering, and so on) on the target. You can specify SECURITY_NATIVE_DREP to indicate that the native format is in use.phNewContext
[out] Pointer to a CtxtHandle structure. On the first call to AcceptSecurityContext, this pointer receives the new context handle. On the second call, this parameter can be the same as the handle specified in the phContext parameter.pOutput
[in] Pointer to a SecBufferDesc structure that contains the output buffer descriptor.pfContextAttr
[out] Pointer to a variable that receives a set of bit flags indicating the attributes of the established context. For more information about context requirements, see Cryptography. This value can include any of the following flags:ASC_RET_ALLOCATED_MEMORY ASC_RET_MUTUAL_AUTH ASC_RET_CALL_LEVEL ASC_RET_REPLAY_DETECT ASC_RET_CONFIDENTIALITY ASC_RET_SEQUENCE_DETECT ASC_RET_CONNECTION ASC_RET_STREAM ASC_RET_DATAGRAM ASC_RET_USED_DCE_STYLE ASC_RET_DELEGATE ASC_RET_USE_SESSION_KEY ASC_RET_EXTENDED_ERROR ASC_RET_THIRD_LEG_FAILED ASC_RET_INTEGRITY ptsExpiry
[out] Pointer to a PTimeStamp variable that receives the expiration time of the context. The security provider should always return this value in local time.
Return Values
Upon success, one of the values described in the following table is returned.
| Value | Description |
|---|---|
| SEC_E_OK | The security context was successfully established. |
| SEC_I_CONTINUE_NEEDED | |
| SEC_I_COMPLETE_NEEDED | |
| SEC_I_COMPLETE_AND_CONTINUE |
Upon failure, one of the error values described in the following table is returned.
| Value | Description |
|---|---|
| SEC_E_INVALID_TOKEN | The token passed to the function is invalid. |
| SEC_E_INVALID_HANDLE | The handle passed to the function is invalid. |
| SEC_E_LOGON_DENIED | The logon failed. |
| SEC_E_INTERNAL_ERROR | The Local Security Authority cannot be contacted. |
| SEC_E_NO_AUTHENTICATING_AUTHORITY | No authority could be contacted for authentication. |
Remarks
The AcceptSecurityContext function is the server counterpart to the InitializeSecurityContext function.
When a request comes in, 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 fail clients that cannot meet that demand. As an alternative, a server can require nothing, and whatever the client can provide or requires is returned in the pfContextAttr parameter.
For a package that supports three-leg mutual authentication, the calling sequence is as follows:
- The client transmits a token to the server.
- The server calls AcceptSecurityContext the first time, generating a reply token.
- The client passes this token in a second call to InitializeSecurityContext, which generates a final token.
- The server uses this token in the final call to AcceptSecurityContext to complete the session.
LAN Manager and Windows NT use another authentication style.
- The client connects to negotiate a protocol.
- The server calls AcceptSecurityContext to set up a context and generate a challenge to the client.
- The client calls InitializeSecurityContext and creates the response.
- The server then calls AcceptSecurityContext the final time to allow the security package to verify that the response is appropriate for the challenge.
Requirements
| Runs on | Versions | Defined in | Include | Link to |
|---|---|---|---|---|
| Windows CE OS | 2.10 and later | Sspi.h | Security.h | Schannel.lib |
Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.
See Also
AcquireCredentialsHandle, InitializeSecurityContext, SecBufferDesc
Last updated on Tuesday, July 13, 2004
© 1992-2000 Microsoft Corporation. All rights reserved.