AcceptSecurityContext

The AcceptSecurityContext 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,  // handle to the credentials
  PCtxtHandle phContext,     // handle of partially formed context
  PSecBufferDesc pInput,     // pointer to the input buffers
  ULONG fContextReq,         // required context attributes
  ULONG TargetDataRep,       // data representation on the target
  PCtxtHandle phNewContext,  // receives the new context handle
  PSecBufferDesc pOutput,    // pointer to the output buffers
  PULONG pfContextAttr,      // receives the context attributes
  PTimeStamp ptsExpiry       // receives the life span of the security 
                             // context
);
 

Parameters

phCredential

Handle to the server's credentials. The server calls the AcquireCredentialsHandle function to retrieve this handle.

phContext

Pointer to a CtxtHandle structure. On the first call to AcceptSecurityContext, this pointer is NULL. On the second call, this the handle to the partially formed context that was returned in the phNewContext parameter by the first call.

pInput

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.

fContextReqs

A 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_DELEGATE
ASC_REQ_MUTUAL_AUTH
ASC_REQ_REPLAY_DETECT
ASC_REQ_SEQUENCE_DETECT
ASC_REQ_CONFIDENTIALITY
ASC_REQ_USE_SESSION_KEY
ASC_REQ_ALLOCATE_MEMORY
ASC_REQ_USE_DCE_STYLE
ASC_REQ_DATAGRAM
ASC_REQ_CONNECTION
ASC_REQ_CALL_LEVEL
ASC_REQ_EXTENDED_ERROR
ASC_REQ_STREAM
ASC_REQ_INTEGRITY

TargetDataRep

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

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

Pointer to a SecBufferDesc structure that contains the output buffer descriptor.

pfContextAttributes

Pointer to a variable that receives a set of bit flags indicating the attributes of the established context. For a description of the various attributes, see Context Requirements. This value can include any of the following flags:

ASC_RET_DELEGATE
ASC_RET_MUTUAL_AUTH
ASC_RET_REPLAY_DETECT
ASC_RET_SEQUENCE_DETECT
ASC_RET_CONFIDENTIALITY
ASC_RET_USE_SESSION_KEY
ASC_RET_ALLOCATED_MEMORY
ASC_RET_USED_DCE_STYLE
ASC_RET_DATAGRAM
ASC_RET_CONNECTION
ASC_RET_CALL_LEVE
ASC_RET_THIRD_LEG_FAILED
ASC_RET_EXTENDED_ERROR
ASC_RET_STREAM
ASC_RET_INTEGRITY

ptsExpiry

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

If the function succeeds, the return value is one of the following success codes.

If the function fails, the return value is one of the following error codes.

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.

See Also

InitializeSecurityContext