Index: src/java/org/apache/commons/httpclient/NTCredentials.java =================================================================== RCS file: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/NTCredentials.java,v retrieving revision 1.6 diff -u -r1.6 NTCredentials.java --- src/java/org/apache/commons/httpclient/NTCredentials.java 30 Jan 2003 05:01:54 -0000 1.6 +++ src/java/org/apache/commons/httpclient/NTCredentials.java 15 Aug 2003 06:54:39 -0000 @@ -63,8 +63,8 @@ package org.apache.commons.httpclient; -/** - *

Username and password {@link Credentials}.

+/** {@link Credentials} for use with the NTLM authentication scheme which requires additional + * information. * * @author Adrian Sutton * @author Mike Bowler @@ -77,10 +77,10 @@ // ----------------------------------------------------- Instance Variables - /** The Domain. */ + /** The Domain to authenticate with. */ private String domain; - /** The Host. */ + /** The host the authentication request is originating from. */ private String host; @@ -95,10 +95,12 @@ /** * Constructor. - * @param userName The user name. + * @param userName The user name. This should not include the domain to authenticate with. + * For example: "user" is correct whereas "DOMAIN\\user" is not. * @param password The password. - * @param host The host. - * @param domain The domain. + * @param host The host the authentication request is originating from. Essentially, the + * computer name for this machine. + * @param domain The domain to authenticate within. */ public NTCredentials(String userName, String password, String host, String domain) { @@ -110,7 +112,7 @@ /** - * Domain property setter. + * Sets the domain to authenticate with. * * @param domain the NT domain to authenticate in. * @@ -122,9 +124,9 @@ } /** - * Domain property getter. + * Retrieves the name to authenticate with. * - * @return String domain + * @return String the domain these credentials are intended to authenticate with. * * @see #setDomain(String) * @@ -133,8 +135,7 @@ return domain; } - /** - * Host property setter. + /** Sets the host name of the computer originating the request. * * @param host the Host the user is logged into. */ @@ -143,9 +144,9 @@ } /** - * Host property getter. + * Retrieves the host name of the computer originating the request. * - * @return String host. + * @return String the host the user is logged into. */ public String getHost() { return this.host; Index: src/java/org/apache/commons/httpclient/NTLM.java =================================================================== RCS file: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/Attic/NTLM.java,v retrieving revision 1.12 diff -u -r1.12 NTLM.java --- src/java/org/apache/commons/httpclient/NTLM.java 11 Feb 2003 03:41:14 -0000 1.12 +++ src/java/org/apache/commons/httpclient/NTLM.java 15 Aug 2003 06:54:43 -0000 @@ -66,7 +66,6 @@ import java.io.UnsupportedEncodingException; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; -import java.security.Security; import javax.crypto.BadPaddingException; import javax.crypto.Cipher; @@ -86,6 +85,12 @@ * protocol is a proprietary Microsoft protocol and as such no RFC * exists for it. This class is based upon the reverse engineering * efforts of a wide range of people.

+ * + *

Please note that an implementation of JCE must be correctly installed and configured when + * using NTLM support.

+ * + *

This class should not be used externally to HttpClient as it's API is specifically + * designed to work with HttpClient's use case, in particular it's connection management.

* * @deprecated this class will be made package access for 2.0beta2 * @@ -110,31 +115,6 @@ /** Character encoding */ public static final String DEFAULT_CHARSET = "ASCII"; - //Initialize the security provider - static { - //TODO: do not use System properties - final String secProviderName - = System.getProperty("httpclient.security.provider", - "com.sun.crypto.provider.SunJCE"); - try { - java.security.Provider secProvider = (java.security.Provider) - Class.forName(secProviderName).newInstance(); - Security.addProvider(secProvider); - } catch (ClassNotFoundException e) { - LOG.error("Specified security provider " + secProviderName - + " could not be found by the class loader", e); - } catch (ClassCastException e) { - LOG.error("Specified security provider " + secProviderName - + " is not of type java.security.Provider", e); - } catch (InstantiationException e) { - LOG.error("Specified security provider " + secProviderName - + " could not be instantiated", e); - } catch (IllegalAccessException e) { - LOG.error("Specified security provider " + secProviderName - + " does not allow access to the constructor", e); - } - } - /** * Returns the response for the given message. * @@ -280,10 +260,12 @@ } /** - * TODO: Figure out what this method really does. - * @param host The host - * @param domain The domain - * @return String + * Creates the first message (type 1 message) in the NTLM authentication sequence. + * This message includes the user name, domain and host for the authentication session. + * + * @param host the computer name of the host requesting authentication. + * @param domain The domain to authenticate with. + * @return String the message to add to the HTTP request header. */ private String getType1Message(String host, String domain) { host = host.toUpperCase(); @@ -372,11 +354,14 @@ } /** - * Creates the type 3 message using the given server nonce. - * @param user The user. + * Creates the type 3 message using the given server nonce. The type 3 message includes all the + * information for authentication, host, domain, username and the result of encrypting the + * nonce sent by the server using the user's password as the key. + * + * @param user The user name. This should not include the domain name. * @param password The password. - * @param host The host. - * @param domain The domain. + * @param host The host that is originating the authentication request. + * @param domain The domain to authenticate within. * @param nonce the 8 byte array the server sent. * @return The type 3 message. * @throws HttpException If {@encrypt(byte[],byte[])} fails. @@ -585,7 +570,7 @@ /** * Converts a given number to a two byte array in little endian order. * @param num the number to convert. - * @return The new array. + * @return The byte representation of num in little endian order. */ private byte[] convertShort(int num) { byte[] val = new byte[2]; Index: src/java/org/apache/commons/httpclient/auth/NTLMScheme.java =================================================================== RCS file: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/auth/NTLMScheme.java,v retrieving revision 1.6.2.1 diff -u -r1.6.2.1 NTLMScheme.java --- src/java/org/apache/commons/httpclient/auth/NTLMScheme.java 13 Aug 2003 19:58:14 -0000 1.6.2.1 +++ src/java/org/apache/commons/httpclient/auth/NTLMScheme.java 15 Aug 2003 06:54:48 -0000 @@ -70,10 +70,9 @@ import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; -/** - *

- * Microsoft proprietary NTLM authentication scheme. - *

+/** An implementation of the Microsoft proprietary NTLM authentication scheme. For a detailed + * explanation of the NTLM scheme please see + * http://davenport.sourceforge.net/ntlm.html. * * @author Remy Maucherat * @author Rodney Waldhoff @@ -156,7 +155,10 @@ /** - * Returns authentication parameter with the given name, if available. + * Returns the authentication parameter with the given name, if available. + * + *

There are no valid parameters for NTLM authentication so this method always returns + * null.

* * @param name The name of the parameter to be returned * Index: xdocs/authentication.xml =================================================================== RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/authentication.xml,v retrieving revision 1.5.2.1 diff -u -r1.5.2.1 authentication.xml --- xdocs/authentication.xml 14 Aug 2003 09:08:50 -0000 1.5.2.1 +++ xdocs/authentication.xml 15 Aug 2003 06:54:52 -0000 @@ -159,9 +159,18 @@

Some authentication schemes may use cryptographic algorithms. It is recommended to include the Java Cryptography Extension in - your runtime environment prior to JDK 1.4. - + your runtime environment prior to JDK 1.4. Also note that you must register the JCE + implementation manually as HttpClient will not do so automatically. For instance to + register the Sun JCE implementation, you should execute the following code before attempting + to use HttpClient.

+ + +String secProviderName = "com.sun.crypto.provider.SunJCE"); +java.security.Provider secProvider = + (java.security.Provider)Class.forName(secProviderName).newInstance(); +Security.addProvider(secProvider); +