This package defines an API for secure network sockets using the SSL (Secure Sockets Layer) protocol, or the closely related TLS (Transport Layer Security) protocol. It defines the SSLSocket and SSLServerSocket subclasses of the java.net socket and server socket classes. And it defines SSLSocketFactory and SSLServerSocketFactory subclasses of the javax.net factory classes to create those SSL-enabled sockets and server sockets. Clients that want to perform simple SSL-enabled networking can create an SSLSocket with code like the following:

SSLSocketFactory factory = SSLSocketFactory.getDefault( );
SSLSocket securesock = (SSLSocket)factory.getSocket(hostname,
                                                    443);     // https port

Once an SSLSocket has been created, it can be used just like a normal java.net.Socket. Once a connection is established over an SSLSocket, you can use the getSession( ) method to obtain an SSLSession object that provides information about the connection. Note that despite the name of this package and of its key classes, it supports the TLS protocol in addition to the SSL. (The default provider in Sun's implementation supports SSL 3.0 and TLS 1.0.) The TLS protocol is closely related to SSL, and we'll simply use the term SSL here.

The SSLSocket class allows you to do arbitrary networking with an SSL-enabled peer. The most common use of SSL today is with the https: protocol on the web. The addition of this package to the core Java platform enables support for https: URLs in the java.net.URL class, which allows you to securely transfer data over the web without having to directly use this package at all. When you call openConnection( ) on a https: URL, the URLConnection object that is returned can be cast to an HttpsURLConnection object, which defines some SSL-specific methods. See java.net.URL and java.net.URLConnection for more information about networking with URLs.

Although the code shown above to create a SSLSocket is quite simple, this package is much more complex because it exposes a lot of SSL infrastructure so that applications with advanced networking needs can configure it as needed. Also, like all security-related packages, this one is provider-based and algorithm-independent, which adds a layer of complexity. If you want to explore this package beyond the two socket classes, the two factory classes, and the HttpsURLConnection class, start with SSLContext. This class is a factory for socket factories, and as such is the central class of the API. To customize the way SSL networking is done, you create an SSLContext optionally specifing the desired provider of the implementation. Next, you initialize the SSLContext by providing a custom KeyManager as a source of authentication information to be supplied to the remote host if required, a custom TRustManager as a verifier for the authentication information (if any) presented by the remote host, and a custom java.security.SecureRandom object as a source of randomness. Once the SSLContext is initialized in this way, you can use it to create SSLSocketFactory and SSLServerSocketFactory objects that use the KeyManager and trustManager objects you supplied.

In Java 5.0, the SSLContext can also be used to create an SSLEngine object, which performs transport-independent SSL encryption of outbound packets and SSL decryption of inbound packets. This enables the use of SSL with the nonblocking networking facilities of the java.nio.channels package, for example.

Interfaces

public interface HandshakeCompletedListener extends java.util.EventListener;
public interface HostnameVerifier;
public interface KeyManager;
public interface ManagerFactoryParameters;
public interface SSLSession;
public interface SSLSessionBindingListener extends java.util.EventListener;
public interface SSLSessionContext;
public interface TrustManager;
public interface X509KeyManager extends KeyManager;
public interface X509TrustManager extends TrustManager;

Enumerated Types

public enum SSLEngineResult.HandshakeStatus;
public enum SSLEngineResult.Status;

Events

public class HandshakeCompletedEvent extends java.util.EventObject;
public class SSLSessionBindingEvent extends java.util.EventObject;

Other Classes

public class CertPathTrustManagerParameters implements ManagerFactoryParameters;
public abstract class HttpsURLConnection extends java.net.HttpURLConnection;
public class KeyManagerFactory;
public abstract class KeyManagerFactorySpi;
public class KeyStoreBuilderParameters implements ManagerFactoryParameters;
public class SSLContext;
public abstract class SSLContextSpi;
public abstract class SSLEngine;
public class SSLEngineResult;
public final class SSLPermission extends java.security.BasicPermission;
public abstract class SSLServerSocket extends java.net.ServerSocket;
public abstract class SSLServerSocketFactory extends javax.net.ServerSocketFactory;
public abstract class SSLSocket extends java.net.Socket;
public abstract class SSLSocketFactory extends javax.net.SocketFactory;
public class TrustManagerFactory;
public abstract class TrustManagerFactorySpi;
public abstract class X509ExtendedKeyManager implements X509KeyManager;

Exceptions

public class SSLException extends java.io.IOException;
   public class SSLHandshakeException extends SSLException;
   public class SSLKeyException extends SSLException;
   public class SSLPeerUnverifiedException extends SSLException;
   public class SSLProtocolException extends SSLException;