[Topic whats_new]

What's new

KasperskyOS Community Edition 1.3 has the following new capabilities and refinements:

• Added support for the Radxa ROCK 3A hardware platform.
• Added an extension for the source code editor Visual Studio Code to integrate it with KasperskyOS Community Edition.
• Added the PackageManager component that lets you install KPA packages in an operational KasperskyOS-based solution, remove KPA packages and receive information about them; and added tools for managing KPA packages.
• Added the capability for debugging using the GDB debugger.
• KasperskyOS Community Edition now includes tools for development in Rust and program examples.
• Added the capability to work with USB drives.
• The toolchain included in KasperskyOS Community Edition now uses the Clang compiler.
• Added the LogRR component, which is a system for logging information about the operation of other programs.
• Updated Developer's Guide, including:
  • Added descriptions of improvements and new features introduced in KasperskyOS Community Edition 1.3.
  • Added descriptions of scenarios for working with libkos library interfaces.
  • Added the Introduction section.
  • Added the KasperskyOS Developer's Quick Start Guide section.
• Added the following third-party libraries and applications:
  • 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)
• Updated the following third-party libraries and applications:
  • binutils
  • boost
  • civetweb
  • json-schema-validator
  • libevdev
  • libtool
  • mbedtls
  • qemu
  • usb
• Excluded the following third-party libraries and applications from the SDK:
  • autotools-wrappers

KasperskyOS Community Edition 1.2 has the following new capabilities and refinements:

• Updated system requirements: the Ubuntu GNU/Linux 22.04 "Jammy Jellyfish" operating system is required for SDK installation.
• Added capability to use dynamic libraries.
• Added capability to use a hardware watchdog on the Raspberry Pi 4 Model B.
• Added ExecutionManager component designed for creating, starting, and stopping processes.
• Added script for automatically setting environment variables used by SDK tools.
• Added data transmission to Kaspersky servers when starting a build of examples from the SDK. Data is transmitted to account for the number of users of KasperskyOS Community Edition and to obtain information about the distribution and use of KasperskyOS Community Edition. You can disable this functionality.
• Updated Developer's Guide, including:
  • Added section titled "Working with an IPC message arena".
  • Added section titled "Information about certain limits set in the system".
  • Added descriptions of scenarios for working with libkos library interfaces.
  • Updated instructions on building and running solution security policy tests.
  • Added glossary.
• Added the following third-party libraries and applications:
  • Guidelines Support Library (GSL) (2.1.0)
  • json_scheme_validator (2.1.0)
  • libpcap (1.10.4)
  • libunwind (1.6.2)
• Updated the following third-party libraries and applications:
  • libxml2
  • Mbedtls
  • Mosquitto
  • OpenSSL
  • spdlog
  • sqlite
  • fmt
  • zlib
  • flex
  • bison
  • QEMU
• Excluded the following third-party libraries and applications from the SDK:
  • ffmpeg
  • opencv
  • libjpeg-turbo
  • libpng
  • protobuf

KasperskyOS Community Edition 1.1.1 has the following new capabilities and refinements:

• Updated the following third-party libraries and applications:
  • FFmpeg
  • libxml2
  • Eclipse Mosquitto
  • opencv
  • OpenSSL
  • protobuf
  • sqlite
  • usb
• Added support for the Raspberry Pi 4 Model B hardware platform (Revision 1.5).

KasperskyOS Community Edition 1.1 has the following new capabilities and refinements:

• Added support for working with an I2C bus in master device mode.
• Added support for working with an SPI bus in master device mode.
• Added support for USB HID devices.
• Added support for Symmetric Multiprocessing (SMP).
• Expanded capabilities for device profiling: added iperf library and counters that track system parameters.
• Added PCRE library and usage example.
• Added SPDLOG library and usage example.
• Added MessageBus component and usage example.
• Added dynamic code analysis tools (ASAN, UBSAN).

KasperskyOS Community Edition 1.0 has the following new capabilities and refinements:

• Added support for the Raspberry Pi 4 Model B hardware platform.
• Added SD card support for the Raspberry Pi 4 Model B hardware platform.
• Added Ethernet support for the Raspberry Pi 4 Model B hardware platform.
• Added GPIO port support for the Raspberry Pi 4 Model B hardware platform.
• Added network services for DHCP, DNS, and NTP and usage examples.
• Added library for working with the MQTT protocol and usage examples.

[Topic introduction]

Introduction

This Guide is intended for software developers who work on KasperskyOS-based software/hardware systems. The main part of this Guide provides the following information:

• How-to guides that describe the actions that a developer should take to get specific practical results.

  For these purposes, developers can use the following:

  • API functions and macros (in the C language)
  • Shell commands, GDB commands, and CMake commands
  • Specialized languages used to automatically generate source code

  A how-to guide may be presented as an example of code with explanations.

• Reference guides:
  • API information
  • Syntax of shell commands, GDB commands, and CMake commands
  • Syntax of specialized languages used to automatically generate source code
  • Program startup parameters
  • Environment variables of programs
  • POSIX support details
  • Information on the KasperskyOS kernel methods used for a security policy description
• KasperskyOS conceptual guides.

How-to guides and reference guides may be combined into one section.

Contents of Guide sections

[Topic community_edition]

About KasperskyOS Community Edition

KasperskyOS Community Edition (CE) is a publicly available version of the KasperskyOS SDK that is designed to help you master the main principles of application development under KasperskyOS. KasperskyOS Community Edition will let you see how the concepts rooted in KasperskyOS actually work in practical applications. KasperskyOS Community Edition includes sample applications with source code, detailed explanations, and instructions and tools for building applications.

KasperskyOS Community Edition will help you:

• Learn the principles and techniques of "secure by design" development based on practical examples.
• Explore KasperskyOS as a potential platform for implementing your own projects.
• Make prototypes of solutions (primarily Embedded/IoT) based on KasperskyOS.
• Port applications/components to KasperskyOS.
• Explore security issues in software development.

KasperskyOS Community Edition lets you develop applications in the C, C++ and Rust languages.

You can download KasperskyOS Community Edition here.

In addition to this documentation, we also recommend that you explore the materials provided in the specific KasperskyOS website section for developers.

[Topic sdk_contents]

Distribution kit

The KasperskyOS SDK is a set of software tools for creating KasperskyOS-based solutions.

The distribution kit of KasperskyOS Community Edition includes the following:

• Deb package for installation of KasperskyOS Community Edition, including:
  • Image of the KasperskyOS kernel
  • Development tools (Clang compiler, LD linker, GDB debugger, QEMU emulator, and accompanying tools)
  • Utilities and scripts (for example, source code generators, makekss script for creating the Kaspersky Security Module, and makeimg script for creating the solution image)
  • A set of libraries that provide partial compatibility with the POSIX standard
  • Drivers
  • System programs (for example, virtual file system)
  • Usage examples for components of KasperskyOS Community Edition
  • End User License Agreement
  • Information about third-party code (Legal Notices)
• KasperskyOS Community Edition Developer's Guide (Online Help)
• Release Notes

The KasperskyOS SDK is installed to a computer running the Ubuntu GNU/Linux operating system.

The following components included in the KasperskyOS Community Edition distribution kit are the Runtime Components as defined by the terms of the License Agreement:

• Image of the KasperskyOS kernel.

All the other components of the distribution kit are not the Runtime Components. Terms and conditions of the use of each component can be additionally defined in the section "Information about third-party code".

[Topic system_requirements]

System requirements

To install and use KasperskyOS Community Edition, and to run examples on a virtual machine in a QEMU emulator (provided in the SDK), the following is required:

1. Operating system: Ubuntu GNU/Linux 22.04 (Jammy Jellyfish). A Docker container can be used.
2. CPU: processor with an x86-64 architecture.
3. RAM: it is recommended to have at least 4 GB of RAM for convenient use of the build tools.
4. Disk space: at least 5 GB of free space in the /opt folder (depending on the solution being developed).

To run examples on the Raspberry Pi hardware platform, the following is required:

• Raspberry Pi 4 Model B (Revision 1.4, 1.5) with 4 or 8 GB of RAM
• MicroSD card with at least 2 GB
• USB-UART converter

To run examples on the Radxa ROCK 3A hardware platform, the following is required:

• Radxa ROCK 3A (Arm64 architecture) Revision 1.3 with 8 GB of RAM
• MicroSD card with at least 2 GB
• USB-UART converter that supports a speed of 1,500,000 baud

[Topic included_third_party_libs]

Included third-party libraries and applications

To simplify the application development, KasperskyOS Community Edition also includes the following third-party libraries and applications:

• flex (v.2.6.2) is a lexical analyzer generator.

  Documentation: https://github.com/westes/flex

• pkg-config-lite (v.0.28) is a tool that provides an interface for getting information about the libraries installed in the system (such as the version and parameters for the C/C ++ compiler and linker).

  Documentation: https://sourceforge.net/projects/pkgconfiglite

• CMake (v.3.25.0) is a cross-platform software tool that automatically builds software from source code.

  Documentation: https://cmake.org/documentation

• autoconf-archive (v.2022.09.03) is a set of macros for the Autoconf tool, which creates configuration scripts for automatically configuring and building software from source code.

  Documentation: https://www.gnu.org/software/autoconf-archive

• Automake (v.1.16.4) is a tool that generates standard Makefile.in files for automatically configuring and building software from source code.

  Documentation: https://www.gnu.org/software/automake

• Autoconf (v.2.69) is a tool that generates configure scripts for automatically configuring and building software from source code.

  Documentation: https://www.gnu.org/software/autoconf

• Libtool (v.2.4.2, v.2.4.7) is a generic library support script that conceals the complexity of using shared libraries behind a consistent, portable interface.

  Documentation: https://www.gnu.org/software/libtool

• Binutils (v.2.41) is a set of tools for working with binary files that includes an assembler, linker, archiver, and other tools.

  Documentation: https://www.gnu.org/software/binutils

• Bison (v.3.5.4) is a general-purpose syntax analyzer generator that converts an annotated context-free grammar into an LR or GLR parser employing LALR(1) parser tables.

  Documentation: https://www.gnu.org/software/bison

• QEMU (v.8.2.5) is a program that emulates hardware of various platforms.

  Documentation: https://www.qemu.org/docs/master

• Automated Testing Framework (ATF) (v.0.20) is a set of libraries for writing tests for programs in C, C++ and POSIX shell.

  Documentation: https://github.com/jmmv/atf

• Boost (v.1.82.0) is a set of class libraries that utilize C++ language functionality and provide a convenient cross-platform, high-level interface for concise coding of various everyday programming subtasks (such as working with data, algorithms, files, threads, and more).

  Documentation: https://www.boost.org/doc

• nlohmann_json (v.3.9.1) is the library for working with JSON format.

  Documentation: https://github.com/nlohmann/json

• Civetweb (v.1.12) is an easy-to-use, powerful, embeddable web server based on C/C++ with additional support for CGI, SSL and Lua.

  Documentation: http://civetweb.github.io/civetweb/UserManual.html

• fmt (v.9.1.0) is an open-source formatting library.

  Documentation: https://fmt.dev/latest/index.html

• Guidelines Support Library (GSL) (v.2.1.0) is a library containing functions and types that are suggested for use by the C++ Core Guidelines maintained by the Standard C++ Foundation.

  Documentation: https://github.com/microsoft/gsl

• GoogleTest (v.1.10.0) is a C++ code testing library.

  Documentation: https://google.github.io/googletest

• iperf (v.3.10.1) is a network performance testing library.

  Documentation: https://software.es.net/iperf

• json-schema-validator (v.2.3.0) is a library designed for validating data in JSON format according to defined JSON schemas.

  Documentation: https://github.com/pboettch/json-schema-validator

• libffi (v.3.2.1) is a library providing a C interface for calling previously compiled code.

  Documentation: https://github.com/libffi/libffi

• jsoncpp (v.1.9.4) is a library for working with JSON format.

  Documentation: https://github.com/open-source-parsers/jsoncpp

• libpcap (v.1.10.4) is a library for developing programs that can capture, filter, and analyze network traffic in UNIX-like systems.

  Documentation: https://www.tcpdump.org/index.html#documentation

• libunwind (v.1.6.2) is a library for handling exceptional situations and implementing a mechanism for backtracing the stack of function calls when a process crashes.

  Documentation: https://www.nongnu.org/libunwind/docs.html

• libxml2 (v.2.10.4) is a library for working with XML.

  Documentation: http://xmlsoft.org

• Mbed TLS (v.3.6.1) is a library that implements cryptographic protocols such as TLS/SSL and DTLS, and algorithms for encryption, hashing, and authentication.

  Documentation: https://mbed-tls.readthedocs.io/en/latest

• Eclipse Mosquitto (v2.0.18) is a message broker that implements the MQTT protocol.

  Documentation: https://mosquitto.org/documentation

• jsoncpp (v.4.2.8P15) is a library for working with the NTP time protocol.

  Documentation: http://www.ntp.org/documentation.html

• OpenSSL (v.1.1.1t) is a full-fledged open-source encryption library.

  Documentation: https://www.openssl.org/docs/

• pcre (v.8.44) is a library for working with regular expressions.

  Documentation: https://www.pcre.org/current/doc/html

• spdlog (v.1.11.0) is a logging library.

  Documentation: https://github.com/gabime/spdlog

• sqlite (v.3.41.2) is a library for working with databases.

  Documentation: https://www.sqlite.org/docs.html

• Zlib (v.1.2.13) is the data compression library.

  Documentation: https://zlib.net/manual.html

• usb (v.14.0.0) is a library for working with USB devices.

  Documentation: https://github.com/freebsd/freebsd-src/tree/release/13.0.0/sys/dev/usb

• libevdev (v.1.12.1) is a library for working with evdev peripheral devices.

  Documentation: https://www.freedesktop.org/software/libevdev/doc/latest

• dhcpcd (v.9.4.1) is a DHCP/DHCPv6 client intended for automatic configuration of network settings on the client side.

  Documentation: https://github.com/NetworkConfiguration/dhcpcd

• Lwext4 (v.1.0.0) is a library for working with the ext2/3/4 file systems.

  Documentation: https://github.com/gkostka/lwext4.git

• abseil/abseil-cpp (v.20211102.0), a library that extends the standard library of C++ functions.

  Documentation: https://abseil.io/docs/cpp/

