Динамическое создание IPC-каналов с использованием системной программы DCM

В составе KasperskyOS SDK поставляется системная программа DCM (Dynamic Connection Manager), которая позволяет динамически создавать IPC-каналы. Благодаря этой программе серверы могут сообщать клиентам о предоставляемых службах, а также передавать callable-дескрипторы для использования этих служб.

Для использования программы DCM в составе KasperskyOS SDK поставляются следующие файлы:

• sysroot-*-kos/include/dcm/dcm_api.h – заголовочный файл, в котором определен базовый API.
• sysroot-*-kos/include/dcm/groups/pub.h – заголовочный файл, в котором определен дополнительный API для серверов.
• sysroot-*-kos/include/dcm/groups/subscr.h – заголовочный файл, в котором определен дополнительный API для клиентов.
• sysroot-*-kos/include/dcm/dcm.h – заголовочный файл для включения в исходный код клиентов и серверов.
• sysroot-*-kos/bin/dcm – исполняемый файл.
• sysroot-*-kos/lib/libdcm.a – клиентская библиотека.
• sysroot-*-kos/lib/libdcm_s.a – клиентская библиотека, собранная с флагом -fPIC для обеспечения возможности компоновки с динамической библиотекой.
• sysroot-*-kos/include/kl/core/DCM.*dl – файлы формальной спецификации.

IPC-каналы от клиентов и серверов к DCM нужно создать статически.

Можно запустить несколько процессов программы DCM. При этом каждый клиент и сервер может быть соединен только с одним процессом программы DCM.

В API программы DCM используются идентификаторы, которые называются DCM-дескрипторами (англ. DCM handles). DCM-дескрипторы идентифицируют объекты, которые дают клиентам и серверам, использующим DCM, следующие возможности:

• Клиенты могут получать уведомления о публикации и отмене публикации служб, а также выполнять запросы на создание IPC-каналов с серверами.
• Серверы могут получать запросы клиентов на создание IPC-каналов, а также принимать или отклонять эти запросы.

Имена служб и интерфейсов служб нужно задавать в соответствии с формальными спецификациями компонентов решения. (О квалифицированном имени службы см. "Привязка методов моделей безопасности к событиям безопасности".) Вместо квалифицированного имени службы можно использовать какое-либо условное название этой службы. Имена клиентов и серверов задаются в init-описании.

Использование базового API (dcm_api.h)

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

Динамическое создание IPC-канала на стороне сервера

Динамическое создание IPC-канала на стороне сервера включает следующие шаги:

1. Создать подключение к DCM вызовом функции DcmInit().
2. Опубликовать предоставляемые службы в DCM, используя функцию DcmPublishEndpoint().

   В параметре serverHandle функции DcmPublishEndpoint() нужно указать дескриптор, идентифицирующий сервер. В качестве дескриптора, идентифицирующего сервер, можно использовать дескриптор этого серверного процесса, полученный последовательностью вызовов функций KosTaskGetSelf() и KosTaskGetHandle() из API task.h, или дескриптор, созданный вызовом функции KnHandleCreateUserObject() из API handle_api.h. (При вызове функции KnHandleCreateUserObject() в параметре rights должны быть указаны флаги OCAP_HANDLE_TRANSFER и OCAP_HANDLE_GET_SID.) Можно опубликовать несколько служб, указывая один и тот же или разные дескрипторы, идентифицирующие сервер. (Клиенты могут получить потомков этих дескрипторов через опциональный параметр outServerHandle функции DcmReadPubQueue().) После публикации служб дескриптор, идентифицирующий сервер, можно закрыть.

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

   Чтобы отменить публикацию службы, нужно вызовом функции DcmCloseHandle() закрыть DCM-дескриптор, созданный при ее публикации. Также публикация всех опубликованных служб сервера будет отменена, если сервер завершится.

