public abstract class

HttpsURLConnection

extends HttpURLConnection
java.lang.Object
   ↳ java.net.URLConnection
     ↳ java.net.HttpURLConnection
       ↳ javax.net.ssl.HttpsURLConnection

Class Overview

An HttpURLConnection for HTTPS (RFC 2818). A connected HttpsURLConnection allows access to the negotiated cipher suite, the server certificate chain, and the client certificate chain if any.

Providing an application specific X509TrustManager

If an application wants to trust Certificate Authority (CA) certificates that are not part of the system, it should specify its own X509TrustManager via a SSLSocketFactory set on the HttpsURLConnection. The X509TrustManager can be created based on a KeyStore using a TrustManagerFactory to supply trusted CA certificates. Note that self-signed certificates are effectively their own CA and can be trusted by including them in a KeyStore.

For example, to trust a set of certificates specified by a KeyStore:

   KeyStore keyStore = ...;
   TrustManagerFactory tmf = TrustManagerFactory.getInstance("X509");
   tmf.init(keyStore);
   SSLContext context = SSLContext.getInstance("TLS");
   context.init(null, tmf.getTrustManagers(), null);
   URL url = new URL("https://www.example.com/");
   HttpsURLConnection urlConnection = (HttpsURLConnection) url.openConnection();
   urlConnection.setSSLSocketFactory(context.getSocketFactory());
   InputStream in = urlConnection.getInputStream();
 

It is possible to implement X509TrustManager directly instead of using one created by a TrustManagerFactory. While this is straightforward in the insecure case of allowing all certificate chains to pass verification, writing a proper implementation will usually want to take advantage of CertPathValidator. In general, it might be better to write a custom KeyStore implementation to pass to the TrustManagerFactory than to try and write a custom X509TrustManager.

Providing an application specific X509KeyManager

A custom X509KeyManager can be used to supply a client certificate and its associated private key to authenticate a connection to the server. The X509KeyManager can be created based on a KeyStore using a KeyManagerFactory.

For example, to supply client certificates from a KeyStore:

   KeyStore keyStore = ...;
   KeyManagerFactory kmf = KeyManagerFactory.getInstance("X509");
   kmf.init(keyStore);
   SSLContext context = SSLContext.getInstance("TLS");
   context.init(kmf.getKeyManagers(), null, null);
   URL url = new URL("https://www.example.com/");
   HttpsURLConnection urlConnection = (HttpsURLConnection) url.openConnection();
   urlConnection.setSSLSocketFactory(context.getSocketFactory());
   InputStream in = urlConnection.getInputStream();
 

A X509KeyManager can also be implemented directly. This can allow an application to return a certificate and private key from a non-KeyStore source or to specify its own logic for selecting a specific credential to use when many may be present in a single KeyStore.

TLS Intolerance Support

This class attempts to create secure connections using common TLS extensions and SSL deflate compression. Should that fail, the connection will be retried with SSLv3 only.

Summary

[Expand]
Inherited Constants
From class java.net.HttpURLConnection
Fields
protected HostnameVerifier hostnameVerifier The host name verifier used by this connection.
[Expand]
Inherited Fields
From class java.net.HttpURLConnection
From class java.net.URLConnection
Protected Constructors
HttpsURLConnection(URL url)
Creates a new HttpsURLConnection with the specified URL.
Public Methods
abstract String getCipherSuite()
Returns the name of the cipher suite negotiated during the SSL handshake.
static HostnameVerifier getDefaultHostnameVerifier()
Returns the default hostname verifier.
static SSLSocketFactory getDefaultSSLSocketFactory()
Returns the default SSL socket factory for new instances.
HostnameVerifier getHostnameVerifier()
Returns the hostname verifier used by this instance.
abstract Certificate[] getLocalCertificates()
Returns the list of local certificates used during the handshake.
Principal getLocalPrincipal()
Returns the Principal used to identify the local host during the handshake.
Principal getPeerPrincipal()
Returns the Principal identifying the peer.
SSLSocketFactory getSSLSocketFactory()
Returns the SSL socket factory used by this instance.
abstract Certificate[] getServerCertificates()
Return the list of certificates identifying the peer during the handshake.
static void setDefaultHostnameVerifier(HostnameVerifier v)
Sets the default hostname verifier to be used by new instances.
static void setDefaultSSLSocketFactory(SSLSocketFactory sf)
Sets the default SSL socket factory to be used by new instances.
void setHostnameVerifier(HostnameVerifier v)
Sets the hostname verifier for this instance.
void setSSLSocketFactory(SSLSocketFactory sf)
Sets the SSL socket factory for this instance.
[Expand]
Inherited Methods
From class java.net.HttpURLConnection
From class java.net.URLConnection
From class java.lang.Object

