[Topic whats_new]

Что нового

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

• Добавлена поддержка аппаратной платформы Radxa ROCK 3A.
• Добавлено расширение для редактора исходного кода Visual Studio Code, которое обеспечивает интеграцию с KasperskyOS Community Edition.
• Добавлен компонент PackageManager, который позволяет установить KPA-пакеты в работающее решение на базе KasperskyOS, удалить KPA-пакеты и получить сведения о них, а также утилиты для управления KPA-пакетами.
• Добавлена возможность отладки с использованием отладчика GDB.
• В состав KasperskyOS Community Edition добавлены инструменты для разработки на языке Rust, а также примеры программ.
• Добавлена возможность работы с носителями USB.
• Тулчейн в составе KasperskyOS Community Edition переведен на использование компилятора Clang.
• Добавлен компонент LogRR, который представляет собой систему для журналирования информации о работе других программ.
• Обновлено руководство разработчика, в частности:
  • Добавлены описания доработок и новых возможностей, появившихся в версии KasperskyOS Community Edition 1.3.
  • Добавлены описания сценариев работы с интерфейсами библиотеки libkos.
  • Добавлен раздел "Введение".
  • Добавлен раздел "Краткое руководство разработчика решений на базе KasperskyOS".
• Добавлены следующие сторонние библиотеки и приложения:
  • abseil-cpp (20211102.0);
  • clang (17.0.6);
  • clang-format (13.0.1);
  • corrosion-rs/corrosion (0.2.2);
  • ftpd (2.3.0);
  • libyaml (0.2.5);
  • python (3.12.2);
  • google/re2 (2022-02-01);
  • rust (1.59);
  • wpa_supplicant (2.10).
• Обновлены следующие сторонние библиотеки и приложения:
  • binutils;
  • boost;
  • civetweb;
  • json-schema-validator;
  • libevdev;
  • libtool;
  • mbedtls;
  • qemu;
  • usb.
• Исключены из состава SDK следующие сторонние библиотеки и приложения:
  • autotools-wrappers;

В 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 introduction]

Введение

Настоящее руководство адресовано разработчикам программного обеспечения для программно-аппаратных систем на базе KasperskyOS. Основную часть руководства составляют следующие сведения:

• Практические руководства (англ. how-to guides), которые представляют собой сведения о действиях разработчика для получения конкретных практических результатов.

  Действия разработчика связаны с использованием:

  • функций и макросов API (язык C);
  • shell-, GDB-, CMake-команд;
  • специальных языков, используемых для автоматической генерации исходного кода.

  Практическое руководство может быть представлено в виде примера кода с пояснениями.

• Справочные материалы (англ. reference guides):
  • сведения об API;
  • синтаксис shell-, GDB-, CMake-команд;
  • синтаксис специальных языков, используемых для автоматической генерации исходного кода;
  • параметры запуска программ;
  • переменные окружения программ;
  • особенности поддержки POSIX;
  • сведения о методах ядра KasperskyOS, используемые при описании политики безопасности.
• Пояснительные материалы о базовых концепциях KasperskyOS (англ. conceptual guides).

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

Содержание разделов руководства

[Topic community_edition]

О KasperskyOS Community Edition

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

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

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

KasperskyOS Community Edition позволяет разрабатывать приложения на языках C, C++ и Rust.

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

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

[Topic sdk_contents]

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

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

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

• deb-пакет для установки KasperskyOS Community Edition, содержащий:
  • образ ядра операционной системы KasperskyOS;
  • инструменты для разработки (компилятор Clang, компоновщик LD, отладчик GDB, эмулятор 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 (поставляется в составе SDK) необходимы:

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

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

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

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

• Radxa ROCK 3A (архитектура Arm64) ревизии 1.3 с объемом оперативной памяти равным 8 ГБ;
• microSD-карта объемом не менее 2 ГБ;
• преобразователь USB-UART, поддерживающий скорость работы 1500000 бод.

[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.16.4) – утилита генерации стандартизированных файлов Makefile.in для автоматической настройки и сборки программного обеспечения из исходного кода.

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

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

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

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

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

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

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

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

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

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

  Документация: 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.82.0) – собрание библиотек классов, использующих функциональность языка C++ и предоставляющих удобный кроссплатформенный высокоуровневый интерфейс для лаконичного кодирования различных повседневных подзадач программирования (работа с данными, алгоритмами, файлами, потоками и т. п.).

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

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

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

• Civetweb (v.1.12) – простой в использовании, мощный, встраиваемый веб-сервер на 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.3.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.6.1) – библиотека, предоставляющая реализацию криптографических протоколов, таких как 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.14.0.0) – библиотека для работы с USB-устройствами.

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

• libevdev (v.1.12.1) – библиотека для работы с периферийными устройствами типа 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

• abseil/abseil-cpp (v.20211102.0) – библиотека, расширяющая стандартную библиотеку функций C++.

  Документация: https://abseil.io/docs/cpp/

• clang (v.17.0.6) – компилятор C/C++.

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

• clang-format (v.13.0.1) – инструмент для автоматического форматирования кода на C/C++.

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

• corrosion-rs/corrosion (v.0.2.2) – инструмент для интеграции Rust в существующий CMake проект.

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

• google/re2 (v.2022-02-01) – библиотека для работы с регулярными выражениями.

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

• mtheall/ftpd (v.2.3.0) – сервер File Transfer Protocol.

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

• python (v.3.12.2) – высокоуровневый язык программирования общего назначения.

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

• rust (v.1.59) – мультипарадигменный компилируемый язык программирования общего назначения.

  Документация: https://www.rust-lang.org/

• wpa_supplicant (v.2.10) – кросс-платформенная открытая реализация стандарта IEEE 802.11.

  Документация: https://w1.fi

• yaml/libyaml (v.0.2.5) – библиотека для работы с YAML.

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

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

[Topic limitations_and_known_problems]

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

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

