javax.security.sasl
介面 SaslClient

public interface SaslClient

以客戶端的身份執行 SASL 驗證。

為了執行具體 SASL 機制所定義的驗證，協議資源庫（例如用於 LDAP 的資源庫）要獲得此類別的一個實例。調用 SaslClient 實例的方法可處理 challenge，並創建與 SaslClient 所實作的 SASL 機制相對應的回應。隨著驗證的進行，該實例會封裝 SASL 客戶端的驗證交換狀態。

以下是 LDAP 資源庫如何使用 SaslClient 的一個範例。它首先獲得 SaslClient 的一個實例：

 SaslClient sc = Sasl.createSaslClient(mechanisms,
     authorizationId, protocol, serverName, props, callbackHandler);

然後它可繼續使用該客戶端進行驗證。例如，LDAP 資源庫可能按如下方式使用該客戶端：

 // Get initial response and send to server
 byte[] response = (sc.hasInitialResponse() ? sc.evaluateChallenge(new byte[0]) :
     null);
 LdapResult res = ldap.sendBindRequest(dn, sc.getName(), response);
 while (!sc.isComplete() && 
     (res.status == SASL_BIND_IN_PROGRESS || res.status == SUCCESS)) {
     response = sc.evaluateChallenge(res.getBytes());
     if (res.status == SUCCESS) {
         // we're done; don't expect to send another BIND
         if (response != null) {
               throw new SaslException(
                   "Protocol error: attempting to send response after completion");
           }
         break;
     }
     res = ldap.sendBindRequest(dn, sc.getName(), response);
 }
 if (sc.isComplete() && res.status == SUCCESS) {
    String qop = (String) sc.getNegotiatedProperty(Sasl.QOP);
    if (qop != null 
        && (qop.equalsIgnoreCase("auth-int") 
            || qop.equalsIgnoreCase("auth-conf"))) {

      // Use SaslClient.wrap() and SaslClient.unwrap() for future
      // communication with server
        ldap.in = new SecureInputStream(sc, ldap.in);
        ldap.out = new SecureOutputStream(sc, ldap.out);
    }
 }

如果該機制有初始回應，則資源庫可調用帶有空 challenge 的 evaluateChallenge() 來獲得該初始回應。諸如 IMAP4 等此類別協議在其送往伺服器的第一個驗證命令中不包括初始回應，所以可無需首先調用 hasInitialResponse() 或 evaluateChallenge() 即可發起驗證。當伺服器回應該命令時，它會發送初始 challenge。對於客戶端首先發送資料的 SASL 機制而言，伺服器應該發出一個沒有資料的 challenge。然後，這會導致帶有空 challenge 的 evaluateChallenge() 調用（在客戶端上）。

從以下版本開始：

1.5

另請參見：

Sasl, SaslClientFactory

方法摘要

void	dispose() 處置 SaslClient 可能使用的所有系統資源或安全敏感資訊。
byte[]	evaluateChallenge(byte[] challenge) 評估 challenge 資料並產生一個回應。
String	getMechanismName() 返回此 SASL 客戶端的 IANA 註冊機制名。
Object	getNegotiatedProperty(String propName) 獲取已協商的屬性。
boolean	hasInitialResponse() 確定此機制是否具有可選的初始回應。
boolean	isComplete() 確定驗證交換是否已完成。
byte[]	unwrap(byte[] incoming, int offset, int len) 解包接收自伺服器的 byte 陣列。
byte[]	wrap(byte[] outgoing, int offset, int len) 包裹要發送到伺服器的 byte 陣列。

方法詳細資訊

getMechanismName

String getMechanismName()

返回此 SASL 客戶端的 IANA 註冊機制名。（例如 "CRAM-MD5"、"GSSAPI"）。

返回：

表示 IANA 註冊機制名的非 null 字元串。

hasInitialResponse

boolean hasInitialResponse()

