1 /*
2 * Copyright 1999-2005 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package javax.net.ssl;
27
28 import java.net.URL;
29 import java.net.HttpURLConnection;
30 import java.security.Principal;
31 import java.security.cert.X509Certificate;
32 import javax.security.auth.x500.X500Principal;
33
34 /**
35 * <code>HttpsURLConnection</code> extends <code>HttpURLConnection</code>
36 * with support for https-specific features.
37 * <P>
38 * See <A HREF="http://www.w3.org/pub/WWW/Protocols/">
39 * http://www.w3.org/pub/WWW/Protocols/</A> and
40 * <A HREF="http://www.ietf.org/"> RFC 2818 </A>
41 * for more details on the
42 * https specification.
43 * <P>
44 * This class uses <code>HostnameVerifier</code> and
45 * <code>SSLSocketFactory</code>.
46 * There are default implementations defined for both classes.
47 * However, the implementations can be replaced on a per-class (static) or
48 * per-instance basis. All new <code>HttpsURLConnection</code>s instances
49 * will be assigned
50 * the "default" static values at instance creation, but they can be overriden
51 * by calling the appropriate per-instance set method(s) before
52 * <code>connect</code>ing.
53 *
54 * @since 1.4
55 */
56 abstract public
57 class HttpsURLConnection extends HttpURLConnection
58 {
59 /**
60 * Creates an <code>HttpsURLConnection</code> using the
61 * URL specified.
62 *
63 * @param url the URL
64 */
65 protected HttpsURLConnection(URL url) {
66 super(url);
67 }
68
69 /**
70 * Returns the cipher suite in use on this connection.
71 *
72 * @return the cipher suite
73 * @throws IllegalStateException if this method is called before
74 * the connection has been established.
75 */
76 public abstract String getCipherSuite();
77
78 /**
79 * Returns the certificate(s) that were sent to the server during
80 * handshaking.
81 * <P>
82 * Note: This method is useful only when using certificate-based
83 * cipher suites.
84 * <P>
85 * When multiple certificates are available for use in a
86 * handshake, the implementation chooses what it considers the
87 * "best" certificate chain available, and transmits that to
88 * the other side. This method allows the caller to know
89 * which certificate chain was actually sent.
90 *
91 * @return an ordered array of certificates,
92 * with the client's own certificate first followed by any
93 * certificate authorities. If no certificates were sent,
94 * then null is returned.
95 * @throws IllegalStateException if this method is called before
96 * the connection has been established.
97 * @see #getLocalPrincipal()
98 */
99 public abstract java.security.cert.Certificate [] getLocalCertificates();
100
101 /**
102 * Returns the server's certificate chain which was established
103 * as part of defining the session.
104 * <P>
105 * Note: This method can be used only when using certificate-based
106 * cipher suites; using it with non-certificate-based cipher suites,
107 * such as Kerberos, will throw an SSLPeerUnverifiedException.
108 *
109 * @return an ordered array of server certificates,
110 * with the peer's own certificate first followed by
111 * any certificate authorities.
112 * @throws SSLPeerUnverifiedException if the peer is not verified.
113 * @throws IllegalStateException if this method is called before
114 * the connection has been established.
115 * @see #getPeerPrincipal()
116 */
117 public abstract java.security.cert.Certificate [] getServerCertificates()
118 throws SSLPeerUnverifiedException;
119
120 /**
121 * Returns the server's principal which was established as part of
122 * defining the session.
123 * <P>
124 * Note: Subclasses should override this method. If not overridden, it
125 * will default to returning the X500Principal of the server's end-entity
126 * certificate for certificate-based ciphersuites, or throw an
127 * SSLPeerUnverifiedException for non-certificate based ciphersuites,
128 * such as Kerberos.
129 *
130 * @return the server's principal. Returns an X500Principal of the
131 * end-entity certiticate for X509-based cipher suites, and
132 * KerberosPrincipal for Kerberos cipher suites.
133 *
134 * @throws SSLPeerUnverifiedException if the peer was not verified
135 * @throws IllegalStateException if this method is called before
136 * the connection has been established.
137 *
138 * @see #getServerCertificates()
139 * @see #getLocalPrincipal()
140 *
141 * @since 1.5
142 */
143 public Principal getPeerPrincipal()
144 throws SSLPeerUnverifiedException {
145
146 java.security.cert.Certificate[] certs = getServerCertificates();
147 return ((X500Principal)
148 ((X509Certificate)certs[0]).getSubjectX500Principal());
149 }
150
151 /**
152 * Returns the principal that was sent to the server during handshaking.
153 * <P>
154 * Note: Subclasses should override this method. If not overridden, it
155 * will default to returning the X500Principal of the end-entity certificate
156 * that was sent to the server for certificate-based ciphersuites or,
157 * return null for non-certificate based ciphersuites, such as Kerberos.
158 *
159 * @return the principal sent to the server. Returns an X500Principal
160 * of the end-entity certificate for X509-based cipher suites, and
161 * KerberosPrincipal for Kerberos cipher suites. If no principal was
162 * sent, then null is returned.
163 *
164 * @throws IllegalStateException if this method is called before
165 * the connection has been established.
166 *
167 * @see #getLocalCertificates()
168 * @see #getPeerPrincipal()
169 *
170 * @since 1.5
171 */
172 public Principal getLocalPrincipal() {
173
174 java.security.cert.Certificate[] certs = getLocalCertificates();
175 if (certs != null) {
176 return ((X500Principal)
177 ((X509Certificate)certs[0]).getSubjectX500Principal());
178 } else {
179 return null;
180 }
181 }
182
183 /**
184 * <code>HostnameVerifier</code> provides a callback mechanism so that
185 * implementers of this interface can supply a policy for
186 * handling the case where the host to connect to and
187 * the server name from the certificate mismatch.
188 * <p>
189 * The default implementation will deny such connections.
190 */
191 private static HostnameVerifier defaultHostnameVerifier;
192
193 /**
194 * Initialize the default <code>HostnameVerifier</code>.
195 */
196 static {
197 try {
198 defaultHostnameVerifier =
199 new sun.net.www.protocol.https.DefaultHostnameVerifier();
200 } catch (NoClassDefFoundError e) {
201 defaultHostnameVerifier = new DefaultHostnameVerifier();
202 }
203 }
204
205 /*
206 * The initial default <code>HostnameVerifier</code>. Should be
207 * updated for another other type of <code>HostnameVerifier</code>
208 * that are created.
209 */
210 private static class DefaultHostnameVerifier
211 implements HostnameVerifier {
212 public boolean verify(String hostname, SSLSession session) {
213 return false;
214 }
215 }
216
217 /**
218 * The <code>hostnameVerifier</code> for this object.
219 */
220 protected HostnameVerifier hostnameVerifier = defaultHostnameVerifier;
221
222 /**
223 * Sets the default <code>HostnameVerifier</code> inherited by a
224 * new instance of this class.
225 * <P>
226 * If this method is not called, the default
227 * <code>HostnameVerifier</code> assumes the connection should not
228 * be permitted.
229 *
230 * @param v the default host name verifier
231 * @throws IllegalArgumentException if the <code>HostnameVerifier</code>
232 * parameter is null.
233 * @throws SecurityException if a security manager exists and its
234 * <code>checkPermission</code> method does not allow
235 * <code>SSLPermission("setHostnameVerifier")</code>
236 * @see #getDefaultHostnameVerifier()
237 */
238 public static void setDefaultHostnameVerifier(HostnameVerifier v) {
239 if (v == null) {
240 throw new IllegalArgumentException(
241 "no default HostnameVerifier specified");
242 }
243
244 SecurityManager sm = System.getSecurityManager();
245 if (sm != null) {
246 sm.checkPermission(new SSLPermission("setHostnameVerifier"));
247 }
248 defaultHostnameVerifier = v;
249 }
250
251 /**
252 * Gets the default <code>HostnameVerifier</code> that is inherited
253 * by new instances of this class.
254 *
255 * @return the default host name verifier
256 * @see #setDefaultHostnameVerifier(HostnameVerifier)
257 */
258 public static HostnameVerifier getDefaultHostnameVerifier() {
259 return defaultHostnameVerifier;
260 }
261
262 /**
263 * Sets the <code>HostnameVerifier</code> for this instance.
264 * <P>
265 * New instances of this class inherit the default static hostname
266 * verifier set by {@link #setDefaultHostnameVerifier(HostnameVerifier)
267 * setDefaultHostnameVerifier}. Calls to this method replace
268 * this object's <code>HostnameVerifier</code>.
269 *
270 * @param v the host name verifier
271 * @throws IllegalArgumentException if the <code>HostnameVerifier</code>
272 * parameter is null.
273 * @see #getHostnameVerifier()
274 * @see #setDefaultHostnameVerifier(HostnameVerifier)
275 */
276 public void setHostnameVerifier(HostnameVerifier v) {
277 if (v == null) {
278 throw new IllegalArgumentException(
279 "no HostnameVerifier specified");
280 }
281
282 hostnameVerifier = v;
283 }
284
285 /**
286 * Gets the <code>HostnameVerifier</code> in place on this instance.
287 *
288 * @return the host name verifier
289 * @see #setHostnameVerifier(HostnameVerifier)
290 * @see #setDefaultHostnameVerifier(HostnameVerifier)
291 */
292 public HostnameVerifier getHostnameVerifier() {
293 return hostnameVerifier;
294 }
295
296 private static SSLSocketFactory defaultSSLSocketFactory = null;
297
298 /**
299 * The <code>SSLSocketFactory</code> inherited when an instance
300 * of this class is created.
301 */
302 private SSLSocketFactory sslSocketFactory = getDefaultSSLSocketFactory();
303
304 /**
305 * Sets the default <code>SSLSocketFactory</code> inherited by new
306 * instances of this class.
307 * <P>
308 * The socket factories are used when creating sockets for secure
309 * https URL connections.
310 *
311 * @param sf the default SSL socket factory
312 * @throws IllegalArgumentException if the SSLSocketFactory
313 * parameter is null.
314 * @throws SecurityException if a security manager exists and its
315 * <code>checkSetFactory</code> method does not allow
316 * a socket factory to be specified.
317 * @see #getDefaultSSLSocketFactory()
318 */
319 public static void setDefaultSSLSocketFactory(SSLSocketFactory sf) {
320 if (sf == null) {
321 throw new IllegalArgumentException(
322 "no default SSLSocketFactory specified");
323 }
324
325 SecurityManager sm = System.getSecurityManager();
326 if (sm != null) {
327 sm.checkSetFactory();
328 }
329 defaultSSLSocketFactory = sf;
330 }
331
332 /**
333 * Gets the default static <code>SSLSocketFactory</code> that is
334 * inherited by new instances of this class.
335 * <P>
336 * The socket factories are used when creating sockets for secure
337 * https URL connections.
338 *
339 * @return the default <code>SSLSocketFactory</code>
340 * @see #setDefaultSSLSocketFactory(SSLSocketFactory)
341 */
342 public static SSLSocketFactory getDefaultSSLSocketFactory() {
343 if (defaultSSLSocketFactory == null) {
344 defaultSSLSocketFactory =
345 (SSLSocketFactory)SSLSocketFactory.getDefault();
346 }
347 return defaultSSLSocketFactory;
348 }
349
350 /**
351 * Sets the <code>SSLSocketFactory</code> to be used when this instance
352 * creates sockets for secure https URL connections.
353 * <P>
354 * New instances of this class inherit the default static
355 * <code>SSLSocketFactory</code> set by
356 * {@link #setDefaultSSLSocketFactory(SSLSocketFactory)
357 * setDefaultSSLSocketFactory}. Calls to this method replace
358 * this object's <code>SSLSocketFactory</code>.
359 *
360 * @param sf the SSL socket factory
361 * @throws IllegalArgumentException if the <code>SSLSocketFactory</code>
362 * parameter is null.
363 * @see #getSSLSocketFactory()
364 */
365 public void setSSLSocketFactory(SSLSocketFactory sf) {
366 if (sf == null) {
367 throw new IllegalArgumentException(
368 "no SSLSocketFactory specified");
369 }
370
371 sslSocketFactory = sf;
372 }
373
374 /**
375 * Gets the SSL socket factory to be used when creating sockets
376 * for secure https URL connections.
377 *
378 * @return the <code>SSLSocketFactory</code>
379 * @see #setSSLSocketFactory(SSLSocketFactory)
380 */
381 public SSLSocketFactory getSSLSocketFactory() {
382 return sslSocketFactory;
383 }
384 }
Save This Page