SSLEngine (Java 2 Platform SE 6)

概觀

軟體套件

類別

使用

階層樹

已過時

索引

說明

Java^TM 2 Platform
Standard Ed. 6

上一個類別 下一個類別

框架 無框架

摘要：巢狀 | 欄位 | 建構子 | 方法

詳細資訊：欄位 | 建構子 | 方法

javax.net.ssl
類別 SSLEngine

java.lang.Object
  javax.net.ssl.SSLEngine

public abstract class SSLEngine
extends Object
extends Object

此類別允許使用安全Socket層 (SSL) 或 IETF RFC 2246 "Transport Layer Security" (TLS) 協議進行安全通信，但它與傳輸無關。

安全的通信網要包括：

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

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

通過稱為“連繫交換”的協商過程來建立所用的密碼套件。此過程的目的是創建或重新加入一個“Session”，“Session”可以保護很多Session過程中的連接。連繫交換結束後，可以使用 getSession() 方法存取Session的屬性。

SSLSocket 類別提供很多相同的安全功能，但是所有的入站和出站資料都是使用底層 Socket 自動地傳輸，底層 Socket 設計為使用阻塞模型。雖然這適合於很多應用程序，但是此模型卻不提供大型伺服器所需的可伸縮性。

SSLEngine 的主要特徵是它在入站和出站的位元組串流上操作，與傳輸機制無關。安排到同位體可靠的 I/O 傳輸是 SSLEngine 使用者的職責。通過從 I/O 傳輸機制中分離出 SSL/TLS 抽象，SSLEngine 可以被用於各種 I/O 型別，例如 non-blocking I/O (polling)、selectable non-blocking I/O、 Socket 和傳統的 Input/OutputStreams、本地的 ByteBuffers 或位元組陣列、未來的非同步 I/O 模型等等。

從較高的層次上看，SSLEngine 表示為如下：

                   app data

                |           ^
                |     |     |
                v     |     |
           +----+-----|-----+----+
           |          |          |
           |       SSL|Engine    |
   wrap()  |          |          |  unwrap()
           | OUTBOUND | INBOUND  |
           |          |          |
           +----+-----|-----+----+
                |     |     ^
                |     |     |
                v           |

                   net data

應用程序資料（也稱為純文本或明文）是應用程序產生或使用的資料。它的對應物是網路資料，它由連繫交換和/或密文（加密的）資料組成，並且注定要通過 I/O 機制傳輸。入站資料指的是從同位體接收的資料，出站資料是去往同位體的資料。

（在 SSLEngine 上下文中，術語“連繫交換資料”的意思是所有用來建立和控制安全連接的已交換資料。連繫交換資料封包括 SSL/TLS 訊息 "alert"、"change_cipher_spec" 和 "handshake。"）

SSLEngine 有五種不同的階段。

創建 - 已經創建和初始化 SSLEngine，但尚未被使用。在此階段，應用程序可以設置任何特定於 SSLEngine 的設置（啟用密碼套件、SSLEngine 應該以客戶端還是伺服器網要連繫交換等等）。一旦連繫交換開始，任何新的設置（除了客戶端/伺服器網要，見下文）將在下一次連繫交換時才被使用。
初始連繫交換 - 初始連繫交換是兩個同位體交換通信參數，直到建立 SSLSession 為止的過程。在此階段不能發送應用程序資料。
應用程序資料 - 一旦通信參數建立起來且連繫交換完成，就可以通過 SSLEngine 傳輸應用程序資料。出站的應用程序報文被加密並進行完整性保護，入站的報文進行相反的過程。
重新連繫交換 - 在應用程序資料階段的任何時間，每一方都可以請求重新協商Session。新的連繫交換資料可以混入到應用程序資料中。在開始重新連繫交換階段之前，應用程序可以重置 SSL/TLS 通信參數，例如已啟用的密碼套件列表和是否使用客戶端驗證，但是不能更改客戶端/伺服器網要。如前所述，一旦連繫交換開始，任何新的 SSLEngine 配置設置都將在下一次連繫交換時才被使用。
關閉 - 當不再需要連接時，應用程序應該關閉 SSLEngine，並且也應該在關閉底層傳輸機制之前發送/接收所有剩餘的報文到同位體。一旦引擎關閉，它就是不可重用的：必須創建一個新的 SSLEngine。

根據已初始化的 SSLContext 來調用 SSLContext.createSSLEngine() 即可創建 SSLEngine。在第一次調用 wrap()、unwrap() 或 beginHandshake() 之前應該設置所有的配置參數。這些方法都能觸發初始連繫交換。