確定此機制是否具有可選的初始回應。如果為 true，則調用者應該調用帶有空陣列的 evaluateChallenge() 以獲得初始回應。

返回：

如果此機制具有初始回應，則返回 true。

evaluateChallenge

byte[] evaluateChallenge(byte[] challenge)
                         throws SaslException

評估 challenge 資料並產生一個回應。如果在驗證處理期間接收到伺服器的 challenge，則調用此方法來準備要提交給伺服器的下一個合適回應。

參數：

challenge - 伺服器發送的非 null challenge。該 challenge 陣列的長度可以為零。

返回：

要發送給伺服器的回應，可能為 null。如果 challenge 隨附一個 "SUCCESS" 狀態並且它只包含客戶端更新其狀態的資料，而沒有需要送到伺服器的回應，則返回 null。如果客戶端要發送沒有資料的回應，則該回應是一個零長度的 byte 陣列。

拋出：

SaslException - 如果處理 challenge 或產生回應時發生錯誤。

isComplete

boolean isComplete()

確定驗證交換是否已完成。可在任何時間調用此方法，但是通常在調用者接收到伺服器關於交換已完成的指示（以特定於協議的方式通知）前不會調用此方法。

返回：

如果驗證交換已完成，則返回 true；否則返回 false。

unwrap

byte[] unwrap(byte[] incoming,
              int offset,
              int len)
              throws SaslException

解包接收自伺服器的 byte 陣列。僅在驗證交換已完成（即 isComplete() 返回 true）後，並且僅在驗證交換已經協商將完整性和/或機密性作為保護級別時才調用此方法；否則會拋出 IllegalStateException。

incoming 是 SASL 緩衝區的內容（在 RFC 2222 中定義），沒有表示長度的前導 4 個八位組欄位。offset 和 len 指定了要使用的 incoming 部分。

參數：

incoming - 非 null 的 byte 陣列，包含取自伺服器的已編碼位元組。

offset - 所用位元組在 incoming 中的開始位置。

len - 要使用的 incoming 中的位元組數。

返回：

包含已解碼位元組的非 null byte 陣列。

拋出：

SaslException - 如果無法成功解包 incoming。

IllegalStateException - 如果驗證交換未完成，如果協商的保護級別既沒有完整性，也沒有機密性。

wrap

byte[] wrap(byte[] outgoing,
            int offset,
            int len)
            throws SaslException

包裹要發送到伺服器的 byte 陣列。僅在驗證交換已完成（即 isComplete() 返回 true）後，並且僅在驗證交換已經協商將完整性和/或機密性作為保護級別時才調用此方法；否則會拋出 IllegalStateException。

此方法的結果會組成 SASL 緩衝區的內容（在 RFC 2222 中定義），沒有表示長度的前導 4 個八位組欄位。offset 和 len 指定了要使用的 outgoing 部分。

參數：

outgoing - 非 null 的 byte 陣列，包含要編碼的位元組。

offset - 所用位元組在 outgoing 中的開始位置。

len - 要使用的 outgoing 中的位元組數。

返回：

包含已編碼位元組的非 null byte 陣列。

拋出：

SaslException - 如果無法成功包裹 outgoing。

IllegalStateException - 如果驗證交換未完成，如果協商的保護級別既沒有完整性，也沒有機密性。

getNegotiatedProperty

Object getNegotiatedProperty(String propName)

獲取已協商的屬性。僅在驗證交換已完成後（即 isComplete() 返回 true 時）才調用此方法；否則會拋出 IllegalStateException。

參數：

propName - 非 null 的屬性名。

返回：

已協商的屬性的值。如果為 null，則未協商該屬性，或者該屬性不適用於此機制。

拋出：

IllegalStateException - 如果未完成此驗證交換。

dispose

void dispose()
             throws SaslException

處置 SaslClient 可能使用的所有系統資源或安全敏感資訊。調用此方法會使 SaslClient 實例失效。此方法是冪等的。

拋出：

SaslException - 如果釋放資源時遇到問題。