InitializeSecurityContext

The InitializeSecurityContext function initiates the outbound security context from a credential handle. The function establishes a security context between the client application and a remote peer. InitializeSecurityContext returns 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.

SECURITY_STATUS InitializeSecurityContext(
  PCredHandle phCredential,  // handle to the credentials
  PCtxtHandle phContext, // handle of partially formed context
  SEC_CHAR * pszTargetName,  // name of the target of the context
  ULONG fContextReq,     // required context attributes
  ULONG Reserved1,       // reserved; must be zero
  ULONG TargetDataRep,   // data representation on the target
  PSecBufferDesc pInput, // pointer to the input buffers
  ULONG Reserved2,       // reserved; must be zero
  PCtxtHandle phNewContext,  // receives the new context handle
  PSecBufferDesc pOutput,  // pointer to the output buffers
  PULONG pfContextAttr,  // receives the context attributes
  PTimeStamp ptsExpiry   // receives the life span of the security 
                         // context
);
 

Parameters

phCredential

Handle to the credentials to use to create the context. The client retrieves this handle by calling the AcquireCredentialsHandle function.

phContext

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

pszTargetName

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

fContextReq

A set of bit flags that indicate the requirements of the context. Not all packages can support all requirements. For a description of the various attributes, see Context Requirements. This parameter can include any of the following values:

ISC_REQ_DELEGATE
ISC_REQ_MUTUAL_AUTH
ISC_REQ_REPLAY_DETECT
ISC_REQ_SEQUENCE_DETECT
ISC_REQ_CONFIDENTIALITY
ISC_REQ_USE_SESSION_KEY
ISC_REQ_PROMPT_FOR_CREDS
ISC_REQ_USE_SUPPLIED_CREDS
ISC_REQ_ALLOCATE_MEMORY
ISC_REQ_USE_DCE_STYLE
ISC_REQ_DATAGRAM
ISC_REQ_CONNECTION
ISC_REQ_CALL_LEVEL
ISC_REQ_EXTENDED_ERROR
ISC_REQ_STREAM
ISC_REQ_INTEGRITY

Reserved1

Reserved value; must be zero.

TargetDataRep

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

pInput

Pointer to a SecBufferDesc structure that contains pointers to the buffers supplied as input to the package. The transport application should provide as much input as possible, although some packages may not be interested in the nonsecurity portions. This parameter is optional, particularly on the first call to InitializeSecurityContext.

Reserved2

Reserved value; must be zero.

phNewContext

Pointer to a CtxtHandle structure. 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

Pointer to a SecBufferDesc structure that contains pointers to 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.

pfContextAttributes

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. This value can include any of the following flags.

ISC_RET_DELEGATE
ISC_RET_MUTUAL_AUTH
ISC_RET_REPLAY_DETECT
ISC_RET_SEQUENCE_DETECT
ISC_RET_CONFIDENTIALITY
ISC_RET_USE_SESSION_KEY
ISC_RET_USED_COLLECTED_CREDS
ISC_RET_USED_SUPPLIED_CREDS
ISC_RET_ALLOCATED_MEMORY
ISC_RET_USED_DCE_STYLE
ISC_RET_DATAGRAM
ISC_RET_CONNECTION
ISC_RET_INTERMEDIATE_RETURN
ISC_RET_CALL_LEVEL
ISC_RET_EXTENDED_ERROR
ISC_RET_STREAM
ISC_RET_INTEGRITY

ptsExpiry

Pointer to a TimeStamp variable that receives the expiration time of the context. The security provider should always return this value in local time.

Return Values

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

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

Remarks

The InitializeSecurityContext function is used by a client to initialize an outbound context.

For a two-leg security package, 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 function.
4. AcceptSecurityContext may return 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 package will return 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 that was returned from the first call. The token received from the server is supplied in the pInput parameter. If the server has successfully responded, then the security package will respond with success, otherwise, it will invalidate the context.

To initialize a security context, more than one call to this function may be required, depending on the underlying authentication mechanism as well as the "choices" specified in the fContextReq parameter.

The fContextReq and pfContextAttributes are bit masks representing various context attributes. For a description of the various attributes, see Context Requirements. The pfContextAttributes parameter is valid on any successful return, but only on the final successful return should you examine the flags pertaining to security aspects of the context. Intermediate returns can set, for example, the ISC_RET_ALLOCATED_MEMORY flag.

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.

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 noninteractive service), this flag is ignored. During the prompt, the package may 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.

If the 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 or Windows NT file server. 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 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, of course, incorporates both of these actions.

If the connection is rejected by the server, the client must call the DeleteSecurityContext function at that time to free any resources.

See Also

AcceptSecurityContext, CompleteAuthToken, DeleteSecurityContext, FreeContextBuffer