commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject cvs commit: jakarta-commons/httpclient/xdocs authentication.xml
Date Tue, 01 Jun 2004 20:57:59 GMT
olegk       2004/06/01 13:57:59

  Modified:    httpclient/xdocs authentication.xml
  Log:
  PR #29062 ([API Doc] Improve the description of the preemptive authentication)
  
  Contributed by Oleg Kalnichevski
  Reviewed by Michael Becke
  
  Revision  Changes    Path
  1.10      +35 -5     jakarta-commons/httpclient/xdocs/authentication.xml
  
  Index: authentication.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/authentication.xml,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- authentication.xml	21 Aug 2003 16:08:54 -0000	1.9
  +++ authentication.xml	1 Jun 2004 20:57:59 -0000	1.10
  @@ -22,8 +22,8 @@
   		the only thing a developer must do is actually provide the login
   		credentials.  These credentials are stored in the HttpState instance
   		and can be set or retrieved using the <code>setCredentials(String realm,
  -		Credentials cred)</code> and <code>getCredentials(String realm)</code>
  -		methods.</p>
  +		String host, Credentials cred)</code> and <code>getCredentials(String realm,
  +		String host)</code> methods.</p>
   
   		<p><i>Note:</i> To set default Credentials for any realm that has not
been
   		explicitly specified, pass in <code>null</code> as the value of
  @@ -41,7 +41,15 @@
   
       <source>client.getState().setAuthenticationPreemptive(true);</source>
   
  -    <p>To enable preemptive authentication by default for all newly created
  +		<p>Preemptive authentication mode also requires default Credentials to be set 
  +		for the target or proxy host against which preemptive authentication is to be 
  +		attempted. Failure to provide default credentials will render the preemptive 
  +		authentication mode ineffective.</p>
  +
  +<source>Credentials defaultcreds = new UsernamePasswordCredentials("username", "password");
  +client.getState().setCredentials(null, "myhost", defaultcreds);</source>
  +
  +	<p>To enable preemptive authentication by default for all newly created
       <tt>HttpState</tt>'s, a system property can be set, as shown below.</p>
   
   		<source>setSystemProperty(Authenticator.PREEMPTIVE_PROPERTY, "true");</source>
  @@ -58,6 +66,28 @@
   		a userid and password in the Proxy-Authorization header field without
   		receiving another challenge from the proxy server.</blockquote>
   		</subsection>
  +		<subsection name="Security aspects of server authentication">
  +
  +		<p>Use default credentials with caution when developing applications 
  +        that may need to communicate with untrusted web sites or web applications. When

  +        preemptive authentication is activated or credentials are not explicitly given

  +        for a specific authentication realm and host HttpClient will use default credentials

  +        to try to authenticate with the target site. If you want to avoid sending sensitive

  +        credentials to an untrusted site, narrow the credentials scope as much as possible:

  +        always specify the host and, when known, the realm the credentials are intended
for.
  +        </p>
  +        <p>
  +        Setting credentials with <code>null</code> host and realm values is
highly 
  +        discouraged in production applications. Doing this will result in the credentials

  +        being sent for all authentication attempts (all requests in the case of 
  +        preemptive authentication). Use of this setting should be limited to debugging

  +        only.
  +        </p>
  +<source>// To be avoided unless in debug mode
  +Credentials defaultcreds = new UsernamePasswordCredentials("username", "password");
  +client.getState().setCredentials(null, null, defaultcreds);</source>
  +
  +		</subsection>
   	</section>
   
   	<section name="Proxy Authentication">
  @@ -155,7 +185,7 @@
         <a href="http://cvs.apache.org/viewcvs.cgi/jakarta-commons/httpclient/src/examples/">example
directory</a> in CVS.
         </p>
     </section>
  -  
  +    
     <section name="Troubleshooting">
         <p>Some authentication schemes may use cryptographic algorithms. It is recommended
to include the
            <a href="http://java.sun.com/products/jce/" target="_blank">Java Cryptography
Extension</a> in
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message