分別對出站或入站資料調用 wrap() 或 unwrap() 可使資料通過引擎。根據 SSLEngine 的狀態，對 wrap() 的調用可能使用源緩衝區的應用程序資料，並且可能在目標緩衝區內產生網路資料。出站資料可以包含應用程序和/或連繫交換資料。對 unwrap() 的調用將檢查源緩衝區，如果資料是連繫交換資訊，則可能提前連繫交換；如果資料是應用程序資料，則將其放入目標緩衝區中。底層 SSL/TLS 演算法的狀態將決定何時使用和產生資料。

調用 wrap() 和 unwrap() 返回 SSLEngineResult，它指示操作的狀態以及（可選的）如何與引擎交互以取得進展。

SSLEngine 只是產生/使用完整的 SSL/TLS 套件，它不在 wrap()/unwrap() 的調用之間內部存儲應用程序資料。因此輸入和輸出 ByteBuffer 必須設為合適的大小以便容納可能產生的最多記錄。要確定合適的緩衝區大小，應該調用 SSLSession.getPacketBufferSize() 和 SSLSession.getApplicationBufferSize()。通常無需考慮出站應用程序資料緩衝區的大小。如果緩衝區的狀況不允許正確地使用/產生資料，則應用程序必須加以確定（通過 SSLEngineResult）並糾正問題，然後再嘗試調用一次。

例如，如果引擎確定沒有足夠的目標緩衝區空間可用，則 unwrap() 將返回 SSLEngineResult.Status.BUFFER_OVERFLOW 結果。應用程序應該調用 SSLSession.getApplicationBufferSize() 並將該值與目標緩衝區中的可用空間進行比較，如有必要，可以擴大該緩衝區。類似地，如果 unwrap() 返回 SSLEngineResult.Status.BUFFER_UNDERFLOW，則應用程序應調用 SSLSession.getPacketBufferSize() 以確保源緩衝區有足夠的空間來容納記錄（如有必要，可以擴大該緩衝區），然後獲得更多的入站資料。

   SSLEngineResult r = engine.unwrap(src, dst);
   switch (r.getStatus()) {
   BUFFER_OVERFLOW:
       // Could attempt to drain the dst buffer of any already obtained
       // data, but we'll just increase it to the size needed.
       int appSize = engine.getSession().getApplicationBufferSize();
       ByteBuffer b = ByteBuffer.allocate(appSize + dst.position());
       dst.flip();
       b.put(dst);
       dst = b;
       // retry the operation.
       break;
   BUFFER_UNDERFLOW:
       int netSize = engine.getSession().getPacketBufferSize();
       // Resize buffer if needed.
       if (netSize > dst.capacity()) {
           ByteBuffer b = ByteBuffer.allocate(netSize);
           src.flip();
           b.put(src);
           src = b;
       }
       // Obtain more inbound network data for src,
       // then retry the operation.
       break;
   // other cases: CLOSED, OK.
   }

與 SSLSocket 不同，SSLEngine 的所有方法都是非阻塞的。SSLEngine 實作所需的任務結果可能需要經過很長的時間才能獲得，甚至可能被阻塞。例如，TrustManager 可能需要連接到遠端的證書驗證服務，或者 KeyManager 可能需要提示使用者來確定將哪個證書用作客戶端驗證部分。另外，創建加密的簽章和驗證它們可能很慢，就好像阻塞一樣。

對於任何可能阻塞的操作，SSLEngine 將創建 Runnable 委託任務。當 SSLEngineResult 指示需要一個委託任務結果時，應用程序必須調用 getDelegatedTask() 來獲取一個未執行的委託任務並調用其 run() 方法（根據計算策略的不同，可能要使用不同的執行緒）。應用程序應該繼續獲取委託任務，直到沒有為止，然後再嘗試執行最初的操作。

在通信Session的結尾，應用程序應該正確地關閉 SSL/TLS 連接。SSL/TLS 協議有關閉連繫交換報文，這些報文應該在釋放 SSLEngine 並關閉底層傳輸機制之前傳送到同位體。通過以下某個方法可發起關閉：SSLException、入站的關閉連繫交換報文或某種 close 方法。在所有情況下，關閉連繫交換報文由引擎產生，在 SSLEngineResult 的狀態返回 "CLOSED"，或者 isOutboundDone() 返回 true 之前應該重複調用 wrap()。從 wrap() 方法獲得的所有資料都應該發送到同位體。

使用 closeOutbound() 通知引擎該應用程序將不再發送任何其他資料了。

