AcceptSecurityContext (Windows Embedded CE 6.0)

1/6/2010

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.

Syntax

SECURITY_STATUS SEC_ENTRY AcceptSecurityContext( 
  PCredHandle phCredential, 
  PCtxtHandle phContext, 
  PSecBufferDesc pInput, 
  ULONG fContextReq, 
  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 Value

The following table shows the possible return values.

The following table shows the possible error values.

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:

1. The client transmits a token to the server.
2. The server calls AcceptSecurityContext the first time, generating a reply token.
3. The client passes this token in a second call to InitializeSecurityContext, which generates a final token.
4. 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:

1. The client connects to negotiate a protocol.
2. The server calls AcceptSecurityContext to set up a context and generate a challenge to the client.
3. The client calls InitializeSecurityContext and creates the response.
4. The server calls AcceptSecurityContext the final time to allow the security package to verify that the response is appropriate for the challenge.

Requirements

See Also

Reference

Authentication Services Functions
AcquireCredentialsHandle
InitializeSecurityContext
SecBufferDesc