javax.net.ssl
類別 SSLSocket

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

public abstract class SSLSocket
extends Socket

此類別擴展 Socket 並提供使用諸如安全Socket層 (Secure Sockets Layer, SSL) 或 IETF 傳輸層安全性 (Transport Layer Security, TLS) 等協議的安全Socket。

這種Socket是普通的串流Socket，只不過它們在底層網路傳輸協議（如 TCP）上添加了安全保護層。這些保護包括：

• 完整性保護。SSL 可以防止訊息被主動的竊聽者修改。
• 驗證。在多數網要下，SSL 提供對等驗證。伺服器通常要進行驗證，客戶機可以根據伺服器的請求進行驗證。
• 機密性（私有性保護）。在多數網要下，SSL 加密在客戶機和伺服器之間發送的資料。這保護了資料的機密性，所以被動的竊聽者不能看到各種型別的敏感資料，如財務資訊或個人資訊。

這些保護由一個“密碼套件”指定，“密碼套件”是給定的 SSL 連接所使用的加密演算法組合。在協商過程中，兩個端點必須對可用於雙方環境的密碼套件達成一致。如果不存在這種公共的套件，就不能建立 SSL 連接，也不能交換資料。

通過稱為“連繫交換”的協商過程可建立所用的密碼套件。此過程的目的是創建或重新加入一個“Session”，“Session”可以防止多個連接逾時。連繫交換完成後，可以使用 getSession 方法存取Session的屬性。此連接上最初的連繫交換可以用以下三種方式開始：

• 調用 startHandshake 顯式地開始連繫交換，或者
• 任何在此Socket上讀取或寫入應用資料的嘗試將引起隱式連繫交換，或者
• 調用 getSession 嘗試建立Session（如果當前不存在有效的Session）將進行隱式連繫交換。

如果連繫交換由於某些原因失敗，則 SSLSocket 將關閉，不進行更多通信。

管理密碼套件時需要知道以下兩組密碼套件：

• 支持的 密碼套件：SSL 實作支持的所有套件。使用 getSupportedCipherSuites 報告此列表。
• 啟用的 密碼套件，它可少於完整的支持套件集。此組使用 setEnabledCipherSuites 方法設置，使用 getEnabledCipherSuites 方法查詢。最初，在表示最低建議配置的新Socket上啟用預設的密碼套件集。

預設情況下，實作要求只預設啟用那些可對伺服器進行驗證並提供機密性的密碼套件。只有雙方明確同意非驗證和/或非私有的（未加密的）的通信時才選擇這種密碼套件。

第一次創建 SSLSocket 時不進行連繫交換，從而應用程序可以首先設置它們的通信首選項：使用哪個密碼套件、Socket應該為客戶機還是伺服器網要等。但是，應用資料在連接上發送時始終提供安全性。

可以進行註冊以便接收連繫交換結束的事件通知。這涉及到另外兩個類別的使用。HandshakeCompletedEvent 物件會被傳遞到由此 API 的使用者所註冊 HandshakeCompletedListener 實例。 SSLSocket 通過 SSLSocketFactory 創建，或通過從 SSLServerSocket 接受 一個連接來創建。

SSL Socket必須選擇以客戶機還是伺服器網要操作。這將決定誰來開始連繫交換過程，以及每一方應該發送哪種報文。每個連接都必須有一個客戶機和一個伺服器，否則連繫交換將無法正確進行。初始連繫交換開始後，Socket就不能在客戶機和伺服器網要間轉換，即使在執行重新協商時也不能。

