javax.net.ssl
介面 SSLSession

public interface SSLSession

在 SSL 中，Session用來描述兩個實體間正在發生的關係。每個 SSL 連接在某一時刻都會涉及一個Session，但是該Session可以同時地或相繼地用在這些實體的多個連接上。還可以用不同的Session代替某一連接上使用的Session。Session是作為 SSL 連繫交換協議的一部分創建或重新加入的。影響安全或資源使用的策略或由應用程序顯式調用 invalidate 可能使Session無效。Session管理策略通常用來調優性能。

除了標準Session屬性之外，SSL Session還會公開以下這些只讀屬性：

• 同級身份。 Session是在特定客戶端和特定伺服器之間進行的。同級身份可能已作為Session設置的一部分建立。同位體通常是用 X.509 證書鏈標識。
• 密碼套件的名稱。密碼套件描述在特定Session中的連接使用的加密保護的種類別。
• 同級主機。一次Session的所有連接都是在相同的兩個主機之間進行的。連接的另一端的主機的位址是可用的。

可以顯式地使Session無效。當遇到某種錯誤時，也可以隱式地使Session無效。

從以下版本開始：

1.4

方法摘要

int	getApplicationBufferSize() 獲取使用此Session時期望的最大應用程序資料的當前大小。
String	getCipherSuite() 返回Session中的所有連接所使用的 SSL 密碼套件的名稱。
long	getCreationTime() 返回創建此Session表示的時間，該時間是自協調世界時 1970 年 1 月 1 日午夜起經過的毫秒數。
byte[]	getId() 返回分派給此Session的標識符。
long	getLastAccessedTime() 返回此Session表示上一次被Session層應用存取的時間，該時間是自協調世界時 1970 年 1 月 1 日午夜起經過的毫秒數。
Certificate[]	getLocalCertificates() 返回連繫交換期間發送給同位體的證書。
Principal	getLocalPrincipal() 返回連繫交換期間發送給同位體的主體。
int	getPacketBufferSize() 獲取使用此Session時期望的最大 SSL/TLS 套件的當前大小。
X509Certificate[]	getPeerCertificateChain() 返回同級身份，該同級身份被標識作為定義Session的一部分。
Certificate[]	getPeerCertificates() 返回同級身份，該同級身份是作為定義Session的一部分而建立的。
String	getPeerHost() 返回此Session中同位體的主機名稱。
int	getPeerPort() 返回此Session中同位體的埠號號。
Principal	getPeerPrincipal() 返回同級身份，該同級身份是作為定義Session的一部分而建立的。
String	getProtocol() 返回Session中的所有連接使用的協議的標準名稱。
SSLSessionContext	getSessionContext() 返回此Session所在的上下文。
Object	getValue(String name) 返回Session的應用層資料中的綁定到給定名稱的物件。
String[]	getValueNames() 返回綁定到Session中的所有應用層資料物件的名稱組成的陣列。
void	invalidate() 使Session失效。
boolean	isValid() 返回此Session對於恢復和加入是否是有效的和可用的。
void	putValue(String name, Object value) 使用給定的 name 將指定的 value 物件綁定到Session的應用層資料中。
void	removeValue(String name) 移除Session的應用層資料中綁定到給定名稱的物件。

方法詳細資訊

getId

byte[] getId()

返回分派給此Session的標識符。

返回：

Session的標識符

getSessionContext

SSLSessionContext getSessionContext()

返回此Session所在的上下文。

此上下文在一些環境中可能不可用，在這種情況下，此方法返回 null。

如果存在上下文並且已安裝了一個安全管理器，則調用者可能需要相應的權限才能存取上下文，否則可能拋出安全異常。在 Java 環境中，使用 SSLPermission("getSSLSessionContext") 權限調用安全管理器的 checkPermission 方法。

返回：

用於此Session的Session上下文；如果上下文不可用，則返回 null。

拋出：

SecurityException - 如果調用執行緒沒有獲取 SSL Session上下文的權限。

getCreationTime

long getCreationTime()

返回創建此Session表示的時間，該時間是自協調世界時 1970 年 1 月 1 日午夜起經過的毫秒數。

返回：

創建此Session的時間

getLastAccessedTime

long getLastAccessedTime()

