javax.net.ssl
类 SSLSocket

java.lang.Object
  java.net.Socket
      javax.net.ssl.SSLSocket

public abstract class SSLSocket
extends Socket

此类扩展 Socket 并提供使用协议（如 "Secure Sockets Layer" (SSL) 或 IETF "Transport Layer Security" (TLS) 协议）的安全套接字。

这种套接字是正常的流套接字，但是它们在基础网络传输协议（如 TCP）上添加了安全保护层。这些保护包括：

• 完整性保护。SSL 可以防止报文被主动的窃听者修改。
• 身份验证。在多数模式下，SSL 提供对等身份验证。服务器通常要进行身份验证，客户端也可在服务器的请求下进行身份验证。
• 机密性（私有性保护）。在多数模式下，SSL 加密在客户端和服务器之间发送的数据。这保护了数据的机密性，所以被动的窃听者不能看到各种类型的敏感数据，如财务信息或个人信息。

这些类型的保护由一个“密码套件”指定，“密码套件”是由给定的 SSL 连接使用的加密算法组合。在协商过程中，两个端点必须对在双方的环境中都可用的密码套件达成一致。如果不存在这种公共的套件，就不能建立 SSL 连接，也不能交换数据。

通过称为“握手”的协商过程来建立所用的密码套件。此过程的目的是创建或重新加入一个“会话”，“会话”可以保护很多会话过程中的连接。握手结束后，可以使用 getSession 方法访问会话的属性。在此连接上的初始握手可以以三种方式开始：

• 调用 startHandshake 显式地开始握手，或
• 任何在此连接上尝试读或写应用数据而引起的隐式握手，或
• 如果当前不存在有效的会话，则调用 getSession 试图建立会话，并进行隐式握手。

如果握手由于某些原因失败，则 SSLSocket 关闭，不进行进一步的通信。

有两组密码套件是您在管理密码套件时需要知道的：

• 支持的 密码套件：SSL 实现支持的所有套件。使用 getSupportedCipherSuites 报告此列表。
• 启用的 密码套件，它可少于完整的支持套件集。此组使用 setEnabledCipherSuites 方法设置，使用 getEnabledCipherSuites 方法查询。最初，在新的表示最低建议配置的套接字上启用默认的密码套件组。

实现默认要求，默认只启用那些可对服务器进行身份验证并提供机密性的密码套件。只有双方明确同意非鉴别和/或非私有的（未加密的）的通信时才选择这种密码套件。

第一次创建 SSLSocket 时不进行握手，所以应用程序可以首先设置它们的通信首选项：使用哪个密码套件、套接字应该为客户端还是服务器模式等。但是，在应用数据在连接上发送时总是提供安全性。

你可以注册来接收握手结束的事件通知。这涉及到使用另外的两个类。HandshakeCompletedEvent 对象被传递到 HandshakeCompletedListener 实例，此实例被 API 的用户注册。 SSLSocket 通过 SSLSocketFactory 来创建，或通过从 SSLServerSocket 接受 一个连接来创建。

SSL 套接字必须选择以客户端还是服务器模式操作。这决定了谁来开始握手过程和每一方应该发送哪种报文。每个连接都必须有一个客户端和一个服务器端，否则握手将不能正确地进行。一旦初始握手开始，套接字就不能在客户端和服务器模式间转换，甚至在执行重新协商时也不能。

从以下版本开始：

1.4

另请参见：

Socket, SSLServerSocket, SSLSocketFactory

构造方法摘要

protected	SSLSocket() 仅供子类使用。
protected	SSLSocket(InetAddress address, int port) 仅供子类使用。
protected	SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort) 仅供子类使用。
protected	SSLSocket(String host, int port) 仅供子类使用。
protected	SSLSocket(String host, int port, InetAddress clientAddress, int clientPort) 仅供子类使用。

方法摘要

