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 the proprietary world. You can run and use a free OS and honor our noble idea, but you can't hide! Once you're behind the cold steel bars of a corporate proxy server requiring NTLM authentication, you're lost.
Here comes Cntlm. It takes the address of your proxy (or proxies) and opens a listening socket, forwarding each request to the parent (moving in a circular list if one stops working). Along the way, each connection to the parent is created anew and authenticated or, if available, previously cached connection is reused to achieve higher efficiency and faster responses. When set up, Cntlm should be used as a proxy in your applications instead of the primary (parent) proxy to lift off the authentication requirements from them. This is useful on Windows, but essential for other OS's like Linux, BSD or Mac. Cntlm also itegrates transparent TCP/IP port forwarding (tunneling) through the proxy. Each tunnel opens a new listening socket on the defined local port and forwards all connections to the given host:port behind the parent proxy. Alternatively, you can use it as a SOCKS5 proxy, which basically allows unlimited number of tunnels on one port.
Cntlm works similarly to NTLMAPS, but it's lightning fast, has bucket load of new features (like proxy chaining or penetration) and none of its shortcomings and inefficiencies. It adds support for real keep-alive (on both sides) and it caches all authenticated connections for reuse in subsequent requests. It can be restarted without TIME_WAIT delay, uses just a fraction of memory compared to NTLMAPS and by orders of magnitude less CPU. Each thread is completely independent and one cannot block another. Cntlm has many security features like NTLMv2 support and password protection - it is possible to substitute password hashes (which can be obtained using -H) for the actual password or to enter the password just interactively. If plaintext password is used, it is automatically hashed during the startup and all its traces are removed from the process memory.
In addition to minimal usage of resources, Cntlm achieves higher throughput on a given link. By caching authenticated connections, it acts as an HTTP accelerator; 5-way NTLM handshake for each connection is transparently eliminated, providing direct access most of the time. Others (e.g. NTLMAPS) don't authenticate in parallel with the request - instead, it first connects, sends a probe and disconnects. No sooner than that it connects again and initiates NTLM handshake. Cntlm also doesn't read the whole request including HTTP body into memory, in fact, no traffic is generated except for the exchange of headers until the client <-> server connection is fully negotiated. Only then are the request and response bodies forwarded, directly between client and server sockets. This way, Cntlm significantly cuts down on the overhead of similar proxies. Along with the fact that it is written in optimized C, it achieves up to fifteen times faster responses. The slower the line, the more impact Cntlm has on download speeds.
Cntlm has been tested against various ISA servers, WinGate, NetCache, Squid and Tinyproxy.
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.
[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] New 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.
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 ------------------------------------------------
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. ;)
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.
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).
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.
On the first picture, you can see how Cntlm compares to NTLMAPS in speed. It is a screenshot of a terminal window. First, I setup the environment to use NTLMAPS as the default proxy and then measure the time it takes wget to finish a request. Notice that with the first contestant, it takes roughly the same amount of time. Then I move to Cntlm as the default proxy with the same request. It isn't just 5 times faster, see the second request - it's 15 times faster. That's connection reuse in action. :)
The second picture shows CPU and RAM consumption. The numbers were acquired during a test, when 50 parallel connection hammered both proxies. I was running top, resp. ps to capture the peak values. Averages are somewhat lower, but for the sake of comparison, this serves the purpose better.
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.
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 packages [FTP/HTTP]: ftp://awk.cz/cntlm/ | http://ftp.awk.cz/cntlm/
Sources for Debian packages [FTP/HTTP] ftp://awk.cz/cntlm/debian/ | http://ftp.awk.cz/cntlm/debian
Official Windows installer [FTP/HTTP]: ftp://awk.cz/cntlm/win32/ | http://ftp.awk.cz/cntlm/win32
Subversion access: Cntlm source code HOWTO
The site is in perpetual development, for the rest go to the default project page.