1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package javax.net.ssl; 19 20 import java.net.HttpURLConnection; 21 import java.net.URL; 22 import java.security.Principal; 23 import java.security.cert.Certificate; 24 import java.security.cert.X509Certificate; 25 26 /** 27 * This abstract subclass of {@code HttpURLConnection} defines methods for 28 * managing HTTPS connections according to the description given by RFC 2818. 29 */ 30 public abstract class HttpsURLConnection extends HttpURLConnection { 31 32 private static HostnameVerifier defaultHostnameVerifier = new DefaultHostnameVerifier(); 33 34 private static SSLSocketFactory defaultSSLSocketFactory = (SSLSocketFactory) SSLSocketFactory 35 .getDefault(); 36 37 /** 38 * Sets the default hostname verifier to be used by new instances. 39 * 40 * @param v 41 * the new default hostname verifier 42 * @throws IllegalArgumentException 43 * if the specified verifier is {@code null}. 44 */ 45 public static void setDefaultHostnameVerifier(HostnameVerifier v) { 46 if (v == null) { 47 throw new IllegalArgumentException("HostnameVerifier is null"); 48 } 49 defaultHostnameVerifier = v; 50 } 51 52 /** 53 * Returns the default hostname verifier. 54 * 55 * @return the default hostname verifier. 56 */ 57 public static HostnameVerifier getDefaultHostnameVerifier() { 58 return defaultHostnameVerifier; 59 } 60 61 /** 62 * Sets the default SSL socket factory to be used by new instances. 63 * 64 * @param sf 65 * the new default SSL socket factory. 66 * @throws IllegalArgumentException 67 * if the specified socket factory is {@code null}. 68 */ 69 public static void setDefaultSSLSocketFactory(SSLSocketFactory sf) { 70 if (sf == null) { 71 throw new IllegalArgumentException("SSLSocketFactory is null"); 72 } 73 defaultSSLSocketFactory = sf; 74 } 75 76 /** 77 * Returns the default SSL socket factory for new instances. 78 * 79 * @return the default SSL socket factory for new instances. 80 */ 81 public static SSLSocketFactory getDefaultSSLSocketFactory() { 82 return defaultSSLSocketFactory; 83 } 84 85 /** 86 * The host name verifier used by this connection. It is initialized from 87 * the default hostname verifier 88 * {@link #setDefaultHostnameVerifier(HostnameVerifier)} or 89 * {@link #getDefaultHostnameVerifier()}. 90 */ 91 protected HostnameVerifier hostnameVerifier; 92 93 private SSLSocketFactory sslSocketFactory; 94 95 /** 96 * Creates a new {@code HttpsURLConnection} with the specified {@code URL}. 97 * 98 * @param url 99 * the {@code URL} to connect to. 100 */ 101 protected HttpsURLConnection(URL url) { 102 super(url); 103 hostnameVerifier = defaultHostnameVerifier; 104 sslSocketFactory = defaultSSLSocketFactory; 105 } 106 107 /** 108 * Returns the name of the cipher suite negotiated during the SSL handshake. 109 * 110 * @return the name of the cipher suite negotiated during the SSL handshake. 111 * @throws IllegalStateException 112 * if no connection has been established yet. 113 */ 114 public abstract String getCipherSuite(); 115 116 /** 117 * Returns the list of local certificates used during the handshake. These 118 * certificates were sent to the peer. 119 * 120 * @return Returns the list of certificates used during the handshake with 121 * the local identity certificate followed by CAs, or {@code null} 122 * if no certificates were used during the handshake. 123 * @throws IllegalStateException 124 * if no connection has been established yet. 125 */ 126 public abstract Certificate[] getLocalCertificates(); 127 128 /** 129 * Return the list of certificates identifying the peer during the 130 * handshake. 131 * 132 * @return the list of certificates identifying the peer with the peer's 133 * identity certificate followed by CAs. 134 * @throws SSLPeerUnverifiedException 135 * if the identity of the peer has not been verified.. 136 * @throws IllegalStateException 137 * if no connection has been established yet. 138 */ 139 public abstract Certificate[] getServerCertificates() throws SSLPeerUnverifiedException; 140 141 /** 142 * Returns the {@code Principal} identifying the peer. 143 * 144 * @return the {@code Principal} identifying the peer. 145 * @throws SSLPeerUnverifiedException 146 * if the identity of the peer has not been verified. 147 * @throws IllegalStateException 148 * if no connection has been established yet. 149 */ 150 public Principal getPeerPrincipal() throws SSLPeerUnverifiedException { 151 Certificate[] certs = getServerCertificates(); 152 if (certs == null || certs.length == 0 || (!(certs[0] instanceof X509Certificate))) { 153 throw new SSLPeerUnverifiedException("No server's end-entity certificate"); 154 } 155 return ((X509Certificate) certs[0]).getSubjectX500Principal(); 156 } 157 158 /** 159 * Returns the {@code Principal} used to identify the local host during the handshake. 160 * 161 * @return the {@code Principal} used to identify the local host during the handshake, or 162 * {@code null} if none was used. 163 * @throws IllegalStateException 164 * if no connection has been established yet. 165 */ 166 public Principal getLocalPrincipal() { 167 Certificate[] certs = getLocalCertificates(); 168 if (certs == null || certs.length == 0 || (!(certs[0] instanceof X509Certificate))) { 169 return null; 170 } 171 return ((X509Certificate) certs[0]).getSubjectX500Principal(); 172 } 173 174 /** 175 * Sets the hostname verifier for this instance. 176 * 177 * @param v 178 * the hostname verifier for this instance. 179 * @throws IllegalArgumentException 180 * if the specified verifier is {@code null}. 181 */ 182 public void setHostnameVerifier(HostnameVerifier v) { 183 if (v == null) { 184 throw new IllegalArgumentException("HostnameVerifier is null"); 185 } 186 hostnameVerifier = v; 187 } 188 189 /** 190 * Returns the hostname verifier used by this instance. 191 * 192 * @return the hostname verifier used by this instance. 193 */ 194 public HostnameVerifier getHostnameVerifier() { 195 return hostnameVerifier; 196 } 197 198 /** 199 * Sets the SSL socket factory for this instance. 200 * 201 * @param sf 202 * the SSL socket factory to be used by this instance. 203 * @throws IllegalArgumentException 204 * if the specified socket factory is {@code null}. 205 */ 206 public void setSSLSocketFactory(SSLSocketFactory sf) { 207 if (sf == null) { 208 throw new IllegalArgumentException("SSLSocketFactory is null"); 209 } 210 sslSocketFactory = sf; 211 } 212 213 /** 214 * Returns the SSL socket factory used by this instance. 215 * 216 * @return the SSL socket factory used by this instance. 217 */ 218 public SSLSocketFactory getSSLSocketFactory() { 219 return sslSocketFactory; 220 } 221 222 } 223