返回此Session表示上一次被Session層應用存取的時間，該時間是自協調世界時 1970 年 1 月 1 日午夜起經過的毫秒數。

存取將指示使用Session資料建立一個新的連接。存取期間並不反映應用級操作，例如獲取或設置與Session相關的值。

此資訊在Session管理策略中特別有用。例如，Session管理器執行緒可以將所有Session放在一個很長時間未被使用的給定上下文中；或者可能根據生存時間對Session進行排序，以優化一些任務。

返回：

上一次存取此Session的時間

invalidate

void invalidate()

使Session失效。

將來的連接無法恢復或加入此Session。但是，任何使用此Session的現有連接可以繼續使用此Session，直到該連接關閉。

另請參見：

isValid()

isValid

boolean isValid()

返回此Session對於恢復和加入是否是有效的和可用的。

返回：

如果可以重新加入此Session，則返回 true。

從以下版本開始：

1.5

另請參見：

invalidate()

putValue

void putValue(String name,
              Object value)

使用給定的 name 將指定的 value 物件綁定到Session的應用層資料中。

替換任何使用相同 name 的現有綁定。如果新的（或現有）value 實作了 SSLSessionBindingListener 介面，則會相應地通知 value 表示的物件。

出於安全原因，具有相同名稱的值在不同的存取控制上下文之間是不可見的。

參數：

name - 資料物件將要綁定到的名稱。此參數不可以為 null。

value - 將要綁定的資料物件。此參數不可以為 null。

拋出：

IllegalArgumentException - 如果任何一個參數為 null。

getValue

Object getValue(String name)

返回Session的應用層資料中的綁定到給定名稱的物件。如果不存在這種綁定，則返回 null。

出於安全原因，具有相同名稱的值在不同的存取控制上下文之間是不可見的。

參數：

name - 要尋找的綁定的名稱。

返回：

綁定到該名稱的值；如果不存在綁定，則返回 null。

拋出：

IllegalArgumentException - 如果參數為 null。

removeValue

void removeValue(String name)

移除Session的應用層資料中綁定到給定名稱的物件。如果沒有對象綁定到給定名稱，則什麼都不做。如果綁定的現有對象實作了 SessionBindingListener 介面，則以適當的方式通知它。

出於安全原因，具有相同名稱的值在不同的存取控制上下文之間是不可見的。

參數：

name - 將移除的在不同存取控制上下文之間可見的物件名稱

拋出：

IllegalArgumentException - 如果參數為 null。

getValueNames

String[] getValueNames()

返回綁定到Session中的所有應用層資料物件的名稱組成的陣列。

出於安全原因，具有相同名稱的值在不同的存取控制上下文之間是不可見的。

返回：

綁定到此Session的物件的名稱組成的非 null（可能為空）陣列。

getPeerCertificates

Certificate[] getPeerCertificates()
                                  throws SSLPeerUnverifiedException

返回同級身份，該同級身份是作為定義Session的一部分而建立的。

註：僅當使用基於證書的密碼套件時才可以使用此方法；將它與非基於證書的密碼套件（如 Kerberos）一起使用將拋出 SSLPeerUnverifiedException。

返回：

同級證書的有序陣列，同位體自己的證書緊跟在任何證書授權之後。

拋出：

SSLPeerUnverifiedException - 如果同級身份未被驗證

另請參見：

getPeerPrincipal()

getLocalCertificates

Certificate[] getLocalCertificates()

返回連繫交換期間發送給同位體的證書。

註：僅當使用基於證書的密碼套件時此方法才有用。

當在一次連繫交換中有多個證書可供使用時，具體實作可以選擇使用它認為“最好的”證書鏈，並將該證書鏈傳輸給另一端。此方法允許調用者知道實際使用了哪些證書鏈。

返回：

證書的有序陣列，本地證書緊跟在任何證書授權之後。如果沒有發送任何證書，則返回 null。

另請參見：

getLocalPrincipal()

getPeerCertificateChain

X509Certificate[] getPeerCertificateChain()
                                          throws SSLPeerUnverifiedException

返回同級身份，該同級身份被標識作為定義Session的一部分。

