libjava/javax/net/ssl/HttpsURLConnection.java

   1 /* HttpsURLConnection.java -- an HTTPS connection.
   2    Copyright (C) 2004 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package javax.net.ssl;
  40
  41 import java.io.IOException;
  42 import java.net.HttpURLConnection;
  43 import java.net.URL;
  44 import java.security.cert.Certificate;
  45
  46 /**
  47  * A URL connection that connects via the <i>Secure Socket Layer</i>
  48  * (<b>SSL</b>) for HTTPS connections.
  49  *
  50  * <p>This class may be used in the same way as {@link
  51  * HttpURLConnection}, and it will transparently negotiate the SSL
  52  * connection.
  53  *
  54  * @author Casey Marshall (rsdio@metastatic.org)
  55  */
  56 public abstract class HttpsURLConnection extends HttpURLConnection
  57 {
  58
  59   // Fields.
  60   // ------------------------------------------------------------------
  61
  62   /**
  63    * The default verifier.
  64    * This is lazily initialized as required.
  65    * @see #getDefaultHostnameVerifier
  66    */
  67   private static HostnameVerifier defaultVerifier;
  68
  69   /**
  70    * The default factory.
  71    * This is lazily initialized as required.
  72    * @see #getDefaultSSLSocketFactory
  73    */
  74   private static SSLSocketFactory defaultFactory;
  75
  76   /**
  77    * The hostname verifier used for this connection.
  78    */
  79   protected HostnameVerifier hostnameVerifier;
  80
  81   /**
  82    * This connection's socket factory.
  83    */
  84   private SSLSocketFactory factory;
  85
  86   // Constructor.
  87   // ------------------------------------------------------------------
  88
  89   /**
  90    * Creates a new HTTPS URL connection.
  91    *
  92    * @param url The URL of the connection being established.
  93    * @throws IOException If the connection cannot be established.
  94    */
  95   protected HttpsURLConnection(URL url) throws IOException
  96   {
  97     super(url);
  98   }
  99
 100   // Class methods.
 101   // ------------------------------------------------------------------
 102
 103   /**
 104    * Returns the default hostname verifier used in all new
 105    * connections.
 106    * If the default verifier has not been set, a new default one will be
 107    * provided by this method.
 108    *
 109    * @return The default hostname verifier.
 110    */
 111   public static synchronized HostnameVerifier getDefaultHostnameVerifier()
 112   {
 113     if (defaultVerifier == null)
 114       {
 115         defaultVerifier = new TrivialHostnameVerifier();
 116       }
 117     return defaultVerifier;
 118   }
 119
 120   /**
 121    * Sets the default hostname verifier to be used in all new
 122    * connections.
 123    *
 124    * @param newDefault The new default hostname verifier.
 125    * @throws IllegalArgumentException If <i>newDefault</i> is null.
 126    * @throws SecurityException If there is a security manager
 127    *   currently installed and the caller does not have the {@link
 128    *   SSLPermission} "setHostnameVerifier".
 129    */
 130   public static void setDefaultHostnameVerifier(HostnameVerifier newDefault)
 131   {
 132     if (newDefault == null)
 133       throw new IllegalArgumentException("default verifier cannot be null");
 134     SecurityManager sm = System.getSecurityManager();
 135     if (sm != null)
 136       sm.checkPermission(new SSLPermission("setHostnameVerifier"));
 137     synchronized (HttpsURLConnection.class)
 138       {
 139         defaultVerifier = newDefault;
 140       }
 141   }
 142
 143   /**
 144    * Returns the default SSL socket factory used in all new
 145    * connections.
 146    * If the default SSL socket factory has not been set, a new default one
 147    * will be provided by this method.
 148    *
 149    * @return The default SSL socket factory.
 150    */
 151   public static synchronized SSLSocketFactory getDefaultSSLSocketFactory()
 152   {
 153     if (defaultFactory == null)
 154       {
 155         try
 156           {
 157             defaultFactory = (SSLSocketFactory) SSLSocketFactory.getDefault();
 158           }
 159         catch (Throwable t)
 160           {
 161             t.printStackTrace();
 162           }
 163       }
 164     return defaultFactory;
 165   }
 166
 167   /**
 168    * Sets the default SSL socket factory to be used in all new
 169    * connections.
 170    *
 171    * @param newDefault The new socket factory.
 172    * @throws IllegalArgumentException If <i>newDefault</i> is null.
 173    * @throws SecurityException If there is a security manager
 174    *   installed and a call to {@link
 175    *   SecurityManager#checkSetFactory()} fails.
 176    */
 177   public static void setDefaultSSLSocketFactory(SSLSocketFactory newDefault)
 178   {
 179     if (newDefault == null)
 180       throw new IllegalArgumentException("default factory cannot be null");
 181     SecurityManager sm = System.getSecurityManager();
 182     if (sm != null)
 183       sm.checkSetFactory();
 184     synchronized (HttpsURLConnection.class)
 185       {
 186         defaultFactory = newDefault;
 187       }
 188   }
 189
 190   // Instance methods.
 191   // ------------------------------------------------------------------
 192
 193   /**
 194    * Returns the current hostname verifier for this instance.
 195    *
 196    * @return The hostname verifier.
 197    */
 198   public HostnameVerifier getHostnameVerifier()
 199   {
 200     if (hostnameVerifier == null)
 201       {
 202         hostnameVerifier = getDefaultHostnameVerifier();
 203       }
 204     return hostnameVerifier;
 205   }
 206
 207   /**
 208    * Sets the hostname verifier for this instance.
 209    *
 210    * @param hostnameVerifier The new verifier.
 211    * @throws IllegalArgumentException If <i>hostnameVerifier</i> is
 212    *   null.
 213    */
 214   public void setHostnameVerifier(HostnameVerifier hostnameVerifier)
 215   {
 216     if (hostnameVerifier == null)
 217       throw new IllegalArgumentException("verifier cannot be null");
 218     this.hostnameVerifier = hostnameVerifier;
 219   }
 220
 221   /**
 222    * Returns the current SSL socket factory for this instance.
 223    *
 224    * @return The current SSL socket factory.
 225    */
 226   public SSLSocketFactory getSSLSocketFactory()
 227   {
 228     if (factory == null)
 229       {
 230         factory = getDefaultSSLSocketFactory();
 231       }
 232     return factory;
 233   }
 234
 235   /**
 236    * Sets the SSL socket factory for this instance.
 237    *
 238    * @param factory The new factory.
 239    * @throws IllegalArgumentException If <i>factory</i> is null.
 240    */
 241   public void setSSLSocketFactory(SSLSocketFactory factory)
 242   {
 243     if (factory == null)
 244       throw new IllegalArgumentException("factory cannot be null");
 245     this.factory = factory;
 246   }
 247
 248   // Abstract methods.
 249   // -------------------------------------------------------------------
 250
 251   /**
 252    * Returns the cipher name negotiated for this connection.
 253    *
 254    * @return The cipher name.
 255    * @throws IllegalStateException If the connection has not yet been
 256    *   established.
 257    */
 258   public abstract String getCipherSuite();
 259
 260   /**
 261    * Returns the certificates used on the local side in this
 262    * connection.
 263    *
 264    * @return The local certificates.
 265    * @throws IllegalStateException If the connection has not yet been
 266    *  established.
 267    */
 268   public abstract Certificate[] getLocalCertificates();
 269
 270   /**
 271    * Returns the certificates sent by the other party.
 272    *
 273    * @return The peer's certificates.
 274    * @throws IllegalStateException If the connection has not yet been
 275    *   established.
 276    * @throws SSLPeerUnverifiedException If the peer could not be
 277    *   verified.
 278    */
 279   public abstract Certificate[] getServerCertificates() throws SSLPeerUnverifiedException;
 280 }