Интерфейс SaslClient

public interface SaslClient

Выполняет аутентификацию SASL как клиент.

Библиотека протоколов, например, для LDAP, получает экземпляр этого класса для выполнения аутентификации, определённой конкретным механизмом SASL. Вызов методов на экземпляре 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(). Когда сервер отвечает на команду, он отправляет начальный запрос. Для механизма SASL, в котором клиент сначала отправляет данные, сервер должен выдать запрос без данных. Это приведёт к вызову (на клиенте) evaluateChallenge() с пустым запросом.

Методы

getMechanismName

String getMechanismName()

Возвращает имя механизма, зарегистрированного в IANA, этого SASL-клиента. (например, "CRAM-MD5", "GSSAPI").

Возвращает:

Непустая строка, представляющая имя механизма, зарегистрированного в IANA.

hasInitialResponse

boolean hasInitialResponse()

Определяет, имеет ли этот механизм необязательный начальный ответ. Если true, вызывающий метод должен вызвать evaluateChallenge() с пустым массивом, чтобы получить начальный ответ.

Возвращает:

true, если у этого механизма есть начальный ответ.

evaluateChallenge

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

Оценивает данные запроса и генерирует ответ. Если во время процесса аутентификации от сервера получен запрос, этот метод вызывается для подготовки соответствующего следующего ответа для отправки серверу.

Параметры:

challenge - Непустой запрос, отправленный сервером. Массив запроса может иметь нулевую длину.

Возвращает:

Возможный ответ для отправки серверу. Он равен null, если запрос сопровождался статусом "SUCCESS", и запрос содержит только данные для обновления состояния клиента, и серверу не нужно отправлять ответ. Ответ является массивом нулевой длины, если клиент должен отправить ответ без данных.

Исключения:

SaslException - Если произошла ошибка при обработке запроса или генерации ответа.

isComplete

boolean isComplete()

Определяет, завершился ли обмен аутентификации. Этот метод можно вызывать в любое время, но обычно он вызывается, только когда вызывающий код получил указание от сервера (специфичным для протокола способом), что обмен завершен.

Возвращает:

true, если обмен аутентификации завершен; false в противном случае.

unwrap

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

Параметры:

incoming - Непустой массив байтов, содержащий закодированные байты от сервера.

offset - Начальная позиция в incoming байтов для использования.

len - Количество байтов от incoming для использования.

Возвращает:

Непустой массив байтов, содержащий декодированные байты.

Исключения:

SaslException - если incoming не может быть успешно распакован.

IllegalStateException - если обмен аутентификации не завершен, или согласованное качество защиты не включает ни целостность, ни конфиденциальность.

wrap

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

Параметры:

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 - Если при освобождении ресурсов возникла проблема.