/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package javax.net.ssl; import java.io.IOException; import java.net.InetAddress; import java.net.Socket; import java.net.UnknownHostException; /** * The extension of {@code Socket} providing secure protocols like SSL (Secure * Sockets Layer) or TLS (Transport Layer Security). * *

Default configuration

*

{@code SSLSocket} instances obtained from default {@link SSLSocketFactory}, * {@link SSLServerSocketFactory}, and {@link SSLContext} are configured as follows: * * * *

Protocols

* *

Client socket: * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
ProtocolSupported (API Levels)Enabled by default (API Levels)
SSLv31+1+
TLSv11+1+
TLSv1.116+20+
TLSv1.216+20+
* *

Server socket: * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
ProtocolSupported (API Levels)Enabled by default (API Levels)
SSLv31+1+
TLSv11+1+
TLSv1.116+16+
TLSv1.216+16+
* *

Cipher suites

* *

Methods that operate with cipher suite names (for example, * {@link #getSupportedCipherSuites() getSupportedCipherSuites}, * {@link #setEnabledCipherSuites(String[]) setEnabledCipherSuites}) have used * standard names for cipher suites since API Level 9, as listed in the table * below. Prior to API Level 9, non-standard (OpenSSL) names had been used (see * the table following this table). * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
Cipher suiteSupported (API Levels)Enabled by default (API Levels)
SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA9–229–19
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA9–229–19
SSL_DHE_DSS_WITH_DES_CBC_SHA9–229–19
SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA9–229–19
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA9–229–19
SSL_DHE_RSA_WITH_DES_CBC_SHA9–229–19
SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA9–22
SSL_DH_anon_EXPORT_WITH_RC4_40_MD59–22
SSL_DH_anon_WITH_3DES_EDE_CBC_SHA9–22
SSL_DH_anon_WITH_DES_CBC_SHA9–22
SSL_DH_anon_WITH_RC4_128_MD59–22
SSL_RSA_EXPORT_WITH_DES40_CBC_SHA9–229–19
SSL_RSA_EXPORT_WITH_RC4_40_MD59–229–19
SSL_RSA_WITH_3DES_EDE_CBC_SHA9+9–19
SSL_RSA_WITH_DES_CBC_SHA9–229–19
SSL_RSA_WITH_NULL_MD59–22
SSL_RSA_WITH_NULL_SHA9–22
SSL_RSA_WITH_RC4_128_MD59+9–19
SSL_RSA_WITH_RC4_128_SHA9+9+
TLS_DHE_DSS_WITH_AES_128_CBC_SHA9–229–22
TLS_DHE_DSS_WITH_AES_128_CBC_SHA25620–22
TLS_DHE_DSS_WITH_AES_128_GCM_SHA25620–22
TLS_DHE_DSS_WITH_AES_256_CBC_SHA9–2211–22
TLS_DHE_DSS_WITH_AES_256_CBC_SHA25620–22
TLS_DHE_DSS_WITH_AES_256_GCM_SHA38420–22
TLS_DHE_RSA_WITH_AES_128_CBC_SHA9+9+
TLS_DHE_RSA_WITH_AES_128_CBC_SHA25620+
TLS_DHE_RSA_WITH_AES_128_GCM_SHA25620+20+
TLS_DHE_RSA_WITH_AES_256_CBC_SHA9+11+
TLS_DHE_RSA_WITH_AES_256_CBC_SHA25620+
TLS_DHE_RSA_WITH_AES_256_GCM_SHA38420+20+
TLS_DH_anon_WITH_AES_128_CBC_SHA9–22
TLS_DH_anon_WITH_AES_128_CBC_SHA25620–22
TLS_DH_anon_WITH_AES_128_GCM_SHA25620–22
TLS_DH_anon_WITH_AES_256_CBC_SHA9–22
TLS_DH_anon_WITH_AES_256_CBC_SHA25620–22
TLS_DH_anon_WITH_AES_256_GCM_SHA38420–22
TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA11–2211–19
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA11+11+
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA25620+
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA25620+20+
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA11+11+
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA38420+
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA38420+20+
TLS_ECDHE_ECDSA_WITH_NULL_SHA11–22
TLS_ECDHE_ECDSA_WITH_RC4_128_SHA11+11+
TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA21+21+
TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA21+21+
TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA11–2211–19
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA11+11+
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA25620+
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA25620+20+
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA11+11+
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA38420+
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA38420+20+
TLS_ECDHE_RSA_WITH_NULL_SHA11–22
TLS_ECDHE_RSA_WITH_RC4_128_SHA11+11+
TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA11–2211–19
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA11–2211–19
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA25620–22
TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA25620–22
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA11–2211–19
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA38420–22
TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA38420–22
TLS_ECDH_ECDSA_WITH_NULL_SHA11–22
TLS_ECDH_ECDSA_WITH_RC4_128_SHA11–2211–19
TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA11–2211–19
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA11–2211–19
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA25620–22
TLS_ECDH_RSA_WITH_AES_128_GCM_SHA25620–22
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA11–2211–19
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA38420–22
TLS_ECDH_RSA_WITH_AES_256_GCM_SHA38420–22
TLS_ECDH_RSA_WITH_NULL_SHA11–22
TLS_ECDH_RSA_WITH_RC4_128_SHA11–2211–19
TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA11–22
TLS_ECDH_anon_WITH_AES_128_CBC_SHA11–22
TLS_ECDH_anon_WITH_AES_256_CBC_SHA11–22
TLS_ECDH_anon_WITH_NULL_SHA11–22
TLS_ECDH_anon_WITH_RC4_128_SHA11–22
TLS_EMPTY_RENEGOTIATION_INFO_SCSV11+11+
TLS_FALLBACK_SCSV21+
TLS_PSK_WITH_3DES_EDE_CBC_SHA21–22
TLS_PSK_WITH_AES_128_CBC_SHA21+21+
TLS_PSK_WITH_AES_256_CBC_SHA21+21+
TLS_PSK_WITH_RC4_128_SHA21+
TLS_RSA_WITH_AES_128_CBC_SHA9+9+
TLS_RSA_WITH_AES_128_CBC_SHA25620+
TLS_RSA_WITH_AES_128_GCM_SHA25620+20+
TLS_RSA_WITH_AES_256_CBC_SHA9+11+
TLS_RSA_WITH_AES_256_CBC_SHA25620+
TLS_RSA_WITH_AES_256_GCM_SHA38420+20+
TLS_RSA_WITH_NULL_SHA25620–22
* *

NOTE: PSK cipher suites are enabled by default only if the {@code SSLContext} through * which the socket was created has been initialized with a {@code PSKKeyManager}. * *

API Levels 1 to 8 use OpenSSL names for cipher suites. The table below * lists these OpenSSL names and their corresponding standard names used in API * Levels 9 and newer. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
OpenSSL cipher suiteStandard cipher suiteSupported (API Levels)Enabled by default (API Levels)
AES128-SHATLS_RSA_WITH_AES_128_CBC_SHA1+1+
AES256-SHATLS_RSA_WITH_AES_256_CBC_SHA1+1–8, 11+
DES-CBC-MD5SSL_CK_DES_64_CBC_WITH_MD51–81–8
DES-CBC-SHASSL_RSA_WITH_DES_CBC_SHA1–221–19
DES-CBC3-MD5SSL_CK_DES_192_EDE3_CBC_WITH_MD51–81–8
DES-CBC3-SHASSL_RSA_WITH_3DES_EDE_CBC_SHA1+1–19
DHE-DSS-AES128-SHATLS_DHE_DSS_WITH_AES_128_CBC_SHA1–221–22
DHE-DSS-AES256-SHATLS_DHE_DSS_WITH_AES_256_CBC_SHA1–221–8, 11–22
DHE-RSA-AES128-SHATLS_DHE_RSA_WITH_AES_128_CBC_SHA1+1+
DHE-RSA-AES256-SHATLS_DHE_RSA_WITH_AES_256_CBC_SHA1+1–8, 11+
EDH-DSS-DES-CBC-SHASSL_DHE_DSS_WITH_DES_CBC_SHA1–221–19
EDH-DSS-DES-CBC3-SHASSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA1–221–19
EDH-RSA-DES-CBC-SHASSL_DHE_RSA_WITH_DES_CBC_SHA1–221–19
EDH-RSA-DES-CBC3-SHASSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA1–221–19
EXP-DES-CBC-SHASSL_RSA_EXPORT_WITH_DES40_CBC_SHA1–221–19
EXP-EDH-DSS-DES-CBC-SHASSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA1–221–19
EXP-EDH-RSA-DES-CBC-SHASSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA1–221–19
EXP-RC2-CBC-MD5SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD51–81–8
EXP-RC4-MD5SSL_RSA_EXPORT_WITH_RC4_40_MD51–221–19
RC2-CBC-MD5SSL_CK_RC2_128_CBC_WITH_MD51–81–8
RC4-MD5SSL_RSA_WITH_RC4_128_MD51+1–19
RC4-SHASSL_RSA_WITH_RC4_128_SHA1+1+
*/ public abstract class SSLSocket extends Socket { /** * Only to be used by subclasses. *

* Creates a TCP socket. */ protected SSLSocket() { } /** * Only to be used by subclasses. *

* Creates a TCP socket connection to the specified host at the specified * port. * * @param host * the host name to connect to. * @param port * the port number to connect to. * @throws IOException * if creating the socket fails. * @throws UnknownHostException * if the specified host is not known. */ protected SSLSocket(String host, int port) throws IOException, UnknownHostException { super(host, port); } /** * Only to be used by subclasses. *

* Creates a TCP socket connection to the specified address at the specified * port. * * @param address * the address to connect to. * @param port * the port number to connect to. * @throws IOException * if creating the socket fails. */ protected SSLSocket(InetAddress address, int port) throws IOException { super(address, port); } /** * Only to be used by subclasses. *

* Creates a TCP socket connection to the specified host at the specified * port with the client side bound to the specified address and port. * * @param host * the host name to connect to. * @param port * the port number to connect to. * @param clientAddress * the client address to bind to * @param clientPort * the client port number to bind to. * @throws IOException * if creating the socket fails. * @throws UnknownHostException * if the specified host is not known. */ protected SSLSocket(String host, int port, InetAddress clientAddress, int clientPort) throws IOException, UnknownHostException { super(host, port, clientAddress, clientPort); } /** * Only to be used by subclasses. *

* Creates a TCP socket connection to the specified address at the specified * port with the client side bound to the specified address and port. * * @param address * the address to connect to. * @param port * the port number to connect to. * @param clientAddress * the client address to bind to. * @param clientPort * the client port number to bind to. * @throws IOException * if creating the socket fails. */ protected SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort) throws IOException { super(address, port, clientAddress, clientPort); } /** * Unsupported for SSL because reading from an SSL socket may require * writing to the network. */ @Override public void shutdownInput() throws IOException { throw new UnsupportedOperationException(); } /** * Unsupported for SSL because writing to an SSL socket may require reading * from the network. */ @Override public void shutdownOutput() throws IOException { throw new UnsupportedOperationException(); } /** * Returns the names of the supported cipher suites. */ public abstract String[] getSupportedCipherSuites(); /** * Returns the names of the enabled cipher suites. */ public abstract String[] getEnabledCipherSuites(); /** * Sets the names of the cipher suites to be enabled. * Only cipher suites returned by {@link #getSupportedCipherSuites()} are * allowed. * * @param suites * the names of the to be enabled cipher suites. * @throws IllegalArgumentException * if one of the cipher suite names is not supported. */ public abstract void setEnabledCipherSuites(String[] suites); /** * Returns the names of the supported protocols. */ public abstract String[] getSupportedProtocols(); /** * Returns the names of the enabled protocols. */ public abstract String[] getEnabledProtocols(); /** * Sets the names of the protocols to be enabled. Only * protocols returned by {@link #getSupportedProtocols()} are allowed. * * @param protocols * the names of the to be enabled protocols. * @throws IllegalArgumentException * if one of the protocols is not supported. */ public abstract void setEnabledProtocols(String[] protocols); /** * Returns the {@code SSLSession} for this connection. If necessary, a * handshake will be initiated, in which case this method will block until the handshake * has been established. If the handshake fails, an invalid session object * will be returned. * * @return the session object. */ public abstract SSLSession getSession(); /** * Registers the specified listener to receive notification on completion of * a handshake on this connection. * * @param listener the listener to register. * @throws IllegalArgumentException if {@code listener} is {@code null}. */ public abstract void addHandshakeCompletedListener(HandshakeCompletedListener listener); /** * Removes the specified handshake completion listener. * * @param listener * the listener to remove. * @throws IllegalArgumentException * if the specified listener is not registered or {@code null}. */ public abstract void removeHandshakeCompletedListener(HandshakeCompletedListener listener); /** * Starts a new SSL handshake on this connection. * * @throws IOException * if an error occurs. */ public abstract void startHandshake() throws IOException; /** * Sets whether this connection should act in client mode when handshaking. * * @param mode * {@code true} if this connection should act in client mode, * {@code false} if not. */ public abstract void setUseClientMode(boolean mode); /** * Returns true if this connection will act in client mode when handshaking. */ public abstract boolean getUseClientMode(); /** * Sets whether the server should require client authentication. This * does not apply to sockets in {@link #getUseClientMode() client mode}. * Client authentication is one of the following: *

* This method overrides the setting of {@link #setWantClientAuth(boolean)}. */ public abstract void setNeedClientAuth(boolean need); /** * Sets whether the server should request client authentication. Unlike * {@link #setNeedClientAuth} this won't stop the negotiation if the client * doesn't authenticate. This does not apply to sockets in {@link * #getUseClientMode() client mode}.The client authentication is one of: * * This method overrides the setting of {@link #setNeedClientAuth(boolean)}. */ public abstract void setWantClientAuth(boolean want); /** * Returns true if the server socket should require client authentication. * This does not apply to sockets in {@link #getUseClientMode() client * mode}. */ public abstract boolean getNeedClientAuth(); /** * Returns true if the server should request client authentication. This * does not apply to sockets in {@link #getUseClientMode() client mode}. */ public abstract boolean getWantClientAuth(); /** * Sets whether new SSL sessions may be created by this socket or if * existing sessions must be reused. If {@code flag} is false and there are * no sessions to resume, handshaking will fail. * * @param flag {@code true} if new sessions may be created. */ public abstract void setEnableSessionCreation(boolean flag); /** * Returns whether new SSL sessions may be created by this socket or if * existing sessions must be reused. * * @return {@code true} if new sessions may be created, otherwise * {@code false}. */ public abstract boolean getEnableSessionCreation(); /** * Returns a new SSLParameters based on this SSLSocket's current * cipher suites, protocols, and client authentication settings. * * @since 1.6 */ public SSLParameters getSSLParameters() { SSLParameters p = new SSLParameters(); p.setCipherSuites(getEnabledCipherSuites()); p.setProtocols(getEnabledProtocols()); p.setNeedClientAuth(getNeedClientAuth()); p.setWantClientAuth(getWantClientAuth()); return p; } /** * Sets various SSL handshake parameters based on the SSLParameter * argument. Specifically, sets the SSLSocket's enabled cipher * suites if the parameter's cipher suites are non-null. Similarly * sets the enabled protocols. If the parameters specify the want * or need for client authentication, those requirements are set * on the SSLSocket, otherwise both are set to false. * @since 1.6 */ public void setSSLParameters(SSLParameters p) { String[] cipherSuites = p.getCipherSuites(); if (cipherSuites != null) { setEnabledCipherSuites(cipherSuites); } String[] protocols = p.getProtocols(); if (protocols != null) { setEnabledProtocols(protocols); } if (p.getNeedClientAuth()) { setNeedClientAuth(true); } else if (p.getWantClientAuth()) { setWantClientAuth(true); } else { setWantClientAuth(false); } } }