1. При завершении работы программы любым способом (например, return из основного потока исполнения) выделенные программой ресурсы не освобождаются, а сама программа переводится в "спящее" состояние. Программы не могут быть запущены повторно.
2. Не поддерживается запуск двух и более программ с одинаковым EDL-описанием.
3. Система останавливается, если не осталось работающих программ или если один из потоков программы-драйвера завершился (штатным или нештатным образом).
4. При подключении разных USB-устройств счетчик device-id увеличивается на разную величину.
5. В некоторых примерах есть ошибки в журналах загрузки и исполнения, не влияющие на функциональность.
6. При запуске примеров на аппаратной платформе Raspberry Pi 4 Model B максимальный размер образа решения (файла kos-image) не должен превышать 248 MB, а при запуске на аппаратной платформе Radxa ROCK 3A - 146MB.
7. Не гарантируется полная работоспособность языка Rust.
8. Не гарантируется полное портирование сторонних библиотек на KasperskyOS.
9. Возможна задержка сетевых пакетов после старта KasperskyOS из-за работы протокола STP.
10. На некоторых пинах GPIO аппаратных устройств могут присутствовать внешние подтягивающие резисторы. При наличии таких резисторов более слабые внутренние резисторы не позволят притянуть такие пины к 0.
11. После завершения работы примеров, использующих сеть, на QEMU с помощью комбинации клавиш Ctrl+C в системе могут остаться запущенные процессы примера.
12. Из ядра KasperskyOS в составе SDK удалена поддержка счетчиков производительности. Пример perfcnt исключен из состава SDK.
13. Для API библиотеки libc, который поддерживается VFS, установлены ограничения на количество клиентов VFS равное 30 и ограничение количества потоков на одного клиента равное 5.
14. На портах USB 3.0 аппаратной платформы Radxa ROCK 3A работают только устройства USB 2.0.

[Topic breaking_changes]

Критические изменения в версии 1.3

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

В версии 1.3 были введены следующие критические изменения в компоненты SDK:

• Из ядра KasperskyOS в составе SDK удалена поддержка счетчиков производительности.
• Из SDK удалены объявления функций: fork, exec*, popen*, pclose. Использование этих функций приведет к ошибке при сборке.
• Указание неверного имени IPC-канала в шаблоне файла init.yaml.in приводит к ошибке при сборке.
• Тулчейн в составе SDK переведен на использование компилятора Clang.
• В компоненте Mbed-TLS включены алгоритмы TLS 1.3. Необходимо вызывать функцию psa_crypto_init() перед первым использованием хеширующих механизмов. Для корректной работы библиотеки Mbed-TLS достаточно добавить вызов psa_crypto_init() перед первым вызовом любой функции Mbed-TLS. Эту функцию можно вызывать произвольное количество раз: если первый вызов проходит успешно, остальные вызовы также будут успешны.
• Изменения в библиотеке kdf:
  • удалены функции KdfGetDeviceFromContainer() и KdfEnumContainerNames();
  • функции KdfGetDeviceListByTarget() и KdfGetDeviceListByTargetSet() теперь возвращают контейнер с дескриптором типа KdfDevContainerHandle.
• Из интерфейса ядра Handle.idl удален устаревший метод SecurityDisconnect.
• Удален конфигурационный параметр VFS_BUFFER_SPLIT_SIZE. В качестве ограничения сверху при передаче данных в арене IPC в VFS будет использоваться VFS_BUFFER_SIZE. Для конфигурирования размера I/O буфера (setbuf) вводится новый параметр VFS_BUFSIZ. Для чтения/записи данных большого размера появится возможность использовать буферы MDL.
• В VFS добавлена поддержка прав доступа для файлов. Теперь при работе с файлами VFS будет проверять биты владельца (S_IRUSR, S_IWUSR, S_IXUSR) у файла и разрешать/запрещать те или иные операции. При создании файла и каталога нужно обязательно проверять, что все биты выставляются корректно:
  • Для файлов нужно обязательно указывать биты разрешения чтения и записи: open(file, O_RDWR | O_CREAT, (S_IRUSR | S_IWUSR)
  • Для директорий обязательно указывать все три бита (Read | Write | Execute). Бит Execute отвечает за возможность поиска файлов в директории: mkdir(dir, S_IRWXU)

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

• В интерфейсе Driver.idl метод GetDeviceEvents() переименован в AwaitDeviceEvents().
• Функция-инициализатор kl_drivers_Driver *KdfServerInit(KdfServerData *data) заменена на kl_drivers_Driver *KdfServerInit(void).
• Интерфейс ядра Task::FreeSelfEnv стал заглушкой, которая возвращает rcUimplemented, а функции KnTaskFreeEnv и KnTaskGetEnv перестали быть потокобезопасными.
• Запись в AF_ROUTE сокеты запрещена. Теперь при попытке записи в AF_ROUTE сокет будет возвращена ошибка EACCESS. Для добавления/удаления маршрутов необходимо использовать ioctl() и структуру ortentry.
• Изменено поведение вызова nk_arena_get(). RTL_NULL возвращается только в случае ошибки, иначе даже в случае получения данных нулевого размера возвращается корректный указатель на память.
• Значения IDL-типа string при передаче в IPC-сообщениях должны содержать завершающий нулевой байт, даже пустые строки. Строки из нуля байтов перестанут считаться валидными и будут отклоняться Kaspersky Security Module.
• Изменены прототипы функций:
  • KosString KosCreateStringEx(KosStringRoot *root, const char *str) изменен на Retcode KosCreateStringEx(KosStringRoot *root, const char *str, KosString *outStr);
  • KosString KosCreateString(const char *str) изменен на Retcode KosCreateString(const char *str, KosString *outStr).
• В интерфейс ядра task.Task добавлен новый метод GetPid, который всегда используется при создании процесса.

  В результате при строго настроенной политики безопасности с жестким ограничением методов вызов EntityInit(Ex) начнет возвращать ошибку. Необходимо в политике добавить новый метод в разрешенные.

  Пример:

  request dst=kl.core.Core { match endpoint=task.Task { match method=GetPid { match src=Einit { grant () } } } }
• В каждый EDL-файл в составе SDK, содержащий службу kl.drivers.Block, также добавлена служба типа kl.drivers.Driver.

  Например, для ATA.edl результат будет выглядеть так:

  entity kl.drivers.ATA security kl.drivers.block.Security endpoints { driver : kl.drivers.Driver ata: kl.drivers.Block }
• Переработан набор методов службы Block.idl:
  • Удален метод Fini().
  • Удален метод EnumPorts(). Следует использовать метод GetDeviceList() службы kl.drivers.Driver.
  • Удален метод Open(). Следует использовать метод OpenDevice() службы kl.drivers.Driver.
  • Удален метод Close(). Следует использовать метод CloseDevice() службы kl.drivers.Driver.
• Добавлен список поддерживаемых кодов (MIB) функции sysctl(). Вызов с кодами, отличными от поддерживаемых запрещен и возвращает код ENOSYS. Все разрешенные коды переведены на отдельные интерфейсные методы компонента VFS (VfsNetConfig.idl). При помощи политик безопасности можно разрешать только чтение или только запись, используя аргумент valOperation IPC-запроса (кроме IpctlForwarding, RtDump, RtIflist): 0 - запись, установка значения параметра; 1 - чтение параметра; 2 - запрос размера параметра)

  Поддерживаемые коды перечислены в таблице ниже.

  Разрешенные коды функции sysctl()

  Название параметра	Код MIB	Интерфейсный метод VFS
  net.inet.ip.forwarding	CTL_NET, PF_INET, IPPROTO_IP, IPCTL_FORWARDING	IpctlForwarding
  net.inet.ip.mtudisc	CTL_NET, PF_INET, IPPROTO_IP, IPCTL_MTUDISC	IpctlMtudisc
  net.inet.ip.ttl	CTL_NET, PF_INET, IPPROTO_IP, IPCTL_DEFTTL	IpctlTtl
  net.inet.tcp.keepcnt	CTL_NET, PF_INET, IPPROTO_TCP, TCPCTL_KEEPCNT	TcpctlKeepcnt
  net.inet.tcp.keepidle	CTL_NET, PF_INET, IPPROTO_TCP, TCPCTL_KEEPIDLE	TcpctlKeepidle
  net.inet.tcp.keepintvl	CTL_NET, PF_INET, IPPROTO_TCP, TCPCTL_KEEPINTVL	TcpctlKeepintvl
  net.inet.tcp.mss_ifmtu	CTL_NET, PF_INET, IPPROTO_TCP, TCPCTL_MSS_IFMTU	TcpctlMssifmtu
  net.inet.tcp.mssdflt	CTL_NET, PF_INET, IPPROTO_TCP, TCPCTL_MSSDFLT	TcpctlMssdflt
  net.inet.tcp.recvspace	CTL_NET, PF_INET, IPPROTO_TCP, TCPCTL_RECVSPACE	TcpctlRecvspace
  net.inet.tcp.sendspace	CTL_NET, PF_INET, IPPROTO_TCP, TCPCTL_SENDSPACE	TcpctlSendspace
  net.inet.udp.recvspace	CTL_NET, PF_INET, IPPROTO_UDP, UDPCTL_RECVSPACE	UdpctlRecvspace
  net.inet.udp.sendspace	CTL_NET, PF_INET, IPPROTO_UDP, UDPCTL_SENDSPACE	UdpctlSendspace
  net.route.rtdump	CTL_NET, PF_ROUTE, NET_RT_DUMP	RtDump
  net.route.rtiflist	CTL_NET, PF_ROUTE, NET_RT_IFLIST	RtIflist
  net.inet.ip.dad_count	CTL_NET, PF_INET, IPPROTO_IP, IPCTL_DAD_COUNT	IpctlDadcount
  kern.hostname	CTL_KERN, KERN_HOSTNAME	KernHostname

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

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

