javax.net.ssl.SSLServerSocket Maven / Gradle / Ivy
Show all versions of qbicc-rt-java.base Show documentation
/*
* Copyright (c) 1997, 2018, 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 ServerSocket and
* provides secure server sockets using protocols such as the Secure
* Sockets Layer (SSL) or Transport Layer Security (TLS) protocols.
*
* Instances of this class are generally created using an
* SSLServerSocketFactory. The primary function
* of an SSLServerSocket
* is to create SSLSockets by accepting
* connections.
*
* An SSLServerSocket contains several pieces of state data
* which are inherited by the SSLSocket 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 SSLSocket 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.
*
* 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.
*
* 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.
*
* A port number of 0 creates a socket on any free port.
*
* If there is a security manager, its checkListen
* method is called with the port argument as its
* argument to ensure the operation is allowed. This could result
* in a SecurityException.
*
* @param port the port on which to listen
* @throws IOException if an I/O error occurs when creating the socket
* @throws SecurityException if a security manager exists and its
* checkListen method doesn't allow the operation.
* @throws IllegalArgumentException if the port parameter is outside the
* specified range of valid port values, which is between 0 and
* 65535, inclusive.
* @see SecurityManager#checkListen
*/
protected SSLServerSocket(int port)
throws IOException
{ super(port); }
/**
* Used only by subclasses.
*
* Create a TCP server socket on a port, using the default
* authentication context and a specified backlog of connections.
*
* A port number of 0 creates a socket on any free port.
*
* The backlog 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 altogther. The value provided
* should be greater than 0. If it is less than or equal to
* 0, then an implementation specific default will be used.
*
* If there is a security manager, its checkListen
* method is called with the port argument as its
* argument to ensure the operation is allowed. This could result
* in a SecurityException.
*
* @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 SecurityException if a security manager exists and its
* checkListen method doesn't allow the operation.
* @throws IllegalArgumentException if the port parameter is outside the
* specified range of valid port values, which is between 0 and
* 65535, inclusive.
* @see SecurityManager#checkListen
*/
protected SSLServerSocket(int port, int backlog)
throws IOException
{ super(port, backlog); }
/**
* Used only by subclasses.
*
* 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.
*
* If there is a security manager, its checkListen
* method is called with the port argument as its
* argument to ensure the operation is allowed. This could result
* in a SecurityException.
*
* A port number of 0 creates a socket on any free port.
*
* The backlog 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 altogther. The value provided
* should be greater than 0. If it is less than or equal to
* 0, then an implementation specific default will be used.
*
* If address 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 SecurityException if a security manager exists and its
* checkListen method doesn't allow the operation.
* @throws IllegalArgumentException if the port parameter is outside the
* specified range of valid port values, which is between 0 and
* 65535, inclusive.
* @see SecurityManager#checkListen
*/
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.
*
* If this list has not been explicitly modified, a system-provided
* default guarantees a minimum quality of service in all enabled
* cipher suites.
*
* 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.
*
* The returned array includes cipher suites from the list of standard
* cipher suite names in the
* JSSE Cipher Suite Names section of the Java Cryptography
* Architecture Standard Algorithm Name Documentation, and may also
* include other cipher suites that the provider supports.
*
* @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.
*
* The cipher suites must have been listed by getSupportedCipherSuites()
* as being supported. Following a successful call to this method,
* only suites listed in the suites parameter are enabled
* for use.
*
* 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.
*
* Note that the standard list of cipher suite names may be found in the
*
* JSSE Cipher Suite Names section of the Java Cryptography
* Architecture Standard Algorithm Name Documentation. Providers
* may support cipher suite names not found in this list or might not
* use the recommended name for a certain cipher suite.
*
* SSLSockets returned from accept()
* 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.
* @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.
*
* 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.
*
* The returned array includes cipher suites from the list of standard
* cipher suite names in the
* JSSE Cipher Suite Names section of the Java Cryptography
* Architecture Standard Algorithm Name Documentation, and may also
* include other cipher suites that the provider supports.
*
* @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.
*
* 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.
*
* The protocols must have been listed by
* getSupportedProtocols() as being supported.
* Following a successful call to this method, only protocols listed
* in the protocols parameter are enabled for use.
*
* SSLSockets returned from accept()
* 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 accepted server-mode
* SSLSockets will be initially configured to
* require client authentication.
*
* A socket's client authentication setting is one of the following:
*
* - client authentication required
*
- client authentication requested
*
- no client authentication desired
*
*
* Unlike {@link #setWantClientAuth(boolean)}, if the accepted
* socket's option is set and the client chooses not to provide
* authentication information about itself, the negotiations
* will stop and the connection will be dropped.
*
* Calling this method overrides any previous setting made by
* this method or {@link #setWantClientAuth(boolean)}.
*
* 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 required on
* newly accepted server-mode SSLSockets.
*
* 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 accepted server-mode
* SSLSockets will be initially configured to
* request client authentication.
*
* A socket's client authentication setting is one of the following:
*
* - client authentication required
*
- client authentication requested
*
- no client authentication desired
*
*
* Unlike {@link #setNeedClientAuth(boolean)}, if the accepted
* socket's option is set and the client chooses not to provide
* authentication information about itself, the negotiations
* will continue.
*
* Calling this method overrides any previous setting made by
* this method or {@link #setNeedClientAuth(boolean)}.
*
* 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 requested on
* newly accepted server-mode connections.
*
* 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.
*
* Servers normally authenticate themselves, and clients are not
* required to do so.
*
* 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.
*
* SSLSockets returned from accept()
* 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.
*
* SSLSockets returned from accept()
* 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.
*
*
This means:
*
* - If {@code params.getCipherSuites()} is non-null,
* {@code setEnabledCipherSuites()} is called with that value.
* - If {@code params.getProtocols()} is non-null,
* {@code setEnabledProtocols()} is called with that value.
* - 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.
* - If {@code params.getServerNames()} is non-null, the socket will
* configure its server names with that value.
* - If {@code params.getSNIMatchers()} is non-null, the socket will
* configure its SNI matchers with that value.
*
*
* @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 if (params.getWantClientAuth()) {
setWantClientAuth(true);
} else {
setWantClientAuth(false);
}
}
}