• clang (v.17.0.6) is a C/C++ compiler.

  Documentation: http://llvm.org/

• clang-format (v.13.0.1) is a tool used to automatically format C/C++ code.

  Documentation: http://llvm.org/

• corrosion-rs/corrosion (v.0.2.2) is a tool for integrating Rust into an existing CMake project.

  Documentation: https://github.com/corrosion-rs/corrosion

• google/re2 (v.2022-02-01) is a library for working with regular expressions.

  Documentation: https://github.com/google/re2

• mtheall/ftpd (v.2.3.0) is a File Transfer Protocol (FTP) server.

  Documentation: https://github.com/mtheall/ftpd

• python (v.3.12.2) is a general-purpose, high-level programming language.

  Documentation: https://github.com/python/cpython/

• rust (v.1.59) is a general-purpose, multi-paradigm compiled programming language.

  Documentation: https://www.rust-lang.org/

• wpa_supplicant (v.2.10) is a cross-platform, open implementation of the IEEE 802.11 standard.

  Documentation: https://w1.fi

• yaml/libyaml (v.0.2.5) is a library for working with YAML.

  Documentation: https://yaml.org/

See also Information about third-party code.

[Topic limitations_and_known_problems]

Limitations and known issues

Because the KasperskyOS Community Edition is intended for educational purposes only, it includes several limitations:

1. When a program is terminated through any method (for example, "return" from the main thread), the resources allocated by the program are not released, and the program goes to sleep. Programs cannot be started repeatedly.
2. You cannot start two or more programs that have the same EDL description.
3. The system stops if no running programs remain, or if one of the driver program threads has been terminated, whether normally or abnormally.
4. When connecting different USB devices, the device-id counter increases by a different value.
5. Some examples contain errors in the boot and execution logs that do not affect the functionality.
6. When running examples on the Raspberry Pi 4 Model B hardware platform, the maximum size of the solution image (kos-image file) must not exceed 248 MB, and 146 MB when running on the Radxa ROCK 3A hardware platform.
7. Full functionality of the Rust language cannot be guaranteed.
8. Full porting of third-party libraries to KasperskyOS cannot be guaranteed.
9. Network packets may be delayed after KasperskyOS startup due to operation of the STP protocol.
10. Some GPIO pins of hardware devices may contain external pull-up resistors. If these types of resistors are present, weaker internal resistors will not allow these pins to be pulled to 0.
11. After finishing examples that use the network, running processes of an example may remain in the system in QEMU by using the Ctrl+C key combination.
12. Removed support for performance counters from the KasperskyOS kernel in the SDK. Removed the perfcnt example from the SDK.
13. The libc library API supported by VFS has a limit of 30 VFS clients and 5 threads per client.
14. Only USB 2.0 devices work in USB 3.0 ports of the Radxa ROCK 3A hardware platform.

[Topic breaking_changes]

Critical changes in version 1.3

Due to modifications made to SDK components in version 1.3, you may need to make changes to the application code that was developed using KasperskyOS Community Edition version 1.2 before using that code with KasperskyOS Community Edition version 1.3.

The following critical changes were made to SDK components in version 1.3:

• Removed support for performance counters from the KasperskyOS kernel in the SDK.
• Declarations of the following functions were removed from the SDK: fork, exec*, popen*, and pclose. Use of these functions will result in an error during a build.
• Specifying an invalid name of an IPC channel in the init.yaml.in file template will result in an error during a build.
• The toolchain included in the SDK now uses the Clang compiler.
• TLS 1.3 algorithms are now included in the Mbed-TLS component. You must call the psa_crypto_init() function before you use the hashing mechanisms for the first time. To ensure correct operation of the Mbed-TLS library, all you have to do is add the psa_crypto_init() call before calling any Mbed-TLS function for the first time. This function can be called any number of times. If the first call is successful, all other calls will also be successful.
• Changes to the kdf library:
  • The KdfGetDeviceFromContainer() and KdfEnumContainerNames() functions have been removed.
  • The KdfGetDeviceListByTarget() and KdfGetDeviceListByTargetSet() functions now return a container with a handle of the KdfDevContainerHandle type.
• The obsolete SecurityDisconnect method has been removed from the Handle.idl kernel interface.
• The configuration parameter VFS_BUFFER_SPLIT_SIZE has been removed. VFS will use VFS_BUFFER_SIZE as the upper limit when transmitting data in an IPC arena. The new parameter VFS_BUFSIZ is being implemented to configure the size of the I/O buffer (setbuf). You will be able to use MDL buffers to read/write large-sized data.
• Support for file access permissions has been added to VFS. When working with files, VFS will now check the file owner bits (S_IRUSR, S_IWUSR, and S_IXUSR) and either allow or deny specific operations. When creating a file and directory, you must verify that all bits are set correctly:
  • The read/write permission bits must be specified for files: open(file, O_RDWR | O_CREAT, (S_IRUSR | S_IWUSR)
  • All three bits must be specified for directories (Read | Write | Execute). The Execute bit provides the capability to search for files in the directory: mkdir(dir, S_IRWXU)

  The open() function lets you create files without specifying these bits, therefore you may encounter a situation in which previously created files may stop opening and instead return an EACCESS error. You can use the chmod() function to change the file permissions.

• In the Driver.idl interface, the GetDeviceEvents() method has been renamed to AwaitDeviceEvents().
• The initializer function kl_drivers_Driver *KdfServerInit(KdfServerData *data) has been replaced with kl_drivers_Driver *KdfServerInit(void).
• The kernel interface Task::FreeSelfEnv has become a stub that returns rcUimplemented, and the KnTaskFreeEnv and KnTaskGetEnv functions are no longer thread-safe.
• Writing to AF_ROUTE sockets is prohibited. Now, if you attempt to write to the AF_ROUTE socket, the EACCESS error is returned. To add/delete routes, you must use ioctl() and the ortentry structure.
• The behavior of the nk_arena_get() call has changed. RTL_NULL is returned only if there is an error. Otherwise, the correct memory pointer is returned even if zero-sized data is received.
• The values of an IDL type "string" must contain a terminating null byte when passed in IPC messages, even if they are empty strings. Strings composed of zero bytes will no longer be considered valid and will be denied by the Kaspersky Security Module.
• Function prototypes have been changed:
  • KosString KosCreateStringEx(KosStringRoot *root, const char *str) was changed to Retcode KosCreateStringEx(KosStringRoot *root, const char *str, KosString *outStr);
  • KosString KosCreateString(const char *str) was changed to Retcode KosCreateString(const char *str, KosString *outStr).
• The kernel interface task.Task now has a new method named GetPid, which is always used when a process is created.

  As a result, the EntityInit(Ex) call will start to return an error when there is a strictly configured security policy with a rigid restriction on methods. You must add the new method to the permitted methods in the policy.

  Example:

  request dst=kl.core.Core { match endpoint=task.Task { match method=GetPid { match src=Einit { grant () } } } }
• An endpoint of the kl.drivers.Driver type has also been added to each SDK-included EDL file containing the kl.drivers.Block endpoint.

  For example, the result will look as follows for ATA.edl:

  entity kl.drivers.ATA security kl.drivers.block.Security endpoints { driver : kl.drivers.Driver ata: kl.drivers.Block }
• The set of methods of the Block.idl endpoint has been refined:
  • The Fini() method has been removed.
  • The EnumPorts() method has been removed. You should use the GetDeviceList() method of the kl.drivers.Driver endpoint.
  • The Open() method has been removed. You should use the OpenDevice() method of the kl.drivers.Driver endpoint.
  • The Close() method has been removed. You should use the CloseDevice() method of the kl.drivers.Driver endpoint.
• A list of supported codes (MIB) of the sysctl() function has been added. A call with codes that are different from the supported codes is prohibited and returns the ENOSYS code. All authorized codes have been converted into separate interface methods of the VFS component (VfsNetConfig.idl). With security policies, you can permit read-only or write-only by using the valOperation argument of an IPC request (except IpctlForwarding, RtDump, and RtIflist): 0 is for writing, or setting a parameter value, 1 is for reading a parameter, and 2 is for requesting the parameter size)

  The supported codes are listed in the table below.

  Authorized codes of the sysctl() function

  Parameter name	MIB code	VFS interface method
  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]

Overview of KasperskyOS

KasperskyOS is a specialized operating system based on a separation microkernel and security monitor.

See also:

• What's new
• About KasperskyOS Community Edition
• System requirements
• Getting started

[Topic overview_general_inf]

Overview

Microkernel

KasperskyOS is a microkernel operating system. The kernel provides minimal functionality, including scheduling of program execution, management of memory and input/output. The code of device drivers, file systems, network protocols and other system software is executed in user mode (outside of the kernel context).

Processes and endpoints

Software managed by KasperskyOS is executed as processes. A process is a running program that has the following distinguishing characteristics:

• It can provide endpoints to other processes and/or use the endpoints of other processes via the IPC mechanism.
• It uses core endpoints via the IPC mechanism.
• It is associated with security rules that regulate the interactions of the process with other processes and with the kernel.

An endpoint is a set of logically related methods available via the IPC mechanism (for example, an endpoint for receiving and transmitting data over the network, or an endpoint for handling interrupts).

Implementation of the MILS and FLASK architectural approaches

When developing a KasperskyOS-based system, software is designed as a set of components (programs) whose interactions are regulated by security mechanisms. In terms of security, the degree of trust in each component may be high or low. In other words, the system software includes trusted and untrusted components. Interactions between different components (and between components and the kernel) are controlled by the kernel (see the figure below), which has a high level of trust. This type of system design is based on the architectural approach known as MILS (Multiple Independent Levels of Security), which is employed when developing critical information systems.

A decision on whether to allow or deny a specific interaction is made by the Kaspersky Security Module. (This decision is referred to as the security module decision.) The security module is a kernel module whose trust level is high like the trust level of the kernel. The kernel executes the security module decision. This type of division of interaction management functions is based on the architectural approach known as FLASK (Flux Advanced Security Kernel), which is used in operating systems for flexible application of security policies.

Interaction between different processes and between processes and the kernel in KasperskyOS

KasperskyOS-based solution

A KasperskyOS-based solution (hereinafter also referred to as the solution) consists of system software (including the KasperskyOS kernel and Kaspersky Security Module) and applications integrated to work as part of the software/hardware system. The programs included in a KasperskyOS-based solution are considered to be components of the KasperskyOS-based solution (hereinafter referred to as solution components). Each instance of a solution component is executed in the context of a separate process.

Security policy for a KasperskyOS-based solution

Interactions between the various processes and between processes and the KasperskyOS kernel are allowed or denied according to the KasperskyOS-based solution security policy (hereinafter referred to as the solution security policy or simply the policy). The solution security policy is stored in the Kaspersky Security Module and is used by this module whenever it makes decisions on whether to allow or deny interactions.

The solution security policy can also define the logic for handling queries sent by a process to the security module via the security interface. A process can use the security interface to send some data to the security module (for example, to influence future decisions made by the security module) or to receive a security module decision that is needed by the process to determine its own further actions.

Kaspersky Security System technology

Kaspersky Security System technology lets you implement diverse security policies for solutions. You can also combine multiple security mechanisms and flexibly regulate the interactions between different processes and between processes and the KasperskyOS kernel. A Kaspersky Security Module to be used in a specific solution is created based on the solution security policy description.

Source code generators

Some of the source code of a KasperskyOS-based solution is created by source code generators. Specialized programs generate the source code in C from declarative descriptions. They generate source code of the Kaspersky Security Module, source code of the initializing program (which starts all other programs in the solution and statically defines the topology of interaction between them), and the source code of the methods and types for carrying out IPC (transport code).

The transport code is generated by the nk-gen-c compiler based on the formal specifications of solution components.

The source code of the Kaspersky Security Module is generated by the nk-psl-gen-c compiler from the solution security policy description and formal specifications of solution components.

The source code of the initializing program is generated by the einit tool from the init description and formal specifications of solution components.

[Topic overview_architecture]

KasperskyOS architecture

The KasperskyOS architecture is presented in the figure below:

KasperskyOS architecture

In KasperskyOS, applications and drivers interact with each other and with the kernel by using the libkos library, which provides the interfaces for querying core endpoints. (In KasperskyOS, a driver generally operates with the same level of privileges as the application.) The libkos library queries the kernel by executing only three system calls: Call(), Recv() and Reply(). These calls are implemented by the IPC mechanism. Core endpoints are supported by kernel subsystems whose purposes are presented in the table below. Kernel subsystems interact with hardware through the hardware abstraction layer (HAL), which makes it easier to port KasperskyOS to various platforms.

Kernel subsystems and their purpose

[Topic overview_ipc_intro]

IPC

[Topic overview_ipc_details]

IPC mechanism

Exchanging IPC messages

In KasperskyOS, processes interact with each other by exchanging IPC messages (IPC request and IPC response). In an interaction between processes, there are two separate roles: client (the process that initiates the interaction) and server (the process that handles the request). Additionally, a process that acts as a client in one interaction can act as a server in another.

To exchange IPC messages, the client and server use three system calls: Call(), Recv() and Reply() (see the figure below):

1. The client sends an IPC request to the server. To do so, one of the client's threads makes the Call() system call and is locked until an IPC response is received from the server.
2. The server thread that has made the Recv() system call waits for IPC requests. When an IPC request is received, this thread is unlocked and handles the request, then sends an IPC response by making the Reply() system call.
3. When an IPC response is received, the client thread is unlocked and continues execution.

   

   Exchanging IPC messages between a client and a server

Calling methods of server endpoints

IPC requests are sent to the server when the client calls endpoint methods of the server (hereinafter also referred to as interface methods) (see the figure below). The IPC request contains input parameters for the called method, as well as the Runtime Implementation Identifier (RIID) and the called method ID (MID). Upon receiving a request, the server uses these identifiers to find the method's implementation. The server calls the method's implementation while passing in the input parameters from the IPC request. After handling the request, the server sends the client an IPC response that contains the output parameters of the method.

Calling a server endpoint method

IPC channels

To enable two processes to exchange IPC messages, an IPC channel must be established between them. An IPC channel has a client side and a server side. One process can use multiple IPC channels at the same time. A process may act as a server for some IPC channels while acting as a client for other IPC channels.

KasperskyOS has two mechanisms for creating IPC channels:

