InitializeSecurityContext (CredSSP) function

The InitializeSecurityContext (CredSSP) function initiates the client side, outbound security context from a credential handle. The function builds a security context between the client application and a remote peer. InitializeSecurityContext (CredSSP) returns a token that the client must pass to the remote peer; the peer in turn submits that token to the local security implementation through the AcceptSecurityContext (CredSSP) call. The token generated should be considered opaque by all callers.

Typically, the InitializeSecurityContext (CredSSP) function is called in a loop until a sufficient security context is established.

Syntax

SECURITY_STATUS SEC_ENTRY InitializeSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _In_opt_    PCtxtHandle    phContext,
  _In_opt_    SEC_CHAR       *pszTargetName,
  _In_        unsigned long  fContextReq,
  _Reserved_  unsigned long  Reserved1,
  _In_        unsigned long  TargetDataRep,
  _Inout_opt_ PSecBufferDesc pInput,
  _In_        unsigned long  Reserved2,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Out_opt_   PSecBufferDesc pOutput,
  _Out_       unsigned long  *pfContextAttr,
  _Out_opt_   PTimeStamp     ptsExpiry
);

Parameters

phCredential [in, optional]

A handle to the credentials returned by AcquireCredentialsHandle (CredSSP). This handle is used to build the security context. The InitializeSecurityContext (CredSSP) function requires at least OUTBOUND credentials.

phContext [in, optional]

A pointer to a CtxtHandle structure. On the first call to InitializeSecurityContext (CredSSP), this pointer is NULL. On the second call, this parameter is a pointer to the handle to the partially formed context returned in the phNewContext parameter by the first call.

On the first call to InitializeSecurityContext (CredSSP), specify NULL. On future calls, specify the token received in the phNewContext parameter after the first call to this function.

pTargetName [in, optional]

A pointer to a null-terminated string that uniquely identifies the target server. Schannel uses this value to verify the server certificate. Schannel also uses this value to locate the session in the session cache when reestablishing a connection. The cached session is used only if all of the following conditions are met:

• The target name is the same.
• The cache entry has not expired.
• The application process that calls the function is the same.
• The logon session is the same.
• The credential handle is the same.

fContextReq [in]

Bit flags that indicate requests for the context. Not all packages can support all requirements. Flags used for this parameter are prefixed with ISC_REQ_, for example, ISC_REQ_DELEGATE.

This parameter can be one or more of the following attributes flags.

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

For further descriptions of the various attributes, see Context Requirements.

Reserved1 [in]

Reserved. This parameter must be set to zero.

TargetDataRep [in]

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

pInput [in, out, optional]

A pointer to a SecBufferDesc structure that contains pointers to the buffers supplied as input to the package. Unless the client context was initiated by the server, the value of this parameter must be NULL on the first call to the function. On subsequent calls to the function or when the client context was initiated by the server, the value of this parameter is a pointer to a buffer allocated with enough memory to hold the token returned by the remote computer.

On calls to this function after the initial call, there must be two buffers. The first has type SECBUFFER_TOKEN and contains the token received from the server. The second buffer has type SECBUFFER_EMPTY; set both the pvBuffer and cbBuffer members to zero.

Reserved2 [in]

Reserved. This parameter must be set to zero.

phNewContext [in, out, optional]

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

pOutput [out, optional]

A pointer to a SecBufferDesc structure. This structure in turn contains pointers to the SecBuffer structure that receives the output data. If a buffer was typed as SEC_READWRITE in the input, it will be there on output. The system will allocate a buffer for the security token if requested (through ISC_REQ_ALLOCATE_MEMORY) and fill in the address in the buffer descriptor for the security token.

If the ISC_REQ_ALLOCATE_MEMORY flag is specified, CredSSP will allocate memory for the buffer and put the appropriate information in the SecBufferDesc.

pfContextAttr [out]

A pointer to 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 ISC_RET, such as ISC_RET_DELEGATE. For a list of valid values, see the fContextReq parameter.

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

ptsExpiry [out, optional]

A 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. This parameter is optional and NULL should be passed for short-lived clients.

Return value

If the function succeeds, it returns one of the following success codes.

If the function fails, the function returns one of the following error codes.

Remarks

The caller is responsible for determining whether the final context attributes are sufficient. If, for example, confidentiality was requested, but could not be established, some applications may choose to shut down the connection immediately.

