3002N/A * Copyright (c) 1997, 2010, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * This class extends <code>Socket</code>s and provides secure 0N/A * socket using protocols such as the "Secure 0N/A * Sockets Layer" (SSL) or IETF "Transport Layer Security" (TLS) protocols. 0N/A * Such sockets are normal stream sockets, but they 0N/A * add a layer of security protections over the underlying network transport 0N/A * protocol, such as TCP. Those protections include: <UL> 0N/A * <LI> <em>Integrity Protection</em>. SSL protects against 0N/A * modification of messages by an active wiretapper. 0N/A * <LI> <em>Authentication</em>. In most modes, SSL provides 0N/A * peer authentication. Servers are usually authenticated, 0N/A * and clients may be authenticated as requested by servers. 0N/A * <LI> <em>Confidentiality (Privacy Protection)</em>. In most 0N/A * modes, SSL encrypts data being sent between client and server. 0N/A * This protects the confidentiality of data, so that passive 0N/A * wiretappers won't see sensitive data such as financial 0N/A * information or personal information of many kinds. 0N/A * <P>These kinds of protection are specified by a "cipher suite", which 0N/A * is a combination of cryptographic algorithms used by a given SSL connection. 0N/A * During the negotiation process, the two endpoints must agree on 0N/A * a ciphersuite that is available in both environments. 0N/A * If there is no such suite in common, no SSL connection can 0N/A * be established, and no data can be exchanged. 0N/A * <P> The cipher suite used is established by a negotiation process 0N/A * called "handshaking". The goal of this 0N/A * process is to create or rejoin a "session", which may protect many 0N/A * connections over time. After handshaking has completed, you can access 0N/A * session attributes by using the <em>getSession</em> method. 0N/A * The initial handshake on this connection can be initiated in 0N/A * one of three ways: <UL> 0N/A * <LI> calling <code>startHandshake</code> which explicitly 0N/A * begins handshakes, or 0N/A * <LI> any attempt to read or write application data on 0N/A * this socket causes an implicit handshake, or 0N/A * <LI> a call to <code>getSession</code> tries to set up a session 0N/A * if there is no currently valid session, and 0N/A * an implicit handshake is done. 0N/A * <P>If handshaking fails for any reason, the <code>SSLSocket</code> 0N/A * is closed, and no futher communications can be done. 0N/A * <P>There are two groups of cipher suites which you will need to know 0N/A * about when managing cipher suites: <UL> 0N/A * <LI> <em>Supported</em> cipher suites: all the suites which are 0N/A * supported by the SSL implementation. This list is reported 0N/A * using <em>getSupportedCipherSuites</em>. 0N/A * <LI> <em>Enabled</em> cipher suites, which may be fewer 0N/A * than the full set of supported suites. This group is 0N/A * set using the <em>setEnabledCipherSuites</em> method, and 0N/A * queried using the <em>getEnabledCipherSuites</em> method. 0N/A * Initially, a default set of cipher suites will be enabled on 0N/A * a new socket that represents the minimum suggested configuration. 0N/A * <P> Implementation defaults require that only cipher 0N/A * suites which authenticate servers and provide confidentiality 0N/A * be enabled by default. 0N/A * Only if both sides explicitly agree to unauthenticated and/or 0N/A * non-private (unencrypted) communications will such a ciphersuite be 0N/A * <P>When <code>SSLSocket</code>s are first created, no handshaking 0N/A * is done so that applications may first set their communication 0N/A * preferences: what cipher suites to use, whether the socket should be 0N/A * in client or server mode, etc. 0N/A * However, security is always provided by the time that application data 0N/A * is sent over the connection. 0N/A * <P> You may register to receive event notification of handshake 0N/A * completion. This involves 0N/A * the use of two additional classes. <em>HandshakeCompletedEvent</em> 0N/A * objects are passed to <em>HandshakeCompletedListener</em> instances, 0N/A * which are registered by users of this API. 0N/A * <code>SSLSocket</code>s are created by <code>SSLSocketFactory</code>s, 0N/A * or by <code>accept</code>ing a connection from a 0N/A * <code>SSLServerSocket</code>. 0N/A * <P>A SSL socket must choose to operate in the client or server mode. 0N/A * This will determine who begins the handshaking process, as well 0N/A * as which messages should be sent by each party. Each 0N/A * connection must have one client and one server, or handshaking 0N/A * will not progress properly. Once the initial handshaking has started, a 0N/A * socket can not switch between client and server modes, even when 0N/A * performing renegotiations. 0N/A * @see java.net.Socket 0N/A * @see SSLServerSocket 0N/A * @see SSLSocketFactory 0N/A * @author David Brownell 0N/A * Used only by subclasses. 0N/A * Constructs an uninitialized, unconnected TCP socket. 0N/A * Used only by subclasses. 0N/A * Constructs a TCP connection to a named host at a specified port. 0N/A * This acts as the SSL client. 0N/A * If there is a security manager, its <code>checkConnect</code> 0N/A * method is called with the host address and <code>port</code> 0N/A * as its arguments. This could result in a SecurityException. 0N/A * @param host name of the host with which to connect, or 0N/A * <code>null</code> for the loopback address. 0N/A * @param port number of the server's port 0N/A * @throws IOException if an I/O error occurs when creating the socket 0N/A * @throws SecurityException if a security manager exists and its 0N/A * <code>checkConnect</code> method doesn't allow the operation. 0N/A * @throws UnknownHostException if the host is not known 0N/A * @throws IllegalArgumentException if the port parameter is outside the 0N/A * specified range of valid port values, which is between 0 and 0N/A * @see SecurityManager#checkConnect 0N/A * Used only by subclasses. 0N/A * Constructs a TCP connection to a server at a specified address 0N/A * and port. This acts as the SSL client. 0N/A * If there is a security manager, its <code>checkConnect</code> 0N/A * method is called with the host address and <code>port</code> 0N/A * as its arguments. This could result in a SecurityException. 0N/A * @param address the server's host 0N/A * @param port its port 0N/A * @throws IOException if an I/O error occurs when creating the socket 0N/A * @throws SecurityException if a security manager exists and its 0N/A * <code>checkConnect</code> method doesn't allow the operation. 0N/A * @throws IllegalArgumentException if the port parameter is outside the 0N/A * specified range of valid port values, which is between 0 and 0N/A * @throws NullPointerException if <code>address</code> is null. 0N/A * @see SecurityManager#checkConnect 0N/A * Used only by subclasses. 0N/A * Constructs an SSL connection to a named host at a specified port, 0N/A * binding the client side of the connection a given address and port. 0N/A * This acts as the SSL client. 0N/A * If there is a security manager, its <code>checkConnect</code> 0N/A * method is called with the host address and <code>port</code> 0N/A * as its arguments. This could result in a SecurityException. 0N/A * @param host name of the host with which to connect, or 0N/A * <code>null</code> for the loopback address. 0N/A * @param port number of the server's port 252N/A * @param clientAddress the client's address the socket is bound to, or 252N/A * <code>null</code> for the <code>anyLocal</code> address. 252N/A * @param clientPort the client's port the socket is bound to, or 252N/A * <code>zero</code> for a system selected free port. 0N/A * @throws IOException if an I/O error occurs when creating the socket 0N/A * @throws SecurityException if a security manager exists and its 0N/A * <code>checkConnect</code> method doesn't allow the operation. 0N/A * @throws UnknownHostException if the host is not known 0N/A * @throws IllegalArgumentException if the port parameter or clientPort 0N/A * parameter is outside the specified range of valid port values, 0N/A * which is between 0 and 65535, inclusive. 0N/A * @see SecurityManager#checkConnect 0N/A * Used only by subclasses. 0N/A * Constructs an SSL connection to a server at a specified address 0N/A * and TCP port, binding the client side of the connection a given 0N/A * address and port. This acts as the SSL client. 0N/A * If there is a security manager, its <code>checkConnect</code> 0N/A * method is called with the host address and <code>port</code> 0N/A * as its arguments. This could result in a SecurityException. 0N/A * @param address the server's host 0N/A * @param port its port 252N/A * @param clientAddress the client's address the socket is bound to, or 252N/A * <code>null</code> for the <code>anyLocal</code> address. 252N/A * @param clientPort the client's port the socket is bound to, or 252N/A * <code>zero</code> for a system selected free port. 0N/A * @throws IOException if an I/O error occurs when creating the socket 0N/A * @throws SecurityException if a security manager exists and its 0N/A * <code>checkConnect</code> method doesn't allow the operation. 0N/A * @throws IllegalArgumentException if the port parameter or clientPort 0N/A * parameter is outside the specified range of valid port values, 0N/A * which is between 0 and 65535, inclusive. 0N/A * @throws NullPointerException if <code>address</code> is null. 0N/A * @see SecurityManager#checkConnect 0N/A * Returns the names of the cipher suites which could be enabled for use 0N/A * on this connection. Normally, only a subset of these will actually 0N/A * be enabled by default, since this list may include cipher suites which 0N/A * do not meet quality of service requirements for those defaults. Such 0N/A * cipher suites might be useful in specialized applications. 0N/A * @return an array of cipher suite names 0N/A * @see #getEnabledCipherSuites() 0N/A * @see #setEnabledCipherSuites(String []) 0N/A * Returns the names of the SSL cipher suites which are currently 0N/A * enabled for use on this connection. When an SSLSocket is first 0N/A * created, all enabled cipher suites support a minimum quality of 0N/A * service. Thus, in some environments this value might be empty. 0N/A * Even if a suite has been enabled, it might never be used. (For 0N/A * example, the peer does not support it, the requisite certificates 0N/A * (and private keys) for the suite are not available, or an 0N/A * anonymous suite is enabled but authentication is required. 0N/A * @return an array of cipher suite names 0N/A * @see #getSupportedCipherSuites() 0N/A * @see #setEnabledCipherSuites(String []) 0N/A * Sets the cipher suites enabled for use on this connection. 0N/A * Each cipher suite in the <code>suites</code> parameter must have 0N/A * been listed by getSupportedCipherSuites(), or the method will 0N/A * fail. Following a successful call to this method, only suites 0N/A * listed in the <code>suites</code> parameter are enabled for use. 0N/A * See {@link #getEnabledCipherSuites()} for more information 0N/A * on why a specific ciphersuite may never be used on a connection. 0N/A * @param suites Names of all the cipher suites to enable 0N/A * @throws IllegalArgumentException when one or more of the ciphers 0N/A * named by the parameter is not supported, or when the 0N/A * parameter is null. 0N/A * @see #getSupportedCipherSuites() 0N/A * @see #getEnabledCipherSuites() 0N/A * Returns the names of the protocols which could be enabled for use 0N/A * on an SSL connection. 0N/A * @return an array of protocols supported 0N/A * Returns the names of the protocol versions which are currently 0N/A * enabled for use on this connection. 0N/A * @see #setEnabledProtocols(String []) 0N/A * @return an array of protocols 0N/A * Sets the protocol versions enabled for use on this connection. 0N/A * The protocols must have been listed by 0N/A * <code>getSupportedProtocols()</code> as being supported. 0N/A * Following a successful call to this method, only protocols listed 0N/A * in the <code>protocols</code> parameter are enabled for use. 0N/A * @param protocols Names of all the protocols to enable. 0N/A * @throws IllegalArgumentException when one or more of 0N/A * the protocols named by the parameter is not supported or 0N/A * when the protocols parameter is null. 0N/A * @see #getEnabledProtocols() 0N/A * Returns the SSL Session in use by this connection. These can 0N/A * be long lived, and frequently correspond to an entire login session 0N/A * for some user. The session specifies a particular cipher suite 0N/A * which is being actively used by all connections in that session, 0N/A * as well as the identities of the session's client and server. 0N/A * This method will initiate the initial handshake if 0N/A * necessary and then block until the handshake has been 0N/A * If an error occurs during the initial handshake, this method 0N/A * returns an invalid session object which reports an invalid 0N/A * cipher suite of "SSL_NULL_WITH_NULL_NULL". 0N/A * @return the <code>SSLSession</code> 3002N/A * Returns the {@code SSLSession} being constructed during a SSL/TLS 3002N/A * TLS protocols may negotiate parameters that are needed when using 3002N/A * an instance of this class, but before the {@code SSLSession} has 3002N/A * been completely initialized and made available via {@code getSession}. 3002N/A * For example, the list of valid signature algorithms may restrict 3002N/A * the type of certificates that can used during TrustManager 3002N/A * decisions, or the maximum TLS fragment packet sizes can be 3002N/A * resized to better support the network environment. 3002N/A * This method provides early access to the {@code SSLSession} being 3002N/A * constructed. Depending on how far the handshake has progressed, 3002N/A * some data may not yet be available for use. For example, if a 3002N/A * remote server will be sending a Certificate chain, but that chain 3002N/A * has yet not been processed, the {@code getPeerCertificates} 3002N/A * method of {@code SSLSession} will throw a 3002N/A * SSLPeerUnverifiedException. Once that chain has been processed, 3002N/A * {@code getPeerCertificates} will return the proper value. 3002N/A * Unlike {@link #getSession()}, this method does not initiate the 3002N/A * initial handshake and does not block until handshaking is 3002N/A * @see X509ExtendedKeyManager 3002N/A * @see X509ExtendedTrustManager 3002N/A * @return null if this instance is not currently handshaking, or 3002N/A * if the current handshake has not progressed far enough to 3002N/A * create a basic SSLSession. Otherwise, this method returns the 3002N/A * {@code SSLSession} currently being negotiated. 3002N/A * @throws UnsupportedOperationException if the underlying provider 3002N/A * does not implement the operation. 0N/A * Registers an event listener to receive notifications that an 0N/A * SSL handshake has completed on this connection. 0N/A * @param listener the HandShake Completed event listener 0N/A * @see #startHandshake() 0N/A * @see #removeHandshakeCompletedListener(HandshakeCompletedListener) 0N/A * @throws IllegalArgumentException if the argument is null. 0N/A * Removes a previously registered handshake completion listener. 0N/A * @param listener the HandShake Completed event listener 0N/A * @throws IllegalArgumentException if the listener is not registered, 0N/A * or the argument is null. 0N/A * @see #addHandshakeCompletedListener(HandshakeCompletedListener) 0N/A * Starts an SSL handshake on this connection. Common reasons include 0N/A * a need to use new encryption keys, to change cipher suites, or to 0N/A * initiate a new session. To force complete reauthentication, the 0N/A * current session could be invalidated before starting this handshake. 0N/A * <P> If data has already been sent on the connection, it continues 0N/A * to flow during this handshake. When the handshake completes, this 0N/A * will be signaled with an event. 0N/A * This method is synchronous for the initial handshake on a connection 0N/A * and returns when the negotiated handshake is complete. Some 0N/A * protocols may not support multiple handshakes on an existing socket 0N/A * and may throw an IOException. 0N/A * @throws IOException on a network level error 0N/A * @see #addHandshakeCompletedListener(HandshakeCompletedListener) 0N/A * Configures the socket to use client (or server) mode when 0N/A * This method must be called before any handshaking occurs. 0N/A * Once handshaking has begun, the mode can not be reset for the 0N/A * life of this socket. 0N/A * Servers normally authenticate themselves, and clients 0N/A * are not required to do so. 0N/A * @param mode true if the socket should start its handshaking 0N/A * @throws IllegalArgumentException if a mode change is attempted 0N/A * after the initial handshake has begun. 0N/A * @see #getUseClientMode() 0N/A * Returns true if the socket is set to use client mode when 0N/A * @return true if the socket should do handshaking 0N/A * @see #setUseClientMode(boolean) 0N/A * Configures the socket to <i>require</i> client authentication. This 0N/A * option is only useful for sockets in the server mode. 0N/A * A socket's client authentication setting is one of the following: 0N/A * <li> client authentication required 0N/A * <li> client authentication requested 0N/A * <li> no client authentication desired 0N/A * Unlike {@link #setWantClientAuth(boolean)}, if this option is set and 0N/A * the client chooses not to provide authentication information 0N/A * about itself, <i>the negotiations will stop and the connection 0N/A * will be dropped</i>. 0N/A * Calling this method overrides any previous setting made by 0N/A * this method or {@link #setWantClientAuth(boolean)}. 0N/A * @param need set to true if client authentication is required, 0N/A * or false if no client authentication is desired. 0N/A * @see #getNeedClientAuth() 0N/A * @see #setWantClientAuth(boolean) 0N/A * @see #getWantClientAuth() 0N/A * @see #setUseClientMode(boolean) 0N/A * Returns true if the socket will <i>require</i> client authentication. 0N/A * This option is only useful to sockets in the server mode. 0N/A * @return true if client authentication is required, 0N/A * or false if no client authentication is desired. 0N/A * @see #setNeedClientAuth(boolean) 0N/A * @see #setWantClientAuth(boolean) 0N/A * @see #getWantClientAuth() 0N/A * @see #setUseClientMode(boolean) 0N/A * Configures the socket to <i>request</i> client authentication. 0N/A * This option is only useful for sockets in the server mode. 0N/A * A socket's client authentication setting is one of the following: 0N/A * <li> client authentication required 0N/A * <li> client authentication requested 0N/A * <li> no client authentication desired 0N/A * Unlike {@link #setNeedClientAuth(boolean)}, if this option is set and 0N/A * the client chooses not to provide authentication information 0N/A * about itself, <i>the negotiations will continue</i>. 0N/A * Calling this method overrides any previous setting made by 0N/A * this method or {@link #setNeedClientAuth(boolean)}. 0N/A * @param want set to true if client authentication is requested, 0N/A * or false if no client authentication is desired. 0N/A * @see #getWantClientAuth() 0N/A * @see #setNeedClientAuth(boolean) 0N/A * @see #getNeedClientAuth() 0N/A * @see #setUseClientMode(boolean) 0N/A * Returns true if the socket will <i>request</i> client authentication. 0N/A * This option is only useful for sockets in the server mode. 0N/A * @return true if client authentication is requested, 0N/A * or false if no client authentication is desired. 0N/A * @see #setNeedClientAuth(boolean) 0N/A * @see #getNeedClientAuth() 0N/A * @see #setWantClientAuth(boolean) 0N/A * @see #setUseClientMode(boolean) 0N/A * Controls whether new SSL sessions may be established by this socket. 0N/A * If session creations are not allowed, and there are no 0N/A * existing sessions to resume, there will be no successful 0N/A * @param flag true indicates that sessions may be created; this 0N/A * is the default. false indicates that an existing session 0N/A * @see #getEnableSessionCreation() 0N/A * Returns true if new SSL sessions may be established by this socket. 0N/A * @return true indicates that sessions may be created; this 0N/A * is the default. false indicates that an existing session 0N/A * @see #setEnableSessionCreation(boolean) 0N/A * Returns the SSLParameters in effect for this SSLSocket. 0N/A * The ciphersuites and protocols of the returned SSLParameters 0N/A * are always non-null. 0N/A * @return the SSLParameters in effect for this SSLSocket. 0N/A * Applies SSLParameters to this socket. 0N/A * <li>if <code>params.getCipherSuites()</code> is non-null, 0N/A * <code>setEnabledCipherSuites()</code> is called with that value 0N/A * <li>if <code>params.getProtocols()</code> is non-null, 0N/A * <code>setEnabledProtocols()</code> is called with that value 0N/A * <li>if <code>params.getNeedClientAuth()</code> or 0N/A * <code>params.getWantClientAuth()</code> return <code>true</code>, 0N/A * <code>setNeedClientAuth(true)</code> and 0N/A * <code>setWantClientAuth(true)</code> are called, respectively; 0N/A * otherwise <code>setWantClientAuth(false)</code> is called. 0N/A * @param params the parameters 0N/A * @throws IllegalArgumentException if the setEnabledCipherSuites() or 0N/A * the setEnabledProtocols() call fails