3. Получить запрос клиента на создание IPC-канала вызовом функции DcmListen().

   Вызовы функции DcmListen() с одним и тем же DCM-дескриптором в параметре pubHandle позволяют получить только те запросы клиентов, которые направлены на создание IPC-каналов для использования той службы с тем интерфейсом, которые были заданы при создании этого DCM-дескриптора на шаге 2.

   Через опциональные параметры outClientHandle и outClientName функции DcmListen() можно получить дескриптор, идентифицирующий клиента, и имя клиента соответственно. (Дескриптор, идентифицирующий клиента, является потомком дескриптора, указанного в параметре clientHandle функции DcmCreateConnection(), вызванной на стороне клиента.) Эти данные можно использовать, чтобы принять решение о принятии или отклонении запроса клиента. При этом дескриптор, идентифицирующий клиента, может быть использован, например, для получения сведений о клиенте от других процессов или для получения SID по этому дескриптору для сравнения с другими имеющимся у сервера дескрипторами, идентифицирующими клиентов. После принятия решения можно закрыть дескриптор, идентифицирующий клиента.

   В результате вызова функции DcmListen() создается DCM-дескриптор, позволяющий принять или отклонить запрос клиента на создание IPC-канала.

4. Принять запрос клиента на создание IPC-канала вызовом функции DcmAccept().

   В параметре connectionId функции DcmAccept() нужно указать DCM-дескриптор, полученный на шаге 3.

   В параметре sessionHandle функции DcmAccept() нужно указать callable-дескриптор для передачи клиенту. Чтобы создать callable-дескриптор, нужно вызвать функцию KnHandleCreateUserObjectEx() из API handle_api.h. (При вызове функции KnHandleCreateUserObjectEx() в параметре rights должны быть указаны флаги OCAP_IPC_CALL и OCAP_HANDLE_TRANSFER, а в параметрах ipcChannel и riid требуется указать серверный IPC-дескриптор создаваемого IPC-канала и идентификатор службы (RIID) соответственно. Серверный IPC-дескриптор используется для инициализации IPC-транспорта и управления обработкой IPC-запросов на стороне сервера. Для создания серверного дескриптора можно использовать функцию KnHandleCreateListener() из API handle_api.h. Идентификатор службы является константой в автоматически генерируемом транспортном коде, например, FsDriver_operationsComp_fileOperations_iid.) После принятия запроса клиента callable-дескриптор можно закрыть.

   Передачу callable-дескриптора клиенту можно ассоциировать с объектом контекста передачи ресурса, указав дескриптор этого объекта в параметре badgeHandle функции DcmAccept(). Это позволит, используя API notice_api.h, отследить, когда будут закрыты или отозваны потомки callable-дескриптора, которые образуют поддерево наследования дескрипторов, корневой узел которого порожден передачей клиенту этого callable-дескриптора. (Переданный callable-дескриптор может быть закрыт клиентом, но также закрытие этого дескриптора выполняется в результате завершения клиента.) Чтобы создать объект контекста передачи ресурса, нужно вызвать функцию KnHandleCreateBadge() из API handle_api.h.

   Через параметр context функций KnHandleCreateUserObjectEx() и KnHandleCreateBadge() можно задать данные для ассоциации с callable-дескриптором и передачей callable-дескриптора соответственно (аналогично контексту пользовательского ресурса и контексту передачи ресурса). Сервер сможет получить указатель на эти данные при разыменовании callable-дескриптора. (Несмотря на то что callable-дескриптор является IPC-дескриптором, он помещается ядром в поле base_.self фиксированной части IPC-запроса.)

   Один и тот же callable-дескриптор можно использовать, чтобы принять несколько запросов одного или нескольких клиентов.

   Чтобы отклонить запрос клиента на создание IPC-канала, нужно вызовом функции DcmCloseHandle() закрыть DCM-дескриптор, полученный на шаге 3. (При этом вызов функции DcmConnect() на стороне клиента завершится с ошибкой rcNotConnected.) В случае принятия запроса клиента DCM-дескриптор, полученный на шаге 3, нужно также закрыть, но после вызова функции DcmAccept().

Динамическое создание IPC-канала на стороне клиента

Динамическое создание IPC-канала на стороне клиента включает следующие шаги:

