InitializeSecurityContext (Compact 2013)

  • Article

3/28/2014

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 AcceptSecurityContext call. 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 CredHandle structure identifying the handle to the credentials. The client retrieves this handle by calling the AcquireCredentialsHandle function. For information on CredHandle, see SSPI Handles.
  • phContext
    [in, out] Pointer to a CtxtHandle structure 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 phNewContext parameter 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 SecBufferDesc structures 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 CtxtHandle structure. 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 phContext parameter.
  • pOutput
    [out] Pointer to SecBufferDesc structures 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 InitializeSecurityContext call 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 CompleteAuthToken function.

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 pOutput buffer to the target server. The server then passes the token as an input argument in a call to the AcceptSecurityContext function.
  4. AcceptSecurityContext might 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 InitializeSecurityContext again, with phContext set to the handle retrieved in the first call. The token received from the server is supplied in the pInput parameter. 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 InitializeSecurityContext might be required. This depends on the underlying authentication mechanism, as well as the choices specified in the fContextReq parameter*.*

The fContextReq and pfContextAttributes parameters are bit masks representing various context attributes.

The pfContextAttributes parameter 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 pInput input 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 fContextReq parameter, 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 FreeContextBuffer function. 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 InitializeSecurityContext 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. 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 the server rejects the connection, the client must call the DeleteSecurityContext function at that time to free any resources.

Requirements

Header

security.h,
sspi.h

Library

secur32.lib

See Also

Reference

Authentication Services Functions
AcceptSecurityContext
CompleteAuthToken
DeleteSecurityContext
FreeContextBuffer