Класс GSSManager
public abstract class GSSManager extends Object
GSSName, GSSCredential и GSSContext. Он также имеет методы для запроса списка доступных механизмов и типов имён, которые поддерживает каждый механизм. Экземпляр по умолчанию GSSManager подкласса может быть получен через статический метод getInstance, но приложения могут свободно создавать другие подклассы GSSManager. Экземпляр по умолчанию GSSManager будет поддерживать механизм Kerberos v5 GSS-API, а также любые другие. Этот механизм идентифицируется Oid "1.2.840.113554.1.2.2" и определён в RFC 1964.
Подкласс, расширяющий GSSManager абстрактный класс, может быть реализован как модульный провайдер, основанный на слое, использующем некоторые известные спецификации поставщиков услуг. GSSManager API позволяет приложению устанавливать предпочтения поставщика в такой реализации. Эти методы также позволяют реализации генерировать чётко определённое исключение в случае, если поддержка, основанная на поставщике, не поддерживается. Приложения, ожидающие переносимости, должны быть осведомлены об этом и корректно восстанавливаться, перехватывая исключение.
Предполагается, что существует три наиболее распространённых способа использования поставщиков:
- Приложению неважно, какой поставщик используется (случай по умолчанию).
- Приложение хочет, чтобы определённый поставщик использовался предпочтительно, либо для конкретного механизма, либо всегда, независимо от механизма.
- Приложение хочет использовать локально настроенных поставщиков по возможности, но если поддержка отсутствует для одного или нескольких механизмов, то оно хочет использовать собственного поставщика в качестве резервного варианта.
Класс GSSManager имеет два метода, которые позволяют использовать эти режимы: addProviderAtFront и addProviderAtEnd. Эти методы создают упорядоченный список пар <provider, oid>, где каждая пара указывает предпочтение поставщика для данного oid.
Важно отметить, что существуют определённые взаимодействия между различными объектами GSS-API, создаваемыми GSSManager, где поставщик, используемый для конкретного механизма, может потребовать согласованности по всем объектам. Например, если GSSCredential содержит элементы из поставщика p для механизма m, его следует передавать в GSSContext, который будет использовать поставщика p для механизма m. Простое правило, которое максимизирует переносимость, заключается в том, что объекты, созданные различными GSSManager, не должны смешиваться, и если возможно, должен быть создан другой экземпляр GSSManager, если приложение хочет вызвать метод addProviderAtFront на GSSManager, который уже создал объект.
Вот пример кода, показывающий, как можно использовать GSSManager:
GSSManager manager = GSSManager.getInstance();
Oid krb5Mechanism = new Oid("1.2.840.113554.1.2.2");
Oid krb5PrincipalNameType = new Oid("1.2.840.113554.1.2.2.1");
// Identify who the client wishes to be
GSSName userName = manager.createName("duke", GSSName.NT_USER_NAME);
// Identify the name of the server. This uses a Kerberos specific
// name format.
GSSName serverName = manager.createName("nfs/foo.sun.com",
krb5PrincipalNameType);
// Acquire credentials for the user
GSSCredential userCreds = manager.createCredential(userName,
GSSCredential.DEFAULT_LIFETIME,
krb5Mechanism,
GSSCredential.INITIATE_ONLY);
// Instantiate and initialize a security context that will be
// established with the server
GSSContext context = manager.createContext(serverName,
krb5Mechanism,
userCreds,
GSSContext.DEFAULT_LIFETIME);
Сторона сервера может использовать следующую вариацию этого кода:
// Acquire credentials for the server
GSSCredential serverCreds = manager.createCredential(serverName,
GSSCredential.DEFAULT_LIFETIME,
krb5Mechanism,
GSSCredential.ACCEPT_ONLY);
// Instantiate and initialize a security context that will
// wait for an establishment request token from the client
GSSContext context = manager.createContext(serverCreds);
- Since:
- 1.4
- См. также:
Краткое описание конструкторов
| Конструктор | Описание |
|---|---|
GSSManager() |
Конструктор для вызова подклассами. |
Краткое описание методов
| Модификатор и тип | Метод | Описание |
|---|---|---|
abstract void |
addProviderAtEnd |
Этот метод используется для указания GSSManager, что приложение хочет, чтобы определённый поставщик использовался, если не найдётся другой поставщик, поддерживающий данный механизм. |
abstract void |
addProviderAtFront |
Этот метод используется для указания GSSManager, что приложение хочет, чтобы определённый поставщик использовался перед всеми другими, когда желательна поддержка для данного механизма. |
abstract GSSContext |
createContext |
Метод-фабрика для создания ранее экспортированного контекста. |
abstract GSSContext |
createContext |
Метод-фабрика для создания контекста на стороне акцептора. |
abstract GSSContext |
createContext |
Метод-фабрика для создания контекста на стороне инициатора. |
abstract GSSCredential |
createCredential |
Метод-фабрика для получения по умолчанию учетных данных. |
abstract GSSCredential |
createCredential |
Метод-фабрика для получения учетных данных по набору механизмов. |
abstract GSSCredential |
createCredential |
Метод-фабрика для получения учетных данных для одного механизма. |
abstract GSSName |
createName |
Метод-фабрика для преобразования байтового массива, содержащего имя из указанного пространства имён, в объект GSSName. |
abstract GSSName |
createName |
Метод-фабрика для преобразования байтового массива, содержащего имя из указанного пространства имён, в объект GSSName и его канонизации для механизма. |
abstract GSSName |
createName |
Метод-фабрика для преобразования строкового имени из указанного пространства имён в объект GSSName. |
abstract GSSName |
createName |
Метод-фабрика для преобразования строкового имени из указанного пространства имён в объект GSSName и его канонизации для механизма. |
static GSSManager |
getInstance() |
Возвращает реализацию GSSManager по умолчанию. |
abstract Oid[] |
getMechs() |
Возвращает список механизмов, доступных вызывающим сторонам GSS-API через этот GSSManager. |
abstract Oid[] |
getMechsForName |
Возвращает список механизмов, поддерживающих указанный тип имени. |
abstract Oid[] |
getNamesForMech |
Возвращает типы имён, поддерживаемые указанным механизмом. |
Подробное описание конструкторов
GSSManager
public GSSManager()
Подробное описание методов
getInstance
public static GSSManager getInstance()
- Возвращает:
- реализация GSSManager
getMechs
public abstract Oid[] getMechs()
getInstance(), включает Oid "1.2.840.113554.1.2.2" в свой список. Этот Oid идентифицирует механизм Kerberos v5 GSS-API, определенный в RFC 1964.- Возвращает:
- массив объектов Oid, соответствующих доступным механизмам. Значение
nullвозвращается, когда механизмы недоступны (например, когда механизмы динамически настраиваются, и в настоящее время механизмы не установлены).
getNamesForMech
public abstract Oid[] getNamesForMech(Oid mech) throws GSSException
Стандартный экземпляр GSSManager включает поддержку механизма Kerberos v5. Когда указан этот механизм ("1.2.840.113554.1.2.2"), возвращаемый список будет содержать как минимум следующие типы имен: GSSName.NT_HOSTBASED_SERVICE, GSSName.NT_EXPORT_NAME и специфичный для Kerberos v5 Oid "1.2.840.113554.1.2.2.1". Пространство имен для Oid "1.2.840.113554.1.2.2.1" определено в RFC 1964.
- Параметры:
-
mech- Oid механизма для запроса - Возвращает:
- массив объектов Oid, соответствующих типам имен, которые поддерживает механизм.
- Исключение:
-
GSSException- содержащий следующие основные коды ошибок:GSSException.BAD_MECHGSSException.FAILURE - См. также:
getMechsForName
public abstract Oid[] getMechsForName(Oid nameType)
Механизм Kerberos v5 ("1.2.840.113554.1.2.2") всегда будет возвращен в этом списке, когда указанный тип имени является одним из GSSName.NT_HOSTBASED_SERVICE, GSSName.NT_EXPORT_NAME или "1.2.840.113554.1.2.2.1".
- Параметры:
-
nameType- Oid типа имени для поиска - Возвращает:
- массив объектов Oid, соответствующих механизмам, которые поддерживают указанный тип имени.
nullвозвращается, когда механизмы, поддерживающие указанный тип имени, не найдены. - См. также:
createName
public abstract GSSName createName(String nameStr, Oid nameType) throws GSSException
GSSName будет содержать несколько представлений имени, по одному для каждого поддерживаемого механизма; два примера исключений из этого правила — когда параметр типа пространства имен указывает NT_EXPORT_NAME или когда реализация GSS-API не является многомеханической. Не рекомендуется использовать этот метод с типом NT_EXPORT_NAME, потому что представление ранее экспортированного имени, состоящего из произвольных байтов, как строки, может привести к проблемам с схемами кодирования символов. В таких случаях рекомендуется передавать байты непосредственно в перегруженный вариант этого метода createName.- Параметры:
-
nameStr- строка, представляющая удобочитаемую форму имени для создания. -
nameType- Oid, определяющий пространство имен удобочитаемого имени.nullможет быть использован для указания того, что каждый механизм, анализирующий имя nameStr, должен предполагать механически-специфичный стандартный синтаксис удобочитаемого имени. Не рекомендуется использовать тип имени NT_EXPORT_NAME с этим методом. - Возвращает:
- GSSName, представляющий указанного принципала
- Исключение:
-
GSSException- содержащий следующие основные коды ошибок:GSSException.BAD_NAMETYPE,GSSException.BAD_NAME,GSSException.BAD_MECH,GSSException.FAILURE - См. также:
createName
public abstract GSSName createName(byte[] name, Oid nameType) throws GSSException
GSSName будет содержать несколько представлений имени, по одному для каждого поддерживаемого механизма; два примера исключений из этого правила — когда параметр типа пространства имен указывает NT_EXPORT_NAME или когда реализация GSS-API не является многомеханической. Байты, которые передаются, интерпретируются каждым основным механизмом в соответствии с какой-либо схемой кодирования по своему выбору для данного типа имени.- Параметры:
-
name- массив байтов, содержащий имя для создания -
nameType- Oid, определяющий пространство имен имени, предоставленного в массиве байтов.nullможет быть использован для указания того, что каждый механизм, анализирующий массив байтов, должен предполагать механически-специфичный стандартный синтаксис. - Возвращает:
- GSSName, представляющий указанного принципала
- Исключение:
-
GSSException- содержащий следующие основные коды ошибок:GSSException.BAD_NAMETYPE,GSSException.BAD_NAME,GSSException.BAD_MECH,GSSException.FAILURE - См. также:
createName
public abstract GSSName createName(String nameStr, Oid nameType, Oid mech) throws GSSException
createName и затем также GSSName.canonicalize.- Параметры:
-
nameStr- строка, представляющая удобочитаемую форму имени для создания. -
nameType- Oid, определяющий пространство имен удобочитаемого имени.nullможет быть использован для указания того, что каждый механизм, анализирующий имя nameStr, должен предполагать механически-специфичный стандартный синтаксис удобочитаемого имени. Не рекомендуется использовать тип имени NT_EXPORT_NAME с этим методом. -
mech- Oid, определяющий механизм, для которого имя должно быть канонизировано - Возвращает:
- GSSName, представляющий указанного принципала
- Исключение:
-
GSSException- содержащий следующие основные коды ошибок:GSSException.BAD_NAMETYPE,GSSException.BAD_NAME,GSSException.BAD_MECH,GSSException.FAILURE - См. также:
createName
public abstract GSSName createName(byte[] name, Oid nameType, Oid mech) throws GSSException
createName и затем также GSSName.canonicalize.- Параметры:
-
name- массив байтов, содержащий имя для создания -
nameType- Oid, определяющий пространство имен имени, предоставленного в массиве байтов.nullможет быть использован для указания того, что каждый механизм, анализирующий массив байтов, должен предполагать механически-специфичный стандартный синтаксис. -
mech- Oid, определяющий механизм, для которого имя должно быть канонизировано - Возвращает:
- GSSName, представляющий указанного принципала
- Исключение:
-
GSSException- содержащий следующие основные коды ошибок:GSSException.BAD_NAMETYPE,GSSException.BAD_NAME,GSSException.BAD_MECH,GSSException.FAILURE - См. также:
createCredential
public abstract GSSCredential createCredential(int usage) throws GSSException
Поставщики механизмов GSS-API должны накладывать локальную политику контроля доступа на вызывающие стороны, чтобы предотвратить несанкционированное получение учетных данных, на которые у вызывающей стороны нет прав. Виды разрешений, необходимые различным поставщикам механизмов, будут документированы для каждого механизма в отдельности. Неудачная проверка разрешений может привести к броску исключения SecurityException из этого метода.
- Parameters:
-
usage- Предполагаемое использование этого объекта учетных данных. Значение этого параметра должно быть одним из:GSSCredential.INITIATE_AND_ACCEPT,GSSCredential.ACCEPT_ONLYиGSSCredential.INITIATE_ONLY. - Returns:
- объект GSSCredential запрошенного типа.
- Throws:
-
GSSException- содержащий следующие основные коды ошибок:GSSException.BAD_MECH,GSSException.BAD_NAMETYPE,GSSException.BAD_NAME,GSSException.CREDENTIALS_EXPIRED,GSSException.NO_CRED,GSSException.FAILURE - See Also:
createCredential
public abstract GSSCredential createCredential(GSSName name, int lifetime, Oid mech, int usage) throws GSSException
Поставщики механизмов GSS-API должны накладывать локальную политику контроля доступа на вызывающие стороны, чтобы предотвратить несанкционированное получение учетных данных, на которые у вызывающей стороны нет прав. Неудачная проверка разрешений может привести к броску исключения SecurityException из этого метода.
Значения срока действия, отличные от значений по умолчанию, не всегда могут быть учтены базовыми механизмами, поэтому приложения должны быть готовы вызвать getRemainingLifetime для возвращаемых учетных данных.
- Parameters:
-
name- имя принципала, для которого необходимо получить учетные данные. Используйтеnullдля указания принципала по умолчанию. -
lifetime- количество секунд, в течение которых учетные данные должны оставаться действительными. ИспользуйтеGSSCredential.INDEFINITE_LIFETIMEдля запроса максимального допустимого срока действия учетных данных. ИспользуйтеGSSCredential.DEFAULT_LIFETIMEдля запроса срока действия учетных данных по умолчанию. -
mech- Oid желаемого механизма. Используйте(Oid) nullдля запроса механизма по умолчанию. -
usage- Предполагаемое использование этого объекта учетных данных. Значение этого параметра должно быть одним из:GSSCredential.INITIATE_AND_ACCEPT,GSSCredential.ACCEPT_ONLYиGSSCredential.INITIATE_ONLY. - Returns:
- объект GSSCredential запрошенного типа.
- Throws:
-
GSSException- содержащий следующие основные коды ошибок:GSSException.BAD_MECH,GSSException.BAD_NAMETYPE,GSSException.BAD_NAME,GSSException.CREDENTIALS_EXPIRED,GSSException.NO_CRED,GSSException.FAILURE - See Also:
createCredential
public abstract GSSCredential createCredential(GSSName name, int lifetime, Oid[] mechs, int usage) throws GSSException
GSSCredential.getMechs. Поставщики механизмов GSS-API должны накладывать локальную политику контроля доступа на вызывающие стороны, чтобы предотвратить несанкционированное получение учетных данных, на которые у вызывающей стороны нет прав. Неудачная проверка разрешений может привести к броску исключения SecurityException из этого метода.
Значения срока действия, отличные от значений по умолчанию, не всегда могут быть учтены базовыми механизмами, поэтому приложения должны быть готовы вызвать getRemainingLifetime для возвращаемых учетных данных.
- Parameters:
-
name- имя принципала, для которого необходимо получить учетные данные. Используйтеnullдля указания принципала по умолчанию. -
lifetime- количество секунд, в течение которых учетные данные должны оставаться действительными. ИспользуйтеGSSCredential.INDEFINITE_LIFETIMEдля запроса максимального допустимого срока действия учетных данных. ИспользуйтеGSSCredential.DEFAULT_LIFETIMEдля запроса срока действия учетных данных по умолчанию. -
mechs- массив Oid, указывающий механизмы, для которых необходимо получить учетные данные. Используйте(Oid[]) nullдля запроса набора механизмов по умолчанию. -
usage- Предполагаемое использование этого объекта учетных данных. Значение этого параметра должно быть одним из:GSSCredential.INITIATE_AND_ACCEPT,GSSCredential.ACCEPT_ONLYиGSSCredential.INITIATE_ONLY. - Returns:
- объект GSSCredential запрошенного типа.
- Throws:
-
GSSException- содержащий следующие основные коды ошибок:GSSException.BAD_MECH,GSSException.BAD_NAMETYPE,GSSException.BAD_NAME,GSSException.CREDENTIALS_EXPIRED,GSSException.NO_CRED,GSSException.FAILURE - See Also:
createContext
public abstract GSSContext createContext(GSSName peer, Oid mech, GSSCredential myCred, int lifetime) throws GSSException
SecurityException из этого метода. Значения срока действия, отличные от значений по умолчанию, не всегда могут быть учтены базовым механизмом, поэтому приложения должны быть готовы вызвать getLifetime для возвращаемого контекста.
- Parameters:
-
peer- имя целевого узла. -
mech- Oid желаемого механизма. Используйтеnullдля запроса механизма по умолчанию. -
myCred- учетные данные инициатора. Используйтеnullдля использования принципала-инициатора по умолчанию. -
lifetime- срок действия, в секундах, запрашиваемый для контекста. ИспользуйтеGSSContext.INDEFINITE_LIFETIMEдля запроса максимального допустимого срока действия контекста. ИспользуйтеGSSContext.DEFAULT_LIFETIMEдля запроса срока действия контекста по умолчанию. - Returns:
- неустановленный GSSContext
- Throws:
-
GSSException- содержащий следующие основные коды ошибок:GSSException.NO_CREDGSSException.CREDENTIALS_EXPIREDGSSException.BAD_NAMETYPEGSSException.BAD_MECHGSSException.FAILURE - See Also:
createContext
public abstract GSSContext createContext(GSSCredential myCred) throws GSSException
SecurityException из этого метода.- Parameters:
-
myCred- учетные данные акцептора. Используйтеnullдля использования принципала-акцептора по умолчанию. - Returns:
- неустановленный GSSContext
- Throws:
-
GSSException- содержащий следующие основные коды ошибок:GSSException.NO_CREDGSSException.CREDENTIALS_EXPIREDGSSException.BAD_MECHGSSException.FAILURE - See Also:
createContext
public abstract GSSContext createContext(byte[] interProcessToken) throws GSSException
Реализации не обязаны поддерживать межпроцессный перенос контекстов безопасности. Перед экспортом контекста, вызов GSSContext.isTransferable укажет, является ли контекст передаваемым. Вызов этого метода в реализации, которая не поддерживает эту функцию, приведет к GSSException с кодом ошибки GSSException.UNAVAILABLE. Некоторые поставщики механизмов могут потребовать, чтобы у вызывающего процесса были разрешения на инициацию или принятие контекста безопасности. Неудачная проверка разрешений может вызвать исключение SecurityException из этого метода.
- Parameters:
-
interProcessToken- токен, ранее выпущенный методом export. - Returns:
- ранее созданный GSSContext
- Throws:
-
GSSException- содержащий следующие основные коды ошибок:GSSException.NO_CONTEXT,GSSException.DEFECTIVE_TOKEN,GSSException.UNAVAILABLE,GSSException.UNAUTHORIZED,GSSException.FAILURE - See Also:
addProviderAtFront
public abstract void addProviderAtFront(Provider p, Oid mech) throws GSSException
Oid для механизма используется значение null, GSSManager должен использовать указанного поставщика перед всеми другими, независимо от механизма. Только если указанный поставщик не поддерживает необходимый механизм, GSSManager переходит к другому поставщику.Повторный вызов этого метода сохраняет предыдущие настройки, но понижает их приоритет, таким образом формируя упорядоченный список пар «поставщик-механизм», который увеличивается сверху.
Вызов addProviderAtFront с null Oid удалит все предыдущие настройки для этого поставщика в экземпляре GSSManager. Вызов addProviderAtFront с не-null Oid удалит любые предыдущие настройки, заданные с использованием этого механизма и этого поставщика вместе.
Если реализация GSSManager не поддерживает SPI с архитектурой подключаемых поставщиков, она должна выбросить GSSException с кодом состояния GSSException.UNAVAILABLE, чтобы указать, что операция недоступна.
Предположим, что приложение хочет, чтобы поставщик A всегда проверялся первым при необходимости любого механизма, оно вызовет:
GSSManager mgr = GSSManager.getInstance();
// mgr may at this point have its own pre-configured list
// of provider preferences. The following will prepend to
// any such list:
mgr.addProviderAtFront(A, null);
Теперь, если оно также хочет, чтобы механизм Oid m1 всегда получался от поставщика B до проверки ранее установленного A, оно вызовет:
mgr.addProviderAtFront(B, m1);
GSSManager в этом случае сначала проверит B, если нужен m1. В случае, если B не поддерживает m1, GSSManager продолжит проверку у A. Если нужен любой механизм m2, отличающийся от m1, GSSManager пропустит B и проверит A напрямую.Предположим, что впоследствии будет сделан следующий вызов тому же экземпляру GSSManager:
mgr.addProviderAtFront(B, null)
тогда предыдущая настройка с парой (B, m1) будет подсумирована, и поэтому она должна быть удалена. Таким образом, список предпочтений теперь станет {(B, null), (A, null), ... //последующий список предварительно настроенных}.Обратите внимание, что следующий вызов:
mgr.addProviderAtFront(A, m3)
не подсумирует предыдущую настройку (A, null), и список фактически станет {(A, m3), (B, null), (A, null), ...}- Parameters:
-
p- экземпляр поставщика, который должен использоваться всякий раз, когда нужна поддержка для mech. -
mech- механизм, для которого устанавливается поставщик - Throws:
-
GSSException- содержащий следующие основные коды ошибок:GSSException.UNAVAILABLE,GSSException.FAILURE
addProviderAtEnd
public abstract void addProviderAtEnd(Provider p, Oid mech) throws GSSException
Повторный вызов этого метода сохраняет предыдущие настройки, но повышает их приоритет над новыми, таким образом формируя упорядоченный список пар «поставщик-Oid», который увеличивается снизу. Таким образом, более старые настройки поставщика будут использоваться в первую очередь, прежде чем будет использована эта.
Если существуют какие-либо ранее заданные предпочтения, конфликтующие с устанавливаемым здесь предпочтением, то GSSManager должен проигнорировать этот запрос.
Если реализация GSSManager не поддерживает SPI с архитектурой подключаемых поставщиков, она должна выбросить GSSException с кодом состояния GSSException.UNAVAILABLE, чтобы указать, что операция недоступна.
Предположим, что приложение хочет, чтобы при необходимости механизма с Oid m1 система всегда проверяла стандартные поставщики в первую очередь, а только если они не поддерживают m1, должен проверяться поставщик A. Тогда оно вызовет:
GSSManager mgr = GSSManager.getInstance();
mgr.addProviderAtEnd(A, m1);
Теперь, если оно также хочет, чтобы для всех механизмов поставщик B проверялся после проверки всех настроенных поставщиков, оно вызовет:
mgr.addProviderAtEnd(B, null);
Таким образом, список предпочтений теперь станет {..., (A, m1), (B, null)}.Предположим, что впоследствии будет сделан следующий вызов тому же экземпляру GSSManager:
mgr.addProviderAtEnd(B, m2)
тогда предыдущая настройка с парой (B, null) подсумирует эту, и поэтому этот запрос должен быть проигнорирован. То же самое произойдёт, если запрос сделан для уже существующих пар (A, m1) или (B, null).Обратите внимание, что следующий вызов:
mgr.addProviderAtEnd(A, null)
не подсумирует предыдущую настройку (A, m1), и список фактически станет {..., (A, m1), (B, null), (A, null)}- Parameters:
-
p- экземпляр поставщика, который должен использоваться всякий раз, когда нужна поддержка для mech. -
mech- механизм, для которого устанавливается поставщик - Throws:
-
GSSException- содержащий следующие основные коды ошибок:GSSException.UNAVAILABLE,GSSException.FAILURE
© 1993, 2021, 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/17/docs/api/java.security.jgss/org/ietf/jgss/GSSManager.html