| Platform SDK: Logon Authentication |
The InitializeSecurityContext function initiates the outbound security context from a credential handle. The function is used to build 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 the peer in turn submits 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 );
| Security package | String contents |
|---|---|
| Kerberos or Negotiate | Server principal name (SPN) or the security context of the destination server. |
| NTLM | Not needed by the package; must be set to NULL. |
| SSL | SPN for the first call to InitializeSecurityContext. |
Note Particular context attributes can change during a negotiation dialog with a remote peer.
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. If the function returns an output token, that is, if the SECBUFFER_TOKEN in pOutput is of non-zero length, that token must be sent to the server. |
| SEC_I_CONTINUE_NEEDED | The client must send the output token to the server, and wait for a return token. The returned token is then passed in another call to InitializeSecurityContext. |
| SEC_I_COMPLETE_NEEDED | The client must finish building the message, then call the CompleteAuthToken function. |
| SEC_I_COMPLETE_ AND_CONTINUE |
The client must call CompleteAuthToken, then pass the output to the server. The client then waits for a returned token and passes it in another 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 domain name of the authenticating party could be wrong, the domain could be unreachable, or there might have been a trust relationship failure. |
| SEC_E_INSUFFICIENT_MEMORY | One or more of the SecBufferDesc structures passed as an OUT parameter has a buffer that is too small. |
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 multi-leg security packages such as mutual authentication, 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 non-interactive service), this flag is ignored. During the prompt, the package might inquire if the supplied credentials must be retained. If retention of the supplied credentials is indicated, 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 must 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 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/Windows 2000 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 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.
The client may call InitializeSecurityContext again after it has completed successfully. This indicates to the security package that a re-authentication is desired.
Kernel mode callers have the following differences: the target name is a Unicode string and must be allocated in virtual memory using VirtualAlloc, not from the pool. Buffers passed and supplied in pInput and pOutput must be in virtual memory, not in the pool.
The prototype for this function can be found in Sspi.h.
Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98: Requires Windows 95 or later.
Header: Declared in Sspi.h; include Security.h.
Library: Use Secur32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.
AcceptSecurityContext, AcquireCredentialsHandle, CompleteAuthToken, DeleteSecurityContext, FreeContextBuffer, SecBuffer, SecBufferDesc