Fields

protected HostnameVerifier hostnameVerifier

Since: API Level 1

The host name verifier used by this connection. It is initialized from the default hostname verifier setDefaultHostnameVerifier(HostnameVerifier) or getDefaultHostnameVerifier().

Protected Constructors

protected HttpsURLConnection (URL url)

Since: API Level 1

Creates a new HttpsURLConnection with the specified URL.

Parameters
url the URL to connect to.

Public Methods

public abstract String getCipherSuite ()

Since: API Level 1

Returns the name of the cipher suite negotiated during the SSL handshake.

Returns
  • the name of the cipher suite negotiated during the SSL handshake.
Throws
IllegalStateException if no connection has been established yet.

public static HostnameVerifier getDefaultHostnameVerifier ()

Since: API Level 1

Returns the default hostname verifier.

Returns
  • the default hostname verifier.

public static SSLSocketFactory getDefaultSSLSocketFactory ()

Since: API Level 1

Returns the default SSL socket factory for new instances.

Returns
  • the default SSL socket factory for new instances.

public HostnameVerifier getHostnameVerifier ()

Since: API Level 1

Returns the hostname verifier used by this instance.

Returns
  • the hostname verifier used by this instance.

public abstract Certificate[] getLocalCertificates ()

Since: API Level 1

Returns the list of local certificates used during the handshake. These certificates were sent to the peer.

Returns
  • Returns the list of certificates used during the handshake with the local identity certificate followed by CAs, or null if no certificates were used during the handshake.
Throws
IllegalStateException if no connection has been established yet.

public Principal getLocalPrincipal ()

Since: API Level 1

Returns the Principal used to identify the local host during the handshake.

Returns
  • the Principal used to identify the local host during the handshake, or null if none was used.
Throws
IllegalStateException if no connection has been established yet.

public Principal getPeerPrincipal ()

Since: API Level 1

Returns the Principal identifying the peer.

Returns
  • the Principal identifying the peer.
Throws
SSLPeerUnverifiedException if the identity of the peer has not been verified.
IllegalStateException if no connection has been established yet.

public SSLSocketFactory getSSLSocketFactory ()

Since: API Level 1

Returns the SSL socket factory used by this instance.

Returns
  • the SSL socket factory used by this instance.

public abstract Certificate[] getServerCertificates ()

Since: API Level 1

Return the list of certificates identifying the peer during the handshake.

Returns
  • the list of certificates identifying the peer with the peer's identity certificate followed by CAs.
Throws
SSLPeerUnverifiedException if the identity of the peer has not been verified..
IllegalStateException if no connection has been established yet.

public static void setDefaultHostnameVerifier (HostnameVerifier v)

Since: API Level 1

Sets the default hostname verifier to be used by new instances.

Parameters
v the new default hostname verifier
Throws
IllegalArgumentException if the specified verifier is null.

public static void setDefaultSSLSocketFactory (SSLSocketFactory sf)

Since: API Level 1

Sets the default SSL socket factory to be used by new instances.

Parameters
sf the new default SSL socket factory.
Throws
IllegalArgumentException if the specified socket factory is null.

public void setHostnameVerifier (HostnameVerifier v)

Since: API Level 1

Sets the hostname verifier for this instance.

Parameters
v the hostname verifier for this instance.
Throws
IllegalArgumentException if the specified verifier is null.

public void setSSLSocketFactory (SSLSocketFactory sf)

Since: API Level 1

Sets the SSL socket factory for this instance.

Parameters
sf the SSL socket factory to be used by this instance.
Throws
IllegalArgumentException if the specified socket factory is null.