1 /*
2 * Copyright (c) 1999, 2010, Oracle and/or its affiliates. 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. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * 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 new DefaultHostnameVerifier();
193
194 /*
195 * The initial default <code>HostnameVerifier</code>. Should be
196 * updated for another other type of <code>HostnameVerifier</code>
197 * that are created.
198 */
199 private static class DefaultHostnameVerifier
200 implements HostnameVerifier {
201 public boolean verify(String hostname, SSLSession session) {
202 return false;
203 }
204 }
205
206 /**
207 * The <code>hostnameVerifier</code> for this object.
208 */
209 protected HostnameVerifier hostnameVerifier = defaultHostnameVerifier;
210
211 /**
212 * Sets the default <code>HostnameVerifier</code> inherited by a
213 * new instance of this class.
214 * <P>
215 * If this method is not called, the default
216 * <code>HostnameVerifier</code> assumes the connection should not
217 * be permitted.
218 *
219 * @param v the default host name verifier
220 * @throws IllegalArgumentException if the <code>HostnameVerifier</code>
221 * parameter is null.
222 * @throws SecurityException if a security manager exists and its
223 * <code>checkPermission</code> method does not allow
224 * <code>SSLPermission("setHostnameVerifier")</code>
225 * @see #getDefaultHostnameVerifier()
226 */
227 public static void setDefaultHostnameVerifier(HostnameVerifier v) {
228 if (v == null) {
229 throw new IllegalArgumentException(
230 "no default HostnameVerifier specified");
231 }
232
233 SecurityManager sm = System.getSecurityManager();
234 if (sm != null) {
235 sm.checkPermission(new SSLPermission("setHostnameVerifier"));
236 }
237 defaultHostnameVerifier = v;
238 }
239
240 /**
241 * Gets the default <code>HostnameVerifier</code> that is inherited
242 * by new instances of this class.
243 *
244 * @return the default host name verifier
245 * @see #setDefaultHostnameVerifier(HostnameVerifier)
246 */
247 public static HostnameVerifier getDefaultHostnameVerifier() {
248 return defaultHostnameVerifier;
249 }
250
251 /**
252 * Sets the <code>HostnameVerifier</code> for this instance.
253 * <P>
254 * New instances of this class inherit the default static hostname
255 * verifier set by {@link #setDefaultHostnameVerifier(HostnameVerifier)
256 * setDefaultHostnameVerifier}. Calls to this method replace
257 * this object's <code>HostnameVerifier</code>.
258 *
259 * @param v the host name verifier
260 * @throws IllegalArgumentException if the <code>HostnameVerifier</code>
261 * parameter is null.
262 * @see #getHostnameVerifier()
263 * @see #setDefaultHostnameVerifier(HostnameVerifier)
264 */
265 public void setHostnameVerifier(HostnameVerifier v) {
266 if (v == null) {
267 throw new IllegalArgumentException(
268 "no HostnameVerifier specified");
269 }
270
271 hostnameVerifier = v;
272 }
273
274 /**
275 * Gets the <code>HostnameVerifier</code> in place on this instance.
276 *
277 * @return the host name verifier
278 * @see #setHostnameVerifier(HostnameVerifier)
279 * @see #setDefaultHostnameVerifier(HostnameVerifier)
280 */
281 public HostnameVerifier getHostnameVerifier() {
282 return hostnameVerifier;
283 }
284
285 private static SSLSocketFactory defaultSSLSocketFactory = null;
286
287 /**
288 * The <code>SSLSocketFactory</code> inherited when an instance
289 * of this class is created.
290 */
291 private SSLSocketFactory sslSocketFactory = getDefaultSSLSocketFactory();
292
293 /**
294 * Sets the default <code>SSLSocketFactory</code> inherited by new
295 * instances of this class.
296 * <P>
297 * The socket factories are used when creating sockets for secure
298 * https URL connections.
299 *
300 * @param sf the default SSL socket factory
301 * @throws IllegalArgumentException if the SSLSocketFactory
302 * parameter is null.
303 * @throws SecurityException if a security manager exists and its
304 * <code>checkSetFactory</code> method does not allow
305 * a socket factory to be specified.
306 * @see #getDefaultSSLSocketFactory()
307 */
308 public static void setDefaultSSLSocketFactory(SSLSocketFactory sf) {
309 if (sf == null) {
310 throw new IllegalArgumentException(
311 "no default SSLSocketFactory specified");
312 }
313
314 SecurityManager sm = System.getSecurityManager();
315 if (sm != null) {
316 sm.checkSetFactory();
317 }
318 defaultSSLSocketFactory = sf;
319 }
320
321 /**
322 * Gets the default static <code>SSLSocketFactory</code> that is
323 * inherited by new instances of this class.
324 * <P>
325 * The socket factories are used when creating sockets for secure
326 * https URL connections.
327 *
328 * @return the default <code>SSLSocketFactory</code>
329 * @see #setDefaultSSLSocketFactory(SSLSocketFactory)
330 */
331 public static SSLSocketFactory getDefaultSSLSocketFactory() {
332 if (defaultSSLSocketFactory == null) {
333 defaultSSLSocketFactory =
334 (SSLSocketFactory)SSLSocketFactory.getDefault();
335 }
336 return defaultSSLSocketFactory;
337 }
338
339 /**
340 * Sets the <code>SSLSocketFactory</code> to be used when this instance
341 * creates sockets for secure https URL connections.
342 * <P>
343 * New instances of this class inherit the default static
344 * <code>SSLSocketFactory</code> set by
345 * {@link #setDefaultSSLSocketFactory(SSLSocketFactory)
346 * setDefaultSSLSocketFactory}. Calls to this method replace
347 * this object's <code>SSLSocketFactory</code>.
348 *
349 * @param sf the SSL socket factory
350 * @throws IllegalArgumentException if the <code>SSLSocketFactory</code>
351 * parameter is null.
352 * @see #getSSLSocketFactory()
353 */
354 public void setSSLSocketFactory(SSLSocketFactory sf) {
355 if (sf == null) {
356 throw new IllegalArgumentException(
357 "no SSLSocketFactory specified");
358 }
359
360 sslSocketFactory = sf;
361 }
362
363 /**
364 * Gets the SSL socket factory to be used when creating sockets
365 * for secure https URL connections.
366 *
367 * @return the <code>SSLSocketFactory</code>
368 * @see #setSSLSocketFactory(SSLSocketFactory)
369 */
370 public SSLSocketFactory getSSLSocketFactory() {
371 return sslSocketFactory;
372 }
373 }