[Topic whats_new]

Что нового

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

• Изменены системные требования: для установки SDK требуется ОС Ubuntu GNU/Linux 22.04 "Jammy Jellyfish".
• Добавлена возможность использовать динамические библиотеки.
• Добавлена возможность использовать аппаратный сторожевой таймер (watchdog) на Raspberry Pi 4 Model B.
• Добавлен компонент ExecutionManager, предназначенный для создания, запуска и остановки процессов.
• Добавлен скрипт для автоматической установки переменных окружения, используемых инструментами SDK.
• Добавлена передача данных на серверы "Лаборатории Касперского" при запуске сборки примеров из состава SDK. Данные передаются с целью учета количества пользователей KasperskyOS Community Edition и получения информации о распространении и использовании KasperskyOS Community Edition. Вы можете отключить эту функциональность.
• Обновлено руководство разработчика, в частности:
  • Добавлен раздел "Работа с ареной IPC-сообщений".
  • Добавлен раздел "Сведения о некоторых лимитах, установленных в системе".
  • Добавлены описания сценариев работы с интерфейсами библиотеки libkos.
  • Обновлена инструкция по сборке и выполнению тестов политики безопасности решения.
  • Добавлен глоссарий.
• Добавлены следующие сторонние библиотеки и приложения:
  • Guidelines Support Library (GSL) (2.1.0);
  • json_scheme_validator (2.1.0);
  • libpcap (1.10.4);
  • libunwind (1.6.2);
• Обновлены следующие сторонние библиотеки и приложения:
  • libxml2;
  • Mbedtls;
  • Mosquitto;
  • OpenSSL;
  • spdlog;
  • sqlite;
  • fmt;
  • zlib
  • flex;
  • bison;
  • QEMU.
• Исключены из состава SDK следующие сторонние библиотеки и приложения:
  • ffmpeg;
  • opencv;
  • libjpeg-turbo;
  • libpng;
  • protobuf.

В 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, набор утилит binutils, эмулятор QEMU и сопутствующие инструменты);
  • утилиты и скрипты (например, генераторы исходного кода, скрипт makekss для создания модуля безопасности Kaspersky Security Module, скрипт makeimg для создания образа решения);
  • набор библиотек, обеспечивающих частичную совместимость со стандартом POSIX;
  • драйверы;
  • системные программы (например, виртуальную файловую систему);
  • примеры работы с компонентами KasperskyOS Community Edition;
  • лицензионное соглашение;
  • файл с информацией о стороннем коде (Legal Notices).
• Руководство разработчика KasperskyOS Community Edition (онлайн-документация).
• Информация о версии (Release Notes);

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

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

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

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

[Topic system_requirements]

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

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

1. Операционная система: Ubuntu GNU/Linux 22.04 "Jammy Jellyfish". Возможно использование 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 также включены следующие сторонние библиотеки и приложения:

• flex (v.2.6.2) – генератор лексических анализаторов.

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

• pkg-config-lite (v.0.28) – утилита, предоставляющая интерфейс для получения информации об установленных в системе библиотеках (версия, параметры для C / C ++ компилятора и компоновщика).

  Документация: https://sourceforge.net/projects/pkgconfiglite

• CMake (v.3.25.0) – кроссплатформенное программное средство автоматизации сборки программного обеспечения из исходного кода.

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

• autoconf-archive (v.2022.09.03) – набор макросов для утилиты Autoconf, создающей конфигурационные скрипты для автоматической настройки и сборки программного обеспечения из исходного кода.

  Документация: https://www.gnu.org/software/autoconf-archive

• Automake (v.1.13 и v.1.16.4) – утилита генерации стандартизированных файлов Makefile.in для автоматической настройки и сборки программного обеспечения из исходного кода.

  Документация: https://www.gnu.org/software/automake

• Autoconf (v.2.69) – утилита генерации конфигурационных скриптов configure для автоматической настройки и сборки программного обеспечения из исходного кода.

  Документация: https://www.gnu.org/software/autoconf

• autotools-wrappers (v.am-10) – обертка для утилит Autoconf и Automake, которая определяет подходящую для автоматической настройки и сборки программного обеспечения версию утилиты из нескольких, установленных в системе.

  Документация: https://gitweb.gentoo.org/proj/autotools-wrappers.git/tree

• Libtool (v.2.4.2) – скрипт поддержки общих библиотек, который скрывает сложности использования библиотек за последовательным, переносимым интерфейсом.

  Документация: https://www.gnu.org/software/libtool

• Binutils (v.2.38) – набор утилит для работы с бинарными файлами, который включает в себя ассемблер, компоновщик, архиватор и другие утилиты.

  Документация: https://www.gnu.org/software/binutils

• Bison (v.3.5.4) – генератор синтаксических анализаторов общего назначения, преобразующий аннотированную контекстно-свободную грамматику в LR- или GLR-анализатор с использованием таблиц разбора LALR(1).

  Документация: https://www.gnu.org/software/bison

• GNU Compiler Collection (GCC) (v.9.2.1) – набор компиляторов для различных языков программирования, включая C / C ++.

  Документация: https://gcc.gnu.org/onlinedocs

• QEMU (v.8.1.3) – программа для эмуляции аппаратного обеспечения различных платформ.

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

• 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

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

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

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

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

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

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

• Guidelines Support Library (GSL) (v.2.1.0) – библиотека, содержащая функции и типы, которые предлагаются к использованию в соответствии с C++ Core Guidelines при поддержке Standard C++ Foundation.

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

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

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

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

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

• json-schema-validator (v.2.1.0) – библиотека, предназначенная для проведения валидации данных в формате JSON в соответствии с заданными JSON-схемами.

  Документация: https://github.com/pboettch/json-schema-validator

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

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

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

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

• libpcap (v.1.10.4) – библиотека для разработки программ, которые могут захватывать, фильтровать и анализировать сетевой трафик в UNIX-подобных системах.

  Документация: https://www.tcpdump.org/index.html#documentation

• libunwind (v.1.6.2) – библиотека для обработки исключительных ситуаций и реализации механизма обратной трассировки стека вызова функций при аварийном завершении процесса.

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

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

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

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

  Документация: https://mbed-tls.readthedocs.io/en/latest

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

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

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

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

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

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

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

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

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

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

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

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

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

  Документация: 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

• dhcpcd (v.9.4.1) – DHCP-, DHCPv6-клиент, предназначенный для автоматической конфигурации сетевых параметров на клиентской стороне.

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

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

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

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

[Topic limitations_and_known_problems]

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

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

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

[Topic migration_to_12]

Миграция прикладного кода с версии SDK 1.1.1 на версию SDK 1.2

В связи с изменениями в компонентах SDK в версии 1.2, вам необходимо внести изменения в прикладной код, разработанный с использованием версии KasperskyOS Community Edition 1.1.1, перед тем как использовать его с версией KasperskyOS Community Edition 1.2.

Список необходимых изменений:

1. В SDK добавился драйвер для работы с сопроцессором VideoCore (VC6) через технологию mailbox: kl.drivers.Bcm2711MboxArmToVc, доступ к которому необходим драйверам kl.drivers.DNetSrv и kl.drivers.USB.
   • Если для создания init-описания решения (файл init.yaml) используется шаблон init.yaml.in и для процессов kl.drivers.DNetSrv и kl.drivers.USB использованы макросы @INIT_ProgramName_ENTITY_CONNECTIONS+@ или @INIT_ProgramName_ENTITY_CONNECTIONS@, то изменений в init-описании не требуется.

     Иначе, если IPC-каналы для процессов kl.drivers.DNetSrv и kl.drivers.USB указаны вручную, то необходимо добавить процесс kl.drivers.Bcm2711MboxArmToVc в init-описание и определить IPC-каналы между ним и процессами kl.drivers.DNetSrv и kl.drivers.USB:

   - name: kl.drivers.Bcm2711MboxArmToVc path: bcm2711_mbox_arm2vc_h - name: kl.drivers.USB path: usb connections: ... - target: kl.drivers.Bcm2711MboxArmToVc id: kl.drivers.Bcm2711MboxArmToVc - name: kl.drivers.DNetSrv path: dnet_entity connections: ... - target: kl.drivers.Bcm2711MboxArmToVc id: kl.drivers.Bcm2711MboxArmToVc
   • Необходимо добавить процесс kl.drivers.Bcm2711MboxArmToVc в файл security.psl и разрешить процессам kl.drivers.DNetSrv и kl.drivers.USB и ядру взаимодействовать с ним:
   ... use kl.drivers.Bcm2711MboxArmToVc._ ... execute src = Einit dst = kl.drivers.Bcm2711MboxArmToVc { grant () } request src = kl.drivers.Bcm2711MboxArmToVc dst = kl.core.Core { grant () } response src = kl.core.Core dst = kl.drivers.Bcm2711MboxArmToVc { grant () } request src = kl.drivers.DNetSrv dst = kl.drivers.Bcm2711MboxArmToVc { grant () } response src = kl.drivers.Bcm2711MboxArmToVc dst = kl.drivers.DNetSrv { grant () } request src = kl.drivers.USB dst = kl.drivers.Bcm2711MboxArmToVc { grant () } response src = kl.drivers.Bcm2711MboxArmToVc dst = kl.drivers.USB{ grant () }
