Package javax.net.ssl

Class HttpsURLConnection

java.lang.Object
java.net.URLConnection
java.net.HttpURLConnection
javax.net.ssl.HttpsURLConnection
Direct Known Subclasses:
HttpsURLConnectionImpl
public abstract class HttpsURLConnection
extends HttpURLConnection
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 = ...;
   String algorithm = TrustManagerFactory.getDefaultAlgorithm();
   TrustManagerFactory tmf = TrustManagerFactory.getInstance(algorithm);
   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 = ...;
   String algorithm = KeyManagerFactory.getDefaultAlgorithm();
   KeyManagerFactory kmf = KeyManagerFactory.getInstance(algorithm);
   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.

  • Field Details

  • Constructor Details

    • HttpsURLConnection

      protected HttpsURLConnection​(URL url)
      Creates a new HttpsURLConnection with the specified URL.
      Parameters:
      url - the URL to connect to.

  • Method Details

    • setDefaultHostnameVerifier

      public static void setDefaultHostnameVerifier​(HostnameVerifier v)
      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.

    • getDefaultHostnameVerifier

      public static HostnameVerifier getDefaultHostnameVerifier()
      Returns the default hostname verifier.
      Returns:
      the default hostname verifier.

    • setDefaultSSLSocketFactory

      public static void setDefaultSSLSocketFactory​(SSLSocketFactory sf)
      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.

    • getDefaultSSLSocketFactory

      public static SSLSocketFactory getDefaultSSLSocketFactory()
      Returns the default SSL socket factory for new instances.
      Returns:
      the default SSL socket factory for new instances.

    • getCipherSuite

      public abstract String getCipherSuite()
      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.

    • getLocalCertificates

      public abstract Certificate[] getLocalCertificates()
      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.

    • getServerCertificates

      public abstract Certificate[] getServerCertificates() throws SSLPeerUnverifiedException
      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.

    • getPeerPrincipal

      public Principal getPeerPrincipal() throws SSLPeerUnverifiedException
      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.

    • getLocalPrincipal

      public Principal getLocalPrincipal()
      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.

    • setHostnameVerifier

      public void setHostnameVerifier​(HostnameVerifier v)
      Sets the hostname verifier for this instance.
      Parameters:
      v - the hostname verifier for this instance.
      Throws:
      IllegalArgumentException - if the specified verifier is null.

    • getHostnameVerifier

      public HostnameVerifier getHostnameVerifier()
      Returns the hostname verifier used by this instance.
      Returns:
      the hostname verifier used by this instance.

    • setSSLSocketFactory

      public void setSSLSocketFactory​(SSLSocketFactory sf)
      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.

    • getSSLSocketFactory

      public SSLSocketFactory getSSLSocketFactory()
      Returns the SSL socket factory used by this instance.
      Returns:
      the SSL socket factory used by this instance.