KasperskyOS Community Edition 1.3

Использование сессий (session.h)

API определен в заголовочном файле sysroot-*-kos/include/kos/session.h из состава KasperskyOS SDK.

API предназначен для применения в коде поставщиков ресурсов, предоставляющих доступ к пользовательским ресурсам через IPC, и в коде программ, использующих пользовательские ресурсы локально (без IPC). API позволяет организовать управление доступом к пользовательским ресурсам на основе сессий. Сессия представляет собой последовательность действий: открытие доступа к ресурсу, использование ресурса, закрытие доступа к ресурсу. Открытие доступа к ресурсу создает сессию. Закрытие доступа к ресурсу завершает сессию. В одной сессии может выполняться несколько операций с ресурсом одновременно. Ресурс может быть использован в режиме эксклюзивного или множественного доступа. Во втором случае ресурс должен быть открыт несколько раз (возможно с разными правами доступа), то есть ресурс будет использован через множество одновременно существующих сессий (параллельных сессий).

"Объект" в описании API – это объект KosObject, который представляет собой абстракцию ресурса (об объектах KosObject см. "Использование объектов KosObject (objects.h)"). Также тип сессий и контекст сессии являются объектами KosObject. (Контекст сессии содержит сведения об этой сессии, такие как права доступа к ресурсу, счетчик активных операций с ресурсом.)

Сведения о функциях API приведены в таблице ниже.

Создание типа сессий

Созданию сессий предшествует создание их типа. Чтобы создать тип сессий, нужно вызвать функцию KosSessionCreateType().

Через параметр objectType нужно задать тип объектов, для которых предназначены сессии создаваемого типа. Тип объектов должен наследовать тип с идентификатором kosSessionBaseObjectType.

Через параметр sessionType нужно задать тип контекстов сессий. Можно указать базовый тип контекстов сессий с идентификатором kosSessionBaseSessionType либо тип, который наследует его. Базовому типу контекстов сессий соответствует структура, содержащая такие данные, как указатель на объект, права доступа к ресурсу, маска прав дескриптора ресурса, передаваемая потребителям ресурсов, счетчик активных операций с ресурсом в сессии (тип этой структуры не экспортируется программам, а используется библиотекой libkos). Можно добавить в контекст сессии дополнительные сведения, создав собственный тип контекстов сессий, наследующий базовый. Например, контекст сессии использования устройства может дополнительно содержать указатели на функции, вызываемые программами решения для работы с устройством.

Через параметр ops нужно задать callback-функции, вызываемые при создании и завершении сессий. Callback-функции для идентификаторов open и close нужно задать обязательно. Callback-функцию для идентификатора closeComplete можно не задавать, поэтому этот идентификатор может иметь значение RTL_NULL.

Callback-функция, соответствующая идентификатору open, вызывается при создании сессии и получает указатели на объект, контекст сессии, данные, переданные функции KosSessionOpenObject() через параметр openCtx, и буфер для сохранения маски прав дескриптора ресурса, передаваемой потребителям ресурсов. В этой callback-функции можно, например, проверить состояние ресурса, задать передаваемую потребителям ресурсов маску прав дескриптора ресурса, выполнить запись данных в объект или контекст сессии. Если код возврата будет отличным от rcOk, сессия не будет создана.

Callback-функция, соответствующая идентификатору close, вызывается при завершении сессии независимо от того, завершены операции с ресурсом или нет (счетчик активных операций в закрываемой сессии может быть больше нуля), и получает указатели на объект и контекст сессии. В этой callback-функции можно, например, прервать активные операции в завершаемой сессии, выполнить запись данных в объект или контекст сессии. Код возврата может быть произвольным.

Callback-функция, соответствующая идентификатору closeComplete, вызывается при завершении сессии только после завершения всех операций с ресурсом (счетчик активных операций в завершаемой сессии равен нулю) и получает указатели на объект и контекст сессии. В этой callback-функции можно, например, выполнить запись данных в объект.

Регистрация объекта

После создания типа сессий нужно зарегистрировать требуемые объекты как объекты, с которыми могут быть связаны сессии этого типа. Чтобы зарегистрировать объект, нужно вызвать функцию KosSessionRegisterObject().

Нельзя зарегистрировать один объект для связывания с разными типами сессий одновременно.

После регистрации объект готов к открытию.

Открытие объекта

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

