[Topic whats_new]

Что нового

В KasperskyOS Community Edition 1.1.1 появились следующие возможности и доработки:

• Обновлены следующие сторонние библиотеки и приложения:
  • FFmpeg;
  • libxml2;
  • Eclipse Mosquitto;
  • opencv;
  • OpenSSL;
  • protobuf;
  • sqlite;
  • usb.
• Добавлена поддержка аппаратной платформы Raspberry Pi 4 Model B ревизии 1.5.

В KasperskyOS Community Edition 1.1 появились следующие возможности и доработки:

• Добавлена поддержка работы с шиной I2C в режиме ведущего устройства (master).
• Добавлена поддержка работы с шиной SPI в режиме ведущего устройства (master).
• Добавлена поддержка для USB HID устройств.
• Добавлена поддержка симметричной многопроцессорности (SMP).
• Расширены возможности для профилирования устройства: добавлена библиотека iperf и счетчики, отслеживающие системные параметры.
• Добавлена библиотека PCRE и пример работы с ней.
• Добавлена библиотека SPDLOG и пример работы с ней.
• Добавлен компонент MessageBus и пример работы с ним.
• Добавлены средства динамического анализа кода (ASAN, UBSAN).

В KasperskyOS Community Edition 1.0 появились следующие возможности и доработки:

• Добавлена поддержка аппаратной платформы Raspberry Pi 4 Model B.
• Добавлена поддержка SD-карты для аппаратной платформы Raspberry Pi 4 Model B.
• Добавлена поддержка Ethernet для аппаратной платформы Raspberry Pi 4 Model B.
• Добавлена поддержка портов ввода-вывода GPIO для аппаратной платформы Raspberry Pi 4 Model B.
• Добавлены сетевые сервисы DHCP, DNS, NTP и примеры работы с ними.
• Добавлена библиотека для работы с протоколом MQTT и примеры ее использования.

[Topic community_edition]

О KasperskyOS Community Edition

KasperskyOS Community Edition (CE) — общедоступная версия KasperskyOS, предназначенная для освоения основных принципов разработки приложений под KasperskyOS. KasperskyOS Community Edition позволит вам увидеть, как концепции, заложенные в KasperskyOS, работают на практике. KasperskyOS Community Edition включает в себя примеры приложений с исходным кодом, подробные пояснения, а также инструкции и инструменты для сборки приложений.

KasperskyOS Community Edition пригодится вам для:

• изучения принципов и приемов разработки "secure by design" на практических примерах;
• изучения KasperskyOS как возможной платформы для реализации своих проектов;
• прототипирования решений (прежде всего, Embedded/IoT) на основе KasperskyOS;
• портирования приложений/компонентов на KasperskyOS;
• изучения вопросов безопасности в разработке ПО.

KasperskyOS Community Edition позволяет разрабатывать приложения как на языке C, так и на C++. Подробнее о настройке среды разработки см. "Настройка среды разработки".

Для получения KasperskyOS Community Edition перейдите по ссылке.

Помимо этой документации, также рекомендуем изучить материалы раздела сайта KasperskyOS для разработчиков.

[Topic about_this_document]

Об этом документе

Руководство разработчика KasperskyOS Community Edition адресовано специалистам, которые осуществляют разработку безопасных решений на базе KasperskyOS.

Руководство предназначено специалистам, обладающим следующими навыками: знание языков C/C++, опыт разработки под POSIX-совместимые системы, знакомство с GNU Binary Utilities (далее также "binutils").

Вы можете применять информацию в этом руководстве для выполнения следующих задач:

• установка и удаление KasperskyOS Community Edition;
• использование KasperskyOS Community Edition.

[Topic sdk_contents]

Комплект поставки

KasperskyOS SDK представляет собой набор программных средств для создания решений на базе KasperskyOS.

В комплект поставки KasperskyOS Community Edition входят:

• deb-пакет для установки KasperskyOS Community Edition, содержащий:
  • образ ядра операционной системы KasperskyOS;
  • инструменты для разработки (компилятор GCC, компоновщик LD, отладчик GDB, набор утилит binutils, эмулятор QEMU и сопутствующие инструменты);
  • утилиты и скрипты (например, генераторы исходного кода, скрипт makekss для создания модуля безопасности Kaspersky Security Module, скрипт makeimg для создания образа решения);
  • набор библиотек, обеспечивающих частичную совместимость со стандартом POSIX;
  • драйверы;
  • системные программы (например, виртуальную файловую систему);
  • примеры работы с компонентами KasperskyOS Community Edition;
  • лицензионное соглашение;
  • файл с информацией о стороннем коде (Legal Notices).
• Руководство разработчика KasperskyOS Community Edition (онлайн-документация).
• Информация о версии (Release Notes);

KasperskyOS SDK устанавливается на компьютер под управлением ОС Debian GNU/Linux.

Следующие компоненты, входящие в комплект поставки KasperskyOS Community Edition, являются "Runtime компонентами" в соответствии с условиями лицензионного соглашения:

• Образ ядра операционной системы KasperskyOS.

Остальные части комплекта поставки не являются "Runtime компонентами". Условия и возможности использования каждого компонента могут быть дополнительно указаны в разделе "Информация о стороннем коде".

[Topic system_requirements]

Системные требования

Для установки KasperskyOS Community Edition и запуска примеров под QEMU необходимы:

1. Операционная система: Debian GNU/Linux 10 "Buster". Возможно использование Docker-контейнера.
2. Процессор: процессор с архитектурой x86-64 (для большей производительности требуется поддержка аппаратной виртуализации).
3. Оперативная память: для комфортной работы с инструментами сборки рекомендуется иметь не менее 4 ГБ оперативной памяти.
4. Дисковое пространство: не менее 3 ГБ свободного пространства в директории /opt (в зависимости от разрабатываемого решения).

Для запуска примеров на аппаратной платформе Raspberry Pi необходимы:

• модель Raspberry Pi 4 Model B (ревизии 1.1, 1.2, 1.4, 1.5) с объемом оперативной памяти равным 2, 4 или 8 Гб;
• microSD-карта объемом не менее 2 Гб;
• преобразователь USB-UART.

[Topic included_third_party_libs]

Включенные сторонние библиотеки и приложения

Для упрощения процесса разработки приложений в состав KasperskyOS Community Edition также включены следующие сторонние библиотеки и приложения:

• Automated Testing Framework (ATF) (v.0.20) – набор библиотек для написания тестов для программ на C, C++ и POSIX shell.

  Документация: https://github.com/jmmv/atf

• Boost (v.1.78.0) – собрание библиотек классов, использующих функциональность языка C++ и предоставляющих удобный кроссплатформенный высокоуровневый интерфейс для лаконичного кодирования различных повседневных подзадач программирования (работа с данными, алгоритмами, файлами, потоками и т. п.).

  Документация: https://www.boost.org/doc/

• Arm Mbed TLS (v.2.28.0) – реализация протоколов TLS и SSL, а также соответствующих криптографических алгоритмов и необходимого кода поддержки.

  Документация: https://github.com/Mbed-TLS/mbedtls

• Civetweb (v.1.11) – простой в использовании, мощный, встраиваемый веб-сервер на C / C ++ с дополнительной поддержкой CGI, SSL и Lua.

  Документация: http://civetweb.github.io/civetweb/UserManual.html

• FFmpeg (v.5.1) – набор библиотек с открытым исходным кодом, которые позволяют записывать, конвертировать и передавать цифровые аудио- и видеозаписи в различных форматах.

  Документация: https://ffmpeg.org/ffmpeg.html

• fmt (v.8.1.1) – библиотека для форматирования с открытым исходным кодом.

  Документация: https://fmt.dev/latest/index.html

• GoogleTest (v.1.10.0) – библиотека для тестирования кода на C++.

  Документация: https://google.github.io/googletest/

• iperf (v.3.10.1) – библиотека для тестирования производительности сети.

  Документация: https://software.es.net/iperf/

• libffi (v.3.2.1) – библиотека, предоставляющая C-интерфейс для вызова заранее скомпилированного кода.

  Документация: https://github.com/libffi/libffi

• libjpeg-turbo (v.2.0.91) – библиотека для работы с JPEG-изображениями.

  Документация: https://libjpeg-turbo.org/

• jsoncpp (v.1.9.4) – библиотека для работы с форматом JSON.

  Документация: https://github.com/open-source-parsers/jsoncpp

• libpng (v.1.6.38) – библиотека для работы с PNG-изображениями.

  Документация: http://www.libpng.org/pub/png/libpng.html

• libxml2 (v.2.9.14) – библиотека для работы с XML.

  Документация: http://xmlsoft.org/

• Eclipse Mosquitto (v.2.0.14) – брокер сообщений, реализующий протокол MQTT.

  Документация: https://mosquitto.org/documentation/

• nlohmann_json (v.3.9.1) – библиотека для работы с форматом JSON.

  Документация: https://github.com/nlohmann/json

• NTP (v.4.2.8P15) – библиотека для работы протоколом времени NTP.

  Документация: http://www.ntp.org/documentation.html

• opencv (v.4.6.0) – библиотека компьютерного зрения с открытым исходным кодом.

  Документация: https://docs.opencv.org/

• OpenSSL (v.1.1.1q) – полноценная криптографическая библиотека с открытым исходным кодом.

  Документация: https://www.openssl.org/docs/

• pcre (v.8.44) – библиотека для работы с регулярными выражениями.

  Документация: https://www.pcre.org/current/doc/html/

• protobuf (v.3.19.4) – библиотека для сериализации данных.

  Документация: https://developers.google.com/protocol-buffers/docs/overview

• spdlog (v.1.9.2) – библиотека для журналирования.

  Документация: https://github.com/gabime/spdlog

• sqlite (v.3.39.2) – библиотека для работы с базами данных.

  Документация: https://www.sqlite.org/docs.html

• Zlib (v.1.2.12) – библиотека для сжатия данных.

  Документация: https://zlib.net/manual.html

• usb (v.13.0.0) – библиотека для работы с USB-устройствами.

  Документация: https://github.com/freebsd/freebsd-src/tree/release/13.0.0/sys/dev/usb

• libevdev (v.1.6.0) – библиотека для работы с периферийными устройствами типа evdev.

  Документация: https://www.freedesktop.org/software/libevdev/doc/latest/

• Lwext4 (v.1.0.0) – библиотека для работы с файловыми системами ext2/3/4.

  Документация: https://github.com/gkostka/lwext4.git

Также см. Информация о стороннем коде.

[Topic limitations_and_known_problems]

Ограничения и известные проблемы

Поскольку KasperskyOS Community Edition предназначен для обучения, мы интегрировали в пакет ряд ограничений:

1. Не поддерживается динамическая загрузка библиотек.
2. Максимальное поддерживаемое количество запущенных программ: 32.
3. При завершении работы программы любым способом (например, return из основного потока исполнения) выделенные программой ресурсы не освобождаются, а сама программа переводится в "спящее" состояние. Программы не могут быть запущены повторно.
4. Не поддерживается запуск двух и более программ с одинаковым EDL-описанием.
5. Система останавливается, если не осталось работающих программ или если один из потоков программы-драйвера завершился (штатным или нештатным образом).

[Topic overview]

Обзор KasperskyOS

KasperskyOS – специализированная операционная система на основе микроядра разделения и монитора безопасности.

См. также:

• Что нового
• О KasperskyOS Community Edition
• Системные требования
• Начало работы

[Topic overview_general_inf]

Общие сведения

Микроядерность

KasperskyOS является микроядерной операционной системой. Ядро предоставляет минимальную функциональность, включая планирование исполнения программ, управление памятью и вводом-выводом. Код драйверов устройств, файловых систем, сетевых протоколов и другого системного ПО исполняется в пользовательском режиме (вне контекста ядра).

Процессы и службы

ПО, управляемое KasperskyOS, исполняется в виде процессов. Процесс – это запущенная на исполнение программа, которая имеет следующие особенности:

• может предоставлять службы другим процессам и/или использовать службы других процессов через механизм IPC;
• использует службы ядра через механизм IPC;
• ассоциируется с правилами безопасности, которые регулируют взаимодействия процесса с другими процессами и ядром.

Служба (англ. endpoint) – набор связанных по смыслу методов, доступных через механизм IPC (например, служба для приема и передачи данных по сети, служба для работы с прерываниями).

Реализация архитектурных подходов MILS и FLASK

Разрабатывая систему на базе KasperskyOS, ПО проектируют как набор компонентов (программ), взаимодействие между которыми регулируется механизмами безопасности. С точки зрения безопасности уровень доверия к каждому компоненту может быть высоким или низким, то есть ПО системы включает доверенные и недоверенные компоненты. Взаимодействиями компонентов между собой (и с ядром) управляет ядро (см. рис. ниже), уровень доверия к которому является высоким. Такой дизайн системы базируется на архитектурном подходе MILS (Multiple Independent Levels of Security), который применяется при разработке информационных систем ответственного применения.

Решение о разрешении или запрете конкретного взаимодействия принимает модуль безопасности Kaspersky Security Module. (Это решение называется решением модуля безопасности.) Модуль безопасности является модулем ядра, уровень доверия к которому является высоким, как и к самому ядру. Ядро выполняет решение модуля безопасности. Такое разделение функций по управлению взаимодействиями основано на архитектурном подходе FLASK (Flux Advanced Security Kernel), используемом в операционных системах для гибкого применения политик безопасности.

Взаимодействие процессов между собой и с ядром в KasperskyOS

Решение на базе KasperskyOS

Системное ПО (включая ядро KasperskyOS и модуль безопасности Kaspersky Security Module) и прикладное ПО, интегрированные для работы в составе программно-аппаратного комплекса, представляют собой решение на базе KasperskyOS (далее также решение). Программы, входящие в решение на базе KasperskyOS, являются компонентами решения на базе KasperskyOS (далее компонентами решения). Каждый экземпляр компонента решения исполняется в контексте отдельного процесса.

Политика безопасности решения на базе KasperskyOS

Разрешения и запреты взаимодействий процессов между собой и с ядром KasperskyOS задает политика безопасности решения на базе KasperskyOS (далее политика безопасности решения, политика). Политика безопасности решения сохраняется в модуле безопасности Kaspersky Security Module и используется этим модулем, когда он принимает решения о разрешении или запрете взаимодействий.

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

Технология Kaspersky Security System

Технология Kaspersky Security System позволяет реализовать разнообразные политики безопасности решений. При этом можно комбинировать несколько механизмов безопасности и гибко регулировать взаимодействия процессов между собой и с ядром KasperskyOS. Чтобы описать политику безопасности решения, используется специально разработанный язык PSL (Policy Specification Language). На основе описания политики безопасности решения создается модуль безопасности Kaspersky Security Module для использования в конкретном решении.

Генераторы исходного кода

Часть исходного кода решения на базе KasperskyOS создается генераторами исходного кода. Специальные программы генерируют исходный код на языке C из декларативных описаний. Генерируется исходный код модуля безопасности Kaspersky Security Module, инициализирующей программы (запускает остальные программы в решении и статически задает топологию взаимодействия между ними), а также методов и типов для осуществления IPC (транспортный код).

Транспортный код генерируется компилятором nk-gen-c из декларативных описаний на языках IDL (Interface Definition Language), CDL (Component Definition Language) и EDL (Entity Definition Language) соответственно (подробнее см. "Формальные спецификации компонентов решения на базе KasperskyOS").

Исходный код модуля безопасности Kaspersky Security Module генерируется компилятором nk-psl-gen-c из описания политики безопасности решения и IDL-, CDL-, EDL-описаний.