2. Всем реализациям компонента VFS теперь необходим доступ к программе kl.EntropyEntity.
   • Если для создания init-описания решения (файл init.yaml) используется шаблон init.yaml.in и для процессов, использующих компонент VFS (как поставляемых в составе SDK kl.VfsNet, kl.VfsRamFs, kl.VfsSdCardFs, так и включающих в себя VFS статически), использованы макросы @INIT_ProgramName_ENTITY_CONNECTIONS+@ или @INIT_ProgramName_ENTITY_CONNECTIONS@, то изменений в init-описании не требуется.

     Иначе, если IPC-каналы для процессов, использующих компонент VFS, указаны вручную, то необходимо добавить процесс kl.EntropyEntity в init-описание и определить IPC-каналы между ним и процессами, использующими компонент VFS:

   - name: kl.VfsSdCardFs path: VfsSdCardFs connections: ... - target: kl.EntropyEntity id: kl.EntropyEntity - name: kl.VfsNet path: VfsNet connections: ... - target: kl.EntropyEntity id: kl.EntropyEntity - name: kl.ProgramWithEmbeddedVfs path: ProgramWithEmbedVfs connections: ... - target: kl.EntropyEntity id: kl.EntropyEntity - name: kl.EntropyEntity path: Entropy
   • Необходимо добавить процесс kl.EntropyEntity в файл security.psl и разрешить процессам, использующим компонент VFS, и ядру взаимодействовать с ним:
   ... use kl.EntropyEntity._ ... execute src = Einit dst = kl.drivers.EntropyEntity { grant () } ... request src = kl.EntropyEntity dst = kl.core.Core { grant () } response src = kl.core.Core dst = kl.EntropyEntity { grant () } request src = kl.VfsNet dst = kl.EntropyEntity { grant () } response src = kl.EntropyEntity dst = kl.VfsNet { grant () } request src = kl.VfsSdCardFs dst = kl.EntropyEntity { grant () } response src = kl.EntropyEntity dst = kl.VfsSdCardFs { grant () } request src = kl.ProgramWithEmbeddedVfs dst = kl.EntropyEntity { grant () } response src = kl.EntropyEntity dst = kl.ProgramWithEmbeddedVfs { grant () }
3. Драйверу kl.drivers.USB теперь необходим доступ к программе kl.core.NameServer.
   • Если для создания init-описания решения (файл init.yaml) используется шаблон init.yaml.in и для процесса kl.drivers.USB использованы макросы @INIT_ProgramName_ENTITY_CONNECTIONS+@ или @INIT_ProgramName_ENTITY_CONNECTIONS@, то изменений в init-описании не требуется.

     Иначе, если IPC-каналы для процесса kl.drivers.USB указаны вручную, то необходимо добавить процесс kl.core.NameServer в init-описание и определить IPC-каналы между ним и процессом kl.drivers.USB:

   - name: kl.core.NameServer path: ns - name: kl.drivers.USB path: usb connections: ... - target: kl.core.NameServer id: kl.core.NameServer
   • Необходимо добавить процесс kl.core.NameServer в файл security.psl и разрешить процессу kl.drivers.USB и ядру взаимодействовать с ним:
   ... use kl.core.NameServer ... execute src = Einit dst = kl.core.NameServer { grant () } ... request src = kl.core.NameServer dst = kl.core.Core { grant () } response src = kl.core.Core dst = kl.core.NameServer { grant () } request src = kl.drivers.USB dst = kl.core.NameServer { grant () } response src = core.NameServer dst = kl.drivers.USB { grant () }
4. В SDK добавлена возможность использования динамических библиотек. Теперь любое решение по умолчанию собирается с использованием динамической компоновки. Это может повлиять на сборку решений, содержащих библиотеки, имеющие как статический так и динамический вариант.
   • Чтобы включить принудительную статическую компоновку исполняемых файлов, нужно в корневом CMakeLists.txt проекта заменить initialize_platform() на initialize_platform (FORCE_STATIC).
   • Для перехода от статической компоновки к динамической компоновке необходимо выполнить дополнительные действия, описанные в статье "Использование динамических библиотек".
   • Для использования динамических библиотек необходимо включить в решение системную программу BlobContainer.
   • Необходимо добавить процесс kl.bc.BlobContainer в файл security.psl и разрешить процессам, использующим динамические библиотеки, взаимодействовать с ним:
   ... use kl.bc.BlobContainer ... execute src = Einit dst = kl.bc.BlobContainer { grant () } request { /* Allows tasks with the kl.bc.BlobContainer class to send requests to specified tasks. */ match src = kl.bc.BlobContainer { match dst = kl.core.Core { grant () } match dst = kl.VfsSdCardFs { grant () } } /* Allows task with the kl.bc.BlobContainer class to recive request from any task. */ match dst = kl.bc.BlobContainer { grant () } } response { /* Allows tasks with the kl.bc.BlobContainer class to get responses from specified tasks. */ match dst = kl.bc.BlobContainer { match src = kl.core.Core { grant () } match src = kl.VfsSdCardFs { grant () } } /* Allows task with the kl.bc.BlobContainer class to send response to any task. */ match src = kl.bc.BlobContainer { grant () } }

   Можно вынести разрешения для работы kl.bc.BlobContainer в отдельный .psl файл и подключать его. (см. пример secure_logger в составе SDK).

5. Монтирование файловой системы romfs теперь возможно только в режиме readonly.
   • При монтировании romfs в C/C++ коде с использованием функции mount() нужно передавать флаг MS_RDONLY.
   • Также требуется внести изменения в аргументы командной строки программы VFS в init-описании или в файле CMakeLists.txt для сборки программы Einit.

   Пример монтирования файловой системы romfs в файле init.yaml:

   - name: kl.VfsSdCardFs path: VfsSdCardFs connections: - target: kl.drivers.SDCard id: kl.drivers.SDCard - target: kl.EntropyEntity id: kl.EntropyEntity args: - -l - nodev /tmp ramfs 0 - -l - romfs /etc romfs ro env: ROOTFS: mmc0,0 / fat32 0 VFS_FILESYSTEM_BACKEND: server:kl.VfsSdCardFs

   Пример монтирования файловой системы romfs в файле CMakeLists.txt:

   set (VFS_NET_ARGS " - -l - devfs /dev devfs 0 - -l - romfs /etc romfs ro") set_target_properties (${precompiled_vfsVfsNet} PROPERTIES EXTRA_ARGS ${VFS_NET_ARGS})