1. Создать подключение к DCM вызовом функции DcmInit().
2. Создать DCM-дескриптор, позволяющий получать уведомления о публикации и отмене публикации служб с заданным интерфейсом.

   Чтобы выполнить этот шаг, нужно вызвать функцию DcmSetSubscription().

   Опциональные параметры endpointName, serverName и serverHandle функции DcmSetSubscription() нужно использовать, чтобы включить фильтрацию уведомлений по квалифицированному имени службы, имени сервера и дескриптору, идентифицирующему сервер, соответственно. (Дескриптор, идентифицирующий сервер, является потомком дескриптора, указанного в параметре serverHandle функции DcmPublishEndpoint(), вызванной на стороне сервера. Клиент может получить этот дескриптор, например, от другого процесса.)

   В результате вызова функции DcmSetSubscription() создается DCM-дескриптор, позволяющий получать уведомления о публикации и отмене публикации служб с заданным интерфейсом. При этом формируется очередь уведомлений о публикации служб, которые были опубликованы до вызова DcmSetSubscription() и соответствуют критериям фильтрации. Если больше не требуется получать уведомления о публикации и отмене публикации служб с заданным интерфейсом, то этот DCM-дескриптор нужно закрыть вызовом функции DcmCloseHandle().

3. Извлечь уведомление о публикации службы из очереди этих уведомлений вызовом функции DcmReadPubQueue().

   В параметре subscrHandle функции DcmReadPubQueue() нужно указать DCM-дескриптор, полученный на шаге 2.

   Через опциональные параметры outServerHandle, outServerName и outEndpointName функции DcmReadPubQueue() можно получить дескриптор, идентифицирующий сервер, имя сервера и квалифицированное имя службы соответственно. (Дескриптор, идентифицирующий сервер, является потомком дескриптора, указанного в параметре serverHandle функции DcmPublishEndpoint(), вызванной на стороне сервера.) Эти данные можно использовать, чтобы принять решение о выполнении запроса на создание IPC-канала с сервером. При этом дескриптор, идентифицирующий сервер, может быть использован, например, для получения сведений о сервере от других процессов или для получения SID по этому дескриптору для сравнения с другими имеющимися у клиента дескрипторами, идентифицирующими серверы.

   Значение, полученное через параметр outPubStatus функции DcmReadPubQueue(), отражает, что служба опубликована, или публикация службы отменена. Уведомление об отмене публикации службы появляется, если сервер отменил публикацию этой службы, а также при завершении сервера.

4. Создать DCM-дескриптор, позволяющий выполнить запрос на создание IPC-канала с сервером.

   Чтобы выполнить этот шаг, нужно вызвать функцию DcmCreateConnection().

   В параметре serverHandle функции DcmCreateConnection() нужно указать дескриптор, идентифицирующий сервер. Этот дескриптор может быть получен на шаге 3 через параметр outServerHandle функции DcmReadPubQueue() или другим способом (например, от другого процесса).

   В параметре clientHandle функции DcmCreateConnection() нужно указать дескриптор, идентифицирующий клиента. В качестве дескриптора, идентифицирующего клиента, можно использовать дескриптор этого клиентского процесса, полученный последовательностью вызовов функций KosTaskGetSelf() и KosTaskGetHandle() из API task.h, или дескриптор, созданный вызовом функции KnHandleCreateUserObject() из API handle_api.h. (При вызове функции KnHandleCreateUserObject() в параметре rights должны быть указаны флаги OCAP_HANDLE_TRANSFER и OCAP_HANDLE_GET_SID.) Можно создать несколько DCM-дескрипторов, позволяющих выполнить запрос на создание IPC-канала, указывая в параметре clientHandle функции DcmCreateConnection() один и тот же или разные дескрипторы, идентифицирующие клиента. (Серверы могут получить потомков этих дескрипторов через опциональный параметр outClientHandle функции DcmListen().) После создания DCM-дескриптора, позволяющего выполнить запрос на создание IPC-канала, дескриптор, идентифицирующий клиента, можно закрыть.

   В результате вызова функции DcmCreateConnection() создается DCM-дескриптор, позволяющий выполнить запрос на создание IPC-канала с сервером для использования заданной службы с заданным интерфейсом.

5. Выполнить запрос на создание IPC-канала с сервером вызовом функции DcmConnect().

   В параметре connectionId нужно указать DCM-дескриптор, полученный на шаге 4.

   В результате вызова функции DcmConnect() клиент получает через параметр outSessionHandle callable-дескриптор. Клиент использует этот дескриптор для инициализации IPC-транспорта. При этом в функции инициализации прокси-объекта клиент указывает значение INVALID_RIID в качестве идентификатор службы (RIID).

   После получения callable-дескриптора DCM-дескриптор, полученный на шаге 4, нужно закрыть вызовом функции DcmCloseHandle().

