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.