abstract void	addHandshakeCompletedListener(HandshakeCompletedListener listener) 注册一个事件侦听器来接收此连接上的 SSL 握手已经结束的通知。
abstract String[]	getEnabledCipherSuites() 返回在为了此连接中使用而在当前启用的密码套件的名称。
abstract String[]	getEnabledProtocols() 返回当前启用的在此连接上使用的协议的版本名称。
abstract boolean	getEnableSessionCreation() 如果新 SSL 会话可以使用此套接字建立，则返回 true。
abstract boolean	getNeedClientAuth() 如果套接字要求 客户端身份验证，则返回 true。
abstract SSLSession	getSession() 返回此连接使用的 SSL Session。
abstract String[]	getSupportedCipherSuites() 返回在此连接中为了使用可以被启用的密码套件的名称。
abstract String[]	getSupportedProtocols() 返回能够被启用在 SSL 连接上使用的协议的名称。
abstract boolean	getUseClientMode() 如果套接字设置为握手时使用客户端模式，则返回 true。
abstract boolean	getWantClientAuth() 如果套接字请求 客户端身份验证，则返回 true。
abstract void	removeHandshakeCompletedListener(HandshakeCompletedListener listener) 移除一个以前注册的握手完成侦听器。
abstract void	setEnabledCipherSuites(String[] suites) 把密码套件设置为启用的以便在此连接上使用。
abstract void	setEnabledProtocols(String[] protocols) 设置为了在此连接上使用而启用的协议的版本。
abstract void	setEnableSessionCreation(boolean flag) 控制是否新 SSL 可以使用此套接字建立。
abstract void	setNeedClientAuth(boolean need) 配置套接字要求 客户端身份验证。
abstract void	setUseClientMode(boolean mode) 配置套接字以便握手时使用客户端（或服务器）模式。
abstract void	setWantClientAuth(boolean want) 配置套接字请求 客户端身份验证。
abstract void	startHandshake() 在此连接上开始 SSL 握手。

从类 java.net.Socket 继承的方法

bind, close, connect, connect, getChannel, getInetAddress, getInputStream, getKeepAlive, getLocalAddress, getLocalPort, getLocalSocketAddress, getOOBInline, getOutputStream, getPort, getReceiveBufferSize, getRemoteSocketAddress, getReuseAddress, getSendBufferSize, getSoLinger, getSoTimeout, getTcpNoDelay, getTrafficClass, isBound, isClosed, isConnected, isInputShutdown, isOutputShutdown, sendUrgentData, setKeepAlive, setOOBInline, setPerformancePreferences, setReceiveBufferSize, setReuseAddress, setSendBufferSize, setSocketImplFactory, setSoLinger, setSoTimeout, setTcpNoDelay, setTrafficClass, shutdownInput, shutdownOutput, toString

从类 java.lang.Object 继承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

构造方法详细信息

SSLSocket

protected SSLSocket()

仅供子类使用。创建未初始化的、未连接的 TCP 套接字。

SSLSocket

protected SSLSocket(String host,
                    int port)
             throws IOException,
                    UnknownHostException

仅供子类使用。创建一个到指定端口上的命名主机的 TCP 连接。它充当 SSL 客户端。

参数：

host - 要连接的主机的名称

port - 服务器的端口号

抛出：

IOException - 当创建套接字时出现 I/O 错误

UnknownHostException - 如果不能识别主机

SSLSocket

protected SSLSocket(InetAddress address,
                    int port)
             throws IOException

仅供子类使用。创建一个到指定地址和端口上的服务器的 TCP 连接。它充当 SSL 客户端。

参数：

address - 服务器的主机

port - 服务器主机的端口

抛出：

IOException - 当创建套接字时出现 I/O 错误。

SSLSocket

protected SSLSocket(String host,
                    int port,
                    InetAddress clientAddress,
                    int clientPort)
             throws IOException,
                    UnknownHostException

仅供子类使用。创建一个到指定端口上的命名主机的 SSL 连接，把给定的地址和端口号绑定到客户端的连接。它充当 SSL 客户端。

参数：

host - 要连接的主机的名称

port - 服务器的端口号

clientAddress - 客户端主机

clientPort - 客户端的端口号

抛出：

IOException - 当创建套接字时出现 I/O 错误

UnknownHostException - 如果不能识别主机

SSLSocket

protected SSLSocket(InetAddress address,
                    int port,
                    InetAddress clientAddress,
                    int clientPort)
             throws IOException

仅供子类使用。创建一个到指定地址和 TCP 端口上的服务器的 SSL 连接，把给定地址和端口号绑定到客户端的连接。它充当 SSL 客户端。

参数：

address - 服务器主机

port - 服务器主机的端口

clientAddress - 客户端主机

clientPort - 客户端端口号

抛出：

IOException - 当创建套接字时出现 I/O 错误

方法详细信息

getSupportedCipherSuites