1. The static mechanism allows the parent process to create an IPC channel between child processes. Static creation of IPC channels is normally performed by the initializing program.
2. The dynamic mechanism allows already running processes to create IPC channels between each other.

[Topic overview_ipc_control]

IPC control

The Kaspersky Security Module is integrated into the IPC implementation mechanism. The security module is aware of the structure of IPC messages for all possible interactions because IDL, CDL and EDL descriptions are used to generate the source code of this module. This enables the security module to verify that the interactions between processes comply with the solution security policy.

The KasperskyOS kernel queries the security module each time a process sends an IPC message to another process. The security module operating scenario includes the following steps:

1. The security module verifies that the IPC message complies with the called method of the endpoint (the size of the IPC message is verified along with the size and location of certain structural elements).
2. If the IPC message is incorrect, the security module makes the "deny" decision and the next step of the scenario is not carried out. If the IPC message is correct, the next step of the scenario is carried out.
3. The security module checks whether the security rules allow the requested action. If allowed, the security module makes the "granted" decision. Otherwise it makes the "denied" decision.

The kernel executes the security module decision. In other words, it either delivers the IPC message to the recipient process or rejects its delivery. If delivery of an IPC message is rejected, the sender process receives an error code via the return code of the Call() or Reply() system call.

The security module checks IPC requests as well as IPC responses. The figure below depicts the controlled exchange of IPC messages between a client and a server.

Controlled exchange of IPC messages between a client and a server

[Topic overview_ipc_transport]

Transport code for IPC

Implementation of interprocess interaction requires transport code, which is responsible for generating, sending, receiving, and processing IPC messages. However, developers of KasperskyOS-based solutions do not have to write their own transport code. Instead, you can use special tools and libraries included in the KasperskyOS SDK.

Transport code for developed components of a solution

A developer of a KasperskyOS-based solution component can generate transport code based on IDL, CDL and EDL descriptions related to this component. The KasperskyOS SDK includes the nk-gen-c compiler for this purpose. The nk-gen-c compiler generates transport methods and types for use by both a client and a server.

Transport code for supplied components of a solution

Most components included in the KasperskyOS SDK may be used in a solution both locally (through static linking with other components) as well as via IPC.

To use a supplied component via IPC, the KasperskyOS SDK provides the following transport libraries:

• Solution component's client library, which converts local calls into IPC requests.
• Solution component's server library, which converts IPC requests into local calls.

The client library is linked to the client code (the component code that will use the supplied component). The server library is linked to the implementation of the supplied component (see the figure below).

Using a supplied solution component via IPC

[Topic overview_ipc_kernel]

IPC between a process and the kernel

The IPC mechanism is used for interaction between processes and the KasperskyOS kernel. In other words, processes exchange IPC messages with the kernel. The kernel provides endpoints, and processes use those endpoints. Processes query core endpoints by calling functions of the libkos library (directly or via other libraries). The client transport code for interaction between a process and the kernel is included in this library.

A solution developer is not required to create IPC channels between processes and the kernel because these channels are created automatically when processes are created. (To set up interaction between processes, the solution developer has to create IPC channels between them.)

The Kaspersky Security Module makes decisions regarding interaction between processes and the kernel the same way it makes decisions regarding interaction between a process and other processes. (The KasperskyOS SDK has IDL, CDL and EDL descriptions for the kernel that are used to generate source code of the security module.)

[Topic overview_resource_acces_control]

Resource Access Control

Types of resources

KasperskyOS has two types of resources:

• System resources, which are managed by the kernel. Some examples of these include processes, memory regions, and interrupts.
• User resources, which are managed by processes. Examples of user resources: files, input-output devices, data storage.

Handles

Both system resources and user resources are identified by handles. Processes (and the KasperskyOS kernel) can transfer handles to other processes. By receiving a handle, a process obtains access to the resource that is identified by this handle. In other words, the process that receives a handle can request operations to be performed on a resource by specifying its received handle in the request. The same resource can be identified by multiple handles used by different processes.

Security identifiers

The KasperskyOS kernel assigns security identifiers to system resources and user resources. A security identifier (SID) is a globally unique identifier of a resource (in other words, a resource can have only one SID but can have multiple handles). The Kaspersky Security Module identifies resources based on their SID.

Security context

Kaspersky Security System technology lets you employ security mechanisms that receive SID values as inputs. When employing these mechanisms, the Kaspersky Security Module distinguishes resources (and the KasperskyOS kernel) and binds security contexts to them. A security context consists of data that is associated with an SID and used by the security module to make decisions.

The contents of a security context depend on the security mechanisms being used. For example, a security context may contain the state of a resource and the levels of integrity of access subjects and/or access objects. If a security context stores the state of a resource, this lets you allow certain operations to be performed on a resource only if the resource is in a specific state, for example.

The security module can modify a security context when it makes a decision. For example, it can modify information about the state of a resource (the security module used the security context to verify that a file is in the "not in use" state and allowed the file to be opened for write access and wrote a new state called "opened for write access" into the security context of this file).

Resource access control by the KasperskyOS kernel

The KasperskyOS kernel controls access to resources by using two mutually complementary methods at the same time: executing the decisions of the Kaspersky Security Module and implementing a security mechanism based on object capabilities (OCap).

Each handle is associated with access rights to the resource identified by this handle, which means it is a capability in OCap terms. By receiving a handle, a process obtains the access rights to the resource that is identified by this handle. For example, these access rights may consist of read permissions, write permissions, and/or permissions to allow another process to perform operations on the resource (handle transfer permission).

Processes that use the resources provided by the kernel or other processes are referred to as resource consumers. When a resource consumer opens a system resource, the kernel sends the consumer the handle associated with the access rights to this resource. These access rights are assigned by the kernel. Before an operation is performed on a system resource requested by a consumer, the kernel verifies that the consumer has sufficient rights. If the consumer does not have sufficient rights, the kernel rejects the request of the consumer.

In an IPC message, a handle is sent together with its permissions mask. The handle permissions mask is a value whose bits are interpreted as access rights to the resource identified by the handle. A resource consumer can find out their access rights to a system resource from the handle permissions mask of this resource. The kernel uses the handle permissions mask to verify that the consumer is allowed to request the operations to be performed on the system resource.

The security module can verify the permissions masks of handles and use these verifications to either allow or deny interactions between different processes and between processes and the kernel when such interactions are related to resource access.

The kernel prohibits the expansion of access rights when handles are transferred among processes (when a handle is transferred, access rights can only be restricted).

Resource access control by resource providers

Processes that control user resources and access to those resources for other processes are referred to as resource providers. For example, drivers are resource providers. Resource providers control access to resources by using two mutually complementary methods: executing the decisions of the Kaspersky Security Module and using the OCap mechanism that is provided by the KasperskyOS kernel.

If a resource is queried by its name (for example, to open it), the security module cannot be used to control access to the resource without the involvement of the resource provider. This is because the security module identifies a resource by its SID, not by its name. In such cases, the resource provider finds the resource handle based on the resource name and forwards this handle (together with other data, such as the required state of the resource) to the security module via the security interface (the security module receives the SID corresponding to the transferred handle). The security module makes a decision and returns it to the resource provider. The resource provider implements the decision of the security module.

When a resource consumer opens a user resource, the resource provider sends the consumer the handle associated with the access rights to this resource. In addition, the resource provider decides which specific rights for accessing the resource will be granted to the resource consumer. Before an operation is performed on a user resource as requested by a consumer, the resource provider verifies that the consumer has sufficient rights. If the consumer does not have sufficient rights, the resource provider rejects the request of the consumer.

A resource consumer can find out their access rights to a user resource from the permissions mask of the handle of this resource. The resource provider uses the handle permissions mask to verify that the consumer is allowed to request the operations to be performed on the user resource.

[Topic overview_solution_image]

Structure and startup of a KasperskyOS-based solution

Structure of a solution

The image of the KasperskyOS-based solution loaded into hardware contains the following files:

• Image of the KasperskyOS kernel
• File containing the executable code of the Kaspersky Security Module
• Executable file of the initializing program
• Executable files of all other solution components (for example, applications and drivers)
• Files used by programs (for example, dynamic libraries, files containing settings, fonts, graphical and audio data)

The ROMFS file system is used to save files in the solution image.

Starting a solution

A KasperskyOS-based solution is started as follows:

1. The bootloader starts the KasperskyOS kernel.
2. The kernel finds and loads the security module (as a kernel module).
3. The kernel starts the initializing program.
4. The initializing program starts the programs included in the solution (one, several, or all).

[Topic quick_reference_guide]

The KasperskyOS Developer's Quick Start Guide

Preparations for developing

To start developing KasperskyOS solutions, complete the following steps:

1. Install KasperskyOS Community Edition and development environment, such as Microsoft Visual Studio Code with extensions for C/C++ development and CMake support, as well as KasperskyOS SDK Extension, on a computer that meets the system requirements.

   KasperskyOS Community Edition includes C/C++ compilers, source code generators, a GDB debugger, QEMU emulator, utilities, such as binutils and cmake, and other tools. Tool executables are located in toolchain/bin.

2. Carefully read the Overview of KasperskyOS.
3. Carefully read this section.

   When working on a project, you will need to refer to various sections to get detailed information.

Exploring the examples from KasperskyOS Community Edition

The examples directory in KasperskyOS Community Edition contains examples of KasperskyOS solution projects with a README.md description and comments in text files. Each example resides in a separate directory. To build an example, copy it into a directory that you have write permissions to, such as home, and run cross-build.sh. The build process will create a solution image: <example directory>/build/einit/kos-*image. If cross-build.sh calls cmake with the --target sim parameter, the built image will be automatically run in QEMU. You can also build examples to be run on Raspberry Pi 4 B or Radxa ROCK 3A. For more details, refer to the Building and running examples section.

For details on the examples, see Examples in KasperskyOS Community Edition.

Some of the examples implement the security patterns that are used for KasperskyOS development.

Location of libraries and executable files of supplied solution components

The libraries (including transport libraries) of supplied solution components are located in sysroot-*-kos/lib, in KasperskyOS Community Edition.

The executable files of supplied solution components are located in sysroot-*-kos/bin, in KasperskyOS Community Edition.

Creating a KasperskyOS-based solution project.

You are advised to use the CMake build system, but you may also use another build system or create your own build script by using the build tools from KasperskyOS Community Edition.

To create a CMake project for a KasperskyOS solution, create a hierarchy of directories and files as described in Using CMake from the contents of KasperskyOS Community Edition, similarly to the project examples. In addition to files containing source code, a solution CMake project includes an *.sh build script, CMakeLists.txt files, an init.yaml(.in) file, security.psl.in and *.psl files, and *.idl, *.cdl and *.edl files.

Creating a build script (*.sh file)

A build script can be created according to the description in Using CMake from the contents of KasperskyOS Community Edition, or you can take a ready-to-use script from the project examples. The build target is determined by the value of the --target parameter when cmake is called. For example, a build target may be to create and run a solution image in QEMU or to create a solution image to be run on a hardware platform.

Creating build scenarios (CMakeLists.txt files)

CMakeLists.txt files contain build scenarios. Create one root CMakeLists.txt file and then one CMakeLists.txt file for each program included in the solution. To create CMakeLists.txt files, use information from Using CMake from the contents of KasperskyOS Community Edition and the project examples.

CMakeLists.txt files contain standard CMake commands (for example, add_executable(), add_library(), and target_link_libraries()) as well as CMake commands that are specific to KasperskyOS solution projects.

Creating an init description (init.yaml.in and init.yaml files)

During the build process, init.yaml.in is used to create an init.yaml file, which is an init description. The macros specified in init.yaml.in are expanded in the init.yaml file. The init description specifies the processes, except for the process of the initializing program, and the IPC channels that will be created when the solution starts. It can also specify the run parameters and environment variables of programs. For example, you can use macros in init.yaml.in to populate init.yaml with IPC channels, run parameters, and environment variables of programs defined via the set_target_properties() CMake command in CMakeLists.txt files (see CMakeLists.txt files for building applications). In addition, init.yaml.in supports the ability to specify variables defined by the CMake command set() in CMakeLists.txt files.

To create the init.yaml.in file, use the syntax described in Overview: Einit and init.yaml, and you can use macros.

You can also use the system program ExecutionManager to start processes.

Creating a solution security policy description (security.psl.in and *.psl files)

During the build process, security.psl.in is used to create a security.psl file, which is the top-level file of the solution security policy description. The macros specified in security.psl.in are expanded in security.psl in the form of declarations to include *.psl files located in sysroot-*-kos/include/kl, in KasperskyOS Community Edition. The security.psl.in file also supports the ability to specify variables defined by the set() CMake command in CMakeLists.txt files.

The security.psl file contains part of the solution security policy description and refers to the files containing its other parts. For example, the part of the solution security policy description that manages interactions between programs and the KasperskyOS kernel is placed into core.psl.

To create security.psl.in and other *.psl files, such as core.psl, carefully read Describing a security policy for a KasperskyOS solution and Security.psl.in template. You need a complete understanding of what must be allowed and denied for each program in the solution and under which conditions.

The security.psl.in file and other *.psl files can include declarations to perform a security audit and test the policy.

During the early stages of development, you can use a solution security policy stub that allows all interactions (see Example descriptions of basic security policies for KasperskyOS-based solutions).

Creating formal specifications of solution components (*.idl, *.cdl, and *.edl files)

For each program in the solution, create a formal specification that describes the program in terms of its interaction with other programs. For example, the formal specification defines whether the program provides endpoints to other programs, which endpoints are provided, which interfaces they have, and whether the program can query the Kaspersky Security Module via the security interface.

The *.edl file is mandatory, while *.cdl and *.idl are optional. If the program does not provide endpoints to other programs in the solution, its formal specification may consist of one *.edl file. For example, the formal specification of the initializing program consists of one Einit.edl file created automatically during the build.

The formal specification files for supplied solution components are located in sysroot-*-kos/include/kl, in KasperskyOS Community Edition. There is also a formal specification of the KasperskyOS kernel, whose files are located in sysroot-*-kos/include/kl/core, in KasperskyOS Community Edition. The solution component executable is accompanied by the full set of formal specification files. The libraries for creating a solution component are accompanied by *.cdl and *.idl files.

You need to create formal specifications for programs being developed as part of the project. You can use a CMake command to create *.edl. If the program executable is linked to libraries provided in KasperskyOS Community Edition, include the *.cdl and *.idl files accompanying these libraries into the formal specification of the program.

