Cntlm Authentication Proxy


About Cntlm proxy

Cntlm (user-friendly wiki / technical manual) is an NTLM / NTLM Session Response / NTLMv2 authenticating HTTP proxy intended to help you break free from the chains of Microsoft proprietary world. You can use a free OS and honor our noble idea, but you can't hide. Once you're behind those cold steel bars of a corporate proxy server requiring NTLM authentication, you're done with. The same even applies to 3rd party Windows applications, which don't support NTLM natively.

Here comes Cntlm. It stands between your applications and the corporate proxy, adding NTLM authentication on-the-fly. You can specify several "parent" proxies and Cntlm will try one after another until one works. All auth'd connections are cached and reused to achieve high efficiency. Just point your apps proxy settings at Cntlm, fill in cntlm.conf (cntlm.ini) and you're ready to do. This is useful on Windows, but essential for non-Microsoft OS's.

Cntlm integrates TCP/IP port forwarding (HTTP tunneling), SOCKS5 proxy mode, standalone proxy allowing you to browse intranet as well as Internet and to access corporate web servers with NTLM protection. There are many advanced features like NTLMv2 support, password protection, password hashing, completely mutliplatform code (running on just about every architecture and OS out there) and so much more. Cntlm eats up so little resources it can be used on embedded platforms as well - it's written in plain C without any external dependencies.

Cntlm has been tested against various ISA servers, WinGate, NetCache, Squid and Tinyproxy with and without NTLM auth.

Memory management audits and profiling are inherent part of the development process. Each change in the code is audited using Valgrind, which acts as a virtual CPU and checks behaviour of each instruction of the application being profiled. Using this marvelous tool, you can uncloak any imbalance in malloc/free calls (double free's or leaks), operations with uninitialized memory, access outside of properly allocated memory and oh so much more.

News

HELP US MAKE CNTLM GO ON (AND GET BETTER):

[2012-04-29] UNIX man(1) page is updated incl. the generated PDF manual (also directly downloadable). WebSVN access and RSS feed are now enabled and working again, same setup as before (see our Cntlm source code HOWTO page for details).

[2012-03-07] Version 0.92.3 available (the whole branch retroactively un-stabled, because of crashes on Windows; first stable version after 0.35.1 will be 0.93). Fixes Windows 0.92.2 installer, which was missing new DLL's from Cygwin. Previous 0.92 enhancements include: introduced a plain ZIP release package for manual installation without Admin privileges, fixed race condition in 0.92 which caused crashes on Windows, interactive password input doesn't strip trailing whitespaces anymore, added proper handling of the "Program Files (x86)" hack in Windows, proxy hostname is resolved at run-time not during startup (as requested), ISA A/V scanner (GFI WebMonitor) handler is now bypassed when download size is unknown, fixed a bug in downloading files larger than 2GB, fixed the GIT + HTTPS issue.

[2012-03-02] Version 0.92.2 available (retroactively un-stabled). Some fixes.

[2011-11-28] Version 0.92 available (retroactively un-stabled). Several bugfixes and many chages and features since the last stable version.

[2010-04-20] Testing version 0.91rc5 available. There are still some planned features missing, but this version is mainly a fixpack release. Whoever is using these RC's, please do upgrade for your own sake. Cheers.

[2010-03-30] Testing version 0.91rc2 available. Features remaining to be implemented: optional limit of max auth tries (account protection); in case of failed auth return proxy error, but translate NTLM to basic; run-time switching between normal mode (work) and full direct mode (home). Apart from fixes, this testing version includes:

[2010-03-20] A new testing version has been released in DEB, RPM and Windows packages. I'm sure it's ready for prime time, but I'll wait a bit for it to get tested before releasing official stable packages. Apart from a huge rewrite, Cntlm has some news for you:

[2010-02-26] SVN repository has been updated with a collection of fixes and other changes request by people during the last year. I'm sorry for being a bit slow on the uptake, but I'm very busy. Everything I knew about has been implemented. I won't make a new release today, though. I hope you people test the new code in the meantime and let me know if you find any bugs! :)

[2007-11-02] New version 0.35 is here. The code was refactored to facilitate future support of multiple profiles and other planned extensions. I have added one symbol definition in the Makefile to make newer socket API constants visible on FreeBSD, which is now supported. Cntlm has finally made it into Debian, which is great! This means other deb-based distributions can use ready-made official packages. On Ubuntu, we're confirmed running since 0.35 (older versions have dash(1) incompatible init script). There was a bug preventing Cntlm from working on some proxies, when they didn't require any authentication; this was reported for the Wingate proxy, which is now confirmed working. There was a sinister typo in the tunneling routine and it made tunnels kinda unstable under certain circumstances (e.g. SSH over HTTPS). It's fixed now, so you should update. The new big shiny feature is:

[2007-08-26] New version 0.34(.1) is finally here. Since I was busy at work, I took my time to spit it out, but I've implemented most of the stuff I could think of. :) There are also three useful bug fixes and many new features. The major ones being:

[2007-07-17] New version 0.33 switches automatically and temporarily to NTLM-to-basic if config file credentials fail. The most changes happened around packaging, though. The debian directory has been moved outside of the distribution package. This was suggested by David Watson, a Debian maintainer, who was so kind as to offer sponsorship for Cntlm. In other words, Cntlm is going to be included as part of the Debian GNU/Linux, my favourite distro since 1998. :) This however changes what you have to do to build debs from sources. Follow the new "Debian sources" link in the "Downloads" section. There's a small HOWTO as well. Cntlm has also been ported to the Windows platform, where it runs as a service. See Win32 downloads below and the included README.