[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. На основе описания политики безопасности решения создается модуль безопасности Kaspersky Security Module для использования в конкретном решении.

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

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

Транспортный код генерируется компилятором nk-gen-c на основе формальных спецификаций компонентов решения.

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

Исходный код инициализирующей программы генерируется утилитой einit из init-описания и формальных спецификаций компонентов решения.

[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, соответствующий переданному дескриптору). Модуль безопасности принимает решение и возвращает его поставщику. Поставщик выполняет решение модуля безопасности.

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

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

[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-образа операционной системы Ubuntu GNU/Linux 22.04 "Jammy Jellyfish" из публичного репозитория Docker Hub выполните следующую команду:

   docker pull ubuntu:22.04

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

   docker run --net=host --user root --privileged -it --rm ubuntu:22.04 bash

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

   export PATH=/usr/sbin:$PATH

[Topic sdk_install_and_remove]

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

Установка

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

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

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

Чтобы удобно работать с инструментами, поставляемыми в составе KasperskyOS Community Edition SDK, нужно добавить в переменную окружения PATH путь к исполняемым файлам этих инструментов /opt/KasperskyOS-Community-Edition-<version>/toolchain/bin. Чтобы не делать это каждый раз при входе в пользовательскую сессию, нужно выполнить скрипт /opt/KasperskyOS-Community-Edition-<version>/set_env.sh, выйти и снова войти в сессию.

Синтаксис команды вызова скрипта set_env.sh:

Параметры:

• -d

  Отменяет действие скрипта.

• -h, --help

  Отображает текст справки.

Помимо изменения переменной окружения PATH скрипт задает переменные окружения KOSCEVER и KOSCEDIR, которые содержат версию и абсолютный путь к KasperskyOS Community Edition SDK соответственно. Использование этих переменных окружения позволяет системе сборки при запуске определить путь установки SDK, а также проверить, что версия решения соответствует версии SDK.

Удаление

Перед удалением KasperskyOS Community Edition отмените действие скрипта set_env.sh, если выполняли этот скрипт после установки SDK.

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

В результате выполнения этой команды будут удалены все установленные файлы в директории /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, который включает пример, и инициируется запуск примера на QEMU. Файл образа решения kos-qemu-image сохраняется в директории <название примера>/build/einit.

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

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

Какой образ создается в результате работы скрипта cross-build.sh зависит от выбора значения параметра target:

• kos-image

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

• sd-image

  Создается образ файловой системы загрузочной SD-карты. В образ файловой системы загружаются: образ kos-image, загрузчик U-Boot, который запускает пример, и встроенное программное обеспечение (англ. firmware) для Raspberry Pi 4 B. Исходный код загрузчика U-Boot и встроенное программное обеспечение загружаются с сайта https://github.com. Файл образа файловой системы rpi4kos.img сохраняется в директории <название примера>/build.

[Topic running_sample_programs_qemu]

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

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

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

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

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

[Topic preparing_sd_card_rpi]

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

Коммутация компьютера и 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 или другую аналогичную программу. Настройте параметры следующим образом: bps = 115200, data bits = 8, stop bits = 1, parity = none, flow control = none. Задайте порт USB, через который подключен преобразователь USB-UART, используемый для получения вывода с Raspberry Pi 4 B.

Чтобы компьютер и 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

Если при сборке примера был создан образ rpi4kos.img, то достаточно записать получившийся образ на SD-карту. Для этого подключите SD-карту к компьютеру и выполните следующую команду:

Если при сборке примера был создан образ kos-image, то перед записью образа на SD-карту, её нужно дополнительно подготовить. Загрузочную 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 pv -y $ git clone --depth 1 --branch v2022.01 https://github.com/u-boot/u-boot.git u-boot-armv8 $ cd u-boot-armv8 $ make ARCH=arm CROSS_COMPILE=aarch64-linux-gnu- rpi_4_defconfig $ echo 'CONFIG_SERIAL_PROBE_ALL=y' > ./.custom_config $ echo 'CONFIG_BOOTCOMMAND="fatload mmc 0 ${loadaddr} kos-image; bootelf ${loadaddr} ${fdt_addr}"' >> ./.custom_config $ echo 'CONFIG_PREBOOT="pci enum;"' >> ./.custom_config $ ./scripts/kconfig/merge_config.sh '.config' '.custom_config' $ make ARCH=arm CROSS_COMPILE=aarch64-linux-gnu- u-boot.bin
2. Подготовьте образ с файловой системой для SD-карты.
   # Образ будет содержать boot-раздел на 1 ГБ в fat32 и три раздела по 350 МБ в ext2, ext3 и ext4 соответственно. $ fs_image_name=sdcard.img $ dd if=/dev/zero of=${fs_image_name} bs=1024k count=2048 $ sudo parted ${fs_image_name} mklabel msdos $ loop_device=$(sudo losetup --find --show --partscan ${fs_image_name}) $ sudo parted ${loop_device} mkpart primary fat32 8192s 50% $ sudo parted ${loop_device} mkpart extended 50% 100% $ sudo parted ${loop_device} mkpart logical ext2 50% 67% $ sudo parted ${loop_device} mkpart logical ext3 67% 84% $ sudo parted ${loop_device} mkpart logical ext4 84% 100% $ sudo parted ${loop_device} set 1 boot on $ sudo mkfs.vfat ${loop_device}p1 $ sudo mkfs.ext2 ${loop_device}p5 $ sudo mkfs.ext3 ${loop_device}p6 $ sudo mkfs.ext4 -O ^64bit,^extent ${loop_device}p7
3. Скопируйте загрузчик U-Boot и встроенное программное обеспечение (англ. firmware) для Raspberry Pi 4 B на полученный образ файловой системы, выполнив следующие команды:
   # В следующих командах путь ~/mnt/fat32 используется для примера. # Вы можете использовать другой путь. $ mount_temp_dir=~/mnt/fat32 $ mkdir -p ${mount_temp_dir} $ sudo mount ${loop_device}p1 ${mount_temp_dir} $ git clone --depth 1 --branch 1.20220331 https://github.com/raspberrypi/firmware.git firmware $ sudo cp u-boot.bin ${mount_temp_dir}/u-boot.bin $ sudo cp -r firmware/boot/. ${mount_temp_dir}
4. Заполните конфигурационный файл для загрузчика U-Boot в образе используя следующие команды:
   $ sudo sh -c "echo '[all]' > ${mount_temp_dir}/config.txt" $ sudo sh -c "echo 'arm_64bit=1' >> ${mount_temp_dir}/config.txt" $ sudo sh -c "echo 'enable_uart=1' >> ${mount_temp_dir}/config.txt" $ sudo sh -c "echo 'kernel=u-boot.bin' >> ${mount_temp_dir}/config.txt" $ sudo sh -c "echo 'dtparam=i2c_arm=on' >> ${mount_temp_dir}/config.txt" $ sudo sh -c "echo 'dtparam=i2c=on' >> ${mount_temp_dir}/config.txt" $ sudo sh -c "echo 'dtparam=spi=on' >> ${mount_temp_dir}/config.txt" $ sudo sh -c "echo 'device_tree_address=0x2eff5b00' >> ${mount_temp_dir}/config.txt" $ sudo sh -c "echo 'device_tree_end=0x2f0f5b00' >> ${mount_temp_dir}/config.txt" $ sudo sh -c "echo 'dtoverlay=uart5' >> ${mount_temp_dir}/config.txt" $ sudo umount ${mount_temp_dir} $ sudo losetup -d ${loop_device}
5. Запишите получившийся образ на SD-карту. Для этого подключите SD-карту к компьютеру и выполните следующую команду:
   # В следующей команде [X] – последний символ в имени блочного устройства для SD-карты. $ sudo pv -L 32M ${fs_image_name} | sudo dd bs=64k of=/dev/sd[X] conv=fsync

[Topic running_sample_programs_rpi]

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

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

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

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

[Topic developing]

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

[Topic sc_application_start]

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

[Topic einit_overview]

Обзор: Einit и init.yaml

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

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

• создает и запускает процессы при запуске решения;
• создает IPC-каналы между процессами при запуске решения (статически создает IPC-каналы).

Процесс инициализирующей программы имеет класс Einit.

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

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

Утилита einit генерирует исходный код инициализирующей программы основе init-описания, представляющего собой текстовый файл, который обычно имеет имя init.yaml.

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

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

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

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

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

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

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

[Topic using_einit]

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

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

Запуск клиента и сервера и создание IPC-канала между ними

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

init.yaml

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

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

init.yaml

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

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

init.yaml

Запуск двух серверов одного класса и клиента и создание IPC-каналов между клиентом и серверами

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

init.yaml

Установка параметров запуска и переменных окружения программ

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

init.yaml

[Topic app_static_start]

Запуск процессов с помощью системной программы ExecutionManager

Компонент ExecutionManager предоставляет интерфейс на языке C++ для создания, запуска и остановки процессов в решениях, построенных на базе KasperskyOS.

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

Программный интерфейс компонента ExecutionManager описан в статье "Компонент ExecutionManager".

Сценарий использования компонента ExecutionManager

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

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

1. Добавление программы ExecutionManager в решение. Чтобы добавить ExecutionManager в решение, необходимо:
   • Добавить следующие команды в корневой файл CMakeLists.txt:
   find_package (execution_manager REQUIRED) include_directories (${execution_manager_INCLUDE}) add_subdirectory (execution_manager)

   Для работы программы ExecutionManager необходима программа BlobContainer. Эта программа автоматически добавляется в решение при добавлении ExecutionManager.

   • Компонент ExecutionManager поставляется в составе SDK в виде набора статических библиотек и заголовочных файлов и собирается под конкретное решение с помощью CMake-команды create_execution_manager_entity() из CMake-библиотеки execution_manager.

     Чтобы собрать программу ExecutionManager, необходимо в корневой директории проекта создать директорию с именем execution_manager, а в ней создать файл CMakeLists.txt, в котором содержится команда create_execution_manager_entity().

     CMake-команда create_execution_manager_entity() принимает следующие параметры:

     Обязательный параметр ENTITY, в котором указывается имя исполняемого файла для программы ExecutionManager.

     Опциональные параметры:

     • DEPENDS - дополнительные зависимости для сборки программы ExecutionManager.
     • MAIN_CONN_NAME - имя IPC-канала для соединения с процессом ExecutionManager. Должно совпадать со значением переменной mainConnection при обращении к API ExecutionManager в коде клиента.
     • ROOT_PATH - путь к корневой директории для служебных файлов программы ExecutionManager, по умолчанию "/ROOT".
     • VFS_CLIENT_LIB - имя клиентской транспортной библиотеки для подключения программы ExecutionManager к программе VFS.
   include (execution_manager/create_execution_manager_entity) create_execution_manager_entity( ENTITY ExecMgrEntity MAIN_CONN_NAME ${ENTITY_NAME} ROOT_PATH "/root" VFS_CLIENT_LIB ${vfs_CLIENT_LIB})
   • При сборке решения (файл CMakeLists.txt для программы Einit) добавить следующие исполняемые файлы в образ решения:
     • исполняемый файл программы ExecutionManager;
     • исполняемый файл программы BlobContainer.
2. Компоновка исполняемого файла клиента с клиентской прокси-библиотекой ExecutionManager, для чего необходимо в файле CMakeLists.txt для сборки клиента добавить следующую команду:
   target_link_libraries (<имя CMake-цели для сборки клиента> ${execution_manager_EXECMGR_PROXY})
3. Добавление разрешений для необходимых событий в описание политики безопасности решения:
   1. Чтобы программа ExecutionManager могла запускать другие процессы, политика безопасности решения должна разрешать следующие взаимодействия для класса процессов execution_manager.ExecMgrEntity:
      • События безопасности вида execute для всех классов запускаемых процессов.
      • Доступ ко всем службам программы VFS.
      • Доступ ко всем службам программы BlobContainer.
      • Доступ к службам ядра Sync, Task, VMM, Thread, HAL, Handle, FS, Notice, CM и Profiler (их описания находятся в директории sysroot-*-kos/include/kl/core из состава SDK).
   2. Чтобы клиент мог обращаться к программе ExecutionManager, политика безопасности решения должна разрешать следующие взаимодействия для класса клиентского процесса:
      • Доступ к соответствующим службам программы ExecutionManager (их описания находятся в директории sysroot-*-kos/include/kl/execution_manager из состава SDK).
4. Использование API программы ExecutionManager в коде клиента.

   Для этого необходимо использовать заголовочный файл component/package_manager/kos_ipc/package_manager_proxy.h. Подробнее см. "Компонент ExecutionManager".

[Topic env_overview]

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

Системная программа Env предназначена для установки параметров запуска и переменных окружения программ. Если программа Env включена в решение, то процессы, соединенные IPC-каналом с процессом Env, при своем запуске автоматически отправляют IPC-запросы этой программе и получают параметры запуска и переменные окружения.

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

1. Разработать код программы Env, используя макросы и функции из заголовочного файла sysroot-*-kos/include/env/env.h из состава KasperskyOS SDK.
2. Собрать исполняемый файл программы Env, скомпоновав его с библиотекой env_server из состава KasperskyOS SDK.
3. В init-описании указать, что необходимо запустить процесс Env и соединить с ним другие процессы (Env при этом является сервером). Имя IPC-канала задается макросом ENV_SERVICE_NAME, определенным в заголовочном файле env.h.
4. Включить исполняемый файл Env в образ решения.

Исходный код программы Env

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

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

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

[Topic using_env_app]

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

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

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

env.c

Пример установки переменных окружения программы

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

env.c

[Topic sc_filesystems_and_net]

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

В KasperskyOS работа с файловыми системами и сетью выполняется через отдельную системную программу, реализующую виртуальную файловую систему (англ. Virtual File System, VFS).

В составе SDK компонент VFS представлен набором исполняемых файлов, библиотек, файлов формальной спецификации и заголовочных файлов. Подробнее см. раздел "Состав компонента VFS".

Основной сценарий взаимодействия с системной программой VFS происходит следующим образом:

1. Прикладная программа соединяется IPC-каналом с системной программой VFS и при сборке компонуется с клиентской библиотекой компонента VFS.
2. В прикладном коде POSIX-вызовы для работы с файловыми системами и сетью преобразуются в вызовы функций клиентской библиотеки.

   Ввод и вывод в файловые дескрипторы для стандартных потоков ввода-вывода (stdin, stdout и stderr) также преобразуется в обращения к VFS. Если прикладная программа не скомпонована с клиентской библиотекой компонента VFS, то вывод в stdout невозможен. В таком случае возможен только вывод в стандартный поток ошибок (stderr), который в этом случае осуществляется без использования VFS через специальные методы ядра KasperskyOS.

3. Клиентская библиотека выполняет IPC-запросы к системной программе VFS.
4. Системная программа VFS принимает IPC-запросы и вызывает соответствующие реализации файловых систем (которые, в свою очередь могут выполнять IPC-запросы к драйверам устройств) или сетевые драйверы.
5. После обработки запроса, системная программа VFS выполняет ответы на IPC-запросы прикладной программы.

Использование нескольких программ VFS

В решение можно добавить несколько копий системной программы VFS, разделив таким образом информационные потоки разных системных и прикладных программ. Также можно разделить информационные потоки в рамках одной прикладной программы. Подробнее см. "Разделение информационных потоков с помощью VFS-бэкендов".

Включение функциональности VFS в прикладную программу

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

При этом использование функциональности VFS по IPC позволяет разработчику решения:

• контролировать вызовы методов для работы с сетью и файловыми системами с помощью политики безопасности решения;
• соединить несколько клиентских программ с одной программой VFS;
• соединить одну клиентскую программу с двумя программами VFS для раздельной работы с сетью и файловыми системами.

[Topic vfs_overview]

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

Компонент VFS реализует виртуальную файловую систему. В составе KasperskyOS SDK компонент VFS представлен набором исполняемых файлов, библиотек, файлов формальной спецификации и заголовочных файлов, позволяющих использовать файловые системы и/или сетевой стек.

Библиотеки VFS

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

• vfs_fs – содержит реализации файловых систем devfs, ramfs и ROMFS, а также позволяет добавить в VFS реализации других файловых систем.
• vfs_net – содержит реализацию файловой системы devfs и сетевого стека.
• 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.

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

Файлы формальной спецификации и заголовочные файлы VFS

В директории sysroot-*-kos/include/kl из состава KasperskyOS SDK находятся следующие файлы VFS:

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

API библиотеки libc, поддерживаемый VFS

Функциональность VFS доступна программам через API, предоставляемый библиотекой libc.

Функции, реализуемые библиотеками vfs_fs и vfs_net, приведены в таблицах ниже. Символом * отмечены функции, которые включаются в библиотеку vfs_fs опционально (в зависимости от параметров сборки библиотеки).

Функции, реализуемые библиотекой vfs_fs

Функции, реализуемые библиотекой vfs_net

[Topic client_and_vfs_ipc_channel]

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

В этом примере процесс Client использует файловые системы и сетевой стек, а процесс VfsFsnet обрабатывает IPC-запросы процесса Client, связанные с использованием файловых систем и сетевого стека. Такой подход используется в тех случаях, когда не требуется разделение информационных потоков, связанных с файловыми системами и сетевым стеком.

Имя IPC-канала должно задаваться макросом _VFS_CONNECTION_ID, определенным в заголовочном файле sysroot-*-kos/include/vfs/defs.h из состава KasperskyOS SDK.

Init-описание примера:

init.yaml

[Topic client_and_vfs_linked]

Включение функциональности VFS в программу

В этом примере программа Client включает функциональность программы VFS для работы с сетевым стеком (см. рис. ниже).

Библиотеки компонента VFS в составе программы

Выполняется компиляция файла реализации client.c и компоновка с библиотеками vfs_local, vfs_implementation и dnet_implementation:

CMakeLists.txt

Если бы программа Client использовала файловые системы, то нужно было бы выполнить компоновку с библиотеками vfs_local и vfs_fs, а также с библиотеками реализации этих файловых систем. Кроме того, нужно было бы добавить в решение драйвер блочного устройства.

[Topic vfs_args_and_envs_overview]

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

Параметры запуска программы VFS

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

  Параметр запуска -l монтирует заданную файловую систему.

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

  Параметр -f монтирует файловые системы, указанные в файле fstab. Если переменная окружения UNMAP_ROMFS не определена, то поиск файла fstab будет выполнен в ROMFS-образе. Если переменная окружения UNMAP_ROMFS определена, то поиск файла fstab будет выполнен в файловой системе, заданной через переменную окружения ROOTFS.

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

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

• UNMAP_ROMFS

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

  Пример использования переменной окружения UNMAP_ROMFS

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

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

  Пример использования переменной окружения ROOTFS

• VFS_CLIENT_MAX_THREADS

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

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

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

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

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

Значения по умолчания для параметров запуска и переменных окружения VFS

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

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

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

[Topic mount_on_start]

Монтирование файловых систем при запуске VFS

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

Использование параметра запуска -l

Одним из способов монтировать файловую систему является установка для программы VFS параметра запуска -l <запись в формате fstab>.

В этих примерах при запуске программы VFS будут монтированы файловые системы devfs и ROMFS:

init.yaml.(in)

CMakeLists.txt

Использование файла fstab из ROMFS-образа

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

В этих примерах при запуске программы VFS будут монтированы файловые системы, заданные через файл fstab, который был добавлен при сборке решения в ROMFS-образ:

init.yaml.(in)

CMakeLists.txt

Использование "внешнего" файла fstab

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

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

В этих примерах при запуске программы VFS в корневую директорию будет монтирована файловая система ext2, в которой должен находиться файл fstab по пути /etc/fstab:

init.yaml.(in)

CMakeLists.txt

[Topic client_and_two_vfs]

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

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

Процесс Client использует файловые системы и сетевой стек. Процесс VfsFirst обеспечивает работу с файловыми системами, а процесс VfsSecond дает возможность работать с сетевым стеком. Через переменные окружения программ, исполняющихся в контекстах процессов Client, VfsFirst и VfsSecond, заданы VFS-бэкенды, которые обеспечивают раздельное использование файловых систем и сетевого стека. В результате этого IPC-запросы процесса Client, связанные с использованием файловых систем, обрабатываются процессом VfsFirst, а IPC-запросы процесса Client, связанные с использованием сетевого стека, обрабатываются процессом VfsSecond (см. рис. ниже).

Схема взаимодействия процессов

Init-описание примера:

init.yaml

[Topic vfs_backends]

Создание VFS-бэкенда

В этом примере показано, как создать и использовать собственный VFS-бэкенд.

Процесс Client использует файловые системы fat32 и ext4. Процесс VfsFirst обеспечивает работу с файловой системой fat32, а процесс VfsSecond дает возможность работать с файловой системой ext4. Через переменные окружения программ, исполняющихся в контекстах процессов Client, VfsFirst и VfsSecond, заданы VFS-бэкенды, которые обеспечивают обработку IPC-запросов процесса Client процессом VfsFirst или VfsSecond в зависимости от того, какую файловую систему использует процесс Client. В результате этого IPC-запросы процесса Client, связанные с использованием файловой системы fat32, обрабатываются процессом VfsFirst, а IPC-запросы процесса Client, связанные с использованием файловой системы ext4, обрабатываются процессом VfsSecond (см. рис. ниже).

На стороне процесса VfsFirst файловая система fat32 монтируется в директорию /mnt1. На стороне процесса VfsSecond файловая система ext4 монтируется в директорию /mnt2. Пользовательский VFS-бэкенд custom_client, используемый на стороне процесса Client, позволяет отправлять IPC-запросы по IPC-каналу VFS1 или VFS2 в зависимости от того, начинается ли путь к файлу с /mnt1 или нет. При этом пользовательский VFS-бэкенд использует в качестве посредника стандартный VFS-бэкенд client.

Схема взаимодействия процессов

Исходный код VFS-бэкенда

Этот файл реализации содержит исходный код VFS-бэкенда custom_client, использующего стандартные VFS-бэкенды client:

backend.c

Компоновка программы Client

Создание статической библиотеки VFS-бэкенда:

CMakeLists.txt

Компоновка программы Client со статической библиотеки VFS-бэкенда:

CMakeLists.txt

Установка параметров запуска и переменных окружения программ

Init-описание примера:

init.yaml

[Topic vfs_net_stack_dyn_conf]

Динамическая настройка сетевого стека

Чтобы изменить параметры сетевого стека, заданные по умолчанию, нужно использовать функцию sysctl() или sysctlbyname(), объявленные в заголовочном файле sysroot-*-kos/include/sys/sysctl.h из состава KasperskyOS SDK. Параметры, которые можно изменить, приведены в таблице ниже.

Настраиваемые параметры сетевого стека

Пример настройки MSS:

[Topic sc_using_ipc]

IPC и транспорт

[Topic ipc_channels]

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

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

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

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

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

Статическое создание IPC-каналов имеет следующие особенности:

• Клиент и сервер еще не запущены в момент создания IPC-канала.
• Создание IPC-канала выполняется родительским процессом, запускающим клиента и сервера (обычно это Einit).
• В случае удаления IPC-канал невозможно восстановить.
• Чтобы получить IPC-дескриптор и идентификатор службы (riid) после создания IPC-канала, клиент и сервер должны использовать API, определенный в заголовочном файле sysroot-*-kos/include/coresrv/sl/sl_api.h из состава KasperskyOS SDK.

Статически создаются IPC-каналы, заданные в init-описании.

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

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

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

[Topic using_sdk_endpoints_examples]

Добавление в решение службы из состава KasperskyOS Community Edition

Чтобы программа 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-сообщения определяются IDL-описаниями серверов.

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

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

Фиксированная часть IPC-сообщения содержит RIID, MID и опционально параметры интерфейсных методов фиксированного размера.

Параметры фиксированного размера – это параметры, которые имеют IDL-типы фиксированного размера.

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

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

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

Арена IPC-сообщения

Арена IPC-сообщения (далее также арена) содержит параметры интерфейсных методов (и/или элементы этих параметров) переменного размера.

Параметры переменного размера – это параметры, которые имеют IDL‑типы переменного размера.

Подробнее см. "Работа с ареной IPC-сообщений".

Максимальный размер IPC-сообщения

Максимальный размер IPC-сообщения определяется параметрами ядра KasperskyOS. На большинстве поддерживаемых KasperskyOS аппаратных платформ совокупный размер фиксированной части и арены IPC-сообщения не может превышать 4, 8 или 16 МБ.

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

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

Реализация IPC-взаимодействия

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

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

Реализация простейшего 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.

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

[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 ipc_arena]

Работа с ареной IPC-сообщений

Общие сведения об арене

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

Через IPC передается только использованная часть арены, то есть занятая данными. (При отсутствии данных арена не передается.) Использованная часть арены включает один или несколько участков. В одном участке арены хранится массив объектов одного типа, например, массив однобайтовых объектов или массив структур. В разных участках арены могут храниться массивы объектов разного типа. Адрес начала арены должен быть выравнен на границу 2^N-байтовой последовательности, где 2^N – значение, которое больше либо равно размеру наибольшего примитивного типа в арене (например, наибольшего поля примитивного типа в структуре). Адрес участка арены также должен быть выравнен на границу 2^N-байтовой последовательности, где 2^N – значение, которое больше либо равно размеру наибольшего примитивного типа в участке арены.

Необходимость наличия нескольких участков в арене возникает, если интерфейсный метод имеет несколько входных, выходных или error-параметров переменного размера, а также если несколько элементов входных, выходных или error-параметров интерфейсного метода имеют переменный размер. Например, если интерфейсный метод имеет входной параметр IDL-типа sequence и входной параметр IDL-типа bytes, то в арене IPC-запросов будет как минимум два участка, но могут потребоваться и дополнительные участки, если параметр IDL-типа sequence состоит из элементов IDL-типа переменного размера (например, string, то есть элементами последовательности являются строковые буферы). Также, к примеру, если интерфейсный метод имеет один выходной параметр IDL-типа struct, который содержит два поля типа bytes и string, то в арене IPC-ответов будет два участка.

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

API для работы с ареной

Набор функций и макросов для работы с ареной определен в заголовочном файле sysroot-*-kos/include/nk/arena.h из состава KasperskyOS SDK. Также функция для копирования строки в арену объявлена в заголовочном файле sysroot-*-kos/include/coresrv/nk/transport-kos.h из состава KasperskyOS SDK.

Сведения о функциях и макросах, определенных в заголовочном файле sysroot-*-kos/include/nk/arena.h, приведены в таблице ниже. В этих функциях и макросах арена и участок арены идентифицируются дескриптором арены (тип nk_arena) и дескриптором участка арены (тип nk_ptr_t) соответственно. Дескриптор арены представляет собой структуру, содержащую три указателя: на начало арены, на начало неиспользованной части арены и на конец арены. Дескриптор участка арены представляет собой структуру, содержащую смещение участка арены в байтах (относительно начала арены) и размер участка арены в байтах. (Тип дескриптора участка арены определен в заголовочном файле sysroot-*-kos/include/nk/types.h. из состава KasperskyOS SDK.)

Создание арены

Чтобы передавать через IPC параметры интерфейсных методов переменного размера, нужно создать арены как на стороне клиента, так и на стороне сервера. (При обработке IPC-запросов на стороне сервера с использованием функции NkKosDoDispatch(), определенной в заголовочном файле sysroot-*-kos/include/coresrv/nk/transport-kos-dispatch.h из состава KasperskyOS SDK, арены IPC-запросов и IPC-ответов создаются автоматически.)

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

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

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

• макрос NK_ARENA_INITIALIZER();
• функцию nk_arena_init();
• функцию nk_arena_create();
• макрос NK_ARENA_FINAL();
• макрос nk_arena_init_final().

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

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

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

Размер арены должен быть достаточен, чтобы с учетом выравнивания адресов участков вместить параметры переменного размера для IPC-запросов или IPC-ответов одного интерфейсного метода или множества интерфейсных методов, соответствующих одному интерфейсу, компоненту или классу процессов. Автоматически генерируемый транспортный код (заголовочные файлы *.idl.h, *.cdl.h, *.edl.h) содержит константы *_arena_size, значения которых гарантированно соответствуют достаточным размерам арен в байтах.

Заголовочные файлы *.idl.h, *.cdl.h, *.edl.h содержат следующие константы *_arena_size:

• <имя интерфейса>_<имя интерфейсного метода>_req_arena_size – размер арены IPC-запросов для указанного интерфейсного метода указанного интерфейса;
• <имя интерфейса>_<имя интерфейсного метода>_res_arena_size – размер арены IPC-ответов для указанного интерфейсного метода указанного интерфейса;
• <имя интерфейса>_req_arena_size – размер арены IPC-запросов для любого интерфейсного метода указанного интерфейса;
• <имя интерфейса>_res_arena_size – размер арены IPC-ответов для любого интерфейсного метода указанного интерфейса.

Заголовочные файлы *.cdl.h, *.edl.h дополнительно содержат следующие константы *_arena_size:

• <имя компонента>_component_req_arena_size – размер арены IPC-запросов для любого интерфейсного метода указанного компонента;
• <имя компонента>_component_res_arena_size – размер арены IPC-ответов для любого интерфейсного метода указанного компонента.

Заголовочные файлы *.edl.h дополнительно содержат следующие константы *_arena_size:

• <имя класса процессов>_entity_req_arena_size – размер арены IPC-запросов для любого интерфейсного метода указанного класса процессов;
• <имя класса процессов>_entity_res_arena_size – размер арены IPC-ответов для любого интерфейсного метода указанного класса процессов.

Константы, содержащие размер арены IPC-запросов или IPC-ответов для одного интерфейсного метода (<имя интерфейса>_<имя интерфейсного метода>_req_arena_size и <имя интерфейса>_<имя интерфейсного метода>_res_arena_size), предназначены для использования на стороне клиента. Остальные константы могут использоваться как на стороне клиента, так и на стороне сервера.

Примеры создания арены:

Заполнение арены данными перед передачей через IPC

Перед передачей IPC-запроса на стороне клиента или IPC-ответа на стороне сервера арену нужно заполнить данными. Если для создания арены используется макрос NK_ARENA_FINAL() или nk_arena_init_final(), то резервировать участок арены не требуется, а нужно только заполнить этот участок данными. Если для создания арены используется макрос NK_ARENA_INITIALIZER() или NK_ARENA_AUTO() либо функция nk_arena_init() или nk_arena_create(), то в арене необходимо зарезервировать один или несколько участков, чтобы поместить в них данные. Чтобы зарезервировать участок арены, нужно использовать функцию или макрос API:

• функцию __nk_arena_alloc();
• макрос nk_arena_store();
• функцию __nk_arena_store();
• макрос nk_arena_alloc();
• функцию NkKosCopyStringToArena().

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

Макрос nk_arena_store() и функции __nk_arena_store() и NkKosCopyStringToArena() не только резервируют участок арены, но и копируют данные в этот участок.

Макрос nk_arena_alloc() позволяет получить адрес зарезервированного участка арены. Также адрес участка арены можно получить, используя функцию __nk_arena_get() или макрос nk_arena_get(), которые дополнительно через выходной параметр передают размер арены.

Зарезервированный участок арены можно уменьшить. Для этого нужно использовать макрос nk_arena_shrink() или функцию _nk_arena_shrink().

Чтобы отменить текущее резервирование участков арены для последующего резервирования новых участков под другие данные (после отправки IPC-сообщения), нужно вызвать функцию nk_arena_reset(). Если для создания арены используется макрос NK_ARENA_FINAL() или nk_arena_init_final(), то отменять резервирование участка не требуется, так как такая арена на протяжении всего своего жизненного цикла содержит один участок, занимающий всю арену.

Примеры заполнения арены данными:

Получение данных из арены после приема через IPC

Перед получением IPC-запроса на стороне сервера или IPC-ответа на стороне клиента для арены, в которую будут помещены полученные через IPC-данные, нужно отменить текущее резервирование участков, вызвав функцию nk_arena_reset(). Это требуется сделать, даже если для создания арены используется макрос NK_ARENA_FINAL() или nk_arena_init_final(). (Макросы NK_ARENA_INITIALIZER() и NK_ARENA_AUTO(), а также функции nk_arena_init() и nk_arena_create() создают арену без зарезервированных участков. Перед однократном использовании такой арены для сохранения полученных через IPC данных вызывать функцию nk_arena_reset() не требуется.)

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

Пример получения данных из арены:

Дополнительные возможности API

Чтобы получить размер арены, нужно вызвать функцию nk_arena_capacity().

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

Чтобы проверить, является ли корректным дескриптор участка арены, нужно использовать макрос nk_arena_validate() или функцию __nk_arena_validate().

Сведения о функциях и макросах API

Функции и макросы arena.h

[Topic cpp_proxy_stubs]

Транспортный код на языке C++

Чтобы реализовать взаимодействие процессов, необходим транспортный код, отвечающий за формирование, отправку, прием и обработку IPC-сообщений.

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

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

Для генерации транспортного кода на языке C++ в составе KasperskyOS SDK поставляется компилятор nkppmeta.

Компилятор nkppmeta позволяет генерировать транспортные C++ прокси-объекты (proxy) и стабы (stub) для использования как клиентом, так и сервером.

Прокси-объекты используются клиентом для упаковки параметров вызываемого метода в IPC-запрос, выполнения IPC-запроса и распаковки IPC-ответа.

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

Генерация транспортного кода для разработки на C++

Для генерации транспортных прокси-объектов и стабов с помощью генератора nkppmeta при сборке решения используются CMake-команды add_nk_idl(), add_nk_cdl() и add_nk_edl().

Типы С++ в файле *.idl.cpp.h

Каждый интерфейс определяется в IDL-описании. Это описание задает имя интерфейса, сигнатуры интерфейсных методов и типы данных для параметров интерфейсных методов.

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

Генерируемые заголовочные файлы содержат представление на языке C++ для интерфейса и типов данных, описанных в IDL-файле, а также методы, необходимые для использования прокси-объектов и стабов.

Соответствие типов данных, объявленных в IDL-файле, типам C++ приведены в таблице ниже.

Соответствие типов IDL типам C++

Работа с транспортным кодом на C++

Сценарии разработки клиента и сервера, которые обмениваются IPC-сообщениями, представлены в разделах "Статическое создание IPC-каналов при разработке на языке C++" и "Динамическое создание IPC-каналов при разработке на языке C++"

[Topic static_IPC_kosipc]

Статическое создание IPC-каналов при разработке на языке C++

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

1. Подключить сгенерированный заголовочный файл описания (*.edl.cpp.h) клиентской программы.
2. Подключить сгенерированные заголовочные файлы описаний используемых интерфейсов (*.idl.cpp.h).
3. Подключить заголовочные файлы:
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/application.h
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/api.h
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/connect_static_channel.h
4. Инициализировать объект приложения, вызвав функцию kosipc::MakeApplicationAutodetect(). (Также можно использовать функции kosipc::MakeApplication() и kosipc::MakeApplicationPureClient().)
5. Получить клиентский IPC-дескриптор канала и идентификатор службы (riid) вызвав функцию kosipc::ConnectStaticChannel().

   Функция принимает имя IPC-канала (из файла init.yaml) и квалифицированное имя службы (из CDL- и EDL-описаний компонента решения).

6. Инициализировать прокси-объект для используемой службы, вызвав функцию MakeProxy().

Пример

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

1. Подключить сгенерированный заголовочный файл *.edl.cpp.h, содержащий описание компонентной структуры программы, включая все предоставляемые службы.
2. Подключить заголовочные файлы:
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/event_loop.h
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/api.h
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/serve_static_channel.h
3. Создать классы, содержащие реализации интерфейсов, которые данная программа и её компоненты предоставляют в виде служб.
4. Инициализировать объект приложения, вызвав функцию kosipc::MakeApplicationAutodetect().
5. Инициализировать структуру kosipc::components::Root, которая описывает компонентную структуру программы и описания интерфейсов всех предоставляемых программой служб.
6. Связать поля структуры kosipc::components::Root с объектами, реализующими соответствующие службы.

   Поля структуры Root повторяют иерархию компонентов и служб, заданную совокупностью CDL- и EDL-файлов.

7. Получить серверный IPC-дескриптор канала, вызвав функцию ServeStaticChannel().

   Функция принимает имя IPC-канала (из файла init.yaml) и структуру, созданную на шаге 5.

8. Создать объект kosipc::EventLoop, вызвав функцию MakeEventLoop().
9. Запустить цикл диспетчеризации входящих IPC-сообщений, вызвав метод Run() объекта kosipc::EventLoop.

Пример

[Topic dynamic_IPC_kosipc]

Динамическое создание IPC-каналов при разработке на языке C++

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

1. Подключить к клиентской программе сгенерированный заголовочный файл описания (*.edl.cpp.h).
2. Подключить сгенерированные заголовочные файлы описаний используемых интерфейсов (*.idl.cpp.h).
3. Подключить заголовочные файлы:
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/application.h
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/make_application.h
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/connect_dynamic_channel.h
4. Получить указатели на имя сервера и квалифицированное имя службы с помощью сервера имен – специального сервиса ядра, представленного программой NameServer. Для этого необходимо подключиться к серверу имен вызовом функции NsCreate() и найти сервер, предоставляющий требуемую службу, используя функцию NsEnumServices(). Подробнее см. "Динамическое создание IPC-каналов (cm_api.h, ns_api.h)".
5. Создать объект приложения, вызвав функцию kosipc::MakeApplicationAutodetect(). (Также можно использовать функции kosipc::MakeApplication() и kosipc::MakeApplicationPureClient().)
6. Создать прокси-объект для требуемой службы, вызвав функцию MakeProxy(). В качестве входного параметра функции MakeProxy() использовать вызов функции kosipc::ConnectDynamicChannel(). В функцию kosipc::ConnectDynamicChannel() передать указатели на имя сервера и квалифицированное имя службы, полученные на шаге 4.

После успешной инициализации прокси-объекта клиенту доступен вызов методов требуемой службы.

Пример

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

1. Подключить к серверной программе сгенерированный заголовочный файл (*.edl.cpp.h), содержащий описание компонентной структуры сервера, включая все предоставляемые службы.
2. Подключить заголовочные файлы:
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/application.h
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/event_loop.h
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/make_application.h
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/root_component.h
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/serve_dynamic_channel.h
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/simple_connection_acceptor.h
3. Создать классы, содержащие реализации интерфейсов, которые сервер предоставляет в виде служб. Создать и инициализировать объекты этих классов.
4. Создать объект приложения, вызвав функцию kosipc::MakeApplicationAutodetect().
5. Создать и инициализировать объект класса kosipc::components::Root, который описывает структуру компонентов и служб сервера. Эта структура генерируется из описаний в CDL- и EDL-файлах.
6. Cвязать объект класса kosipc::components::Root с объектами классов, созданными на шаге 3.
7. Создать и инициализировать объект класса kosipc::EventLoop, который реализует цикл диспетчеризации входящих IPC-сообщений, вызвав функцию MakeEventLoop(). В качестве входного параметра функции MakeEventLoop() использовать вызов функции ServeDynamicChannel(). В функцию ServeDynamicChannel() передать объект класса kosipc::components::Root, созданный на шаге 5.
8. Запустить цикл диспетчеризации входящих IPC-сообщений в отдельном потоке, вызвав метод Run() объекта kosipc::EventLoop.
9. Создать и инициализировать объект, который реализует обработчик приема входящих запросов на динамическое создание IPC-канала.

   При создании объекта можно использовать класс kosipc::SimpleConnectionAcceptor, который является стандартной реализацией интерфейса kosipc::IConnectionAcceptor. (Интерфейс kosipc::IConnectionAcceptor определен в файле /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/connection_acceptor.h.) В этом случае обработчик будет реализовать следующую логику: если запрашиваемая клиентом служба опубликована на сервере, то запрос от клиента будет принят, иначе отклонен.

   Если необходимо создать собственный обработчик, то следует реализовать свою логику обработки запросов в методе OnConnectionRequest(), унаследованном от интерфейса kosipc::IConnectionAcceptor. Этот метод будет вызываться сервером при получении от клиента запроса на динамическое создание IPC-канала.

10. Создать объект класса kosipc::EventLoop, который реализует цикл приема входящих запросов на динамическое создание IPC-канала, вызвав функцию MakeEventLoop(). В качестве входного параметра функции MakeEventLoop() использовать вызов функции ServeConnectionRequests(). В функцию ServeConnectionRequests() передать объект, созданный на шаге 9.

    Цикл приема входящих запросов на динамическое создание IPC-канала может быть только один. Цикл должен работать в одном потоке. Цикл приема входящих запросов на динамическое создание IPC-канала должен быть создан после создания цикла диспетчеризации входящих IPC-сообщений (см. на шаг 7).

11. Запустить цикл приема входящих запросов на динамическое соединение в текущем потоке, вызвав метод Run() объекта kosipc::EventLoop.

Пример

При необходимости можно создать и инициализировать несколько объектов класса kosipc::components::Root, объединенных в список объектов типа ServiceList с помощью метода AddServices(). Использование нескольких объектов позволяет, например, разделять компоненты и службы сервера на группы или публиковать службы под разными именами.

Пример

[Topic api]

KasperskyOS API

[Topic return_codes]

Коды возврата

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

В решении на базе KasperskyOS коды возврата функций различных API (например, API библиотек libkos и kdf, драйверов, транспортного кода, прикладного ПО) имеют тип 32-битного знакового целого числа. Этот тип определен в заголовочном файле sysroot-*-kos/include/rtl/retcode.h из состава KasperskyOS SDK так:

Множество кодов возврата состоит из кода успеха со значением 0 и кодов ошибок. Код ошибки интерпретируется как структура данных, формат которой описан в заголовочном файле sysroot-*-kos/include/rtl/retcode.h из состава KasperskyOS SDK. Этот формат предусматривает наличие нескольких полей, которые содержат не только сведения о результатах вызова функции, но и следующую дополнительную информацию:

• Флаг в поле Customer, сигнализирующий о том, что код ошибки определен разработчиками решения на базе KasperskyOS, а не разработчиками ПО из состава KasperskyOS SDK.

  Благодаря флагу в поле Customer разработчики решения на базе KasperskyOS и разработчики ПО из состава KasperskyOS SDK могут определять коды ошибок из непересекающихся множеств.

• Глобальный идентификатор кода ошибки в поле Space.

  Глобальные идентификаторы позволяют определять непересекающиеся множества кодов ошибок. Коды ошибок могут быть общими и специфичными. Общие коды ошибок могут использоваться в API любых компонентов решения и в API любых составных частей компонентов решения (например, драйвер или VFS могут быть составной частью компонента решения). Специфичные коды ошибок используются в API одного или нескольких компонентов решения или в API одной или нескольких составных частей компонентов решения.

  Например, идентификатору RC_SPACE_GENERAL соответствуют коды общих ошибок, идентификатору RC_SPACE_KERNEL соответствуют коды ошибок ядра, идентификатору RC_SPACE_DRIVERS соответствуют коды ошибок драйверов.

• Локальный идентификатор кода ошибки в поле Facility.

  Локальные идентификаторы позволяют определять непересекающиеся подмножества кодов ошибок в рамках множества кодов ошибок, которые соответствуют одному глобальному идентификатору. Например, множество кодов ошибок с глобальным идентификатором RC_SPACE_DRIVERS включает непересекающиеся подмножества кодов ошибок с локальными идентификаторами RC_FACILITY_I2C, RC_FACILITY_USB, RC_FACILITY_BLKDEV.

Глобальные и локальные идентификаторы специфичных кодов ошибок назначаются разработчиками решения на базе KasperskyOS и разработчиками ПО из состава KasperskyOS SDK независимо друг от друга. То есть формируется два множества глобальных идентификаторов. Каждый глобальный идентификатор имеет уникальное смысловое значение в рамках одного множества. Каждый локальный идентификатор имеет уникальное смысловое значение в рамках множества локальных идентификаторов, относящихся к одному глобальному идентификатору. Общие коды ошибок могут использоваться в любых API.

Такой централизованный подход позволяет избежать появления в решении на базе KasperskyOS одинаковых кодов ошибок с разными смысловыми значениями. Это нужно, чтобы исключить проблему транзита кодов ошибок через разные API. Например, такая проблема возникает, когда драйверы вызывают функции библиотеки kdf, получают коды ошибок и возвращают эти коды через свои API. Если формировать коды ошибок без централизованного подхода, то один и тот же код ошибки может иметь разные смысловые значения для библиотеки kdf и для драйвера. В таких условиях драйверы возвращают корректные коды ошибок, если только выполняется преобразование кодов ошибок библиотеки kdf в коды ошибок каждого из драйверов. То есть коды ошибок в решении на базе KasperskyOS назначаются так, чтобы не выполнять конвертацию этих кодов при транзите через разные API.

Общие коды возврата

Коды возврата, которые являются общими для API любых компонентов решения и их составных частей, определены в заголовочном файле sysroot-*-kos/include/rtl/retcode.h из состава KasperskyOS SDK. Описание общих кодов возврата приведено в таблице ниже.

Общие коды возврата

Определение кодов ошибок

Чтобы определить код ошибки, разработчику решения на базе KasperskyOS нужно использовать макрос MAKE_RETCODE(), определенный в заголовочном файле sysroot-*-kos/include/rtl/retcode.h из состава KasperskyOS SDK. При этом через параметр customer нужно передать символьную константу RC_CUSTOMER_TRUE.

Пример:

Чтение полей структуры кода ошибки

Макросы RC_GET_CUSTOMER(), RC_GET_SPACE(), RC_GET_FACILITY() и RC_GET_CODE(), определенные в заголовочном файле sysroot-*-kos/include/rtl/retcode.h из состава KasperskyOS SDK, позволяют читать поля структуры кода ошибки.

Макросы RETCODE_HR_PARAMS() и RETCODE_HR_FMT(), определенные в заголовочном файле sysroot-*-kos/include/rtl/retcode_hr.h из состава KasperskyOS SDK, используются для форматированного вывода сведений об ошибке.

[Topic libkos]

Библиотека libkos

Библиотека libkos является базовой библиотекой KasperskyOS, предоставляющей набор API, через которые программы и другие библиотеки (например, libc, kdf) используют службы ядра. API, предоставляемые библиотекой libkos, обеспечивают для разработчиков решения следующие возможности:

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

Этот раздел содержит подробные описания работы с некоторыми интерфейсами библиотеки libkos. Описания остальных интерфейсов вы можете найти в соответствующих им заголовочных файлах.

Заголовочные файлы, определяющие API библиотеки libkos, расположены в следующих директориях:

• sysroot-*-kos/include/coresrv/
• sysroot-*-kos/include/kos/

[Topic handles_manage]

Управление дескрипторами (handle_api.h)

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

API предназначен для выполнения операций с дескрипторами. Дескрипторы имеют тип Handle, который определен в заголовочном файле sysroot-*-kos/include/handle/handletype.h из состава KasperskyOS SDK.

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

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

[Topic libkos_handles_rights]

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

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

При создании дескриптора системного ресурса маска прав задается ядром KasperskyOS, которое применяет маски прав из заголовочного файла 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 libkos_handles_create]

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

Создание дескрипторов системных ресурсов

Дескрипторы системных ресурсов создаются при создании этих ресурсов, например, при регистрации прерывания или региона памяти MMIO, создании буфера DMA, потока исполнения или процесса.

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

Дескрипторы пользовательских ресурсов создаются поставщиками ресурсов с использованием функции KnHandleCreateUserObject() или KnHandleCreateUserObjectEx().

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

Через параметр rights нужно задать маску прав дескриптора.

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

IPC-дескриптор (англ. IPC handle) – это дескриптор, который идентифицирует IPC-канал. IPC-дескрипторы используются для выполнения системных вызовов. Клиентский IPC-дескриптор нужен для выполнения системного вызова Call(). Серверный IPC-дескриптор требуется для выполнения системных вызовов Recv() и Reply(). Серверный IPC-дескриптор, который имеет расширенные права, позволяющие добавлять IPC-каналы в набор идентифицируемых этим дескриптором IPC-каналов, называется слушающим дескриптором (англ. listener handle). Клиентский IPC-дескриптор, который идентифицирует одновременно IPC-канал до сервера и службу этого сервера, называется callable-дескриптором (англ. callable handle).

Сервер создает callable-дескриптор и передает его клиенту, чтобы клиент мог использовать службу сервера. Клиент инициализирует IPC-транспорт, используя полученный callable-дескриптор. При этом в функции инициализации прокси-объекта клиент указывает значение INVALID_RIID в качестве идентификатор службы (RIID). Чтобы создать callable-дескриптор, нужно вызвать функцию KnHandleCreateUserObjectEx(), указав в параметрах ipcChannel и riid серверный IPC-дескриптор и идентификатор службы (RIID) соответственно. Через параметр context можно задать данные для ассоциации с callable-дескриптором. Сервер сможет получить указатель на эти данные при разыменовании callable-дескриптора. (Несмотря на то что callable-дескриптор является IPC-дескриптором, он помещается ядром в поле base_.self фиксированной части IPC-запроса.)

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

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

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

Чтобы создать клиентский IPC-дескриптор для обращения к модулю безопасности Kaspersky Security Module через интерфейс безопасности, нужно вызвать функцию KnHandleSecurityConnect(). Эта функция вызывается библиотекой libkos при инициализации IPC-транспорта для обращения к модулю безопасности.

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

Функции handle_api.h

[Topic libkos_handles_transfer]

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

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

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

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

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

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

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

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

В IDL-описании сигнатуры интерфейсных методов для передачи дескрипторов имеют входные (in) и/или выходные (out) параметры типа Handle или array с элементами типа Handle. Через входные параметры одного метода можно передать до 255 дескрипторов. Столько же дескрипторов можно получить через выходные параметры.

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

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

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

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

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

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

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

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

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

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

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

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

Чтобы упаковать дескриптор, маску прав дескриптора и дескриптор объекта контекста передачи ресурса в транспортный контейнер дескриптора, нужно использовать макрос nk_handle_desc(), который определен в заголовочном файле sysroot-*-kos/include/nk/types.h из состава KasperskyOS SDK. Этот макрос принимает переменное число параметров.

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

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

Чтобы извлечь дескриптор, маску прав дескриптора и указатель на контекст передачи ресурса из транспортного контейнера дескриптора, нужно использовать соответственно функции nk_get_handle(), nk_get_rights() и nk_get_badge_op() (или nk_get_badge()), которые определены в заголовочном файле sysroot-*-kos/include/nk/types.h из состава KasperskyOS SDK. Функции nk_get_badge_op() и nk_get_badge() нужно использовать только при разыменовании дескрипторов.

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

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

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

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

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

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

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

Функции handle_api.h

[Topic libkos_handle_copy]

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

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

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

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

Функции handle_api.h

[Topic libkos_handles_dereference]

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

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

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

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

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

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

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

[Topic libkos_handles_revoke]

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

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

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

Чтобы отозвать потомков дескриптора, нужно вызвать функцию KnHandleRevoke() или KnHandleRevokeSubtree(). Функция KnHandleRevokeSubtree() использует объект контекста передачи ресурса, который создается при передаче дескрипторов.

Если каждый из дескрипторов системного ресурса во всех процессах, которые владеют этими дескрипторами, будет закрыт (см. "Закрытие дескрипторов") или отозван, то этот системный ресурс будет удален.

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

Функции handle_api.h

[Topic libkos_handles_delete]

Закрытие дескрипторов

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

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

Если каждый из дескрипторов системного ресурса во всех процессах, которые владеют этими дескрипторами, будет отозван (см. "Отзыв дескрипторов") или закрыт, то этот системный ресурс будет удален.

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

Функции handle_api.h

[Topic libkos_handle_get_sid]

Получение идентификатора безопасности (SID)

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

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

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

Функции 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_alloc_api]