同位體通過發送它自己的關閉連繫交換報文來通知它的關閉意圖。在此報文被本地 SSLEngine 的 unwrap() 調用接收和處理後，應用程序可檢測關閉，方法是調用 unwrap() 並尋找帶有狀態 "CLOSED" 的 SSLEngineResult，或者是 isInboundDone() 返回 true。如果由於某些原因使同位體關閉通信連接但沒有發送正確的 SSL/TLS 關閉報文，則應用程序可以檢測串流的末尾並且能夠通過 closeInbound() 來通知引擎沒有更多的入站報文需要處理。某些應用程序可能選擇要求同位體傳送有序的關閉報文，在這種情況下，它們能夠檢查出關閉是由連繫交換報文產生的，而不是由串流的末尾這種情況引起的。

有兩組密碼套件是您在管理密碼套件時需要知道的：

支持的密碼套件：SSL 實作支持的所有套件。使用 getSupportedCipherSuites() 來報告此列表。
啟用的密碼套件，它可少於完整的支持套件集。使用 setEnabledCipherSuites(String []) 方法設置此組套件，使用 getEnabledCipherSuites() 方法查詢它們。最初，在一個新引擎上啟用預設的密碼套件集，表示最低的建議配置。

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

每個 SSL/TLS 連接都必須有一個客戶端和一個伺服器，因此每一端必須決定擔任哪種角色。這種選擇決定了誰來開始連繫交換過程以及每一方應該發送哪種型別的報文。方法 setUseClientMode(boolean) 可配置網要。一旦初始連繫交換開始，SSLEngine 就不能在客戶端和伺服器網要間轉換，甚至在執行重新協商時也不能。

應用程序可能選擇在不同的執行緒中處理委託任務。當創建一個 SSLEngine 時，當前的 AccessControlContext 被保存。所有以後的委託任務都將使用此上下文來處理：也就是說，所有的存取控制決定都使用創建引擎時所捕獲的上下文來做出。

共時性要點：下面是需要知道的兩種共時性問題：

wrap() 和 unwrap() 方法可以互相共時執行。
SSL/TLS 協議使用有序的套件。應用程序必須小心保證產生的套件按順序傳遞。如果包無序到達，則可能出現不可預料的或災難性的結果。
例如：
```
                synchronized (outboundLock) {
                    sslEngine.wrap(src, dst);
                    outboundQueue.put(dst);
                }
        
```
做為必然的結果，兩個執行緒必須不能試圖共時地調用相同的方法（wrap() 或 unwrap()），因為沒有方法保證最後套件的排序。

從以下版本開始：: 1.5
另請參見：: SSLContext, SSLSocket, SSLServerSocket, SSLSession, Socket

建構子摘要
`protected`	`SSLEngine()` `SSLEngine` 的建構子，該建構子不為內部Session重用策略提供提示。
`protected`	`SSLEngine(String peerHost, int peerPort)` `SSLEngine` 的建構子。

