NTLM Authentication in Java

by Luigi Dragone [e-Mail] [Home Page]

Overview

This is "100% Pure Java" implementation of the MS NTLM authentication protocol.

NTLM is a proprietary protocol employed by many Microsoft products to perform challange response authentication and it is the default authetication scheme used by Microsoft firewall and proxy server products.

This software has been developed to issue the problem of work with Java technologies in strongly Microsoft oriented enviroments. Since it not relies over any official protocol specification there are any warranties that it works correctly in every situation. It has been on same Windows installation, where it worked fine.

This software is released under GNU General Public License. It can be freely used, modified and distributed in conformity with the GNU General Public License. The License Agreement is available here. For any information about the GNU GPL and its implications please see here.

The content of this site is provided "AS IS" without warranties of any kind either express or implied. Please send me any comment or suggestion and report me any bug you notice.

To contact me please send an e-mail to luigi@luigidragone.com.
Click here to go to my home page (in Italian).

Change log

The NTLM Authentication Protocol

Since there is any official specification of the NTLM protocol publicly available the only products that support it are released by Microsoft itself (e.g., Internet Explorer, Windows OSs family). As consequence, in Microsoft oriented network enviroment nearly all non-MS products have a lot of troubles to perform their tasks correctly.

For example, Netscape Navigator and other common Internet browser do not support NTLM authetication scheme, thus they can not access to the Internet through a Microsoft proxy server or firewall. The only browser that can do this is, evidently, Internet Explorer.

Software development enviroments suffer from the aforementioned problem, there is not any library that implements this authentication scheme except these ones bundled in Windows OS. In the Open Source community there are many projects focused on the implementation of this protocol, but any of these has Java as target enviroment.

The lack of the availability of this authentication scheme in the Java platform could be a seriuos trouble in the development and deployment of cooperative applications based on technologies like SOAP Web Services, that rely on HTTP protocol. Take into account that spreading of CORBA technology has been definitively halted by its problems to work with firewalls and proxies.

To perform a NTLM authentication in Java there are two main alternatives:

  1. employ the class com.ms.net.wininet.WininetStreamHandlerFactory, provided by Microsoft Java VM;
  2. employ a native OpenSource implemenation of NTLM by JNI;

The first solution requires to work with Microsoft Java VM exclusively, since the class com.ms.net.wininet.WininetStreamHandlerFactory is a wrapper of some native functions in Wininet.dll, but the calling convention is not JNI compatible, but it is performed by the stub javart.dll according to the proprietary Microsoft J/Direct interface. The other is not obviously "100% Pure Java", because it requires native code.

Since NTLM is finally a weak protocol (it is more safe than basic authentication, but it is not strong as the digest autentication), there are many cracking tools and many security issues ralated to it. It has been replaced by a new version in the SP3 of NT and by the Kerberos protocol in Windows 2000, but it is the only protocol supported by Windows 95/Windows 98 clients.

Decriptions of the protocol are available here and here. Notice that they are obtained from an analysis of sniffed packets.

Release Notes

This package contains three classes:

  1. NTLM that implements all the computation required by the protocol;
  2. NTLMAuthorizationHandler that implements NTLM authentication over HTTP;
  3. NTLMTestClient that is command line tool that shows how to use this library.

It requires a JCE compatible MD4 hash algorithm implementation and DES with no-padding ECB cipher to compute the requested value. An Open Source JCE compatible library is Cryptix JCE and it is available here. Notice that the Sun JCE implementation proviedes the DES cipher but does not provide the MD4 hashing (it is a weak hashing algorithm, definitively).

The HTTP authentication component is a module for the HTTPClient library. HTTPClient is an Open Source HTTP client written by Ronald Tschalär, release under the GNU LGPL and it is available following this link. It can be configured to replace the standard Sun HTTP client completely.

To perform NTLM authentication over a protocol different from HTTP (e.g., FTP or Telnet) you need to write the required code employing functions implemented in NTLM.

Notice that NTLM is not a proxyable protocol, it can be used to authenticate a client against a proxy or a web site, but not both at the same time.

System requirements

This library requires the following components completely installed to work properly:

Download

The latest version is available here. The zipped file contains source code, compiled byte code and documentation.

Instructions

In this sections we explain how to use this library to perform an NTLM authentication over HTTP using the HTTPClient and JCE compliant library.

Set the CLASSPATH accordingly to contains:

To use these classes you need to put the file ntlm.jar in the CLASSPATH, see thier own instructions to install the other elements. To perform an authentication the following information are needed: Alternatively, the user password can be replaced with its Lan Manager and NT hashed versions. On a Windows system these can be collected in the registry (with a bit of JNI, so), otherwise can be extracted from a SAMBA password file. Notice that the host and user domain could not be the same. As first step you need to register the JCE compliant components. Each library defines its own provider, e.g., if you use Cryptix JCE you need to execute the following instruction:
      Security.addProvider(new cryptix.jce.provider.CryptixCrypto());
This task can be performed in the static initializer of the main class. Use these data as argument to class constructor to create a new authorization object:
	HTTPClient.AuthorizationHandler ntlm = new NTLMAuthorizationHandler(host,
		hostDomain, user, userDomain, password);
	HTTPClient.AuthorizationInfo.setAuthHandler(ntlm);
If the client is behind a proxy server, set accordingly the Java system properties http.proxyHost and http.proxyPort. The authorization handler must be set before opening any connection, thus it could be done in a (static or instance) initializer or in a constructor. After the setting of the authorization handler HTTP connections can be used as usual.

It is also possibile store authentication information in the following system properties:

Then use the parameter-less constructor to obtain a new authorization handler.

The HTTPClient can override the standard Sun HTTP protocol handler, in this case all existing programs that rely on this one can work with this new component without any adjustment. It is enough to set the Java system property java.protocol.handler.pkgs to the value HTTPClient.

See class documentation and links at the bottom of the page to more information.

Links

luigi@luigidragone.com.