adrian 2003/06/12 15:24:21
Modified: httpclient/xdocs sslguide.xml
Log:
Minor clean-ups and rewording for clarity.
Contributed by Adrian Sutton
Reviewed by Oleg Kalnichevski
Revision Changes Path
1.2 +127 -105 jakarta-commons/httpclient/xdocs/sslguide.xml
Index: sslguide.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/sslguide.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- sslguide.xml 12 Jun 2003 03:31:50 -0000 1.1
+++ sslguide.xml 12 Jun 2003 22:24:21 -0000 1.2
@@ -5,6 +5,7 @@
<properties>
<title>HttpClient SSL Guide</title>
<author email="[EMAIL PROTECTED]">Oleg Kalnichevski</author>
+ <author email="[EMAIL PROTECTED]">Adrian Sutton</author>
<revision>$Id$</revision>
</properties>
@@ -16,7 +17,7 @@
HttpClient provides full support for HTTP over Secure Sockets Layer (SSL) or
IETF Transport Layer
Security (TLS) protocols by leveraging the <a
href="http://java.sun.com/products/jsse/index.html";>
Java Secure Socket Extension (JSSE)</a>. JSSE has been integrated into the
Java 2 platform as of
- version 1.4 and usually should work with HttpClient out of the box. On older
Java 2 versions JSSE
+ version 1.4 and works with HttpClient out of the box. On older Java 2
versions JSSE
needs to be manually installed and configured. Installation instructions can
be found
<a
href="http://java.sun.com/products/jsse/doc/guide/API_users_guide.html#Installation";>here</a>
</p>
@@ -25,7 +26,7 @@
<section name="Standard SSL in HttpClient">
<p>
- With SSL properly set up and configured, secure HTTP communication over SSL
should be as simple
+ Once you have JSSE correctly installed, secure HTTP communication over SSL
should be as simple
as plain HTTP communication.
</p>
<source><![CDATA[
@@ -37,8 +38,8 @@
<p>
HTTPS communication via an authenticating proxy server is also no different
from plain HTTP
- communication. All the low-level details of establishing a tunneled SSL
connection are abstracted
- away by HttpClient:
+ communication. All the low-level details of establishing a tunneled SSL
connection are handled
+ by HttpClient:
</p>
<source><![CDATA[
@@ -57,105 +58,120 @@
<section name="Customizing SSL in HttpClient">
<p>
- Per default HTTP client does not perform any custom certificate or
certificate chain validation.
- The default HTTPS protocol implementation is completely reliant upon the
standard functionality
- of the JSSE that comes with the JVM. If your application requires some
additional processing of
- credentials such certificate verification or certificate chain validation,
or you want to be using
- a third party SSL library, you can augment HttpClient to meet your specific
requirements by providing
- a custom protocol implementation.
- </p>
+ The default behaviour of HttpClient is suitable for most uses, however
+ there are some aspects which you may want to configure. The most common
+ requirements for customizing SSL are:</p>
+
+ <ul>
+ <li>Ability to accept self-signed or untrusted SSL certificates. This
+ is highlighted by an <code>SSLException</code> with the message
+ <i>Unrecognized SSL handshake</i> (or similar) being thrown when a
+ connection attempt is made.</li>
+
+ <li>You want to use a third party SSL library instead of Sun's default
+ implementation.</li>
+ </ul>
+
+ <p>
+ Implementation of a custom protocol involves the following steps:
+ </p>
- <p>
- Implementation of a custom protocol involves the following steps:
- </p>
+ <ol>
- <ul>
+ <li>
+ <p>
+ Provide a custom socket factory that implements
+ <a
href="apidocs/org/apache/commons/httpclient/protocol/SecureProtocolSocketFactory.html">
+ org.apache.commons.httpclient.protocol.SecureProtocolSocketFactory</a>
interface. The socket
+ factory is responsible for opening a socket to the target server
+ using either the standard or a third party SSL library and
+ performing any required initialization such as performing the
+ connection handshake. Generally the initialization is performed
+ automatically when the socket is created.
+ </p>
+ </li>
- <li>
- <p>
- Provide a custom socket factory that implements
- <a
href="apidocs/org/apache/commons/httpclient/protocol/SecureProtocolSocketFactory.html">
- org.apache.commons.httpclient.protocol.SecureProtocolSocketFactory</a>
interface. The socket
- factory should encapsulate application specific aspects of opening a
socket to the target server
- using either standard or third party SSL library.
- </p>
- </li>
+ <li>
+ <p>
+ Instantiate an object of type <a
href="apidocs/org/apache/commons/httpclient/protocol/Protocol.html">
+ org.apache.commons.httpclient.protocol.Protocol</a>. The new instance
+ would be created with a valid URI protocol scheme (https in this
+ case), the custom socket factory (discussed above) and a default port
+ number (typically 443 for https). For example:
+ </p>
- <li>
- <p>
- Instantiate an object of type <a
href="apidocs/org/apache/commons/httpclient/protocol/Protocol.html">
- org.apache.commons.httpclient.protocol.Protocol</a>. The new instance
would be initialized with the
- following parameters: valid URI protocol scheme (https in this case),
custom socket factory discussed
- above, and a default port number.
- </p>
+ <source><![CDATA[
+Protocol myhttps = new Protocol("https", new MySSLSocketFactory(), 443);
+ ]]></source>
- <source><![CDATA[
- Protocol myhttps = new Protocol("https", new MySSLSocketFactory(), 443);
- ]]></source>
+ <p>
+ The new instance of protocol can then be set as the protocol handler
+ for a HostConfiguration. For example to configure the default host and
+ protocol handler for a HttpClient instance use:
+ </p>
- <p>
- The resultant protocol object then can be used as a default protocol for a
host.
- </p>
+ <source><![CDATA[
+HttpClient httpclient = new HttpClient();
+httpclient.getHostConfiguration().setHost("www.whatever.com", 443, myhttps);
+GetMethod httpget = new GetMethod("/");
+httpclient.executeMethod(httpget);
+ ]]></source>
- <source><![CDATA[
- HttpClient httpclient = new HttpClient();
- httpclient.getHostConfiguration().setHost("www.whatever.com", 443, myhttps);
- GetMethod httpget = new GetMethod("/");
- httpclient.executeMethod(httpget);
- ]]></source>
+ </li>
- </li>
+ <li>
+ <p>
+ Finally, you can register your custom protocol as the default handler
+ for a specific protocol designator (eg: https) by calling the
+ Protocol.registerProtocol method. You can specify your own protocol
+ designator (such as 'myhttps') if you need to use your custom
+ protocol as well as the default SSL protocol implementation.
+ </p>
- <li>
- <p>
- Optionally register the custom protocol by calling
Protocol.registerProtocol method. You can
- specify your own protocol designator (such as 'myhttps') if you are going
to be using this protocol
- along with the default SSL protocol implementation.
- </p>
+ <source><![CDATA[
+Protocol.registerProtocol("myhttps",
+new Protocol("https", new MySSLSocketFactory(), 9443));
+ ]]></source>
- <source><![CDATA[
- Protocol.registerProtocol("myhttps",
- new Protocol("https", new MySSLSocketFactory(), 9443));
- ]]></source>
+ <p>
+ Once registered the protocol be used as a 'virtual' scheme inside target
URIs.
+ </p>
- <p>
- Once registered the protocol be used as a 'virtual' scheme inside target
URIs.
- </p>
+ <source><![CDATA[
+HttpClient httpclient = new HttpClient();
+GetMethod httpget = new GetMethod("myhttps://www.whatever.com/";);
+httpclient.executeMethod(httpget);
+ ]]></source>
- <source><![CDATA[
- HttpClient httpclient = new HttpClient();
- GetMethod httpget = new GetMethod("myhttps://www.whatever.com/";);
- httpclient.executeMethod(httpget);
- ]]></source>
+ <p>
+ If you want this protocol to represent the default SSL protocol
implementation, simply register
+ it under 'https' designator, which will make the protocol object take place
of the existing one
+ </p>
- <p>
- If you want this protocol to represent the default SSL protocol
implementation, simply register
- it under 'https' designator, which will make the protocol object take
place of the existing one
- </p>
-
- <source><![CDATA[
- Protocol.registerProtocol("https",
- new Protocol("https", new MySSLSocketFactory(), 443));
- HttpClient httpclient = new HttpClient();
- GetMethod httpget = new GetMethod("https://www.whatever.com/";);
- httpclient.executeMethod(httpget);
- ]]></source>
+ <source><![CDATA[
+Protocol.registerProtocol("https",
+new Protocol("https", new MySSLSocketFactory(), 443));
+HttpClient httpclient = new HttpClient();
+GetMethod httpget = new GetMethod("https://www.whatever.com/";);
+httpclient.executeMethod(httpget);
+ ]]></source>
- </li>
+ </li>
- </ul>
+ </ol>
- </section>
+ </section>
- <section name="Examples of SSL customization in HttpClient">
-
- <p>
- There are several custom socket factories available in our contribution
package. They can
- be a good start for those who seek to tailor the behavior of the HTTPS
protocol to the specific
- needs of their application:
- </p>
+ <section name="Examples of SSL customization in HttpClient">
+
+ <p>
+ There are several custom socket factories available in our contribution
+ package. They can be a good start for those who seek to tailor the
+ behavior of the HTTPS protocol to the specific needs of their
+ application:
+ </p>
- <ul>
+ <ul>
<li>
<a
href="http://cvs.apache.org/viewcvs/jakarta-commons/httpclient/src/contrib/org/apache/commons/httpclient/contrib/ssl/EasySSLProtocolSocketFactory.java?rev=HEAD";>
@@ -185,19 +201,20 @@
Due to what appears to be a bug in Sun's older (below 1.4) implementation
of
Java Virtual Machines or JSSE there's no reliable way of telling if an SSL
connection
is 'stale' or not. For example, the HTTP 1.1 specification permits HTTP
servers in
- 'keep-alive' mode to drop connection to the client after a given period
inactivity
+ 'keep-alive' mode to drop the connection to the client after a given
period inactivity
without having to notify the client, effectively rendering such connection
unusable or
- 'stale'. For the HTTP agent written in Java there's no reliable way known
to us to test
- if a connection is 'stale' other than attempting to perform a read on it.
If you happen
- to know a better way we would be delighted to hear about it. Rather
unfortunately, a read
+ 'stale'. For the HTTP agent written in Java there's no reliable way to
test
+ if a connection is 'stale' other than attempting to perform a read on it.
+ However, a read
operation on an idle SSL connection on Sun JVM older than 1.4 returns 'end
of stream'
instead of an expected read timeout. That effectively makes the connection
appear 'stale'
- to the HttpClient, which leaves it with no other way but to drop the
connection and to
+ to HttpClient, which leaves it with no other way but to drop the
connection and to
open a new one, thus defeating HTTP 1.1 keep-alive mechanism and resulting
in significant
- performance degradation (SSL authentication is a highly time consuming
operation). Sun's
- Java 1.4 SSL implementation does not exhibit this kind of problem. Plain
sockets on all
- JVMs are not subject to the problem either.
+ performance degradation (SSL authentication is a highly time consuming
operation). The problem appears to have been fixed in Sun's
+ Java 1.4 SSL implementation. Sockets which are not using HTTPS are
+ unaffected on any JVM.
</p>
+
<p>
<strong>Workaround:</strong> If persistent SSL connections support is an
issue for your
application we strongly advise you to upgrade to Java 1.4.
@@ -214,9 +231,12 @@
breaking the existing APIs. The problem will be addressed in HttpClient
release 2.1.
</p>
<p>
- <strong>Workaround:</strong> Use preemptive server authentication. Please
note that only
- BASIC authentication can be used preemptively. For more detailed
information please refer
- to the <a href="authentication.html">Authentication Guide</a>.
+ <strong>Workaround:</strong> Use preemptive server authentication or
+ configure the server to keep the connection alive when returning an
+ authorization challenge. Please note that only
+ BASIC authentication can be used preemptively. For more detailed
+ information please refer to the
+ <a href="authentication.html">Authentication Guide</a>.
</p>
</li>
@@ -227,17 +247,19 @@
<section name="Troubleshooting">
<p>
- If you are unlucky and HTTPS with HttpClient does not work for you, it may
be a bit premature
- to blame it squarely on HttpClient. The JSSE is highly prone to
configuration problems, especially
- on older JVMs, which it is not an integral part of.
+ JSSE is prone to configuration problems, especially on older JVMs,
+ which it is not an integral part of. As such, if you do encounter
+ problems with SSL and HttpClient it is important to check that JSSE is
+ correctly installed.
</p>
<p>
- The application below can be used as an ultimate test that can reliably
tell if SSL configured
- properly, as it relies on a plain socket in order to communicate with the
target server. If you
- get an exception while executing this code, most certainly SSL is not
functioning properly with
- your JVM. Please refer to Sun's official resources for support or
additional details on JSSE
- configuration.
+ The application below can be used as an ultimate test that can reliably
+ tell if SSL configured properly, as it relies on a plain socket in
+ order to communicate with the target server. If an exception is thrown
+ when executing this code, SSL is not correctly installed and configured.
+ Please refer to Sun's official resources for support or additional
+ details on JSSE configuration.
</p>
<source><![CDATA[
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