註：僅當使用基於證書的密碼套件時才可以使用此方法；將它與非基於證書的密碼套件（如 Kerberos）一起使用將拋出 SSLPeerUnverifiedException。

註：此方法存在是為了與以前的版本相容。新的應用程序應該使用 getPeerCertificates()。

返回：

同級 X.509 證書的有序陣列，同位體自己的證書緊跟在任何證書授權之後。（證書格式採用原來的 JSSE 證書 X509Certificate 格式。）

拋出：

SSLPeerUnverifiedException - 如果同級身份未被驗證

另請參見：

getPeerPrincipal()

getPeerPrincipal

Principal getPeerPrincipal()
                           throws SSLPeerUnverifiedException

返回同級身份，該同級身份是作為定義Session的一部分而建立的。

返回：

同位體的主體。對於基於 X509 的密碼套件，返回最終實體證書的 X500Principal；對於 Kerberos 密碼套件，返回 KerberosPrincipal。

拋出：

SSLPeerUnverifiedException - 如果同級身份未被驗證

從以下版本開始：

1.5

另請參見：

getPeerCertificates(), getLocalPrincipal()

getLocalPrincipal

Principal getLocalPrincipal()

返回連繫交換期間發送給同位體的主體。

返回：

發送給同位體的主體。返回基於 X509 的密碼套件的最終實體證書的 X500Principal，以及 Kerberos 的密碼套件的 KerberosPrincipal。如果沒有發送任何主體，則返回 null。

從以下版本開始：

1.5

另請參見：

getLocalCertificates(), getPeerPrincipal()

getCipherSuite

String getCipherSuite()

返回Session中的所有連接所使用的 SSL 密碼套件的名稱。

此密碼套件定義了針對連接上發送的資料所提供的保護級別，包括所使用的加密型別和如何進行驗證的大多數方面。

返回：

Session的密碼套件的名稱。

getProtocol

String getProtocol()

返回Session中的所有連接使用的協議的標準名稱。

此方法定義了連接中使用的協議。

返回：

Session中的所有連接使用的協議的標準名稱。

getPeerHost

String getPeerHost()

返回此Session中同位體的主機名稱。

對於伺服器來說，該主機是客戶端的主機；對於客戶端來說，它是伺服器的主機。此名稱可以不是一個完全限定的主機名或根本不是主機名，因為它可以表示同級網路位址的字元串編碼。如果需要這樣的名稱，可以根據此方法返回的值通過名稱服務來解析該名稱。

此值並沒有經過驗證，因此不應依賴它。它主要被用作 SSLSession 快取記憶體策略的提示。

返回：

同級主機的主機名稱；如果沒有資訊可用，則返回 null。

getPeerPort

int getPeerPort()

返回此Session中同位體的埠號號。

對於伺服器來說，該埠號號是客戶端的埠號號；對於客戶端來說，它是伺服器的埠號號。

此值並沒有經過驗證，因此不應依賴它。它主要被用作 SSLSession 快取記憶體策略的提示。

返回：

同位體的埠號號；如果沒有資訊可用，則返回 -1。

從以下版本開始：

1.5

getPacketBufferSize

int getPacketBufferSize()

獲取使用此Session時期望的最大 SSL/TLS 套件的當前大小。

使用此Session的 SSLEngine 可以產生任意大小並包括此方法返回的值的 SSL/TLS 套件。所有 SSLEngine 網路緩衝區的大小最少應該是這麼大，以防止執行 wrap 和 unwrap 時出現空間不足問題。

返回：

期望網路包大小的當前最大值

從以下版本開始：

1.5

另請參見：

SSLEngine.wrap(ByteBuffer, ByteBuffer), SSLEngine.unwrap(ByteBuffer, ByteBuffer)

getApplicationBufferSize

int getApplicationBufferSize()

獲取使用此Session時期望的最大應用程序資料的當前大小。

SSLEngine 應用資料緩衝區必須足夠大以容納所接收的取自任何入站網路應用資料封包的應用資料。通常，出站應用資料緩衝區可以為任意大小。

返回：

期望應用程序包大小的當前最大值

從以下版本開始：

1.5

另請參見：

SSLEngine.wrap(ByteBuffer, ByteBuffer), SSLEngine.unwrap(ByteBuffer, ByteBuffer)