$Id: USING_HTTPS.txt,v 1.4 2002/08/08 18:21:55 jsdever Exp $
================================================================
Using HTTPS with HttpClient
================================================================

To support the HTTPS protocol, httpclient uses an
implementation of the Java Secure Socket Extension.

See http://java.sun.com/products/jsse for more
information of the Secure Socket Extension.

Note that JSSE is only needed at runtime if you want
to use the HTTPS protocol.  You will however need
the JSSE classes to build httpclient from source.

If you are using Sun JDK 1.4, the Java Secure Socket Extension
classes are included with the JDK.

CONFIGURATION

You'll need to set up the JSSE within your Java
security configuration.

You can do this by configuring your JRE installation, or you
may do this in code.

To configure JSSE within your JRE, edit the java.security file
(typically in [JAVA-HOME]/jre/lib/security) and add the line:

   security.provider.<n>=com.sun.net.ssl.internal.ssl.Provider

where <n> is one greater than the existing security.provider.*
properties.

NOTE: You may have multiple copies of the JRE installation.
If you're having trouble, you may not have modified the
right file. Search for "java.security" to find additional
copies.

You will also need to set the Java system property:

   java.protocol.handler.pkgs

to include your JSSE provider. For Sun's implementation of
JSSE, this is:

   com.sun.net.ssl.internal.www.protocol

For example:

   -Djava.protocol.handler.pkgs=\
     com.sun.net.ssl.internal.www.protocol


Alternatively, you may configure the JSSE support in your code,
by invoking the following lines:

  // add the provider
  Security.addProvider(new
                     com.sun.net.ssl.internal.ssl.Provider());
  // set the property
  System.setProperty("java.protocol.handler.pkgs",
                     "com.sun.net.ssl.internal.www.protocol");