AcceptSecurityContext (Windows CE 5.0)
This function enables the server part 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 might need one or more reply tokens from the remote client to complete the establishment of the security context.
Note For the AcceptSecurityContext function, all input buffers must be aligned.
SECURITY_STATUS SEC_ENTRY AcceptSecurityContext( PCredHandle phCredential,PCtxtHandle phContext,PSecBufferDesc pInput,ULONGfContextReq,ULONG TargetDataRep,PCtxtHandle phNewContext,PSecBufferDesc pOutput,ULONG SEC_FAR*pfContextAttr,PTimeStamp ptsExpiry);
Parameters
- phCredential
[in] Pointer to a CredHandle structure representing the handle to server credentials. The server calls the AcquireCredentialsHandle function to retrieve this handle. For information about CredHandle, see SSPI Handles. - phContext
[in] Pointer to a CtxtHandle structure representing the context handle. On the first call to AcceptSecurityContext, this pointer is NULL. On the second call, this parameter indicates the handle to the partially formed context that was retrieved in the phNewContext parameter by the first call. For information about CtxtHandle, see SSPI Handles. - pInput
[in] Pointer to a SecBufferDesc structure that contains the input buffer descriptor. Depending on the security package, this parameter can be NULL if no initial token is ready. - fContextReq
[in] Set of bit flags that specify the attributes that the server requires for the context to be established. The following list shows the flags that can be used in any combination:- ASC_REQ_ALLOCATE_MEMORY
- ASC_REQ_ALLOW_CONTEXT_REPLAY
- ASC_REQ_ALLOW_NON_USER_LOGONS
- ASC_REQ_ALLOW_NULL_SESSION
- ASC_REQ_CALL_LEVEL
- ASC_REQ_CONFIDENTIALITY
- ASC_REQ_CONNECTION
- ASC_REQ_DATAGRAM
- ASC_REQ_DELEGATE
- ASC_REQ_EXTENDED_ERROR
- ASC_REQ_FRAGMENT_SUPPLIED
- ASC_REQ_FRAGMENT_TO_FIT
- ASC_REQ_IDENTIFY
- ASC_REQ_INTEGRITY
- ASC_REQ_LICENSING
- ASC_REQ_MUTUAL_AUTH
- ASC_REQ_REPLAY_DETECT
- ASC_REQ_STREAM
- ASC_REQ_SEQUENCE_DETECT
- ASC_REQ_USE_DCE_STYLE
- ASC_REQ_USE_SESSION_KEY
- TargetDataRep
[in] The data representation (byte ordering and so on) on the target. The caller can specify SECURITY_NATIVE_DREP to indicate that the native format is in use. - phNewContext
[out] Pointer to a CtxtHandle structure representing the handle to a new security context. On the first call to AcceptSecurityContext, this parameter contains the new context handle. On the second call, this parameter can be the same as the handle specified in the phContext parameter. For information about CtxtHandle, see SSPI Handles. - pOutput
[in] Pointer to a SecBufferDesc structure that contains the output buffer descriptor. - pfContextAttr
[out] Pointer to a set of bit flags indicating the attributes of the established context. For more information about context requirements, see Cryptography. The following list shows the possible flags:- ASC_RET_ALLOCATED_MEMORY
- ASC_RET_ALLOW_CONTEXT_REPLAY
- ASC_RET_ALLOW_NON_USER_LOGONS
- ASC_RET_CALL_LEVEL
- ASC_RET_CONFIDENTIALITY
- ASC_RET_CONNECTION
- ASC_RET_DATAGRAM
- ASC_RET_DELEGATE
- ASC_RET_EXTENDED_ERROR
- ASC_RET_FRAGMENT_ONLY
- ASC_RET_IDENTIFY
- ASC_RET_INTEGRITY
- ASC_RET_LICENSING
- ASC_RET_MUTUAL_AUTH
- ASC_RET_NULL_SESSION
- ASC_RET_REPLAY_DETECT
- ASC_RET_SEQUENCE_DETECT
- ASC_RET_STREAM
- ASC_RET_THIRD_LEG_FAILED
- ASC_RET_USED_DCE_STYLE
- ASC_RET_USE_SESSION_KEY
- ptsExpiry
[out] Pointer to the expiration time of the context. The security provider should always retrieve this value in local time.
Return Values
The following table shows the possible return values.
| Value | Description |
|---|---|
| SEC_E_OK | The security context was successfully established. |
| SEC_I_CONTINUE_NEEDED | The client must send the output token to the server and then pass the token retrieved by the server in a second call to InitializeSecurityContext. |
| SEC_I_COMPLETE_NEEDED | The client must finish building the message and then call the CompleteAuthToken function. |
| SEC_I_COMPLETE_AND_CONTINUE | The client must call CompleteAuthToken, then pass the output to the server, and finally make a second call to InitializeSecurityContext. |
The following table shows the possible error values.
| 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 could not be contacted. |
| SEC_E_NO_AUTHENTICATING_AUTHORITY | No authority could be contacted for authentication. |
Remarks
This 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 retrieved 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 the following 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 calls AcceptSecurityContext the final time to allow the security package to verify that the response is appropriate for the challenge.
Requirements
Pocket PC: Pocket PC 2000 and later.
Smartphone: Smartphone 2002 and later.
OS Versions: Windows CE 2.10 and later.
Header: Security.h, Sspi.h.
Link Library: Secur32.lib.
See Also
AcquireCredentialsHandle | InitializeSecurityContext | SecBufferDesc
Send Feedback on this topic to the authors