方法摘要
`abstract void`	`beginHandshake()` 在此 SSLEngine 上發起連繫交換（初始的或重新協商）。
`abstract void`	`closeInbound()` 通知沒有更多的入站網路資料將發送到此 `SSLEngine`。
`abstract void`	`closeOutbound()` 通知沒有更多的出站應用程序資料將在此 `SSLEngine` 上發送。
`abstract Runnable`	`getDelegatedTask()` 返回此 `SSLEngine` 的一個委託 `Runnable` 任務。
`abstract String[]`	`getEnabledCipherSuites()` 返回為了在此引擎上使用而當前已啟用的 SSL 密碼套件名稱。
`abstract String[]`	`getEnabledProtocols()` 返回當前已啟用的，以便讓 `SSLEngine` 使用的協議版本的名稱。
`abstract boolean`	`getEnableSessionCreation()` 如果可以由此引擎建立新的 SSL Session，則返回 true。
`abstract SSLEngineResult.HandshakeStatus`	`getHandshakeStatus()` 返回此 `SSLEngine` 的當前連繫交換狀態。
`abstract boolean`	`getNeedClientAuth()` 如果引擎要求客戶端驗證，則返回 true。
`String`	`getPeerHost()` 返回同位體的主機名。
`int`	`getPeerPort()` 返回同位體的埠號號。
`abstract SSLSession`	`getSession()` 返回此 `SSLEngine` 中使用的 `SSLSession`。
`SSLParameters`	`getSSLParameters()` 返回對此 SSLEngine 有效的 SSLParameters。
`abstract String[]`	`getSupportedCipherSuites()` 返回為了在此引擎上使用而可以啟用的密碼套件名稱。
`abstract String[]`	`getSupportedProtocols()` 返回能夠被啟用，以便讓 `SSLEngine` 可使用的協議的名稱。
`abstract boolean`	`getUseClientMode()` 如果引擎設置為在連繫交換時使用客戶端網要，則返回 true。
`abstract boolean`	`getWantClientAuth()` 如果引擎請求客戶端驗證，則返回 true。
`abstract boolean`	`isInboundDone()` 返回 `unwrap(ByteBuffer, ByteBuffer)` 是否再接受更多的入站資料電報文。
`abstract boolean`	`isOutboundDone()` 返回 `wrap(ByteBuffer, ByteBuffer)` 是否再產生更多的出站資料電報文。
`abstract void`	`setEnabledCipherSuites(String[] suites)` 設置密碼套件為啟用，以便在此引擎上使用。
`abstract void`	`setEnabledProtocols(String[] protocols)` 設置為了在此引擎上使用而啟用的協議版本。
`abstract void`	`setEnableSessionCreation(boolean flag)` 控制是否可以由此引擎建立新的 SSL Session。
`abstract void`	`setNeedClientAuth(boolean need)` 配置引擎要求客戶端進行驗證。
`void`	`setSSLParameters(SSLParameters params)` 對此引擎應用 SSLParameters。
`abstract void`	`setUseClientMode(boolean mode)` 配置引擎在連繫交換時使用客戶端（或伺服器）網要。
`abstract void`	`setWantClientAuth(boolean want)` 配置引擎請求客戶端驗證。
`SSLEngineResult`	`unwrap(ByteBuffer src, ByteBuffer dst)` 嘗試把 SSL/TLS 網路資料解碼到純文本應用程序資料緩衝區中。
`SSLEngineResult`	`unwrap(ByteBuffer src, ByteBuffer[] dsts)` 嘗試把 SSL/TLS 網路資料解碼到純文本應用程序資料緩衝區序列中。
`abstract SSLEngineResult`	`unwrap(ByteBuffer src, ByteBuffer[] dsts, int offset, int length)` 嘗試把 SSL/TLS 網路資料解碼到純文本應用程序資料緩衝區子序列中。
`SSLEngineResult`	`wrap(ByteBuffer[] srcs, ByteBuffer dst)` 嘗試把資料緩衝區序列中的純文本位元組編碼成 SSL/TLS 網路資料。
`abstract SSLEngineResult`	`wrap(ByteBuffer[] srcs, int offset, int length, ByteBuffer dst)` 嘗試把資料緩衝區字序列中的純文本位元組編碼成 SSL/TLS 網路資料。
`SSLEngineResult`	`wrap(ByteBuffer src, ByteBuffer dst)` 試圖把緩衝區的純文本應用程序資料編碼成 SSL/TLS 網路資料。

從類別 java.lang.Object 繼承的方法
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

建構子詳細資訊

SSLEngine

protected SSLEngine()

SSLEngine 的建構子，該建構子不為內部Session重用策略提供提示。

另請參見：: SSLContext.createSSLEngine(), SSLSessionContext

SSLEngine

protected SSLEngine(String peerHost,
                    int peerPort)

SSLEngine 的建構子。

SSLEngine 實作可以使用 peerHost 和 peerPort 參數作為其內部Session重用策略的提示。

某些密碼套件（例如 Kerberos）需要遠端主機名資訊。為了使用 Kerberos，此類別的實作應該使用這種建構子。

該參數不由 SSLEngine 進行驗證。

參數：: peerHost - 同位體主機的名稱; peerPort - 同位體的埠號號
另請參見：: SSLContext.createSSLEngine(String, int), SSLSessionContext

方法詳細資訊

getPeerHost

public String getPeerHost()

返回同位體的主機名。

注意，該值未經驗證，不應該依賴它。

返回：: 同位體的主機名；如果沒有可供使用的主機名，則返回 null。

getPeerPort

public int getPeerPort()

返回同位體的埠號號。

注意，該值未經驗證，不應該依賴它。

返回：: 同位體的埠號號；如果沒有可供使用的埠號號，則返回 -1。

wrap

public SSLEngineResult wrap(ByteBuffer src,
                            ByteBuffer dst)
                     throws SSLException

試圖把緩衝區的純文本應用程序資料編碼成 SSL/TLS 網路資料。

調用此方法與調用下面的方法產生的行為完全相同：

 engine.wrap(new ByteBuffer [] { src }, 0, 1, dst);

參數：: src - 套件含出站應用程序資料的 ByteBuffer; dst - 保存出站網路資料的 ByteBuffer
返回：: 描述此次操作結果的 SSLEngineResult。
拋出：: SSLException - 如果處理資料時遇到的問題導致 SSLEngine 中止。關於引擎關閉的更多資訊，請參見該類別的描述。; ReadOnlyBufferException - 如果 dst 緩衝區是只讀的。; IllegalArgumentException - 如果 src 或 dst 為 null。; IllegalStateException - 如果沒有設置客戶端/伺服器網要。
另請參見：: wrap(ByteBuffer [], int, int, ByteBuffer)