Исходный код инициализирующей программы генерируется утилитой einit из описания инициализации решения (в формате YAML) и IDL-, CDL-, EDL-описаний.

[Topic overview_architecture]

Архитектура KasperskyOS

Архитектура KasperskyOS представлена на рисунке ниже:

Архитектура KasperskyOS

В KasperskyOS приложения и драйверы взаимодействуют между собой и с ядром, используя библиотеку libkos, которая предоставляет интерфейсы для обращения к службам ядра. (Драйвер в KasperskyOS в общем случае работает на том же уровне привилегий, что и приложение.) Библиотека libkos обращается к ядру, выполняя только три системных вызова: Call(), Recv() и Reply(), которые реализуют механизм IPC. Службы ядра поддерживаются подсистемами ядра, назначение которых приведено в таблице ниже. Подсистемы ядра взаимодействуют с аппаратурой через уровень аппаратных абстракций (англ. Hardware Abstraction Layer, HAL), что упрощает портирование KasperskyOS на различные платформы.

Подсистемы ядра и их назначение

[Topic overview_ipc_intro]

IPC

[Topic overview_ipc_details]

Механизм IPC

Обмен IPC-сообщениями

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

Чтобы обмениваться IPC-сообщениями, клиент и сервер используют три системных вызова: Call(), Recv() и Reply() (см. рис. ниже):

1. Клиент направляет серверу IPC-запрос. Для этого один из потоков исполнения клиента выполняет системный вызов Call() и блокируется до получения IPC-ответа от сервера.
2. Серверный поток, выполнивший системный вызов Recv(), находится в ожидании IPC-запросов. При получении IPC-запроса этот поток разблокируется, обрабатывает запрос и отправляет IPC-ответ с помощью системного вызова Reply().
3. При получении IPC-ответа клиентский поток разблокируется и продолжает исполнение.

   

   Обмен IPC-сообщениями между клиентом и сервером

Вызов методов служб сервера

Отправка IPC-запросов серверу осуществляется, когда клиент вызывает методы служб (далее также интерфейсные методы) сервера (см. рис. ниже). IPC-запрос содержит входные параметры вызываемого метода, а также идентификатор службы RIID и идентификатор вызываемого метода MID. Получив запрос, сервер использует эти идентификаторы, чтобы найти реализацию метода. Сервер вызывает реализацию метода, передав в нее входные параметры из IPC-запроса. Обработав запрос, сервер отправляет клиенту IPC-ответ, содержащий выходные параметры метода.

Вызов метода службы сервера

IPC‑каналы

Чтобы два процесса могли обмениваться IPC-сообщениями, между ними должен быть установлен IPC-канал. IPC-канал имеет клиентскую и серверную стороны. Один процесс может использовать одновременно несколько IPC-каналов. При этом для одних IPC-каналов процесс может быть сервером, а для других IPC-каналов этот же процесс может быть клиентом.

В KasperskyOS предусмотрено два способа создания IPC-каналов:

1. Статический способ предполагает создание IPC-каналов при запуске решения. Статическое создание IPC-каналов выполняется инициализирующей программой.
2. Динамический способ позволяет уже запущенным процессам установить IPC-каналы между собой.

[Topic overview_ipc_control]

Управление IPC

Модуль безопасности Kaspersky Security Module интегрирован в механизм, реализующий IPC. Содержимое IPC-сообщений для всех возможных взаимодействий известно модулю безопасности, так как для генерации исходного кода этого модуля используются IDL-, CDL-, EDL-описания. Это позволяет модулю безопасности проверять взаимодействие процессов на соответствие политике безопасности решения.

Ядро KasperskyOS обращается к модулю безопасности каждый раз, когда один процесс отправляет IPC-сообщение другому процессу. При этом сценарий работы модуля безопасности включает следующие шаги:

1. Модуль безопасности проверяет, что IPC-сообщение соответствует вызываемому методу службы (проверяются размер IPC-сообщения, а также размер и размещение некоторых структурных элементов).
2. Если IPC-сообщение некорректно, модуль безопасности выносит решение "запрещено", и следующий шаг сценария не выполняется. Если IPC-сообщение корректно, выполняется следующий шаг сценария.
3. Модуль безопасности проверяет, что правила безопасности разрешают запрашиваемое действие. Если это так, модуль безопасности выносит решение "разрешено", в противном случае он выносит решение "запрещено".

Ядро выполняет решение модуля безопасности, то есть доставляет IPC-сообщение процессу-получателю либо отклоняет его доставку. В случае отклонения доставки IPC-сообщения процесс-отправитель получает код ошибки через код возврата системного вызова Call() или Reply().

Проверке подлежат как IPC-запросы, так и IPC-ответы. На рисунке ниже показана схема управляемого обмена IPC-сообщениями между клиентом и сервером.

Управляемый обмен IPC-сообщениями между клиентом и сервером

[Topic overview_ipc_transport]

Транспортный код для IPC

Чтобы реализовать взаимодействие процессов, необходим транспортный код, отвечающий за корректное создание IPC-сообщений, их упаковку, отправку и распаковку. Разработчику решения на базе KasperskyOS нет необходимости самостоятельно писать транспортный код. Вместо этого можно использовать специальные инструменты и библиотеки, поставляемые в составе KasperskyOS SDK.

Транспортный код для разрабатываемых компонентов решения

Разработчик компонента решения на базе KasperskyOS может сгенерировать транспортный код на основе IDL-, CDL-, EDL-описаний, относящихся к этому компоненту. Для этого в составе KasperskyOS SDK поставляется компилятор nk-gen-c. Компилятор nk-gen-c позволяет генерировать транспортные методы и типы для использования как клиентом, так и сервером.

Транспортный код для поставляемых компонентов решения

Большинство компонентов, поставляемых в составе KasperskyOS SDK, может быть использовано в решении как локально, то есть путем статической компоновки с другими компонентами, так и через IPC.

Чтобы использовать поставляемый компонент через IPC, в составе KasperskyOS SDK есть следующие транспортные библиотеки:

• клиентская библиотека компонента решения, которая преобразует локальные вызовы в IPC-запросы;
• серверная библиотека компонента решения, которая преобразует IPC-запросы в локальные вызовы.

Клиентская библиотека компонуется с кодом клиента (с кодом компонента, который будет использовать поставляемый компонент). Серверная библиотека компонуется с реализацией поставляемого компонента (см. рис. ниже).

Использование поставляемого компонента решения через IPC

[Topic overview_ipc_kernel]

IPC между процессом и ядром

Механизм IPC используется при взаимодействии процессов с ядром KasperskyOS, то есть процессы обмениваются с ядром IPC-сообщениями. Ядро предоставляет службы, а процессы используют их. Процессы обращаются к службам ядра, вызывая функции библиотеки libkos (непосредственно или через другие библиотеки). Клиентский транспортный код для взаимодействия процесса с ядром сосредоточен в этой библиотеке.

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

Модуль безопасности Kaspersky Security Module принимает решения о взаимодействии процессов с ядром так же, как и о взаимодействии процессов между собой. (В составе KasperskyOS SDK есть IDL-, CDL-, EDL-описания для ядра, которые используются для генерации исходного кода модуля безопасности.)

[Topic overview_resource_acces_control]

Управление доступом к ресурсам

Виды ресурсов

В KasperskyOS есть два вида ресурсов:

• Системные ресурсы, которыми управляет ядро. К ним относятся, например, процессы, регионы памяти, прерывания.
• Пользовательские ресурсы, которыми управляют процессы. Примеры пользовательских ресурсов: файлы, устройства ввода-вывода, накопители данных.

Дескрипторы

Как системные, так и пользовательские ресурсы идентифицируются дескрипторами (англ. handles). Процессы (и ядро KasperskyOS) могут передавать дескрипторы другим процессам. Получая дескриптор, процесс получает доступ к ресурсу, который этот дескриптор идентифицирует. То есть процесс, получивший дескриптор, может запрашивать операции над ресурсом, указывая в запросе полученный дескриптор. Один и тот же ресурс может идентифицироваться несколькими дескрипторами, которые используют разные процессы.

Идентификаторы безопасности (SID)

Для системных и пользовательских ресурсов ядро KasperskyOS назначает идентификаторы безопасности. Идентификатор безопасности (англ. Security Identifier, SID) – это глобальный уникальный идентификатор ресурса (то есть у ресурса есть только один SID, а дескрипторов может быть несколько). Модуль безопасности Kaspersky Security Module идентифицирует ресурсы по их SID.

Контекст безопасности

Технология Kaspersky Security System позволяет применять механизмы безопасности, которые принимают на вход значения SID. При применении таких механизмов модуль безопасности Kaspersky Security Module различает ресурсы (и ядро KasperskyOS) и связывает с ними контексты безопасности. Контекст безопасности представляет собой данные, ассоциированные с SID, которые используются модулем безопасности для принятия решений.

Содержимое контекста безопасности зависит от используемых механизмов безопасности. Контекст безопасности может содержать, например, состояние ресурса, уровни целостности субъектов и/или объектов доступа. Если контекст безопасности хранит состояние ресурса, это позволяет, например, разрешить выполнять операции над ресурсом, если только этот ресурс находится в каком-либо конкретном состоянии.

Модуль безопасности может изменить контекст безопасности, когда принимает решение. Например, могут измениться сведения о состоянии ресурса (модуль безопасности проверил по контексту безопасности, что файл находится в состоянии "не используется", разрешил открыть файл на запись и записал в контекст безопасности этого файла новое состояние "открыт на запись").

Управление доступом к ресурсам ядром KasperskyOS

Ядро KasperskyOS управляет доступом к ресурсам одновременно двумя взаимодополняющими способами: выполняя решения модуля безопасности Kaspersky Security Module и реализуя механизм безопасности на основе мандатных ссылок (англ. Object Capability, OCap).

Каждый дескриптор ассоциируется с правами доступа к идентифицируемому им ресурсу, то есть является мандатной ссылкой (англ. capability) в терминах OCap. Получая дескриптор, процесс получает права доступа к ресурсу, который этот дескриптор идентифицирует. Например, правами доступа могут быть: право на чтение, право на запись, право на передачу другому процессу возможности выполнять операции над ресурсом (право на передачу дескриптора).

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

В IPC-сообщении дескриптор передается вместе с маской прав. Маска прав дескриптора представляет собой значение, биты которого интерпретируются как права доступа к ресурсу, который этот дескриптор идентифицирует. Потребитель может узнать свои права доступа к системному ресурсу из маски прав дескриптора этого ресурса. Ядро использует маску прав дескриптора для проверки, что запрашиваемые потребителем операции над системным ресурсом разрешены.

Модуль безопасности может проверять маски прав дескрипторов и по результатам проверки разрешать или запрещать взаимодействия процессов между собой и с ядром, связанные с доступом к ресурсам.

Ядро запрещает расширение прав доступа при передачи дескрипторов между процессами (при передаче дескриптора права доступа могут быть только ограничены).

Управление доступом к ресурсам поставщиками ресурсов

Процессы, которые управляют пользовательскими ресурсами и доступом к этим ресурсам для других процессов, являются поставщиками ресурсов. (Поставщиками ресурсов являются, например, драйверы.) Поставщики управляют доступом к ресурсам двумя взаимодополняющими способами: выполняя решения модуля безопасности Kaspersky Security Module и используя механизм OCap, который предоставляется ядром KasperskyOS.

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

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

Потребитель может узнать свои права доступа к пользовательскому ресурсу из маски прав дескриптора этого ресурса. Поставщик использует маску прав дескриптора для проверки, что запрашиваемые потребителем операции над пользовательским ресурсом разрешены.

Структура маски прав дескриптора

Маска прав дескриптора имеет размер 32 бита и состоит из общей и специальной части. Общая часть описывает права, неспецифичные для любых ресурсов (флаги этих прав определены в заголовочном файле services/ocap.h). Например, в общей части находится флаг OCAP_HANDLE_TRANSFER, который определяет право на передачу дескриптора. Специальная часть описывает права, специфичные для пользовательского или системного ресурса. Флаги прав специальной части для системных ресурсов определены в заголовочном файле services/ocap.h. Структура специальной части для пользовательских ресурсов определяется поставщиком ресурсов с использованием макроса OCAP_HANDLE_SPEC(), который определен в заголовочном файле services/ocap.h. Поставщику ресурсов необходимо экспортировать публичные заголовочные файлы с описанием структуры специальной части.

При создании дескриптора системного ресурса маска прав задается ядром KasperskyOS, которое применяет маски прав из заголовочного файла services/ocap.h. Применяются маски прав с именами вида OCAP_*_FULL (например, OCAP_IOPORT_FULL, OCAP_TASK_FULL, OCAP_FILE_FULL) и вида OCAP_IPC_* (например, OCAP_IPC_SERVER, OCAP_IPC_LISTENER, OCAP_IPC_CLIENT).

При создании дескриптора пользовательского ресурса маска прав задается пользователем.

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

[Topic overview_solution_image]

Структура и запуск решения на базе KasperskyOS

Структура решения

Загружаемый в аппаратуру образ решения на базе KasperskyOS содержит следующие файлы:

• образ ядра KasperskyOS;
• файл с исполняемым кодом модуля безопасности Kaspersky Security Module;
• исполняемый файл инициализирующей программы;
• исполняемые файлы всех остальных компонентов решения (например, прикладных программ, драйверов);
• файлы, используемые программами (например, файлы с параметрами, шрифтами, графическими и звуковыми данными).

Для хранения файлов в образе решения используется файловая система ROMFS.

Запуск решения

Запуск решения на базе KasperskyOS происходит следующим образом:

1. Загрузчик запускает ядро KasperskyOS.
2. Ядро находит и загружает модуль безопасности (как модуль ядра).
3. Ядро запускает инициализирующую программу.
4. Инициализирующая программа запускает все остальные программы, входящие в решение.

[Topic getting_started]

Начало работы

Этот раздел содержит информацию, необходимую для начала работы с KasperskyOS Community Edition.

[Topic using_docker]

Использование Docker-контейнера

Для установки и использования KasperskyOS Community Edition можно использовать Docker-контейнер, в котором развернут образ одной из поддерживаемых операционных систем.

Чтобы использовать Docker-контейнер для установки KasperskyOS Community Edition:

1. Убедитесь что программное обеспечение Docker установлено и запущено.
2. Для загрузки официального Docker-образа операционной системы Debian Buster 10.12 из публичного репозитория Docker Hub выполните следующую команду:

   docker pull debian:10.12

3. Для запуска образа выполните следующую команду:

   docker run --net=host --user root --privileged -it --rm debian:10.12 bash

4. Скопируйте deb-пакет для установки KasperskyOS Community Edition в контейнер.
5. Установите KasperskyOS Community Edition.
6. Для корректной работы некоторых примеров необходимо:
   1. Добавить внутри контейнера директорию /usr/sbin в переменную окружения PATH, выполнив следующую команду:

      export PATH=/usr/sbin:$PATH

   2. Установить программу parted внутри контейнера. Для этого добавьте следующую строку в /etc/apt/sources.list:

      deb http://deb.debian.org/debian bullseye main

      После этого выполните следующую команду:

      sudo apt update && sudo apt install parted

[Topic sdk_install_and_remove]

Установка и удаление

Установка

KasperskyOS Community Edition поставляется в виде deb-пакета. Для установки KasperskyOS Community Edition мы рекомендуем использовать установщик пакетов apt.

Для развертывания пакета с помощью apt запустите с root-правами команду:

Пакет будет установлен в директорию /opt/KasperskyOS-Community-Edition-<version>.

Для удобства работы вы можете добавить путь к бинарным файлам инструментов KasperskyOS Community Edition в переменную PATH, это позволит работать с утилитами через терминал из любой директории:

Удаление

Для удаления KasperskyOS Community Edition выполните с root-правами команду:

При этом будут удалены все установленные файлы в директории /opt/KasperskyOS-Community-Edition-<version>.

[Topic ide_settings]

Настройка среды разработки

В этом разделе содержится краткое руководство по настройке среды разработки и добавлению заголовочных файлов, поставляемых в KasperskyOS Community Edition, в проект разработки.

Настройка редактора кода

Для упрощения процесса разработки решений на базе KasperskyOS перед началом работы рекомендуется:

• Установить в редакторе кода расширения и плагины для используемых языков программирования (C и/или C++).
• Добавить заголовочные файлы, поставляемые в KasperskyOS Community Edition, в проект разработки.

  Заголовочные файлы расположены в следующей директории: /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include.

Пример настройки Visual Studio Code

Например, работа с исходным кодом при разработке под KasperskyOS может проводиться в Visual Studio Code.

Для более удобной навигации по коду проекта, включая системный API, необходимо выполнить следующие действия:

1. Создайте новую рабочую область (workspace) или откройте существующую рабочую область в Visual Studio Code.

   Рабочая область может быть открыта неявно, с помощью пунктов меню File > Open folder.

2. Убедитесь, что расширение C/C++ for Visual Studio Code установлено.
3. В меню View выберите пункт Command Palette.
4. Выберите пункт C/C++: Edit Configurations (UI).
5. В поле Include path добавьте путь /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include.
6. Закройте окно C/C++ Configurations.

[Topic building_and_running_sample_programs]

Сборка и запуск примеров

[Topic building_sample_programs]

Сборка примеров

Сборка примеров осуществляется с помощью системы сборки CMake, входящей в состав KasperskyOS Community Edition.

Код примеров и скрипты для сборки находятся по следующему пути:

/opt/KasperskyOS-Community-Edition-<version>/examples

Сборка примеров для запуска на QEMU

Чтобы выполнить сборку примера, перейдите в директорию с примером и выполните команду:

В результате работы скрипта cross-build.sh создается образ решения на базе KasperskyOS, который включает пример. Файл образа решения kos-qemu-image сохраняется в директории <название примера>/build/einit.

Сборка примеров для запуска на Raspberry Pi 4 B

Чтобы выполнить сборку примера:

1. Перейдите в директорию с примером.
2. Откройте файл скрипта cross-build.sh в текстовом редакторе.
3. В последней строке скрипта замените команду make sim на команду make kos-image.
4. Сохраните файл скрипта, а затем выполните команду:

   $ ./cross-build.sh

В результате работы скрипта cross-build.sh создается образ решения на базе KasperskyOS, который включает пример. Файл образа решения kos-image сохраняется в директории <название примера>/build/einit.

[Topic running_sample_programs_qemu]

Запуск примеров на QEMU

Запуск примеров на QEMU в Linux с графической оболочкой

Запуск примера на QEMU в Linux с графической оболочкой осуществляется скриптом cross-build.sh, который также выполняет сборку примера. Чтобы запустить скрипт, перейдите в директорию с примером и выполните команду:

Запуск некоторых примеров требует использования дополнительных параметров QEMU. Команды для запуска таких примеров приведены в описаниях этих примеров.

Запуск примеров на QEMU в Linux без графической оболочки

Чтобы запустить пример на QEMU в Linux без графической оболочки, перейдите в директорию с примером, соберите пример и выполните следующие команды:

[Topic preparing_sd_card_rpi]

Подготовка Raspberry Pi 4 B к запуску примеров

Коммутация компьютера и Raspberry Pi 4 B

Чтобы видеть вывод примеров на компьютере, выполните следующие действия:

1. Соедините пины преобразователя USB-UART на базе FT232 с соответствующими GPIO-пинами Raspberry Pi 4 B (см. рис. ниже).

   

   Схема соединения преобразователя USB-UART и Raspberry Pi 4 B

2. Соедините USB-порт компьютера и преобразователь USB-UART.
3. Установите PuTTY или другую аналогичную программу для чтения данных из COM-порта. Настройте параметры следующим образом: bps = 115200, data bits = 8, stop bits = 1, parity = none, flow control = none.

Чтобы компьютер и Raspberry Pi 4 B могли взаимодействовать через сеть Ethernet, выполните следующие действия:

1. Соедините сетевые карты компьютера и Raspberry Pi 4 B с коммутатором или друг с другом.
2. Выполните настройку сетевой карты компьютера, чтобы ее IP-адрес был в одной подсети с IP-адресом сетевой карты Raspberry Pi 4 B (параметры сетевой карты Raspberry Pi 4 B задаются в файле dhcpcd.conf, который находится по пути <название примера>/resources/...).

Подготовка загрузочной SD-карты для Raspberry Pi 4 B

Загрузочную SD-карту для Raspberry Pi 4 B можно подготовить автоматически и вручную.

Чтобы подготовить загрузочную SD-карту автоматически, подключите SD-карту к компьютеру и выполните следующие команды:

Чтобы подготовить загрузочную SD-карту вручную, выполните следующие действия:

1. Выполните сборку загрузчика U-Boot для платформы ARMv8, который будет автоматически запускать пример. Для этого выполните следующие команды:

   $ sudo apt install git build-essential libssl-dev bison flex unzip parted gcc-aarch64-linux-gnu xz-utils device-tree-compiler

   $ git clone https://github.com/u-boot/u-boot.git u-boot-armv8

   # Только для Raspberry Pi 4 B ревизий 1.1 и 1.2

   $ cd u-boot-armv8 && git checkout tags/v2020.10

   # Только для Raspberry Pi 4 B ревизий 1.4 и 1.5

   $ cd u-boot-armv8 && git checkout tags/v2022.01

   # Для всех ревизий Raspberry Pi

   $ make ARCH=arm CROSS_COMPILE=aarch64-linux-gnu- rpi_4_defconfig

   # В меню, которое появится при выполнении следующей команды, в разделе

   # Boot options замените значение в поле bootcmd value на следующее:

   # fatload mmc 0 ${loadaddr} kos-image; bootelf ${loadaddr},

   # а в поле preboot default value удалите значение "usb start;".

   # Выйдите из меню, сохранив параметры.

   $ make ARCH=arm CROSS_COMPILE=aarch64-linux-gnu- menuconfig

   $ make ARCH=arm CROSS_COMPILE=aarch64-linux-gnu- u-boot.bin

2. Подготовьте образ с файловой системой для SD-карты. Для этого подключите SD-карту к компьютеру и выполните следующие команды:

   # Только для Raspberry Pi 4 B ревизий 1.1 и 1.2

   $ wget https://downloads.raspberrypi.org/raspbian_lite/images/raspbian_lite-2020-02-14/2020-02-13-raspbian-buster-lite.zip

   $ unzip 2020-02-13-raspbian-buster-lite.zip

   $ loop_device=$(sudo losetup --find --show --partscan 2020-02-13-raspbian-buster-lite.img)

   # Только для Raspberry Pi 4 B ревизии 1.4

   $ wget https://downloads.raspberrypi.org/raspios_lite_arm64/images/raspios_lite_arm64-2022-04-07/2022-04-04-raspios-bullseye-arm64-lite.img.xz

   $ unxz 2022-04-04-raspios-bullseye-arm64-lite.img.xz

   $ loop_device=$(sudo losetup --find --show --partscan 2022-04-04-raspios-bullseye-arm64-lite.img)

   # Только для Raspberry Pi 4 B ревизии 1.5

   $ wget https://downloads.raspberrypi.org/raspios_lite_arm64/images/raspios_lite_arm64-2022-09-07/2022-09-06-raspios-bullseye-arm64-lite.img.xz

   $ unxz 2022-09-06-raspios-bullseye-arm64-lite.img.xz

   $ loop_device=$(sudo losetup --find --show --partscan 2022-09-06-raspios-bullseye-arm64-lite.img)

   # Для всех ревизий Raspberry Pi

   # Образ будет содержать boot-раздел на 1 ГБ в fat32 и три раздела по 256 МБ в ext2, ext3 и ext4 соответственно.

   $ sudo parted ${loop_device} rm 2

   $ sudo parted ${loop_device} resizepart 1 1G

   $ sudo parted ${loop_device} mkpart primary ext2 1000 1256M

   $ sudo parted ${loop_device} mkpart primary ext3 1256 1512M

   $ sudo parted ${loop_device} mkpart primary ext4 1512 1768M

   $ sudo mkfs.ext2 ${loop_device}p2

   $ sudo mkfs.ext3 ${loop_device}p3

   $ sudo mkfs.ext4 -O ^64bit,^extent ${loop_device}p4

   $ sudo losetup -d ${loop_device}

   # В следующей команде [X] – последний символ в имени блочного устройства

   # для SD-карты.

   $ sudo dd bs=64k if=$(ls *rasp*lite.img) of=/dev/sd[X] conv=fsync

3. Скопируйте загрузчик U-Boot на SD-карту, выполнив следующие команды:

   # В следующих командах путь ~/mnt/fat32 используется для примера. Вы

   # можете использовать другой путь.

   $ mkdir -p ~/mnt/fat32

   # В следующей команде [X] – последний буквенный символ в имени блочного

   # устройства для раздела на отформатированной SD-карте.

   $ sudo mount /dev/sd[X]1 ~/mnt/fat32/

   $ sudo cp u-boot.bin ~/mnt/fat32/u-boot.bin

   # Только для Raspberry Pi 4 B ревизии 1.5

   # В следующих командах путь ~/tmp_dir используется для примера. Вы

   # можете использовать другой путь.

   $ mkdir -p ~/tmp_dir

   $ cp ~/mnt/fat32/bcm2711-rpi-4-b.dtb ~/tmp_dir

   $ dtc -I dtb -O dts -o ~/tmp_dir/bcm2711-rpi-4-b.dts ~/tmp_dir/bcm2711-rpi-4-b.dtb && \

   $ sed -i -e "0,/emmc2bus = /s/emmc2bus =.*//" ~/tmp_dir/bcm2711-rpi-4-b.dts && \

   $ sed -i -e "s/dma-ranges = <0x00 0xc0000000 0x00 0x00 0x40000000>;/dma-ranges = <0x00 0x00 0x00 0x00 0xfc000000>;/" ~/tmp_dir/bcm2711-rpi-4-b.dts && \

   $ sed -i -e "s/mmc@7e340000 {/mmc@7e340000 {\n\t\t\tranges = <0x00 0x7e000000 0x00 0xfe000000 0x1800000>;\n dma-ranges = <0x00 0x00 0x00 0x00 0xfc000000>;/" ~/tmp_dir/bcm2711-rpi-4-b.dts && \

   $ dtc -I dts -O dtb -o ~/tmp_dir/bcm2711-rpi-4-b.dtb ~/tmp_dir/bcm2711-rpi-4-b.dts

   $ sudo cp ~/tmp_dir/bcm2711-rpi-4-b.dtb ~/mnt/fat32/bcm2711-rpi-4-b.dtb

   $ sudo rm -rf ~/tmp_dir

4. Заполните конфигурационный файл для загрузчика U-Boot на SD-карте используя следующие команды:

   $ echo "[all]" > ~/mnt/fat32/config.txt

   $ echo "arm_64bit=1" >> ~/mnt/fat32/config.txt

   $ echo "enable_uart=1" >> ~/mnt/fat32/config.txt

   $ echo "kernel=u-boot.bin" >> ~/mnt/fat32/config.txt

   $ echo "dtparam=i2c_arm=on" >> ~/mnt/fat32/config.txt

   $ echo "dtparam=i2c=on" >> ~/mnt/fat32/config.txt

   $ echo "dtparam=spi=on" >> ~/mnt/fat32/config.txt

   $ sync

   $ sudo umount ~/mnt/fat32

[Topic running_sample_programs_rpi]

Запуск примеров на Raspberry Pi 4 B

Чтобы запустить пример на Raspberry Pi 4 B, выполните следующие действия:

1. Перейдите в директорию с примером и соберите пример.
2. Убедитесь, что Raspberry Pi 4 B и загрузочная SD-карта подготовлены к запуску примеров.
3. Скопируйте на загрузочную SD-карту образ решения на базе KasperskyOS. Для этого подключите загрузочную SD-карту к компьютеру и выполните следующие команды:

   # В следующей команде [X] – последний буквенный символ в имени блочного

   # устройства для раздела на загрузочной SD-карте.

   # В следующих командах путь ~/mnt/fat32 используется для примера. Вы

   # можете использовать другой путь.

   $ sudo mount /dev/sd[X]1 ~/mnt/fat32/

   $ sudo cp build/einit/kos-image ~/mnt/fat32/kos-image

   $ sync

   $ sudo umount ~/mnt/fat32

4. Подключите загрузочную SD-карту к Raspberry Pi 4 B.
5. Подайте питание на Raspberry Pi 4 B и дождитесь, пока запустится пример.

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

[Topic developing]

Разработка под KasperskyOS

[Topic sc_application_start]

Запуск процессов

[Topic einit_overview]

Обзор: Einit и init.yaml

Инициализирующая программа Einit

При старте ядро KasperskyOS находит в образе решения и запускает исполняемый файл с именем Einit (инициализирующая программа). Запущенный процесс имеет класс Einit и, как правило, используется для запуска остальных процессов, которые требуются в момент старта решения.

Генерация C-кода инициализирующей программы

В составе пакета инструментов KasperskyOS Community Edition поставляется утилита einit, которая позволяет сгенерировать C-код инициализирующей программы на основе init-описания (файл с описанием обычно имеет имя init.yaml). Полученная программа использует KasperskyOS API для выполнения следующих действий:

• статическое создание и запуск процессов;
• статическое создание IPC-каналов.

Стандартным способом использования утилиты einit является интеграция ее вызова в один из шагов сборочного скрипта, в результате которого утилита einit на основе файла init.yaml сгенерирует файл einit.c, содержащий код инициализирующей программы. На одном из следующих шагов сборочного скрипта необходимо скомпилировать файл einit.c в исполняемый файл Einit и включить в образ решения.

Синтаксис init.yaml

Init-описание содержит данные в формате YAML, которые идентифицируют:

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

Эти данные представляют собой словарь с ключом entities, содержащий список словарей процессов. Ключи словаря процесса приведены в таблице ниже.

Ключи словаря процесса в init-описании

Ключи словаря IPC-канала процесса приведены в таблице ниже.

Ключи словаря IPC-канала в init-описании

[Topic using_einit]

Примеры init-описаний

Здесь собраны init-описания, демонстрирующие различные аспекты запуска процессов.

Файл с init-описанием обычно называется init.yaml, хотя может иметь любое имя.

Соединение и запуск процесса-клиента и процесса-сервера

В следующем примере будут запущены два процесса: класса Client и класса Server. Имена процессов не указаны, поэтому они будут совпадать с именами классов процессов. Имена исполняемых файлов также не указаны, они также будут совпадать с именами классов. Процессы будут соединены IPC-каналом с именем server_connection.

init.yaml

Указание исполняемого файла для запуска

В следующем примере будут запущены: процесс класса Client из исполняемого файла cl, процесс класса ClientServer из исполняемого файла csr и процесс класса MainServer из исполняемого файла msr. Имена процессов не указаны, поэтому они будут совпадать с именами классов процессов.

init.yaml

Запуск двух процессов из одного исполняемого файла

В следующем примере будут запущены три процесса: процесс класса Client из исполняемого файла по умолчанию (Client), а также процессы классов MainServer и BkServer из исполняемого файла srv. Имена процессов не указаны, поэтому они будут совпадать с именами классов процессов.

init.yaml