從以下版本開始：

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() 如果可以使用此Socket建立新的 SSL Session，則返回 true。
abstract boolean	getNeedClientAuth() 如果Socket要求 客戶機驗證，則返回 true。
abstract SSLSession	getSession() 返回此連接使用的 SSL Session。
SSLParameters	getSSLParameters() 返回對此 SSLSocket 有效的 SSLParameters。
abstract String[]	getSupportedCipherSuites() 返回可以啟用以供此連接使用的密碼套件的名稱。
abstract String[]	getSupportedProtocols() 返回能夠被啟用以供 SSL 連接使用的協議的名稱。
abstract boolean	getUseClientMode() 如果Socket設置為連繫交換時使用客戶機網要，則返回 true。
abstract boolean	getWantClientAuth() 如果Socket請求 客戶機驗證，則返回 true。
abstract void	removeHandshakeCompletedListener(HandshakeCompletedListener listener) 移除一個以前註冊的連繫交換完成偵聽器。
abstract void	setEnabledCipherSuites(String[] suites) 將密碼套件設置為啟用以供此連接使用。
abstract void	setEnabledProtocols(String[] protocols) 設置啟用以供此連接使用的協議版本。
abstract void	setEnableSessionCreation(boolean flag) 控制是否可以使用此Socket建立新的 SSL Session。
abstract void	setNeedClientAuth(boolean need) 配置Socket要求 客戶機驗證。
void	setSSLParameters(SSLParameters params) 對此Socket應用 SSLParameters。
abstract void	setUseClientMode(boolean mode) 配置Socket在連繫交換時使用客戶機（或伺服器）網要。
abstract void	setWantClientAuth(boolean want) 配置Socket請求 客戶機驗證。
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 Socket。

SSLSocket

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

僅供子類別使用。建構一個到指定埠號指定主機的 TCP 連接。它充當 SSL 客戶機。

參數：

host - 要連接的主機的名稱

port - 伺服器的埠號號

拋出：

IOException - 如果創建Socket時發生 I/O 錯誤

UnknownHostException - 如果主機是未知的

SSLSocket

protected SSLSocket(InetAddress address,
                    int port)
             throws IOException

僅供子類別使用。建構一個到指定位址和埠號的伺服器的 TCP 連接。它充當 SSL 客戶機。

參數：

address - 伺服器的主機

port - 伺服器主機的埠號

拋出：

IOException - 如果創建Socket時發生 I/O 錯誤。

SSLSocket

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

僅供子類別使用。建構一個到指定埠號指定主機的 SSL 連接，將給定的位址和埠號綁定到連接的客戶機那端。它充當 SSL 客戶機。

參數：

host - 要連接的主機的名稱

port - 伺服器的埠號號

clientAddress - 客戶機的主機

clientPort - 客戶機的埠號號

拋出：

IOException - 如果創建Socket時發生 I/O 錯誤

UnknownHostException - 如果主機是未知的

SSLSocket

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

僅供子類別使用。建構一個到指定位址和 TCP 埠號的伺服器的 SSL 連接，將給定位址和埠號綁定到連接的客戶機那端。它充當 SSL 客戶機。

參數：

address - 伺服器主機

port - 伺服器主機的埠號

clientAddress - 客戶機的主機

clientPort - 客戶機埠號號

拋出：

IOException - 如果創建Socket時發生 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 Session。它可以是持久Session，並且通常對應於某個使用者的整個登錄Session過程。該Session指定一個Session中所有連接主動使用的特定密碼套件，以及Session客戶機和伺服器的標識。

此方法將發起初始連繫交換（如有必要），然後阻塞，直到連繫交換已經建立。

如果在初始連繫交換期間出現錯誤，則此方法返回一個無效的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 - 「連繫交換已完成」事件偵聽器

拋出：

IllegalArgumentException - 如果沒有註冊此偵聽器，或參數為 null。

另請參見：

addHandshakeCompletedListener(HandshakeCompletedListener)

startHandshake

public abstract void startHandshake()
                             throws IOException

在此連接上開始 SSL 連繫交換。這樣做通常是因為需要使用新的加密密鑰、需要更改密碼套件或開始新的Session。若要強制完成重新驗證，可以在開始此連繫交換之前使當前Session無效。

如果資料已經在連接上發送，則在此連繫交換期間資料繼續串流動。當連繫交換完成時，將使用事件來通知。 此方法對於連接上的初始連繫交換是同步的，它在協商的連繫交換完成時返回。一些協議可能不支持在一個已經存在的Socket上的多次連繫交換，並可能拋出 SSLException。

拋出：

IOException - 如果發生網路級別的錯誤