Для системных и пользовательских ресурсов ядро 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 quick_reference_guide]

Краткое руководство разработчика решений на базе KasperskyOS

Подготовка к разработке

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

1. Установить KasperskyOS Community Edition и среду разработки (например, Microsoft Visual Studio Code с расширениями для разработки на C/C++ и поддержки CMake, а также расширением KasperskyOS SDK Extension) на компьютер, соответствующий системным требованиям.

   KasperskyOS Community Edition включает компиляторы C/C++, генераторы исходного кода, отладчик GDB, эмулятор QEMU, утилиты (например, binutils, cmake) и другие инструменты. Исполняемые файлы инструментов находятся в директории toolchain/bin.

2. Изучить раздел "Обзор KasperskyOS".
3. Изучить этот раздел.

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

Изучение примеров из состава KasperskyOS Community Edition

В директории examples из состава KasperskyOS Community Edition находятся примеры проектов решений на базе KasperskyOS, содержащие описание README.md и комментарии в текстовых файлах. Каждый пример помещен в отдельную директорию. Чтобы собрать пример, нужно скопировать его в директорию, где разрешен доступ на запись (например, в домашнюю директорию), и запустить скрипт cross-build.sh. В результате сборки будет создан образ решения <директория примера>/build/einit/kos-*image. Если в скрипте cross-build.sh утилита cmake вызвана с параметром --target sim, то собранный образ будет автоматически запущен на QEMU. Также примеры могут быть собраны для запуска на Raspberry Pi 4 B или Radxa ROCK 3A. Подробнее см. "Сборка и запуск примеров".

Сведения о примерах см. в "Примеры в KasperskyOS Community Edition".

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

Расположение библиотек и исполняемых файлов поставляемых компонентов решения

Библиотеки (в том числе транспортные) поставляемых компонентов решения находятся в директории sysroot-*-kos/lib из состава KasperskyOS Community Edition.

Исполняемые файлы поставляемых компонентов решения находятся в директории sysroot-*-kos/bin из состава KasperskyOS Community Edition.

Создание проекта решения на базе KasperskyOS

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

Чтобы создать CMake-проект решения на базе KasperskyOS, нужно создать иерархию директорий и файлов, как описано в разделе "Использование CMake из состава KasperskyOS Community Edition" (аналогично примерам проектов). Помимо файлов с исходным кодом CMake-проект решения включает скрипт сборки *.sh, файлы CMakeLists.txt, файл init.yaml(.in), файлы security.psl.in и *.psl, файлы *.idl, *.cdl, *.edl.

Создание скрипта сборки (файла *.sh)

Скрипт сборки можно создать, исходя из описания в разделе "Использование CMake из состава KasperskyOS Community Edition", или можно взять готовый скрипт из примеров проектов. Значение параметра --target при вызове утилиты cmake определяет цель сборки. Целью сборки может быть, например, создание и запуск образа решения на QEMU или создание образа решения для запуска на аппаратной платформе.

Создание сценариев сборки (файлов CMakeLists.txt)

Файлы CMakeLists.txt содержат сценарии сборки. Требуется создать один корневой файл CMakeLists.txt и по одному файлу CMakeLists.txt для каждой программы, включаемой в решение. Чтобы создать файлы CMakeLists.txt, нужно использовать сведения из раздела "Использование CMake из состава KasperskyOS Community Edition" и примеры проектов.

Файлы CMakeLists.txt содержат как стандартные CMake-команды (например, add_executable(), add_library(), target_link_libraries()), так и CMake-команды, специфичные для проектов решений на базе KasperskyOS.

Создание init-описания (файлов init.yaml.in и init.yaml)

На основе файла init.yaml.in в процессе сборки создается файл init.yaml, который представляет собой init-описание. Макросы, указанные в файле init.yaml.in, раскрываются в файле init.yaml. В init-описании указаны процессы (кроме процесса инициализирующей программы) и IPC-каналы, которые будут созданы при запуске решения. Также могут быть указаны параметры запуска и переменные окружения программ. Используя макросы в файле init.yaml.in, можно, например, добавить в файл init.yaml IPC-каналы, параметры запуска и переменные окружения программ, заданные через CMake-команду set_target_properties() в файлах CMakeLists.txt (см. "Файлы CMakeLists.txt для сборки прикладных"). Кроме этого, в файле init.yaml.in поддерживается возможность указывать переменные, заданные CMake-командой set() в файлах CMakeLists.txt.