Запуск двух процессов одного класса

В следующем примере будут запущены: один процесс класса Client (с именем по умолчанию – Client) и два процесса класса Server с именами UserServer и PrivilegedServer. Клиентский процесс связан с серверными процессами IPC-каналами с именами server_connection_us и server_connection_ps, соответственно. Имена исполняемых файлов не указаны, поэтому они будут совпадать с именами классов процессов.

init.yaml

Передача переменных окружения и аргументов функции main()

В следующем примере будут запущены два процесса: один класса VfsFirst (с именем по умолчанию – VfsFirst) и второй класса VfsSecond (с именем по умолчанию – VfsSecond). Первый процесс при запуске получит аргумент -f /etc/fstab, а также переменные окружения: ROOTFS со значением ramdisk0,0 / ext2 0 и UNMAP_ROMFS со значением 1. Второй процесс при запуске получит аргумент -l devfs /dev devfs 0.

Имена исполняемых файлов не указаны, поэтому они будут совпадать с именами классов процессов.

init.yaml

[Topic app_static_start]

Запуск процесса с помощью KasperskyOS API

Ниже приводится код функции GpMgrOpenSession(), выполняющей запуск серверного процесса, соединение его с клиентским процессом и инициализацию IPC-транспорта. Исполняемый файл нового процесса должен содержаться в ROMFS-хранилище решения.

[Topic env_overview]

Обзор: программа Env

Служебная программа Env предназначена для передачи аргументов и переменных окружения запускаемым процессам. При запуске каждый процесс автоматически отправляет запрос процессу Env и получает необходимые данные.

Чтобы использовать программу Env в своем решении, необходимо:

1. Разработать код программы Env, используя макросы из env/env.h.

2. Собрать бинарный файл программы Env, скомпоновав ее с библиотекой env_server.

3. В init-описании указать, что необходимо запустить процесс Env и соединить с ней выбранные процессы (Env при этом является сервером). Имя канала задается макросом ENV_SERVICE_NAME, объявленным в файле env/env.h.

4. Включить бинарный файл Env в образ решения.

Код программы Env

В коде программы Env используются следующие макросы и функции, объявленные в файле env/env.h:

• ENV_REGISTER_ARGS(name,argarr) – передать процессу с именем name аргументы из массива argarr (максимальный размер одного элемента – 256 байтов);
• ENV_REGISTER_VARS(name,envarr) – передать процессу с именем name переменные окружения из массива envarr (максимальный размер одного элемента – 256 байтов);
• ENV_REGISTER_PROGRAM_ENVIRONMENT(name,argarr,envarr) – передать процессу с именем name как аргументы, так и переменные окружения;
• envServerRun() – инициализировать серверную часть программы Env, чтобы она могла отвечать на запросы.

Примеры использования Env

[Topic using_env_app]

Передача переменных окружения и аргументов с помощью Env

Пример передачи аргументов при запуске процесса

Ниже приводится код программы Env, которая при запуске процесса с именем NetVfs передаст ему три аргумента: NetVfs, -l devfs /dev devfs 0 и -l romfs /etc romfs 0:

env.c

Пример передачи переменных окружения при запуске процесса

Ниже приводится код программы Env, которая при запуске процесса с именем Vfs3 передаст ему две переменных окружения: ROOTFS=ramdisk0,0 / ext2 0 и UNMAP_ROMFS=1:

env.c

[Topic sc_filesystems_and_net]

Файловые системы и сеть

[Topic vfs_overview]

Состав компонента VFS

Компонент VFS содержит набор исполняемых файлов, библиотек и файлов описаний, позволяющих использовать файловые системы и/или сетевой стек, вынесенные в отдельный процесс VFS (Virtual File System – виртуальная файловая система). При необходимости можно собрать собственные реализации VFS.

Библиотеки VFS

CMake-пакет vfs содержит следующие библиотеки:

• vfs_fs – содержит реализации defvs, ramfs и romfs, а также позволяет добавить в VFS реализации других файловых систем;
• vfs_net – содержит реализацию defvs и сетевого стека;
• vfs_imp – содержит в себе сумму компонентов vfs_fs и vfs_net;
• vfs_remote – клиентская транспортная библиотека; преобразует локальные вызовы в IPC-запросы к VFS и принимает IPC-ответы;
• vfs_server – серверная транспортная библиотека VFS; принимает IPC-запросы, преобразует их в локальные вызовы и отправляет IPC-ответы;
• vfs_local – используется для статической компоновки клиента с библиотеками VFS.

Исполняемые файлы VFS

CMake-пакет precompiled_vfs содержит следующие исполняемые файлы:

• VfsRamFs
• VfsSdCardFs
• VfsNet

Исполняемые файлы VfsRamFs и VfsSdCardFs включают в себя библиотеки vfs_server, vfs_fs, vfat и lwext4. Исполняемый файл VfsNet включает в себя библиотеки vfs_server, vfs_imp и dnet_imp.

Каждый из этих исполняемых файлов имеет собственные значения аргументов и переменных окружения по умолчанию.

При необходимости можно самостоятельно собрать исполняемый файл VFS с нужной функциональностью.

Файлы описаний VFS

В директории /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include/kl/ находятся следующие файлы VFS:

• VfsRamFs.edl, VfsSdCardFs.edl, VfsNet.edl и VfsEntity.edl и сгенерированные из них заголовочные файлы с транспортным кодом;
• Vfs.cdl и сгенерированный Vfs.cdl.h;
• Vfs*.idl и сгенерированные из них заголовочные файлы с транспортным кодом.

[Topic client_and_vfs_ipc_channel]

Создание IPC-канала до VFS

Рассмотрим программу Client, использующую файловые системы и сокеты Беркли. Для обработки ее вызовов запустим один процесс VFS (с именем VfsFsnet). В этот процесс будут направляться как "сетевые", так и "файловые" вызовы. Такой подход используется в тех случаях, когда не требуется разделение "файловых" и "сетевых" информационных потоков.

Чтобы взаимодействие процессов Client и VfsFsnet было корректным, имя IPC-канала между ними должно задаваться макросом _VFS_CONNECTION_ID, объявленным в файле vfs/defs.h.

Ниже приводится фрагмент init‑описания для соединения процессов Client и VfsFsnet.

init.yaml

[Topic vfs_app_build]

Сборка исполняемого файла VFS

При сборке исполняемого файла VFS можно включить в него именно ту функциональность, которая требуется, например:

• реализацию той или иной файловый системы;
• сетевой стек;
• сетевой драйвер.

Например, при разделении файловых и сетевых вызовов понадобится сборка "файловой версии" и "сетевой версии" VFS. В некоторых случаях в VFS потребуется включить и сетевой стек, и файловые системы ("полная версия" VFS).

Сборка "файловой версии" VFS

Рассмотрим программу VFS, содержащую только реализацию файловой системы lwext4 и не содержащую сетевого стека. Для сборки такого исполняемого файла необходимо файл с функцией main() скомпоновать с библиотеками vfs_server, vfs_fs и lwext4:

CMakeLists.txt

Взаимодействие трех процессов: клиента, "файловой версии" VFS и драйвера блочного устройства

Сборка "сетевой версии" VFS совместно с сетевым драйвером

Рассмотрим программу VFS, содержащую сетевой стек с драйвером и не содержащую реализаций файловых систем. Для сборки такого исполняемого файла необходимо файл с функцией main() скомпоновать с библиотеками vfs_server, vfs_implementation и dnet_implementation.

CMakeLists.txt

Взаимодействие процесса Client с процессом "сетевой версии" VFS

Сборка "сетевой версии" VFS с отдельным сетевым драйвером

Еще один вариант сборки "сетевой версии" VFS – без сетевого драйвера. Сам сетевой драйвер необходимо будет запустить как отдельный процесс. Взаимодействие с драйвером происходит через IPC с помощью библиотеки dnet_client.

Таким образом, необходимо файл с функцией main() скомпоновать с библиотеками vfs_server, vfs_implementation и dnet_client.

CMakeLists.txt

Взаимодействие трех процессов: клиента, "сетевой версии" VFS и сетевого драйвера

Сборка "полной версии" VFS

Если в VFS требуется включить как сетевой стек, так и реализации файловых систем, то при сборке следует использовать библиотеки vfs_server, vfs_implementation, dnet_implementation (или dnet_client – в случае отдельного сетевого драйвера), а также библиотеки реализации файловых систем.

[Topic client_and_vfs_linked]

Объединение клиента и VFS в один исполняемый файл

Рассмотрим программу Client, использующую сокеты Беркли. Вызовы, которые выполняет Client, должны направляться в VFS. Обычный путь состоит в запуске отдельного процесса VFS и создании IPC-канала. Однако вместо этого можно интегрировать функциональность VFS в сам исполняемый файл Client. Для этого нужно при сборке исполняемого файла Client скомпоновать его с библиотекой vfs_local, которая будет принимать вызовы, а также с библиотеками реализации – vfs_implementation и dnet_implementation.

Локальную компоновку с VFS удобно использовать при отладке. Кроме того, вызовы для работы с сетью могут обрабатываться намного быстрее за счет исключения IPC-вызовов. Тем не менее, изоляция VFS в отдельном процессе и IPC-взаимодействие с ним рекомендуется во всех случаях как более безопасный подход.

Ниже приведен сборочный скрипт исполняемого файла Client.

CMakeLists.txt

[Topic vfs_args_and_envs_overview]

Обзор: аргументы и переменные окружения VFS

Аргументы VFS

• -l <запись в формате fstab>

  Аргумент -l позволяет монтировать файловую систему.

• -f <путь к файлу fstab>

  Аргумент -f позволяет передать файл с записями в формате fstab для монтирования файловых систем. Файл будет искаться в ROMFS-хранилище. Если переменная UMNAP_ROMFS определена, то файл будет искаться на файловой системе, смонтированной с помощью переменной ROOTFS.

Пример использования аргументов -l и -f

Переменные окружения VFS

• UNMAP_ROMFS

  Если переменная UNMAP_ROMFS определена, то ROMFS-хранилище будет удалено. Это позволяет сэкономить память и изменить поведение при использовании аргумента -f.

• ROOTFS = <запись в формате fstab>

  Переменная ROOTFS позволяет монтировать файловую систему в корневой каталог. В комбинации с переменной UNMAP_ROMFS и аргументом -f позволяет искать fstab-файл на монтированной файловой системе, а не в ROMFS-хранилище. Пример использования ROOTFS

• VFS_CLIENT_MAX_THREADS

  Переменная окружения VFS_CLIENT_MAX_THREADS позволяет в момент запуска VFS переопределить параметр конфигурирования SDK VFS_CLIENT_MAX_THREADS.

• _VFS_NETWORK_BACKEND=<имя бэкенда>:<имя IPC-канала до VFS>

Переменная _VFS_NETWORK_BACKEND задает используемый для "сетевых" вызовов бэкенд. Можно указать имя стандартного бэкенда: client, server или local, а также имя пользовательского бэкенда. Если используется бэкенд local, то имя IPC-канала не указывается (_VFS_NETWORK_BACKEND=local:). Может быть указано два и больше IPC-канала через запятую.

• _VFS_FILESYSTEM_BACKEND=<имя бэкенда>:<имя IPC-канала до VFS>

  Переменная _VFS_FILESYSTEM_BACKEND задает используемый для "файловых" вызовов бэкенд. Имя бэкенда и имя IPC-канала до VFS задаются так же, как и для переменной _VFS_NETWORK_BACKEND.

Значения по умолчанию

Для исполняемого файла VfsRamFs:

Для исполняемого файла VfsSdCardFs:

Для исполняемого файла VfsNet:

[Topic mount_on_start]

Монтирование файловой системы при старте

При запуске процесса VFS по умолчанию монтируется только файловая система RAMFS, в корневую директорию. Если требуется монтировать другие файловые системы, это можно сделать не только с помощью вызова mount() после запуска VFS, но и непосредственно при запуске процесса VFS – передав ему нужные аргументы и переменные окружения.

Рассмотрим три примера монтирования файловых систем при запуске VFS. Для передачи аргументов и переменных окружения процессу VFS использована программа Env.

Монтирование с помощью аргумента -l

Простой способ монтировать файловую систему – это передать процессу VFS аргумент -l <запись в формате fstab>.

В этом примере при запуске процесса с именем Vfs1 будут монтированы файловые системы devfs и romfs.

env.c

Монтирование с помощью fstab из ROMFS

Если при сборке решения добавить fstab-файл, после старта он будет доступен через ROMFS-хранилище. Его можно использовать для монтирования, передав процессу VFS аргумент -f <путь к fstab-файлу>.

В этом примере при запуске процесса с именем Vfs2 будут монтированы файловые системы, заданные через файл fstab, который был добавлен при сборке решения.

env.c

Монтирование с помощью "внешнего" fstab

Пусть fstab-файл находится не в ROMFS-образе решения, а на диске. Чтобы использовать его для монтирования, необходимо передать VFS следующие аргументы и переменные окружения:

1. ROOTFS. Эта переменная позволяет монтировать в корневую директорию файловую систему, в которой находится fstab-файл.
2. UNMAP_ROMFS. Если эта переменная определена, ROMFS-хранилище удаляется. В итоге fstab-файл будет искаться на файловой системе, смонтированной с помощью переменной ROOTFS.
3. -f. Этот аргумент используется, чтобы задать путь к fstab-файлу.

В следующем примере при запуске процесса с именем Vfs3 в корневой каталог будет монтирована файловая система ext2, на которой будет найден файл /etc/fstab для монтирования дополнительных файловых систем. ROMFS-хранилище будет удалено.

env.c

[Topic client_and_two_vfs]

Разделение файловых и сетевых вызовов с помощью бэкендов VFS

Рассмотрим программу Client, использующую файловые системы и сокеты Беркли. Для обработки ее вызовов мы запустим не один, а два отдельных VFS-процесса из исполняемых файлов VfsFirst и VfsSecond. Через переменные окружения мы зададим файловые бэкенды как работающие через канал до VfsFirst, а сетевые бэкенды – как работающие через канал до VfsSecond. Будем использовать стандартные бэкенды client и server. Благодаря этому мы перенаправим "файловые вызовы" Client в VfsFirst, а "сетевые" – в VfsSecond. Чтобы передать процессам переменные окружения, добавим в решение программу Env.

Init-описание решения представлено ниже. Процесс Client будет соединен с процессами VfsFirst и VfsSecond, при этом каждый из трех процессов соединен с процессом Env. Обратите внимание, что имя IPC-канала до процесса Env задается с помощью переменной ENV_SERVICE_NAME.

init.yaml

Чтобы направить все "файловые" вызовы в VfsFirst, зададим значение переменной окружения _VFS_FILESYSTEM_BACKEND следующим образом:

• для VfsFirst: _VFS_FILESYSTEM_BACKEND=server:<имя IPC-канала до VfsFirst>;
• для Client: _VFS_FILESYSTEM_BACKEND=client:<имя IPC-канала до VfsFirst>.

Для направления "сетевых" вызовов в VfsSecond используем аналогичную переменную окружения _VFS_NETWORK_BACKEND:

• для VfsSecond зададим: _VFS_NETWORK_BACKEND=server:<имя IPC-канала до VfsSecond>;
• для Client: _VFS_NETWORK_BACKEND=client:<имя IPC-канала до VfsSecond>.

Значение переменных окружения зададим через программу Env, код которой представлен ниже.

env.c

[Topic vfs_backends]

Написание пользовательского бэкенда VFS

Рассмотрим решение, включающее процессы Client, VfsFirst и VfsSecond. Пусть процесс Client соединен с VfsFirst и VfsSecond с помощью IPC-каналов.