[2007-07-12] New version 0.32 adds support for multiple users per one Cntlm instance, which has been requested on the feature suggestion tracker (and implemented the following day:). This feature is called NTLM-to-basic and allows passing credentials using the standard "basic" proxy authentication scheme (e.g. via browser's popup dialog or proxy settings in other applications). This implementation detects failed authentication attempts and makes it possible for you to keep trying (until you get it right or give up) by informing the client (browser) about the actual result. Other proxies don't do any verification, always accept your first try and therefore the client remembers it; if you made a mistake, you'd get "access denied" page for any URL and would have to restart your browser to try again.

[2007-07-09] New version 0.31.1 adds full chunked encoding support, including extensions and trailers.

[2007-07-02] The first version 0.31 fixes ftp:// access, which might not work on some exotic ISAs and adds support for the chunked transfer-encoding. Chunked support is a major benefit over other NTLM proxies. If you use HTTP/1.1 clients (all modern browsers in the default configuration) and your proxy doesn't automatically decode it behind the scenes (e.g. new ISA server I have to use ATM), you are unlikey to be able to browse most of the dynamic sites (timeouts, partially rendered pages, etc). There are some other compatibility fixes for new misbehaving ISA servers.

WARNING: please understand that any unannounced versions on the FTP are for internal/development purposes only, usually beta testing. Until properly advertised on the official homepage, http://cntlm.sf.net, and uploaded to sourceforge.net archives, it is to be considered highly unstable and ought to be replaced by the final build when available.

Configuration hints

After installation, you have to locate the configuration file. The default for Linux packages is /etc/cntlm.conf, for locally compiled source distribution ("./configure; make; make install") it's /usr/local/etc/cntlm.conf and for Windows installer it's %PROGRAMFILES%\Cntlm\cntlm.ini (usually X:\Program Files\Cntlm\cntlm.ini, where X is your system drive).

When you have found it, fire up your favourite editor (not a word processor) and open the file. First a few rules, though - lines beginning with a hash, #, are comments: completely ignored. There is no required formatting and option names are case insensitive. Option values are parsed literally: a quote means a quote and is taken as part of the string, so do not quote, escape, etc. Anyway, you need to set these core options:

Next, we need to find out which NTLM dialect your proxy understands. It's a jungle out there and it can be quite challenging (i.e. boooring) to find a working NTLM setup - thank Bill. Good thing Cntlm has this magic switch to do it for you - thank me. :) Save the configuration and run the following command; when asked, enter your proxy access password:

$ cntlm -I -M http://test.com
Config profile  1/11... OK (HTTP code: 200)
Config profile  2/11... OK (HTTP code: 200)
Config profile  3/11... OK (HTTP code: 200)
Config profile  4/11... OK (HTTP code: 200)
Config profile  5/11... OK (HTTP code: 200)
Config profile  6/11... Credentials rejected
Config profile  7/11... Credentials rejected
Config profile  8/11... OK (HTTP code: 200)
Config profile  9/11... OK (HTTP code: 200)
Config profile 10/11... OK (HTTP code: 200)
Config profile 11/11... OK (HTTP code: 200)
----------------------------[ Profile  0 ]------
Auth            NTLMv2
PassNTLMv2      4AC6525378DF8C69CF6B6234532943AC
------------------------------------------------
You see, NTLMv2 - I told you to use it, now it's official. :) BTW, here you can see all tests running - it's just for demonstration purposes. Normal version finishes when it finds the first (i.e. most secure) working setup.

When you get your options (might be more than just Auth and Pass* here), remove all previous password settings and paste the profile into the configuration file and save it. (Re)start Cntlm and it should work. To use it in your applications, replace the old proxy settings with "localhost", port same as you chose for Listen.

This was just a simple 101 lesson to help you kick-start the proxy. You should still RTFM. ;)