Creating initializing program

KasperskyOS solutions include an initializing program. Each solution project contains an einit directory. The name of this directory matches the name of the initializing program but does not contain its source code because the code is generated automatically during the build.

Creating IPC channels

IPC channels can be created statically or dynamically. See Creating IPC channels

Creating and using transport code

To create transport code in C, you can use the nk_build_*dl_files() CMake commands (see nk library). These CMake commands create the *.edl.h, *.cdl.h, and *.idl.h files, which contain the transport code. These files need to be included in the source code of both clients and servers. The specific files to include depend on which transport code elements are required. For example, it may suffice to include *.idl.h into the client code and *.edl.h into the server code. However, a client may also require the constants defined in *.edl.h. In addition, the NK_FLAGS parameter of the nk_build_*dl_files() CMake commands can define transport code selective generation flags that modify the contents of *.edl.h, *.cdl.h, and *.idl.h.

Examples of using transport code elements written in C are provided in Initializing IPC transport for interprocess communication and managing IPC request processing (transport-kos.h, transport-kos-dispatch.h) and Initializing IPC transport for querying the security module (transport-kos-security.h).

For details about creating and using C++ transport code, see Transport code in C++ and Generating transport code for development in C++.

If a solution component is supplied with transport libraries, you do not need to create transport code.

Querying the Kaspersky Security Module

A security interface must be defined in the formal specification of the program. An example of code for querying the Kaspersky Security Module is provided in Initializing IPC transport for querying the security module (transport-kos-security.h).

Working with IPC messages

An IPC message contains a constant part and an (optional) arena. The constant part is a structure that serves as an element of transport code. Operations on the constant part of IPC messages consist of writing and reading fields of the structure. You must use an API to work with the IPC message arena (see Working with an IPC message arena).

Using dynamic libraries

You can use dynamic libraries (*.so). See Using dynamic libraries.

Working with file systems and network stack

KasperskyOS Community Edition is supplied with executable files and libraries containing implementations of file systems and the network stack. Functionality is available to programs via POSIX functions and other functions of the standard C library.

See File systems and network.

Working with KPA packages

A KPA package is essentially packaging for a program intended for installation in a KasperskyOS-based solution.

KasperskyOS Community Edition includes the following components and tools used to work with KPA packages:

• Tools for managing KPA packages let you build a KPA package from program source files in the system where the KasperskyOS Community Edition is installed and then install the KPA package in a built KasperskyOS-based solution image.
• PackageManager component lets you install KPA packages in an operational KasperskyOS-based solution, remove KPA packages, and receive information about them.

See Working with KPA packages.

KasperskyOS APIs

KasperskyOS provides the following APIs:

• POSIX (with limitations and specific features of implementation) and other APIs of the standard C library:
  • Main APIs (header files in the sysroot-*-kos/include/strict and sysroot-*-kos/include/sys directories from KasperskyOS Community Edition)
  • Extended APIs (header files in sysroot-*-kos/include from KasperskyOS Community Edition)

  The header files of extended APIs include the header files of the main APIs (the include directive is used to include header files located in sysroot-*-kos/include/strict, in KasperskyOS Community Edition).

• Native APIs:
  • Top-level APIs (header files in sysroot-*-kos/include/kos, in KasperskyOS Community Edition)
  • Low-level APIs (header files in sysroot-*-kos/include/coresrv, in KasperskyOS Community Edition)

Components for application development

KasperskyOS Community Edition includes the following:

• The MessageBus component that implements the message bus.
• The LogRR component, which provides a system for logging information about the operation of other programs.

Debugging programs

To debug programs, use the GDB debugger from KasperskyOS Community Edition. Debugging can be performed in QEMU or on the hardware platform. To perform debugging in QEMU, you should use the GDB server of QEMU or the GDB server of the KasperskyOS kernel. To perform debugging on the hardware platform, you must use the GDB server of the KasperskyOS kernel.

See Debugging programs in a KasperskyOS-based solution.

Developing drivers

In KasperskyOS, a driver may be a bus driver and/or a client driver, and it may be local or distributed among processes. For driver development, KasperskyOS Community Edition provides the kdf library (header files in sysroot-*-kos/include/kdf, in KasperskyOS Community Edition).

See Developing drivers for KasperskyOS.

Using a glossary

The glossary defines terms and abbreviations in alphabetical order. Each term is accompanied by a definition and links to the sections related to the term.

[Topic getting_started]

Getting started

This section tells you what you need to know to start working with KasperskyOS Community Edition.

[Topic using_docker]

Using a Docker container

To install and use KasperskyOS Community Edition, you can use a Docker container in which an image of one of the supported operating systems is deployed.

To use a Docker container for installing KasperskyOS Community Edition:

1. Make sure that the Docker software is installed and running.
2. To download the official Docker image of the Ubuntu GNU/Linux 22.04 (Jammy Jellyfish) operating system from the public Docker Hub repository, run the following command:

   docker pull ubuntu:22.04

3. To run the image, run the following command:

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

4. Copy the deb package for installation of KasperskyOS Community Edition into the container.
5. Install KasperskyOS Community Edition.

[Topic sdk_install_and_remove]

Installation and removal

Installation

KasperskyOS Community Edition is distributed as a deb package. It is recommended to use the apt package installer to install KasperskyOS Community Edition.

To deploy the package using apt, run the following command:

The package will be installed in /opt/KasperskyOS-Community-Edition-<version>.

To conveniently work with tools provided in the KasperskyOS Community Edition SDK, the path to the executable files of these tools in /opt/KasperskyOS-Community-Edition-<version>/toolchain/bin must be added to the PATH environment variable. To avoid having to do this each time you log in to a user session, run the script /opt/KasperskyOS-Community-Edition-<version>/common/set_env.sh, log out and log in to a session again.

Syntax of the command for calling the set_env.sh script:

Parameters:

• -d

  Cancels the action of the script.

• -h, --help

  Displays the Help text.

In addition to changing the PATH environment variable, the script defines the KOSCEVER and KOSCEDIR environment variables that contain the version and absolute path to the KasperskyOS Community Edition SDK, respectively. Use of these environment variables allows the build system to determine the SDK installation path at startup, and to verify that the solution version matches the SDK version.

Removal

Prior to removing KasperskyOS Community Edition, cancel the action of the set_env.sh script if you ran this script after installing the SDK.

To remove KasperskyOS Community Edition, run the following command:

After running this command, all installed files in the /opt/KasperskyOS-Community-Edition-<version> directory will be deleted.

[Topic ide_settings]

Configuring the development environment

This section provides brief instructions on configuring the development environment and adding the header files included in KasperskyOS Community Edition to a development project.

Configuring the code editor

Before getting started, you should do the following to simplify your development of KasperskyOS-based solutions:

• Install code editor extensions and plugins for your programming language (C, C++ and/or Rust).
• Add the header files included in KasperskyOS Community Edition to the development project.

  The header files are located in the directory: /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include.

Example of how to configure Visual Studio Code

KasperskyOS Community Edition includes the KasperskyOS SDK Extension for Visual Studio Code, which integrates KasperskyOS Community Edition with the source code editor known as Visual Studio Code.

Instead of installing the extension, you can also manually add the header files included in KasperskyOS Community Edition to the development project.

To more conveniently navigate the project code, including the system API:

1. Create a new workspace or open an existing workspace in Visual Studio Code.

   A workspace can be opened implicitly by using the File > Open folder menu options.

2. Make sure the C/C++ for Visual Studio Code extension is installed.
3. In the View menu, select the Command Palette item.
4. Select the C/C++: Edit Configurations (UI) item.
5. In the Include path field, enter /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include.
6. Close the C/C++ Configurations window.

[Topic vscode_extension]

KasperskyOS SDK Extension for Visual Studio Code

The KasperskyOS SDK Extension for Visual Studio Code (hereinafter also referred to as the KasperskyOS SDK Extension) integrates KasperskyOS Community Edition with the source code editor known as Visual Studio Code.

[Topic vscode_ext_install]

Installing and removing the extension

Installing dependencies

Extension dependencies are automatically installed from the Visual Studio Code Extension Marketplace. If your computer has access to the Visual Studio Code Extension Marketplace, you can skip the steps for setting dependencies below and instead proceed to the "Installing the extension" section.

Otherwise, you will need to manually set the dependencies for the extension. To set the dependencies of the KasperskyOS SDK Extension for Visual Studio Code:

1. On another computer that can access the Visual Studio Code Extension Marketplace, open the address https://marketplace.visualstudio.com/vscode in a browser.
2. Find and download the relevant extensions:
   • cpptools is required for working with the debugger.
   • clangd is required for static analysis of source code.
   • devcontainers is required for Docker support.
3. Copy the received VSIX files to the computer where you need to install the KasperskyOS SDK Extension.
4. Open the Visual Studio Code development environment.
5. Press F1.
6. Run the Extensions: Install from VSIX... command in the command line that opens in the upper part of the window.
7. Install the extensions that you downloaded at step 2.

Installing the extension

To install KasperskyOS SDK Extension, do the following:

1. Open the Visual Studio Code development environment.
2. Press F1.
3. Run the Extensions: Install from VSIX... command in the command line that opens in the upper part of the window.
4. Select the kos-extension-<version>.vsix extension file located in the directory /opt/KasperskyOS-Community-Edition-<version>/dev_tools/ide_integration/vscode/.

   During installation of the KasperskyOS SDK Extension, its dependencies are automatically set.

Removing the extension

To remove the extension, press the key combination CTRL+SHIFT+X, find the extension in the list, and select the Uninstall command from the context menu of the extension.

[Topic vscode_ext_use]

Extension functions

The extension automatically detects a KasperskyOS project in the open workspace and starts. The detection parameter is the presence of the .vscode/kos_project.json file or einit directory in the workspace. If the extension has not automatically activated in the directory but you are certain that it is a KasperskyOS project, run the command KOS: Activate extension in this directory. This command activates the extension and creates an empty .vscode/kos_project.json file in the project directory. To cancel manual activation, delete this file.

After startup, the extension adds the following buttons to the lower panel of the Visual Studio Code editor:

• – select the build target.
• – start the project in QEMU.
• – start the selected target with debugging.
• – build all targets.
• – build the selected target.
• – clear the build directory.
• – switch the build type.
• – enable/disable the project build with tests.
• – select the target platform for the build.
• – select the device or QEMU emulator.
• – display the SDK version.

Functions that provide buttons can also be called from the command line of the code editor, which can be opened by pressing F1. All commands have the KOS: prefix.

Working with a basic KasperskyOS image

The extension lets you avoid having to completely build a KasperskyOS-based solution after making changes to application code. Instead, you can use the following scenario:

1. Running a basic KasperskyOS-based solution image, included in the SDK, in the QEMU emulator. The basic image contains all the system programs required to run and debug programs packaged in KPA packages.
2. Build an application and package it into a KPA package. You must use the CMake commands of the kpa library to pack a program into a KPA package.
3. Install a program from a KPA package into the solution image that was run at step 1 and start it under KasperskyOS.
4. Make changes to the application code.
5. Repeat steps 2–5.
6. With the extension, you can also debug a program that is running in a basic KasperskyOS image. For more details, refer to Debugging programs that are part of a KPA package.

Create a basic solution security policy description

The extension lets you automatically create basic solution security policy descriptions for a project.

To create a basic security policy description:

1. Make sure that the KasperskyOS SDK Extension is installed and active.
2. Press F1.
3. Run the command KOS: Generate policy file for current project.
4. Select the type of basic policy description that you want to create:
   • Grant all permissions: create a basic solution security policy description that allows all interactions between different processes of any class and between these processes and the KasperskyOS kernel, and that also allows any process to initialize the startup of processes.
   • Grant necessary permissions: create a basic solution security policy description that allows all interactions between different processes of any class and between these processes and the KasperskyOS kernel, and that also determines the necessary permissions for initializing the startup of processes based on the init.yaml.in file within the project.
5. Enter the file name for saving the created security policy description.

Running tests

After the extension is activated, the Testing tab () appears on the side panel of Visual Studio Code. When you select the Testing tab, the code editor window displays a tree of tests created using the Google Test library and found in files in the test/ directory.

To run the tests, tap the button. All detected tests are run by default. However, you can select specific tests on the tabs containing the source code of the tests, or you can select specific groups of tests by selecting them from the tree of all tests. You can only run tests that are added to CMakeLists.txt files for building programs using the kl_kos_add_small_test() or generate_kos_test() CMake commands from the TestGenerator CMake library included in the SDK.

The test results and log files are located in the directory <build_directory>/bin/tests/output.

Starting solution security policy tests

The extension lets you run solution security policy tests for a project if they were created based on the solution security policy description.

To build and run solution security policy tests:

1. Make sure that the solution security policy description contains the solution security policy tests.
2. Make sure that the CMake commands for building solution security policy tests have been added to one of the CMakeLists.txt files of the project.
3. Make sure that the KasperskyOS SDK Extension is installed and active.
4. Build all targets by clicking the button in the lower panel.
5. Click the build target selection button and select the target named kos-qemu-image-PalTest<N>-sim (N refers to the PSL file index within the list of PSL files containing solution security policy tests).
6. Click the button to build the selected target.

[Topic vscode_emu_start]

Starting a basic KasperskyOS-based solution image

The basic KasperskyOS-based solution image is included in the SDK and contains all the system programs required to run and debug programs packaged in KPA packages.

To start a basic KasperskyOS-based solution image from Visual Studio Code:

1. Make sure that the KasperskyOS SDK Extension is installed and active.
2. Click the device selection button on the lower panel or press F1 and run the command KOS: Select Device.
3. Select Create new emulator.
4. Select kos_base-dev.
5. In the opened field, enter the additional QEMU flags and press Enter, or immediately press Enter to use the default flags.
6. In the opened field, enter the name of the new emulator and press Enter, or immediately press Enter to use the automatically generated name.
7. Wait until the previous command completes.
8. In the notification about the new emulator being created, click the Start button.
9. Wait for the emulator to finish loading.

[Topic vscode_app_build]

Building programs in Visual Studio Code

To build a program in Visual Studio Code:

1. Open the program project directory in Visual Studio Code.
2. Make sure that the project was correctly identified based on the appearance of additional extension buttons in the lower panel. If the buttons do not appear, manually activate the solution by running the command KOS: Activate extension in this directory.
3. Select the build architecture by clicking the button for selecting the target platform for the build .
4. Build all targets by clicking the button in the lower panel.