Чтобы открыть объект, нужно вызвать функцию KosSessionOpenObject(). Через параметр requiredRights нужно задать права доступа к ресурсу в создаваемой сессии, а через параметр shareMode нужно задать права множественного доступа к ресурсу, которые устанавливают ограничения доступа к этому ресурсу для параллельных сессий. Например, если через параметр requiredRights заданы права на чтение и запись, а в параметре shareMode указан 0, то создаваемая сессия требует эксклюзивного доступа к ресурсу на чтение и запись. Если через параметр requiredRights заданы права на чтение и запись, а через параметр shareMode заданы права только на чтение, то создаваемая сессия требует доступа на чтение и запись и разрешает чтение в параллельных сессиях. Если через параметр requiredRights заданы права на чтение, а через параметр shareMode заданы права на чтение и запись, то создаваемая сессия требует доступа на чтение, а также разрешает чтение и запись в параллельных сессиях.

Если ресурс требуется использовать в режиме множественного доступа, то при втором и последующих открытиях объекта нужно учесть следующие условия:

• Права доступа, задаваемые через параметр requiredRights, не могут превышать минимальных прав доступа, заданных через параметр shareMode для всех параллельных сессий, связанных с этим объектом.
• Права доступа, задаваемые через параметр shareMode, должны включать все права доступа, заданные через параметр requiredRights для всех параллельных сессий, связанных с этим объектом.

В результате открытия объекта будет создан контекст сессии.

Если программа использует ресурсы локально, то после открытия объекта компонент программы, управляющий ресурсами, должен передать компоненту программы, использующему ресурсы, указатель на созданный контекст сессии. Запрашивая в дальнейшем операции с ресурсом, компонент программы, использующий ресурсы, должен передавать этот указатель компоненту программы, управляющему ресурсами, для идентификации сессии.

Поставщик ресурсов после открытия объекта должен передать потребителю дескриптор ресурса. В качестве контекста передачи ресурса должен использоваться контекст сессии, чтобы потребитель получил дескриптор ресурса, связанный с сессией. Запрашивая в дальнейшем операции с ресурсом, потребитель должен помещать полученный дескриптор ресурса в IPC-запросы, чтобы после разыменования этого дескриптора поставщик получал указатель на контекст сессии. Чтобы заполнить данными транспортный контейнер дескриптора ресурса для передачи потребителю ресурсов, нужно вызвать функцию KosSessionContextToIpcHandle(). Через параметр sessionCtx эта функция получает контекст сессии, а через параметр desc передает транспортный контейнер дескриптора ресурса.

Функция KosSessionContextToIpcHandle() помещает в транспортный контейнер дескриптора ресурса маску прав, заданную в callback-функции, которая вызывается при создании сессии. Права доступа, заданные в этой маске, не должны превышать права доступа в сессии, заданные через параметр requiredRights функции KosSessionOpenObject(). При этом одно и то же право доступа может соответствовать разным битам в маске прав и в значении, заданном через параметр requiredRights функции KosSessionOpenObject().

В качестве контекста передачи ресурса функция KosSessionContextToIpcHandle() задает контекст сессии. Контекст сессии будет автоматически удален (соответственно сессия будет завершена) после закрытия или отзыва дескрипторов ресурса, порожденных передачей дескриптора ресурса, который получен вызовом функции KosSessionContextToIpcHandle(). Если требуется предотвратить автоматическое завершение сессии для последующего завершения вызовом функции KosSessionCloseObject(), перед передачей дескриптора ресурса нужно инкрементировать счетчик ссылок на контекст этой сессии вызовом функции KosRefObject() из API objects.h. В этом случае после вызова функции KosSessionCloseObject() нужно декрементировать счетчик ссылок на контекст сессии вызовом функции KosPutObject() из API objects.h.

Выполнение операций с ресурсом

Операция с ресурсом (например, чтение, запись, получение параметров) выполняется по запросу через IPC от потребителя ресурсов или по локальному запросу от другого компонента программы.

Сценарий выполнения операции с ресурсом включает следующие шаги:

1. Проверить права доступа к ресурсу.

   При обработке локального запроса нужно вызвать функцию KosSessionGetOpenRights(). Эта функция позволяет получить сведения о правах доступа к ресурсу в сессии, заданных через параметр requiredRights функции KosSessionOpenObject(), чтобы сравнить эти права с требуемыми для выполнения операции.

   При обработке IPC-запроса нужно вызвать функцию KosSessionIpcHandleToSession(), которая позволяет получить контекст сессии, а также проверяет, что маска прав дескриптора ресурса, который потребитель ресурсов поместил в IPC-запрос, соответствует запрашиваемой операции. Через параметр desc нужно передать функции полученный от потребителя ресурса транспортный контейнер дескриптора ресурса. В параметре operation нужно указать права доступа к ресурсу, требуемые для выполнения запрашиваемой операции. В параметре type можно указать идентификатор типа сессии, чтобы проверить, что тип контекста сессии соответствует типу сессии. Если в параметре type указать значение RTL_NULL, то перед приведением типа указателя, полученного через параметр sessionCtx, нужно проверить тип контекста сессии. Проверку типа контекста сессии нужно сделать обязательно, поскольку поставщик ресурсов может создавать сессии с контекстами разных типов, а потребитель ресурсов может ошибочно поместить в IPC-запрос дескриптор ресурса, который соответствует сессии с контекстом другого типа. Чтобы проверить тип контекста, нужно использовать API objects.h.

2. Инкрементировать счетчик активных операций в сессии вызовом функции KosSessionRef().

   Функция проверяет, что сессия не завершена. В параметре type можно указать идентификатор типа сессии, чтобы проверить, что тип контекста сессии соответствует типу сессии. Через параметр object можно получить указатель на объект.

3. Выполнить запрошенные действия с ресурсом.
4. Декрементировать счетчик активных операций в сессии вызовом функции KosSessionPut().

Получение дескриптора ресурса

Дескриптор ресурса может потребоваться, например, для использования уведомлений или для обращения к модулю безопасности Kaspersky Security Module через интерфейс безопасности. Чтобы получить дескриптор ресурса по объекту или по контексту сессии, нужно вызвать функцию KosSessionGetObjectHandle() или KosSessionGetObjectHandleBySession() соответственно.

Перечисление сессий, связанных с объектом

Перечисление сессий, связанных с объектом, может потребоваться, например, чтобы сообщать о состоянии ресурса каждому из потребителей ресурсов, использующих этот ресурс. Чтобы перечислить сессии, связанные с объектом, нужно вызвать функцию KosSessionWalk(). Через параметр handler нужно задать callback-функцию, которая вызывается для каждой сессии при перечислении и получает указатели на объект, контекст сессии и данные, переданные функции KosSessionWalk() через параметр walkCtx. В этой callback-функции можно, например, отправить потребителям ресурсов уведомления о состоянии ресурса.

Закрытие объекта

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

Закрытие объекта выполняется по запросу на закрытие доступа к ресурсу. Это может быть запрос через IPC от потребителя ресурсов или локальный запрос от другого компонента программы. После выполнения запроса на закрытие доступа к ресурсу потребитель ресурсов должен закрыть дескриптор этого ресурса. (Если потребитель ресурсов завершится, не выполнив запрос на закрытие доступа к ресурсу, либо закроет дескриптор ресурса без выполнения этого запроса, то соответствующая сессия будет автоматически завершена при условии, что поставщик ресурсов дополнительно не инкременетировал счетчик ссылок на контекст этой сессии.)

Чтобы закрыть объект, нужно вызвать функцию KosSessionCloseObject() или KosSessionCloseObjectByIpcHandle().

Функция KosSessionCloseObject() завершает сессию, соответствующую контексту сессии, заданному через параметр sessionCtx.

Функция KosSessionCloseObjectByIpcHandle() завершает сессию, с которой связан дескриптор ресурса, помещенный потребителем ресурса в IPC-запрос на закрытие доступа к ресурсу. Через параметр desc нужно передать функции полученный транспортный контейнер дескриптора ресурса. В параметре type можно указать идентификатор типа сессии, чтобы проверить, что тип контекста сессии соответствует типу сессии.

Дерегистрация объекта

Дерегистрация объекта делает невозможным открытие этого объекта и завершает все связанные с ним сессии. Завершение сессии не будет выполнено, пока не будут завершены все операции в этой сессии, то есть счетчик активных операций не станет равным нулю. При завершении сессии автоматически отзываются дескрипторы ресурса, связанные с этой сессией. (Отзыв не закрывает дескрипторы ресурса, поэтому отозванные дескрипторы нужно закрыть.)

Чтобы дерегистрировать объект, нужно вызвать функцию KosSessionUnregisterObject().

Удаление типа сессий

Тип сессий нужно удалить, если отсутствуют зарегистрированные объекты, для которых можно использовать сессии этого типа, и больше регистраций не будет. Например, тип сессий требуется удалить при завершении работы поставщика ресурсов.

Чтобы удалить тип сессий, нужно вызвать функцию KosSessionDestroyType().

Сведения о функциях API

Функции session.h