Класс 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 по умолчанию поддерживает механизм GSS-API Kerberos v5, а также любые другие механизмы. Этот механизм имеет 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);

Since:

1.4

See Also:

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

Конструктор	Описание
`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)`	Возвращает типы имён, поддерживаемые указанным механизмом.

Методы, объявленные в классе 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, поскольку представление ранее экспортированного имени, состоящего из произвольных байтов, в виде String может привести к проблемам с кодировкой символов. В таких случаях рекомендуется передавать байты непосредственно в перегруженную форму этого метода 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. Как правило, созданный объект 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 должен перейти к другому поставщику, только если указанный поставщик не поддерживает требуемый механизм.

Повторные вызовы этого метода сохраняют предыдущие настройки, но понижают их приоритет, формируя упорядоченный список пар «поставщик и Oid», который расширяется в начале.

Вызов addProviderAtFront с null в качестве Oid удаляет все предыдущие настройки для этого поставщика в экземпляре GSSManager. Вызов addProviderAtFront с ненулевым 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://docs.oracle.com/en/java/javase/25/docs/api/java.security.jgss/org/ietf/jgss/GSSManager.html