Source for javax.net.ssl.HttpsURLConnection

   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., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 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: }