NTLM Security Support Provider

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

NTLM SSP is based on Microsoft Windows NT LAN Manager challenge/response and NTLM version 2 authentication protocols used on networks running versions of Windows NT operating system or Windows Mobile servers. The protocol is implemented through SSPI, which provides the functions for enumerating the providers available on a system, selecting one of the functions, and using it to obtain an authenticated connection. The registry controls the authentication protocol to use. For more information, see Authentication Services Registry Settings.

The following steps show a brief outline of the process for client application authentication:

1. Call the AcquireCredentialsHandle function using the SEC_WINNT_AUTH_IDENTITY structure to specify the credentials. If the user saved a default NT domain name and password on the CE device, the application can use the cached credentials by passing NULL instead of the SEC_WINNT_AUTH_IDENTITY structure. If the NTLM SSP cannot find the cached credentials, the function returns SEC_E_NO_CREDENTIALS.

   Note

   Because the credentials handle does not expire, the client can ignore the expiration time for this security package.

   The following code example shows how to make a connection.

   SEC_WINNT_AUTH_IDENTITY AdditionalCredentials;
   SECURITY_STATUS status;
   CredHandle hCredential;
   TimeStamp tsExpiry;
   BOOL bSupplyCredentials;
   
   // Zero memory
   memset(&AdditionalCredentials,0,sizeof(SEC_WINNT_AUTH_IDENTITY));
   
   // If there are additional credentials stored in lpszUserName, 
   // lpszDomainName, and lpszPassword, fill them in here.
   AdditionalCredentials.Flags = SEC_WINNT_AUTH_IDENTITY_UNICODE;
   
   if (lpszUserName != NULL) 
   {
     AdditionalCredentials.User = lpszUserName;
     AdditionalCredentials.UserLength = wcslen (lpszUserName);
   }
   
   if (lpszDomainName != NULL) 
   {
     AdditionalCredentials.Domain = lpszDomainName;
     AdditionalCredentials.DomainLength = wcslen (lpszDomainName);
   }
   
   if (lpszPassword != NULL) 
   {
     AdditionalCredentials.Password = lpszPassword;
     AdditionalCredentials.PasswordLength = wcslen (lpszPassword);
   }
   
   status = AcquireCredentialsHandle (
                 NULL,                   // No principal name
                 TEXT("NTLM"),           // Package name
                 SECPKG_CRED_OUTBOUND,   // Credential use flag
                 NULL,                   // No logon identifier
                 bSupplyCredentials ?  &AdditionalCredentials : NULL,
                                         // Package-specific data     
                 NULL,                   // No GetKey function
                 NULL,                   // No GetKey function argument
                 &hCredential,           // Receives the new credential
                 &tsExpiry);             // Receives the expiration 
                                         // time of the credential
   

2. Call the InitializeSecurityContext function to setup the security context. Note that NTLM only supports the connection semantics.
   The function returns SEC_I_CONTINUE_NEEDED on success, or an error code on failure. If the function is successful, the application passes the token buffer to the server. The token buffer is stored in the pvBuffer member of the SecBuffer structure.
   The following security context flags are used in NTLM.

   • ALLOCATE_MEMORY
   • CONFIDENTIALITY
   • CONNECTION
   • EXTENDED ERROR
   • INTEGRITY
   • REPLAY_DETECT
   • SEQUENCE_DETECT

   For more information about using the context flags, see Context Requirements.

3. Call the InitializeSecurityContext function again.
   If the function returns SEC_E_OK, the application transmits the output security buffer and the buffer length to the server, as it did after the first call. If the function fails, an error value returns.

See Also

Reference

Authentication Services Reference

Concepts

Security Support Provider Interface Architecture
Security Packages
Authentication Services Security
Authentication Services Registry Settings

Other Resources

Authentication Services