Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function initiates the outbound security context from a credential handle. The function establishes a security context between the client application and a remote peer. The function retrieves a token that the client must pass to the remote peer, which in turn submits it to the local security implementation through the AcceptSecurityContextcall. The token generated should be considered opaque by all callers.

Syntax 

SECURITY_STATUS SEC_ENTRY InitializeSecurityContext( 
  PCredHandle
 phCredential,
  PCtxtHandle
 phContext, 
  SEC_WCHAR SEC_FAR* 
pszTargetName, 
  ULONG
 fContextReq,
  ULONG
 Reserved1, 
  ULONG
 TargetDataRep, 
  PSecBufferDesc
 pInput, 
  ULONG
 Reserved2, 
  PCtxtHandle
 phNewContext, 
  PSecBufferDesc
 pOutput,
  ULONG SEC_FAR*
 pfContextAttr, 
  PTimeStamp
 ptsExpiry 
);

Parameters

phCredential

[in] Pointer to a CredHandlestructure identifying the handle to the credentials. The client retrieves this handle by calling the AcquireCredentialsHandlefunction. For information on CredHandle, see SSPI Handles.

phContext

[in, out] Pointer to a CtxtHandlestructure identifying the context. For information on CtxtHandle, see SSPI Handles. On the first call to InitializeSecurityContext, this pointer is NULL. On the second call, this parameter is the handle to the partially formed context retrieved in the phNewContextparameter by the first call.

pszTargetName

[in] Pointer to a null-terminated string that indicates the target of the context. The name is security-package specific.

fContextReq

[in] Set of bit flags that indicate the requirements of the context. Not all packages can support all requirements. For more information about context requirements, see Cryptography. The following list shows the values that this parameter can include:

  • ISC_REQ_ALLOCATE_MEMORY

  • ISC_REQ_CALL_LEVEL

  • ISC_REQ_CONFIDENTIALITY

  • ISC_REQ_CONNECTION

  • ISC_REQ_DATAGRAM

  • ISC_REQ_DELEGATE

  • ISC_REQ_EXTENDED_ERROR

  • ISC_REQ_INTEGRITY

  • ISC_REQ_MUTUAL_AUTH

  • ISC_REQ_PROMPT_FOR_CREDS

  • ISC_REQ_REPLAY_DETECT

  • ISC_REQ_SEQUENCE_DETECT

  • ISC_REQ_STREAM

  • ISC_REQ_USE_DCE_STYLE

  • ISC_REQ_USE_SESSION_KEY

  • ISC_REQ_USE_SUPPLIED_CREDS

Reserved1

Reserved; set to zero.

TargetDataRep

[in] The data representation (byte ordering and so on) on the target. The constant SECURITY_NATIVE_DREP can be supplied by the transport application, indicating that the native format is in use.

pInput

[in, out] Pointer to SecBufferDescstructures containing information about the buffers supplied as input to the package. The transport application should provide as much input as possible, although some packages might not be interested in the non-security portions. This parameter is optional, particularly on the first call to InitializeSecurityContext.

Reserved2

Reserved; set to zero.

phNewContext

[in, out] Pointer to a CtxtHandlestructure. For information on CtxtHandle, see SSPI Handles. On the first call to InitializeSecurityContext, this pointer receives the new context handle. On the second call, this can be the same as the handle specified in the phContextparameter.

pOutput

[out] Pointer to SecBufferDescstructures containing information about the buffers that receive the output data. If a buffer was typed as 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.

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. The following list shows the flags that this value can include:

  • ISC_RET_ALLOCATED_MEMORY

  • ISC_RET_CALL_LEVEL

  • ISC_RET_CONFIDENTIALITY

  • ISC_RET_CONNECTION

  • ISC_RET_DATAGRAM

  • ISC_RET_DELEGATE

  • ISC_RET_EXTENDED_ERROR

  • ISC_RET_INTEGRITY

  • ISC_RET_INTERMEDIATE_RETURN

  • ISC_RET_MUTUAL_AUTH

  • ISC_RET_REPLAY_DETECT

  • ISC_RET_SEQUENCE_DETECT

  • ISC_RET_STREAM

  • ISC_RET_USED_COLLECTED_CREDS

  • ISC_RET_USED_DCE_STYLE

  • ISC_RET_USE_SESSION_KEY

  • ISC_RET_USED_SUPPLIED_CREDS

