compact3

javax.security.sasl

Interface SaslClient

public interface SaslClient

执行SASL身份验证作为客户端。

诸如LDAP之类的协议库获取此类的实例，以执行由特定SASL机制定义的认证。 调用SaslClient实例过程的方法，并根据SaslClient执行的SASL机制创建SaslClient 。 当认证进行时，该实例封装了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);
    }
 }

如果机制有一个初始响应，库将调用evaluateChallenge()一个空挑战并得到初始响应。 诸如IMAP4之类的协议，其中不包括对服务器的第一认证命令的初始响应，在没有首先呼叫hasInitialResponse()或evaluateChallenge()情况下hasInitialResponse() evaluateChallenge() 。 当服务器响应该命令时，它发送初始挑战。 对于客户端首先发送数据的SASL机制，服务器应该发出无数据的挑战。 这将导致一个呼叫（在客户端）到evaluateChallenge()一个空的挑战。

从以下版本开始：

1.5

另请参见：

Sasl ， SaslClientFactory

方法摘要

Modifier and Type	Method and Description
void	dispose() 处理SaslClient可能使用的任何系统资源或安全敏感信息。
byte[]	evaluateChallenge(byte[] challenge) 评估挑战数据并产生响应。
String	getMechanismName() 返回此SASL客户端的IANA注册机制名称。
Object	getNegotiatedProperty(String propName) 检索谈判的财产。
boolean	hasInitialResponse() 确定此机制是否具有可选的初始响应。
boolean	isComplete() 确定认证交换是否已完成。
byte[]	unwrap(byte[] incoming, int offset, int len) 解开从服务器接收的字节数组。
byte[]	wrap(byte[] outgoing, int offset, int len) 包装要发送到服务器的字节数组。

方法详细信息

getMechanismName

String getMechanismName()

返回此SASL客户端的IANA注册机制名称。 （例如“CRAM-MD5”，“GSSAPI”）。

结果

表示IANA注册的机制名称的非空字符串。

hasInitialResponse

boolean hasInitialResponse()

确定此机制是否具有可选的初始响应。 如果为真，则呼叫方应使用空数组来调用evaluateChallenge()以获取初始响应。

结果

如果此机制具有初始响应，则为true。

evaluateChallenge

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

评估挑战数据并产生响应。 如果在认证过程中从服务器收到质询，则会调用此方法来准备适当的下一个响应以提交给服务器。

参数

challenge - 从服务器发送的非空挑战。 挑战阵列可能具有零长度。

结果

可能的空响应发送到服务器。 如果挑战伴随“SUCCESS”状态，则该值为空，并且质询仅包含客户端更新其状态的数据，并且不需要将响应发送到服务器。 如果客户端要发送没有数据的响应，则响应是零长度字节数组。

异常

SaslException - 如果在处理挑战或产生响应时发生错误。

isComplete

boolean isComplete()

确定认证交换是否已完成。 该方法可以在任何时间被调用，但是通常，直到主叫方已经从服务器（以协议特定的方式）接收到交换已经完成的指示才会被调用。

结果

如果认证交换完成，则为真; 否则为假。

unwrap

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

解开从服务器接收的字节数组。 只有认证交换完成后（即当isComplete()返回true时），并且只有认证交换协商完整性和/或隐私作为保护质量，才可以调用此方法。 否则，抛出一个IllegalStateException 。

incoming是RFC 2222中定义的SASL缓冲区的内容，没有表示长度的前四个八位字节字段。 offset和len指定要使用的部分incoming 。

参数

incoming - 包含服务器编码字节的非空字节数组。

offset - 起始位置在 incoming的字节使用。

len - 从 incoming使用的字节数。

结果

包含解码字节的非空字节数组。

异常

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

IllegalStateException - 如果验证交换尚未完成，或者协商的保护质量既不完整也不具有隐私。

wrap

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

包装要发送到服务器的字节数组。 只有认证交换完成后（即当isComplete()返回true时），只有认证交换协商完整性和/或隐私作为保护质量，才可以调用此方法。 否则，抛出IllegalStateException 。

该方法的结果将构成RFC 2222中定义的SASL缓冲区的内容，而不包含表示长度的前导四个八位字节字段。 offset和len指定要使用的部分outgoing 。

参数

outgoing - 包含要编码的字节的非空字节数组。

offset - 起始位置在 outgoing的字节使用。

len - 从 outgoing使用的字节数。

结果

包含编码字节的非空字节数组。

异常

SaslException - 如果 outgoing无法成功包装。

IllegalStateException - 如果认证交换尚未完成，或者协商的保护质量既没有完整性也没有隐私。

getNegotiatedProperty

Object getNegotiatedProperty(String propName)

检索谈判的财产。 只有认证交换完成后才能调用此方法（即当isComplete()返回true时）。 否则，抛出一个IllegalStateException 。

参数

propName - 非空属性名称。

结果

谈判财产的价值。 如果为null，则该属性未被协商或不适用于该机制。

异常

IllegalStateException - 如果此认证交换尚未完成

dispose

void dispose()
      throws SaslException

处理SaslClient可能使用的任何系统资源或安全敏感信息。 调用此方法会使SaslClient实例无效。 这种方法是幂等的。

异常

SaslException - 处理资源时遇到问题。