软件包  javax.security.sasl

Interface SaslClient



  • public interface SaslClient
    执行SASL身份验证作为客户端。

    诸如LDAP之类的协议库获取此类的实例,以执行由特定SASL机制定义的认证。 调用SaslClient实例过程的方法,并根据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);
        }
     }
    
    如果机制有一个初始响应,库将调用evaluateChallenge()一个空挑战并得到初始响应。 诸如IMAP4之类的协议,不包括初始响应及其对服务器的第一个认证命令,在不首先调用hasInitialResponse()evaluateChallenge()情况下启动认证。 当服务器响应该命令时,它发送初始挑战。 对于客户端首先发送数据的SASL机制,服务器应该发出无数据的挑战。 这将导致呼叫(在客户端)到evaluateChallenge()与空挑战。
    从以下版本开始:
    1.5
    另请参见:
    SaslSaslClientFactory
    • 方法摘要

      所有方法  接口方法  抽象方法 
      Modifier and Type 方法 描述
      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​()
        确定此机制是否具有可选的初始响应。 如果为true,调用者应该使用空数组来调用evaluateChallenge()以获取初始响应。
        结果
        如果此机制具有初始响应,则为真。
      • 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缓冲区的内容,没有表示长度的前四个八位字节字段。 offsetlen指定要使用的部分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缓冲区的内容,而不包含表示长度的前导四个八位字节字段。 offsetlen指定要使用的部分outgoing

        参数
        outgoing - 包含要编码的字节的非空字节数组。
        offset - 要使用的字节的起始位置为 outgoing
        len - 从 outgoing使用的字节数。
        结果
        包含编码字节的非空字节数组。
        异常
        SaslException - 如果 outgoing无法成功包装。
        IllegalStateException - 如果验证交换尚未完成,或者协商的保护质量既不完整也不保密。
      • getNegotiatedProperty

        Object getNegotiatedProperty​(String propName)
        检索谈判的财产。 只有认证交换完成后才能调用此方法(即isComplete()返回true时)。 否则,抛出一个IllegalStateException

        Sasl类包括几个着名的属性名称(例如, Sasl.QOP )。 SASL提供商可以支持特定于供应商和/或机制的其他属性。

        参数
        propName - 非空属性名称。
        结果
        谈判财产的价值。 如果为null,则该属性未被协商或不适用于该机制。
        异常
        IllegalStateException - 如果此认证交换尚未完成
      • dispose

        void dispose​()
              throws SaslException
        处理SaslClient可能使用的任何系统资源或安全敏感信息。 调用此方法会使SaslClient实例无效。 这种方法是幂等的。
        异常
        SaslException - 处理资源时遇到问题。