Класс 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, может быть реализован как модульный провайдерский слой, который использует некоторые хорошо известные спецификации провайдеров. 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 |
Этот метод используется для указания 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 идентифицирует механизм 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_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. Не рекомендуется использовать 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 будет содержать несколько представлений имени, по одному для каждого поддерживаемого механизма; два примера исключений из этого – когда параметр типа пространства имён указывает NT_EXPORT_NAME или когда реализация GSS-API не является многомеханической. Байты, которые передаются, интерпретируются каждым базовым механизмом в соответствии со схемой кодирования по своему выбору для данного nametype.- Параметры:
-
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. Не рекомендуется использовать nametype 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
Повторный вызов этого метода сохраняет более старые настройки, но понижает их приоритет, формируя упорядоченный список пар поставщик-механизм, который растет сверху.
Вызов 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, 2023, 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/21/docs/api/java.security.jgss/org/ietf/jgss/GSSManager.html