另請參見：

addHandshakeCompletedListener(HandshakeCompletedListener)

setUseClientMode

public abstract void setUseClientMode(boolean mode)

配置Socket在連繫交換時使用客戶機（或伺服器）網要。

此方法必須在發生任何連繫交換之前調用。一旦連繫交換開始，在此Socket的生存期內將不能再重置網要。

伺服器通常會驗證本身，客戶機則不要求這麼做。

參數：

mode - 如果Socket應該以「客戶機」網要開始它的連繫交換，此參數為 true

拋出：

IllegalArgumentException - 如果初始連繫交換開始後試圖更改網要。

另請參見：

getUseClientMode()

getUseClientMode

public abstract boolean getUseClientMode()

如果Socket設置為連繫交換時使用客戶機網要，則返回 true。

返回：

如果Socket應該以「客戶機」網要進行連繫交換，則返回 true

另請參見：

setUseClientMode(boolean)

setNeedClientAuth

public abstract void setNeedClientAuth(boolean need)

配置Socket要求 客戶機驗證。此選項只對伺服器網要的Socket有用。

Socket的客戶機驗證設置是以下之一:

• 要求的客戶機驗證
• 請求的客戶機驗證
• 不需要客戶機驗證

與 setWantClientAuth(boolean) 不同，如果設置了此選項並且客戶機選擇不提供關於本身的驗證資訊，協商將會停止且連接將被終止。

調用此方法會覆寫由此方法或 setWantClientAuth(boolean) 以前所做的任何設置。

參數：

need - 如果要求客戶機驗證設置，則為 true；如果不需要客戶機驗證設置，則為 false。

另請參見：

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

getNeedClientAuth

public abstract boolean getNeedClientAuth()

如果Socket要求 客戶機驗證，則返回 true。此選項只對伺服器網要的Socket有用。

返回：

如果要求客戶機驗證，返回 true；如果不需要客戶機驗證，則返回 false。

另請參見：

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

setWantClientAuth

public abstract void setWantClientAuth(boolean want)

配置Socket請求 客戶機驗證。此選項只對伺服器網要的Socket有用。

Socket的客戶機驗證設置是以下之一:

• 要求的客戶機驗證
• 請求的客戶機驗證
• 不需要客戶機驗證

與 setNeedClientAuth(boolean) 不同，如果設置了此選項並且客戶機選擇不提供關於本身的驗證資訊，則協商將會繼續。

調用此方法會覆寫由此方法或 setNeedClientAuth(boolean) 以前所做的任何設置。

參數：

want - 如果請求進行客戶機驗證，則設置為 true；如果不需要客戶機驗證，則設置為 false。

另請參見：

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

getWantClientAuth

public abstract boolean getWantClientAuth()

如果Socket請求 客戶機驗證，則返回 true。此選項只對伺服器網要的Socket有用。

返回：

如果請求進行客戶機驗證，則返回 true；如果不需要客戶機驗證，則返回 false。

另請參見：

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

setEnableSessionCreation

public abstract void setEnableSessionCreation(boolean flag)

控制是否可以使用此Socket建立新的 SSL Session。如果不允許創建Session，也沒有可以恢復的現有Session，則連繫交換不會成功。

參數：

flag - 如果為 true，則指示可以創建Session，這是預設設置；如果為 false，則指示必須恢復一個現有的Session

另請參見：

getEnableSessionCreation()

getEnableSessionCreation

public abstract boolean getEnableSessionCreation()

如果可以使用此Socket建立新的 SSL Session，則返回 true。

返回：

如果為 true，則指示可以創建Session，這是預設設置；如果為 false，則指示必須恢復一個現有的Session

另請參見：

setEnableSessionCreation(boolean)

getSSLParameters

public SSLParameters getSSLParameters()

返回對此 SSLSocket 有效的 SSLParameters。返回的 SSLParameters 的密碼套件和協議始終不為 null。

返回：

對此 SSLSocket 有效的 SSLParameters。

從以下版本開始：

1.6

setSSLParameters

public void setSSLParameters(SSLParameters params)

對此Socket應用 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