Чтобы создать файл init.yaml.in, нужно использовать синтаксис, описанный разделе "Обзор: Einit и init.yaml", и можно использовать макросы.

Также для запуска процессов можно использовать системную программу ExecutionManager.

Создание описания политики безопасности решения (файлов security.psl.in и *.psl)

На основе файла security.psl.in в процессе сборки создается файл security.psl, который представляет собой верхнеуровневый файл описания политики безопасности решения. Макросы, указанные в файле security.psl.in, раскрываются в файле security.psl в виде деклараций включения файлов *.psl, расположенных в директории sysroot-*-kos/include/kl из состава KasperskyOS Community Edition. Также в файле security.psl.in поддерживается возможность указывать переменные, заданные CMake-командой set() в файлах CMakeLists.txt.

Файл security.psl содержит часть описания политики безопасности решения и ссылается на файлы с другими ее частями. Например, часть описания политики безопасности решения, управляющая взаимодействиями между программами и ядром KasperskyOS, помещается в файл core.psl.

Чтобы создать файл security.psl.in и другие файлы *.psl (например, core.psl), нужно изучить разделы "Описание политики безопасности решения на базе KasperskyOS" и "Шаблон security.psl.in", а также необходимо иметь полное представление о том, что должно быть разрешено и запрещено каждой программе в решении и при каких условиях.

В файлы security.psl.in и другие файлы *.psl можно включать декларации для выполнения аудита безопасности и тестирования политики.

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

Создание формальных спецификаций компонентов решения (файлов *.idl, *.cdl, *.edl)

Для каждой программы в решении должна быть создана формальная спецификация, которая описывает программу с точки зрения взаимодействия с другими программами. Формальная спецификация задает, например, предоставляет ли программа службы другим программам или нет, какие службы предоставляет программа, какие интерфейсы у служб программы, может ли программа обращаться к модулю безопасности Kaspersky Security Module через интерфейс безопасности.

Файл *.edl обязателен, а файлы *.cdl и *.idl опциональны. Если программа не предоставляет служб другим программам в решении, то ее формальная спецификация может состоять из одного файла *.edl. Например, формальная спецификация инициализирующей программы состоит из одного файла Einit.edl, который создается автоматически при сборке решения.

Файлы формальных спецификаций поставляемых компонентов решения находятся в директории sysroot-*-kos/include/kl из состава KasperskyOS Community Edition. Также поставляется формальная спецификация ядра KasperskyOS, файлы которой расположены в директории sysroot-*-kos/include/kl/core из состава KasperskyOS Community Edition. Исполняемый файл компонента решения сопровождается полным набором файлов формальной спецификации. Библиотеки для создания компонента решения сопровождаются файлами *.cdl и *.idl.

Для программ, разрабатываемых в проекте, формальные спецификации нужно создать. При этом для создания файла *.edl можно использовать CMake-команду. Если исполняемый файл программы компонуется с поставляемыми в составе KasperskyOS Community Edition библиотеками, то в формальную спецификацию этой программы нужно включить файлы *.cdl и *.idl, сопровождающие эти библиотеки.

Создание инициализирующей программы

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

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

IPC-каналы можно создать статически и динамически. См. "Создание IPC-каналов".

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

Чтобы создать транспортный код на языке C, нужно использовать CMake-команды nk_build_*dl_files() (см. "Библиотека nk"). В результате использования этих CMake-команд создаются файлы *.edl.h, *.cdl.h, *.idl.h, содержащие транспортный код. Эти файлы нужно включить в исходный код как клиентов, так и серверов. Какие именно файлы включать, зависит от того, какие элементы транспортного кода требуются. Например, может быть достаточно включить *.idl.h в код клиента и *.edl.h в код сервера. Но клиенту также могут потребоваться константы, определенные в *.edl.h. Кроме того, через параметр NK_FLAGS CMake-команд nk_build_*dl_files() можно задать флаги выборочной генерации транспортного кода, которые изменяют содержимое файлов *.edl.h, *.cdl.h, *.idl.h.

Примеры использования элементов транспортного кода на языке C приведены в разделах "Инициализация IPC-транспорта для межпроцессного взаимодействия и управление обработкой IPC-запросов (transport-kos.h, transport-kos-dispatch.h)" и "Инициализация IPC-транспорта для обращения к модулю безопасности (transport-kos-security.h)".

О создании и использовании транспортного кода на языке C++ см. "Транспортный код на языке C++" и "Генерация транспортного кода для разработки на языке C++".

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

Обращение к модулю безопасности Kaspersky Security Module

Интерфейс безопасности нужно задать в формальной спецификации программы. Пример кода для обращения к модулю безопасности Kaspersky Security Module приведен в разделе "Инициализация IPC-транспорта для обращения к модулю безопасности (transport-kos-security.h)".

Работа с IPC-сообщениями

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

Использование динамических библиотек

Можно использовать динамические библиотеки (*.so). См. "Использование динамических библиотек".

Работа с файловыми системами и сетевым стеком

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

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

Работа с KPA-пакетами

KPA-пакет является упаковкой для программы, предназначенной для установки в решение на базе KasperskyOS.

В составе KasperskyOS Community Edition поставляются компоненты и утилиты для работы с KPA-пакетами:

• Утилиты для управления KPA-пакетами позволяют собрать в системе, где установлен KasperskyOS Community Edition, KPA-пакет из исходных файлов программы и установить KPA-пакет в собираемый образ решения на базе KasperskyOS.
• Компонент PackageManager позволяет установить KPA-пакеты в работающее решение на базе KasperskyOS, а также удалить KPA-пакеты и получить сведения о них.

См. "Работа с KPA-пакетами".

API KasperskyOS

KasperskyOS предоставляет следующие API:

• POSIX (с ограничениями и особенностями реализации) и другие API стандартной библиотеки языка C:
  • основные API (заголовочные файлы в директориях sysroot-*-kos/include/strict, sysroot-*-kos/include/sys из состава KasperskyOS Community Edition);
  • расширенные API (заголовочные файлы в директории sysroot-*-kos/include из состава KasperskyOS Community Edition).

  Заголовочные файлы расширенных API включают заголовочные файлы основных API (через директиву include включаются заголовочные файлы, расположенные в директории sysroot-*-kos/include/strict из состава KasperskyOS Community Edition).

