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
);
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
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
If the function succeeds, the return value is one of the following success codes.
Value | Meaning |
---|---|
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 returned 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. |
If the function fails, the return value is one of the following error codes.
Value | Meaning |
---|---|
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. |
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:
For a three-leg (mutual authentication) security package, the calling sequence is as follows:
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.
AcceptSecurityContext, CompleteAuthToken, DeleteSecurityContext, FreeContextBuffer