InitializeSecurityContext

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. 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.

At a Glance

Syntax

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

Parameters

phCredential

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

phContext

Pointer to the handle of 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

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. This parameter can include any of the following values:

Reserved1

Reserved; set to 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; set to zero.

phNewContext

Pointer to the handle of 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 more information about context requirements, see Cryptography. This value can include any of the following flags:

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

Upon success, one of the values described in the following table is returned.

Upon failure, one of the error values described in the following table is returned.

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 more information about context requirements, see Cryptography. 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