[Topic vscode_app_start]

Starting programs in a basic solution image

If a program that you want to start uses file systems (via the VFS component), the following is required before starting the program:

1. Use the menu to open the extension settings window: File → Preferences → Settings, then select Extensions → KasperskyOS.
2. Set the client:kl.VfsSdCardFs value for the VFS_FILESYSTEM_BACKEND environment variable in the Application Environment Variables parameter.

To start a program in a basic solution image:

1. Open the program project directory in Visual Studio Code.
2. Make sure that the project was correctly identified based on the appearance of additional extension buttons in the lower panel. If the buttons do not appear, manually activate the solution by running the command KOS: Activate extension in this directory.
3. Make sure that the basic solution image is started according to the instructions provided in the Starting a basic KasperskyOS-based solution image section.
4. Click the button for selecting the device or QEMU emulator in the lower panel.
5. Select the previously started basic solution image.
6. Build the program according to the instructions provided in the Building a program in Visual Studio Code section.
7. Make sure that the program has been packed into a KPA package.

   You must use the CMake commands of the kpa library to pack a program into a KPA package.

8. Click the target selection button . In the drop-down list, select the built program KPA package that is signed as [application] in the list.
9. Click the start button . The program will be installed to the selected basic image and will automatically start.

[Topic kpa_debug]

Debugging a program that is part of a KPA package

Unlike debugging programs in a KasperskyOS-based solution, debugging a program in a KPA package means you don’t have to rebuild the entire KasperskyOS-based solution after updating the application code.

The scenario for debugging a program that is part of a KPA package looks as follows:

1. Install the KasperskyOS SDK Extension.
2. Build an application and package it into a KPA package. You must use the CMake commands of the kpa library to pack a program into a KPA package.
3. Run a basic KasperskyOS image from KasperskyOS Community Edition with a GDB server built into the kernel.
4. Connect the debugger to the GDB server of the kernel. The debugger can be connected at program startup or while the program is running. Details:
   • Connecting a debugger at program startup.
   • Connecting a debugger while a program is running.
5. Debugging a program using the Visual Studio Code graphical user interface. For more details, refer to the Visual Studio Code documentation: https://code.visualstudio.com/docs/editor/debugging .

[Topic kpa_debug_start]

Connecting a debugger when starting a program in a basic image

To connect a debugger to the GDB server of the kernel while starting a program in QEMU using the Visual Studio Code extension:

1. Set a breakpoint in the program source code before the fragment to be debugged.
2. Build the program. You must use the CMake commands of the kpa library to pack a program into a KPA package.
3. Run a basic KasperskyOS image from KasperskyOS Community Edition.
4. Wait for the basic image to finish loading and install the program by running the command KOS: Install package.
5. On the side bar of Visual Studio Code, click Run and debug > create a launch.json file and then select KasperskyOS Debugger.

   This will create a debug configuration file named launch.json.

6. In the launch.json file, in the field of the configuration named (kos/gdb) Launch & debug application, specify the path to the binary file of your program resulting from the build, and the program name. In the eiid field, you need to specify the kl.Kds value.
7. Start debugging by clicking the (kos/gdb) Launch & debug application button on the lower pane.
8. In the drop-down list, select the configuration named (kos/gdb) Launch & debug application.
9. The debug console will show a message stating that the program is ready for debugging. Click Continue, and program execution will be stopped at the breakpoint that you selected at step 1.

[Topic kpa_debug_attach]

Connecting a debugger while a program is running from a basic image

To connect a debugger to the GDB server of the kernel while the program is running in QEMU using the Visual Studio Code extension:

1. Add an infinite loop to the main function of the program. This enables the debugger to connect to the running program.
2. Set a breakpoint in the program source code before the fragment to be debugged.
3. Build the program. You must use the CMake commands of the kpa library to pack a program into a KPA package.
4. Run a basic KasperskyOS image from KasperskyOS Community Edition.
5. On the side bar of Visual Studio Code, click Run and debug > create a launch.json file and then select KasperskyOS Debugger.

   This will create a debug configuration file named launch.json.

6. In the launch.json file, in the field of the configuration named (kos/gdb) Attach to process, specify the path to the binary file of your program resulting from the build.
7. Start the program in the basic image.
8. Start debugging by clicking the (kos/gdb) Attach to process button on the lower pane.
9. In the drop-down list, select the configuration named (kos/gdb) Attach to process and select the name of the program to debug.
10. The debug console will show a message stating that the program is ready for debugging. Click Continue, and program execution will be stopped at the breakpoint that you selected at step 2.

[Topic vscode_params]

Extension settings

The extension settings are located in the Visual Studio Code storage, which can be called through the menu as follows: File → Preferences → Settings, then Extensions → KasperskyOS.

Extension settings

Application Arguments

List of command-line arguments for applications started with the extension.

Application Environment Variables

List of environment variables for applications started with the extension.

Auto_update

Enable/disable automatic updates of the extension when the SDK Path parameter is modified.

Build Threads Num

Select the quantity of processor threads used during the build. All available threads are used by default.

Cmake Build Flags

Additional CMake flags for the build.

Cmake Config Flags

Additional configuration flags for running CMake.

Auto Open Log Tab

Enable/disable automatic opening of the tab containing the command execution log.

Force Clean

The Clean button deletes the build directory.

Gdbinit File

Path to the gdbinit file containing the GDB commands that are executed when the debugger is started.

Run No Graphic

Enable/disable enforced startup of the emulator without a graphical user interface.

SDK Path

Path to the installed KasperskyOS Community Edition.

If the extension does not detect the correct SDK in the SDK Path at startup, you will be prompted to select an SDK from the list of detected SDKs. To avoid having to do this for each workspace, it is recommended to set the SDK Path for the User settings.

Set Build Dir

Project build directory. The ./build directory is used by default.

Shell Export Variables

Additional variables that are set before starting CMake.

Suppress Extensions Recommendations

Enable/disable the reminder that you need to set the dependencies of the KasperskyOS SDK Extension.

Test Failures Num

Number of failed tests displayed in the log.

Test Failures Only

Enable/disable display of only failed tests in the log.

Test Files Pattern

Mask for searching for files containing the source code of project tests.

Test No Skipped

Enable/disable display of skipped tests in the log.

Test Skip Details

Enable/disable display of skipped and failed tests in the log.

Test Threads Num

Select the quantity of processor threads used when running tests. All available threads are used by default. However, single tests will use one thread each.

Test Timeout

Time limit for running each test (in seconds). When this value is set to 0, the limits from the test configurations are applied.

Test Verbose

Enable/disable display of debug information about tests in the log.

Trace: Server

Select the level of logging detail for the Visual Studio Code LSP client when working with the LSP server built into the SDK for the IDL/CDL/EDL languages. You can view the LSP client log by selecting the nk-lsp channel in the Visual Studio Code output window.

User SDKs

Additional paths to SDKs for displaying the SDK selection menu

[Topic building_and_running_sample_programs]

Building and running examples

[Topic building_sample_programs]

Building the examples

The examples are built using the CMake build system that is included in KasperskyOS Community Edition.

The code of the examples and build scripts are available at the following path:

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

Building the examples to run on QEMU

To build an example, go to the directory with the example and run this command:

Running the cross-build.sh script creates a KasperskyOS-based solution image that includes the example, and initiates startup of the example in QEMU. The kos-qemu-image solution image is located in the <name of example>/build/einit directory.

Building the examples to run on Raspberry Pi 4 B or Radxa ROCK 3A

To build an example, go to the directory with the example and run this command:

The type of image that is created by the cross-build.sh script depends on the value that you choose for the target parameter:

• kos-image

  This creates a KasperskyOS-based solution image that includes the example. The kos-image solution image is located in the <name of example>/build/einit directory.

• sd-image

  This creates a file system image for a bootable SD card. The following is loaded into the file system image: kos-image, U-Boot bootloader that starts the example, and the firmware for Raspberry Pi 4 B or Radxa ROCK 3A. The source code for the U-Boot bootloader and firmware can be downloaded from the website https://github.com. The file system image file hdd.img is saved in the directory <example name>/build.

[Topic running_sample_programs_qemu]

Running examples on QEMU

Running examples on QEMU on Linux with a graphical shell

An example is run on QEMU on Linux with a graphical shell using the cross-build.sh script, which also builds the example. To run the script, go to the folder with the example and run the command:

Running examples on QEMU on Linux without a graphical shell

To run an example on QEMU on Linux without a graphical shell, go to the directory with the example, build the example and run the following commands:

[Topic preparing_sd_card_rpi]

Preparing Raspberry Pi 4 B to run examples

Connecting a computer and Raspberry Pi 4 B

To see the output from Raspberry Pi 4 B on a computer and to have debug capabilities, do the following:

1. Connect the pins of the FT232 USB-UART converters to the corresponding GPIO pins of Raspberry Pi 4 B (see the figure below). If debugging is not necessary, all you need to do is connect one USB-UART converter for output.

   

   Diagram for connecting USB-UART converters and Raspberry Pi 4 B

2. Connect the computer's USB ports and the USB-UART converters.
3. Install PuTTY or another equivalent program. Configure the settings as follows: bps = 115200, data bits = 8, stop bits = 1, parity = none, flow control = none. Define the USB port connected to the USB-UART converter used for receiving output from Raspberry Pi 4 B.

To allow a computer and Raspberry Pi 4 B to interact through Ethernet:

1. Connect the network cards of the computer and Raspberry Pi 4 B to a switch or to each other.
2. Configure the computer's network card so that its IP address is in the same subnet as the IP address of the Raspberry Pi 4 B network card (the settings of the Raspberry Pi 4 B network card are defined in the dhcpcd.conf file, which is found at the path <example name>/resources/...).

Preparing a bootable SD card for Raspberry Pi 4 B

If the hdd.img image was created when building the example, all you have to do is write the resulting image to the SD card. To do this, connect the SD card to the computer and run the following command:

If kos-image was created when building the example, the SD card requires additional preparations before you can write the image to it. A bootable SD card for Raspberry Pi 4 B can be prepared automatically or manually. After preparing the SD card, you must copy the kos-image file from the directory <example name>/build/einit to the bootable area (FAT32 partition) of the prepared SD card.

To automatically prepare the bootable SD card, connect the SD card to the computer and run the following commands:

To manually prepare the bootable SD card:

1. If a Docker container is used when working with KasperskyOS Community Edition, it must be granted access to devices in the /dev directory on the host system. To do so when starting the Docker container, add the following parameter to the startup command:
   -v /dev:/dev
2. Build the U-Boot bootloader for ARMv8, which will automatically run the example. To do this, run the following commands:
   $ 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. Prepare the image containing the file system for the SD card.
   # Image will contain a boot partition of 1 GB in fat32 and three partitions of 350 MB each in ext2, ext3 and ext4, respectively. $ 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. Copy the U-Boot bootloader and embedded software (firmware) for Raspberry Pi 4 B to the received file system image by running the following commands:
   # In the following commands, the path ~/mnt/fat32 is just an example. # You can use a different path. $ 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. Fill in the configuration file for the U-Boot bootloader in the image by using the following commands:
   $ 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. Write the resulting image to an SD card. To do this, connect the SD card to the computer and run the following command:
   # In the following command, [X] is the last symbol in the name of the block device for the SD card. $ sudo pv -L 32M ${fs_image_name} | sudo dd bs=64k of=/dev/sd[X] conv=fsync
7. After preparing the SD card, you must copy the kos-image file from the directory <example name>/build/einit to the bootable area (FAT32 partition) of the prepared SD card.

[Topic preparing_sd_card_radxa]

Preparing Radxa ROCK 3A to run examples

Switching for a computer and Radxa ROCK 3A

To see the output from Radxa ROCK 3A on a computer and to have debug capabilities, do the following:

1. Connect the pins of the USB-UART converters to the corresponding GPIO pins of the Radxa ROCK 3A (see the figure below). If debugging is not necessary, all you need to do is connect one USB-UART converter for output.

   

   Diagram for connecting USB-UART converters and Radxa ROCK 3A

2. Connect the computer's USB ports and the USB-UART converters.
3. Install PuTTY or another equivalent program. Configure the settings as follows: bps = 1500000, data bits = 8, stop bits = 1, parity = none, flow control = none. Define the USB port connected to the USB-UART converter used for receiving output from Radxa ROCK 3A.

To allow a computer and Radxa ROCK 3A to interact through Ethernet, perform the following actions:

1. Connect the network cards of the computer and Radxa ROCK 3A to a switch or to each other.
2. Configure the computer's network card so that its IP address is in the same subnet as the IP address of the Radxa ROCK 3A network card (the settings of the Radxa ROCK 3A network card are defined in the dhcpcd.conf file, which is found at the path <example name>/resources/...).

Debugging programs for Radxa ROCK 3A

To debug programs running on the Radxa ROCK 3A, you must do the following:

1. Include a second USB-UART converter (see the figure above).
2. In the home directory of the user, create the .gdbinit file and add the following strings to it:
   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. In the CmakeLists.txt file in the <path_to_debuggee>/einit directory, add the GDBSTUB_KERNEL parameter to the build_kos_hw_image () command call.
4. Build the program. After startup and initialization, the entry [KDBG ] Waiting for GDB connection infinitely will appear in the output. The application will stop while it waits for the debugger to connect.
5. To connect the debugger, you must run gdb from the SDK: /opt/KasperskyOS-Community-Edition-<version>/toolchain/bin/aarch64-kos-gdb.
6. After the debugger starts, the entry [KDBG ] Connection to GDB was established will appear in the output.

   For more details, refer to Preparations for debugging on the hardware platform and Initial steps of debugging on the hardware platform.

Preparing a bootable SD card for Radxa ROCK 3A

If the hdd.img image was created when building the example, all you have to do is write the resulting image to the SD card. To do this, connect the SD card to the computer and run the following command:

If kos-image was created when building the example, the SD card requires additional preparations before you can write the image to it. A bootable SD card for Radxa ROCK 3A can be prepared automatically or manually. After preparing the SD card, you must copy the kos-image file from the directory <example name>/build/einit to the bootable area (FAT32 partition) of the prepared SD card.

To automatically prepare the bootable SD card, connect the SD card to the computer and run the following commands:

Clearing the Radxa ROCK 3A flash memory

In some editions of the Radxa ROCK 3A, the flash memory may contain a bootloader that is incompatible with the card that you have prepared according to the instructions provided above.

If you see the message "SPL: failed to boot from all boot devices" when running examples on the Radxa ROCK 3A, you must clear the Radxa ROCK 3A flash memory before running the examples.

To clear the Radxa ROCK 3A flash memory:

1. Download and install the tool named rkdeveloptool.

   Instructions on installing this tool are provided in the documentation: https://docs.radxa.com/en/rock3/rock3a/low-level-dev/rkdeveloptool?host-os=debian#installation-for-rkdeveloptool

2. Download the bootloader for interacting with the Radxa ROCK 3A: https://dl.radxa.com/rock3/images/loader/rk356x_spl_loader_ddr1056_v1.12.109_no_check_todly.bin
3. Switch the Radxa ROCK 3A to Maskrom mode:
   1. Power it off.
   2. Extract the SD card (and the eMMC module if present).
   3. Connect the computer's USB port to the ROCK 3A OTG port (upper USB 3.0 port).
   4. Connect the Radxa ROCK 3A pins as shown on the figure below and power on the Radxa ROCK 3A.

      

   5. Disconnect the pins that were connected at the previous step.
   6. Make sure that the Radxa ROCK 3A is in Maskrom mode by running the following command in the terminal:
      $: rkdeveloptool ld DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=104 Maskrom
4. Copy the bootloader for RAM initialization and firmware environment preparation to the Radxa ROCK 3A by running the following command in the terminal:
   rkdeveloptool db rk356x_spl_loader_ddr1056_v1.12.109_no_check_todly.bin
5. Clear the Radxa ROCK 3A flash memory by running the following commands in the terminal:
   rkdeveloptool ef rkdeveloptool rd

[Topic running_sample_programs_rpi]

Running examples on Raspberry Pi 4 B or Radxa ROCK 3A

To run an example on a Raspberry Pi 4 B or Radxa ROCK 3A:

1. Go to the directory with the example and build the example.
2. Make sure that Raspberry Pi 4 B or Radxa ROCK 3A and the bootable SD card are prepared to run examples.
3. Connect the bootable SD card to the Raspberry Pi 4 B or Radxa ROCK 3A.
4. Supply power to the Raspberry Pi 4 B or Radxa ROCK 3A and wait for the example to run.

   The output displayed on the computer connected to Raspberry Pi 4 B or Radxa ROCK 3A indicates that the example started.

[Topic developing]

Development for KasperskyOS

[Topic sc_application_start]

Starting processes

[Topic einit_overview]

Overview: Einit and init.yaml

Einit initializing program

When a solution is started, the KasperskyOS kernel finds the executable file named Einit (initializing program) in the solution image and runs this executable file. The initializing program performs the following operations:

• Creates and starts processes when a solution is started.
• Creates IPC channels between processes when a solution is started (statically creates IPC channels).

A process of the initializing program belongs to the Einit class.

Generating the source code of the initializing program

The KasperskyOS SDK includes the einit tool, which generates the C-language source code of the initializing program. The standard way to use the einit tool is to integrate an einit call into one of the steps of the build script, which generates the einit.c file containing the source code of the initializing program. In one of the following steps of the build script, you must compile the einit.c file into the executable file of Einit and include it into the solution image.

The einit tool generates the source code of the initializing program based on the init description, which consists of a text file that is usually named init.yaml.

Syntax of init.yaml

An init description contains data in YAML format. This data identifies the following:

• Processes that are started when the solution starts.
• IPC channels that are created when the solution starts and are used by processes to interact with each other (not with the kernel).

This data consists of a dictionary with the entities key containing a list of dictionaries of processes. Process dictionary keys are presented in the table below.

Process dictionary keys in an init description

Process IPC channel dictionary keys are presented in the table below.

IPC channel dictionary keys in an init description

[Topic using_einit]

Example init descriptions

This section provides examples of init descriptions that demonstrate various aspects of starting processes.

Starting a client and server and creating an IPC channel between them

In this example, a process of the Client class and a process of the Server class are started. The names of the processes are not specified, so they will match the names of their respective process classes. The names of the executable files are not specified, so they will also match the names of their respective process classes. The processes will be connected by an IPC channel named server_connection.

init.yaml

Starting processes from defined executable files

This example will start a Client-class process from the executable file named cl, a ClientServer-class process from the executable file named csr, and a MainServer-class process from the executable file named msr. The names of the processes are not specified, so they will match the names of their respective process classes.

init.yaml

Starting two processes from the same executable file

This example will start a Client-class process from the executable file named Client, and two processes of the MainServer and BkServer classes from the executable file named srv. The names of the processes are not specified, so they will match the names of their respective process classes.

init.yaml

Starting two servers of the same class and a client, and creating IPC channels between the client and servers

This example will start a Client-class process (named Client) and two Server-class processes named UserServer and PrivilegedServer. The client will be connected to the servers via IPC channels named server_connection_us and server_connection_ps. The names of the executable files are not specified, so they will match the names of their respective process classes.

init.yaml

Setting the startup parameters and environment variables of programs

This example will start a VfsFirst-class process (named VfsFirst) and a VfsSecond-class process (named VfsSecond). The program that will run in the context of the VfsFirst process will be started with the parameter -f /etc/fstab, and will receive the ROOTFS environment variable with the value ramdisk0,0 / ext2 0 and the UNMAP_ROMFS environment variable with the value 1. The program that will run in the context of the VfsSecond process will be started with the -l devfs /dev devfs 0 parameter. The names of the executable files are not specified, so they will match the names of their respective process classes.

init.yaml

[Topic app_static_start]

Starting processes using the system program ExecutionManager

The ExecutionManager component provides a C++ interface for creating, starting and stopping processes in solutions that are based on KasperskyOS.

You can use the ExecutionManager component to start processes from the following:

• Executable file with a known location in the file system.
• Executable file installed by the PackageManager component in a KasperskyOS-based solution from a KPA package.

The ExecutionManager component API is built on top of IPC and helps simplify program development. ExecutionManager is a separate system program that is accessed through IPC. However, developers are provided with a client library that eliminates the necessity of directly using IPC calls.

The programming interface of the ExecutionManager component is described in the article titled "ExecutionManager component".

ExecutionManager component usage scenario

Hereinafter "the client" refers to the application that uses the ExecutionManager component API to manage other applications.

The typical usage scenario for the ExecutionManager component includes the following steps:

1. Add the ExecutionManager program to a solution. To add ExecutionManager to a solution:
   • Add the following commands to the CMakeLists.txt root file:
   find_package (execution_manager REQUIRED) include_directories (${execution_manager_INCLUDE}) add_subdirectory (execution_manager)

   The BlobContainer program is required for the ExecutionManager program to work properly. This program is automatically added to a solution when adding ExecutionManager.

   • The ExecutionManager component is provided in the SDK as a set of static libraries and header files, and is built for a specific solution by using the CMake command create_execution_manager_entity() from the CMake library execution_manager.

     To build the ExecutionManager program, create a directory named execution_manager in the root directory of the project. In the new directory, create a CMakeLists.txt file containing the create_execution_manager_entity() command.

     The CMake command create_execution_manager_entity() takes the following parameters:

     Mandatory ENTITY parameter that specifies the name of the executable file for the ExecutionManager program.

     Optional parameters:

     • DEPENDS – additional dependencies for building the ExecutionManager program.
     • MAIN_CONN_NAME – name of the IPC channel for connecting to the ExecutionManager process. It must match the value of the mainConnection variable when calling the ExecutionManager API in the client code.
     • ROOT_PATH – path to the root directory for service files of the ExecutionManager program. The default root path is "/ROOT".
     • VFS_CLIENT_LIB – name of the client transport library used to connect the ExecutionManager program to the VFS program.
   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})
   • When building a solution (CMakeLists.txt file for the Einit program), add the following executable files to the solution image:
     • Executable file of the ExecutionManager program
     • Executable file of the BlobContainer program
2. Link the client executable file to the client proxy library of ExecutionManager by adding the following command to the CMakeLists.txt file for building the client:
   target_link_libraries (<name of the CMake target for building the client> ${execution_manager_EXECMGR_PROXY})
3. Add permissions for the necessary events to the solution security policy description:
   1. To enable the ExecutionManager program to run other processes, the solution security policy must allow the following interactions for the execution_manager.ExecMgrEntity process class:
      • Security events of the execute type for all classes of processes that will be run.
      • Access to all endpoints of the VFS program.
      • Access to all endpoints of the BlobContainer program.
      • Access to the core endpoints Sync, Task, VMM, Thread, HAL, Handle, FS, Notice, CM and Profiler (their descriptions are located in the directory sysroot-*-kos/include/kl/core from the SDK).
   2. To enable a client to call the ExecutionManager program, the solution security policy must allow the following interactions for the client process class:
      • Access to the appropriate endpoints of the ExecutionManager program (their descriptions are located in the directory sysroot-*-kos/include/kl/execution_manager from the SDK).
4. Use of the ExecutionManager program API in the client code.

   Use the header file component/execution_manager/kos_ipc/execution_manager_proxy.h for this. For more details, refer to "ExecutionManager component".

[Topic env_overview]

Overview: Env program

The system program Env is intended for setting startup parameters and environment variables of programs. If the Env program is included in a solution, the processes connected via IPC channel to the Env process will automatically send IPC requests to this program and receive startup parameters and environment variables when these processes are started.

To use the Env program in a solution, you need to do the following:

1. Develop the code of the Env program using the macros and functions from the header file sysroot-*-kos/include/env/env.h from the KasperskyOS SDK.
2. Build the executable file of the Env program by linking it to the env_server library from the KasperskyOS SDK.
3. In the init description, indicate that the Env process must be started and connected to other processes (Env acts as a server in this case). The name of the IPC channel is assigned by the ENV_SERVICE_NAME macro defined in the header file env.h.
4. Include the Env executable file in the solution image.

Source code of the Env program

The source code of the Env program utilizes the following macros and functions from the header file env.h:

• ENV_REGISTER_ARGS(name,argarr) sets the argarr startup parameters for the program that will run in the context of the name process.
• ENV_REGISTER_VARS(name,envarr) sets the envarr environment variables for the program that will run in the context of the name process.
• ENV_REGISTER_PROGRAM_ENVIRONMENT(name,argarr,envarr) sets the argarr startup parameters and envarr environment variables for the program that will run in the context of the name process.
• envServerRun() initializes the server part of the Env program so that it can respond to IPC requests.

Env program usage examples

[Topic using_env_app]

Examples of using Env to set the startup parameters and environment variables of programs

Example of setting startup parameters of a program

Source code of the Env program is presented below. When the process named NetVfs starts, the program passes the following two program startup parameters to this process: -l devfs /dev devfs 0 and -l romfs /etc romfs ro:

env.c

Example of setting environment variables of a program

Source code of the Env program is presented below. When the process named Vfs3 starts, the program passes the following two program environment variables to this process: ROOTFS=ramdisk0,0 / ext2 0 and UNMAP_ROMFS=1:

env.c

[Topic sc_filesystems_and_net]

File systems and network

In KasperskyOS, operations with file systems and the network are executed via a separate system program that implements a virtual file system (VFS).

In the SDK, the VFS component consists of a set of executable files, libraries, formal specification files, and header files. For more details, see the Contents of the VFS component section.

The main scenario of interaction with the VFS system program includes the following:

1. An application connects via IPC channel to the VFS system program and then links to the client library of the VFS component during the build.
2. In the application code, POSIX calls for working with file systems and the network are converted into client library function calls.

   Input and output to file handles for standard I/O streams (stdin, stdout and stderr) are also converted into queries to the VFS. If the application is not linked to the client library of the VFS component, printing to stdout is not possible. If this is the case, you can only print to the standard error stream (stderr), which in this case is performed via special methods of the KasperskyOS kernel without using VFS.

3. The client library makes IPC requests to the VFS system program.
4. The VFS system program receives an IPC requests and calls the corresponding file system implementations (which, in turn, may make IPC requests to device drivers) or network drivers.
5. After the request is handled, the VFS system program responds to the IPC requests of the application.

Using multiple VFS programs

Multiple copies of the VFS system program can be added to a solution for the purpose of separating the data streams of different system programs and applications. You can also separate the data streams within one application. For more details, refer to Using VFS backends to separate data streams.

Adding VFS functionality to an application

The complete functionality of the VFS component can be included in an application, thereby avoiding the need to pass each request via IPC. For more details, refer to Including VFS functionality in a program.

However, use of VFS functionality via IPC enables the solution developer to do the following:

• Use a solution security policy to control method calls for working with the network and file systems.
• Connect multiple client programs to one VFS program.
• Connect one client program to two VFS programs to separately work with the network and file systems.

[Topic vfs_overview]

Contents of the VFS component

The VFS component implements the virtual file system. In the KasperskyOS SDK, the VFS component consists of a set of executable files, libraries, formal specification files and header files that enable the use of file systems and/or a network stack.

VFS libraries

The vfs CMake package contains the following libraries:

• vfs_fs contains implementations of the devfs, ramfs and ROMFS file systems, and adds implementations of other file systems to VFS.
• vfs_net contains the implementation of the devfs file system and the network stack.
• vfs_imp contains the vfs_fs and vfs_net libraries.
• vfs_remote is the client transport library that converts local calls into IPC requests to VFS and receives IPC responses.
• vfs_server is the VFS server transport library that receives IPC requests, converts them into local calls, and sends IPC responses.
• vfs_local is used to include VFS functionality in a program.

VFS executable files

The precompiled_vfs CMake package contains the following executable files:

• VfsRamFs
• VfsSdCardFs
• VfsNet

The VfsRamFs and VfsSdCardFs executable files include the vfs_server, vfs_fs, vfat and lwext4 libraries. The VfsNet executable file includes the vfs_server, vfs_imp libraries.

Each of these executable files has its own default values for startup parameters and environment variables.

Formal specification files and header files of VFS

The sysroot-*-kos/include/kl directory from the KasperskyOS SDK contains the following VFS files:

• Formal specification files VfsRamFs.edl, VfsSdCardFs.edl, VfsNet.edl and VfsEntity.edl, and the header files generated from them.
• Formal specification file Vfs.cdl and the header file Vfs.cdl.h generated from it.
• Formal specification files Vfs*.idl and the header files generated from them.

