About KasperskyOS Community Edition

KasperskyOS Community Edition (CE) is a publicly available version of KasperskyOS 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 and C++ languages. For more details about setting up the development environment, see "Configuring the development environment".

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.

About this Guide

The KasperskyOS Community Edition Developer's Guide is intended for specialists involved in the development of secure solutions based on KasperskyOS.

The Guide is designed for specialists who know the C/C++ programming languages, have experience developing for POSIX-compatible systems, and are familiar with GNU Binary Utilities (binutils).

You can use the information in this Guide to:

• Install and remove KasperskyOS Community Edition.
• Use KasperskyOS Community Edition.

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 (GCC compiler, LD linker, binutils toolset, 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".

System requirements

To install KasperskyOS Community Edition and run examples on QEMU, the following is required:

1. Operating system: Ubuntu GNU/Linux 22.04 (Jammy Jellyfish). A Docker container can be used.
2. Processor: x86-64 architecture (support for hardware virtualization is required for higher performance).
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 3 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.1, 1.2, 1.4, 1.5) with 2, 4, or 8 GB of RAM
• MicroSD card with at least 2 GB
• USB-UART converter

Included third-party libraries and applications

To simplify the application development process, 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.13 and 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

• autotools-wrappers (v.am-10) is a wrapper for the Autoconf and Automake tools that determines which installed version of a tool is suitable for automatically configuring and building software.

  Documentation: https://gitweb.gentoo.org/proj/autotools-wrappers.git/tree

• Libtool (v.2.4.2) 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.38) 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

• GNU Compiler Collection (GCC) (v.9.2.1) is a set of compilers for various programming languages, including C and C ++.

  Documentation: https://gcc.gnu.org/onlinedocs

• QEMU (v.8.1.3) 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.78.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.11) 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.1.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.3.0) 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.13.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.6.0) 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

See also Information about third-party code.

Limitations and known issues

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

1. The maximum supported number of running programs is 32.
2. 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.
3. You cannot start two or more programs that have the same EDL description.
4. The system stops if no running programs remain, or if one of the driver program threads has been terminated, whether normally or abnormally.
5. 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.

Migrating application code from SDK version 1.1.1 to SDK version 1.2

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

Required changes:

1. The SDK now includes a driver for working with the VideoCore (VC6) coprocessor via mailbox technology: kl.drivers.Bcm2711MboxArmToVc. The kl.drivers.DNetSrv and kl.drivers.USB drivers require access to this new driver.
   • If the init.yaml.in template is used to create the solution init description (init.yaml file) and the @INIT_ProgramName_ENTITY_CONNECTIONS+@ or @INIT_ProgramName_ENTITY_CONNECTIONS@ macros were used for the kl.drivers.DNetSrv and kl.drivers.USB processes, no changes to the init description are required.

     Otherwise, if IPC channels for the kl.drivers.DNetSrv and kl.drivers.USB processes are manually specified, you must add the kl.drivers.Bcm2711MboxArmToVc process to the init description and define the IPC channels between it and the kl.drivers.DNetSrv and kl.drivers.USB processes:

   - name: kl.drivers.Bcm2711MboxArmToVc path: bcm2711_mbox_arm2vc_h - name: kl.drivers.USB path: usb connections: ... - target: kl.drivers.Bcm2711MboxArmToVc id: kl.drivers.Bcm2711MboxArmToVc - name: kl.drivers.DNetSrv path: dnet_entity connections: ... - target: kl.drivers.Bcm2711MboxArmToVc id: kl.drivers.Bcm2711MboxArmToVc
   • You must add the kl.drivers.Bcm2711MboxArmToVc process to the security.psl file and allow the kl.drivers.DNetSrv and kl.drivers.USB processes and the kernel to interact with it:
   ... use kl.drivers.Bcm2711MboxArmToVc._ ... execute src = Einit dst = kl.drivers.Bcm2711MboxArmToVc { grant () } request src = kl.drivers.Bcm2711MboxArmToVc dst = kl.core.Core { grant () } response src = kl.core.Core dst = kl.drivers.Bcm2711MboxArmToVc { grant () } request src = kl.drivers.DNetSrv dst = kl.drivers.Bcm2711MboxArmToVc { grant () } response src = kl.drivers.Bcm2711MboxArmToVc dst = kl.drivers.DNetSrv { grant () } request src = kl.drivers.USB dst = kl.drivers.Bcm2711MboxArmToVc { grant () } response src = kl.drivers.Bcm2711MboxArmToVc dst = kl.drivers.USB{ grant () }
