PageRenderTime 53ms CodeModel.GetById 27ms RepoModel.GetById 0ms app.codeStats 0ms

/luni/src/main/java/javax/net/ssl/SSLSocket.java

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