AcceptSecurityContext (Compact 2013)

  • Article

3/28/2014

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.

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.

Value

Description

SEC_E_OK

The security context was successfully established.

SEC_I_CONTINUE_NEEDED

The server must send the output token to the client and wait for a returned token. The returned token should be passed for another call to AcceptSecurityContext.

SEC_I_COMPLETE_NEEDED

The server must finish building the message from the client and then call the CompleteAuthToken function.

SEC_I_COMPLETE_AND_CONTINUE

The server must call CompleteAuthToken and pass the output token to the client. The server then waits for a return token from the client and then makes another call to AcceptSecurityContext.

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:

  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

Header

security.h,
sspi.h

Library

secur32.lib

See Also

Reference

Authentication Services Functions
AcquireCredentialsHandle
InitializeSecurityContext
SecBufferDesc