Прерывание блокирующих вызовов функций

Чтобы прервать блокирующий вызов функции DcmConnect(), DcmReadPubQueue() или DcmListen() из другого потока исполнения, нужно вызвать функцию DcmInterruptBlockingCall().

Использование уведомлений

Используя функции DcmSubscribeToEvents() и DcmUnsubscribeFromEvents() совместно с функциями из API notice_api.h, можно получать уведомления о том, что произошли следующие события: публикация или отмена публикации сервером службы в DCM (флаг DCM_PUBLICATION_CHANGED), получение сервером запроса от клиента на создание IPC-канала (флаг DCM_CLIENT_CONNECTED), прерывание блокирующего вызова функции DcmConnect(), DcmReadPubQueue() или DcmListen() (флаг DCM_BLOCKING_CALL_INTERRUPTED), прием или отклонение сервером запроса клиента на создание IPC-канала (флаг DCM_CLIENT_RELEASED_BY_SERVER). (Флаги маски событий и идентификатор записи вида "ресурс – маска событий" DCM_EVENT_ID определены в заголовочном файле sysroot-*-kos/include/dcm/dcm_api.h из состава KasperskyOS SDK.) Функции DcmSubscribeToEvents() и DcmUnsubscribeFromEvents() позволяют настроить приемник уведомлений, соответственно добавляя и удаляя отслеживаемые объекты, идентифицируемые DCM-дескрипторами.

Удаление динамически созданных IPC-каналов

Динамически созданный IPC-канал будет удален при закрытии callable-дескриптора и серверного IPC-дескриптора этого IPC-канала.

Удаление подключения к DCM

Если использовать DCM больше не требуется, нужно вызвать функцию DcmFini(), чтобы удалить подключение к DCM и тем самым освободить связанные с этим подключением ресурсы.

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

Функции dcm_api.h

Использование дополнительного API для серверов (pub.h)

API позволяет серверам публиковать группы служб. С позиции сервера группа служб представляет собой набор предоставляемых этим сервером служб, для которых можно получать клиентские запросы на создание IPC-каналов, используя один DCM-дескриптор. Сервер может опубликовать несколько групп служб. Множества служб из разных групп, опубликованных сервером, не должны пересекаться.

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

Чтобы опубликовать группу предоставляемых сервером служб в DCM, нужно вызвать функцию DcmPublishGroupEndpoints(). Через параметр endpoints функции DcmPublishGroupEndpoints() нужно задать квалифицированные имена и контексты группируемых служб, а также имена интерфейсов служб. (Массив структур, указатель на который задан через параметр endpoints, можно удалить после публикации.) Контекст службы представляет собой данные, которые используются сервером, чтобы при вызове функции DcmListenGroupPub() определить, какая именно служба из опубликованной группы требуется клиенту. В качестве контекста службы можно использовать числовой идентификатор либо указатель на какие-либо данные. В результате вызова функции DcmPublishGroupEndpoints() создается DCM-дескриптор, позволяющий получать запросы клиентов на создание IPC-каналов для использования служб из заданной группы с заданными интерфейсами.

Чтобы получить запрос клиента на создание IPC-канала для использования службы из опубликованной группы, нужно вызвать функцию DcmListenGroupPub(). В параметре pubHandle функции DcmListenGroupPub() нужно указать DCM-дескриптор, полученный вызовом функции DcmPublishGroupEndpoints(). Выходной параметр outContext функции DcmListenGroupPub() содержит указатель на контекст службы. В результате вызова функции DcmListenGroupPub() создается DCM-дескриптор, позволяющий принять или отклонить запрос клиента на создание IPC-канала для использования той службы группы, которой соответствует полученный контекст службы.

Чтобы отменить публикацию группы служб, нужно вызовом функции DcmCloseGroupPubHandle() закрыть DCM-дескриптор, созданный при ее публикации. Также публикация всех опубликованных групп служб сервера будет отменена, если сервер завершится.

