AcceptSecurityContext (Digest) function

The AcceptSecurityContext (Digest) 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 (Digest) 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.

Syntax

SECURITY_STATUS SEC_Entry AcceptSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _Inout_opt_ PCtxtHandle    phContext,
  _In_opt_    PSecBufferDesc pInput,
  _In_        ULONG          fContextReq,
  _In_        ULONG          TargetDataRep,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Inout_opt_ PSecBufferDesc pOutput,
  _Out_       PULONG         pfContextAttr,
  _Out_opt_   PTimeStamp     ptsExpiry
);

Parameters

phCredential [in, optional]

A handle to the credentials of the server. The server calls the AcquireCredentialsHandle (Digest) function with either the SECPKG_CRED_INBOUND or SECPKG_CRED_BOTH flag set to retrieve this handle.

phContext [in, out, optional]

A pointer to a CtxtHandle structure. On the first call to AcceptSecurityContext (Digest), 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, optional]

A pointer to a SecBufferDesc structure generated by a client call to InitializeSecurityContext (Digest) that contains the input buffer descriptor.

The following table shows the buffer configuration for Digest HTTP. The first buffer must be of type SECBUFFER_TOKEN, and the rest must be of type SECBUFFER_PKG_PARAMS. SASL requires only buffer zero.

fContextReq [in]

Bit flags that specify the attributes required by the server to establish the context. Bit flags can be combined by using bitwise-OR operations. This parameter can be one or more of the following values.

For possible attribute flags and their meanings, see Context Requirements. Flags used for this parameter are prefixed with ASC_REQ, for example, ASC_REQ_DELEGATE.

The requested attributes may not be supported by the client. For more information, see the pfContextAttr parameter.

TargetDataRep [in]

The data representation, such as byte ordering, on the target. This parameter can be either SECURITY_NATIVE_DREP or SECURITY_NETWORK_DREP.

This parameter is not used with Digest SSP. When you use Digest SSP, specify zero for this parameter.

phNewContext [in, out, optional]

A pointer to a CtxtHandle structure. On the first call to AcceptSecurityContext (Digest), this pointer receives the new context handle. On subsequent calls, phNewContext can be the same as the handle specified in the phContext parameter. phNewContext should never be NULL.

pOutput [in, out, optional]

A 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 (Digest). 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]

A pointer to a variable that receives a set of bit flags that indicate 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, for example, ASC_RET_DELEGATE.

Do not check for security-related attributes until the final function call returns successfully. Attribute flags not related to security, such as the ASC_RET_ALLOCATED_MEMORY flag, can be checked before the final return.

ptsTimeStamp [out, optional]

A pointer to a TimeStamp structure that receives the expiration time of the context. We recommend that the security package always return this value in local time.

This parameter is set to a constant maximum time. There is no expiration time for Digest security contexts or credentials or when using the Digest SSP.

Return value

This function returns one of the following values:

Remarks

The AcceptSecurityContext (Digest) function is the server counterpart to the InitializeSecurityContext (Digest) 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 multiple-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 (Digest) the first time, which generates a reply token that is then sent to the client.
3. The client receives the token and passes it to InitializeSecurityContext (Digest). If InitializeSecurityContext (Digest) returns SEC_E_OK, mutual authentication has been completed and a secure session can begin. If InitializeSecurityContext (Digest) returns an error code, the mutual authentication negotiation ends. Otherwise, the security token returned by InitializeSecurityContext (Digest) is sent to the client, and steps 2 and 3 are repeated.
4. Do not use the phContext value in concurrent calls to AcceptSecurityContext (Digest). The implementation in the security providers is not thread-safe.

The fContextReq and pfContextAttr parameters are bitmasks that represent various context attributes. For a description of the various attributes, see Context Requirements.

The caller is responsible for determining whether the final context attributes are sufficient. If, for example, confidentiality (encryption) was requested, but could not be established, some applications may choose to shut down the connection immediately. If the security context cannot be established, the server must free the partially created context by calling the DeleteSecurityContext function. For information about when to call the DeleteSecurityContext function, see DeleteSecurityContext.

After the security context has been established, the server application can use the QuerySecurityContextToken function to retrieve a handle to the user account to which the client certificate was mapped. Also, the server can use the ImpersonateSecurityContext function to impersonate the user.

Requirements

See also

SSPI Functions

DeleteSecurityContext

InitializeSecurityContext (Digest)