Platform SDK: Logon Authentication

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 can require one or more reply tokens from the remote client to complete establishing 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 ptsTimeStamp    // receives the life span of the security context
);

Parameters

phCredential
[in] Handle to the server's credentials. The server calls the AcquireCredentialsHandle function with the INBOUND flag set to retrieve this handle.
phContext
[in/out] Pointer to a CtxtHandle structure. On the first call to AcceptSecurityContext, this pointer is NULL. On subsequent calls, phContext 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 generated by a client call to InitializeSecurityContext that contains the input buffer descriptor.
fContextReq
[in] Bit flags that specify the attributes required by the server to establish the context. Bit flags can be combined using bitwise OR operations. For possible attribute flags and their meanings, see Context Requirements. Flags used for this parameter are prefixed with ASC_REQ, such as ASC_REQ_DELEGATE.
TargetDataRep
[in] Indicates the data representation, such as byte ordering, on the target. Can be either SECURITY_NATIVE_DREP or SECURITY_NETWORK_DREP.
phNewContext
[in/out] Pointer to a CtxtHandle structure. On the first call to AcceptSecurityContext, this pointer receives the new context handle. On subsequent calls, phNewContext can be the same as the handle specified in the phContext parameter.
pOutput
[in/out] Pointer to a SecBufferDesc structure that contains the output buffer descriptor. This buffer is sent to the client for input into additional calls to InitializeSecurityContext. An output buffer may be generated even if the function returns SEC_E_OK. Any buffer generated must be sent back to the client application.
pfContextAttr
[out] 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. Flags used for this parameter are prefixed with ASC_RET, such as ASC_RET_DELEGATE.
ptsTimeStamp
[out] Pointer to a TimeStamp structure that receives the expiration time of the context. It is recommended that the security package always return this value in local time.

Note  Until the last call of the authentication process, the expiration time for the context can be incorrect because more information will be provided during later stages of the negotiation dialog. Therefore, ptsTimeStamp must be NULL until the last call to the function.

Return Values

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

Value Meaning
SEC_E_OK The security context received from the client was accepted. If an output token was generated by the function, it must be sent to the client process.
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 in pInput for another call to AcceptSecurityContext.
SEC_I_COMPLETE_NEEDED The server must finish building the message from the client, then call the CompleteAuthToken function.
SEC_I_COMPLETE_AND_CONTINUE The server must call CompleteAuthToken, then pass the output token to the client. The server then waits for a return token from the client, and makes another call to AcceptSecurityContext.

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

Value Meaning
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 An error occurred that did not map to an SSPI error code.
SEC_E_NO_AUTHENTICATING_AUTHORITY No authority could be contacted for authentication. This could be due to the domain name of the authenticating party being wrong, the domain being unreachable, or to a trust relationship failure.
SEC_E_INSUFFICIENT_MEMORY One or more of the SecBufferDesc structures passed as an OUT parameter has a buffer that is too small.

Remarks

The AcceptSecurityContext function is the server counterpart to the InitializeSecurityContext function.

When the server receives a request from a client, 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 reject clients that cannot meet that demand. Alternatively, a server can require nothing, and whatever the client can provide or requires is returned in the pfContextAttr parameter.

For a package that supports multi-leg authentication such as 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 which is sent to the client.
  3. The client receives the token and passes it to InitializeSecurityContext. If InitializeSecurityContext returns SS_E_OK, mutual authentication has been completed and a secure session can begin. If InitializeSecurityContext returns an error code, the mutual authentication dialog ends. Otherwise, the security token returned by InitializeSecurityContext is sent to the client and steps 2 and 3 are repeated.

The prototype for this function can be found in Sspi.h.

Requirements

  Windows NT/2000: Requires Windows NT 3.51 or later.
  Windows 95/98: Requires Windows 95 or later.
  Header: Declared in Sspi.h; include Security.h.
  Library: Use Secur32.lib.

See Also

InitializeSecurityContext

Built on Tuesday, February 08, 2000