Skip to content

Most visited

Recently visited

navigation
Added in API level 1

HttpsURLConnection

public abstract class HttpsURLConnection
extends HttpURLConnection

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


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.

Summary

Inherited constants

From class java.net.HttpURLConnection

Fields

protected HostnameVerifier hostnameVerifier

The host name verifier used by this connection.

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.

Inherited methods

From class java.net.HttpURLConnection
From class java.net.URLConnection
From class java.lang.Object

Fields

hostnameVerifier

Added in API level 1
HostnameVerifier hostnameVerifier

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

Protected constructors

HttpsURLConnection

Added in API level 1
HttpsURLConnection (URL url)

Creates a new HttpsURLConnection with the specified URL.

Parameters
url URL: the URL to connect to.

Public methods

getCipherSuite

Added in API level 1
String getCipherSuite ()

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

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

getDefaultHostnameVerifier

Added in API level 1
HostnameVerifier getDefaultHostnameVerifier ()

Returns the default hostname verifier.

Returns
HostnameVerifier the default hostname verifier.

getDefaultSSLSocketFactory

Added in API level 1
SSLSocketFactory getDefaultSSLSocketFactory ()

Returns the default SSL socket factory for new instances.

Returns
SSLSocketFactory the default SSL socket factory for new instances.

getHostnameVerifier

Added in API level 1
HostnameVerifier getHostnameVerifier ()

Returns the hostname verifier used by this instance.

Returns
HostnameVerifier the hostname verifier used by this instance.

getLocalCertificates

Added in API level 1
Certificate[] getLocalCertificates ()

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

Returns
Certificate[] 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.

getLocalPrincipal

Added in API level 1
Principal getLocalPrincipal ()

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

Returns
Principal 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.

getPeerPrincipal

Added in API level 1
Principal getPeerPrincipal ()

Returns the Principal identifying the peer.

Returns
Principal 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.

getSSLSocketFactory

Added in API level 1
SSLSocketFactory getSSLSocketFactory ()

Returns the SSL socket factory used by this instance.

Returns
SSLSocketFactory the SSL socket factory used by this instance.

getServerCertificates

Added in API level 1
Certificate[] getServerCertificates ()

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

Returns
Certificate[] 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.

setDefaultHostnameVerifier

Added in API level 1
void setDefaultHostnameVerifier (HostnameVerifier v)

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

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

setDefaultSSLSocketFactory

Added in API level 1
void setDefaultSSLSocketFactory (SSLSocketFactory sf)

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

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

setHostnameVerifier

Added in API level 1
void setHostnameVerifier (HostnameVerifier v)

Sets the hostname verifier for this instance.

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

setSSLSocketFactory

Added in API level 1
void setSSLSocketFactory (SSLSocketFactory sf)

Sets the SSL socket factory for this instance.

Parameters
sf SSLSocketFactory: the SSL socket factory to be used by this instance.
Throws
IllegalArgumentException if the specified socket factory is null.
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.