2. All implementations of the VFS component now require access to the kl.EntropyEntity program.
   • If the init.yaml.in template is used to create the solution init description (init.yaml file) and the @INIT_ProgramName_ENTITY_CONNECTIONS+@ or @INIT_ProgramName_ENTITY_CONNECTIONS@ macros were used for processes that use the VFS component (the kl.VfsNet, kl.VfsRamFs, and kl.VfsSdCardFs processes as well as the processes that statically include VFS), no changes to the init description are required.

     Otherwise, if IPC channels for processes that use the VFS component are manually specified, you must add the kl.EntropyEntity process to the init description and define the IPC channels between it and the processes that use the VFS component:

   - name: kl.VfsSdCardFs path: VfsSdCardFs connections: ... - target: kl.EntropyEntity id: kl.EntropyEntity - name: kl.VfsNet path: VfsNet connections: ... - target: kl.EntropyEntity id: kl.EntropyEntity - name: kl.ProgramWithEmbeddedVfs path: ProgramWithEmbedVfs connections: ... - target: kl.EntropyEntity id: kl.EntropyEntity - name: kl.EntropyEntity path: Entropy
   • You must add the kl.EntropyEntity process to the security.psl file and allow the kernel and processes that use the VFS component to interact with it:
   ... use kl.EntropyEntity._ ... execute src = Einit dst = kl.drivers.EntropyEntity { grant () } ... request src = kl.EntropyEntity dst = kl.core.Core { grant () } response src = kl.core.Core dst = kl.EntropyEntity { grant () } request src = kl.VfsNet dst = kl.EntropyEntity { grant () } response src = kl.EntropyEntity dst = kl.VfsNet { grant () } request src = kl.VfsSdCardFs dst = kl.EntropyEntity { grant () } response src = kl.EntropyEntity dst = kl.VfsSdCardFs { grant () } request src = kl.ProgramWithEmbeddedVfs dst = kl.EntropyEntity { grant () } response src = kl.EntropyEntity dst = kl.ProgramWithEmbeddedVfs { grant () }
3. The kl.drivers.USB driver now requires access to the kl.core.NameServer program.
   • If the init.yaml.in template is used to create the solution init description (init.yaml file) and the @INIT_ProgramName_ENTITY_CONNECTIONS+@ or @INIT_ProgramName_ENTITY_CONNECTIONS@ macros were used for the kl.drivers.USB process, no changes to the init description are required.

     Otherwise, if IPC channels for the kl.drivers.USB process are manually specified, you must add the kl.core.NameServer process to the init description and define the IPC channels between it and the kl.drivers.USB process:

   - name: kl.core.NameServer path: ns - name: kl.drivers.USB path: usb connections: ... - target: kl.core.NameServer id: kl.core.NameServer
   • You must add the kl.core.NameServer process to the security.psl file and allow the kl.drivers.USB process and the kernel to interact with it:
   ... use kl.core.NameServer ... execute src = Einit dst = kl.core.NameServer { grant () } ... request src = kl.core.NameServer dst = kl.core.Core { grant () } response src = kl.core.Core dst = kl.core.NameServer { grant () } request src = kl.drivers.USB dst = kl.core.NameServer { grant () } response src = core.NameServer dst = kl.drivers.USB { grant () }
4. The capability to use dynamic libraries has been added to the SDK. Now all solutions are built using dynamic linking by default. This may affect the build of solutions containing libraries that have both static and dynamic variants.
   • To include enforced static linking of executable files, replace initialize_platform() with initialize_platform (FORCE_STATIC) in the root CMakeLists.txt of the project.
   • To switch from static linking to dynamic linking, you must complete additional steps as described in the article titled Using dynamic libraries.
   • To use dynamic libraries, your solution must include the system program BlobContainer.
   • You must add the kl.bc.BlobContainer process to the security.psl file and allow processes that use dynamic libraries to interact with it:
   ... use kl.bc.BlobContainer ... execute src = Einit dst = kl.bc.BlobContainer { grant () } request { /* Allows tasks with the kl.bc.BlobContainer class to send requests to specified tasks. */ match src = kl.bc.BlobContainer { match dst = kl.core.Core { grant () } match dst = kl.VfsSdCardFs { grant () } } /* Allows task with the kl.bc.BlobContainer class to recive request from any task. */ match dst = kl.bc.BlobContainer { grant () } } response { /* Allows tasks with the kl.bc.BlobContainer class to get responses from specified tasks. */ match dst = kl.bc.BlobContainer { match src = kl.core.Core { grant () } match src = kl.VfsSdCardFs { grant () } } /* Allows task with the kl.bc.BlobContainer class to send response to any task. */ match src = kl.bc.BlobContainer { grant () } }

   You can move the permissions for kl.bc.BlobContainer operations to a separate PSL file and include this file in the solution. (see the secure_logger example in the SDK).

5. The romfs file system can now be mounted only in read-only mode.
   • When mounting romfs in C/C++ code using the mount() function, you must pass the MS_RDONLY flag.
   • You must also make changes to the command-line arguments of the VFS program in the init description or in the CMakeLists.txt file for building the Einit program.

   Example of mounting the romfs file system in the init.yaml file:

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

   Example of mounting the romfs file system in the CMakeLists.txt file:

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