Выделение и освобождение памяти (alloc.h)

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

API предназначен для выделения и освобождения памяти. Выделенная память представляет собой зафиксированный регион виртуальной памяти, к которому разрешен доступ на чтение и запись.

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

Функции alloc.h

[Topic libkos_dma_api]

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

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

API предназначен для организации обмена данными между устройствами и оперативной памятью в режиме прямого доступа к памяти (англ. Direct Memory Access, DMA), при котором процессор не используется.

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

Использование API

Типовой сценарий использования API включает следующие шаги:

1. Создание буфера DMA.

   Буфер DMA –это буфер, состоящий из одного или нескольких регионов физической памяти (блоков), используемых для DMA. Буфер DMA, состоящий из нескольких блоков, можно использовать, если устройство поддерживает режим "scatter/gather DMA". Буфер DMA, состоящий из одного блока, можно использовать, если устройство поддерживает режим "scatter/gather DMA" или "continuous DMA". Вероятность создать буфер DMA, состоящий из одного большого блока, ниже, чем вероятность создать буфер DMA, состоящий из нескольких небольших блоков. Это особенно актуально при высокой фрагментации физической памяти.

   Если устройство поддерживает только режим "continuous DMA", то даже при задействовании IOMMU нужно использовать буфер DMA, состоящий из одного блока.

   Чтобы выполнить этот шаг, нужно вызвать функцию KnIoDmaCreate() или KnIoDmaCreateContinuous(). Функция KnIoDmaCreateContinuous() создает буфер DMA, состоящий из одного блока. Функция KnIoDmaCreate() создает буфер DMA, состоящий из одного блока, если значение 2^order равно значению size/размер страницы памяти, или значение 2^order является ближайшим большим к значению size/размер страницы памяти в упорядоченном по возрастанию множестве {2^(order-1);size/размер страницы памяти;2^order}. Если значение size/размер страницы памяти больше значения 2^order, функция KnIoDmaCreate() может создать буфер DMA, состоящий из нескольких блоков.

   Дескриптор буфера DMA можно передать другому процессу через IPC.

