| /* | |
| * Copyright (c) 1997, 2025, Oracle and/or its affiliates. All rights reserved. | |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | |
| * | |
| * This code is free software; you can redistribute it and/or modify it | |
| * under the terms of the GNU General Public License version 2 only, as | |
| * published by the Free Software Foundation. Oracle designates this | |
| * particular file as subject to the "Classpath" exception as provided | |
| * by Oracle in the LICENSE file that accompanied this code. | |
| * | |
| * This code is distributed in the hope that it will be useful, but WITHOUT | |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
| * version 2 for more details (a copy is included in the LICENSE file that | |
| * accompanied this code). | |
| * | |
| * You should have received a copy of the GNU General Public License version | |
| * 2 along with this work; if not, write to the Free Software Foundation, | |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. | |
| * | |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA | |
| * or visit www.oracle.com if you need additional information or have any | |
| * questions. | |
| */ | |
| package javax.net.ssl; | |
| import java.io.*; | |
| import java.net.*; | |
| /** | |
| * This class extends <code>ServerSocket</code> and | |
| * provides secure server sockets using protocols such as the Secure | |
| * Sockets Layer (SSL) or Transport Layer Security (TLS) protocols. | |
| * <P> | |
| * Instances of this class are generally created using an | |
| * <code>SSLServerSocketFactory</code>. The primary function | |
| * of an <code>SSLServerSocket</code> | |
| * is to create <code>SSLSocket</code>s by <code>accept</code>ing | |
| * connections. | |
| * <P> | |
| * An <code>SSLServerSocket</code> contains several pieces of state data | |
| * which are inherited by the <code>SSLSocket</code> at | |
| * socket creation. These include the enabled cipher | |
| * suites and protocols, whether client | |
| * authentication is necessary, and whether created sockets should | |
| * begin handshaking in client or server mode. The state | |
| * inherited by the created <code>SSLSocket</code> can be | |
| * overridden by calling the appropriate methods. | |
| * | |
| * @see java.net.ServerSocket | |
| * @see SSLSocket | |
| * | |
| * @since 1.4 | |
| * @author David Brownell | |
| */ | |
| public abstract class SSLServerSocket extends ServerSocket { | |
| /** | |
| * Used only by subclasses. | |
| * <P> | |
| * Create an unbound TCP server socket using the default authentication | |
| * context. | |
| * | |
| * @throws IOException if an I/O error occurs when creating the socket | |
| */ | |
| protected SSLServerSocket() | |
| throws IOException | |
| { super(); } | |
| /** | |
| * Used only by subclasses. | |
| * <P> | |
| * Create a TCP server socket on a port, using the default | |
| * authentication context. The connection backlog defaults to | |
| * fifty connections queued up before the system starts to | |
| * reject new connection requests. | |
| * <P> | |
| * A port number of <code>0</code> creates a socket on any free port. | |
| * | |
| * @param port the port on which to listen | |
| * @throws IOException if an I/O error occurs when creating the socket | |
| * @throws IllegalArgumentException if the port parameter is outside the | |
| * specified range of valid port values, which is between 0 and | |
| * 65535, inclusive. | |
| */ | |
| protected SSLServerSocket(int port) | |
| throws IOException | |
| { super(port); } | |
| /** | |
| * Used only by subclasses. | |
| * <P> | |
| * Create a TCP server socket on a port, using the default | |
| * authentication context and a specified backlog of connections. | |
| * <P> | |
| * A port number of <code>0</code> creates a socket on any free port. | |
| * <P> | |
| * The <code>backlog</code> argument is the requested maximum number of | |
| * pending connections on the socket. Its exact semantics are implementation | |
| * specific. In particular, an implementation may impose a maximum length | |
| * or may choose to ignore the parameter altogether. The value provided | |
| * should be greater than <code>0</code>. If it is less than or equal to | |
| * <code>0</code>, then an implementation specific default will be used. | |
| * | |
| * @param port the port on which to listen | |
| * @param backlog requested maximum length of the queue of incoming | |
| * connections. | |
| * @throws IOException if an I/O error occurs when creating the socket | |
| * @throws IllegalArgumentException if the port parameter is outside the | |
| * specified range of valid port values, which is between 0 and | |
| * 65535, inclusive. | |
| */ | |
| protected SSLServerSocket(int port, int backlog) | |
| throws IOException | |
| { super(port, backlog); } | |
| /** | |
| * Used only by subclasses. | |
| * <P> | |
| * Create a TCP server socket on a port, using the default | |
| * authentication context and a specified backlog of connections | |
| * as well as a particular specified network interface. This | |
| * constructor is used on multihomed hosts, such as those used | |
| * for firewalls or as routers, to control through which interface | |
| * a network service is provided. | |
| * <P> | |
| * A port number of <code>0</code> creates a socket on any free port. | |
| * <P> | |
| * The <code>backlog</code> argument is the requested maximum number of | |
| * pending connections on the socket. Its exact semantics are implementation | |
| * specific. In particular, an implementation may impose a maximum length | |
| * or may choose to ignore the parameter altogether. The value provided | |
| * should be greater than <code>0</code>. If it is less than or equal to | |
| * <code>0</code>, then an implementation specific default will be used. | |
| * <P> | |
| * If <i>address</i> is null, it will default accepting connections | |
| * on any/all local addresses. | |
| * | |
| * @param port the port on which to listen | |
| * @param backlog requested maximum length of the queue of incoming | |
| * connections. | |
| * @param address the address of the network interface through | |
| * which connections will be accepted | |
| * @throws IOException if an I/O error occurs when creating the socket | |
| * @throws IllegalArgumentException if the port parameter is outside the | |
| * specified range of valid port values, which is between 0 and | |
| * 65535, inclusive. | |
| */ | |
| protected SSLServerSocket(int port, int backlog, InetAddress address) | |
| throws IOException | |
| { super(port, backlog, address); } | |
| /** | |
| * Returns the list of cipher suites which are currently enabled | |
| * for use by newly accepted connections. | |
| * <P> | |
| * If this list has not been explicitly modified, a system-provided | |
| * default guarantees a minimum quality of service in all enabled | |
| * cipher suites. | |
| * <P> | |
| * Note that even if a suite is enabled, it may never be used. This | |
| * can occur if the peer does not support it, or its use is restricted, | |
| * or the requisite certificates (and private keys) for the suite are | |
| * not available, or an anonymous suite is enabled but authentication | |
| * is required. | |
| * <P> | |
| * The returned array includes cipher suites from the list of standard | |
| * cipher suite names in the <a href= | |
| * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names"> | |
| * JSSE Cipher Suite Names</a> section of the Java Security Standard | |
| * Algorithm Names Specification, and may also include other cipher | |
| * suites that the provider supports. | |
| * | |
| * @spec security/standard-names.html Java Security Standard Algorithm Names | |
| * @return an array of cipher suites enabled | |
| * @see #getSupportedCipherSuites() | |
| * @see #setEnabledCipherSuites(String[]) | |
| */ | |
| public abstract String [] getEnabledCipherSuites(); | |
| /** | |
| * Sets the cipher suites enabled for use by accepted connections. | |
| * <P> | |
| * The cipher suites must have been listed by getSupportedCipherSuites() | |
| * as being supported. Following a successful call to this method, | |
| * only suites listed in the <code>suites</code> parameter are enabled | |
| * for use. | |
| * <P> | |
| * Suites that require authentication information which is not available | |
| * in this ServerSocket's authentication context will not be used | |
| * in any case, even if they are enabled. | |
| * <P> | |
| * Note that the standard list of cipher suite names may be found in the | |
| * <a href= | |
| * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names"> | |
| * JSSE Cipher Suite Names</a> section of the Java Security Standard | |
| * Algorithm Names Specification. Providers may support cipher suite | |
| * names not found in this list or might not use the recommended name | |
| * for a certain cipher suite. | |
| * <P> | |
| * <code>SSLSocket</code>s returned from <code>accept()</code> | |
| * inherit this setting. | |
| * | |
| * @param suites Names of all the cipher suites to enable | |
| * @exception IllegalArgumentException when one or more of ciphers | |
| * named by the parameter is not supported, or when | |
| * the parameter is null. | |
| * @spec security/standard-names.html Java Security Standard Algorithm Names | |
| * @see #getSupportedCipherSuites() | |
| * @see #getEnabledCipherSuites() | |
| */ | |
| public abstract void setEnabledCipherSuites(String[] suites); | |
| /** | |
| * Returns the names of the cipher suites which could be enabled for use | |
| * on an SSL connection. | |
| * <P> | |
| * Normally, only a subset of these will actually | |
| * be enabled by default, since this list may include cipher suites which | |
| * do not meet quality of service requirements for those defaults. Such | |
| * cipher suites are useful in specialized applications. | |
| * <P> | |
| * The returned array includes cipher suites from the list of standard | |
| * cipher suite names in the <a href= | |
| * "{@docRoot}/../specs/security/standard-names.html#jsse-cipher-suite-names"> | |
| * JSSE Cipher Suite Names</a> section of the Java Security Standard | |
| * Algorithm Names Specification, and may also include other cipher | |
| * suites that the provider supports. | |
| * | |
| * @spec security/standard-names.html Java Security Standard Algorithm Names | |
| * @return an array of cipher suite names | |
| * @see #getEnabledCipherSuites() | |
| * @see #setEnabledCipherSuites(String[]) | |
| */ | |
| public abstract String [] getSupportedCipherSuites(); | |
| /** | |
| * Returns the names of the protocols which could be enabled for use. | |
| * | |
| * @return an array of protocol names supported | |
| * @see #getEnabledProtocols() | |
| * @see #setEnabledProtocols(String[]) | |
| */ | |
| public abstract String [] getSupportedProtocols(); | |
| /** | |
| * Returns the names of the protocols which are currently | |
| * enabled for use by the newly accepted connections. | |
| * <P> | |
| * Note that even if a protocol is enabled, it may never be used. | |
| * This can occur if the peer does not support the protocol, or its | |
| * use is restricted, or there are no enabled cipher suites supported | |
| * by the protocol. | |
| * | |
| * @return an array of protocol names | |
| * @see #getSupportedProtocols() | |
| * @see #setEnabledProtocols(String[]) | |
| */ | |
| public abstract String [] getEnabledProtocols(); | |
| /** | |
| * Controls which particular protocols are enabled for use by | |
| * accepted connections. | |
| * <P> | |
| * The protocols must have been listed by | |
| * getSupportedProtocols() as being supported. | |
| * Following a successful call to this method, only protocols listed | |
| * in the <code>protocols</code> parameter are enabled for use. | |
| * <P> | |
| * <code>SSLSocket</code>s returned from <code>accept()</code> | |
| * inherit this setting. | |
| * | |
| * @param protocols Names of all the protocols to enable. | |
| * @exception IllegalArgumentException when one or more of | |
| * the protocols named by the parameter is not supported or | |
| * when the protocols parameter is null. | |
| * @see #getEnabledProtocols() | |
| * @see #getSupportedProtocols() | |
| */ | |
| public abstract void setEnabledProtocols(String[] protocols); | |
| /** | |
| * Controls whether <code>accept</code>ed server-mode | |
| * <code>SSLSockets</code> will be initially configured to | |
| * <i>require</i> client authentication. | |
| * <P> | |
| * A socket's client authentication setting is one of the following: | |
| * <ul> | |
| * <li> client authentication required | |
| * <li> client authentication requested | |
| * <li> no client authentication desired | |
| * </ul> | |
| * <P> | |
| * Unlike {@link #setWantClientAuth(boolean)}, if the accepted | |
| * socket's option is set and the client chooses not to provide | |
| * authentication information about itself, <i>the negotiations | |
| * will stop and the connection will be dropped</i>. | |
| * <P> | |
| * Calling this method overrides any previous setting made by | |
| * this method or {@link #setWantClientAuth(boolean)}. | |
| * <P> | |
| * The initial inherited setting may be overridden by calling | |
| * {@link SSLSocket#setNeedClientAuth(boolean)} or | |
| * {@link SSLSocket#setWantClientAuth(boolean)}. | |
| * | |
| * @param need set to true if client authentication is required, | |
| * or false if no client authentication is desired. | |
| * @see #getNeedClientAuth() | |
| * @see #setWantClientAuth(boolean) | |
| * @see #getWantClientAuth() | |
| * @see #setUseClientMode(boolean) | |
| */ | |
| public abstract void setNeedClientAuth(boolean need); | |
| /** | |
| * Returns true if client authentication will be <i>required</i> on | |
| * newly <code>accept</code>ed server-mode <code>SSLSocket</code>s. | |
| * <P> | |
| * The initial inherited setting may be overridden by calling | |
| * {@link SSLSocket#setNeedClientAuth(boolean)} or | |
| * {@link SSLSocket#setWantClientAuth(boolean)}. | |
| * | |
| * @return true if client authentication is required, | |
| * or false if no client authentication is desired. | |
| * @see #setNeedClientAuth(boolean) | |
| * @see #setWantClientAuth(boolean) | |
| * @see #getWantClientAuth() | |
| * @see #setUseClientMode(boolean) | |
| */ | |
| public abstract boolean getNeedClientAuth(); | |
| /** | |
| * Controls whether <code>accept</code>ed server-mode | |
| * <code>SSLSockets</code> will be initially configured to | |
| * <i>request</i> client authentication. | |
| * <P> | |
| * A socket's client authentication setting is one of the following: | |
| * <ul> | |
| * <li> client authentication required | |
| * <li> client authentication requested | |
| * <li> no client authentication desired | |
| * </ul> | |
| * <P> | |
| * Unlike {@link #setNeedClientAuth(boolean)}, if the accepted | |
| * socket's option is set and the client chooses not to provide | |
| * authentication information about itself, <i>the negotiations | |
| * will continue</i>. | |
| * <P> | |
| * Calling this method overrides any previous setting made by | |
| * this method or {@link #setNeedClientAuth(boolean)}. | |
| * <P> | |
| * The initial inherited setting may be overridden by calling | |
| * {@link SSLSocket#setNeedClientAuth(boolean)} or | |
| * {@link SSLSocket#setWantClientAuth(boolean)}. | |
| * | |
| * @param want set to true if client authentication is requested, | |
| * or false if no client authentication is desired. | |
| * @see #getWantClientAuth() | |
| * @see #setNeedClientAuth(boolean) | |
| * @see #getNeedClientAuth() | |
| * @see #setUseClientMode(boolean) | |
| */ | |
| public abstract void setWantClientAuth(boolean want); | |
| /** | |
| * Returns true if client authentication will be <i>requested</i> on | |
| * newly accepted server-mode connections. | |
| * <P> | |
| * The initial inherited setting may be overridden by calling | |
| * {@link SSLSocket#setNeedClientAuth(boolean)} or | |
| * {@link SSLSocket#setWantClientAuth(boolean)}. | |
| * | |
| * @return true if client authentication is requested, | |
| * or false if no client authentication is desired. | |
| * @see #setWantClientAuth(boolean) | |
| * @see #setNeedClientAuth(boolean) | |
| * @see #getNeedClientAuth() | |
| * @see #setUseClientMode(boolean) | |
| */ | |
| public abstract boolean getWantClientAuth(); | |
| /** | |
| * Controls whether accepted connections are in the (default) SSL | |
| * server mode, or the SSL client mode. | |
| * <P> | |
| * Servers normally authenticate themselves, and clients are not | |
| * required to do so. | |
| * <P> | |
| * In rare cases, TCP servers | |
| * need to act in the SSL client mode on newly accepted | |
| * connections. For example, FTP clients acquire server sockets | |
| * and listen there for reverse connections from the server. An | |
| * FTP client would use an SSLServerSocket in "client" mode to | |
| * accept the reverse connection while the FTP server uses an | |
| * SSLSocket with "client" mode disabled to initiate the | |
| * connection. During the resulting handshake, existing SSL | |
| * sessions may be reused. | |
| * <P> | |
| * <code>SSLSocket</code>s returned from <code>accept()</code> | |
| * inherit this setting. | |
| * | |
| * @param mode true if newly accepted connections should use SSL | |
| * client mode. | |
| * @see #getUseClientMode() | |
| */ | |
| public abstract void setUseClientMode(boolean mode); | |
| /** | |
| * Returns true if accepted connections will be in SSL client mode. | |
| * | |
| * @see #setUseClientMode(boolean) | |
| * @return true if the connection should use SSL client mode. | |
| */ | |
| public abstract boolean getUseClientMode(); | |
| /** | |
| * Controls whether new SSL sessions may be established by the | |
| * sockets which are created from this server socket. | |
| * <P> | |
| * <code>SSLSocket</code>s returned from <code>accept()</code> | |
| * inherit this setting. | |
| * | |
| * @param flag true indicates that sessions may be created; this | |
| * is the default. false indicates that an existing session | |
| * must be resumed. | |
| * @see #getEnableSessionCreation() | |
| */ | |
| public abstract void setEnableSessionCreation(boolean flag); | |
| /** | |
| * Returns true if new SSL sessions may be established by the | |
| * sockets which are created from this server socket. | |
| * | |
| * @return true indicates that sessions may be created; this | |
| * is the default. false indicates that an existing | |
| * session must be resumed | |
| * @see #setEnableSessionCreation(boolean) | |
| */ | |
| public abstract boolean getEnableSessionCreation(); | |
| /** | |
| * Returns the SSLParameters in effect for newly accepted connections. | |
| * The ciphersuites and protocols of the returned SSLParameters | |
| * are always non-null. | |
| * | |
| * @return the SSLParameters in effect for newly accepted connections | |
| * | |
| * @see #setSSLParameters(SSLParameters) | |
| * | |
| * @since 1.7 | |
| */ | |
| public SSLParameters getSSLParameters() { | |
| SSLParameters parameters = new SSLParameters(); | |
| parameters.setCipherSuites(getEnabledCipherSuites()); | |
| parameters.setProtocols(getEnabledProtocols()); | |
| if (getNeedClientAuth()) { | |
| parameters.setNeedClientAuth(true); | |
| } else if (getWantClientAuth()) { | |
| parameters.setWantClientAuth(true); | |
| } | |
| return parameters; | |
| } | |
| /** | |
| * Applies SSLParameters to newly accepted connections. | |
| * | |
| * <p>This means: | |
| * <ul> | |
| * <li>If {@code params.getCipherSuites()} is non-null, | |
| * {@code setEnabledCipherSuites()} is called with that value.</li> | |
| * <li>If {@code params.getProtocols()} is non-null, | |
| * {@code setEnabledProtocols()} is called with that value.</li> | |
| * <li>If {@code params.getNeedClientAuth()} or | |
| * {@code params.getWantClientAuth()} return {@code true}, | |
| * {@code setNeedClientAuth(true)} and | |
| * {@code setWantClientAuth(true)} are called, respectively; | |
| * otherwise {@code setWantClientAuth(false)} is called.</li> | |
| * <li>If {@code params.getServerNames()} is non-null, the socket will | |
| * configure its server names with that value.</li> | |
| * <li>If {@code params.getSNIMatchers()} is non-null, the socket will | |
| * configure its SNI matchers with that value.</li> | |
| * </ul> | |
| * | |
| * @param params the parameters | |
| * @throws IllegalArgumentException if the setEnabledCipherSuites() or | |
| * the setEnabledProtocols() call fails | |
| * | |
| * @see #getSSLParameters() | |
| * | |
| * @since 1.7 | |
| */ | |
| public void setSSLParameters(SSLParameters params) { | |
| String[] s; | |
| s = params.getCipherSuites(); | |
| if (s != null) { | |
| setEnabledCipherSuites(s); | |
| } | |
| s = params.getProtocols(); | |
| if (s != null) { | |
| setEnabledProtocols(s); | |
| } | |
| if (params.getNeedClientAuth()) { | |
| setNeedClientAuth(true); | |
| } else { | |
| setWantClientAuth(params.getWantClientAuth()); | |
| } | |
| } | |
| } |