Класс GSSManager

java.lang.Object

org.ietf.jgss.GSSManager

public abstract class GSSManager extends Object

Этот класс служит фабрикой для других важных классов GSS-API и также предоставляет информацию о поддерживаемых механизмах. Он может создавать экземпляры классов, реализующих следующие три интерфейса GSS-API: GSSName, GSSCredential и GSSContext. Он также имеет методы для запроса списка доступных механизмов и типов имён, которые поддерживает каждый механизм.

Экземпляр по умолчанию GSSManager подкласса может быть получен через статический метод getInstance, но приложения могут свободно создавать другие подклассы GSSManager. Экземпляр по умолчанию GSSManager будет поддерживать механизм Kerberos v5 GSS-API в дополнение к другим, если таковые имеются. Этот механизм идентифицируется с помощью Oid "1.2.840.113554.1.2.2" и определен в RFC 1964.

Подкласс, расширяющий абстрактный класс GSSManager, может быть реализован как модульный провайдер, использующий спецификацию провайдера известных сервисов. API GSSManager позволяет приложению устанавливать предпочтения провайдера для такой реализации. Эти методы также позволяют реализации выбрасывать четко определённое исключение в случае если основанная на провайдере конфигурация не поддерживается. Приложения, которые ожидают портативности, должны быть осведомлены об этом и должны корректно обрабатывать это исключение.

Предполагается, что будут три наиболее распространённых способа использования провайдеров:

Приложению неважно, какой провайдер используется (случай по умолчанию).
Приложение хочет, чтобы определённый провайдер использовался в приоритете, либо для определённого механизма, либо всегда, независимо от механизма.
Приложение хочет использовать локально сконфигурированные провайдеры по возможности, но если поддержка отсутствует для одного или нескольких механизмов, то оно хочет перейти к своему собственному провайдеру.

Класс GSSManager имеет два метода, которые позволяют использовать эти режимы: addProviderAtFront и addProviderAtEnd. Эти методы создают упорядоченный список пар <провайдер, 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);

С момента:

1.4

См. также:

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

Конструктор	Описание
`GSSManager()`	Конструктор для вызова подклассами.

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

Модификатор и тип	Метод	Описание
`abstract void`	`addProviderAtEnd(Provider p, Oid mech)`	Этот метод используется для указания GSSManager, что приложение хочет использовать конкретный провайдер, если не удастся найти другой провайдер, который поддерживает указанный механизм.
`abstract void`	`addProviderAtFront(Provider p, Oid mech)`	Этот метод используется для указания GSSManager, что приложение хочет использовать конкретный провайдер впереди всех других, когда требуется поддержка для данного механизма.
`abstract GSSContext`	`createContext(byte[] interProcessToken)`	Метод-фабрика для создания ранее экспортированного контекста.
`abstract GSSContext`	`createContext(GSSCredential myCred)`	Метод-фабрика для создания контекста со стороны получателя.
`abstract GSSContext`	`createContext(GSSName peer, Oid mech, GSSCredential myCred, int lifetime)`	Метод-фабрика для создания контекста со стороны инициатора.
`abstract GSSCredential`	`createCredential(int usage)`	Метод-фабрика для получения по умолчанию учётных данных.
`abstract GSSCredential`	`createCredential(GSSName name, int lifetime, Oid[] mechs, int usage)`	Метод-фабрика для получения учётных данных по набору механизмов.
`abstract GSSCredential`	`createCredential(GSSName name, int lifetime, Oid mech, int usage)`	Метод-фабрика для получения учётных данных для одного механизма.
`abstract GSSName`	`createName(byte[] name, Oid nameType)`	Метод-фабрика для преобразования массива байт, содержащего имя из указанного пространства имён, в объект GSSName.
`abstract GSSName`	`createName(byte[] name, Oid nameType, Oid mech)`	Метод-фабрика для преобразования массива байт, содержащего имя из указанного пространства имён, в объект GSSName и его канонизации одновременно для механизма.
`abstract GSSName`	`createName(String nameStr, Oid nameType)`	Метод-фабрика для преобразования строкового имени из указанного пространства имён в объект GSSName.
`abstract GSSName`	`createName(String nameStr, Oid nameType, Oid mech)`	Метод-фабрика для преобразования строкового имени из указанного пространства имён в объект GSSName и его канонизации одновременно для механизма.
`static GSSManager`	`getInstance()`	Возвращает реализацию GSSManager по умолчанию.
`abstract Oid[]`	`getMechs()`	Возвращает список механизмов, доступных вызывающим GSS-API через этот GSSManager.
`abstract Oid[]`	`getMechsForName(Oid nameType)`	Возвращает список механизмов, которые поддерживают указанный тип имени.
`abstract Oid[]`	`getNamesForMech(Oid mech)`	Возвращает типы имён, поддерживаемые указанным механизмом.