2. Отображение буфера DMA на память процессов.

   Один буфер DMA может быть отображен на несколько регионов виртуальной памяти одного или нескольких процессов, которые владеют дескриптором этого буфера DMA. В результате отображения процессы получают доступ к буферу DMA на чтение и/или запись.

   Чтобы зарезервировать регион виртуальной памяти и отобразить на него буфер DMA, нужно вызвать функцию KnIoDmaMap().

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

3. Открытие доступа к буферу DMA для устройства вызовом функции KnIoDmaBegin().

   Вызов функции KnIoDmaBegin() необходим, чтобы создать объект ядра, содержащий адреса и размеры блоков, из которых состоит буфер DMA. Эти сведения необходимы устройству, чтобы использовать буфер DMA. Устройство может работать как с физическими, так и с виртуальными адресами в зависимости от того, задействован ли IOMMU. Если IOMMU задействован, объект содержит виртуальные адреса блоков. В противном случае объект содержит физические адреса блоков.

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

4. Получение сведений о буфере DMA.

   На этом шаге нужно получить адреса и размеры блоков из объекта ядра, созданного вызовом функции KnIoDmaBegin(). Полученные адреса и размеры в дальнейшем требуется передать устройству, используя, например, MMIO. После получения этих сведений устройство может записывать в буфер DMA и/или читать из него (при задействовании IOMMU устройство на шине PCIe должно быть прикреплено к домену IOMMU).

   Чтобы выполнить этот шаг, нужно вызвать функцию KnIoDmaGetInfo() или KnIoDmaContinuousGetDmaAddr(). Функция KnIoDmaGetInfo() позволяет получить номер страницы памяти (frame) и порядок (order) для каждого блока. (Номер страницы памяти, умноженный на размер страницы памяти, дает адрес блока. Значение 2^order представляет собой размер блока в страницах памяти.) Функцию KnIoDmaContinuousGetDmaAddr() можно использовать, если буфер DMA состоит из одного блока. Эта функция позволяет получить адрес блока. (В качестве размера блока нужно принять размер буфера DMA, заданный при его создании.)