ptsExpiry

[out] Pointer to a variable that receives 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 initialized. There is no need for another InitializeSecurityContextcall and no response from the server is expected.

SEC_I_CONTINUE_NEEDED

The client must send the output token to the server and then pass the token retrieved by the server in a second call to InitializeSecurityContext.

SEC_I_COMPLETE_NEEDED

The client must finish building the message and then call the CompleteAuthTokenfunction.

SEC_I_COMPLETE_AND_CONTINUE

The client must call CompleteAuthToken, then pass the output to the server, and finally make a second call to InitializeSecurityContext.

The following table shows the possible error values.

Value Description

SEC_E_INVALID_HANDLE

The handle passed to the function is invalid.

SEC_E_TARGET_UNKNOWN

The target was not recognized.

SEC_E_LOGON_DENIED

The logon failed.

SEC_E_INTERNAL_ERROR

The Local Security Authority cannot be contacted.

SEC_E_NO_CREDENTIALS

No credentials are available in the security package.

SEC_E_NO_AUTHENTICATING_AUTHORITY

No authority could be contacted for authentication.

Remarks

A client uses this function to initialize an outbound context.

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

  1. The client calls this 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 retrieves the pointer in the TOKEN element.

  3. The client sends the token retrieved in the pOutputbuffer to the target server. The server then passes the token as an input argument in a call to the AcceptSecurityContextfunction.

  4. AcceptSecurityContextmight retrieve a token, which the server sends to the client for a second call to InitializeSecurityContext.

For a three-leg (mutual authentication) security package, the calling sequence is as follows:

  1. The client calls the function as described earlier, but the function returns the SEC_I_CONTINUE_NEEDED success code.

  2. The client then sends the output token to the server and waits for the server's reply.

  3. Upon receipt of the server's response, the client calls InitializeSecurityContextagain, with phContextset to the handle retrieved in the first call. The token received from the server is supplied in the pInputparameter. If the server has successfully responded, the security package will respond with success. Otherwise, it will invalidate the context.

To initialize a security context, more than one call to InitializeSecurityContextmight be required. This depends on the underlying authentication mechanism, as well as the choices specified in the fContextReqparameter .

The fContextReq and pfContextAttributesparametersare bit masks representing various context attributes. For more information about context requirements, see Context Requirements.

The pfContextAttributesparameter is valid on any successful return, but only on the final successful return should the caller examine the flags pertaining to security aspects of the context. Intermediate returns can set a flag, for example, the ISC_RET_ALLOCATED_MEMORY flag.

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

When the ISC_REQ_PROMPT_FOR_CREDS flag is set, the security package attempts to prompt the user for the credentials to use for the connection. If the caller is not an interactive user (for example, a non-interactive service), this flag is ignored. During the prompt, the package might inquire if the supplied credentials should be retained. If so, the package can store them away for future use, relieving the user of having to enter credentials later. This behavior, if supported, should be configurable for environments in which the credentials cannot or should not be stored away.

If the ISC_REQ_USE_SUPPLIED_CREDS flag is set, the security package should look for a SECBUFFER_PKG_PARAMS buffer type in the pInputinput buffer. This is not a generic solution, but it allows for a strong pairing of security package and application when appropriate.

You can specify either ISC_REQ_CONNECTION or ISC_REQ_DATAGRAM flags for the fContextReqparameter, but not both. Note that datagram support is available only if NTLM v2 can be negotiated.

If the ISC_REQ_ALLOCATE_MEMORY flag was specified, the caller must free the memory by calling the FreeContextBufferfunction. For example, the input token might be the challenge from a LAN Manager or Windows NT file server. In this case, the output token will 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 InitializeSecurityContextcall 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. The SEC_I_COMPLETE_NEEDED return code indicates that the client must finish building the message and call the CompleteAuthTokenfunction. The SEC_I_COMPLETE_AND_CONTINUE code incorporates both of these actions.

If the server rejects the connection, the client must call the DeleteSecurityContextfunction at that time to free any resources.

Requirements

Header security.h, sspi.h
Library secur32.lib
Windows Embedded CE Windows CE 2.10 and later
Windows Mobile Smartphone 2002 and later

See Also