HttpsURLConnection

public abstract class HttpsURLConnection
extends HttpURLConnection

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


HttpsURLConnection extends HttpURLConnection with support for https-specific features.

See http://www.w3.org/pub/WWW/Protocols/ and RFC 2818 for more details on the https specification.

This class uses HostnameVerifier and SSLSocketFactory. There are default implementations defined for both classes. However, the implementations can be replaced on a per-class (static) or per-instance basis. All new HttpsURLConnections instances will be assigned the "default" static values at instance creation, but they can be overriden by calling the appropriate per-instance set method(s) before connecting.

Summary

Inherited constants

Fields

protected HostnameVerifier hostnameVerifier

The hostnameVerifier for this object.

Inherited fields

Protected constructors

HttpsURLConnection(URL url)

Creates an HttpsURLConnection using the URL specified.

Public methods

abstract String getCipherSuite()

Returns the cipher suite in use on this connection.

static HostnameVerifier getDefaultHostnameVerifier()

Gets the default HostnameVerifier that is inherited by new instances of this class.

static SSLSocketFactory getDefaultSSLSocketFactory()

Gets the default static SSLSocketFactory that is inherited by new instances of this class.

HostnameVerifier getHostnameVerifier()

Gets the HostnameVerifier in place on this instance.

abstract Certificate[] getLocalCertificates()

Returns the certificate(s) that were sent to the server during handshaking.

Principal getLocalPrincipal()

Returns the principal that was sent to the server during handshaking.

Principal getPeerPrincipal()

Returns the server's principal which was established as part of defining the session.

SSLSocketFactory getSSLSocketFactory()

Gets the SSL socket factory to be used when creating sockets for secure https URL connections.

abstract Certificate[] getServerCertificates()

Returns the server's certificate chain which was established as part of defining the session.

static void setDefaultHostnameVerifier(HostnameVerifier v)

Sets the default HostnameVerifier inherited by a new instance of this class.

static void setDefaultSSLSocketFactory(SSLSocketFactory sf)

Sets the default SSLSocketFactory inherited by new instances of this class.

void setHostnameVerifier(HostnameVerifier v)

Sets the HostnameVerifier for this instance.

void setSSLSocketFactory(SSLSocketFactory sf)

Sets the SSLSocketFactory to be used when this instance creates sockets for secure https URL connections.

Inherited methods

Fields

hostnameVerifier

Added in API level 1
protected HostnameVerifier hostnameVerifier

The hostnameVerifier for this object.

Protected constructors

HttpsURLConnection

Added in API level 1
protected HttpsURLConnection (URL url)

Creates an HttpsURLConnection using the URL specified.

Parameters
url URL: the URL

Public methods

getCipherSuite

Added in API level 1
public abstract String getCipherSuite ()

Returns the cipher suite in use on this connection.

Returns
String the cipher suite

Throws
IllegalStateException if this method is called before the connection has been established.

getDefaultHostnameVerifier

Added in API level 1
public static HostnameVerifier getDefaultHostnameVerifier ()

Gets the default HostnameVerifier that is inherited by new instances of this class.

Returns
HostnameVerifier the default host name verifier

getDefaultSSLSocketFactory

Added in API level 1
public static SSLSocketFactory getDefaultSSLSocketFactory ()

Gets the default static SSLSocketFactory that is inherited by new instances of this class.

The socket factories are used when creating sockets for secure https URL connections.

Returns
SSLSocketFactory the default SSLSocketFactory

getHostnameVerifier

Added in API level 1
public HostnameVerifier getHostnameVerifier ()

Gets the HostnameVerifier in place on this instance.

Returns
HostnameVerifier the host name verifier

getLocalCertificates

Added in API level 1
public abstract Certificate[] getLocalCertificates ()

Returns the certificate(s) that were sent to the server during handshaking.

Note: This method is useful only when using certificate-based cipher suites.

When multiple certificates are available for use in a handshake, the implementation chooses what it considers the "best" certificate chain available, and transmits that to the other side. This method allows the caller to know which certificate chain was actually sent.

Returns
Certificate[] an ordered array of certificates, with the client's own certificate first followed by any certificate authorities. If no certificates were sent, then null is returned.

Throws
IllegalStateException if this method is called before the connection has been established.

getLocalPrincipal

Added in API level 1
public Principal getLocalPrincipal ()

Returns the principal that was sent to the server during handshaking.

Note: Subclasses should override this method. If not overridden, it will default to returning the X500Principal of the end-entity certificate that was sent to the server for certificate-based ciphersuites or, return null for non-certificate based ciphersuites, such as Kerberos.

Returns
Principal the principal sent to the server. Returns an X500Principal of the end-entity certificate for X509-based cipher suites, and KerberosPrincipal for Kerberos cipher suites. If no principal was sent, then null is returned.