wrap

public SSLEngineResult wrap(ByteBuffer[] srcs,
                            ByteBuffer dst)
                     throws SSLException

嘗試把資料緩衝區序列中的純文本位元組編碼成 SSL/TLS 網路資料。

調用此方法與調用下面的方法產生的行為完全相同：

 engine.wrap(srcs, 0, srcs.length, dst);

參數：: srcs - 套件含出站應用程序資料的 ByteBuffers 陣列; dst - 保存出站網路資料的 ByteBuffer
返回：: 描述此次操作結果的 SSLEngineResult。
拋出：: SSLException - 如果處理資料時遇到的問題導致 SSLEngine 中止。關於引擎關閉的更多資訊，請參見該類別的描述。; ReadOnlyBufferException - 如果 dst 緩衝區是只讀的。; IllegalArgumentException - 如果 srcs 或 dst 為 null，或者 srcs 中的任何元素為 null。; IllegalStateException - 如果沒有設置客戶端/伺服器網要。
另請參見：: wrap(ByteBuffer [], int, int, ByteBuffer)

wrap

public abstract SSLEngineResult wrap(ByteBuffer[] srcs,
                                     int offset,
                                     int length,
                                     ByteBuffer dst)
                              throws SSLException

嘗試把資料緩衝區字序列中的純文本位元組編碼成 SSL/TLS 網路資料。此“集中” 操作可在單個調用中對來自一個或多個給定緩衝區序列的位元組序列進行編碼。集中包裹通常在實作網路協議或檔案格式時很有用，例如將資料分組放入段中（這些段由一個或多個長度固定的頭，後跟長度可變的正文組成）。關於集中的更多資訊，請參見 GatheringByteChannel，有關子序列行為的更多資訊，請參見 GatheringByteChannel.write(ByteBuffer[], int, int)。

根據 SSLEngine 的狀態，此方法可能產生網路資料而不使用任何應用程序資料（例如，它可能產生連繫交換資料）。

應用程序負責把網路資料可靠地傳輸到同位體，同時也保證將多次調用 wrap() 所創建的資料以和它產生時相同的順序傳輸。應用程序必須正確地同步對此方法的多次調用。

如果此 SSLEngine 還沒有開始它的初始連繫交換，則此方法將自動開始進行連繫交換。

此方法將嘗試產生一個 SSL/TLS 套件，並使用盡可能多的源資料，但是使用的資料將從不會超過每個緩衝區中剩餘位元組的總和。會更新每個 ByteBuffer 的位置，以反映使用或產生的資料量。界限保持不變。

由 srcs 和 dst ByteBuffer 使用的底層記憶體必須不能相同。

關於引擎關閉的更多資訊，請參見該類別的描述。

參數：: srcs - 套件含出站應用程序資料的 ByteBuffers 陣列; offset - 第一個緩衝區（要獲取該緩衝區中的位元組）在緩衝區陣列中的偏移量；必須為非負數並且不能大於 srcs.length; length - 要存取的最大緩衝區編號；它必須為非負和不能大於 srcs.length - offset; dst - 保存出站網路資料的 ByteBuffer
返回：: 描述此次操作結果的 SSLEngineResult。
拋出：: SSLException - 如果處理資料時遇到的問題導致 SSLEngine 中止。關於引擎關閉的更多資訊，請參見該類別的描述。; IndexOutOfBoundsException - 如果關於 offset 和 length 參數的前提不成立。; ReadOnlyBufferException - 如果 dst 緩衝區是只讀的。; IllegalArgumentException - 如果 srcs 或 dst 為 null，或者指定的 srcs 子序列中的任何元素為 null。; IllegalStateException - 如果沒有設置客戶端/伺服器網要。
另請參見：: GatheringByteChannel, GatheringByteChannel.write( ByteBuffer[], int, int)

unwrap

public SSLEngineResult unwrap(ByteBuffer src,
                              ByteBuffer dst)
                       throws SSLException

嘗試把 SSL/TLS 網路資料解碼到純文本應用程序資料緩衝區中。

調用此方法與調用下面的方法產生的行為完全相同：

 engine.unwrap(src, new ByteBuffer [] { dst }, 0, 1);

參數：: src - 套件含入站網路資料的 ByteBuffer。; dst - 保存入站應用程序資料的 ByteBuffer。
返回：: 描述此次操作結果的 SSLEngineResult。
拋出：: SSLException - 如果處理資料時遇到的問題導致 SSLEngine 中止。關於引擎關閉的更多資訊，請參見該類別的描述。; ReadOnlyBufferException - 如果 dst 緩衝區是只讀的。; IllegalArgumentException - 如果 src 或 dst 為 null。; IllegalStateException - 如果沒有設置客戶端/伺服器網要。
另請參見：: unwrap(ByteBuffer, ByteBuffer [], int, int)