• Собственные API:
  • высокоуровневые API (заголовочные файлы в директории sysroot-*-kos/include/kos из состава KasperskyOS Community Edition);
  • низкоуровневые API (заголовочные файлы в директории sysroot-*-kos/include/coresrv из состава KasperskyOS Community Edition).

Компоненты для прикладной разработки

В составе KasperskyOS Community Edition поставляются:

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

Отладка программ

Чтобы выполнить отладку программ, нужно использовать отладчик GDB из состава KasperskyOS Community Edition. Отладку можно выполнить как на QEMU, так и на аппаратной платформе. Для отладки на QEMU нужно использовать GDB-сервер QEMU или GDB-сервер ядра KasperskyOS. Для отладки на аппаратной платформе требуется использовать GDB-сервер ядра KasperskyOS.

См. "Отладка программ в решении на базе KasperskyOS".

Разработка драйверов

Драйвер в KasperskyOS может быть драйвером шины и/или драйвером-клиентом, может быть локальным или распределенным между процессами. Для разработки драйверов в составе KasperskyOS Community Edition поставляется библиотека kdf (заголовочные файлы в директории sysroot-*-kos/include/kdf из состава KasperskyOS Community Edition).

См. "Разработка драйверов под KasperskyOS".

Использование глоссария

В глоссарии приведены термины и аббревиатуры в алфавитном порядке. Для каждого термина приводится определение, и указаны ссылки на связанные с этим термином разделы.

