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.