javax.net.ssl.SSLSocket Maven / Gradle / Ivy

Neither this file nor any files generated from it describe a complete specification, and they may only be used as described below. For example, no permission is given for you to incorporate this file, in whole or in part, in an implementation of a Java specification.

Sun Microsystems Inc. owns the copyright in this file and it is provided to you for informative, as opposed to normative, use. The file and any files generated from it may be used to generate other informative documentation, such as a unified set of documents of API signatures for a platform that includes technologies expressed as Java APIs. The file may also be used to produce "compilation stubs," which allow applications to be compiled and validated for such platforms.

Any work generated from this file, such as unified javadocs or compiled stub files, must be accompanied by this notice in its entirety.

This work corresponds to the API signatures of CDC Security (Java Secure Socket Extension - JSSE) Optional Package interfaces and modules. */ /* * @(#)SSLSocket.java 1.8 06/05/23 */ /* * NOTE: * Because of various external restrictions (i.e. US export * regulations, etc.), the actual source code can not be provided * at this time. This file represents the skeleton of the source * file, so that javadocs of the API can be created. */ package javax.net.ssl; import java.net.*; import java.io.IOException; import java.util.Enumeration; import java.util.Vector; /** * This class extends Sockets and provides secure * socket using protocols such as the "Secure * Sockets Layer" (SSL) or IETF "Transport Layer Security" (TLS) protocols. *

* Such sockets are normal stream sockets, but they * add a layer of security protections over the underlying network transport * protocol, such as TCP. Those protections include:

* *
• Integrity Protection. SSL protects against * modification of messages by an active wiretapper. * *
• Authentication. In most modes, SSL provides * peer authentication. Servers are usually authenticated, * and clients may be authenticated as requested by servers. * *
• Confidentiality (Privacy Protection). In most * modes, SSL encrypts data being sent between client and server. * This protects the confidentiality of data, so that passive * wiretappers won't see sensitive data such as financial * information or personal information of many kinds. * *

These kinds of protection are specified by a "cipher suite", which * is a combination of cryptographic algorithms used by a given SSL connection. * During the negotiation process, the two endpoints must agree on * a ciphersuite that is available in both environments. * If there is no such suite in common, no SSL connection can * be established, and no data can be exchanged. * *

The cipher suite used is established by a negotiation process * called "handshaking". The goal of this * process is to create or rejoin a "session", which may protect many * connections over time. After handshaking has completed, you can access * session attributes by using the getSession method. * The initial handshake on this connection can be initiated in * one of three ways:

* *
• calling startHandshake which explicitly * begins handshakes, or *
• any attempt to read or write application data on * this socket causes an implicit handshake, or *
• a call to getSession tries to set up a session * if there is no currently valid session, and * an implicit handshake is done. *

If handshaking fails for any reason, the SSLSocket * is closed, and no futher communications can be done. * *

There are two groups of cipher suites which you will need to know * about when managing cipher suites:

* *
• Supported cipher suites: all the suites which are * supported by the SSL implementation. This list is reported * using getSupportedCipherSuites. * *
• Enabled cipher suites, which may be fewer * than the full set of supported suites. This group is * set using the setEnabledCipherSuites method, and * queried using the getEnabledCipherSuites method. * Initially, a default set of cipher suites will be enabled on * a new socket that represents the minimum suggested configuration. * *

Implementation defaults require that only cipher * suites which authenticate servers and provide confidentiality * be enabled by default. * Only if both sides explicitly agree to unauthenticated and/or * non-private (unencrypted) communications will such a ciphersuite be * selected. * *

When SSLSockets are first created, no handshaking * is done so that applications may first set their communication * preferences: what cipher suites to use, whether the socket should be * in client or server mode, etc. * However, security is always provided by the time that application data * is sent over the connection. * *

You may register to receive event notification of handshake * completion. This involves * the use of two additional classes. HandshakeCompletedEvent * objects are passed to HandshakeCompletedListener instances, * which are registered by users of this API. * * SSLSockets are created by SSLSocketFactorys, * or by accepting a connection from a * SSLServerSocket. * *

A SSL socket may choose to operate in the client or server mode. * This will determine who begins the handshaking process, as well * as which messages should be sent by each party. However, each * connection must have one client and one server, or handshaking * will not progress properly. * * @see java.net.Socket * @see SSLServerSocket * @see SSLSocketFactory * * @since 1.4 * @version 1.22 * @author David Brownell */ public abstract class SSLSocket extends Socket { /** * Used only by subclasses. * Constructs an uninitialized, unconnected TCP socket. */ protected SSLSocket() { } /** * Used only by subclasses. * Constructs a TCP connection to a named host at a specified port. * This acts as the SSL client. * * @param host name of the host with which to connect * @param port number of the server's port * @throws IOException if an I/O error occurs when creating the socket * @throws UnknownHostException if the host is not known */ protected SSLSocket(String host, int port) throws IOException, UnknownHostException { } /** * Used only by subclasses. * Constructs a TCP connection to a server at a specified address * and port. This acts as the SSL client. * * @param address the server's host * @param port its port * @throws IOException if an I/O error occurs when creating the socket * @throws UnknownHostException if the host is not known */ protected SSLSocket(InetAddress address, int port) throws IOException, UnknownHostException { } /** * Used only by subclasses. * Constructs an SSL connection to a named host at a specified port, * binding the client side of the connection a given address and port. * This acts as the SSL client. * * @param host name of the host with which to connect * @param port number of the server's port * @param clientAddress the client's host * @param clientPort number of the client's port * @throws IOException if an I/O error occurs when creating the socket * @throws UnknownHostException if the host is not known */ protected SSLSocket(String host, int port, InetAddress clientAddress, int clientPort) throws IOException, UnknownHostException { } /** * Used only by subclasses. * Constructs an SSL connection to a server at a specified address * and TCP port, binding the client side of the connection a given * address and port. This acts as the SSL client. * * @param address the server's host * @param port its port * @param clientAddress the client's host * @param clientPort number of the client's port * @throws IOException if an I/O error occurs when creating the socket * @throws UnknownHostException if the host is not known */ protected SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort) throws IOException, UnknownHostException { } /** * Returns the names of the cipher suites which could be enabled for use * on this 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. * * @return an array of cipher suite names * @see #getEnabledCipherSuites() * @see #setEnabledCipherSuites(String []) */ public abstract String[] getSupportedCipherSuites(); /** * Returns the names of the SSL cipher suites which are currently enabled * for use on this connection. When an SSL socket is first created, * all enabled cipher suites support a minium quality of service. Thus, * in some environments this value might be empty. * *

There are several reasons why an enabled cipher suite might * not actually be used. For example: the server socket might * not have appropriate private keys available to it or the cipher * suite might be anonymous, precluding the use of client authentication, * while the server socket has been told to require that sort of * authentication. * * @return an array of cipher suite names * @see #getSupportedCipherSuites() * @see #setEnabledCipherSuites(String []) */ public abstract String[] getEnabledCipherSuites(); /** * Controls which particular cipher suites are enabled for use on * this connection. The cipher suites must have been listed by * getSupportedCipherSuites() as being supported. Even if a suite * has been enabled, it might never be used if no peer supports it, * or the requisite certificates (and private keys) are not available. * * @param suites Names of all the cipher suites to enable * @exception IllegalArgumentException when one or more of the 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 protocols which could be enabled for use * on an SSL connection. * * @return an array of protocols supported */ public abstract String[] getSupportedProtocols(); /** * Returns the names of the protocol versions which are currently * enabled for use on this connection. * @see #setEnabledProtocols * @return an array of protocols */ public abstract String[] getEnabledProtocols(); /** * Controls which particular protocol versions are enabled for use on * this connection. The protocols must have been listed by * getSupportedProtocols() as being supported. * * @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 */ public abstract void setEnabledProtocols(String[] protocols); /** * Returns the SSL Session in use by this connection. These can * be long lived, and frequently correspond to an entire login session * for some user. The session specifies a particular cipher suite * which is being actively used by all connections in that session, * as well as the identities of the session's client and server. *

* This method will initiate the initial handshake if * necessary and then block until the handshake has been * established. *

* If an error occurs during the initial handshake, this method * returns an invalid session object which reports an invalid * cipher suite of "SSL_NULL_WITH_NULL_NULL". * * @return the SSLSession */ public abstract SSLSession getSession(); /** * Registers an event listener to receive notifications that an * SSL handshake has completed on this connection. * * @param listener the HandShake Completed event listener * @see #startHandshake() * @see #removeHandshakeCompletedListener(HandshakeCompletedListener) * @throws IllegalArgumentException if the argument is null. */ public abstract void addHandshakeCompletedListener(HandshakeCompletedListener listener); /** * Removes a previously registered handshake completion listener. * * @param listener the HandShake Completed event listener * @throws IllegalArgumentException if the listener is not registered, * or the argument is null. * @see #addHandshakeCompletedListener(HandshakeCompletedListener) */ public abstract void removeHandshakeCompletedListener(HandshakeCompletedListener listener); /** * Starts an SSL handshake on this connection. Common reasons include * a need to use new encryption keys, to change cipher suites, or to * initiate a new session. To force complete reauthentication, the * current session could be invalidated before starting this handshake. * *

If data has already been sent on the connection, it continues * to flow during this handshake. When the handshake completes, this * will be signaled with an event. * * This method is synchronous for the initial handshake on a connection * and returns when the negotiated handshake is complete. Some * protocols may not support multiple handshakes on an existing socket * and may throw an IOException. * * @throws IOException on a network level error * @see #addHandshakeCompletedListener(HandshakeCompletedListener) */ public abstract void startHandshake() throws IOException; /** * Configures the socket to use client (or server) mode in its first * handshake. Servers normally authenticate themselves, and clients * are not required to do so. * * @param mode true if the socket should start its first handshake * in "client" mode * @throws IllegalArgumentException if a mode change is attempted * after handshaking has begun. * @throws UnsupportedOperationException if mode is * false and the underlying implementation does * not support server mode handshake. * @see #getUseClientMode() */ public abstract void setUseClientMode(boolean mode); /** * Returns true if the socket is set to use client mode in its first * handshake. * * @return true if the socket should start its first handshake * in "client" mode * @see #setUseClientMode(boolean) */ public abstract boolean getUseClientMode(); /** * Configures the socket to require client authentication. This * option is only useful for sockets in the server mode. *

* Unlike {@link #setWantClientAuth(boolean)}, * if the client chooses not to provide authentication information * about itself, the negotiations will stop and the connection * will be dropped. * * @param need should be set to true if the clients must * authenticate themselves. * Setting this parameter to true overrides the current * setting of {@link #setWantClientAuth(boolean)}. * @see #getNeedClientAuth() * @see #setWantClientAuth(boolean) * @see #getWantClientAuth() * @see #setUseClientMode(boolean) */ public abstract void setNeedClientAuth(boolean need); /** * Returns true if the socket will require client authentication. The * option is only useful to sockets in the server mode. * * @return true if the server mode socket should request that * the client authenticate itself. * @see #setNeedClientAuth(boolean) * @see #setWantClientAuth(boolean) * @see #getWantClientAuth() * @see #setUseClientMode(boolean) */ public abstract boolean getNeedClientAuth(); /** * Configures the socket to request client authentication, but * only if such a request is appropriate to the cipher suite * negotiated. This option is only useful * for sockets in the server mode. * * Unlike {@link #setNeedClientAuth(boolean)}, * if the client chooses not to provide authentication information * about itself, the negotiations will continue. *