public abstract String[] getSupportedCipherSuites()

返回在此连接中为了使用可以被启用的密码套件的名称。通常，因为此列表可能包含不能满足这些默认值的服务质量要求的密码套件，所以默认情况下只能实际启用它们的子集。这种密码套件在特定的应用程序中有用。

返回：

密码套件名称的数组

另请参见：

getEnabledCipherSuites(), setEnabledCipherSuites(String [])

getEnabledCipherSuites

public abstract String[] getEnabledCipherSuites()

返回在为了此连接中使用而在当前启用的密码套件的名称。当 SSLSocket 第一次被创建时，所有启用的密码套件支持最低的服务质量。因此，在某些环境中此值可能为空。

即使密码套件已经被启用，它可能从不被使用。（例如，对等方不支持它、密码套件必须的证书（私钥）不可用或启用了匿名的密码套件但需要进行身份验证。）

返回：

密码套件名称的数组

另请参见：

getSupportedCipherSuites(), setEnabledCipherSuites(String [])

setEnabledCipherSuites

public abstract void setEnabledCipherSuites(String[] suites)

把密码套件设置为启用的以便在此连接上使用。

suites 参数中的每个密码套件都必须已经使用 getSupportedCipherSuites() 列表，否则方法会失败。在成功的调用此方法之后，只有在 suites 参数中列出的套件才被启用以便使用。

关于为什么一个密码套件在连接上从来不被使用的更多信息请参见 getEnabledCipherSuites()。

参数：

suites - 将被启用的所有密码套件的名称

抛出：

IllegalArgumentException - 当一个或多个由参数命名的密码套件不被支持时，或当参数为 null时。

另请参见：

getSupportedCipherSuites(), getEnabledCipherSuites()

getSupportedProtocols

public abstract String[] getSupportedProtocols()

返回能够被启用在 SSL 连接上使用的协议的名称。

返回：

所支持的协议的数组

getEnabledProtocols

public abstract String[] getEnabledProtocols()

返回当前启用的在此连接上使用的协议的版本名称。

返回：

协议的数组

另请参见：

setEnabledProtocols(String [])

setEnabledProtocols

public abstract void setEnabledProtocols(String[] protocols)

设置为了在此连接上使用而启用的协议的版本。

协议必须已经作为被支持的协议使用 getSupportedProtocols() 列表。在成功的调用此方法之后，只有在 protocols 参数中列出的协议才被启用以便使用。

参数：

protocols - 将被启用的所有协议的名称。

抛出：

IllegalArgumentException - 当一个或多个由参数命名的协议不被支持时，或 protocols 参数为 null时。

另请参见：

getEnabledProtocols()

getSession

public abstract SSLSession getSession()

返回此连接使用的 SSL Session。这些可以是持久的，并且相应于某个用户的整个登录会话过程。该会话指定了会话中所有连接主动使用的特定密码套件，以及该会话的客户端和服务器标识。

如有必要此方法将开始初始握手然后阻塞直到握手已经建立。

如果在初始握手期间出现错误，则此方法返回一个无效的会话对象，该对象报告了一个无效的密码套件 "SSL_NULL_WITH_NULL_NULL"。

返回：

SSLSession

addHandshakeCompletedListener

public abstract void addHandshakeCompletedListener(HandshakeCompletedListener listener)

注册一个事件侦听器来接收此连接上的 SSL 握手已经结束的通知。

参数：

listener - HandShake Completed 事件侦听器

抛出：

IllegalArgumentException - 如果参数为 null。

另请参见：

startHandshake(), removeHandshakeCompletedListener(HandshakeCompletedListener)

removeHandshakeCompletedListener

public abstract void removeHandshakeCompletedListener(HandshakeCompletedListener listener)

移除一个以前注册的握手完成侦听器。

参数：

listener - HandShake Completed 事件侦听器

抛出：

IllegalArgumentException - 如果没有注册此侦听器，或参数为 null。

另请参见：

addHandshakeCompletedListener(HandshakeCompletedListener)

startHandshake

public abstract void startHandshake()
                             throws IOException

在此连接上开始 SSL 握手。常见的原因包括使用新的加密密钥的需要、改变密码套件的需要或开始新的会话的需要。为了强制进行重新身份验证，可以在开始握手之前使当前的会话无效。