Задача: сделать так, чтобы обращения процесса Client к файловой системе fat32 обрабатывались процессом VfsFirst, а обращения к ext4 обрабатывались VfsSecond. Для решения этой задачи можно использовать механизм бэкендов VFS, причем даже не придется менять код программы Client.

Мы напишем пользовательский бэкенд custom_client, который будет отправлять вызовы по каналу VFS1 или VFS2, в зависимости от того, начинается ли путь к файлу с /mnt1. Для отправки вызовов custom_client будет использовать стандартные бэкенды client, то есть будет являться проксирующим бэкендом.

С помощью аргумента -l мы монтируем fat32 в директорию /mnt1 для процесса VfsFirst и ext4 в /mnt2 для процесса VfsSecond. (Предполагается, что VfsFirst содержит реализацию fat32, а VfsSecond – реализацию ext4.) С помощью переменной окружения _VFS_FILESYSTEM_BACKEND зададим используемые процессами бэкенды (custom_client и server) и IPC-каналы (VFS1 и VFS2).

Наконец, с помощью init-описания зададим имена IPC-каналов: VFS1 и VFS2.

Ниже мы рассмотрим подробнее:

1. Код бэкенда custom_client.
2. Компоновка программы Client и бэкенда custom_client.
3. Код программы Env.
4. Init-описание.

Написание бэкенда custom_client

Этот файл содержит реализацию проксирующего пользовательского бэкенда, передающего вызовы в один из двух стандартных бэкендов client. Логика выбора бэкенда зависит от используемого пути или от дескриптора файла и управляется дополнительными структурами данных.

backend.c

Компоновка программы Client и бэкенда custom_client

Написанный бэкенд скомпилируем в библиотеку:

CMakeLists.txt

Готовую библиотеку backend_client скомпонуем с программой Client:

CMakeLists.txt (фрагмент)

Написание программы Env

Чтобы передать процессам аргументы и переменные окружения, используем программу Env.

env.c

Изменение init.yaml

Для IPC-каналов, соединяющих процесс Client с процессами VfsFirst и VfsSecond, необходимо задать те же имена, которые мы указали в переменной окружения _VFS_FILESYSTEM_BACKEND: VFS1 и VFS2.

init.yaml

[Topic sc_using_ipc]

IPC и транспорт

[Topic sc_ipc_channels]

Создание IPC-каналов

[Topic ipc_channels_overview]

Обзор: создание IPC-каналов

Есть два способа создания IPC-каналов: статический и динамический.

Статическое создание IPC-каналов проще в реализации, поскольку для него можно использовать init-описание.

Динамическое создание IPC-каналов позволяет изменять топологию взаимодействия процессов "на лету". Это требуется, если неизвестно, какой именно сервер содержит службу, необходимую клиенту. Например, может быть неизвестно, на какой именно накопитель нужно будет записывать данные.

Статическое создание IPC-канала

Статический способ имеет следующие особенности:

• клиент и сервер находятся в остановленном состоянии в момент создания IPC-канала;
• создание инициируются родительским процессом, запускающим клиента и сервера (обычно это Einit);
• созданный IPC-канал невозможно удалить;
• чтобы получить IPC-дескриптор и идентификатор службы (riid) после создания IPC-канала, клиент и сервер должны использовать интерфейс локатора сервисов (coresrv/sl/sl_api.h).

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

Динамический способ имеет следующие особенности:

• клиент и сервер уже запущены в момент создания IPC-канала;
• создание инициируются совместно клиентом и сервером;
• созданный IPC-канал может быть удален;
• клиент и сервер получают IPC-дескриптор и идентификатор службы (riid) сразу после успешного создания IPC-канала.

[Topic ipc_channel_create_einit]

Создание IPC-каналов с помощью init.yaml

Здесь собраны init-описания, демонстрирующие особенности создания IPC-каналов. Примеры задания свойств и аргументов процессов через init-описания разбираются в отдельной статье.

Файл с init-описанием обычно называется init.yaml, хотя может иметь любое имя.

Соединение и запуск процесса-клиента и процесса-сервера

В следующем примере будут запущены два процесса: класса Client и класса Server. Имена процессов не указаны, поэтому они будут совпадать с именами классов процессов. Имена исполняемых файлов также не указаны, они также будут совпадать с именами классов. Процессы будут соединены IPC-каналом с именем server_connection.

init.yaml

[Topic ipc_channel_create_dynamic]

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

При динамическом создании IPC-канала используются функции:

• интерфейса сервера имен (Name Server);
• интерфейса менеджера соединений (Connection Manager).

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

1. Запускаются процессы: клиент, сервер и сервер имен.
2. Сервер подключается к серверу имен с помощью вызова NsCreate() и публикует имя сервера, имя интерфейса и имя службы с помощью вызова NsPublishService().
3. Клиент подключается к серверу имен с помощью вызова NsCreate() и выполняет поиск имени сервера и имени службы по имени интерфейса с помощью вызова NsEnumServices().
4. Клиент запрашивает доступ к службе с помощью вызова KnCmConnect(), передавая в качестве аргументов найденные имя сервера и имя службы.
5. Сервер вызывает функцию KnCmListen() для проверки наличия запросов на доступ к службе.
6. Сервер принимает запрос клиента на доступ к службе с помощью вызова KnCmAccept(), передавая в качестве аргументов имя клиента и имя службы, которые получены при вызове KnCmListen().

Сервер может снимать с публикации на сервере имен ранее опубликованные службы с помощью вызова NsUnPublishService().

Сервер может отклонять запросы доступа к службам с помощью вызова KnCmDrop().

[Topic sc_using_sdk_endpoints]

Использование служб из состава KasperskyOS Community Edition

[Topic using_sdk_endpoints_examples]

Добавление службы в решение

Чтобы программа Client могла использовать ту или иную функциональность через механизм IPC, необходимо:

1. Найти в составе KasperskyOS Community Edition исполняемый файл (условно назовем его Server), реализующий нужную функциональность. (Под функциональностью мы здесь понимаем одну или несколько служб, имеющих самостоятельные IPC-интерфейсы)
2. Подключить CMake-пакет, содержащий файл Server и его клиентскую библиотеку.
3. Добавить исполняемый файл Server в образ решения.
4. Изменить init-описание так, чтобы при старте решения программа Einit запускала новый серверный процесс из исполняемого файла Server и соединяла его IPC-каналом с процессом, запускаемым из файла Client.

   Необходимо указать корректное имя IPC-канала, чтобы транспортные библиотеки могли идентифицировать этот канал и найти его IPC-дескрипторы. Корректное имя IPC-канала, как правило, совпадает с именем класса серверного процесса. VFS при этом является исключением.

5. Изменить PSL-описание так, чтобы разрешить запуск серверного процесса и IPC-взаимодействие между клиентом и сервером.
6. Подключить в исходном коде программы Client заголовочный файл с методами сервера.
7. Скомпоновать программу Client с клиентской библиотекой.

Пример добавления GPIO-драйвера в решение

В составе KasperskyOS Community Edition есть файл gpio_hw, реализующий функциональность GPIO-драйвера.

Следующие команды подключают CMake‑пакет gpio:

.\CMakeLists.txt

Добавление исполняемого файла gpio_hw в образ решения производится с помощью переменной gpio_HW_ENTITY, имя которой можно найти в конфигурационном файле пакета – /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/lib/cmake/gpio/gpio-config.cmake:

einit\CMakeLists.txt

В init-описание нужно добавить следующие строки:

init.yaml.in

В PSL-описание нужно добавить следующие строки:

security.psl.in

В коде программы Client нужно подключить заголовочный файл, в котором объявлены методы GPIO-драйвера:

client.c

Наконец, нужно скомпоновать программу Client с клиентской библиотекой GPIO:

client\CMakeLists.txt

[Topic sc_using_new_endpoints]

Создание и использование собственных служб

[Topic ipc_message_structure_overview]

Обзор: структура IPC-сообщения

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

Корректное IPC-сообщение (как запрос, так и ответ) содержит фиксированную часть и арену.

Фиксированная часть сообщения

Фиксированная часть сообщения содержит аргументы фиксированного размера, а также RIID и MID.

Аргументы фиксированного размера – это аргументы любых IDL-типов, кроме типа sequence.

RIID и MID идентифицируют вызываемый интерфейс и метод:

• RIID (Runtime Implementation ID) является порядковым номером вызываемой службы процесса (начиная с нуля).
• MID (Method ID) является порядковым номером метода в содержащем его интерфейсе (начиная с нуля).

Тип фиксированной части сообщения генерируется компилятором NK на основе IDL-описания интерфейса. Для каждого метода интерфейса генерируется отдельная структура. Также генерируются типы union для хранения любого запроса к процессу, компоненту или интерфейсу. Подробнее см. Пример генерации транспортных методов и типов.

Арена

Арена представляет собой буфер для хранения аргументов переменного размера (IDL‑тип sequence).

Проверка структуры сообщения модулем безопасности

Перед тем как вызывать связанные с сообщением правила, подсистема Kaspersky Security Module проверяет отправляемое сообщение на корректность. Проверяются как запросы, так и ответы. Если сообщение имеет некорректную структуру, оно будет отклонено без вызова связанных с ним методов моделей безопасности.

Формирование структуры сообщения

В составе KasperskyOS Community Edition поставляются следующие инструменты, позволяющие упростить для разработчика создание и упаковку IPC-сообщения:

• Библиотека transport-kos для работы с транспортом NkKosTransport.
• Компилятор NK, позволяющий сгенерировать специальные методы и типы.

Формирование простейшего IPC-сообщения показано в примерах echo и ping (/opt/KasperskyOS-Community-Edition-<version>/examples/).

[Topic ipc_find_ipc_desc]

Нахождение IPC-дескриптора

Клиентский и серверный IPC-дескрипторы требуется находить, если для используемой службы нет готовых транспортных библиотек (например, вы написали собственную службу). Для самостоятельной работы с IPC-транспортом нужно предварительно инициализировать его с помощью метода NkKosTransport_Init(), передав в качестве второго аргумента IPC-дескриптор используемого канала.

Подробнее см. примеры echo и ping (/opt/KasperskyOS-Community-Edition-<version>/examples/),

Нахождение IPC-дескриптора при статическом создании канала

При статическом создании IPC-канала как клиент, так и сервер могут сразу после своего запуска узнать свои IPC-дескрипторы с помощью методов ServiceLocatorRegister() и ServiceLocatorConnect(), указав имя созданного IPC-канала.

Например, если IPC-канал имеет имя server_connection, то на клиентской стороне необходимо вызвать:

На серверной стороне необходимо вызвать:

Подробнее см. примеры echo и ping (/opt/KasperskyOS-Community-Edition-<version>/examples/), а так же заголовочный файл /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include/coresrv/sl/sl_api.h.

Нахождение IPC-дескриптора при динамическом создании канала

Как клиент, так и сервер получают свои IPC-дескрипторы сразу при успешном динамическом создании IPC-канала.

Клиентский IPC-дескриптор является одним из выходных (out) аргументов метода KnCmConnect(). Серверный IPC-дескриптор является выходным аргументом метода KnCmAccept(). Подробнее см. заголовочный файл /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include/coresrv/cm/cm_api.h.

[Topic ipc_find_riid]

Нахождение идентификатора службы (riid)

Идентификатор службы (riid) требуется находить на клиентской стороне, если для используемой службы нет готовых транспортных библиотек (например, вы написали собственную службу). Для вызова методов сервера необходимо на клиентской стороне предварительно вызвать метод инициализации прокси-объекта, передав в качестве третьего аргумента идентификатор службы. Например, для интерфейса Filesystem:

Подробнее см. примеры echo и ping (/opt/KasperskyOS-Community-Edition-<version>/examples/),

Нахождение идентификатора службы при статическом создании канала

При статическом создании IPC-канала клиент может узнать идентификатор нужной службы с помощью метода ServiceLocatorGetRiid(), указав дескриптор IPC-канала и полное квалифицированное имя службы. Например, если экземпляр компонента OpsComp содержит службу FS, то на клиентской стороне необходимо вызвать:

Подробнее см. примеры echo и ping (/opt/KasperskyOS-Community-Edition-<version>/examples/), а так же заголовочный файл /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include/coresrv/sl/sl_api.h.

Нахождение идентификатора службы при динамическом создании канала

Клиент получает идентификатор службы сразу при успешном динамическом создании IPC-канала. Клиентский IPC-дескриптор является одним из выходных (out) аргументов метода KnCmConnect(). Подробнее см. заголовочный файл /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include/coresrv/cm/cm_api.h.

[Topic transport_code_overview]

Пример генерации транспортных методов и типов

При сборке решения компилятор NK на основе EDL-, CDL- и IDL-описаний генерирует набор специальных методов и типов, упрощающих формирование, отправку, прием и обработку IPC-сообщений.

В качестве примера рассмотрим класс процессов Server, предоставляющий службу FS, которая содержит единственный метод Open():

Server.edl

Operations.cdl

Filesystem.idl

На основе этих описаний будут сгенерированы файлы Server.edl.h, Operations.cdl.h, и Filesystem.idl.h содержащие следующие методы и типы:

Методы и типы, общие для клиента и сервера

• Абстрактные интерфейсы, содержащие указатели на реализации входящих в них методов.

  В нашем примере будет сгенерирован один абстрактный интерфейс – Filesystem:

  typedef struct Filesystem {

  const struct Filesystem_ops *ops;

  } Filesystem;

  typedef nk_err_t

  Filesystem_Open_fn(struct Filesystem *, const

  struct Filesystem_Open_req *,

  const struct nk_arena *,

  struct Filesystem_Open_res *,

  struct nk_arena *);

  typedef struct Filesystem_ops {

  Filesystem_Open_fn *Open;

  } Filesystem_ops;

• Набор интерфейсных методов.

  При вызове интерфейсного метода в запросе автоматически проставляются соответствующие значения RIID и MID.

  В нашем примере будет сгенерирован единственный интерфейсный метод Filesystem_Open:

  nk_err_t Filesystem_Open(struct Filesystem *self,

  struct Filesystem_Open_req *req,

  const

  struct nk_arena *req_arena,

  struct Filesystem_Open_res *res,

  struct nk_arena *res_arena)

Методы и типы, используемые только на клиенте

• Типы прокси-объектов.

  Прокси-объект используется как аргумент интерфейсного метода. В нашем примере будет сгенерирован единственный тип прокси-объекта Filesystem_proxy:

  typedef struct Filesystem_proxy {

  struct Filesystem base;

  struct nk_transport *transport;

  nk_iid_t iid;

  } Filesystem_proxy;

• Функции для инициализации прокси-объектов.

  В нашем примере будет сгенерирована единственная инициализирующая функция Filesystem_proxy_init:

  void Filesystem_proxy_init(struct Filesystem_proxy *self,

  struct nk_transport *transport,

  nk_iid_t iid)

• Типы, определяющие структуру фиксированной части сообщения для каждого конкретного метода.

  В нашем примере будет сгенерировано два таких типа: Filesystem_Open_req (для запроса) и Filesystem_Open_res (для ответа).

  typedef struct __nk_packed Filesystem_Open_req {

  __nk_alignas(8)

  struct nk_message base_;

  __nk_alignas(4) nk_ptr_t name;

  } Filesystem_Open_req;

  typedef struct Filesystem_Open_res {

  union {

  struct {

  __nk_alignas(8)

  struct nk_message base_;

  __nk_alignas(4) nk_uint32_t h;

  };

  struct {

  __nk_alignas(8)

  struct nk_message base_;

  __nk_alignas(4) nk_uint32_t h;

  } res_;

  struct Filesystem_Open_err err_;

  };

  } Filesystem_Open_res;

