Класс GSSManager

Этот класс служит фабрикой для других важных классов 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 позволяет приложению устанавливать предпочтения поставщика в такой реализации. Эти методы также позволяют реализации генерировать хорошо определённое исключение в случае, если конфигурация на основе поставщика не поддерживается. Приложения, ожидающие быть переносимыми, должны учитывать это и обрабатывать исключение надлежащим образом.

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

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

Класс 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);

Конструкторы

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 идентифицирует механизм Kerberos v5 GSS-API, определённый в RFC 1964.

Возвращает:

массив объектов Oid, соответствующих доступным механизмам. Значение null возвращается, когда механизмы недоступны (например, когда механизмы динамически настраиваются, и в настоящее время механизмы не установлены).

getNamesForMech

public abstract Oid[] getNamesForMech(Oid mech)
                               throws GSSException

Параметры:

mech - Oid механизма для запроса

Возвращает:

массив объектов Oid, соответствующих типам имён, которые поддерживает механизм.

Выбрасывает:

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

См. также:

getMechsForName(Oid)

getMechsForName

public abstract Oid[] getMechsForName(Oid nameType)

Параметры:

nameType - Oid типа имени для поиска

Возвращает:

массив объектов Oid, соответствующих механизмам, которые поддерживают указанный тип имени. null возвращается, когда механизмы, поддерживающие указанный тип имени, не найдены.

См. также:

getNamesForMech(Oid)

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

Возвращает:

GSSName, представляющий указанного принципала

Выбрасывает:

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

См. также:

GSSName, GSSName.NT_EXPORT_NAME

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

См. также:

GSSName, GSSName.NT_EXPORT_NAME

createName

public abstract GSSName createName(String nameStr,
                                   Oid nameType,
                                   Oid mech)
                            throws GSSException

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

Параметры:

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

nameType - Oid, определяющий пространство имён печатного имени. null может быть использован для указания того, что каждый механизм, проверяющий имя, должен использовать механизм-специфичный синтаксис по умолчанию. Не рекомендуется использовать тип имени NT_EXPORT_NAME с этим методом.

mech - Oid, определяющий механизм, для которого имя должно быть канонизировано

Возвращает:

GSSName, представляющий указанного принципала

Выбрасывает:

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

См. также:

GSSName.canonicalize(Oid), GSSName.NT_EXPORT_NAME

createName

public abstract GSSName createName(byte[] name,
                                   Oid nameType,
                                   Oid mech)
                            throws GSSException

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

Параметры:

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

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

mech - Oid, определяющий механизм, для которого имя должно быть канонизировано

Возвращает:

GSSName, представляющий указанного принципала

Выбрасывает:

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

См. также:

GSSName.canonicalize(Oid), GSSName.NT_EXPORT_NAME

createCredential

public abstract GSSCredential createCredential(int usage)
                                        throws GSSException

Параметры:

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

См. также:

GSSCredential

createCredential

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

Параметры:

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

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

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

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

См. также:

GSSCredential

createCredential

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

Параметры:

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

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

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

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

См. также:

GSSCredential

createContext

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

Параметры:

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

См. также:

GSSContext

createContext

public abstract GSSContext createContext(GSSCredential myCred)
                                  throws GSSException

Метод-фабрика для создания контекста со стороны акцептора. Свойства контекста будут определяться входным токеном, предоставленным методу accept. Некоторые поставщики механизмов могут потребовать, чтобы вызывающая сторона имела разрешение на принятие защищенного контекста. Неудача проверки разрешений может привести к выбрасыванию исключения SecurityException из этого метода.

Параметры:

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

Возвращает:

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

Исключения:

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

См. также:

GSSContext

createContext

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

Параметры:

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

Возвращает:

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

Исключения:

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

См. также:

GSSContext

addProviderAtFront

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

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);

mgr.addProviderAtFront(B, m1);

mgr.addProviderAtFront(B, null)

mgr.addProviderAtFront(A, m3)

Параметры:

p - экземпляр поставщика, который должен использоваться всякий раз, когда нужна поддержка для mech.

mech - механизм, для которого настраивается поставщик

Исключения:

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

addProviderAtEnd

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

GSSManager mgr = GSSManager.getInstance();
         mgr.addProviderAtEnd(A, m1);

mgr.addProviderAtEnd(B, null);

mgr.addProviderAtEnd(B, m2)

mgr.addProviderAtEnd(A, null)

Параметры:

p - экземпляр поставщика, который должен использоваться всякий раз, когда нужна поддержка для mech.

mech - механизм, для которого настраивается поставщик

Исключения:

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