Интерфейс SaslClient

public interface SaslClient

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

Библиотека протокола, например библиотека для LDAP, получает экземпляр этого класса для выполнения аутентификации, определённой конкретным механизмом SASL. Вызовы методов экземпляра SaslClient обрабатывают запросы и формируют ответы в соответствии с механизмом SASL, реализованным в SaslClient. По мере выполнения аутентификации экземпляр хранит состояние обмена данными при аутентификации клиента SASL.

Ниже приведён пример использования SaslClient библиотекой LDAP. Сначала она получает экземпляр 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

См. также:

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

Модификатор и тип	Метод	Описание
`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 — ответ, который нужно отправить серверу. Значение равно 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 — если при освобождении ресурсов возникла проблема.

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/25/docs/api/java.security.sasl/javax/security/sasl/SaslClient.html