Методы и типы, используемые только на сервере

• Тип, содержащий все службы компонента, а также инициализирующая функция. (Для каждого компонента сервера.)

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

  В нашем примере будет сгенерирована структура Operations_component и функция Operations_component_init:

  typedef struct Operations_component {

  struct Filesystem *FS;

  };

  void Operations_component_init(struct Operations_component *self,

  struct Filesystem *FS)

• Тип, содержащий все службы, предоставляемые сервером непосредственно; все экземпляры компонентов, входящие в сервер; а также инициализирующая функция.

  В нашем примере будет сгенерирована структура Server_entity и функция Server_entity_init:

  #define Server_entity Server_component

  typedef struct Server_component {

  struct : Operations_component *OpsComp;

  } Server_component;

  void Server_entity_init(struct Server_entity *self,

  struct Operations_component *OpsComp)

• Типы, определяющие структуру фиксированной части сообщения для любого метода конкретного интерфейса.

  В нашем примере будет сгенерировано два таких типа: Filesystem_req (для запроса) и Filesystem_res (для ответа).

  typedef union Filesystem_req {

  struct nk_message base_;

  struct Filesystem_Open_req Open;

  };

  typedef union Filesystem_res {

  struct nk_message base_;

  struct Filesystem_Open_res Open;

  };

• Типы, определяющие структуру фиксированной части сообщения для любого метода любой службы конкретного компонента.

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

  В нашем примере будет сгенерировано два таких типа: Operations_component_req (для запроса) и Operations_component_res (для ответа).

  typedef union Operations_component_req {

  struct nk_message base_;

  Filesystem_req FS;

  } Operations_component_req;

  typedef union Operations_component_res {

  struct nk_message base_;

  Filesystem_res FS;

  } Operations_component_res;

• Типы, определяющие структуру фиксированной части сообщения для любого метода любой службы конкретного компонента, экземпляр которого входит в сервер.

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

  В нашем примере будет сгенерировано два таких типа: Server_entity_req (для запроса) и Server_entity_res (для ответа).

  #define Server_entity_req Server_component_req

  typedef union Server_component_req {

  struct nk_message base_;

  Filesystem_req OpsComp_FS;

  } Server_component_req;

  #define Server_entity_res Server_component_res

  typedef union Server_component_res {

  struct nk_message base_;

  Filesystem_res OpsComp_FS;

  } Server_component_res;

• Dispatch-методы (диспетчеры) для отдельного интерфейса, компонента или класса процессов.

  Диспетчеры анализируют полученный запрос (значения RIID и MID), вызывают реализацию соответствующего метода, после чего сохраняют ответ в буфер. В нашем примере будут сгенерированы диспетчеры Filesystem_interface_dispatch, Operations_component_dispatch и Server_entity_dispatch.

  Диспетчер класса процессов обрабатывает запрос и вызывает методы, реализуемые этим классом. Если запрос содержит некорректный RIID (например, относящийся к другой службе, которой нет у этого класса процессов) или некорректный MID, диспетчер возвращает NK_EOK или NK_ENOENT.

  nk_err_t Server_entity_dispatch(struct Server_entity *self,

  const

  struct nk_message *req,

  const

  struct nk_arena *req_arena,

  struct nk_message *res,

  struct nk_arena *res_arena)

  В специальных случаях можно использовать диспетчеры интерфейса и компонента. Они принимают дополнительный аргумент – ID реализации интерфейса (nk_iid_t). Запрос будет обработан только если переданный аргумент и RIID из запроса совпадают, а MID корректен. В противном случае диспетчеры возвращают NK_EOK или NK_ENOENT.

  nk_err_t Operations_component_dispatch(struct Operations_component *self,

  nk_iid_t iidOffset,

  const

  struct nk_message *req,

  const

  struct nk_arena *req_arena,

  struct nk_message *res,

  struct nk_arena *res_arena)

  nk_err_t Filesystem_interface_dispatch(struct Filesystem *impl,

  nk_iid_t iid,

  const

  struct nk_message *req,

  const

  struct nk_arena *req_arena,

  struct nk_message *res,

  struct nk_arena *res_arena)

[Topic api]

KasperskyOS API

[Topic libkos]

Библиотека libkos

[Topic libkos_intro]

Общие сведения о библиотеке libkos

Ядро KasperskyOS имеет ряд служб для управления дескрипторами, потоками, памятью, процессами, IPC-каналами, ресурсами ввода-вывода и т.д. Для доступа к службам используется библиотека libkos.

Библиотека libkos

Библиотека libkos состоит из двух частей:

• Первая часть предоставляет собой C-интерфейс для доступа к службам ядра KasperskyOS. Она доступна через заголовочные файлы, находящиеся в директории coresrv.
• Вторая часть библиотеки libkos предоставляет абстракции примитивов синхронизации, объектов и очередей. Она также содержит функции-обертки для более простой аллокации памяти и работы с потоками. Заголовочные файлы второй части libkos находятся в директории kos.

Библиотека libkos значительно упрощает использование служб ядра. Функции библиотеки libkos обеспечивают корректную упаковку IPC-сообщения и выполнение системных вызовов. Взаимодействие других библиотек (включая libc) с ядром происходит через библиотеку libkos.

Для использования службы ядра KasperskyOS нужно подключить соответствующий этой службе заголовочный файл библиотеки libkos. Например, для доступа к методам менеджера ввода-вывода (IO Manager) нужно подключить файл io_api.h:

Файлы, используемые библиотекой libkos

Внутренняя реализация библиотеки libkos может использовать следующие файлы, экспортируемые ядром:

• Файлы на языке IDL (idl-описания). Содержат описания интерфейсов служб. Используются IPC-транспортом для корректной упаковки сообщений.
• Заголовочные файлы ядра. Эти файлы включаются библиотекой libkos.

Пример

Менеджер ввода-вывода (IO Manager) представлен для пользователя следующими файлами:

• coresrv/io/io_api.h – заголовочный файл библиотеки libkos;
• services/io/IO.idl – idl-описание менеджера ввода-вывода;
• io/io_dma.h, io/io_irq.h – заголовочные файлы ядра.

[Topic api_memory]

Память

[Topic api_memory_states]

Состояния памяти

Каждая страница виртуальной памяти может быть свободна (free), зарезервирована (reserved) или передана (committed).

Переход из свободного состояния в зарезервированное называется резервированием (аллокацией). Предварительное резервирование памяти (без передачи физических страниц) позволяет приложению заранее разметить свое адресное пространство. Обратный переход из зарезервированного в свободное состояние называется освобождением памяти.

Назначение физической памяти для ранее зарезервированной страницы виртуальной памяти называется передачей памяти, а обратный переход из переданного состояния в зарезервированное – возвращением памяти.

Переходы между состояниями страницы памяти

[Topic kn_vm_allocate]

KnVmAllocate()

Функция объявлена в файле coresrv/vmm/vmm_api.h.

Функция резервирует диапазон физических страниц, задаваемый параметрами addr и size. Если указан флаг VMM_FLAG_COMMIT, функция резервирует и передает страницы за один вызов.

Параметры:

• addr – странично-выровненный базовый физический адрес; если задать addr равным 0, система сама выберет свободный участок физической памяти;
• size – размер участка памяти в байтах (должен быть кратен размеру страницы);
• flags – флаги аллокации.

Функция возвращает базовый виртуальный адрес зарезервированного участка. Если зарезервировать участок памяти невозможно, функция возвращает RTL_NULL.

Флаги аллокации

В параметре flags можно использовать следующие флаги (vmm/flags.h):

• VMM_FLAG_RESERVE – обязательный флаг;
• VMM_FLAG_COMMIT – позволяет за один вызов KnVmAllocate() резервировать и передать страницы памяти в "ленивом" режиме;
• VMM_FLAG_LOCKED – используется совместно с VMM_FLAG_COMMIT; позволяет сразу передать физические страницы памяти вместо "ленивой" передачи;
• VMM_FLAG_WRITE_BACK, VMM_FLAG_WRITE_THROUGH, VMM_FLAG_WRITE_COMBINE, VMM_FLAG_CACHE_DISABLE и VMM_FLAG_CACHE_MASK – управляют кэшированием страниц памяти;
• VMM_FLAG_READ, VMM_FLAG_WRITE, VMM_FLAG_EXECUTE и VMM_FLAG_RWX_MASK – атрибуты защиты памяти;
• VMM_FLAG_LOW_GUARD и VMM_FLAG_HIGH_GUARD – добавление защитной страницы перед и после выделенной памяти соответственно;
• VMM_FLAG_GROW_DOWN – определение направления доступа к памяти (от старших адресов к младшим).

Допустимые комбинации атрибутов защиты памяти:

• VMM_FLAG_READ – разрешено чтение содержимого страницы;
• VMM_FLAG_READ | VMM_FLAG_WRITE – разрешено чтение и изменение содержимого страницы;
• VMM_FLAG_READ | VMM_FLAG_EXECUTE – разрешено чтение и выполнение содержимого страницы;
• VMM_FLAG_RWX_MASK или VMM_FLAG_READ | VMM_FLAG_WRITE | VMM_FLAG_EXECUTE – полный доступ к содержимому страницы (эти записи эквивалентны).

Пример

При необходимости можно изменить заданные атрибуты защиты участка памяти с помощью функции KnVmProtect().

[Topic kn_vm_commit]

KnVmCommit()

Функция объявлена в файле coresrv/vmm/vmm_api.h.

Функция передает диапазон физических страниц, задаваемый параметрами addr и size.

Все передаваемые страницы должны быть предварительно зарезервированы.

Параметры:

• addr – странично-выровненный базовый виртуальный адрес участка памяти;
• size – размер участка памяти в байтах (должен быть кратен размеру страницы);
• flags – параметр не используется (укажите флаг VMM_FLAG_LOCKED в значении параметра для обеспечения совместимости).

В случае успешной передачи страниц функция возвращает rcOk.

[Topic kn_vm_decommit]

KnVmDecommit()

Функция объявлена в файле coresrv/vmm/vmm_api.h.

Функция освобождает диапазон страниц (переводит их в зарезервированное состояние).

Параметры:

• addr – странично-выровненный базовый виртуальный адрес участка памяти;
• size – размер участка памяти в байтах (должен быть кратен размеру страницы).

В случае успешного освобождения страниц функция возвращает rcOk.

[Topic kn_vm_protect]

KnVmProtect()

Функция объявлена в файле coresrv/vmm/vmm_api.h.

Функция изменяет атрибуты защиты зарезервированных или переданных страниц памяти.

Параметры:

• addr – странично-выровненный базовый виртуальный адрес участка памяти;
• size – размер участка памяти в байтах (должен быть кратен размеру страницы);
• newFlags – новые атрибуты защиты.

В случае успешного изменения атрибутов защиты функция возвращает rcOk.

Допустимые комбинации атрибутов защиты памяти:

• VMM_FLAG_READ – разрешено чтение содержимого страницы;
• VMM_FLAG_READ | VMM_FLAG_WRITE – разрешено чтение и изменение содержимого страницы;
• VMM_FLAG_READ | VMM_FLAG_EXECUTE – разрешено чтение и выполнение содержимого страницы;
• VMM_FLAG_RWX_MASK или VMM_FLAG_READ | VMM_FLAG_WRITE | VMM_FLAG_EXECUTE – полный доступ к содержимому страницы (эти записи эквивалентны).

[Topic kn_vm_unmap]

KnVmUnmap()

Функция объявлена в файле coresrv/vmm/vmm_api.h.

Функция освобождает участок памяти.

Параметры:

• addr – странично-выровненный адрес участка памяти;
• size – размер участка памяти.

В случае успешного освобождения страниц функция возвращает rcOk.

[Topic api_memory_alloc]

Аллокация памяти

[Topic kos_mem_alloc]

KosMemAlloc()

Функция объявлена в файле kos/alloc.h.

Функция выделяет (резервирует и передает) участок памяти размером size байт.

Функция возвращает указатель на выделенный участок или RTL_NULL, если память не удалось выделить.

[Topic kos_mem_alloc_ex]

KosMemAllocEx()

Функция объявлена в файле kos/alloc.h.

Функция аналогична KosMemAlloc(), но при этом имеет дополнительные параметры:

• align – выравнивание участка памяти в байтах (степень двойки);
• zeroed – нужно ли заполнить участок памяти нулями (1 – заполнить, 0 – не заполнять).

[Topic kos_mem_free]

KosMemFree()

Функция объявлена в файле kos/alloc.h.

Функция освобождает участок памяти, выделенный с помощью функции KosMemAlloc(), KosMemZalloc() или KosMemAllocEx().

• ptr – указатель на освобождаемый участок памяти.

[Topic kos_mem_get_size]

KosMemGetSize()

Функция объявлена в файле kos/alloc.h.

Функция возвращает размер (в байтах) участка памяти, выделенного с помощью функции KosMemAlloc(), KosMemZalloc() или KosMemAllocEx().

• ptr – указатель на участок памяти.

[Topic kos_mem_zalloc]

KosMemZalloc()

Функция объявлена в файле kos/alloc.h.

Функция аналогична KosMemAlloc(), но при этом заполняет выделяемый участок памяти нулями.

[Topic libkos_threads]

Потоки

[Topic kos_thread_callback]

KosThreadCallback()

Прототип callback-функции объявлен в файле kos/thread.h.

При создании нового потока все зарегистрированные callback-функции будут вызваны с аргументом KosThreadCallbackReasonCreate, при завершении – с аргументом KosThreadCallbackReasonDestroy.

[Topic kos_thread_callback_register]

KosThreadCallbackRegister()

Функция объявлена в файле kos/thread.h.

Функция регистрирует пользовательскую callback-функцию. При создании и завершении потока будут вызваны все зарегистрированные callback-функции.

[Topic kos_thread_callback_unregister]

KosThreadCallbackUnregister()

Функция объявлена в файле kos/thread.h.

Функция дерегистрирует (удаляет из списка вызываемых) пользовательскую callback-функцию.

[Topic kos_thread_create]

KosThreadCreate()

Функция объявлена в файле kos/thread.h.

Функция создает новый поток.

Входные параметры:

• priority – приоритет, должен быть в интервале от 0 до 31; доступны следующие константы приоритета: ThreadPriorityLowest (0), ThreadPriorityNormal (15) и ThreadPriorityHighest (31);
• stackSize – размер стека;
• routine – функция, которая будет выполняться в потоке;
• context – аргумент, который будет передан в функцию routine;
• suspended – позволяет создать поток в приостановленном состоянии (1 – создать приостановленный, 0 – не приостановленный).

Выходные параметры:

• tid – идентификатор созданного потока.

Пример

[Topic kos_thread_current_id]

KosThreadCurrentId()

Функция объявлена в файле kos/thread.h.

Функция запрашивает TID вызывающего потока.

В случае успеха функция возвращает идентификатор потока (TID).

[Topic kos_thread_exit]

KosThreadExit()

Функция объявлена в файле kos/thread.h.

Функция принудительно завершает текущий поток с кодом выхода exitCode.

[Topic kos_thread_get_stack]

KosThreadGetStack()

Функция объявлена в файле kos/thread.h.

Функция получает стек потока с идентификатором tid.

Выходной параметр size содержит размер стека.

В случае успеха функция возвращает указатель на начало стека.

[Topic kos_thread_once]

KosThreadOnce()

Функция объявлена в файле kos/thread.h.

Функция позволяет вызвать заданную процедуру initRoutine в точности один раз, даже при вызове из нескольких потоков.

Параметр onceControl предназначен для контроля однократного вызова процедуры.