Методы, объявленные в классе java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Подробное описание конструкторов

GSSManager

public GSSManager()

Конструктор для вызова подклассами.

Подробное описание методов

getInstance

public static GSSManager getInstance()

Возвращает реализацию по умолчанию GSSManager.

Возвращает:: реализация GSSManager

getMechs

public abstract Oid[] getMechs()

Возвращает список механизмов, доступных вызывающим сторонам GSS-API через этот GSSManager. По умолчанию GSSManager, полученный из метода getInstance(), включает Oid "1.2.840.113554.1.2.2" в свой список. Этот Oid идентифицирует механизм GSS-API Kerberos v5, определённый в 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_MECH GSSException.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. В общем случае, созданный объект GSSName будет содержать несколько представлений имени, по одному для каждого поддерживаемого механизма; два исключения — когда параметр типа пространства имён указывает NT_EXPORT_NAME или когда реализация GSS-API не многомеханизменная. Не рекомендуется использовать этот метод с типом NT_EXPORT_NAME, потому что представление ранее экспортированного имени, состоящего из произвольных байтов, как строки может привести к проблемам с кодировками символов. В таких случаях рекомендуется передавать байты напрямую в перегруженную форму этого метода createName.

Параметры:

nameStr - строка, представляющая печатную форму создаваемого имени.

nameType - Oid, определяющий пространство имён предоставленного печатного имени. null может быть использовано для указания того, что каждый механизм, анализирующий nameStr, должен предполагать собственную печатную форму по умолчанию. Не рекомендуется использовать nametype 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. В общем случае, созданный объект 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

Метод-фабрика для преобразования строкового имени из указанного пространства имён в объект GSSName и канонизации его одновременно для механизма. Другими словами, этот метод — утилита, выполняющая две операции: createName и затем также GSSName.canonicalize.

Параметры:

nameStr - строка, представляющая печатную форму создаваемого имени.

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

Метод-фабрика для преобразования массива байтов, содержащего имя из указанного пространства имён, в объект GSSName и канонизации его одновременно для механизма. Другими словами, этот метод — утилита, выполняющая две операции: createName и затем также GSSName.canonicalize.

Параметры:

name - массив байтов, содержащий создаваемое имя

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 системных значений по умолчанию для набора механизмов, имени и срока действия.

Параметры:

usage - Предполагаемое использование этого объекта учетных данных. Значение этого параметра должно быть одним из следующих: GSSCredential.INITIATE_AND_ACCEPT, GSSCredential.ACCEPT_ONLY и GSSCredential.INITIATE_ONLY.

Возвращает:

GSSCredential запрошенного типа.

Исключение:

GSSException - содержащий следующие основные коды ошибок: GSSException.BAD_MECH, GSSException.BAD_NAMETYPE, GSSException.BAD_NAME, GSSException.CREDENTIALS_EXPIRED, GSSException.NO_CRED, GSSException.FAILURE

См. также:

createCredential

public abstract GSSCredential createCredential(GSSName name, int lifetime, Oid mech, int usage) throws GSSException

Метод-фабрика для получения учетных данных для одного механизма.

Значения срока действия, отличные от значений по умолчанию, не всегда могут быть учтены базовыми механизмами, поэтому приложения должны быть готовы вызвать getRemainingLifetime для полученных учетных данных.

Параметры:

name - имя принципала, для которого необходимо получить учетные данные. Используйте null для указания принципала по умолчанию.

lifetime - количество секунд, в течение которых учетные данные должны оставаться действительными. Используйте GSSCredential.INDEFINITE_LIFETIME для запроса максимального срока действия учетных данных. Используйте GSSCredential.DEFAULT_LIFETIME для запроса срока действия учетных данных по умолчанию.

mech - Oid нужного механизма. Используйте

(Oid) null

для запроса механизма по умолчанию.

Возвращает:

GSSCredential запрошенного типа.

Исключение:

См. также:

createCredential

public abstract GSSCredential createCredential(GSSName name, int lifetime, Oid[] mechs, int usage) throws GSSException

Метод-фабрика для получения учетных данных по набору механизмов. Этот метод пытается получить учетные данные для каждого из механизмов, указанных в массиве mechs. Чтобы определить список механизмов, для которых получение учетных данных было успешным, вызывающий метод должен использовать метод GSSCredential.getMechs.

Параметры:

mechs - массив Oid, указывающий механизмы, для которых должны быть получены учетные данные. Используйте (Oid[]) null для запроса системного набора механизмов по умолчанию.

Возвращает:

GSSCredential запрошенного типа.

Исключение:

См. также:

createContext

public abstract GSSContext createContext(GSSName peer, Oid mech, GSSCredential myCred, int lifetime) throws GSSException

Метод-фабрика для создания контекста со стороны инициатора.

Значения срока действия, отличные от значений по умолчанию, не всегда могут быть учтены базовым механизмом, поэтому приложения должны быть готовы вызвать getLifetime для полученного контекста.

Параметры:

peer - имя целевого партнера.

mech - Oid нужного механизма. Используйте null для запроса механизма по умолчанию.

myCred - учетные данные инициатора. Используйте null для использования принципала-инициатора по умолчанию.

lifetime - срок действия, в секундах, запрошенный для контекста. Используйте GSSContext.INDEFINITE_LIFETIME для запроса максимального срока действия контекста. Используйте GSSContext.DEFAULT_LIFETIME для запроса срока действия контекста по умолчанию.

Возвращает:

неустановленный GSSContext

Исключение:

GSSException - содержащий следующие основные коды ошибок: GSSException.NO_CRED GSSException.CREDENTIALS_EXPIRED GSSException.BAD_NAMETYPE GSSException.BAD_MECH GSSException.FAILURE

См. также:

createContext

public abstract GSSContext createContext(GSSCredential myCred) throws GSSException

Метод-фабрика для создания контекста со стороны акцептора. Свойства контекста будут определяться из входного токена, предоставленного методу accept.

Параметры:

myCred - учетные данные акцептора. Используйте null для использования принципала-акцептора по умолчанию.

Возвращает:

неустановленный GSSContext

Исключение:

GSSException - содержащий следующие основные коды ошибок: GSSException.NO_CRED GSSException.CREDENTIALS_EXPIRED GSSException.BAD_MECH GSSException.FAILURE

См. также:

createContext

public abstract GSSContext createContext(byte[] interProcessToken) throws GSSException

Метод-фабрика для создания ранее экспортированного контекста. Свойства контекста будут определяться из входного токена и не могут быть изменены с помощью методов set.

Реализации не обязаны поддерживать межпроцессный обмен контекстами безопасности. Перед экспортом контекста, вызов GSSContext.isTransferable укажет, переносим ли контекст. Вызов этого метода в реализации, которая не поддерживает его, приведет к GSSException с кодом ошибки GSSException.UNAVAILABLE.

Параметры:

interProcessToken - токен, ранее выпущенный методом export.

Возвращает:

ранее установленный GSSContext

Исключение:

GSSException - содержащий следующие основные коды ошибок: GSSException.NO_CONTEXT, GSSException.DEFECTIVE_TOKEN, GSSException.UNAVAILABLE, GSSException.UNAUTHORIZED, GSSException.FAILURE

См. также:

addProviderAtFront

public abstract void addProviderAtFront(Provider p, Oid mech) throws GSSException

Этот метод используется для указания GSSManager, что приложение желает использовать определённый поставщик перед всеми другими, когда требуется поддержка для данного механизма. Если вместо 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), ...}

Параметры:: p - экземпляр поставщика, который должен использоваться всякий раз, когда требуется поддержка для mech.; mech - механизм, для которого устанавливается поставщик
Исключения:: GSSException - содержащий следующие основные коды ошибок: GSSException.UNAVAILABLE, GSSException.FAILURE

addProviderAtEnd

public abstract void addProviderAtEnd(Provider p, Oid mech) throws GSSException

Этот метод используется для указания GSSManager, что приложение хочет использовать определённый поставщик, если ни один другой поставщик не может быть найден, который поддерживает данный механизм. Если вместо Oid для механизма используется значение null, GSSManager должен использовать указанный поставщик для любого механизма.

Повторный вызов этого метода сохраняет предыдущие настройки, но поднимает их выше новых в порядке предпочтения, формируя упорядоченный список пар "поставщик-Oid", растущий снизу. Таким образом, более старые настройки поставщика будут использоваться первыми, прежде чем будет использоваться эта.

Если существуют какие-либо ранее существующие предпочтения, конфликтующие с предпочтением, устанавливаемым здесь, то GSSManager должен проигнорировать этот запрос.

Предположим, что приложение желает, чтобы при необходимости механизма 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)}

Параметры:: p - экземпляр поставщика, который должен использоваться всякий раз, когда требуется поддержка для mech.; mech - механизм, для которого устанавливается поставщик
Исключения:: GSSException - содержащий следующие основные коды ошибок: GSSException.UNAVAILABLE, GSSException.FAILURE

© 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://download.java.net/java/early_access/jdk24/docs/api/java.security.jgss/org/ietf/jgss/GSSManager.html