Закрытие доступа к буферу DMA для устройства

Если удалить объект ядра, созданный при вызове функции KnIoDmaBegin(), то при задействовании IOMMU доступ устройства к буферу DMA будет запрещен. Чтобы удалить этот объект, нужно вызвать функцию KnHandleClose(), указав дескриптор, который был получен при вызове функции KnIoDmaBegin(). (Функция KnHandleClose() объявлена в заголовочном файле sysroot-*-kos/include/coresrv/handle/handle_api.h из состава KasperskyOS SDK.)

Удаление буфера DMA

Чтобы удалить буфер DMA, нужно выполнить следующие шаги:

1. Освободить регионы виртуальной памяти, зарезервированные при вызовах функции KnIoDmaMap().

   Чтобы выполнить этот шаг, нужно использовать функцию KnHandleClose(), указывая дескрипторы, которые были получены при вызовах функции KnIoDmaMap(). (Функция KnHandleClose() объявлена в заголовочном файле sysroot-*-kos/include/coresrv/handle/handle_api.h из состава KasperskyOS SDK.)

   Этот шаг нужно выполнить для всех процессов, на память которых отображен буфер DMA.

2. Удалить объект ядра, созданный вызовом функции KnIoDmaBegin().

   Чтобы выполнить этот шаг, нужно вызвать функцию KnHandleClose(), указав дескриптор, который был получен при вызове функции KnIoDmaBegin().

3. Закрыть или отозвать каждый дескриптор буфера DMA во всех процессах, которые владеют этими дескрипторами.

   Чтобы выполнить этот шаг, нужно использовать функцию KnHandleClose() и/или KnHandleRevoke(), которые объявлены в заголовочном файле sysroot-*-kos/include/coresrv/handle/handle_api.h из состава KasperskyOS SDK.

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

Функции dma.h