При успешном вызове процедуры, а также если она уже была вызвана ранее, функция KosThreadOnce() возвращает rcOk.

[Topic kos_thread_resume]

KosThreadResume()

Функция объявлена в файле kos/thread.h.

Функция возобновляет поток с идентификатором tid, созданный в приостановленном состоянии.

В случае успеха функция возвращает rcOk.

[Topic kos_thread_sleep]

KosThreadSleep()

Функция объявлена в файле kos/thread.h.

Функция приостанавливает выполнение текущего потока на mdelay миллисекунд.

В случае успеха функция возвращает rcOk.

[Topic kos_thread_suspend]

KosThreadSuspend()

Функция объявлена в файле kos/thread.h.

Функция необратимо останавливает текущий поток, не завершая его.

Параметр tid должен быть равен идентификатору текущего потока (ограничение текущей имплементации).

В случае успеха функция возвращает rcOk.

[Topic kos_thread_terminate]

KosThreadTerminate()

Функция объявлена в файле kos/thread.h.

Функция завершает поток вызывающего процесса. Параметр tid задает идентификатор потока.

Если tid указывает на текущий поток, то параметр exitCode задает код выхода потока.

В случае успеха функция возвращает rcOk.

[Topic kos_thread_tls_get]

KosThreadTlsGet()

Функция объявлена в файле kos/thread.h.

Функция возвращает указатель на локальное хранилище потока (TLS) или RTL_NULL, если TLS отсутствует.

[Topic kos_thread_tls_set]

KosThreadTlsSet()

Функция объявлена в файле kos/thread.h.

Функция задает адрес локального хранилища потока (TLS).

Входной аргумент tls содержит адрес TLS.

[Topic kos_thread_wait]

KosThreadWait()

Функция объявлена в файле kos/thread.h.

Функция приостанавливает выполнение текущего потока до момента завершения потока с идентификатором tid или до истечения timeout миллисекунд.

Вызов KosThreadWait() с нулевым значением timeout аналогичен вызову KosThreadYield().

В случае успеха функция возвращает rcOk, в случае таймаута rcTimeout.

[Topic kos_thread_yield]

KosThreadYield()

Функция объявлена в файле kos/thread.h.

Функция передает выполнение вызвавшего ее потока следующему потоку.

Вызов KosThreadYield() аналогичен вызову KosThreadSleep() с нулевым значением mdelay.

[Topic api_handles]

Дескрипторы

[Topic kn_handle_close]

KnHandleClose()

Функция объявлена в файле coresrv/handle/handle_api.h.

Функция удаляет дескриптор handle.

В случае успеха функция возвращает rcOk, иначе возвращает код ошибки.

[Topic kn_handle_create_badge]

KnHandleCreateBadge()

Функция объявлена в файле coresrv/handle/handle_api.h.

Функция создает объект контекста передачи ресурса для контекста передачи ресурса context и настраивает приемник уведомлений notice на прием уведомлений об этом объекте. Приемник уведомлений настраивается на прием уведомлений о событиях, которые соответствуют флагам маски событий EVENT_OBJECT_DESTROYED и EVENT_BADGE_CLOSED.

Входной параметр eventId задает идентификатор записи вида "ресурс – маска событий" в приемнике уведомлений.

Выходной параметр handle содержит дескриптор объекта контекста передачи ресурса.

В случае успеха функция возвращает rcOk, иначе возвращает код ошибки.

[Topic kn_handle_create_user_object]

KnHandleCreateUserObject()

Функция объявлена в файле coresrv/handle/handle_api.h.

Функция создает дескриптор handle типа type с маской прав rights.

Параметр type может принимать значения от HANDLE_TYPE_USER_FIRST до HANDLE_TYPE_USER_LAST.

Макросы HANDLE_TYPE_USER_FIRST и HANDLE_TYPE_USER_LAST определены в заголовочном файле handle/handletype.h.

Параметр context задает контекст пользовательского ресурса. В случае успеха функция возвращает rcOk, иначе возвращает код ошибки.

Пример

[Topic kn_handle_revoke]

KnHandleRevoke()

Функция объявлена в файле coresrv/handle/handle_api.h.

Функция удаляет дескриптор handle и отзывает всех его потомков.

В случае успеха функция возвращает rcOk, иначе возвращает код ошибки.

[Topic kn_handle_revoke_subtree]

KnHandleRevokeSubtree()

Функция объявлена в файле coresrv/handle/handle_api.h.

Функция отзывает дескрипторы, которые образуют поддерево наследования дескриптора handle.

Корневым узлом поддерева наследования является дескриптор, который порожден передачей дескриптора handle в ассоциации с объектом контекста передачи ресурса badge.

В случае успеха функция возвращает rcOk, иначе возвращает код ошибки.

[Topic nk_get_badge_op]

nk_get_badge_op()

Функция объявлена в файле nk/types.h.

Функция извлекает указатель на контекст передачи ресурса badge из транспортного контейнера дескриптора desc, если в маске прав, которая помещена в транспортном контейнере дескриптора desc, установлены флаги operation.

В случае успеха функция возвращает NK_EOK, иначе возвращает код ошибки.

[Topic nk_is_handle_dereferenced]

nk_is_handle_dereferenced()

Функция объявлена в файле nk/types.h.

Функция возвращает отличное от нуля значение, если дескриптор в транспортном контейнере дескриптора desc получен в результате операции разыменования дескриптора.

Функция возвращает нуль, если дескриптор в транспортном контейнере дескриптора desc получен в результате операции передачи дескриптора.

[Topic handles_manage]

Управление дескрипторами

Для управления дескрипторами используются функции менеджера дескрипторов (Handle Manager) и подсистемы уведомлений (Notification Subsystem).

Менеджер дескрипторов представлен для пользователя следующими файлами:

• coresrv/handle/handle_api.h – заголовочный файл библиотеки libkos;
• services/handle/Handle.idl – описание IPC-интерфейса менеджера дескрипторов на языке IDL.

Подсистема уведомлений представлена для пользователя следующими файлами:

• coresrv/handle/notice_api.h – заголовочный файл библиотеки libkos;
• services/handle/Notice.idl – описание IPC-интерфейса подсистемы уведомлений на языке IDL.

[Topic libkos_handles_rights]

Маска прав дескриптора

Маска прав дескриптора имеет размер 32 бита и состоит из общей и специальной части. Общая часть описывает права, неспецифичные для любых ресурсов (флаги этих прав определены в заголовочном файле services/ocap.h). Например, в общей части находится флаг OCAP_HANDLE_TRANSFER, который определяет право на передачу дескриптора. Специальная часть описывает права, специфичные для пользовательского или системного ресурса. Флаги прав специальной части для системных ресурсов определены в заголовочном файле services/ocap.h. Структура специальной части для пользовательских ресурсов определяется поставщиком ресурсов с использованием макроса OCAP_HANDLE_SPEC(), который определен в заголовочном файле services/ocap.h. Поставщику ресурсов необходимо экспортировать публичные заголовочные файлы с описанием структуры специальной части.

При создании дескриптора системного ресурса маска прав задается ядром KasperskyOS, которое применяет маски прав из заголовочного файла services/ocap.h. Применяются маски прав с именами вида OCAP_*_FULL (например, OCAP_IOPORT_FULL, OCAP_TASK_FULL, OCAP_FILE_FULL) и вида OCAP_IPC_* (например, OCAP_IPC_SERVER, OCAP_IPC_LISTENER, OCAP_IPC_CLIENT).

При создании дескриптора пользовательского ресурса маска прав задается пользователем.

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

[Topic handles_create]

Создание дескрипторов

Дескрипторы пользовательских ресурсов создаются поставщиками ресурсов. Для создания дескрипторов пользовательских ресурсов используется функция KnHandleCreateUserObject(), которая объявлена в заголовочном файле coresrv/handle/handle_api.h.

handle_api.h (фрагмент)

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

О маске прав дескриптора см. "Маска прав дескриптора".

[Topic libkos_handles_transfer]

Передача дескрипторов

Общие сведения

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

Один дескриптор может быть передан многократно одной или нескольким программам. Каждая передача порождает нового потомка переданного дескриптора на стороне принимающей программы. Программа может передавать дескрипторы, которые она получила от других программ или ядра KasperskyOS (при создании дескрипторов системных ресурсов). Поэтому у дескриптора может быть несколько поколений потомков. Иерархия порождения дескрипторов для каждого ресурса хранится в ядре KasperskyOS в виде дерева наследования дескрипторов.

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

Условия для передачи дескрипторов

Чтобы программы могли передавать дескрипторы между собой, должны выполняться следующие условия:

1. Между программами создан IPC-канал.
2. Политика безопасности решения (security.psl) разрешает взаимодействие программ.
3. Реализованы интерфейсные методы для передачи дескрипторов.
4. Программа-клиент получила идентификатор службы (RIID) программы-сервера с методами для передачи дескрипторов.

Интерфейсные методы для передачи дескрипторов объявляются в IDL-описании с входными (in) и/или выходными (out) параметрами типа Handle. Методы с входными параметрами типа Handle предназначены для передачи дескрипторов от программы-клиента программе-серверу. Методы с выходными параметрами типа Handle предназначены для передачи дескрипторов от программы-сервера программе-клиенту. Для одного метода может быть объявлено не более семи входных и семи выходных параметров типа Handle.

Пример IDL-описания, где объявлены интерфейсные методы для передачи дескрипторов:

Для каждого параметра типа Handle компилятор NK генерирует в структурах запросов *_req и/или ответов *_res поле типа nk_handle_desc_t (далее также транспортный контейнер дескриптора). Этот тип объявлен в заголовочном файле nk/types.h и представляет собой структуру, состоящую из трех полей: поля дескриптора handle, поля маски прав дескриптора rights и поля контекста передачи ресурса badge.

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

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

Программа-сервер независимо от того, является ли она поставщиком ресурса или нет, может ассоциировать каждую передачу дескриптора с отдельным контекстом передачи ресурса. Этот контекст передачи ресурса связывается только с теми потомками дескриптора (поддеревом наследования дескриптора), которые порождены в результате конкретной его передачи. Это позволяет определять состояние ресурса по отношению к отдельной передаче дескриптора этого ресурса. Например, в случае множественного доступа к одному файлу контекст передачи файла позволяет определить, какому именно открытию этого файла соответствует полученный запрос.

Если программа-сервер является поставщиком ресурса, то по умолчанию каждая передача дескриптора этого ресурса ассоциируется с контекстом пользовательского ресурса. То есть контекст пользовательского ресурса используется в качестве контекста передачи ресурса для каждой передачи дескриптора, если эта передача не ассоциируется с отдельным контекстом передачи ресурса.

Программа-сервер, которая является поставщиком ресурса, может использовать совместно контекст пользовательского ресурса и контексты передачи ресурса. Например, имя, путь и размер файла хранятся в контексте пользовательского ресурса, а положение курсора хранится в нескольких контекстах передачи ресурса, так как каждый клиент может работать с разными частями файла. Технически совместное использование контекста пользовательского ресурса и контекстов передачи ресурса достигается тем, что контексты передачи ресурса хранят указатель на контекст пользовательского ресурса.

Если программа-клиент использует несколько разнотипных ресурсов программы-сервера, контексты передачи ресурсов (или контексты пользовательских ресурсов, если они используются в качестве контекстов передачи ресурсов) должны быть типизированными объектами KosObject. Это нужно, чтобы программа-сервер могла проверить, что программа-клиент при использовании ресурса передала в интерфейсный метод дескриптор того ресурса, который соответствует этому методу. Такая проверка требуется, поскольку программа-клиент может ошибочно передать в интерфейсный метод дескриптор ресурса, который не соответствует этому методу. Например, программа-клиент получила дескриптор файла и передала его в интерфейсный метод для работы с томами.

Чтобы ассоциировать передачу дескриптора с контекстом передачи ресурса, программа-сервер помещает в поле badge структуры nk_handle_desc_t дескриптор объекта контекста передачи ресурса. Объект контекста передачи ресурса – объект, в котором хранится указатель на контекст передачи ресурса. Объект контекста передачи ресурса создается функцией KnHandleCreateBadge(), которая объявлена в заголовочном файле coresrv/handle/handle_api.h. Работа этой функции связана с подсистемой уведомлений о состоянии ресурсов, так как программе-серверу нужно знать, когда объект контекста передачи ресурса будет закрыт и прекратит свое существование. Эти сведения требуются программе-серверу, чтобы освободить или использовать повторно память, которая отведена для хранения контекста передачи ресурса.

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

Один объект контекста передачи ресурса может быть ассоциирован только с одной передачей дескриптора.

handle_api.h (фрагмент)

Упаковка данных в транспортный контейнер дескриптора

Для упаковки дескриптора, маски прав дескриптора и дескриптора объекта контекста передачи ресурса в транспортный контейнер дескриптора используется макрос nk_handle_desc(), который определен в заголовочном файле nk/types.h. Этот макрос принимает переменное число аргументов.

Если не передавать макросу ни одного аргумента, то в поле дескриптора handle структуры nk_handle_desc_t будет записано значение NK_INVALID_HANDLE.

Если передать макросу один аргумент, то этот аргумент интерпретируется как дескриптор.

Если передать макросу два аргумента, то первый аргумент интерпретируется как дескриптор, второй аргумент интерпретируется как маска прав дескриптора.

Если передать макросу три аргумента, то первый аргумент интерпретируется как дескриптор, второй аргумент интерпретируется как маска прав дескриптора, третий аргумент интерпретируется как дескриптор объекта контекста передачи ресурса.

Извлечение данных из транспортного контейнера дескриптора

Для извлечения дескриптора, маски прав дескриптора и указателя на контекст передачи ресурса из транспортного контейнера дескриптора используются соответственно функции nk_get_handle(), nk_get_rights() и nk_get_badge_op() (или nk_get_badge()), которые определены в заголовочном файле nk/types.h. Функции nk_get_badge_op() и nk_get_badge() используются только при разыменовании дескрипторов.

Сценарии передачи дескрипторов

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

1. Передающая программа-клиент упаковывает дескрипторы и маски прав дескрипторов в поля структуры запросов *_req типа nk_handle_desc_t.
2. Передающая программа-клиент вызывает интерфейсный метод для передачи дескрипторов программе-серверу. Этот метод выполняет системный вызов Call().
3. Принимающая программа-сервер получает запрос, выполняя системный вызов Recv().
4. Диспетчер на стороне принимающей программы-сервера вызывает метод, который соответствует запросу. Этот метод извлекает дескрипторы и маски прав дескрипторов из полей структуры запросов *_req типа nk_handle_desc_t.

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

1. Принимающая программа-клиент вызывает интерфейсный метод для получения дескрипторов от программы-сервера. Этот метод выполняет системный вызов Call().
2. Передающая программа-сервер получает запрос, выполняя системный вызов Recv().
3. Диспетчер на стороне передающей программы-сервера вызывает метод, который соответствует запросу. Этот метод упаковывает дескрипторы, маски прав дескрипторов и дескрипторы объектов контекстов передачи ресурсов в поля структуры ответов *_res типа nk_handle_desc_t.
4. Передающая программа-сервер отвечает на запрос, выполняя системный вызов Reply().
5. На стороне принимающей программы-клиента интерфейсный метод возвращает управление. После этого принимающая программа-клиент извлекает дескрипторы и маски прав дескрипторов из полей структуры ответов *_res типа nk_handle_desc_t.

Если передающая программа задает в передаваемой маске прав дескриптора больше прав доступа, чем задано для передаваемого дескриптора (владельцем которого она является), то передача не осуществляется. В этом случае выполнение системного вызова Call() передающей или принимающей программой-клиентом, а также выполнение системного вызова Reply() передающей программой-сервером завершается с ошибкой rcSecurityDisallow.