If attributes of the security context are not sufficient, the client must free the partially created context by calling the DeleteSecurityContext function.

The client calls the InitializeSecurityContext (CredSSP) function to initialize an outbound context.

For a two-leg security context, the calling sequence is as follows:

1. The client calls the function with phContext set to NULL and fills in the buffer descriptor with the input message.
2. The security package examines the parameters and constructs an opaque token, placing it in the TOKEN element in the buffer array. If the fContextReq parameter includes the ISC_REQ_ALLOCATE_MEMORY flag, the security package allocates the memory and returns the pointer in the TOKEN element.
3. The client sends the token returned in the pOutput buffer to the target server. The server then passes the token as an input argument in a call to the AcceptSecurityContext (CredSSP) function.
4. AcceptSecurityContext (CredSSP) may return a token. The server sends this token to the client through a second InitializeSecurityContext (CredSSP) call if the first call returned SEC_I_CONTINUE_NEEDED.

If the server has successfully responded, the security package returns SEC_E_OK and a secure session is established.

If the function returns one of the error responses, the server's response is not accepted, and the session is not established.

If the function returns SEC_I_CONTINUE_NEEDED, SEC_I_COMPLETE_NEEDED, or SEC_I_COMPLETE_AND_CONTINUE, steps 2 and 3 are repeated.

Security-context initialization may require more than one call to this function, depending on the underlying authentication mechanism as well as the choices specified in the fContextReq parameter.

The fContextReq and pfContextAttributes parameters are bitmasks that represent various context attributes. For a description of the various attributes, see Context Requirements. While the pfContextAttributes parameter is valid on any successful return, you should examine the flags that pertain to security aspects of the context only on the final successful return. Intermediate returns can set, for example, the ISC_RET_ALLOCATED_MEMORY flag.

If the ISC_REQ_USE_SUPPLIED_CREDS flag is set, the security package must look for a SECBUFFER_PKG_PARAMS buffer type in the pInput input buffer. While this is not a generic solution, it allows a strong pairing of security package and application when appropriate.

If ISC_REQ_ALLOCATE_MEMORY was specified, the caller must free the memory by calling the FreeContextBuffer function.

For example, the input token could be the challenge from a LAN Manager. In this case, the output token would be the NTLM-encrypted response to the challenge.

The action the client takes depends on the return code from this function. If the return code is SEC_E_OK, there will be no second InitializeSecurityContext (CredSSP) call, and no response from the server is expected. If the return code is SEC_I_CONTINUE_NEEDED, the client expects a token in response from the server and passes it in a second call to InitializeSecurityContext (CredSSP). The SEC_I_COMPLETE_NEEDED return code indicates that the client must finish building the message and call the CompleteAuthToken function. The SEC_I_COMPLETE_AND_CONTINUE code incorporates both of these actions.

If InitializeSecurityContext (CredSSP) returns success on the first (or only) call, the caller must eventually call the DeleteSecurityContext function on the returned handle, even if the call fails on a later leg of the authentication exchange.

The client may call InitializeSecurityContext (CredSSP) again after it has completed successfully. This indicates to the security package that a reauthentication is wanted.

Kernel-mode callers have the following differences: the target name is a Unicode string that must be allocated in virtual memory by using VirtualAlloc; it must not be allocated from the pool. Buffers passed and supplied in pInput and pOutput must be in virtual memory, not in the pool.

If the function returns SEC_I_INCOMPLETE_CREDENTIALS, check that the r credentials passed to the AcquireCredentialsHandle (CredSSP) function specified a valid and trusted certificate The certificate must be a client authentication certificate issued by a certification authority trusted by the server. To obtain a list of the CAs trusted by the server, call the QueryContextAttributes (CredSSP) function with the SECPKG_ATTR_ISSUER_LIST_EX attribute.

After receiving an authentication certificate from a certification authority that the server trusts, the client application creates a new credential. It does so by calling the AcquireCredentialsHandle (CredSSP) function and then calling InitializeSecurityContext (CredSSP) again, specifying the new credential in the phCredential parameter.

Requirements

See also

SSPI Functions

AcceptSecurityContext (CredSSP)

AcquireCredentialsHandle (CredSSP)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer

SecBuffer

SecBufferDesc