The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 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.io.IOException; |
| 21 | import java.net.InetAddress; |
| 22 | import java.net.Socket; |
| 23 | import java.net.UnknownHostException; |
| 24 | |
| 25 | /** |
| 26 | * The extension of {@code Socket} providing secure protocols like SSL (Secure |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 27 | * Socket Layer") or TLS (Transport Layer Security). |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 28 | */ |
| 29 | public abstract class SSLSocket extends Socket { |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 30 | |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 31 | /** |
| 32 | * Only to be used by subclasses. |
| 33 | * <p> |
| 34 | * Creates a TCP socket. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 35 | */ |
| 36 | protected SSLSocket() { |
| 37 | super(); |
| 38 | } |
| 39 | |
| 40 | /** |
| 41 | * Only to be used by subclasses. |
| 42 | * <p> |
| 43 | * Creates a TCP socket connection to the specified host at the specified |
| 44 | * port. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 45 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 46 | * @param host |
| 47 | * the host name to connect to. |
| 48 | * @param port |
| 49 | * the port number to connect to. |
| 50 | * @throws IOException |
| 51 | * if creating the socket fails. |
| 52 | * @throws UnknownHostException |
| 53 | * if the specified host is not known. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 54 | */ |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 55 | protected SSLSocket(String host, int port) throws IOException, UnknownHostException { |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 56 | super(host, port); |
| 57 | } |
| 58 | |
| 59 | /** |
| 60 | * Only to be used by subclasses. |
| 61 | * <p> |
| 62 | * Creates a TCP socket connection to the specified address at the specified |
| 63 | * port. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 64 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 65 | * @param address |
| 66 | * the address to connect to. |
| 67 | * @param port |
| 68 | * the port number to connect to. |
| 69 | * @throws IOException |
| 70 | * if creating the socket fails. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 71 | */ |
| 72 | protected SSLSocket(InetAddress address, int port) throws IOException { |
| 73 | super(address, port); |
| 74 | } |
| 75 | |
| 76 | /** |
| 77 | * Only to be used by subclasses. |
| 78 | * <p> |
| 79 | * Creates a TCP socket connection to the specified host at the specified |
| 80 | * port with the client side bound to the specified address and port. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 81 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 82 | * @param host |
| 83 | * the host name to connect to. |
| 84 | * @param port |
| 85 | * the port number to connect to. |
| 86 | * @param clientAddress |
| 87 | * the client address to bind to |
| 88 | * @param clientPort |
| 89 | * the client port number to bind to. |
| 90 | * @throws IOException |
| 91 | * if creating the socket fails. |
| 92 | * @throws UnknownHostException |
| 93 | * if the specified host is not known. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 94 | */ |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 95 | protected SSLSocket(String host, int port, InetAddress clientAddress, int clientPort) |
| 96 | throws IOException, UnknownHostException { |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 97 | super(host, port, clientAddress, clientPort); |
| 98 | } |
| 99 | |
| 100 | /** |
| 101 | * Only to be used by subclasses. |
| 102 | * <p> |
| 103 | * Creates a TCP socket connection to the specified address at the specified |
| 104 | * port with the client side bound to the specified address and port. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 105 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 106 | * @param address |
| 107 | * the address to connect to. |
| 108 | * @param port |
| 109 | * the port number to connect to. |
| 110 | * @param clientAddress |
| 111 | * the client address to bind to. |
| 112 | * @param clientPort |
| 113 | * the client port number to bind to. |
| 114 | * @throws IOException |
| 115 | * if creating the socket fails. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 116 | */ |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 117 | protected SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort) |
| 118 | throws IOException { |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 119 | super(address, port, clientAddress, clientPort); |
| 120 | } |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 121 | |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 122 | /** |
| 123 | * Returns the names of the supported cipher suites. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 124 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 125 | * @return the names of the supported cipher suites. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 126 | */ |
| 127 | public abstract String[] getSupportedCipherSuites(); |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 128 | |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 129 | /** |
| 130 | * Returns the names of the enabled cipher suites. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 131 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 132 | * @return the names of the enabled cipher suites. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 133 | */ |
| 134 | public abstract String[] getEnabledCipherSuites(); |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 135 | |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 136 | /** |
| 137 | * Sets the names of the cipher suites to be enabled. |
| 138 | * Only cipher suites returned by {@link #getSupportedCipherSuites()} are |
| 139 | * allowed. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 140 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 141 | * @param suites |
| 142 | * the names of the to be enabled cipher suites. |
| 143 | * @throws IllegalArgumentException |
| 144 | * if one of the cipher suite names is not supported. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 145 | */ |
| 146 | public abstract void setEnabledCipherSuites(String[] suites); |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 147 | |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 148 | /** |
| 149 | * Returns the names of the supported protocols. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 150 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 151 | * @return the names of the supported protocols. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 152 | */ |
| 153 | public abstract String[] getSupportedProtocols(); |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 154 | |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 155 | /** |
| 156 | * Returns the names of the enabled protocols. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 157 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 158 | * @return the names of the enabled protocols. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 159 | */ |
| 160 | public abstract String[] getEnabledProtocols(); |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 161 | |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 162 | /** |
| 163 | * Sets the names of the protocols to be enabled. Only |
| 164 | * protocols returned by {@link #getSupportedProtocols()} are allowed. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 165 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 166 | * @param protocols |
| 167 | * the names of the to be enabled protocols. |
| 168 | * @throws IllegalArgumentException |
| 169 | * if one of the protocols is not supported. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 170 | */ |
| 171 | public abstract void setEnabledProtocols(String[] protocols); |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 172 | |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 173 | /** |
| 174 | * Returns the {@code SSLSession} for this connection. If necessary, a |
| 175 | * handshake will be initiated, in which case this method will block until the handshake |
| 176 | * has been established. If the handshake fails, an invalid session object |
| 177 | * will be returned. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 178 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 179 | * @return the session object. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 180 | */ |
| 181 | public abstract SSLSession getSession(); |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 182 | |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 183 | /** |
| 184 | * Registers the specified listener to receive notification on completion of a |
| 185 | * handshake on this connection. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 186 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 187 | * @param listener |
| 188 | * the listener to register. |
| 189 | * @throws IllegalArgumentException |
| 190 | * if {@code listener} is {@code null}. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 191 | */ |
| 192 | public abstract void addHandshakeCompletedListener(HandshakeCompletedListener listener); |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 193 | |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 194 | /** |
| 195 | * Removes the specified handshake completion listener. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 196 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 197 | * @param listener |
| 198 | * the listener to remove. |
| 199 | * @throws IllegalArgumentException |
| 200 | * if the specified listener is not registered or {@code null}. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 201 | */ |
| 202 | public abstract void removeHandshakeCompletedListener(HandshakeCompletedListener listener); |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 203 | |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 204 | /** |
| 205 | * Starts a new SSL handshake on this connection. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 206 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 207 | * @throws IOException |
| 208 | * if an error occurs. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 209 | */ |
| 210 | public abstract void startHandshake() throws IOException; |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 211 | |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 212 | /** |
| 213 | * Sets whether this connection should act in client mode when handshaking. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 214 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 215 | * @param mode |
| 216 | * {@code true} if this connection should act in client mode, |
| 217 | * {@code false} if not. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 218 | */ |
| 219 | public abstract void setUseClientMode(boolean mode); |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 220 | |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 221 | /** |
| 222 | * Returns whether this connection will act in client mode when handshaking. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 223 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 224 | * @return {@code true} if this connections will act in client mode when |
| 225 | * handshaking, {@code false} if not. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 226 | */ |
| 227 | public abstract boolean getUseClientMode(); |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 228 | |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 229 | /** |
| 230 | * Sets whether this connection should require client authentication. This |
| 231 | * is only useful for sockets in server mode. The client authentication is |
| 232 | * one of the following: |
| 233 | * <ul> |
| 234 | * <li>authentication required</li> |
| 235 | * <li>authentication requested</li> |
| 236 | * <li>no authentication needed</li> |
| 237 | * </ul> |
| 238 | * This method overrides the setting of {@link #setWantClientAuth(boolean)}. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 239 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 240 | * @param need |
| 241 | * {@code true} if client authentication is required, |
| 242 | * {@code false} if no authentication is needed. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 243 | */ |
| 244 | public abstract void setNeedClientAuth(boolean need); |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 245 | |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 246 | /** |
| 247 | * Returns whether this connection requires client authentication. |
| 248 | * This is only useful for sockets in server mode. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 249 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 250 | * @return {@code true} if client authentication is required, {@code false} |
| 251 | * if no client authentication is needed. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 252 | */ |
| 253 | public abstract boolean getNeedClientAuth(); |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 254 | |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 255 | /** |
| 256 | * Sets whether this connections should request client authentication. This |
| 257 | * is only useful for sockets in server mode. The client authentication is |
| 258 | * one of: |
| 259 | * <ul> |
| 260 | * <li>authentication required</li> |
| 261 | * <li>authentication requested</li> |
| 262 | * <li>no authentication needed</li> |
| 263 | * </ul> |
| 264 | * This method overrides the setting of {@link #setNeedClientAuth(boolean)}. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 265 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 266 | * @param want |
| 267 | * {@code true} if client authentication should be requested, |
| 268 | * {@code false} if not authentication is needed. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 269 | */ |
| 270 | public abstract void setWantClientAuth(boolean want); |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 271 | |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 272 | /** |
| 273 | * Returns whether this connections will request client authentication. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 274 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 275 | * @return {@code true} is client authentication will be requested, |
| 276 | * {@code false} if no client authentication is needed. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 277 | */ |
| 278 | public abstract boolean getWantClientAuth(); |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 279 | |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 280 | /** |
| 281 | * Sets whether new SSL sessions may be created by this socket or if |
| 282 | * existing sessions must be reused. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 283 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 284 | * @param flag |
| 285 | * {@code true} if new sessions may be created, otherwise |
| 286 | * {@code false}. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 287 | */ |
| 288 | public abstract void setEnableSessionCreation(boolean flag); |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 289 | |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 290 | /** |
| 291 | * Returns whether new SSL sessions may be created by this socket or if |
| 292 | * existing sessions must be reused. |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 293 | * |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 294 | * @return {@code true} if new sessions may be created, otherwise |
| 295 | * {@code false}. |
The Android Open Source Project | adc854b | 2009-03-03 19:28:47 -0800 | [diff] [blame] | 296 | */ |
| 297 | public abstract boolean getEnableSessionCreation(); |
Jesse Wilson | f921579 | 2009-08-25 16:30:17 -0700 | [diff] [blame^] | 298 | |
| 299 | } |