[Topic libkos_handles_dereference]

Разыменование дескрипторов

Разыменование дескриптора – это операция, при которой программа-клиент отправляет программе-серверу дескриптор, а программа-сервер получает указатель на контекст передачи ресурса, маску прав отправленного дескриптора и предка отправленного программой-клиентом дескриптора, которым программа-сервер уже владеет. Разыменование выполняется, когда программа-клиент, вызывая методы работы с ресурсом (например, чтения, записи, закрытия доступа), передает программе-серверу дескриптор, который был получен от этой программы-сервера при открытии доступа к ресурсу.

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

1. Программа-клиент упаковывает дескриптор в поле структуры запросов *_req типа nk_handle_desc_t.
2. Программа-клиент вызывает интерфейсный метод для отправки дескриптора программе-серверу с целью выполнения действий с ресурсом. Этот метод выполняет системный вызов Call().
3. Программа-сервер принимает запрос, выполняя системный вызов Recv().
4. Диспетчер на стороне программы-сервера вызывает метод, который соответствует запросу. Этот метод проверяет, что выполнена именно операция разыменования, а не передача дескриптора. Затем вызванный метод опционально проверяет, что права доступа разыменованного дескриптора (который отправлен программой-клиентом) разрешают запрашиваемые действия с ресурсом, и извлекает указатель на контекст передачи ресурса из поля структуры запросов *_req типа nk_handle_desc_t.

Для выполнения проверок программа-сервер использует функции nk_is_handle_dereferenced() и nk_get_badge_op(), которые объявлены в заголовочном файле nk/types.h.

types.h (фрагмент)

В общем случае программе-серверу не требуется дескриптор, который получен в результате разыменования, поскольку программа-сервер, как правило, сохраняет дескрипторы, которыми владеет, например, в составе контекстов пользовательских ресурсов. Но при необходимости программа-сервер может извлечь этот дескриптор из транспортного контейнера дескриптора.

[Topic libkos_handles_revoke]

Отзыв дескрипторов

Программа может отзывать потомков дескриптора, которым она владеет. Отзыв дескрипторов осуществляется согласно дереву наследования дескрипторов.

Отзыв дескрипторов не удаляет их, но через отозванные дескрипторы невозможно обращаться к ресурсам. Любая функция, которая принимает дескриптор, завершается с ошибкой rcHandleRevoked, если эта функция вызывается с отозванным дескриптором.

Отзыв выполняется функциями KnHandleRevoke() и KnHandleRevokeSubtree(), которые объявлены в заголовочном файле coresrv/handle/handle_api.h. Функция KnHandleRevokeSubtree() использует объект контекста передачи ресурса, который создается при передаче дескрипторов.

handle_api.h (фрагмент)

[Topic libkos_handles_notification]

Уведомление о состоянии ресурсов

Программы могут отслеживать события, которые происходят с ресурсами (как системными, так и пользовательскими), а также информировать о событиях с пользовательскими ресурсами другие программы.

Функции подсистемы уведомлений объявлены в заголовочном файле coresrv/handle/notice_api.h. Подсистема уведомлений предусматривает использование масок событий.

Маска событий – значение, биты которого интерпретируются как события, которые должны отслеживаться или уже произошли. Маска событий имеет размер 32 бита и состоит из общей и специальной части. Общая часть описывает события, неспецифичные для любых ресурсов (флаги этих событий определены в заголовочном файле handle/event_descr.h). Например, в общей части находится флаг EVENT_OBJECT_DESTROYED, который определяет событие "прекращение существования ресурса". Специальная часть описывает события, специфичные для пользовательского ресурса. Структура специальной части определяется поставщиком ресурса с использованием макроса OBJECT_EVENT_SPEC(), который определен в заголовочном файле handle/event_descr.h. Поставщику ресурса необходимо экспортировать публичные заголовочные файлы с описанием структуры специальной части.

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

1. Функцией KnNoticeCreate() создается приемник уведомлений (объект, в котором накапливаются уведомления).
2. В приемник уведомлений функцией KnNoticeSubscribeToObject() добавляются записи вида "ресурс – маска событий", чтобы настроить его на прием уведомлений о событиях, которые происходят с интересующими ресурсами. Набор отслеживаемых событий задается для каждого ресурса маской событий.
3. Чтобы извлекать уведомления из приемника уведомлений, вызывается функция KnNoticeGetEvent().

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

notice_api.h (фрагмент)

[Topic libkos_handles_delete]

Удаление дескрипторов

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

Удаление дескрипторов выполняется функцией KnHandleClose(), которая объявлена в заголовочном файле coresrv/handle/handle_api.h.

handle_api.h (фрагмент)

[Topic libkos_handles_simple_scenario]

Пример использования OCap

В этой статье приведен сценарий использования OCap, в котором программа-сервер предоставляет следующие методы доступа к своим ресурсам:

• OpenResource() – открытие доступа к ресурсу;
• UseResource() – использование ресурса;
• CloseResource() – закрытие доступа к ресурсу.

Программа-клиент использует эти методы.

IDL-описание интерфейсных методов:

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

1. Поставщик ресурса создает контекст пользовательского ресурса и вызывает функцию KnHandleCreateUserObject() для создания дескриптора ресурса. Поставщик ресурса сохраняет дескриптор ресурса в контексте пользовательского ресурса.
2. Клиент вызывает метод открытия доступа к ресурсу OpenResource().
   1. Поставщик ресурса создает контекст передачи ресурса и вызывает функцию KnHandleCreateBadge() для создания объекта контекста передачи ресурса и настройки приемника уведомлений на прием уведомлений о закрытии и прекращении существования объекта контекста передачи ресурса. Поставщик ресурса сохраняет дескриптор объекта контекста передачи ресурса и указатель на контекст пользовательского ресурса в контексте передачи ресурса.
   2. Поставщик ресурса, используя макрос nk_handle_desc(), упаковывает дескриптор ресурса, маску прав дескриптора и указатель на объект контекста передачи ресурса в транспортный контейнер дескриптора.
   3. Выполняется передача дескриптора от поставщика ресурса клиенту, в результате которой клиент получает потомка дескриптора, которым владеет поставщик ресурса.
   4. Вызов метода OpenResource() завершается успешно. Клиент извлекает дескриптор и маску прав дескриптора из транспортного контейнера дескриптора функциями nk_get_handle() и nk_get_rights() соответственно. Маска прав дескриптора не требуется клиенту для обращения к ресурсу и передается, чтобы клиент мог узнать свои права доступа к ресурсу.
3. Клиент вызывает метод использования ресурса UseResource().
   1. Дескриптор, который получен от поставщика ресурса на шаге 2, используется в качестве аргумента метода UseResource(). Перед вызовом этого метода клиент упаковывает дескриптор в транспортный контейнер дескриптора макросом nk_handle_desc().
   2. Выполняется разыменование дескриптора, в результате которого поставщик ресурса получает указатель на контекст передачи ресурса.
   3. Поставщик ресурса, используя функцию nk_is_handle_dereferenced(), проверяет, что выполнена операция разыменования, а не передача дескриптора.
   4. Поставщик ресурса проверяет, что права доступа разыменованного дескриптора (который отправлен клиентом) разрешают запрашиваемую операцию над ресурсом, и извлекает указатель на контекст передачи ресурса из транспортного контейнера дескриптора. Для этого поставщик ресурса использует функцию nk_get_badge_op(), которая извлекает указатель на контекст передачи ресурса из транспортного контейнера дескриптора, если в полученной маске прав установлены флаги, соответствующие запрашиваемой операции.
   5. Поставщик ресурса, используя контекст передачи ресурса и контекст пользовательского ресурса, выполняет запрашиваемую клиентом операцию над ресурсом. Затем поставщик ресурса отправляет клиенту результат выполнения этой операции.
   6. Вызов метода UseResource() завершается успешно. Клиент получает результат выполнения операции над ресурсом.
4. Клиент вызывает метод закрытия доступа к ресурсу CloseResource().
   1. Дескриптор, который получен от поставщика ресурса на шаге 2, используется в качестве аргумента метода CloseResource(). Перед вызовом этого метода клиент упаковывает дескриптор в транспортный контейнер дескриптора макросом nk_handle_desc(). После вызова метода CloseResource() клиент удаляет дескриптор функцией KnHandleClose().
   2. Выполняется разыменование дескриптора, в результате которого поставщик ресурса получает указатель на контекст передачи ресурса.
   3. Поставщик ресурса, используя функцию nk_is_handle_dereferenced(), проверяет, что выполнена операция разыменования, а не передача дескриптора.
   4. Поставщик ресурса, используя функцию nk_get_badge(), извлекает указатель на контекст передачи ресурса из транспортного контейнера дескриптора.
   5. Поставщик ресурса отзывает дескриптор, которым владеет клиент, функцией KnHandleRevokeSubtree(). В качестве аргументов этой функции используются дескриптор ресурса, которым владеет поставщик ресурса, и дескриптор объекта контекста передачи ресурса. Поставщик ресурса получает доступ к этим дескрипторам через указатель на контекст передачи ресурса. (Технически не требуется отзывать дескриптор, которым владеет клиент, так как клиент его уже удалил. Но поставщик ресурса не может быть уверен в том, что клиент удалил дескриптор, поэтому выполняется отзыв).
   6. Вызов метода CloseResource() завершается успешно.
5. Поставщик ресурса освобождает память, которая была выделена под контекст передачи ресурса и контекст пользовательского ресурса.
   1. Поставщик ресурса вызовом функции KnNoticeGetEvent() получает уведомление, что объект контекста передачи ресурса закрыт, и удаляет дескриптор объекта контекста передачи ресурса функцией KnHandleClose().
   2. Поставщик ресурса вызовом функции KnNoticeGetEvent() получает уведомление, что объект контекста передачи ресурса прекратил свое существование, и освобождает память, которая была выделена под контекст передачи ресурса.
   3. Поставщик ресурса удаляет дескриптор ресурса функцией KnHandleClose() и освобождает память, которая была выделена под контекст пользовательского ресурса.

[Topic libkos_notice]

Уведомления

[Topic event_mask]

Маска событий

Маска событий – значение, биты которого интерпретируются как события, которые должны отслеживаться или уже произошли. Маска событий имеет размер 32 бита и состоит из общей и специальной части. Общая часть описывает события, неспецифичные для любых ресурсов (флаги этих событий определены в заголовочном файле handle/event_descr.h). Например, в общей части находится флаг EVENT_OBJECT_DESTROYED, который определяет событие "прекращение существования ресурса". Специальная часть описывает события, специфичные для пользовательского ресурса. Структура специальной части определяется поставщиком ресурса с использованием макроса OBJECT_EVENT_SPEC(), который определен в заголовочном файле handle/event_descr.h. Поставщику ресурса необходимо экспортировать публичные заголовочные файлы с описанием структуры специальной части.

[Topic event_desc]

EventDesc

Структура, описывающая уведомление, объявлена в файле coresrv/handle/notice_api.h.

eventId – идентификатор записи "ресурс – маска событий" в приемнике уведомлений.

eventMask – маска событий, которые произошли.

[Topic notice_create]

KnNoticeCreate()

Функция объявлена в файле coresrv/handle/notice_api.h.

Функция создает приемник уведомлений notice (объект, в котором накапливаются уведомления).

В случае успеха функция возвращает rcOk, иначе возвращает код ошибки.

[Topic notice_get_event]

KnNoticeGetEvent()

Функция объявлена в файле coresrv/handle/notice_api.h.

Функция извлекает уведомления из приемника уведомлений notice, ожидая наступления событий в течение msec миллисекунд.

Входной параметр countMax задает максимальное число уведомлений, которое может быть извлечено.

Выходной параметр events содержит набор извлеченных уведомлений типа EventDesc.

Выходной параметр count содержит число уведомлений, которые были извлечены.

В случае успеха функция возвращает rcOk, иначе возвращает код ошибки.

Пример

[Topic notice_set_object_event]

KnNoticeSetObjectEvent()

Функция объявлена в файле coresrv/handle/notice_api.h.

Функция сигнализирует, что события из маски событий evMask произошли с ресурсом object.

Нельзя устанавливать флаги общей части маски событий, так как о событиях из общей части маски событий может сигнализировать только ядро KasperskyOS.

В случае успеха функция возвращает rcOk, иначе возвращает код ошибки.

[Topic notice_subscribe_to_object]

KnNoticeSubscribeToObject()

Функция объявлена в файле coresrv/handle/notice_api.h.

Функция добавляет запись вида "ресурс – маска событий" в приемник уведомлений notice, чтобы он принимал уведомления о событиях, которые происходят с ресурсом object и соответствуют маске событий evMask.

Входной параметр evId задает идентификатор записи, который назначается пользователем и используется, чтобы идентифицировать запись в полученных уведомлениях.

В случае успеха функция возвращает rcOk, иначе возвращает код ошибки.

Пример использования – см. KnHandleCreateUserObject().

[Topic libkos_tasks]

Процессы

[Topic entity_connect]

EntityConnect()

Функция объявлена в заголовочном файле coresrv/entity/entity_api.h.

Функция соединяет процессы IPC-каналом. Для этого функция создает IPC-дескрипторы для процесса-клиента cl и процесса-сервера sr, а затем связывает дескрипторы друг с другом. Создаваемый канал будет включен в группу каналов по умолчанию (имя этой группы совпадает с именем процесса-сервера). Соединяемые процессы должны находиться в остановленном состоянии.

В случае успеха функция возвращает rcOk.

[Topic entity_connect_to_service]

EntityConnectToService()

Функция объявлена в заголовочном файле coresrv/entity/entity_api.h.

Функция соединяет процессы IPC-каналом. Для этого функция создает IPC-дескрипторы для процесса-клиента cl и процесса-сервера sr, а затем связывает дескрипторы друг с другом. Создаваемый канал будет включен в группу каналов с именем name. Соединяемые процессы должны находиться в остановленном состоянии.

В случае успеха функция возвращает rcOk.

[Topic entity_info]

EntityInfo

Структура EntityInfo, описывающая процесс, объявлена в файле if_connection.h.

[Topic entity_init]

EntityInit()

Функция объявлена в заголовочном файле coresrv/entity/entity_api.h.

Функция создает процесс. Параметр info задает имя класса процесса и (опционально) его службы, аргументы и переменные окружения.

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

В случае успеха функция возвращает структуру, описывающую новый процесс. Созданный процесс находится в остановленном состоянии.

В случае ошибки функция возвращает RTL_NULL.

[Topic entity_init_ex]

EntityInitEx()

Функция объявлена в заголовочном файле coresrv/entity/entity_api.h.

Функция создает процесс.

Параметр info задает имя класса процесса и (опционально) его службы, аргументы и переменные окружения.

Параметр name задает имя процесса. Если он имеет значение RTL_NULL, то в качестве имени процесса будет использоваться имя класса процесса из параметра info.

Параметр path задает имя исполняемого файла в ROMFS-образе решения. Если он имеет значение RTL_NULL, то в качестве имени файла будет использоваться имя класса процесса из параметра info.

В случае успеха функция возвращает структуру, описывающую новый процесс. Созданный процесс находится в остановленном состоянии.

В случае ошибки функция возвращает RTL_NULL.

[Topic entity_run]

EntityRun()

Функция объявлена в заголовочном файле coresrv/entity/entity_api.h.

Функция запускает процесс, находящийся в остановленном состоянии. Процесс описывается структурой entity.

В случае успеха функция возвращает rcOk.