Troubleshooting

If you have problems, you can see what's going on in the system logger (Linux: daemon.log, messages or syslog in /var/log/; on Windows using Control Panels - Administration - Logging) or run Cntlm from the command line with -v -f (debug mode). If that doesn't give you a hint, look at our wiki for troubleshooting tips and also check out the Help Forum and the Bug Tracker to see if somebody else didn't have a similar problem. When you are out of your wits and none of this helped, read the last chapter of our wiki and see how to request support.

System requirements

Cntlm has no dependencies, but you'll obviously need compiler runtime libraries and, depending on your distribution, package build tools. Cntlm uses ISO C99 and POSIX.1-2001 interface (i.e. SUSv3 / UNIX 03), but will compile with older C/POSIX standards as well (incl. other threading libraries). Compilation should succeed on any UNIX-like system (both little and big endian; GCC and IBM XL C/C++ compilers being officially supported) having sane libc and POSIX threads. You don't need any bloated interpreter like Python or Perl and fight modules or libraries - one binary does it all. Compiles and runs on Linux, FreeBSD, MacOS X, AIX, Solaris and Windows (other platforms probably too, just not confirmed yet).

Roadmap

At the beginning, Cntlm aimed for HTTP/1.0 and 1.1 compliance and addressed the problems users had with other proxies (poor response time; CPU/RAM hogging; breaking HTTP, Subversion, instant messaging, tunneling; failed requests; timeouts; you know what I mean if you had to use them). Now that this stuff has been taken care of, I'll move on to implementing extra features like multiple profiles and multiplatform GUI for easy switching of preconfigured profiles depending on your location. Feel free to suggest new features yourself.

Feedback and suggestions

I'd like to hear any feature suggestion, bug report or support request you might have on your mind. If you want to share some other piece of advice, praise :), or just chat with other Cntlm users, check out the discussion forum. Don't be lazy and find yourself the time to let us know. :)

When reporting a bug or other problems, follow the instructions in our wiki.

Downloads

If you prefer binary/source packages, visit our SF.net download page or my FTP, where you can find all final releases. Alternatively, you can stay up to date with the latest research :) and get the development version from SVN. Also note that some distributions have already included Cntlm in their repositories.

Official packages [sf.net]: SF.net downloads for Cntlm
Official / development packages [FTP/HTTP]: http://ftp.awk.cz/cntlm/
Subversion access: Cntlm source code HOWTO

Get more info on our SF.net project page.