Sample Code Illustrating HTTPS Connections

There are two primary APIs for accessing secure communications through JSSE. One way is through a socket-level API that can be used for arbitrary secure communications, as illustrated by the SSLSocketClient.java, SSLSocketClientWithTunneling.java, and SSLSocketClientWithClientAuth.java examples (with and without the examples described in Running ClassFileServer).

A second, and often simpler, way is through the standard Java URL API. You can communicate securely with an SSL-enabled web server by using the HTTPS URL protocol or scheme using the java.net.URL class.

Support for HTTPS URL schemes is implemented in many of the common browsers, which allows access to secured communications without requiring the socket-level API provided with JSSE. An example URL is https://www.verisign.com.

The trust and key management for the HTTPS URL implementation is environment-specific. The JSSE implementation provides an HTTPS URL implementation. To use a different HTTPS protocol implementation, set the java.protocol.handler.pkgs system property; see How to Specify a java.lang.System Property.

Running URLReader

The example URLReader.java illustrates using a URL to access resources on a secure site. By default, this example connects to www.verisign.com, but it can be adapted to connect to ClassFileServer.java. To do so, the URL will need to be modified to point to the correct address. You may also need to update the server's certificate or provide a custom HostNameVerifier (see HttpsURLConnection) if the hostname in the server's certificate doesn't match the URL's hostname.

Note:

If you are behind a firewall, you may need to set the https.proxyHost and https.proxyPort system properties to correctly specify the proxy.

Usage

java URLReader

URLReader.java

import java.net.*;
import java.io.*;

/*
 * This example illustrates using a URL to access resources
 * on a secure site.
 *
 * If you are running inside a firewall, please also set the following
 * Java system properties to the appropriate value:
 *
 *   https.proxyHost = <secure proxy server hostname>
 *   https.proxyPort = <secure proxy server port>
 *
 */

public class URLReader {
    public static void main(String[] args) throws Exception {
        URL verisign = new URL("https://www.verisign.com/");
        BufferedReader in = new BufferedReader(
                                new InputStreamReader(
                                verisign.openStream()));

        String inputLine;

        while ((inputLine = in.readLine()) != null)
            System.out.println(inputLine);

        in.close();
    }
}

Running URLReaderWithOptions

The example is very similar to URLReaader.java, but it enables you to set the system properties through main method arguments rather than as -D options to the Java runtime environment.

Usage

java URLReaderWithOptions [-h proxyhost] [-p proxyport] [-k protocolhandlerpkgs] [-c ciphersarray]

• proxyHost: secure proxy server hostname (https.proxyHost)
• proxyPort: secure proxy server port (https.proxyPort)
• protocolhandlerpkgs: a pipe-separated (|) list of protocol handlers (java.protocol.handler.pkgs)
• ciphersarray: enabled cipher suites as a comma-separated list (https.cipherSuites)

Note:

Multiple protocol handlers can be included in the protocolhandlerpkgs argument as a list with items separated by vertical bars. Multiple SSL cipher suite names can be included in the ciphersarray argument as a list with items separated by commas. The possible cipher suite names are the same as those returned by the SSLSocket.getSupportedCipherSuites() method. The suite names are taken from the SSL and TLS protocol specifications.

You need a protocolhandlerpkgs argument only if you want to use an HTTPS protocol handler implementation other than the default one provided by Oracle.

If you are running the sample code behind a firewall, then you must include arguments for the proxy host and the proxy port. Additionally, you can include a list of cipher suites to enable.

Here is an example of running URLReaderWithOptions and specifying the proxy host "webproxy" on port 8080:

java URLReaderWithOptions -h webproxy -p 8080

URLReaderWithOptions.java

import java.net.*;
import java.io.*;

/*
 * Using a URL to access resources on a secure site.
 *
 * You can optionally set the following command line options:
 *
 *     -h <secure proxy server hostname>
 *     -p <secure proxy server port>
 *     -k <| separated list of protocol handlers>
 *     -c <enabled cipher suites as a comma separated list>
 *
 */

public class URLReaderWithOptions {
    public static void main(String[] args) throws Exception {

        System.out.println("USAGE: java URLReaderWithOptions " +
            "[-h proxyhost] [-p proxyport] [-k protocolhandlerpkgs] " +
            "[-c ciphersarray]");

        // initialize system properties
        char option = 'd';
        for (int i = 0; i < args.length; i++) {
            System.out.println(option+": "+args[i]);
            switch(option) {
            case 'h':
                System.setProperty("https.proxyHost", args[i]);
                option = 'd';
                break;
            case 'p':
                System.setProperty("https.proxyPort", args[i]);
                option = 'd';
                break;
            case 'k':
                System.setProperty("java.protocol.handler.pkgs", args[i]);
                option = 'd';
                break;
            case 'c':
                System.setProperty("https.cipherSuites", args[i]);
                option = 'd';
                break;
            default:
                // get the next option
                if (args[i].startsWith("-")) {
                    option = args[i].charAt(1);
                }
            }
        }

        URL verisign = new URL("https://www.verisign.com/");
        BufferedReader in = new BufferedReader(
                                new InputStreamReader(
                                verisign.openStream()));

        String inputLine;

        while ((inputLine = in.readLine()) != null)
            System.out.println(inputLine);

        in.close();
    }
}