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 对象会被传递到由此 API 的用户所注册 HandshakeCompletedListener 实例。 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() 返回当前启用以供此连接使用的 SSL 密码套件的名称。
abstract String[]	getEnabledProtocols() 返回当前启用以供此连接使用的协议版本的名称。
abstract boolean	getEnableSessionCreation() 如果可以使用此套接字建立新的 SSL 会话，则返回 true。
abstract boolean	getNeedClientAuth() 如果套接字要求 客户机验证，则返回 true。
abstract SSLSession	getSession() 返回此连接使用的 SSL 会话。
SSLParameters	getSSLParameters() 返回对此 SSLSocket 有效的 SSLParameters。
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) 配置套接字要求 客户机验证。
void	setSSLParameters(SSLParameters params) 对此套接字应用 SSLParameters。
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()

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

即使密码套件已经被启用，也可能不会使用它。例如，同位体不支持它、密码套件必需的证书（私钥）不可用、启用了匿名的密码套件但需要进行验证等。

返回：

密码套件名称数组

另请参见：

getSupportedCipherSuites(), setEnabledCipherSuites(String [])

setEnabledCipherSuites

public abstract void setEnabledCipherSuites(String[] suites)

将密码套件设置为启用以供此连接使用。

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

有的密码套件从不被连接使用，有关其原因的更多信息，请参见 getEnabledCipherSuites()。

参数：

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

抛出：

IllegalArgumentException - 如果由参数指定的一个或多个协议不受支持，或 protocols 参数为 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 会话。它可以是持久会话，并且通常对应于某个用户的整个登录会话过程。该会话指定一个会话中所有连接主动使用的特定密码套件，以及会话客户机和服务器的标识。

此方法将发起初始握手（如有必要），然后阻塞，直到握手已经建立。

如果在初始握手期间出现错误，则此方法返回一个无效的会话对象，该对象会报告一个无效的密码套件 "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 - “握手已完成”事件侦听器

抛出：

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

另请参见：

addHandshakeCompletedListener(HandshakeCompletedListener)

startHandshake

public abstract void startHandshake()
                             throws IOException

在此连接上开始 SSL 握手。这样做通常是因为需要使用新的加密密钥、需要更改密码套件或开始新的会话。若要强制完成重新验证，可以在开始此握手之前使当前会话无效。

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

抛出：

IOException - 如果发生网络级别的错误

另请参见：

addHandshakeCompletedListener(HandshakeCompletedListener)

setUseClientMode

public abstract void setUseClientMode(boolean mode)

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

此方法必须在发生任何握手之前调用。一旦握手开始，在此套接字的生存期内将不能再重置模式。

服务器通常会验证本身，客户机则不要求这么做。

参数：

mode - 如果套接字应该以“客户机”模式开始它的握手，此参数为 true

抛出：

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

另请参见：

getUseClientMode()

getUseClientMode

public abstract boolean getUseClientMode()

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

返回：

如果套接字应该以“客户机”模式进行握手，则返回 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)

getSSLParameters

public SSLParameters getSSLParameters()

返回对此 SSLSocket 有效的 SSLParameters。返回的 SSLParameters 的密码套件和协议始终不为 null。

返回：

对此 SSLSocket 有效的 SSLParameters。

从以下版本开始：

1.6

setSSLParameters

public void setSSLParameters(SSLParameters params)

对此套接字应用 SSLParameters。

这意味着：

• 如果 params.getCipherSuites() 不为 null，则使用该值调用 setEnabledCipherSuites()
• 如果 params.getProtocols() 不为 null，则使用该值调用 setEnabledProtocols()
• 如果 params.getNeedClientAuth() 或 params.getWantClientAuth() 返回 true，则分别调用 setNeedClientAuth(true) 和 setWantClientAuth(true)；否则调用 setWantClientAuth(false)。

参数：

params - 参数

抛出：

IllegalArgumentException - 如果 setEnabledCipherSuites() 或 setEnabledProtocols() 调用失败

从以下版本开始：

1.6