[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.

[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>/common/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++ и/или Rust).
• Добавить заголовочные файлы, поставляемые в KasperskyOS Community Edition, в проект разработки.

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

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

В состав KasperskyOS Community Edition входит расширение KasperskyOS SDK Extension for Visual Studio Code, которое обеспечивает интеграцию KasperskyOS Community Edition с редактором исходного кода Visual Studio Code.

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

Для более удобной навигации по коду проекта, включая системный 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-*-kos/include.
6. Закройте окно C/C++ Configurations.

[Topic vscode_extension]

Расширение KasperskyOS SDK Extension for Visual Studio Code

Расширение KasperskyOS SDK Extension for Visual Studio Code (далее также KasperskyOS SDK Extension) обеспечивает интеграцию KasperskyOS Community Edition с редактором исходного кода Visual Studio Code.

[Topic vscode_ext_install]

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

Установка зависимостей

Зависимости расширения автоматически устанавливаются из магазина расширений Visual Studio Code. Если на вашем компьютере имеется доступ к магазину расширений Visual Studio Code, вы можете пропустить перечисленные ниже шаги по установке зависимостей и перейти к разделу "Установка расширения" ниже.

В противном случае, вам потребуется вручную установить зависимости для расширения. Для установки зависимостей KasperskyOS SDK Extension for Visual Studio Code выполните следующие действия:

1. На другом компьютере с имеющимся доступом к магазину расширений Visual Studio Code откройте адрес https://marketplace.visualstudio.com/vscode в браузере.
2. Найдите и скачайте расширения:
   • cpptools – требуется для работы с отладчиком.
   • clangd – требуется для статического анализа исходного кода.
   • devcontainers – требуется для поддержки Docker.
3. Скопируйте полученные VSIX-файлы на компьютер, на котором требуется установить расширение KasperskyOS SDK Extension.
4. Откройте среду разработки Visual Studio Code.
5. Нажмите на клавишу F1.
6. Выполните команду Extensions: Install from VSIX... в появившейся в верхней части окна командной строке.
7. Установите скачанные на шаге 2 расширения.

Установка расширения

Для установки KasperskyOS SDK Extension выполните следующие действия:

1. Откройте среду разработки Visual Studio Code.
2. Нажмите на клавишу F1.
3. Выполните команду Extensions: Install from VSIX... в появившейся в верхней части окна командной строке.
4. Выберите файл расширения kos-extension-<version>.vsix, расположенный в директории /opt/KasperskyOS-Community-Edition-<version>/dev_tools/ide_integration/vscode/.

   При установке расширения KasperskyOS SDK Extension автоматически устанавливаются его зависимости.

Удаление расширения

Для удаления расширения нажмите комбинацию клавиш CTRL+SHIFT+X, найдите расширение в списке и в контекстном меню расширения выберите команду Uninstall.

[Topic vscode_ext_use]

Функции расширения

Расширение автоматически обнаруживает в открытом рабочем пространстве проект KasperskyOS и запускается. Параметр обнаружения – наличие в рабочем пространстве файла .vscode/kos_project.json или директории einit. Если расширение автоматически не активировалось в директории, но вы уверены, что это проект KasperskyOS, то выполните команду KOS: Activate extension in this directory. Команда активирует расширение и создает в директории проекта пустой файл .vscode/kos_project.json. Чтобы отменить ручную активацию, удалите этот файл.

После запуска расширение добавляет на нижнюю панель редактора кода Visual Studio Code следующие кнопки:

• – выбор цели сборки;
• – запуск проекта в QEMU;
• – запуск выбранной цели с отладкой;
• – сборка всех целей;
• – сборка выбранной цели;
• – очистка директории сборки;
• – переключение типа сборки;
• – включение/отключение сборки проекта с тестами;
• – выбор целевой платформы для сборки;
• – выбор устройства или эмулятора QEMU;
• – отображение версии SDK.

Функции, которые предоставляют кнопки, также можно вызвать из командной строки редактора кода, открываемой по нажатию на клавишу F1. Все команды имеют префикс KOS:.

Работа с базовым образом KasperskyOS

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

1. Запуск в эмуляторе QEMU базового образа решения на базе KasperskyOS, входящего в состав SDK. В базовом образе содержатся все системные программы, необходимые для запуска и отладки программ, упакованных в KPA-пакеты.
2. Сборка прикладной программы и ее упаковка в KPA-пакет. Для того чтобы упаковать прикладную программу в KPA-пакет, необходимо использовать CMake-команды библиотеки kpa.
3. Установка программы из KPA-пакета в запущенный на шаге 1 образ решения и ее запуск под управлением KasperskyOS.
4. Внесение изменений в код прикладной программы.
5. Повторение шагов 2-5.
6. Расширение также позволяет отлаживать программу, запущенную в базовом образе KasperskyOS. Подробнее см. "Отладка программ в составе KPA-пакета".

Создание базового описания политики безопасности решения

Расширение позволяет автоматически создавать простейшие описания политики безопасности решения для проекта.

Чтобы создать базовое описание политики безопасности:

1. Убедитесь, что расширение KasperskyOS SDK Extension установлено и активно.
2. Нажмите на клавишу F1.
3. Выполните команду KOS: Generate policy file for current project.
4. Выберите тип базового описания политики, который вы хотите создать:
   • Grant all permissions - создать простейшее описание политики безопасности решения, которая разрешает любые взаимодействия процессов любых классов между собой и с ядром KasperskyOS, а также разрешает любому процессу инициализировать запуск процессов.
   • Grant necessary permissions - создать простейшее описание политики безопасности решения, которая разрешает любые взаимодействия процессов любых классов между собой и с ядром KasperskyOS, а также определяет необходимые разрешения для инициализации запуска процессов на основе файла init.yaml.in в составе проекта.
5. Введите имя файла для сохранения созданного описания политики безопасности.

Запуск тестов

После активации расширения на боковой панели Visual Studio Code появляется вкладка Testing – . При выборе вкладки Testing в окне редактора кода отобразится дерево тестов, созданных с помощью библиотеки Google Test и обнаруженных в файлах директории test/.

Для запуска тестов нажмите на кнопку . По умолчанию запускаются все обнаруженные тесты, но вы можете выбирать определенные тесты на вкладках с исходным кодом тестов или определенные группы тестов, выбирая их из дерева всех тестов. Запускать можно только тесты, которые добавлены в файлы CMakeLists.txt для сборки программ с помощью CMake-команд kl_kos_add_small_test() или generate_kos_test() из CMake-библиотеки TestGenerator, поставляемой в составе SDK.

Результаты работы тестов, а также файлы журналов находятся в директории <директория_сборки>/bin/tests/output.

Запуск тестов политик безопасности решения

Расширение позволяет запускать тесты политики безопасности решения для проекта, созданные на основе описания политики безопасности решения.

Чтобы собрать и выполнить тесты политики безопасности решения:

1. Убедитесь, что описание политики безопасности решения содержит тесты политики безопасности решения.
2. Убедитесь, что CMake-команды сборки тестов политики безопасности решения добавлены в один из файлов CMakeLists.txt проекта.
3. Убедитесь, что расширение KasperskyOS SDK Extension установлено и активно.
4. Выполните сборку всех целей, нажав на кнопку на нижней панели.
5. Нажмите на кнопку выбора цели сборки и выберите цель с именем kos-qemu-image-PalTest<N>-sim, где N – индекс PSL-файла в списке PSL-файлов, содержащих тесты политики безопасности решения.
6. Нажмите на кнопку сборки выбранной цели .

[Topic vscode_emu_start]

Запуск базового образа решения на базе KasperskyOS

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

Чтобы запустить базовый образ решения KasperskyOS из Visual Studio Code:

1. Убедитесь, что расширение KasperskyOS SDK Extension установлено и активно.
2. Нажмите на кнопку выбора устройства на нижней панели или нажмите на клавишу F1 и выполните команду KOS: Select Device.
3. Выберите Create new emulator.
4. Выберите kos_base-dev.
5. В отобразившемся поле введите дополнительные флаги QEMU и нажмите Enter, либо сразу нажмите Enter чтобы использовать флаги по умолчанию.
6. В отобразившемся поле введите имя нового эмулятора и нажмите Enter, либо сразу нажмите Enter чтобы использовать автоматически сгенерированное имя.
7. Дождитесь завершения предыдущей команды.
8. В отобразившемся уведомлении о создании нового эмулятора нажмите на кнопку Start.
9. Дождитесь окончания загрузки эмулятора.

[Topic vscode_app_build]

Сборка программ в Visual Studio Code

Чтобы собрать программу в Visual Studio Code:

1. Откройте директорию проекта программы в Visual Studio Code.
2. Убедитесь, что проект верно определился по наличию дополнительных кнопок расширения на нижней панели. Если кнопки не появились, то активируйте решение вручную, выполнив команду KOS: Activate extension in this directory.
3. Выберите архитектуру сборки, нажав на кнопку выбора целевой платформы для сборки .
4. Выполните сборку всех целей, нажав на кнопку на нижней панели.

[Topic vscode_app_start]

Запуск программ в базовом образе решения

Если запускаемая программа использует файловые системы (через компонент VFS), то перед запуском необходимо:

1. Вызвать через меню окно параметров расширения: File → Preferences → Settings, далее Extensions → KasperskyOS.
2. Выставить значение client:kl.VfsSdCardFs для переменной окружения VFS_FILESYSTEM_BACKEND в параметре Application Environment Variables.

Чтобы запустить программу в базовом образе решения:

1. Откройте директорию проекта программы в Visual Studio Code.
2. Убедитесь, что проект верно определился по наличию дополнительных кнопок расширения на нижней панели. Если кнопки не появились, то активируйте решение вручную, выполнив команду KOS: Activate extension in this directory.
3. Убедитесь, что базовый образ решения запущен в соответствии с инструкцией в разделе "Запуск базового образа решения на базе KasperskyOS".
4. Нажмите на кнопку выбора устройства или эмулятора QEMU на нижней панели.
5. Выберите запущенный ранее базовый образ решения.
6. Выполните сборку программы в соответствии с инструкцией в разделе "Сборка программы в Visual Studio Code".
7. Убедитесь, для программа упакована в KPA-пакет.

   Для того чтобы упаковать прикладную программу в KPA-пакет, необходимо использовать CMake-команды библиотеки kpa.

8. Нажмите на кнопку выбора цели и в раскрывающемся списке выберите собранный KPA-пакет программы, подписанный в списке как [application].
9. Нажмите на кнопку запуска . Программа будет установлена в выбранный базовый образ и автоматически запущена.

[Topic kpa_debug]

Отладка программы в составе KPA-пакета

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

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

1. Установка расширения KasperskyOS SDK Extension.
2. Сборка прикладной программы и ее упаковка в KPA-пакет. Для того чтобы упаковать прикладную программу в KPA-пакет, необходимо использовать CMake-команды библиотеки kpa.
3. Запуск базового образа KasperskyOS из состава KasperskyOS Community Edition со встроенным в ядро GDB-сервером.
4. Подключение отладчика к GDB-серверу ядра. Отладчик можно подключить при старте программы или при работе программы. Подробнее:
   • Подключение отладчика при старте программы.
   • Подключение отладчика при работе программы.
5. Отладка программы с помощью графического интерфейса Visual Studio Code. Подробнее см. документацию Visual Studio Code: https://code.visualstudio.com/docs/editor/debugging.

[Topic kpa_debug_start]

Подключение отладчика при старте программы в базовом образе

Чтобы подключить отладчик к GDB-серверу ядра при старте программы в QEMU с помощью расширения Visual Studio Code:

1. Установите точку останова в исходном коде программы перед отлаживаемым фрагментом.
2. Соберите программу. Для того чтобы упаковать прикладную программу в KPA-пакет, необходимо использовать CMake-команды библиотеки kpa.
3. Запустите базовый образ KasperskyOS из состава KasperskyOS Community Edition.
4. Дождитесь окончания загрузки базового образа и установите программу с помощью команды KOS: Install package.
5. В боковой панели Visual Studio Code нажмите Run and debug > create a launch.json file , а затем выберите KasperskyOS Debugger.

   В результате будет создан файл конфигурации отладки launch.json.

6. В файле launch.json в поле конфигурации с именем (kos/gdb) Launch & debug application укажите путь до бинарного файла вашей программы, полученного в результате сборки и имя программы. В поле eiid необходимо указать значение kl.Kds.
7. Запустите отладку, нажав на кнопку (kos/gdb) Launch & debug application на нижней панели.
8. В раскрывающемся списке выберите конфигурацию с именем (kos/gdb) Launch & debug application.
9. В отладочной консоли появится сообщение, что программа готова к отладке. Нажмите на кнопку Continue и выполнение программы будет остановлено на выбранной в п.1 точке останова.

[Topic kpa_debug_attach]

Подключение отладчика при работе программы, запущенной в базовом образе

Чтобы подключить отладчик к GDB-серверу ядра при работе программы в QEMU с помощью расширения Visual Studio Code:

1. Добавьте в функцию main программы бесконечный цикл. Это позволит отладчику подключиться к работающей программе.
2. Установите точку останова в исходном коде программы перед отлаживаемым фрагментом.
3. Соберите программу. Для того чтобы упаковать прикладную программу в KPA-пакет, необходимо использовать CMake-команды библиотеки kpa.
4. Запустите базовый образ KasperskyOS из состава KasperskyOS Community Edition.
5. В боковой панели Visual Studio Code нажмите Run and debug > create a launch.json file , а затем выберите KasperskyOS Debugger.

   В результате будет создан файл конфигурации отладки launch.json.

6. В файле launch.json в поле конфигурации с именем (kos/gdb) Attach to process укажите путь до бинарного файла вашей программы, полученного в результате сборки.
7. Запустите программу в базовом образе.
8. Запустите отладку, нажав на кнопку (kos/gdb) Attach to process на нижней панели.
9. В раскрывающемся списке выберите конфигурацию с именем (kos/gdb) Attach to process и выберите имя программы для отладки.
10. В отладочной консоли появится сообщение, что программа готова к отладке. Нажмите на кнопку Continue и выполнение программы будет остановлено на выбранной в п.2 точке останова.

[Topic vscode_params]

Параметры расширения

Расширение имеет параметры, располагающиеся в хранилище Visual Studio Code, вызываемом через меню: File → Preferences → Settings, далее Extensions → KasperskyOS.

Параметры расширения

Application Arguments

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

Application Environment Variables

Список переменных окружения для запускаемых с помощью расширения приложений.

Auto_update

Включение/выключение автоматического обновления расширения при изменении параметра SDK Path.

Build Threads Num

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

Cmake Build Flags

Дополнительные флаги CMake для сборки.

Cmake Config Flags

Дополнительные конфигурационные флаги для запуска CMake.

Auto Open Log Tab

Включение/выключение автоматического открытия вкладки с журналом выполнения команды.

Force Clean

Кнопка очистки удаляет директорию сборки.

Gdbinit File

Путь к файлу gdbinit, который содержит GDB-команды, выполняемые при запуске отладчика.

Run No Graphic

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

SDK Path

Путь до установленного KasperskyOS Community Edition.

Если расширение при запуске не обнаружит корректного SDK в SDK Path, будет выдан запрос с предложением выбрать SDK из списка обнаруженных. Чтобы не делать это для каждого рабочего пространства, рекомендуется установить SDK Path для пространства настроек User.

Set Build Dir

Директория сборки проекта. По умолчанию используется директория ./build.

Shell Export Variables

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

Suppress Extensions Recommendations

Включение/выключение напоминания о необходимости установить зависимости KasperskyOS SDK Extension.

Test Failures Num

Количество непройденных тестов, отображаемое в журнале.

Test Failures Only

Включение/выключение отображения в журнале только непройденных тестов.

Test Files Pattern

Маска для поиска файлов с исходным кодом тестов проекта.

Test No Skipped

Включение/выключение отображения в журнале пропущенных тестов.

Test Skip Details

Включение/выключение отображения в журнале пропущенных и непройденных тестов.

Test Threads Num

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

Test Timeout

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

Test Verbose

Включение/выключение отображения в журнале отладочной информации о тестах.

Trace: Server

Выбор уровня детализации журналирования для LSP-клиента Visual Studio Code при работе со встроенным в SDK LSP-сервером для языков IDL/CDL/EDL. Журнал LSP-клиента можно просмотреть выбрав канал nk-lsp в окне вывода Visual Studio Code.

User SDKs

Дополнительные пути до SDK для отображения в меню выбора SDK.

[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 или Radxa ROCK 3A

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

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

• kos-image

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

• sd-image

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

   

   Схема соединения преобразователей 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

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

Если при сборке примера был создан образ kos-image, то перед записью образа на SD-карту, её нужно дополнительно подготовить. Загрузочную SD-карту для Raspberry Pi 4 B можно подготовить автоматически и вручную. После подготовки SD-карты, необходимо скопировать файл kos-image из директории <название примера>/build/einit в загрузочную область (раздел с FAT32) подготовленной SD-карты.

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

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

1. Если при работе с KasperskyOS Community Edition используется Docker-контейнер, то ему требуется предоставить доступ к устройствам в директории /dev на хост-системе. Для этого при запуске Docker-контейнера добавьте в команду запуска следующий параметр:
   -v /dev:/dev
2. Выполните сборку загрузчика U-Boot для платформы ARMv8, который будет автоматически запускать пример. Для этого выполните следующие команды:
   $ sudo apt install git build-essential libssl-dev bison flex unzip parted gcc-aarch64-linux-gnu udev dosfstools 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
3. Подготовьте образ с файловой системой для 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
4. Скопируйте загрузчик 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}
5. Заполните конфигурационный файл для загрузчика 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}
6. Запишите получившийся образ на SD-карту. Для этого подключите SD-карту к компьютеру и выполните следующую команду:
   # В следующей команде [X] – последний символ в имени блочного устройства для SD-карты. $ sudo pv -L 32M ${fs_image_name} | sudo dd bs=64k of=/dev/sd[X] conv=fsync
