This class may be used in the same way as {@link * HttpURLConnection}, and it will transparently negotiate the SSL * connection. * * @author Casey Marshall (rsdio@metastatic.org) */ public abstract class HttpsURLConnection extends HttpURLConnection { // Fields. // ------------------------------------------------------------------ /** * The default verifier. * This is lazily initialized as required. * @see #getDefaultHostnameVerifier */ private static HostnameVerifier defaultVerifier; /** * The default factory. * This is lazily initialized as required. * @see #getDefaultSSLSocketFactory */ private static SSLSocketFactory defaultFactory; /** * The hostname verifier used for this connection. */ protected HostnameVerifier hostnameVerifier; /** * This connection's socket factory. */ private SSLSocketFactory factory; // Constructor. // ------------------------------------------------------------------ /** * Creates a new HTTPS URL connection. * * @param url The URL of the connection being established. * @specnote This was marked as throwing IOException in 1.4, * but this was removed in 1.5. */ protected HttpsURLConnection(URL url) { super(url); } // Class methods. // ------------------------------------------------------------------ /** * Returns the default hostname verifier used in all new * connections. * If the default verifier has not been set, a new default one will be * provided by this method. * * @return The default hostname verifier. */ public static synchronized HostnameVerifier getDefaultHostnameVerifier() { if (defaultVerifier == null) { defaultVerifier = new TrivialHostnameVerifier(); } return defaultVerifier; } /** * Sets the default hostname verifier to be used in all new * connections. * * @param newDefault The new default hostname verifier. * @throws IllegalArgumentException If newDefault is null. * @throws SecurityException If there is a security manager * currently installed and the caller does not have the {@link * SSLPermission} "setHostnameVerifier". */ public static void setDefaultHostnameVerifier(HostnameVerifier newDefault) { if (newDefault == null) throw new IllegalArgumentException("default verifier cannot be null"); SecurityManager sm = System.getSecurityManager(); if (sm != null) sm.checkPermission(new SSLPermission("setHostnameVerifier")); synchronized (HttpsURLConnection.class) { defaultVerifier = newDefault; } } /** * Returns the default SSL socket factory used in all new * connections. * If the default SSL socket factory has not been set, a new default one * will be provided by this method. * * @return The default SSL socket factory. */ public static synchronized SSLSocketFactory getDefaultSSLSocketFactory() { if (defaultFactory == null) { try { defaultFactory = (SSLSocketFactory) SSLSocketFactory.getDefault(); } catch (Throwable t) { t.printStackTrace(); } } return defaultFactory; } /** * Sets the default SSL socket factory to be used in all new * connections. * * @param newDefault The new socket factory. * @throws IllegalArgumentException If newDefault is null. * @throws SecurityException If there is a security manager * installed and a call to {@link * SecurityManager#checkSetFactory()} fails. */ public static void setDefaultSSLSocketFactory(SSLSocketFactory newDefault) { if (newDefault == null) throw new IllegalArgumentException("default factory cannot be null"); SecurityManager sm = System.getSecurityManager(); if (sm != null) sm.checkSetFactory(); synchronized (HttpsURLConnection.class) { defaultFactory = newDefault; } } // Instance methods. // ------------------------------------------------------------------ /** * Returns the current hostname verifier for this instance. * * @return The hostname verifier. */ public HostnameVerifier getHostnameVerifier() { if (hostnameVerifier == null) { hostnameVerifier = getDefaultHostnameVerifier(); } return hostnameVerifier; } /** * Sets the hostname verifier for this instance. * * @param hostnameVerifier The new verifier. * @throws IllegalArgumentException If hostnameVerifier is * null. */ public void setHostnameVerifier(HostnameVerifier hostnameVerifier) { if (hostnameVerifier == null) throw new IllegalArgumentException("verifier cannot be null"); this.hostnameVerifier = hostnameVerifier; } /** * Returns the current SSL socket factory for this instance. * * @return The current SSL socket factory. */ public SSLSocketFactory getSSLSocketFactory() { if (factory == null) { factory = getDefaultSSLSocketFactory(); } return factory; } /** * Sets the SSL socket factory for this instance. * * @param factory The new factory. * @throws IllegalArgumentException If factory is null. */ public void setSSLSocketFactory(SSLSocketFactory factory) { if (factory == null) throw new IllegalArgumentException("factory cannot be null"); this.factory = factory; } /** * Returns the local principal for this connection. * *
The default implementation will return the {@link
* javax.security.x500.X500Principal} for the end entity certificate
* in the local certificate chain if those certificates are of type
* {@link java.security.cert.X509Certificate}. Otherwise, this
* method returns null.
*
* @return The local principal.
* @since 1.5
*/
public Principal getLocalPrincipal ()
{
Certificate[] c = getLocalCertificates ();
if (c != null && c.length > 0 && (c[0] instanceof X509Certificate))
return ((X509Certificate) c[0]).getSubjectX500Principal ();
return null;
}
/**
* Returns the remote peer's principal for this connection.
*
*
The default implementation will return the {@link
* javax.security.x500.X500Principal} for the end entity certificate
* in the remote peer's certificate chain if those certificates are
* of type {@link java.security.cert.X509Certificate}. Otherwise,
* this method returns null.
*
* @return The remote principal.
* @throws SSLPeerUnverifiedException If the remote peer has not
* been verified.
* @since 1.5
*/
public Principal getPeerPrincipal () throws SSLPeerUnverifiedException
{
Certificate[] c = getServerCertificates ();
if (c != null && c.length > 0 && (c[0] instanceof X509Certificate))
return ((X509Certificate) c[0]).getSubjectX500Principal ();
return null;
}
// Abstract methods.
// -------------------------------------------------------------------
/**
* Returns the cipher name negotiated for this connection.
*
* @return The cipher name.
* @throws IllegalStateException If the connection has not yet been
* established.
*/
public abstract String getCipherSuite();
/**
* Returns the certificates used on the local side in this
* connection.
*
* @return The local certificates.
* @throws IllegalStateException If the connection has not yet been
* established.
*/
public abstract Certificate[] getLocalCertificates();
/**
* Returns the certificates sent by the other party.
*
* @return The peer's certificates.
* @throws IllegalStateException If the connection has not yet been
* established.
* @throws SSLPeerUnverifiedException If the peer could not be
* verified.
*/
public abstract Certificate[] getServerCertificates() throws SSLPeerUnverifiedException;
}