unwrap

public SSLEngineResult unwrap(ByteBuffer src,
                              ByteBuffer[] dsts)
                       throws SSLException

嘗試把 SSL/TLS 網路資料解碼到純文本應用程序資料緩衝區序列中。

調用此方法與調用下面的方法產生的行為完全相同：

 engine.unwrap(src, dsts, 0, dsts.length);

參數：: src - 套件含入站網路資料的 ByteBuffer。; dsts - 保存入站應用程序資料的 ByteBuffer 陣列。
返回：: 描述此次操作結果的 SSLEngineResult。
拋出：: SSLException - 如果處理資料時遇到的問題導致 SSLEngine 中止。關於引擎關閉的更多資訊，請參見該類別的描述。; ReadOnlyBufferException - 如果任何一個 dst 緩衝區是只讀的。; IllegalArgumentException - 如果 src 或 dsts 為 null，或者 dsts 中的任何元素為 null。; IllegalStateException - 如果沒有設置客戶端/伺服器網要。
另請參見：: unwrap(ByteBuffer, ByteBuffer [], int, int)

unwrap

public abstract SSLEngineResult unwrap(ByteBuffer src,
                                       ByteBuffer[] dsts,
                                       int offset,
                                       int length)
                                throws SSLException

嘗試把 SSL/TLS 網路資料解碼到純文本應用程序資料緩衝區子序列中。此“分散” 操作可在單個調用中把位元組序列解碼到一個或多個給定緩衝區序列中。分散解包通常在實作網路協議或檔案格式時很有用，例如將資料分組放入段中（這些段由一個或多個長度固定的頭，後跟長度可變的正文組成）。關於分散的更多資訊，請參見 ScatteringByteChannel，有關子序列行為的更多資訊，請參見 { ScatteringByteChannel.read(ByteBuffer[], int, int)。

根據 SSLEngine 的狀態，此方法可能使用網路資料而不產生任何應用程序資料（例如，它可能使用連繫交換資料）。

應用程序負責從同位體可靠地獲取網路資料，並且負責以資料接收時的順序對資料調用 unwrap()。應用程序必須正確地同步對此方法的多次調用。

如果此 SSLEngine 還沒有開始它的初始連繫交換，則此方法將自動開始進行連繫交換。

此方法將嘗試使用一個完整的 SSL/TLS 網路包，但使用的資料從不超過緩衝區中剩餘位元組的總和。會更新每個 ByteBuffer 的位置，以反映使用或產生的資料量。界限保持不變。

由 src 和 dsts ByteBuffer 使用的底層記憶體必須不能相同。

由於入站網路緩衝區可能由於調用而被修改：因此，如果由於某些次要目的而需要網路資料封包，則在調用此方法前應該複製該資料。註：網路資料對第二個 SSLEngine 將不再有用，因為每個 SSLEngine 套件含唯一的隨機狀態，該狀態影響 SSL/TLS 報文。

關於引擎關閉的更多資訊，請參見該類別的描述。

參數：: src - 套件含入站網路資料的 ByteBuffer。; dsts - 保存入站應用程序資料的 ByteBuffer 陣列。; offset - 第一個緩衝區（要傳遞該緩衝區中的位元組）在緩衝區陣列中的偏移量；必須為非負數並且不能大於 dsts.length。; length - 要存取的最大緩衝區數；必須為非負數並且不能大於 dsts.length - offset。
返回：: 描述此次操作結果的 SSLEngineResult。
拋出：: SSLException - 如果處理資料時遇到的問題導致 SSLEngine 中止。關於引擎關閉的更多資訊，請參見該類別的描述。; IndexOutOfBoundsException - 如果關於 offset 和 length 參數的前提不成立。; ReadOnlyBufferException - 如果任何一個 dst 緩衝區是只讀的。; IllegalArgumentException - 如果 src 或 dsts 為 null，或者指定的 dsts 子序列中的任何元素為 null。; IllegalStateException - 如果沒有設置客戶端/伺服器網要。
另請參見：: ScatteringByteChannel, ScatteringByteChannel.read( ByteBuffer[], int, int)

getDelegatedTask

public abstract Runnable getDelegatedTask()

返回此 SSLEngine 的一個委託 Runnable 任務。

SSLEngine 操作可能需要阻塞操作的結果，或者可能花費很長的時間才能完成。此方法用來獲取一個未完成的 Runnable 操作（任務）。必須分派給每個任務一個執行緒（可能是當前的）來執行 run 操作。一旦 run 方法返回，則不再需要 Runnable 物件，它可能被丟棄。

當創建此物件時，委託任務在 AccessControlContext 中的適當位置運行。

對此方法的一次調用恰好返回每個未完成的任務一次。

多個委託任務可以並行運行。

返回：: 一個委託 Runnable 任務；如果沒有則返回 null。

closeInbound

public abstract void closeInbound()
                           throws SSLException

通知沒有更多的入站網路資料將發送到此 SSLEngine。

如果應用程序通過調用 closeOutbound() 發起關閉進程，則在某些情況下不要求發起方等待同位體的相應關閉報文。（有關等待關閉報警的更改資訊，請參見 TLS 規範的 7.2.1 節 (RFC 2246)。）在這種情況下，不需要調用此方法。

但是如果應用程序沒有發起關閉進程，如果上面的情況不適用，則每當到達 SSL/TLS 資料串流的末尾時就應該調用此方法。這保證了入站端的關閉，也檢查該同位體是否正確地遵循 SSL/TLS 關閉過程，從而檢測可能的截斷攻擊。

此方法是冪等的：如果入站端已經關閉，則此方法不執行任何操作。

應該調用 wrap() 來刷新任何剩餘的連繫交換資料。

拋出：: SSLException - 如果此引擎沒有從同位體接收到正確的 SSL/TLS 關閉通知報文。
另請參見：: isInboundDone(), isOutboundDone()

isInboundDone

public abstract boolean isInboundDone()

返回 unwrap(ByteBuffer, ByteBuffer) 是否再接受更多的入站資料電報文。

返回：: 如果 SSLEngine 不再使用任何網路資料（同時也暗含不再產生任何應用程序資料），則返回 true。
另請參見：: closeInbound()

closeOutbound

public abstract void closeOutbound()

通知沒有更多的出站應用程序資料將在此 SSLEngine 上發送。

此方法是冪等的：如果出站端已經關閉，則此方法不執行任何操作。

應該調用 wrap(ByteBuffer, ByteBuffer) 來刷新任何剩餘的連繫交換資料。

另請參見：: isOutboundDone()

isOutboundDone

public abstract boolean isOutboundDone()

返回 wrap(ByteBuffer, ByteBuffer) 是否再產生更多的出站資料電報文。

注意，在關閉階段，SSLEngine 可能產生必須發送到同位體的連繫交換關閉資料。必須調用 wrap() 來產生此資料。當此方法返回 true 時，將不再創建出站資料。

返回：: 如果 SSLEngine 不再產生任何網路資料，則返回 true
另請參見：: closeOutbound(), closeInbound()

getSupportedCipherSuites

public abstract String[] getSupportedCipherSuites()

返回為了在此引擎上使用而可以啟用的密碼套件名稱。通常，因為此列表可能包括無法滿足預設服務質量要求的密碼套件，所以預設情況下實際啟動的是這些密碼套件的子集。這種密碼套件在特殊的應用程序中可能很有用。

返回：: 密碼套件名稱的陣列
另請參見：: getEnabledCipherSuites(), setEnabledCipherSuites(String [])

getEnabledCipherSuites

public abstract String[] getEnabledCipherSuites()

返回為了在此引擎上使用而當前已啟用的 SSL 密碼套件名稱。當首次創建 SSLEngine 時，所有啟用的密碼套件都支持最低的服務質量。因此，在某些環境中此值可能為空。

即使密碼套件已經被啟用，它也可能從不被使用。（例如，同位體不支持它、密碼套件必須的證書/私鑰不可用，或者啟用了匿名的密碼套件但需要進行驗證。）

返回：: 密碼套件名稱的陣列
另請參見：: getSupportedCipherSuites(), setEnabledCipherSuites(String [])

setEnabledCipherSuites

public abstract void setEnabledCipherSuites(String[] suites)

設置密碼套件為啟用，以便在此引擎上使用。

suites 參數中的每個密碼套件都必須由 getSupportedCipherSuites() 列出，否則該方法會失敗。在成功調用此方法之後，僅啟用了在 suites 參數中列出的套件以便使用。

有關為什麼一個密碼套件在引擎上從來不被使用的更多資訊，請參見 getEnabledCipherSuites()。

參數：: suites - 要啟用的所有密碼套件的名稱
拋出：: IllegalArgumentException - 當一個或多個由參數命名的密碼套件不被支持時，或參數為 null 時。
另請參見：: getSupportedCipherSuites(), getEnabledCipherSuites()

getSupportedProtocols

public abstract String[] getSupportedProtocols()

返回能夠被啟用，以便讓 SSLEngine 可使用的協議的名稱。

返回：: 所支持的協議的陣列

getEnabledProtocols

public abstract String[] getEnabledProtocols()

返回當前已啟用的，以便讓 SSLEngine 使用的協議版本的名稱。

返回：: 協議的陣列
另請參見：: setEnabledProtocols(String [])

setEnabledProtocols

public abstract void setEnabledProtocols(String[] protocols)

設置為了在此引擎上使用而啟用的協議版本。

該協議必須已經由 getSupportedProtocols() 將其作為受支持的協議列出。在成功調用此方法之後，僅啟用了在 protocols 參數中列出的協議以便使用。

參數：: protocols - 要啟用的所有協議的名稱。
拋出：: IllegalArgumentException - 當一個或多個由參數命名的協議不被支持時，或 protocols 參數為 null 時。
另請參見：: getEnabledProtocols()

getSession

public abstract SSLSession getSession()

返回此 SSLEngine 中使用的 SSLSession。

這些 SSLSession 可以是持久的，並且通常對應於某個使用者的整個登錄Session過程。該Session指定了Session中所有連接主動使用的特定密碼套件，以及該Session的客戶端和伺服器標識。

與 SSLSocket.getSession() 不同，此方法在連繫交換完成之後才阻塞。

在初始連繫交換結束之前，此方法返回一個Session物件，它報告 "SSL_NULL_WITH_NULL_NULL" 形式的無效密碼套件。

返回：: 此 SSLEngine 的 SSLSession
另請參見：: SSLSession

beginHandshake

public abstract void beginHandshake()
                             throws SSLException

在此 SSLEngine 上發起連繫交換（初始的或重新協商）。

初始連繫交換不需要此方法，因為如果連繫交換尚未開始，wrap() 和 unwrap() 方法將隱式地調用此方法。

注意，Session的同位體也可以通過發送適當的Session重新協商連繫交換報文來請求與此 SSLEngine 進行Session重新協商。

與 SSLSocket#startHandshake() 方法不同，此方法在連繫交換完成之後才阻塞。

為了強迫一個完整的 SSL/TLS Session重新協商，調用此方法之前應該使當前的Session無效。

某些協議可能不支持在一個現有引擎上的多次連繫交換，可能拋出 SSLException。

拋出：: SSLException - 如果通知 SSLEngine 開始新的連繫交換時遇到了問題。關於引擎關閉的更多資訊，請參見該類別的描述。; IllegalStateException - 如果沒有設置客戶端/伺服器網要。
另請參見：: SSLSession.invalidate()

getHandshakeStatus

public abstract SSLEngineResult.HandshakeStatus getHandshakeStatus()

返回此 SSLEngine 的當前連繫交換狀態。

返回：: 當前的 SSLEngineResult.HandshakeStatus。

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 Session。如果不允許創建Session，也沒有可以恢復的現有Session，則不會有成功的連繫交換。

參數：: flag - 為 true 時指示可以創建Session；這是預設的。為 false 時指示必須恢復現有Session
另請參見：: getEnableSessionCreation()

getEnableSessionCreation

public abstract boolean getEnableSessionCreation()

如果可以由此引擎建立新的 SSL Session，則返回 true。

返回：: 返回值為 true 時指示可以創建Session；這是預設的。為 false 時指示必須恢復現有Session
另請參見：: setEnableSessionCreation(boolean)

getSSLParameters

public SSLParameters getSSLParameters()

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

返回：: 對此 SSLEngine 有效的 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

概觀

軟體套件

類別

使用

階層樹

已過時

索引

說明

Java^TM 2 Platform
Standard Ed. 6

上一個類別 下一個類別

框架 無框架

摘要：巢狀 | 欄位 | 建構子 | 方法

詳細資訊：欄位 | 建構子 | 方法

提交錯誤或意見

javax.net.ssl 類別 SSLEngine

SSLEngine

SSLEngine

getPeerHost

getPeerPort

wrap

wrap

wrap

unwrap

unwrap

unwrap

getDelegatedTask

closeInbound

isInboundDone

closeOutbound

isOutboundDone

getSupportedCipherSuites

getEnabledCipherSuites

setEnabledCipherSuites

getSupportedProtocols

getEnabledProtocols

setEnabledProtocols

getSession

beginHandshake

getHandshakeStatus

setUseClientMode

getUseClientMode

setNeedClientAuth

getNeedClientAuth

setWantClientAuth

getWantClientAuth

setEnableSessionCreation

getEnableSessionCreation

getSSLParameters

setSSLParameters

javax.net.ssl
類別 SSLEngine