如果数据已经在连接上发送，则在握手期间数据继续流动。当握手结束时，将使用事件来通知。 此方法对于连接上的初始握手是同步的并且在协商的握手结束时返回。一些协议可能不支持在一个已经存在的套接字上的多次握手，可能抛出 SSLException。

抛出：

IOException - 关于网络级别的错误

另请参见：

addHandshakeCompletedListener(HandshakeCompletedListener)

setUseClientMode

public abstract void setUseClientMode(boolean mode)

配置套接字以便握手时使用客户端（或服务器）模式。

此方法必须在任何握手出现之前调用。一旦握手开始，在此套接字的生命期内模式都不能被设置。

服务器通常会对自己进行身份验证，对于客户端则不要求这么做。

参数：

mode - 如果套接字应该以 "client" 模式开始它的握手，此参数为 true

抛出：

IllegalArgumentException - 如果初始握手开始后试图改变模式。

另请参见：

getUseClientMode()

getUseClientMode

public abstract boolean getUseClientMode()

如果套接字设置为握手时使用客户端模式，则返回 true。

返回：

如果套接字应该以 "client" 模式进行握手，则返回 true

另请参见：

setUseClientMode(boolean)

setNeedClientAuth

public abstract void setNeedClientAuth(boolean need)

配置套接字要求 客户端身份验证。此选项只对服务器模式的套接字有用。

套接字的客户端身份验证设置是下面的其中之一:

• 必需的客户端身份验证
• 请求的客户端身份验证
• 不需要客户端身份验证

与 setWantClientAuth(boolean) 不同，如果设置了此选项并且客户端选择不提供关于自己的身份验证信息，协商将会停止且连接将被终止。

调用此方法会重写由此方法 或 setWantClientAuth(boolean) 所做的任何以前的设置。

参数：

need - 如果要求客户端身份验证设置，则为 true；如果不需要客户端身份验证设置，则为 false。

另请参见：

getNeedClientAuth(), setWantClientAuth(boolean), getWantClientAuth(), setUseClientMode(boolean)

getNeedClientAuth

public abstract boolean getNeedClientAuth()

如果套接字要求 客户端身份验证，则返回 true。此选项只对服务器模式的套接字有用。

返回：

如果要求客户端身份验证，返回 true；如果不需要客户端身份验证，则返回 false。

另请参见：

setNeedClientAuth(boolean), setWantClientAuth(boolean), getWantClientAuth(), setUseClientMode(boolean)

setWantClientAuth

public abstract void setWantClientAuth(boolean want)

配置套接字请求 客户端身份验证。此选项只对服务器模式的套接字有用。

套接字的客户端身份验证设置是下面的其中之一:

• 必需的客户端身份验证
• 请求的客户端身份验证
• 不需要客户端身份验证

与 setNeedClientAuth(boolean) 不同，如果设置了此选项并且客户端选择不提供其自身的身份验证信息，则协商将会继续。

调用此方法会重写由此方法或 setNeedClientAuth(boolean) 以前所做的任何设置。

参数：

want - 如果请求进行客户端身份验证，则设置为 true；如果不需要客户端身份验证，则设置为 false。

另请参见：

getWantClientAuth(), setNeedClientAuth(boolean), getNeedClientAuth(), setUseClientMode(boolean)

getWantClientAuth

public abstract boolean getWantClientAuth()

如果套接字请求 客户端身份验证，则返回 true。此选项只对服务器模式的套接字有用。

返回：

如果请求进行客户端身份验证，则返回 true；如果不需要客户端身份验证，则返回 false。

另请参见：

setNeedClientAuth(boolean), getNeedClientAuth(), setWantClientAuth(boolean), setUseClientMode(boolean)

setEnableSessionCreation

public abstract void setEnableSessionCreation(boolean flag)

控制是否新 SSL 可以使用此套接字建立。如果不允许创建会话，也没有可以恢复的现有会话，则不会有成功的握手。

参数：

flag - 为 true 时指示会话可以被创建；这是默认的；为 false 时指示有一个存在的会话必须被恢复

另请参见：

getEnableSessionCreation()

getEnableSessionCreation

public abstract boolean getEnableSessionCreation()

如果新 SSL 会话可以使用此套接字建立，则返回 true。

返回：

返回值为 true 时指示会话可以被创建；这是默认的；返回值为 false 时指示有一个存在的会话必须被恢复

另请参见：

setEnableSessionCreation(boolean)