Updated NTLM guide based in input provided by Ron Jacobs <Ron.Jacobs at Reardencommerce.com>

git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@1095921 13f79535-47bb-0310-9956-ffa450edef68

src/site/apt/ntlm.apt

@@ -0,0 +1,155 @@
+~~ ====================================================================
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements.  See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership.  The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License.  You may obtain a copy of the License at
+~~
+~~   http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied.  See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+~~ ====================================================================
+~~
+~~ This software consists of voluntary contributions made by many
+~~ individuals on behalf of the Apache Software Foundation.  For more
+~~ information on the Apache Software Foundation, please see
+~~ <http://www.apache.org/>.
+
+    ----------
+    NTLM support in HttpClient
+    ----------
+    ----------
+    ----------
+
+NTLM support in HttpClient
+
+* {Background}
+
+    NTLM is a proprietary authentication scheme developed by Microsoft and optimized for
+    Windows operating system.
+
+    Until year 2008 there was no official, publicly available, complete documentation of
+    the protocol. {{{http://davenport.sourceforge.net/ntlm.html}Unofficial}} 3rd party
+    protocol descriptions existed as a result of reverse-engineering efforts. It was not
+    really known whether the protocol based on the reverse-engineering were complete or
+    even correct.
+
+    Microsoft published {{{http://download.microsoft.com/download/a/e/6/ae6e4142-aa58-45c6-8dcf-a657e5900cd3/%5BMS-NLMP%5D.pdf}MS-NLMP}}
+    and {{{http://download.microsoft.com/download/a/e/6/ae6e4142-aa58-45c6-8dcf-a657e5900cd3/%5BMS-NTHT%5D.pdf}MS-NTHT}}
+    specifications in February 2008 as a part of its
+    {{{http://www.microsoft.com/interop/principles/default.mspx}Interoperability
+    Principles initiative}}. 
+
+    HttpClient as of version 4.1 supports NTLMv1 and NTLMv2 authentication protocols out 
+    of the box using a custom authentication engine. However, there can still be compatibility
+    issues with newer Microsoft products as the default NTLM engine implementation is still 
+    relatively new. One can also use {{{http://jcifs.samba.org/}JCIFS}} as an alternative, more 
+    established and mature NTLM engine developed by Samba project. 
+
+* {Using Samba JCIFS as an alternative NTLM engine}
+
+    Follow these instructions to build an NTLMEngine implementation using JCIFS library
+
+    <<!!!!DISCLAIMER !!!! HttpComponents project DOES _NOT_ SUPPORT the code provided below. 
+    Use it as is at your own discretion>>.
+
+    * Download version 1.3.14 or newer of the JCIFS library from the 
+    {{{http://jcifs.samba.org/}Samba}} web site
+
+    * Implement NTLMEngine interface
+
+----------------------------------------
+import java.io.IOException;
+
+import jcifs.ntlmssp.NtlmFlags;
+import jcifs.ntlmssp.Type1Message;
+import jcifs.ntlmssp.Type2Message;
+import jcifs.ntlmssp.Type3Message;
+import jcifs.util.Base64;
+
+import org.apache.http.impl.auth.NTLMEngine;
+import org.apache.http.impl.auth.NTLMEngineException;
+
+public final class JCIFSEngine implements NTLMEngine {
+
+    private static final int TYPE_1_FLAGS = 
+            NtlmFlags.NTLMSSP_NEGOTIATE_56 | 
+            NtlmFlags.NTLMSSP_NEGOTIATE_128 | 
+            NtlmFlags.NTLMSSP_NEGOTIATE_NTLM2 | 
+            NtlmFlags.NTLMSSP_NEGOTIATE_ALWAYS_SIGN | 
+            NtlmFlags.NTLMSSP_REQUEST_TARGET;
+
+    public String generateType1Msg(final String domain, final String workstation)
+            throws NTLMEngineException {
+        final Type1Message type1Message = new Type1Message(TYPE_1_FLAGS, domain, workstation);
+        return Base64.encode(type1Message.toByteArray());
+    }
+
+    public String generateType3Msg(final String username, final String password,
+            final String domain, final String workstation, final String challenge)
+            throws NTLMEngineException {
+        Type2Message type2Message;
+        try {
+            type2Message = new Type2Message(Base64.decode(challenge));
+        } catch (final IOException exception) {
+            throw new NTLMEngineException("Invalid NTLM type 2 message", exception);
+        }
+        final int type2Flags = type2Message.getFlags();
+        final int type3Flags = type2Flags
+                & (0xffffffff ^ (NtlmFlags.NTLMSSP_TARGET_TYPE_DOMAIN | NtlmFlags.NTLMSSP_TARGET_TYPE_SERVER));
+        final Type3Message type3Message = new Type3Message(type2Message, password, domain,
+                username, workstation, type3Flags);
+        return Base64.encode(type3Message.toByteArray());
+    }
+
+}
+----------------------------------------
+
+    * Implement AuthSchemeFactory interface
+
+----------------------------------------
+import org.apache.http.auth.AuthScheme;
+import org.apache.http.auth.AuthSchemeFactory;
+import org.apache.http.impl.auth.NTLMScheme;
+import org.apache.http.params.HttpParams;
+
+public class NTLMSchemeFactory implements AuthSchemeFactory {
+
+    public AuthScheme newInstance(final HttpParams params) {
+        return new NTLMScheme(new JCIFSEngine());
+    }
+
+}
+----------------------------------------
+
+    * Register NTLMSchemeFactory with the HttpClient instance you want to NTLM 
+    enable.
+
+----------------------------------------
+httpclient.getAuthSchemes().register("ntlm", new NTLMSchemeFactory());
+----------------------------------------
+
+    * Set NTCredentials for the web server you are going to access.
+
+----------------------------------------
+httpclient.getCredentialsProvider().setCredentials(
+    new AuthScope("myserver", -1), 
+    new NTCredentials("username", "password", "MYSERVER", "MYDOMAIN"));
+-----------------------------------------------------------
+
+    * You are done.
+
+
+* {Why this code is not distributed with HttpClient} 
+
+    JCIFS is licensed under the Lesser General Public License (LGPL). This license 
+    is not compatible with the Apache Licenses under which all Apache Software is 
+    released. Lawyers of the Apache Software Foundation are currently investigating 
+    under which conditions Apache software is allowed to make use of LGPL software.

src/site/site.xml

@@ -36,6 +36,7 @@
       <item name="Tutorial" href="tutorial/html/index.html"/>
       <item name="Examples" href="examples.html"/>
       <item name="Client HTTP Programming Primer" href="primer.html"/>
+      <item name="NTLM Guide" href="ntlm.html"/>
       <item name="Logging" href="logging.html"/>
     </menu>
     <menu name="Modules">