Интерфейс 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() с пустым запросом.

С:: 1.5
См. также:: Sasl, SaslClientFactory

Краткое описание методов

Модификатор и тип	Метод	Описание
`void`	`dispose()`	Освобождает любые системные ресурсы или чувствительную к безопасности информацию, которую SaslClient может использовать.
`byte[]`	`evaluateChallenge(byte[] challenge)`	Оценивает данные запроса и генерирует ответ.
`String`	`getMechanismName()`	Возвращает имя механизма, зарегистрированного в IANA, этого SASL-клиента.
`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()

Возвращает имя механизма, зарегистрированного в 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

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

incoming — содержимое буфера SASL, как определено в RFC 2222 без начального четырёхбайтового поля, представляющего длину. 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.

Результат этого метода составит содержимое буфера SASL, как определено в RFC 2222 без начального четырёхбайтового поля, представляющего длину. offset и len указывают часть 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 - Если при освобождении ресурсов произошла проблема.