7. После подготовки SD-карты, необходимо скопировать файл kos-image из директории <название примера>/build/einit в загрузочную область (раздел с FAT32) подготовленной SD-карты.

[Topic preparing_sd_card_radxa]

Подготовка Radxa ROCK 3A к запуску примеров

Коммутация компьютера и Radxa ROCK 3A

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

1. Соедините пины преобразователей USB-UART с соответствующими GPIO-пинами Radxa ROCK 3A (см. рис. ниже). Если отладку выполнять не требуется, то достаточно подключить один преобразователь USB-UART для вывода.

   

   Схема соединения преобразователей USB-UART и Radxa ROCK 3A

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

Чтобы компьютер и Radxa ROCK 3A могли взаимодействовать через сеть Ethernet, выполните следующие действия:

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

Отладка программ на для Radxa ROCK 3A

Для того чтобы выполнять отладку программ, запущенных на Radxa ROCK 3A, необходимо:

1. Подключить второй преобразователь USB-UART (см. рис. выше).
2. В домашней директории пользователя создать файл .gdbinit и добавить в него следующие строки:
   set sysroot /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos add-symbol-file <path_to_debuggee>/build/einit/EinitQemu-kss/ksm.module set follow-fork-mode parent set follow-exec-mode same set detach-on-fork off set schedule-multiple on set serial baud 115200 target extended-remote /dev/ttyUSB[n]
