NTLM Authentication in Java

• Overview
• Change log
• The NTLM Authentication Protocol
• Release Notes
• System requirements
• Download
• Instructions
• Links

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 challenge response authentication and it is the default authentication 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 environments. 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 refer to GNU site.

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.

Change log

• Release 1.1c 27 Oct 2002
  Problem on exception raising in method NTLMAuthorizationHandler.fixupAuthorizationInfo() was fixed.
• Release 1.1b 5 Oct 2002
  Problem on invalid invocation of method NTLM.getNonce() was fixed.
• Release 1.1a 2 Sep 2002
  Problem on computing Lan Man password was fixed.
• Release 1.1 29 Mar 2002
  Added new class NTLMTestClient
• Release 1.0a 21 Mar 2002
  Problem on NTLM.computeNTLMResponse() method was fixed.
• First release (1.0) 3 Feb 2002

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 environment 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 authentication 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 environments 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 environment.

The lack of the availability of this authentication scheme in the Java platform could be a serious 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 authentication), there are many cracking tools and many security issues related 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.

Descriptions of the protocol are available on the following sites:

• www.innovation.ch
• www.l0pht.com

Please 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 at Cryptix. Notice that the Sun JCE implementation provides 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,
released under the GNU LGPL and it is available at www.innovation.ch.
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:

• a JCE-compliant implementation that provides MD4 hashing and DES chiper (e.g.,Cryptix JCE);
• HTTPClient to perform the NTLM authentication over HTTP.

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:

• the classes of this package;
• the HTTPClient library;
• the JCE compliant library.

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:

• the host name (with its own domain);
• the user name (with its own domain);
• the user password.

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 authorisation 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 authorisation 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 authorisation handler HTTP connections can be used as usual.

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

• com.luigidragone.net.ntlm.host;
• com.luigidragone.net.ntlm.user;
• com.luigidragone.net.ntlm.hostDomain;
• com.luigidragone.net.ntlm.userDomain;
• com.luigidragone.net.ntlm.password.

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

• NTLM Authentication Scheme for HTTP
• HTTPClient
• Hypertext Transfer Protocol — HTTP/1.1
• HTTP Authentication: Basic and Digest Access Authentication
• LanMan and NT Password Encryption in Samba 2.x
• “Handbook of Applied Cryptography”
• JCE
• Cryptix