Чтобы прервать блокирующий вызов функции DcmListenGroupPub() из другого потока исполнения, нужно вызвать функцию DcmInterruptGroupPubBlockingCall().

Используя функции DcmSubscribeToGroupPubEvent() и DcmUnsubscribeFromGroupPubEvent() совместно с функциями из API notice_api.h, можно получать уведомления о том, что произошли следующие события: получение сервером запроса от клиента на создание IPC-канала (флаг DCM_CLIENT_CONNECTED), прерывание блокирующего вызова функции DcmListenGroupPub() (флаг DCM_BLOCKING_CALL_INTERRUPTED). (Флаги маски событий и идентификатор записи вида "ресурс – маска событий" DCM_EVENT_ID определены в заголовочном файле sysroot-*-kos/include/dcm/dcm_api.h из состава KasperskyOS SDK.) Функции DcmSubscribeToGroupPubEvent() и DcmUnsubscribeFromGroupPubEvent() позволяют настроить приемник уведомлений, соответственно добавляя и удаляя отслеживаемые объекты, идентифицируемые DCM-дескрипторами.

Функции pub.h

Использование дополнительного API для клиентов (subscr.h)

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

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

Чтобы создать DCM-дескриптор, позволяющий получать уведомления о публикации и отмене публикации групп служб с заданными интерфейсами, нужно вызвать функцию DcmSetGroupSubscription(). Через параметр endpointTypes нужно задать имена интерфейсов группируемых служб. В параметре endpointsCount нужно указать число группируемых служб, равное числу интерфейсов, заданных через параметр endpointTypes. (Уведомления будут содержать сведения о том числе служб, которое равно числу интерфейсов, так как действует ограничение, что каждому интерфейсу соответствует отдельная и единственная служба.)

Чтобы извлечь уведомление о публикации или отмене публикации группы служб из очереди этих уведомлений, нужно вызвать функцию DcmReadGroupPubQueue(). В параметре subscrHandle функции DcmReadGroupPubQueue() нужно указать DCM-дескриптор, полученный вызовом функции DcmSetGroupSubscription(). В параметре maxCount функции DcmReadGroupPubQueue() нужно указать число элементов в массиве, заданном через параметр outEndpoints. Значение этого параметра должно быть не меньше числа служб в группе. Значение, полученное через параметр outPubStatus функции DcmReadGroupPubQueue(), отражает, что группа служб опубликована, или публикация группы служб отменена. Уведомление о публикации группы служб появляется в очереди только в том случае, если сервер публикует все службы группы (сразу или по отдельности). Если сервер публикует только часть требуемых клиенту служб, то уведомление о публикации группы служб не появляется. Если сервер завершается или отменяет публикацию хотя бы одной службы из опубликованной группы служб, то клиент получает уведомление об отмене публикации этой группы служб.

Если больше не требуется получать уведомления о публикации и отмене публикации группы служб с заданными интерфейсами, то DCM-дескриптор, созданный вызовом функции DcmSetGroupSubscription(), нужно закрыть вызовом функции DcmCloseGroupSubscrHandle().

Чтобы прервать блокирующий вызов функции DcmReadGroupPubQueue() из другого потока исполнения, нужно вызвать функцию DcmInterruptGroupSubscrBlockingCall().

Используя функции DcmSubscribeToGroupSubscrEvent() и DcmUnsubscribeFromGroupSubscrEvent() совместно с функциями из API notice_api.h, можно получать уведомления о том, что произошли следующие события: публикация или отмена публикации сервером службы в DCM (флаг DCM_PUBLICATION_CHANGED), прерывание блокирующего вызова функции DcmReadGroupPubQueue() (флаг DCM_BLOCKING_CALL_INTERRUPTED). (Флаги маски событий и идентификатор записи вида "ресурс – маска событий" DCM_EVENT_ID определены в заголовочном файле sysroot-*-kos/include/dcm/dcm_api.h из состава KasperskyOS SDK.) Функции DcmSubscribeToGroupSubscrEvent() и DcmUnsubscribeFromGroupSubscrEvent() позволяют настроить приемник уведомлений, соответственно добавляя и удаляя отслеживаемые объекты, идентифицируемые DCM-дескрипторами.

Функции subscr.h