3. В файл CmakeLists.txt в директории <path_to_debuggee>/einit добавить параметр GDBSTUB_KERNEL в вызов команды build_kos_hw_image ().
4. Выполнить сборку программы. После запуска и инициализации в выводе появится запись: [KDBG ] Waiting for GDB connection infinitely. Приложение остановится, ожидая подключения отладчика.
5. Для подключения отладчика необходимо запустить gdb из SDK: /opt/KasperskyOS-Community-Edition-<version>/toolchain/bin/aarch64-kos-gdb.
6. После запуска отладчика в выводе появится запись: [KDBG ] Connection to GDB was established.

   Подробнее см. "Подготовка к отладке на аппаратной платформе" и "Начальные шаги отладки на аппаратной платформе".

Подготовка загрузочной SD-карты для Radxa ROCK 3A

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

Если при сборке примера был создан образ kos-image, то перед записью образа на SD-карту, её нужно дополнительно подготовить. Загрузочную SD-карту для Radxa ROCK 3A можно подготовить автоматически и вручную. После подготовки SD-карты, необходимо скопировать файл kos-image из директории <название примера>/build/einit в загрузочную область (раздел с FAT32) подготовленной SD-карты.

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

Очистка flash памяти Radxa ROCK 3A

В некоторых модификациях Radxa ROCK 3A во флеш-памяти может находиться загрузчик, который несовместим с картой, подготовленной по инструкции выше.

Если при запуске примеров на Radxa ROCK 3A вы видите сообщение "SPL: failed to boot from all boot devices", то вам необходимо очистить флеш-память Radxa ROCK 3A перед запуском примеров.

Чтобы очистить флеш-память Radxa ROCK 3A:

1. Скачайте и установите утилиту rkdeveloptool.

   Инструкции по установке утилиты приведены в документации: https://docs.radxa.com/en/rock3/rock3a/low-level-dev/rkdeveloptool?host-os=debian#installation-for-rkdeveloptool

2. Скачайте загрузчик для взаимодействия с Radxa ROCK 3A: https://dl.radxa.com/rock3/images/loader/rk356x_spl_loader_ddr1056_v1.12.109_no_check_todly.bin
3. Переведите Radxa ROCK 3A в режим Maskrom:
   1. Отключите питание.
   2. Извлеките SD-карту (и модуль eMMC при наличии).
   3. Соедините USB-порт компьютера с портом ROCK 3A OTG (верхний порт USB3.0).
   4. Соедините пины Radxa ROCK 3A как показано на рисунке ниже и подайте питание на Radxa ROCK 3A.

      

   5. Разомкните пины, соединенные на предыдущем шаге.
   6. Убедитесь, что Radxa ROCK 3A находится в режиме Maskrom, выполнив в терминале следующую команду:
      $: rkdeveloptool ld DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=104 Maskrom
4. Скопируйте на Radxa ROCK 3A загрузчик для инициализации оперативной памяти и подготовки среды прошивки, выполнив в терминале следующую команду:
   rkdeveloptool db rk356x_spl_loader_ddr1056_v1.12.109_no_check_todly.bin
5. Очистите флеш-память Radxa ROCK 3A, выполнив в терминале следующие команды:
   rkdeveloptool ef rkdeveloptool rd

[Topic running_sample_programs_rpi]

Запуск примеров на Raspberry Pi 4 B или Radxa ROCK 3A

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

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

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

[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.

Используя компонент ExecutionManager можно запускать процессы из:

• исполняемого файла, для которого известно его расположение в файловой системе;
• исполняемого файла, установленного компонентом PackageManager в решение на базе KasperskyOS из KPA-пакета.

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/execution_manager/kos_ipc/execution_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

При запуске программ VfsRamFs и VfsSdCardFs по умолчанию монтируется только файловая система 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-каналов

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

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

Статически создаются IPC-каналы, заданные в init-описании. Также для статического создания IPC-каналов можно использовать API task.h.

Чтобы получить клиентский и серверный IPC-дескрипторы и идентификатор службы (RIID), нужно использовать API sl_api.h.

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

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

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

• Создание IPC-канала выполняется совместно клиентом и сервером.
• Клиент и сервер уже запущены в момент создания IPC-канала.
• Можно создать новый IPC-канал вместо удаленного.

Для динамического создания IPC-каналов нужно использовать системную программу DCM.

Если динамически созданный IPC-канал больше не требуется, его клиентский и серверный дескрипторы можно закрыть. При необходимости 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-*-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 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() или NkKosDoDispatchEx(), объявленных в заголовочном файле 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_aligned();
• макрос nk_arena_alloc();
• макрос nk_arena_store_aligned();
• макрос nk_arena_store();
• функцию NkKosCopyStringToArena().

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

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

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

Зарезервированный участок арены можно уменьшить. Для этого нужно использовать макрос 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() не требуется.)

Отменять текущее резервирование участков арены не требуется, если для получения IPC-сообщения непосредственно используется одна из функций API syscalls.h, но перед вызовами методов транспортного кода на стороне клиента и функции nk_transport_recv() на стороне сервера это делать необходимо. (Функция nk_transport_recv() объявлена в заголовочном файле sysroot-*-kos/include/nk/transport.h из состава KasperskyOS SDK.)

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

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

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

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

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

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

Чтобы проверить, является ли корректным дескриптор участка арены, нужно использовать макрос 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++