Throws
IllegalStateException if this method is called before the connection has been established.

getPeerPrincipal

Added in API level 1
public Principal getPeerPrincipal ()

Returns the server's principal which was established as part of defining the session.

Note: Subclasses should override this method. If not overridden, it will default to returning the X500Principal of the server's end-entity certificate for certificate-based ciphersuites, or throw an SSLPeerUnverifiedException for non-certificate based ciphersuites, such as Kerberos.

Returns
Principal the server's principal. Returns an X500Principal of the end-entity certiticate for X509-based cipher suites, and KerberosPrincipal for Kerberos cipher suites.

Throws
SSLPeerUnverifiedException if the peer was not verified
IllegalStateException if this method is called before the connection has been established.

getSSLSocketFactory

Added in API level 1
public SSLSocketFactory getSSLSocketFactory ()

Gets the SSL socket factory to be used when creating sockets for secure https URL connections.

Returns
SSLSocketFactory the SSLSocketFactory

getServerCertificates

Added in API level 1
public abstract Certificate[] getServerCertificates ()

Returns the server's certificate chain which was established as part of defining the session.

Note: This method can be used only when using certificate-based cipher suites; using it with non-certificate-based cipher suites, such as Kerberos, will throw an SSLPeerUnverifiedException.

Returns
Certificate[] an ordered array of server certificates, with the peer's own certificate first followed by any certificate authorities.

Throws
SSLPeerUnverifiedException if the peer is not verified.
IllegalStateException if this method is called before the connection has been established.

See also:

setDefaultHostnameVerifier

Added in API level 1
public static void setDefaultHostnameVerifier (HostnameVerifier v)

Sets the default HostnameVerifier inherited by a new instance of this class.

Developers are strongly discouraged from changing the default HostnameVerifier as getDefaultHostnameVerifier() is used by several classes for hostname verification on Android.

User Effect
Android's default TrustManager, as used with Android's default SSLContext, SSLSocketFactory and SSLSocket implementations. The HostnameVerifier is used to verify the peer's certificate hostname after connecting if SSLParameters.setEndpointIdentificationAlgorithm("HTTPS") has been called. Instances use the current default HostnameVerifier at verification time.
SSLCertificateSocketFactory The current default HostnameVerifier is used from various createSocket methods. See SSLCertificateSocketFactory for details; for example SSLCertificateSocketFactory.createSocket(String, int).
Android's default HttpsURLConnection implementation. The HostnameVerifier is used after a successful TLS handshake to verify the URI host against the TLS session server. Instances use the default HostnameVerifier set when they were created unless overridden with setHostnameVerifier(javax.net.ssl.HostnameVerifier). Android's HttpsURLConnection relies on the HostnameVerifier for the entire hostname verification step.

If this method is not called, the default HostnameVerifier will check the hostname according to RFC 2818.

Parameters
v HostnameVerifier: the default host name verifier

Throws
IllegalArgumentException if the HostnameVerifier parameter is null.
SecurityException if a security manager exists and its checkPermission method does not allow SSLPermission("setHostnameVerifier")

setDefaultSSLSocketFactory

Added in API level 1
public static void setDefaultSSLSocketFactory (SSLSocketFactory sf)

Sets the default SSLSocketFactory inherited by new instances of this class.

The socket factories are used when creating sockets for secure https URL connections.

Parameters
sf SSLSocketFactory: the default SSL socket factory

Throws
IllegalArgumentException if the SSLSocketFactory parameter is null.
SecurityException if a security manager exists and its checkSetFactory method does not allow a socket factory to be specified.

setHostnameVerifier

Added in API level 1
public void setHostnameVerifier (HostnameVerifier v)

Sets the HostnameVerifier for this instance.

New instances of this class inherit the default static hostname verifier set by setDefaultHostnameVerifier. Calls to this method replace this object's HostnameVerifier.

Android's HttpsURLConnection relies on the HostnameVerifier for the entire hostname verification step.

Parameters
v HostnameVerifier: the host name verifier

Throws
IllegalArgumentException if the HostnameVerifier parameter is null.

setSSLSocketFactory

Added in API level 1
public void setSSLSocketFactory (SSLSocketFactory sf)

Sets the SSLSocketFactory to be used when this instance creates sockets for secure https URL connections.

New instances of this class inherit the default static SSLSocketFactory set by setDefaultSSLSocketFactory. Calls to this method replace this object's SSLSocketFactory.

Parameters
sf SSLSocketFactory: the SSL socket factory

Throws
IllegalArgumentException if the SSLSocketFactory parameter is null.
SecurityException if a security manager exists and its checkSetFactory method does not allow a socket factory to be specified.