Libc library API supported by VFS

VFS functionality is available to programs through the API provided by the libc library.

The functions implemented by the vfs_fs and vfs_net libraries are presented in the table below. The * character denotes the functions that are optionally included in the vfs_fs library (depending on the library build parameters).

Functions implemented by the vfs_fs library

Functions implemented by the vfs_net library

[Topic client_and_vfs_ipc_channel]

Creating an IPC channel to VFS

In this example, the Client process uses the file systems and network stack, and the VfsFsnet process handles the IPC requests of the Client process related to the use of file systems and the network stack. This approach is utilized when there is no need to separate data streams related to file systems and the network stack.

The IPC channel name must be assigned by the _VFS_CONNECTION_ID macro defined in the header file sysroot-*-kos/include/vfs/defs.h from the KasperskyOS SDK.

Init description of the example:

init.yaml

[Topic client_and_vfs_linked]

Including VFS functionality in a program

In this example, the Client program includes the VFS program functionality for working with the network stack (see the figure below).

VFS component libraries in a program

The client.c implementation file is compiled and the vfs_local, vfs_implementation and dnet_implementation libraries are linked:

CMakeLists.txt

If the Client program needs to use file systems, you must link the vfs_local and vfs_fs libraries, and link the libraries for implementing these file systems. In this case, you must also add a block device driver to the solution.

[Topic vfs_args_and_envs_overview]

Overview: startup parameters and environment variables of VFS

VFS program startup parameters

• -l <entry in fstab format>

  The startup parameter -l mounts the defined file system.

• -f <path to fstab file>

  The parameter -f mounts the file systems specified in the fstab file. If the UNMAP_ROMFS environment variable is not defined, the fstab file will be sought in the ROMFS image. If the UNMAP_ROMFS environment variable is defined, the fstab file will be sought in the file system defined through the ROOTFS environment variable.

Examples of using VFS program startup parameters

Environment variables of the VFS program

• UNMAP_ROMFS

  If the UNMAP_ROMFS environment variable is defined, the ROMFS image will be deleted from memory. This helps conserve memory. When using the startup parameter -f, it also provides the capability to search for the fstab file in the file system defined through the ROOTFS environment variable instead of searching the ROMFS image.

  Example of using the UNMAP_ROMFS environment variable

• ROOTFS = <entry in fstab format>

  The ROOTFS environment variable mounts the defined file system to the root directory. When using the startup parameter -f, a combination of the ROOTFS and UNMAP_ROMFS environment variables provides the capability to search for the fstab file in the file system defined through the ROOTFS environment variable instead of searching the ROMFS image.

  Example of using the ROOTFS environment variable

• VFS_CLIENT_MAX_THREADS

  The VFS_CLIENT_MAX_THREADS environment variable redefines the SDK configuration parameter VFS_CLIENT_MAX_THREADS.

• VFS_NETWORK_BACKEND=<VFS backend name>:<name of the IPC channel to the VFS process>

  The VFS_NETWORK_BACKEND environment variable defines the VFS backend for working with the network stack. You can specify the name of the standard VFS backend: client (for a program that runs in the context of a client process), server (for a VFS program that runs in the context of a server process) or local, and the name of a custom VFS backend. If the local VFS backend is used, the name of the IPC channel is not specified (VFS_NETWORK_BACKEND=local:). You can specify more than one IPC channel by separating them with a comma.

• VFS_FILESYSTEM_BACKEND=<VFS backend name>:<name of the IPC channel to the VFS process>

  The VFS_FILESYSTEM_BACKEND environment variable defines the VFS backend for working with file systems. The name of the VFS backend and the name of the IPC channel to the VFS process are defined the same way as they are defined in the VFS_NETWORK_BACKEND environment variable.

Default values for startup parameters and environment variables of VFS

For the VfsRamFs executable file:

For the VfsSdCardFs executable file:

For the VfsNet executable file:

[Topic mount_on_start]

Mounting file systems when VFS starts

When the VfsRamFs and VfsSdCardFs programs start, only the RAMFS file system is mounted to the root directory by default. If you need to mount other file systems, this can be done not only by calling the mount() function but also by setting the startup parameters and environment variables of the VFS program.

Using the startup parameter -l

One way to mount a file system is to set the startup parameter -l <entry in fstab format> for the VFS program.

In these examples, the devfs and ROMFS file systems will be mounted when the VFS program is started:

init.yaml.(in)

CMakeLists.txt

Using the fstab file from the ROMFS image

When building a solution, you can add the fstab file to the ROMFS image. This file can be used to mount file systems by setting the startup parameter -f <path to the fstab file> for the VFS program.

In these examples, the file systems defined via the fstab file that was added to the ROMFS image during the solution build will be mounted when the VFS program is started:

init.yaml.(in)

CMakeLists.txt

Using an "external" fstab file

If the fstab file resides in another file system instead of in the ROMFS image, you must set the following startup parameters and environment variables for the VFS program to enable use of this file:

1. ROOTFS. This environment variable mounts the file system containing the fstab file to the root directory.
2. UNMAP_ROMFS. If this environment variable is defined, the fstab file will be sought in the file system defined through the ROOTFS environment variable.
3. -f. This startup parameter is used to mount the file systems specified in the fstab file.

In these examples, the ext2 file system that should contain the fstab file at the path /etc/fstab will be mounted to the root directory when the VFS program starts:

init.yaml.(in)

CMakeLists.txt

[Topic client_and_two_vfs]

Using VFS backends to separate data streams

This example employs a secure development pattern that separates data streams related to file system use from data streams related to the use of a network stack.

The Client process uses file systems and the network stack. The VfsFirst process works with file systems, and the VfsSecond process provides the capability to work with the network stack. The environment variables of programs that run in the contexts of the Client, VfsFirst and VfsSecond processes are used to define the VFS backends that ensure the segregated use of file systems and the network stack. As a result, IPC requests of the Client process that are related to the use of file systems are handled by the VfsFirst process, and IPC requests of the Client process that are related to network stack use are handled by the VfsSecond process (see the figure below).

Process interaction scenario

Init description of the example:

init.yaml

[Topic vfs_backends]

Creating a VFS backend

This example demonstrates how to create and use a custom VFS backend.

The Client process uses the fat32 and ext4 file systems. The VfsFirst process works with the fat32 file system, and the VfsSecond process provides the capability to work with the ext4 file system. The environment variables of programs that run in the contexts of the Client, VfsFirst and VfsSecond processes are used to define the VFS backends ensuring that IPC requests of the Client process are handled by the VfsFirst or VfsSecond process depending on the specific file system being used by the Client process. As a result, IPC requests of the Client process related to use of the fat32 file system are handled by the VfsFirst process, and IPC requests of the Client process related to use of the ext4 file system are handled by the VfsSecond process (see the figure below).

On the VfsFirst process side, the fat32 file system is mounted to the directory /mnt1. On the VfsSecond process side, the ext4 file system is mounted to the directory /mnt2. The custom VFS backend custom_client used on the Client process side sends IPC requests over the IPC channel VFS1 or VFS2 depending on whether or not the file path begins with /mnt1. The custom VFS backend uses the standard VFS backend client as an intermediary.

Process interaction scenario

Source code of the VFS backend

This implementation file contains the source code of the VFS backend custom_client, which uses the standard client VFS backends:

backend.c

Linking the Client program

Creating a static VFS backend library:

CMakeLists.txt

Linking the Client program to the static VFS backend library:

CMakeLists.txt

Setting the startup parameters and environment variables of programs

Init description of the example:

init.yaml

[Topic vfs_net_stack_dyn_conf]

Dynamically configuring the network stack

To change the default network stack parameters, use the sysctl() function or sysctlbyname() function that are declared in the header file sysroot-*-kos/include/sys/sysctl.h from the KasperskyOS SDK. The parameters that can be changed are presented in the table below.

Configurable network stack parameters

MSS configuration example:

[Topic sc_using_ipc]

IPC and transport

[Topic ipc_channels]

Creating IPC channels

IPC channels can be created statically or dynamically.

Statically created IPC channels

Static creation of IPC channel has the following characteristics:

• Creation of an IPC channel is performed by the parent process that starts the client and server (this is normally Einit).
• The client and server are not yet running when the IPC channel is created.
• You cannot create a new IPC channel in place of a deleted one.

The IPC channels defined in the init description are statically created. You can also use the task.h API to statically create IPC channels.

To get the client and server IPC handles and the endpoint ID (RIID), use the sl_api.h API.

Dynamically created IPC channels

Dynamic creation of IPC channels lets you change the topology of interaction between processes on the fly. For example, this is necessary if it is unknown which specific server provides the endpoint required by the client.

Dynamic creation of IPC channel has the following characteristics:

• The IPC channel is jointly created by the client and server.
• The client and server are already running when the IPC channel is created.
• You can create a new IPC channel in place of a deleted one.

To dynamically create IPC channels, use the DCM system program.

If a dynamically created IPC channel is no longer required, its client and server handles can be closed. The IPC channel can be created again if necessary.

[Topic using_sdk_endpoints_examples]

Adding an endpoint from KasperskyOS Community Edition to a solution

To ensure that a Client program can use some specific functionality via the IPC mechanism, the following is required:

1. In KasperskyOS Community Edition, find the executable file (we'll call it Server) that implements the necessary functionality. (The term "functionality" used here refers to one or more endpoints that have their own IPC interfaces.)
2. Include the CMake package containing the Server file and its client library.
3. Add the Server executable file to the solution image.
4. Edit the init description so that when the solution starts, the Einit program starts a new server process from the Server executable file and connects it, using an IPC channel, to the process started from the Client file.

   You must indicate the correct name of the IPC channel so that the transport libraries can identify this channel and find its IPC handles. The correct name of the IPC channel normally matches the name of the server process class. VFS is an exception in this case.

5. Edit the PSL description to allow startup of the server process and IPC interaction between the client and the server.
6. In the source code of the Client program, include the server methods header file.
7. Link the Client program with the client library.

Example of adding a GPIO driver to a solution

KasperskyOS Community Edition includes a gpio_hw file that implements GPIO driver functionality.

The following commands connect the gpio CMake package:

.\CMakeLists.txt

The gpio_hw executable file is added to a solution image by using the gpio_HW_ENTITY variable, whose name can be found in the configuration file of the package at /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/lib/cmake/gpio/gpio-config.cmake:

einit\CMakeLists.txt

The following strings need to be added to the init description:

init.yaml.in

The following strings need to be added to the PSL description:

security.psl.in

In the code of the Client program, you need to include the header file in which the GPIO driver methods are declared:

client.c

Finally, you need to link the Client program with the GPIO client library:

client\CMakeLists.txt

[Topic sc_using_new_endpoints]

Creating and using your own endpoints

[Topic ipc_message_structure_overview]

Overview: IPC message structure

In KasperskyOS, all interactions between processes have statically defined types. The permissible structures of an IPC message are defined by the IDL descriptions of servers.

An IPC message (request and response) contains a constant part and an (optional) arena.

Constant part of an IPC message

The constant part of an IPC message contains the RIID, MID, and (optionally) fixed-size parameters of interface methods.

Fixed-size parameters are parameters that have IDL types of a fixed size.

The RIID and MID identify the interface and method being called:

• The RIID (Runtime Implementation ID) is the sequence number of the utilized endpoint within the set of server endpoints (starting at zero).
• The MID (Method ID) is the sequence number of the called method within the set of methods of the utilized endpoint (starting at zero).

The type of the constant part of the IPC message is generated by the NK compiler based on the IDL description of the interface. A separate structure is generated for each interface method. Union types are also generated for storing any request to a process, component or interface. For more details, refer to Example generation of transport methods and types.

IPC message arena

An IPC message arena (hereinafter also referred to as an arena) contains variable-size parameters of interface methods (and/or elements of these parameters).

Variable-size parameters are parameters that have IDL types of a variable size.

For more details, refer to Working with an IPC message arena.

Maximum IPC message size

The maximum size of an IPC message is determined by the KasperskyOS kernel parameters. On most hardware platforms supported by KasperskyOS, the cumulative size of the constant part and arena of an IPC message cannot exceed 4, 8, or 16 MB.

IPC message structure verification by the security module

Prior to querying IPC message-related rules, the Kaspersky Security Module verifies that the sent IPC message is correct. Requests and responses are both validated. If the IPC message has an incorrect structure, it will be rejected without calling the security model methods associated with it.

Implementation of IPC interaction

To make it easier for a developer to implement IPC interaction, KasperskyOS Community Edition provides the following:

• NK compiler that generates transport methods and types.
• The libkos library that provides the API for working with IPC transport.

Implementation of simple IPC interaction is demonstrated in the echo and ping examples (/opt/KasperskyOS-Community-Edition-<version>/examples/).

[Topic transport_code_overview]

Example generation of transport methods and types

When building a solution, the NK compiler uses the EDL, CDL and IDL descriptions to generate a set of special methods and types that simplify the creation, forwarding, receipt and processing of IPC messages.

As an example, we will examine the Server process class that provides the FS endpoint, which contains a single Open() method:

Server.edl

Operations.cdl

Filesystem.idl

These descriptions will be used to generate the files named Server.edl.h, Operations.cdl.h, and Filesystem.idl.h, which contain the following methods and types:

Methods and types that are common to the client and server

• Abstract interfaces containing the pointers to the implementations of the methods included in them.

  In our example, one abstract interface (Filesystem) will be generated:

  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;
• Set of interface methods.

  When calling an interface method, the corresponding values of the RIID and MID are automatically inserted into the request.

  In our example, a single Filesystem_Open interface method will be generated:

  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)

Methods and types used only on the client

• Types of proxy objects.

  A proxy object is used as an argument in an interface method. In our example, a single Filesystem_proxy proxy object type will be generated:

  typedef struct Filesystem_proxy { struct Filesystem base; struct nk_transport *transport; nk_iid_t iid; } Filesystem_proxy;
• Functions for initializing proxy objects.

  In our example, the single initializing function Filesystem_proxy_init will be generated:

  void Filesystem_proxy_init(struct Filesystem_proxy *self, struct nk_transport *transport, nk_iid_t iid)
• Types that define the structure of the constant part of a message for each specific method.

  In our example, two such types will be generated: Filesystem_Open_req (for a request) and Filesystem_Open_res (for a response).

  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;

Methods and types used only on the server

• Type containing all endpoints of a component, and the initializing function. (For each server component.)

  If there are embedded components, this type also contains their instances, and the initializing function takes their corresponding initialized structures. Therefore, if embedded components are present, their initialization must begin with the most deeply embedded component.

  In our example, the Operations_component structure and Operations_component_init function will be generated:

  typedef struct Operations_component { struct Filesystem *FS; }; void Operations_component_init(struct Operations_component *self, struct Filesystem *FS)
• Type containing all endpoints provided directly by the server; all instances of components included in the server; and the initializing function.

  In our example, the Server_entity structure and Server_entity_init function will be generated:

  #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)
• Types that define the structure of the constant part of a message for any method of a specific interface.

  In our example, two such types will be generated: Filesystem_req (for a request) and Filesystem_res (for a response).

  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; };
• Types that define the structure of the constant part of a message for any method of any endpoint of a specific component.

  If embedded components are present, these types also contain structures of the constant part of a message for any method of any endpoint included in all embedded components.

  In our example, two such types will be generated: Operations_component_req (for a request) and Operations_component_res (for a response).

  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;
• Types that define the structure of the constant part of a message for any method of any endpoint of a specific component whose instance is included in the server.

  If embedded components are present, these types also contain structures of the constant part of a message for any method of any endpoint included in all embedded components.

  In our example, two such types will be generated: Server_entity_req (for a request) and Server_entity_res (for a response).

  #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 methods (dispatchers) for a separate interface, component, or process class.

  Dispatchers analyze the received query (the RIID and MID values), call the implementation of the corresponding method, and then save the response in the buffer. In our example, three dispatchers will be generated: Filesystem_interface_dispatch, Operations_component_dispatch, and Server_entity_dispatch.

  The process class dispatcher handles the request and calls the methods implemented by this class. If the request contains an incorrect RIID (for example, an RIID for a different endpoint that this process class does not have) or an incorrect MID, the dispatcher returns NK_EOK or 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)

  In special cases, you can use dispatchers of the interface and the component. They take an additional argument: interface implementation ID (nk_iid_t). The request will be handled only if the passed argument and RIID from the request match, and if the MID is correct. Otherwise, the dispatchers return NK_EOK or 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]

Working with an IPC message arena

Arena overview

From the perspective of a developer of KasperskyOS-based solutions, an IPC message arena is a byte buffer in the memory of a process intended for storing variable-size data transmitted over IPC. This variable-size data includes input parameters, output parameters, and error parameters of interface methods (and/or elements of these parameters) that have variable-size IDL types. An arena is also used when querying the Kaspersky Security Module to store input parameters of security interface methods (and/or elements of these parameters) that have variable-size IDL types. (Parameters of fixed-size interface methods are stored in the constant part of an IPC message.) Arenas are used on the client side and on the server side. One arena is intended either for transmitting or for receiving variable-size data through IPC, but not for both transmitting and receiving this data at the same time. In other words, arenas can be divided into IPC request arenas (containing input parameters of interface methods) and IPC response arenas (containing output parameters and error parameters of interface methods).

Only the utilized part of an arena that is occupied by data is transmitted over IPC. (If it has no data, the arena is not transmitted.) The utilized part of an arena includes one or more segments. One segment of an arena stores an array of same-type objects, such as an array of single-byte objects or an array of structures. Arrays of different types of objects may be stored in different segments of an arena. The starting address of an arena must be equal to the boundary of a 2^N-byte sequence, where 2^N is a value that is greater than or equal to the size of the largest primitive type in the arena (for example, the largest field of a primitive type in a structure). The address of an arena chunk must also be equal to the boundary of a 2^N-byte sequence, where 2^N is a value that is greater than or equal to the size of the largest primitive type in the arena chunk.

An arena must have multiple segments if the interface method has multiple variable-size input, output, or error parameters, or if multiple elements of input, output, or error parameters of the interface method have a variable size. For example, if an interface method has an input parameter of the sequence IDL type and an input parameter of the bytes IDL type, the IPC request arena will have at least two segments. In this case, it may even require additional segments if a parameter of the sequence IDL type consists of elements of a variable-size IDL type (for example, if elements of a sequence are string buffers). As another example, if an interface method has one output parameter of the struct IDL type that contains two fields of the bytes and string type, the IPC response arena will have two segments.

Due to the alignment of arena chunk addresses, there may be unused intervals between these chunks. Therefore, the size of the utilized part of an arena may exceed the size of the data it contains.

API for working with an arena

The set of functions and macros for working with an arena is defined in the header file sysroot-*-kos/include/nk/arena.h from the KasperskyOS SDK. In addition, the function for copying a string to an arena is declared in the header file sysroot-*-kos/include/coresrv/nk/transport-kos.h from the KasperskyOS SDK.

Information on the functions and macros defined in the header file sysroot-*-kos/include/nk/arena.h is provided in the table below. In these functions and macros, an arena and arena chunk are identified by an arena descriptor (the nk_arena type) and an arena chunk descriptor (the nk_ptr_t type), respectively. An arena descriptor is a structure containing three pointers: one pointer to the start of the arena, one pointer to the start of the unused part of the arena, and one pointer to the end of the arena. An arena chunk descriptor is a structure containing the offset of the arena chunk in bytes (relative to the start of the arena) and the size of the arena chunk in bytes. (The arena chunk descriptor type is defined in the header file sysroot-*-kos/include/nk/types.h from the KasperskyOS SDK.)

Creating an arena

To pass variable-size parameters of interface methods over IPC, you must create arenas on the client side and on the server side. (When IPC requests are handled on the server side using the NkKosDoDispatch() or NkKosDoDispatchEx() functions declared in the header file sysroot-*-kos/include/coresrv/nk/transport-kos-dispatch.h from the KasperskyOS SDK, the IPC request arena and IPC response arena are created automatically.)

To create an arena, you must create a buffer (in the stack or heap) and initialize the arena descriptor.

The address of the buffer must be aligned to comply with the maximum size of a primitive type that can be put into this buffer. The address of a dynamically created buffer usually has adequate alignment to hold the maximum amount of data of the primitive type. To ensure the required alignment of the address of a statically created buffer, you can use the alignas specifier.

To initialize an arena descriptor using the pointer to an already created buffer, you must use an API function or macro:

• NK_ARENA_INITIALIZER() macro
• nk_arena_init() function
• nk_arena_create() function
• NK_ARENA_FINAL() macro
• nk_arena_init_final() macro

The type of pointer makes no difference because this pointer is converted into a pointer to a single-byte object in the code of API functions and macros.

The NK_ARENA_INITIALIZER() macro and the nk_arena_init() and nk_arena_create() functions initialize such arena descriptor that may contain one or more segments. The NK_ARENA_FINAL() and nk_arena_init_final() macros initialize the descriptor of this arena, which contains only one chunk spanning the entire arena throughout its entire lifetime.

To create a buffer in the stack and initialize the arena descriptor in one step, use the NK_ARENA_AUTO() macro. This macro creates an arena that may contain one or more segments, and the address of the buffer created by this macro has adequate alignment to hold the maximum amount of data of the primitive type.

The size of an arena must be sufficient to hold variable-size parameters for IPC requests or IPC responses of one interface method or a set of interface methods corresponding to one interface, component, or process class while accounting for the alignment of segment addresses. Automatically generated transport code (the header files *.idl.h, *.cdl.h, and *.edl.h) contain *_arena_size constants whose values are guaranteed to comply with sufficient sizes of arenas in bytes.

The header files *.idl.h, *.cdl.h, and *.edl.h contain the following *_arena_size constants:

• <interface name>_<interface method name>_req_arena_size – size of an IPC request arena for the specified interface method of the specified interface
• <interface name>_<interface method name>_res_arena_size – size of an IPC response arena for the specified interface method of the specified interface
• <interface name>_req_arena_size – size of an IPC request arena for any interface method of the specified interface
• <interface name>_res_arena_size – size of an IPC response arena for any interface method of the specified interface

The header files *.cdl.h and *.edl.h also contain the following *_arena_size constants:

• <component name>_component_req_arena_size – size of an IPC request arena for any interface method of the specified component
• <component name>_component_res_arena_size – size of an IPC response arena for any interface method of the specified component

The *.edl.h header files also contain the following *_arena_size constants:

• <process class name>_entity_req_arena_size – size of an IPC request arena for any interface method of the specified process class
• <process class name>_entity_res_arena_size – size of an IPC response arena for any interface method of the specified process class

Constants containing the size of an IPC request arena or IPC response arena for one interface method (<interface name>_<interface method name>_req_arena_size and <interface name>_<interface method name>_res_arena_size) are intended for use on the client side. All other constants can be used on the client side and on the server side.

Examples of creating an arena:

Adding data to an arena before transmission over IPC

Before transmitting an IPC request on the client side or an IPC response on the server side, data must be added to the arena. If the NK_ARENA_FINAL() macro or the nk_arena_init_final() macro is used to create an arena, you do not need to reserve an arena chunk. Instead, you only need to add data to this chunk. If the NK_ARENA_INITIALIZER() or NK_ARENA_AUTO() macro, or the nk_arena_init() or nk_arena_create() function is used to create an arena, one or multiple segments in the arena must be reserved to hold data. To reserve an arena chunk, you must use an API function or macro:

• nk_arena_alloc_aligned() macro
• nk_arena_alloc() macro
• nk_arena_store_aligned() macro
• nk_arena_store() macro
• NkKosCopyStringToArena() function

The arena chunk descriptor, which is passed through the output parameter of these macros and functions and through the output parameter of the NK_ARENA_FINAL() and nk_arena_init_final() macros, must be put into the constant part or into the arena of an IPC message. If an interface method has a variable-size parameter, the constant part of IPC messages contains arena chunk descriptor containing the parameter instead of the actual parameter. If an interface method has a fixed-size parameter with variable-size elements, the constant part of IPC messages contains arena chunk descriptors containing the parameter elements instead of the actual parameter elements. If an interface method has a variable-size parameter containing variable-size elements, the constant part of IPC messages contains arena chunk descriptor containing the descriptors of other arena chunks that contain these parameter elements.

The nk_arena_store_aligned() and nk_arena_store() macros and the NkKosCopyStringToArena() function not only reserve an arena chunk, but also copy data to this chunk.

The nk_arena_alloc_aligned() and nk_arena_alloc() macros get the address of a reserved arena chunk. You can also get an arena chunk address by using the nk_arena_get() macro, which additionally uses the output parameter to pass the quantity of objects accommodated in this chunk.

A reserved arena chunk can be reduced. To do so, you need to use the nk_arena_shrink() macro.

To undo a current reservation of arena chunks so that new chunks can be reserved for other data (after sending an IPC message), call the nk_arena_reset() function. If the NK_ARENA_FINAL() macro or nk_arena_init_final() macro is used to create an arena, you do not need to undo a segment reservation because the arena contains one segment spanning the entire arena throughout its entire life cycle.

Examples of adding data to an arena:

Retrieving data from an arena after receipt over IPC

Prior to receiving an IPC request on the server side or an IPC response on the client side for an arena that will store the data received over IPC, you must undo the current reservation of segments by calling the nk_arena_reset() function. This must be done even if the NK_ARENA_FINAL() macro or the nk_arena_init_final() macro is used to create the arena. (The NK_ARENA_INITIALIZER() and NK_ARENA_AUTO() macros, and the nk_arena_init() and nk_arena_create() functions create an arena without reserved segments. You do not need to call the nk_arena_reset() function if this arena will only be used once to save data received over IPC.)

You do not need to free the currently reserved arena chunks if one of the syscalls.h API functions is directly used to receive an IPC message. However, you must do that prior to calling transport code methods on the client side and the nk_transport_recv() function on the server side. (The nk_transport_recv() function is declared in the header file sysroot-*-kos/include/nk/transport.h from the KasperskyOS SDK.)

When calling the NkKosTransport_Dispatch() function declared in the header file sysroot-*-kos/include/coresrv/nk/transport-kos.h from the KasperskyOS SDK, you must specify arenas that do not have reserved chunks. If the NK_ARENA_FINAL() or nk_arena_init_final() macro is used to create these arenas, call the nk_arena_reset() function to free the reserved chunks.

To get pointers to arena chunks and the quantity of objects accommodated in these chunks, you must use the nk_arena_get() macro while using the input parameter to pass the corresponding arena chunk descriptors received from the constant part and arena of the IPC message.

Example of receiving data from an arena:

Additional capabilities of the API

To get the arena size, call the nk_arena_capacity() function.

To get the size of the utilized part of the arena, call the nk_arena_allocated_size() function.

To verify that the arena chunk descriptor is correct, use the nk_arena_validate() macro.

Information about API functions and macros

Functions and macros of arena.h

[Topic cpp_proxy_stubs]

Transport code in C++

Implementation of interprocess interaction requires transport code, which is responsible for generating, sending, receiving, and processing IPC messages.

However, a developer of a KasperskyOS-based solution does not have to write their own transport code. Instead, you can use the special tools and libraries included in the KasperskyOS SDK. These libraries enable a solution component developer to generate transport code based on IDL, CDL and EDL descriptions related to this component.

Transport code

The KasperskyOS SDK includes the nkppmeta compiler for generating transport code in C++.

The nkppmeta compiler lets you generate transport C++ proxy objects and stubs for use by both a client and a server.

Proxy objects are used by the client to pack the parameters of the called method into an IPC request, execute the IPC request, and unpack the IPC response.

Stubs are used by the server to unpack the parameters from the IPC request, dispatch the call to the appropriate method implementation, and pack the IPC response.

Generating transport code for development in C++

The CMake commands add_nk_idl(), add_nk_cdl() and add_nk_edl() are used to generate transport proxy objects and stubs using the nkppmeta compiler when building a solution.

C++ types in the *.idl.cpp.h file

Each interface is defined in an IDL description. This description defines the interface name, signatures of interface methods, and data types for the parameters of interface methods.

The CMake command add_nk_idl() is used to generate transport code when building a solution. This command creates a CMake target for generating header files for the defined IDL file when using the nkppmeta compiler.

The generated header files contain a C++ representation for the interface and data types described in the IDL file, and the methods required for use of proxy objects and stubs.

The mapping of data types declared in an IDL file to C++ types are presented in the table below.

Mapping IDL types to C++ types