[Topic whats_new]

What's new

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 community_edition]

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.

[Topic about_this_document]

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.

[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 (GCC compiler, LD linker, GDB debugger, 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 Debian 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 KasperskyOS Community Edition and run examples on QEMU, the following is required:

1. Operating system: Debian GNU/Linux 10 "Buster". 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

[Topic included_third_party_libs]

Included third-party libraries and applications

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

• Automated Testing Framework (ATF) (v.0.20) – 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/

• Arm Mbed TLS (v.2.28.0) implements the TLS and SSL protocols as well as the corresponding encryption algorithms and necessary support code.

  Documentation: https://github.com/Mbed-TLS/mbedtls

• 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

• FFmpeg (v.5.1) – set of libraries with open source code that let you write, convert, and transmit digital audio- and video recordings in various formats.

  Documentation: https://ffmpeg.org/ffmpeg.html

• fmt (v.8.1.1) – open-source formatting library.

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

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

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

• iperf (v.3.10.1) – network performance testing library.

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

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

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

• libjpeg-turbo (v.2.0.91) – library for working with JPEG images.

  Documentation: https://libjpeg-turbo.org/

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

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

• libpng (v.1.6.38) – library for working with PNG images.

  Documentation: http://www.libpng.org/pub/png/libpng.html

• libxml2 (v.2.9.14) – library for working with XML.

  Documentation: http://xmlsoft.org/

• Eclipse Mosquitto (v2.0.14) – message broker that implements the MQTT protocol.

  Documentation: https://mosquitto.org/documentation/

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

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

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

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

• opencv (v.4.6.0) – open-source computer vision library.

  Documentation: https://docs.opencv.org/

• OpenSSL (v.1.1.1q) – full-fledged open-source encryption library.

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

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

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

• protobuf (v.3.19.4) – data serialization library.

  Documentation: https://developers.google.com/protocol-buffers/docs/overview

• spdlog (v.1.9.2) – logging library.

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

• sqlite (v.3.39.2) – library for working with databases.

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

• Zlib (v.1.2.12) – data compression library.

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

• usb (v.13.0.0) – 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) – library for working with evdev peripheral devices.

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

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

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

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

[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 solution security policy is described by a specially developed language known as PSL (Policy Specification Language). 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).

Transport code is generated by the nk-gen-c compiler from declarative descriptions in IDL (Interface Definition Language), CDL (Component Definition Language), and EDL (Entity Definition Language), respectively (for details, see Formal specifications of KasperskyOS-based solution components).

Source code of the Kaspersky Security Module is generated by the nk-psl-gen-c compiler from the solution security policy description and the IDL, CDL and EDL descriptions.

Source code of the initializing program is generated by the einit tool from the solution initialization description (in YAML format) and the IDL, CDL and EDL descriptions.

[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

Page top

[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 endpoint ID (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 involves the creation of IPC channels when the solution is started. IPC channels are created statically by the initializing program.
2. The dynamic mechanism allows already running processes to establish 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 contents 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 interaction between processes requires transport code, which is responsible for properly creating, packing, sending, and unpacking 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 lets you generate 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 (SID)

The KasperskyOS kernel assigns security identifiers to system resources and user resources. A security identifier (SID) is a global unique ID 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.

Handle permissions mask structure

A handle permissions mask has a size of 32 bits and consists of a general part and a specialized part. The general part describes the general rights that are not specific to any particular resource (the flags of these rights are defined in the services/ocap.h header file). For example, the general part contains the OCAP_HANDLE_TRANSFER flag, which defines the permission to transfer the handle. The specialized part describes the rights that are specific to the particular user resource or system resource. The flags of the specialized part's permissions for system resources are defined in the services/ocap.h header file. The structure of the specialized part for user resources is defined by the resource provider by using the OCAP_HANDLE_SPEC() macro that is defined in the services/ocap.h header file. The resource provider must export the public header files describing the structure of the specialized part.

When the handle of a system resource is created, the permissions mask is defined by the KasperskyOS kernel, which applies permissions masks from the services/ocap.h header file. It applies permissions masks with names such as OCAP_*_FULL (for example, OCAP_IOPORT_FULL, OCAP_TASK_FULL, OCAP_FILE_FULL) and OCAP_IPC_* (for example, OCAP_IPC_SERVER, OCAP_IPC_LISTENER, OCAP_IPC_CLIENT).

When the handle of a user resource is created, the permissions mask is defined by the user.

When a handle is transferred, the permissions mask is defined by the user but the transferred access rights cannot be elevated above the access rights of the process.

[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, 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 all other programs that are part of the solution.

[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 Debian "Buster" 10.12 operating system from the public Docker Hub repository, run the following command:

   docker pull debian:10.12

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

   docker run --net=host --user root --privileged -it --rm debian:10.12 bash

4. Copy the DEB package for installation of KasperskyOS Community Edition into the container.
5. Install KasperskyOS Community Edition.
6. To ensure correct operation of certain examples:
   1. Add the /usr/sbin directory to the PATH environment variable within the container by running the following command:

      export PATH=/usr/sbin:$PATH

   2. Install the parted program within the container. To do so, add the following string to /etc/apt/sources.list:

      deb http://deb.debian.org/debian bullseye main

      After this, run the following command:

      sudo apt update && sudo apt install parted

[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 with root privileges:

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

For convenient operation, you can add the path to the KasperskyOS Community Edition tools binaries to the PATH variable. This will allow you to use the tools via the terminal from any folder:

Removal

To remove KasperskyOS Community Edition, run the following command with root privileges:

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 solutions based on KasperskyOS:

• Install code editor extensions and plugins for your programming language (C and/or C++).
• 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-aarch64-kos/include.

Example of how to configure Visual Studio Code

For example, during KasperskyOS development, you can work with source code in Visual Studio Code.

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-aarch64-kos/include.
6. Close the C/C++ Configurations window.

[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 cross-build.sh creates a KasperskyOS-based solution image that includes the example. 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

To build an example:

1. Go to the directory with the example.
2. Open the cross-build.sh script file in a text editor.
3. In the last line of the script file, replace the make sim command with make kos-image.
4. Save the script file and then run the command:

   $ ./cross-build.sh

Running cross-build.sh 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.

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

Additional QEMU parameters must be used to run certain examples. The commands used to run these examples are provided in the descriptions of these examples.

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 of the examples on the computer:

1. Connect the pins of the FT232 USB-UART converter to the corresponding GPIO pins of the Raspberry Pi 4 B (see the figure below).

   

   Diagram for connecting the USB-UART converter and Raspberry Pi 4 B

2. Connect the computer's USB port to the USB-UART converter.
3. Install PuTTY or a similar program for reading data from a COM port. Configure the settings as follows: bps = 115200, data bits = 8, stop bits = 1, parity = none, flow control = none.

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

A bootable SD card for Raspberry Pi 4 B can be prepared automatically or manually.

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. 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 xz-utils device-tree-compiler

   $ git clone https://github.com/u-boot/u-boot.git u-boot-armv8

   # For Raspberry Pi 4 B revisions 1.1 and 1.2 only:

   $ cd u-boot-armv8 && git checkout tags/v2020.10

   # For Raspberry Pi 4 B revisions 1.4 and 1.5 only:

   $ cd u-boot-armv8 && git checkout tags/v2022.01

   # For all Raspberry Pi revisions:

   $ make ARCH=arm CROSS_COMPILE=aarch64-linux-gnu- rpi_4_defconfig

   # In the menu that appears when you run the following command,

   # in the 'Boot options' section, change the value in the 'bootcmd value' field to the following:

   # fatload mmc 0 ${loadaddr} kos-image; bootelf ${loadaddr},

   # and delete the value "usb start;" in the 'preboot default value' field.

   # Exit the menu after saving the settings.

   $ make ARCH=arm CROSS_COMPILE=aarch64-linux-gnu- menuconfig

   $ make ARCH=arm CROSS_COMPILE=aarch64-linux-gnu- u-boot.bin

2. Prepare the image containing the file system for the SD card. To do this, connect the SD card to the computer and run the following commands:

   # For Raspberry Pi 4 B revisions 1.1 and 1.2 only:

   $ wget https://downloads.raspberrypi.org/raspbian_lite/images/raspbian_lite-2020-02-14/2020-02-13-raspbian-buster-lite.zip

   $ unzip 2020-02-13-raspbian-buster-lite.zip

   $ loop_device=$(sudo losetup --find --show --partscan 2020-02-13-raspbian-buster-lite.img)

   # For Raspberry Pi 4 B revision 1.4 only:

   $ wget https://downloads.raspberrypi.org/raspios_lite_arm64/images/raspios_lite_arm64-2022-04-07/2022-04-04-raspios-bullseye-arm64-lite.img.xz

   $ unxz 2022-04-04-raspios-bullseye-arm64-lite.img.xz

   $ loop_device=$(sudo losetup --find --show --partscan 2022-04-04-raspios-bullseye-arm64-lite.img)

   # For Raspberry Pi 4 B revision 1.5 only:

   $ wget https://downloads.raspberrypi.org/raspios_lite_arm64/images/raspios_lite_arm64-2022-09-07/2022-09-06-raspios-bullseye-arm64-lite.img.xz

   $ unxz 2022-09-06-raspios-bullseye-arm64-lite.img.xz

   $ loop_device=$(sudo losetup --find --show --partscan 2022-09-06-raspios-bullseye-arm64-lite.img)

   # For all Raspberry Pi revisions:

   # Image will contain a boot partition of 1 GB in fat32 and 3 partitions of 256 MB each in ext2, ext3 and ext4, respectively:

   $ sudo parted ${loop_device} rm 2

   $ sudo parted ${loop_device} resizepart 1 1G

   $ sudo parted ${loop_device} mkpart primary ext2 1000 1256M

   $ sudo parted ${loop_device} mkpart primary ext3 1256 1512M

   $ sudo parted ${loop_device} mkpart primary ext4 1512 1768M

   $ sudo mkfs.ext2 ${loop_device}p2

   $ sudo mkfs.ext3 ${loop_device}p3

   $ sudo mkfs.ext4 -O ^64bit,^extent ${loop_device}p4

   $ sudo losetup -d ${loop_device}

   # In the following command, [X] is the last symbol in the name of the block device

   # for the SD card.

   $ sudo dd bs=64k if=$(ls *rasp*lite.img) of=/dev/sd[X] conv=fsync

3. Copy the U-Boot bootloader to the SD card by running the following commands:

   # In the following commands, the path ~/mnt/fat32 is just an example. You

   # can use a different path.

   $ mkdir -p ~/mnt/fat32

   # In the following command, [X] is the last alphabetic character in the name of the block

   # device for the partition on the formatted SD card.

   $ sudo mount /dev/sd[X]1 ~/mnt/fat32/

   $ sudo cp u-boot.bin ~/mnt/fat32/u-boot.bin

   # For Raspberry Pi 4 B revision 1.5 only:

   # In the following commands, the path ~/tmp_dir is just an example. You

   # can use a different path.

   $ mkdir -p ~/tmp_dir

   $ cp ~/mnt/fat32/bcm2711-rpi-4-b.dtb ~/tmp_dir

   $ dtc -I dtb -O dts -o ~/tmp_dir/bcm2711-rpi-4-b.dts ~/tmp_dir/bcm2711-rpi-4-b.dtb && \

   $ sed -i -e "0,/emmc2bus = /s/emmc2bus =.*//" ~/tmp_dir/bcm2711-rpi-4-b.dts && \

   $ sed -i -e "s/dma-ranges = <0x00 0xc0000000 0x00 0x00 0x40000000>;/dma-ranges = <0x00 0x00 0x00 0x00 0xfc000000>;/" ~/tmp_dir/bcm2711-rpi-4-b.dts && \

   $ sed -i -e "s/mmc@7e340000 {/mmc@7e340000 {\n\t\t\tranges = <0x00 0x7e000000 0x00 0xfe000000 0x1800000>;\n dma-ranges = <0x00 0x00 0x00 0x00 0xfc000000>;/" ~/tmp_dir/bcm2711-rpi-4-b.dts && \

   $ dtc -I dts -O dtb -o ~/tmp_dir/bcm2711-rpi-4-b.dtb ~/tmp_dir/bcm2711-rpi-4-b.dts

   $ sudo cp ~/tmp_dir/bcm2711-rpi-4-b.dtb ~/mnt/fat32/bcm2711-rpi-4-b.dtb

   $ sudo rm -rf ~/tmp_dir

4. Fill in the configuration file for the U-Boot bootloader on the SD card by using the following commands:

   $ echo "[all]" > ~/mnt/fat32/config.txt

   $ echo "arm_64bit=1" >> ~/mnt/fat32/config.txt

   $ echo "enable_uart=1" >> ~/mnt/fat32/config.txt

   $ echo "kernel=u-boot.bin" >> ~/mnt/fat32/config.txt

   $ echo "dtparam=i2c_arm=on" >> ~/mnt/fat32/config.txt

   $ echo "dtparam=i2c=on" >> ~/mnt/fat32/config.txt

   $ echo "dtparam=spi=on" >> ~/mnt/fat32/config.txt

   $ sync

   $ sudo umount ~/mnt/fat32

[Topic running_sample_programs_rpi]

Running examples on Raspberry Pi 4 B

To run an example on a Raspberry Pi 4 B:

1. Go to the directory with the example and build the example.
2. Make sure that Raspberry Pi 4 B and the bootable SD card are prepared to run examples.
3. Copy the KasperskyOS-based solution image to the bootable SD card. To do this, connect the bootable SD card to the computer and run the following commands:

   # In the following command, [X] is the last alphabetic character in the name of the block

   # device for the partition on the bootable SD card.

   # In the following commands, the path ~/mnt/fat32 is just an example. You

   # can use a different path.

   $ sudo mount /dev/sd[X]1 ~/mnt/fat32/

   $ sudo cp build/einit/kos-image ~/mnt/fat32/kos-image

   $ sync

   $ sudo umount ~/mnt/fat32

4. Connect the bootable SD card to the Raspberry Pi 4 B.
5. Supply power to the Raspberry Pi 4 B and wait for the example to run.

   The output displayed on the computer 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

At startup, the KasperskyOS kernel finds the executable file named Einit (initializing program) in the solution image and runs this executable file. The running process has the Einit class and is normally used to start all other processes that are required when the solution is started.

Generating the C-code of the initializing program

The KasperskyOS Community Edition toolkit includes the einit tool, which lets you generate the C-code of the initializing program based on the init description (the description file is normally named init.yaml). The obtained program uses the KasperskyOS API to do the following:

• Statically create and run processes.
• Statically create IPC channels.

The standard way of using the einit tool is to integrate an einit call into one of the steps of the build script. As a result, the einit tool uses the init.yaml file to generate the einit.c file containing the 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.

Syntax of init.yaml

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

• Processes that are started when KasperskyOS is loaded.
• IPC channels that are used by processes to interact with each other.

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

Page top

[Topic using_einit]

Example init descriptions

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

The file containing an init description is usually named init.yaml, but it can have any name.

Connecting and starting a client process and server process

In the next example, two processes will be started: one process of the Client class and one process of the Server class. 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 either, so they will also match the names of their respective classes. The processes will be connected by an IPC channel named server_connection.

init.yaml

Specifying the executable file to run

The next example will run a Client-class process from the cl executable file, a ClientServer-class process from the csr executable file, and a MainServer-class process from the msr executable file. 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

The next example will run three processes: a Client-class process from the default executable file (Client), and processes of the MainServer and BkServer classes from the srv executable file. The names of the processes are not specified, so they will match the names of their respective process classes.

init.yaml

Starting two processes of the same class

The next example will run one Client-class process (named Client by default) and two Server-class processes named UserServer and PrivilegedServer. The client process is linked to the server processes through IPC channels named server_connection_us and server_connection_ps, respectively. The names of the executable files are not specified, so they will match the names of their respective process classes.

init.yaml

Passing environment variables and arguments using the main() function

The next example will run two processes: one VfsFirst-class process (named VfsFirst by default) and one VfsSecond-class process (named VfsSecond by default). At startup, the first process receives the -f /etc/fstab argument and the following environment variables: ROOTFS with the value ramdisk0,0 / ext2 0 and UNMAP_ROMFS with the value 1. At startup, the second process receives the -l devfs /dev devfs 0 argument.

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 a process using the KasperskyOS API

Below is the code of the GpMgrOpenSession() function, which starts the server process, connects it to the client process and initializes IPC transport. The executable file of the new process must be contained in the ROMFS storage of the solution.

[Topic env_overview]

Overview: Env program

The Env program is intended for passing arguments and environment variables to started processes. When started, each process automatically sends a request to the Env process and receives the necessary data.

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

1. Develop the code of the Env program by using macros from env/env.h.

2. Build the binary file of the Env program by linking it to the env_server library.

3. In the init description, indicate that the Env process must be started and connected to the selected processes (Env acts a server in this case). The channel name is defined by the ENV_SERVICE_NAME macro declared in the env/env.h file.

4. Include the Env binary file in the solution image.

Env program code

The code of the Env program utilizes the following macros and functions declared in the env/env.h file:

• ENV_REGISTER_ARGS(name,argarr) – arguments from the argarr array are passed to the process named name (the maximum size of one element is 256 bytes).
• ENV_REGISTER_VARS(name,envarr) – environment variables from the envarr array are passed to the process named name (the maximum size of one element is 256 bytes).
• ENV_REGISTER_PROGRAM_ENVIRONMENT(name,argarr,envarr) – arguments and environment variables are passed to the process named name.
• envServerRun() – initialize the server part of the Env program so that it can respond to requests.

Env usage examples

Page top

[Topic using_env_app]

Passing environment variables and arguments using Env

Example of passing arguments at process startup

Below is the code of the Env program. When the process named NetVfs starts, the program passes three arguments to this process: NetVfs, -l devfs /dev devfs 0 and -l romfs /etc romfs 0:

env.c

Example of passing environment variables at process startup

Below is the code of the Env program. When the process named Vfs3 starts, the program passes two 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

[Topic vfs_overview]

Contents of the VFS component

The VFS component contains a set of executable files, libraries and description files that let you use file systems and/or a network stack combined into a separate Virtual File System (VFS) process. If necessary, you can build your own VFS implementations.

VFS libraries

The vfs CMake package contains the following libraries:

• vfs_fs – contains the defvs, ramfs and romfs implementations, and lets you add implementations of other file systems to VFS.
• vfs_net – contains the defvs implementation and network stack.
• vfs_imp – contains the sum of the vfs_fs and vfs_net components.
• vfs_remote – client transport library that converts local calls into IPC requests to VFS and receives IPC responses.
• vfs_server – server transport library of VFS that receives IPC requests, converts them into local calls, and sends IPC responses.
• vfs_local – used for statically linking the client to VFS libraries.

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 and dnet_imp libraries.

Each of these executable files have their own default values for arguments and environment variables.

If necessary, you can independently build a VFS executable file with the necessary functionality.

VFS description files

The directory /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include/kl/ contains the following VFS files:

• VfsRamFs.edl, VfsSdCardFs.edl, VfsNet.edl and VfsEntity.edl, and the header files generated from them, including the transport code.
• Vfs.cdl and the generated Vfs.cdl.h.
• Vfs*.idl and the header files generated from them, including the transport code.

Page top

[Topic client_and_vfs_ipc_channel]

Creating an IPC channel to VFS

Let's examine a Client program using file systems and Berkeley sockets. To handle its calls, we start one VFS process (named VfsFsnet). Network calls and file calls will be sent to this process. This approach is utilized when there is no need to separate file data streams from network data streams.

To ensure correct interaction between the Client and VfsFsnet processes, the name of the IPC channel between them must be defined by the _VFS_CONNECTION_ID macro declared in the vfs/defs.h file.

Below is a fragment of an init description for connecting the Client and VfsFsnet processes.

init.yaml

[Topic vfs_app_build]

Building a VFS executable file

When building a VFS executable file, you can include whatever specific functionality is required in this file, such as:

• Implementation of a specific file system
• Network stack
• Network driver

For example, you will need to build a "file version" and a "network version" of VFS to separate file calls from network calls. In some cases, you will need to include a network stack and file systems in the VFS ("full version" of VFS).

Building a "file version" of VFS

Let's examine a VFS program containing only an implementation of the lwext4 file system without a network stack. To build this executable file, the file containing the main() function must be linked to the vfs_server, vfs_fs and lwext4 libraries:

CMakeLists.txt

Interaction between three processes: client, "file version" of VFS, and block device driver.

Building a "network version" of VFS together with a network driver

Let's examine a VFS program containing a network stack with a driver but without implementations of files systems. To build this executable file, the file containing the main() function must be linked to the vfs_server, vfs_implementation and dnet_implementation libraries.

CMakeLists.txt

Interaction between the Client process and the process of the "network version" of VFS

Building a "network version" of VFS with a separate network driver

Another option is to build the "network version" of VFS without a network driver. The network driver will need to be started as a separate process. Interaction with the driver occurs via IPC using the dnet_client library.

In this case, the file containing the main() function must be linked to the vfs_server, vfs_implementation and dnet_client libraries.

CMakeLists.txt

Interaction between three processes: client, "network version" of VFS, and network driver.

Building a "full version" of VFS

If the VFS needs to include a network stack and implementations of file systems, the build should use the vfs_server library, vfs_implementation library, dnet_implementation library (or dnet_client library for a separate network driver), and the libraries for implementing file systems.

Page top

[Topic client_and_vfs_linked]

Merging a client and VFS into one executable file

Let's examine a Client program using Berkeley sockets. Calls made by the Client must be sent to VFS. The normal path consists of starting a separate VFS process and creating an IPC channel. Alternatively, you can integrate VFS functionality directly into the Client executable file. To do so, when building the Client executable file, you need to link it to the vfs_local library that will receive calls, and link it to the implementation libraries vfs_implementation and dnet_implementation.

Local linking with VFS is convenient during debugging. In addition, calls for working with the network can be handled much faster due to the exclusion of IPC calls. Nevertheless, insulation of the VFS in a separate process and IPC interaction with it is always recommended as a more secure approach.

Below is a build script for the Client executable file.

CMakeLists.txt

[Topic vfs_args_and_envs_overview]

Overview: arguments and environment variables of VFS

VFS arguments

• -l <entry in fstab format>

  The -l argument lets you mount the file system.

• -f <path to fstab file>

  The -f argument lets you pass the file containing entries in fstab format for mounting file systems. The ROMFS storage will be searched for the file. If the UMNAP_ROMFS variable is defined, the file system mounted using the ROOTFS variable will be searched for the file.

Example of using the -l and -f arguments

VFS environment variables

• UNMAP_ROMFS

  If the UNMAP_ROMFS variable is defined, the ROMFS storage will be deleted. This helps conserve memory and change behavior when using the -f argument.

• ROOTFS = <entry in fstab format>

  The ROOTFS variable lets you mount a file system to the root directory. In combination with the UNMAP_ROMFS variable and the -f argument, it lets you search for the fstab file in the mounted file system instead of in the ROMFS storage. ROOTFS usage example

• VFS_CLIENT_MAX_THREADS

  The VFS_CLIENT_MAX_THREADS environment variable lets you redefine the SDK configuration parameter VFS_CLIENT_MAX_THREADS during VFS startup.

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

The _VFS_NETWORK_BACKEND variable defines the backend used for network calls. You can specify the name of a standard backend such as client, server or local, and the name of a custom backend. If the local backend is used, the name of the IPC channel is not specified (_VFS_NETWORK_BACKEND=local:). You can specify two or more IPC channels by separating them with a comma.

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

  The _VFS_FILESYSTEM_BACKEND variable defines the backend used for file calls. The backend name and name of the IPC channel to VFS are defined the same as way as they were for the _VFS_NETWORK_BACKEND variable.

Default values

For the VfsRamFs executable file:

For the VfsSdCardFs executable file:

For the VfsNet executable file:

[Topic mount_on_start]

Mounting a file system at startup

When the VFS process starts, 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 using the mount() call after the VFS starts but can also be done immediately when the VFS process starts by passing the necessary arguments and environment variables to it.

Let's examine three examples of mounting file systems at VFS startup. The Env program is used to pass arguments and environment variables to the VFS process.

Mounting with the -l argument

A simple way to mount a file system is to pass the -l <entry in fstab format> argument to the VFS process.

In this example, the devfs and romfs file systems will be mounted when the process named Vfs1 is started.

env.c

Mounting with fstab from ROMFS

If an fstab file is added when building a solution, the file will be available through the ROMFS storage after startup. It can be used for mounting by passing the -f <path to fstab file> argument to the VFS process.

In this example, the file systems defined via the fstab file that was added during the solution build will be mounted when the process named Vfs2 is started.

env.c

Mounting with an external fstab

Let's assume that the fstab file is located on a drive and not in the ROMFS image of the solution. To use it for mounting, you need to pass the following arguments and environment variables to VFS:

1. ROOTFS. This variable lets you mount the file system containing the fstab file into the root directory.
2. UNMAP_ROMFS. If this variable is defined, the ROMFS storage is deleted. As a result, the fstab file will be sought in the file system mounted using the ROOTFS variable.
3. -f. This argument is used to define the path to the fstab file.

In the next example, the ext2 file system containing the /etc/fstab file used for mounting additional file systems will be mounted to the root directory when the process named Vfs3 starts. The ROMFS storage will be deleted.

env.c

[Topic client_and_two_vfs]

Using VFS backends to separate file calls and network calls

Let's examine a Client program using file systems and Berkeley sockets. To handle its calls, we will start not one but two separate VFS processes from the VfsFirst and VfsSecond executable files. We will use environment variables to assign the file backends to work via the channel to VfsFirst and assign the network backends to work via the channel to VfsSecond. We will use the standard backends client and server. This way, we will redirect the file calls of the Client to VfsFirst and redirect the network calls to VfsSecond. To pass the environment variables to processes, we will add the Env program to the solution.

The init description of the solution is provided below. The Client process will be connected to the VfsFirst and VfsSecond processes, and each of the three processes will be connected to the Env process. Please note that the name of the IPC channel to the Env process is defined by using the ENV_SERVICE_NAME variable.

init.yaml

To send all file calls to VfsFirst, we define the value of the _VFS_FILESYSTEM_BACKEND environment variable as follows:

• For VfsFirst: _VFS_FILESYSTEM_BACKEND=server:<name of the IPC channel to VfsFirst>
• For Client: _VFS_FILESYSTEM_BACKEND=client:<name of the IPC channel to VfsFirst>

To send network calls to VfsSecond, we use the equivalent _VFS_NETWORK_BACKEND environment variable:

• We define the following for VfsSecond: _VFS_NETWORK_BACKEND=server:<name of the IPC channel to the VfsSecond>
• We define the following for the Client: _VFS_NETWORK_BACKEND=client: <name of the IPC channel to the VfsSecond>

We define the value of environment variables through the Env program, which is presented below.

env.c

[Topic vfs_backends]

Writing a custom VFS backend

Let's examine a solution that includes the Client, VfsFirst and VfsSecond processes. Let's assume that the Client process is connected to VfsFirst and VfsSecond using IPC channels.

Our task is to ensure that queries from the Client process to the fat32 file system are handled by the VfsFirst process, and queries to the ext4 file system are handled by the VfsSecond process. To accomplish this task, we can use the VFS backend mechanism and will not even need to change the code of the Client program.

We will write a custom backend named custom_client, which will send calls via the VFS1 or VFS2 channel depending on whether or not the file path begins with /mnt1. To send calls, custom_client will use the standard backends of the client. In other words, it will act as a proxy backend.

We use the -l argument to mount fat32 to the /mnt1 directory for the VfsFirst process and mount ext4 to /mnt2 for the VfsSecond process. (It is assumed that VfsFirst contains a fat32 implementation and VfsSecond contains an ext4 implementation.) We use the _VFS_FILESYSTEM_BACKEND environment variable to define the backends (custom_client and server) and IPC channels (VFS1 and VFS2) to be used by the processes.

Then we use the init description to define the names of the IPC channels: VFS1 and VFS2.

This is examined in more detail below:

1. Code of the custom_client backend.
2. Linking of the Client program and the custom_client backend.
3. Env program code.
4. Init description.

Writing a custom_client backend

This file contains an implementation of the proxy custom backend that relays calls to one of the two standard client backends. The backend selection logic depends on the utilized path or on the file handle and is managed by additional data structures.

backend.c

Linking of the Client program and the custom_client backend

Compile the written backend into a library:

CMakeLists.txt

Link the prepared backend_client library to the Client program:

CMakeLists.txt (fragment)

Writing the Env program

We use the Env program to pass arguments and environment variables to processes.

env.c

Editing init.yaml

For the IPC channels that connect the Client process to the VfsFirst and VfsSecond processes, you must define the same names that you specified in the _VFS_FILESYSTEM_BACKEND environment variable: VFS1 and VFS2.

init.yaml

[Topic sc_using_ipc]

IPC and transport

[Topic sc_ipc_channels]

Creating IPC channels

[Topic ipc_channels_overview]

Overview: creating IPC channels

There are two methods for creating IPC channels: static and dynamic.

Static creation of IPC channels is simpler to implement because you can use the init description for this purpose.

Dynamic creation of IPC channels lets you change the topology of interaction between processes on the fly. This is necessary if it is unknown which specific server contains the endpoint required by the client. For example, you may not know which specific drive you will need to write data to.

Statically creating an IPC channel

The static method has the following distinguishing characteristics:

• The client and server are in the stopped state when the IPC channel is created.
• Creation of this channel is initiated by the parent process that starts the client and server (this is normally Einit).
• The created IPC channel cannot be deleted.
• To get the IPC handle and endpoint ID (riid) after the IPC channel is created, the client and server must use the endpoint locator interface (coresrv/sl/sl_api.h).

Dynamically creating an IPC channel

The dynamic method has the following distinguishing characteristics:

• The client and server are already running at the time of creating the IPC channel.
• Creation of the channel is initiated jointly by the client and server.
• The created IPC channel can be deleted.
• The client and server get the IPC handle and endpoint ID (riid) immediately after the IPC channel is successfully created.

[Topic ipc_channel_create_einit]

Creating IPC channels using init.yaml

This section contains init descriptions that demonstrate the specific features of creating IPC channels. Examples of defining properties and arguments of processes via init descriptions are examined in a separate article.

The file containing an init description is usually named init.yaml, but it can have any name.

Connecting and starting a client process and server process

In the next example, two processes will be started: one process of the Client class and one process of the Server class. 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 either, so they will also match the names of their respective classes. The processes will be connected by an IPC channel named server_connection.

init.yaml

Page top

[Topic ipc_channel_create_dynamic]

Dynamically created IPC channels

A dynamically created IPC channel uses the following functions:

• Name Server interface
• Connection Manager interface

An IPC channel is dynamically created according to the following scenario:

1. The following processes are started: client, server, and name server.
2. The server connects to the name server by using the NsCreate() call and publishes the server name, interface name, and endpoint name by using the NsPublishService() call.
3. The client uses the NsCreate() call to connect to the name server and then uses the NsEnumServices() call to search for the server name and endpoint name based on the interface name.
4. The client uses the KnCmConnect() call to request access to the endpoint and passes the found server name and endpoint name as arguments.
5. The server calls the KnCmListen() function to check for requests to access the endpoint.
6. The server accepts the client request to access the endpoint by using the KnCmAccept() call and passes the client name and endpoint name received from the KnCmListen() call as arguments.

The server can use the NsUnPublishService() call to unpublish endpoints that were previously published on the name server.

The server can use the KnCmDrop() call to reject requests to access endpoints.

[Topic sc_using_sdk_endpoints]

Using endpoints from KasperskyOS Community Edition

[Topic using_sdk_endpoints_examples]

Adding an endpoint 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. Inhclude 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-aarch64-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 description of the interfaces of the process that receives the message (server).

A correct IPC message (request and response) contains a constant part and an arena.

Constant part of a message

The constant part of a message contains arguments of a fixed size, and the RIID and MID.

Fixed-size arguments can be arguments of any IDL types except the sequence type.

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

• The RIID (Runtime Implementation ID) is the number of the process endpoint being called, starting at zero.
• The MID (Method ID) is the number of the method within the interface that contains it, starting at zero.

The type of the constant part of the 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.

Arena

The arena is a buffer for storing variable-size arguments (sequence IDL type).

Message structure verification by the security module

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

Forming a message structure

KasperskyOS Community Edition includes the following tools that make it easier for the developer to create and package an IPC message:

• The transport-kos library for working with NkKosTransport.
• The NK compiler that lets you generate special methods and types.

Simple IPC message generation is demonstrated in the echo and ping examples (/opt/KasperskyOS-Community-Edition-<version>/examples/).

[Topic ipc_find_ipc_desc]

Finding an IPC handle

The client and server IPC handles must be found if there are no ready-to-use transport libraries for the utilized endpoint (for example, if you wrote your own endpoint). To independently work with IPC transport, you need to first initialize it by using the NkKosTransport_Init() method and pass the IPC handle of the utilized channel as the second argument.

For more details, see the echo and ping examples (/opt/KasperskyOS-Community-Edition-<version>/examples/)

Finding an IPC handle when statically creating a channel

When statically creating an IPC channel, both the client and server can find out their IPC handles immediately after startup by using the ServiceLocatorRegister() and ServiceLocatorConnect() methods and specifying the name of the created IPC channel.

For example, if the IPC channel is named server_connection, the following must be called on the client side:

The following must be called on the server side:

For more details, see the echo and ping examples (/opt/KasperskyOS-Community-Edition-<version>/examples/), and the header file /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include/coresrv/sl/sl_api.h.

Finding an IPC handle when dynamically creating a channel

Both the client and server receive their own IPC handles immediately after dynamic creation of an IPC channel is successful.

The client IPC handle is one of the output (out) arguments of the KnCmConnect() method. The server IPC handle is an output argument of the KnCmAccept() method. For more details, see the header file /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include/coresrv/cm/cm_api.h.

[Topic ipc_find_riid]

Finding an endpoint ID (riid)

The endpoint ID (riid) must be found on the client side if there are no ready-to-use transport libraries for the utilized endpoint (for example, if you wrote your own endpoint). To call methods of the server, you must first call the proxy object initialization method on the client side and pass the endpoint ID as the third argument. For example, for the Filesystem interface:

For more details, see the echo and ping examples (/opt/KasperskyOS-Community-Edition-<version>/examples/)

Finding a service ID when statically creating a channel

When statically creating an IPC channel, the client can find out the ID of the necessary endpoint by using the ServiceLocatorGetRiid() method and specifying the IPC channel handle and the fully qualified name of the endpoint. For example, if the OpsComp component instance contains the FS endpoint, the following must be called on the client side:

For more details, see the echo and ping examples (/opt/KasperskyOS-Community-Edition-<version>/examples/), and the header file /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include/coresrv/sl/sl_api.h.

Finding a service ID when dynamically creating a channel

The client receives the endpoint ID immediately after dynamic creation of an IPC channel is successful. The client IPC handle is one of the output (out) arguments of the KnCmConnect() method. For more details, see the header file /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include/coresrv/cm/cm_api.h.

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

KasperskyOS API

[Topic libkos]

libkos library

[Topic libkos_intro]

Overview of the libkos library

The KasperskyOS kernel has a number of endpoints for managing handles, threads, memory, processes, IPC channels, I/O resources, and others. The libkos library is used for accessing endpoints.

libkos library

The libkos library consists of two parts:

• The first part provides the C interface for accessing KasperskyOS core endpoints. It is available through the header files in the coresrv directory.
• The second part of the libkos library provides abstractions of synchronization primitives, objects, and queues. It also contains wrapper functions for simpler memory allocation and thread management. Header files of the second part of libkos are in the kos directory.

The libkos library significantly simplifies the use of core endpoints. The libkos library functions ensure correct packaging of an IPC message and execution of system calls. Other libraries (including libc) interact with the kernel through the libkos library.

To use a KasperskyOS core endpoint, you need to include the libkos library header file corresponding to this endpoint. For example, to access methods of the IO Manager, you need to include the io_api.h file:

Files used by the libkos library

An intrinsic implementation of the libkos library can use the following files exported by the kernel:

• Files in the IDL language (IDL descriptions). They contain descriptions of the interfaces of endpoints. They are used by IPC transport for correct packaging of messages.
• Header files of the kernel. These files are included in the libkos library.

Example

The I/O Manager is provided for the user in the following files:

• coresrv/io/io_api.h is a header file of the libkos library.
• services/io/IO.idl is the IDL description of the I/O manager.
• io/io_dma.h and io/io_irq.h are header files of the kernel.

[Topic api_memory]

Memory

[Topic api_memory_states]

Memory states

Each page of virtual memory can be free, reserved, or committed.

The transition from a free state to a reserved state is called allocation. Pre-reserving memory (without committing physical pages) enables an application to mark its address space in advance. The transition from a reserved state back to a free state is referred to as freeing memory.

The assignment of physical memory for a previously reserved page of virtual memory is referred to as committing memory, and the inverse transition from the committed state to the reserved state is called returning memory.

Transitions between memory page states

[Topic kn_vm_allocate]

KnVmAllocate()

This function is declared in the coresrv/vmm/vmm_api.h file.

Reserves a range of physical pages defined by the addr and size parameters. If the VMM_FLAG_COMMIT flag is indicated, the function reserves and commits pages for one call.

Parameters:

• addr is the page-aligned base physical address; if addr is set equal to 0, the system chooses a free area of physical memory.
• size is the size of the memory area in bytes (must be a multiple of the page size).
• flags refers to allocation flags.

Returns the base virtual address of the reserved area. If it is not possible to reserve a memory area, the function returns RTL_NULL.

Allocation flags

In the flags parameter, you can use the following flags (vmm/flags.h):

• VMM_FLAG_RESERVE is a required flag.
• VMM_FLAG_COMMIT lets you reserve and commit memory pages to one KnVmAllocate() call in so-called "lazy" mode.
• VMM_FLAG_LOCKED is used together with VMM_FLAG_COMMIT and lets you immediately commit physical memory pages instead of "lazy" commitment.
• VMM_FLAG_WRITE_BACK, VMM_FLAG_WRITE_THROUGH, VMM_FLAG_WRITE_COMBINE, VMM_FLAG_CACHE_DISABLE and VMM_FLAG_CACHE_MASK manage caching of memory pages.
• VMM_FLAG_READ, VMM_FLAG_WRITE, VMM_FLAG_EXECUTE and VMM_FLAG_RWX_MASK are memory protection attributes.
• VMM_FLAG_LOW_GUARD and VMM_FLAG_HIGH_GUARD add a protective page before and after the allocated memory, respectively.
• VMM_FLAG_GROW_DOWN  defines the direction of memory access (from older addresses to newer addresses).

Permissible combinations of memory protection attributes:

• VMM_FLAG_READ allows reading page contents.
• VMM_FLAG_READ | VMM_FLAG_WRITE allows reading and modifying page contents.
• VMM_FLAG_READ | VMM_FLAG_EXECUTE allows reading and executing page contents.
• VMM_FLAG_RWX_MASK or VMM_FLAG_READ | VMM_FLAG_WRITE | VMM_FLAG_EXECUTE refers to full access to page contents (these entries are equivalent).

Example

The KnVmProtect() function can be used to modify the defined memory area protection attributes if necessary.

[Topic kn_vm_commit]

KnVmCommit()

This function is declared in the coresrv/vmm/vmm_api.h file.

Commits a range of physical pages defined by the "addr" and "size" parameters.

All committed pages must be reserved in advance.

Parameters:

• addr is the page-aligned base virtual address of the memory area.
• size is the size of the memory area in bytes (must be a multiple of the page size).
• flags is an unused parameter (indicate the VMM_FLAG_LOCKED flag in this parameter value to ensure compatibility).

If pages are successfully committed, the function returns rcOk.

[Topic kn_vm_decommit]

KnVmDecommit()

This function is declared in the coresrv/vmm/vmm_api.h file.

Frees a range of pages (switches them to the reserved state).

Parameters:

• addr is the page-aligned base virtual address of the memory area.
• size is the size of the memory area in bytes (must be a multiple of the page size).

If pages are successfully freed, the function returns rcOk.

[Topic kn_vm_protect]

KnVmProtect()

This function is declared in the coresrv/vmm/vmm_api.h file.

Modifies the protection attributes of reserved or committed memory pages.

Parameters:

• addr is the page-aligned base virtual address of the memory area.
• size is the size of the memory area in bytes (must be a multiple of the page size).
• newFlags refers to new protection attributes.

If the protection attributes are successfully changed, the function returns rcOk.

Permissible combinations of memory protection attributes:

• VMM_FLAG_READ allows reading page contents.
• VMM_FLAG_READ | VMM_FLAG_WRITE allows reading and modifying page contents.
• VMM_FLAG_READ | VMM_FLAG_EXECUTE allows reading and executing page contents.
• VMM_FLAG_RWX_MASK or VMM_FLAG_READ | VMM_FLAG_WRITE | VMM_FLAG_EXECUTE refers to full access to page contents (these entries are equivalent).

[Topic kn_vm_unmap]

KnVmUnmap()

This function is declared in the coresrv/vmm/vmm_api.h file.

Frees the memory area.

Parameters:

• addr refers to the page-aligned address of the memory area.
• size refers to the memory area size.

If pages are successfully freed, the function returns rcOk.

[Topic api_memory_alloc]

Memory allocation

[Topic kos_mem_alloc]

KosMemAlloc()

This function is declared in the kos/alloc.h file.

This function allocates (reserves and commits) a memory area equal to the specific size of bytes.

This function returns a pointer to the allocated area or RTL_NULL if memory could not be allocated.

[Topic kos_mem_alloc_ex]

KosMemAllocEx()

This function is declared in the kos/alloc.h file.

This function is analogous to KosMemAlloc(), but it also has additional parameters:

• align refers to the alignment of the memory area in bytes (power of two).
• zeroed determines whether or not the memory area needs to be filled with zeros (1 means fill, 0 means do not fill).

[Topic kos_mem_free]

KosMemFree()

This function is declared in the kos/alloc.h file.

This function frees a memory area that was allocated using the KosMemAlloc(), KosMemZalloc() or KosMemAllocEx() function.

• ptr is the pointer to the freed memory area.

[Topic kos_mem_get_size]

KosMemGetSize()

This function is declared in the kos/alloc.h file.

This function returns the size (in bytes) of the memory area allocated using the KosMemAlloc(), KosMemZalloc() or KosMemAllocEx() function.

• ptr is the pointer to the memory area.

[Topic kos_mem_zalloc]

KosMemZalloc()

This function is declared in the kos/alloc.h file.

This function is analogous to KosMemAlloc(), but it also fills the allocated memory area with zeros.

[Topic libkos_threads]

Threads

[Topic kos_thread_callback]

KosThreadCallback()

The callback function prototype is declared in the kos/thread.h file.

When a new thread is created, all registered callback functions will be called with the KosThreadCallbackReasonCreate argument. When the thread is terminated, they will be called with the KosThreadCallbackReasonDestroy argument.

[Topic kos_thread_callback_register]

KosThreadCallbackRegister()

This function is declared in the kos/thread.h file.

This function registers a custom callback function. When a thread is created and terminated, all registered callback functions will be called.

[Topic kos_thread_callback_unregister]

KosThreadCallbackUnregister()

This function is declared in the kos/thread.h file.

This function deregisters the custom callback function (removes it from the list of called functions).

[Topic kos_thread_create]

KosThreadCreate()

This function is declared in the kos/thread.h file.

This function creates a new thread.

Input parameters:

• priority must be within the interval from 0 to 31; the following priority constants are available: ThreadPriorityLowest (0), ThreadPriorityNormal (15) and ThreadPriorityHighest (31).
• stackSize is the size of the stack.
• routine is the function that will be executed in the thread.
• context is the argument that will be passed to the routine function.
• suspended lets you create a thread in the suspended state (1 means create suspended, 0 means create not suspended).

Output parameters:

• tid is the ID of the created thread.

Example

[Topic kos_thread_current_id]

KosThreadCurrentId()

This function is declared in the kos/thread.h file.

This function requests the TID of the calling thread.

If successful, the function returns the thread ID (TID).

[Topic kos_thread_exit]

KosThreadExit()

This function is declared in the kos/thread.h file.

This function forcibly terminates the current thread with the exitCode.

[Topic kos_thread_get_stack]

KosThreadGetStack()

This function is declared in the kos/thread.h file.

This function gets the stack of the thread with the specific tid.

Output parameter size contains the stack size.

If successful, the function returns the pointer to the beginning of the stack.

[Topic kos_thread_once]

KosThreadOnce()

This function is declared in the kos/thread.h file.

This function lets you call the defined initRoutine procedure precisely one time, even when it is called from multiple threads.

The onceControl parameter is designed to control the one-time call of the procedure.

If the procedure is successfully called, and if it was called previously, the KosThreadOnce() function returns rcOk.

[Topic kos_thread_resume]

KosThreadResume()

This function is declared in the kos/thread.h file.

This function resumes the thread with the identifier tid that was created in the suspended state.

If successful, the function returns rcOk.

[Topic kos_thread_sleep]

KosThreadSleep()

This function is declared in the kos/thread.h file.

Suspends execution of the current thread for mdelay (in milliseconds).

If successful, the function returns rcOk.

[Topic kos_thread_suspend]

KosThreadSuspend()

This function is declared in the kos/thread.h file.

Permanently stops the current thread without finishing it.

The tid parameter must be equal to the identifier of the current thread (a limitation of the current implementation).

If successful, the function returns rcOk.

[Topic kos_thread_terminate]

KosThreadTerminate()

This function is declared in the kos/thread.h file.

This function terminates the thread of the calling process. The tid parameter defines the ID of the thread.

If the tid points to the current thread, the exitCode parameter defines the thread exit code.

If successful, the function returns rcOk.

[Topic kos_thread_tls_get]

KosThreadTlsGet()

This function is declared in the kos/thread.h file.

This function returns the pointer to the local storage of the thread (TLS) or RTL_NULL if there is no TLS.

[Topic kos_thread_tls_set]

KosThreadTlsSet()

This function is declared in the kos/thread.h file.

This function defines the address of the local storage for the thread (TLS).

Input argument tls contains the TLS address.

[Topic kos_thread_wait]

KosThreadWait()

This function is declared in the kos/thread.h file.

This function suspends execution of the current thread until termination of the thread with the identifier tid or until the timeout (in milliseconds).

The KosThreadWait() call with a zero value for timeout is analogous to the KosThreadYield() call .

If successful, the function returns rcOk. In case of timeout, it returns rcTimeout.

[Topic kos_thread_yield]

KosThreadYield()

This function is declared in the kos/thread.h file.

Passes execution of the thread that called it to the next thread.

The KosThreadYield() call is analogous to the KosThreadSleep() call with a zero value for mdelay.

[Topic api_handles]

Handles

[Topic kn_handle_close]

KnHandleClose()

This function is declared in the coresrv/handle/handle_api.h file.

Deletes the handle.

If successful, the function returns rcOk, otherwise it returns an error code.

[Topic kn_handle_create_badge]

KnHandleCreateBadge()

This function is declared in the coresrv/handle/handle_api.h file.

This function creates a resource transfer context object for the specified resource transfer context and configures a notification receiver named notice for receiving notifications about this object. The notification receiver is configured to receive notifications about events that match the EVENT_OBJECT_DESTROYED and EVENT_BADGE_CLOSED flags of the event mask.

Input parameter eventId defines the ID of a "resource–event mask" entry in the notification receiver.

Output parameter handle contains the handle of the resource transfer context object.

If successful, the function returns rcOk, otherwise it returns an error code.

[Topic kn_handle_create_user_object]

KnHandleCreateUserObject()

This function is declared in the coresrv/handle/handle_api.h file.

Creates the specified handle of the specified type with the rights permissions mask.

The type parameter can take values ranging from HANDLE_TYPE_USER_FIRST to HANDLE_TYPE_USER_LAST.

The HANDLE_TYPE_USER_FIRST and HANDLE_TYPE_USER_LAST macros are defined in the handle/handletype.h header file.

The context parameter defines the context of the user resource. If successful, the function returns rcOk, otherwise it returns an error code.

Example

[Topic kn_handle_revoke]

KnHandleRevoke()

This function is declared in the coresrv/handle/handle_api.h file.

Deletes the handle and revokes all of its descendants.

If successful, the function returns rcOk, otherwise it returns an error code.

[Topic kn_handle_revoke_subtree]

KnHandleRevokeSubtree()

This function is declared in the coresrv/handle/handle_api.h file.

This function revokes the handles that make up the handle inheritance subtree of the specified handle.

The root node of the inheritance subtree is the handle that was generated by the transfer of the specified handle associated with the badge resource transfer context object.

If successful, the function returns rcOk, otherwise it returns an error code.

[Topic nk_get_badge_op]

nk_get_badge_op()

This function is declared in the nk/types.h file.

This function extracts the pointer to the badge resource transfer context from the transport container of desc if the operation flags are set in the permissions mask that is placed in the transport container of desc.

If successful, the function returns NK_EOK, otherwise it returns an error code.

[Topic nk_is_handle_dereferenced]

nk_is_handle_dereferenced()

This function is declared in the nk/types.h file.

This function returns a non-zero value if the handle in the transport container of desc was obtained as a result of a handle dereferencing operation.

This function returns zero if the handle in the transport container of desc was obtained as a result of a handle transfer operation.

[Topic handles_manage]

Managing handles

Handles are managed by using functions of the Handle Manager and Notification Subsystem.

The Handle Manager is provided for the user in the following files:

• coresrv/handle/handle_api.h is a header file of the libkos library.
• services/handle/Handle.idl is an IDL description of the Handle Manager's IPC interface.

The Notification Subsystem is provided for the user in the following files:

• coresrv/handle/notice_api.h is a header file of the libkos library.
• services/handle/Notice.idl is an IDL description of the IPC interface of the Notification Subsystem.

[Topic libkos_handles_rights]

Handle permissions mask

A handle permissions mask has a size of 32 bits and consists of a general part and a specialized part. The general part describes the general rights that are not specific to any particular resource (the flags of these rights are defined in the services/ocap.h header file). For example, the general part contains the OCAP_HANDLE_TRANSFER flag, which defines the permission to transfer the handle. The specialized part describes the rights that are specific to the particular user resource or system resource. The flags of the specialized part's permissions for system resources are defined in the services/ocap.h header file. The structure of the specialized part for user resources is defined by the resource provider by using the OCAP_HANDLE_SPEC() macro that is defined in the services/ocap.h header file. The resource provider must export the public header files describing the structure of the specialized part.

When the handle of a system resource is created, the permissions mask is defined by the KasperskyOS kernel, which applies permissions masks from the services/ocap.h header file. It applies permissions masks with names such as OCAP_*_FULL (for example, OCAP_IOPORT_FULL, OCAP_TASK_FULL, OCAP_FILE_FULL) and OCAP_IPC_* (for example, OCAP_IPC_SERVER, OCAP_IPC_LISTENER, OCAP_IPC_CLIENT).

When the handle of a user resource is created, the permissions mask is defined by the user.

When a handle is transferred, the permissions mask is defined by the user but the transferred access rights cannot be elevated above the access rights of the process.

[Topic handles_create]

Creating handles

The handles of user resources are created by the providers of the resources. The KnHandleCreateUserObject() function declared in the coresrv/handle/handle_api.h header file is used to create handles of user resources.

handle_api.h (fragment)

The user resource context is the data that allows the resource provider to identify the resource and its state when access to the resource is requested by other programs. This normally consists of a data set with various types of data (structure). For example, the context of a file may include the name, path, and cursor position. The user resource context is used as the resource transfer context or is used together with multiple resource transfer contexts.

For details about a handle permissions mask, see "Handle permissions mask".

[Topic libkos_handles_transfer]

Transferring handles

Overview

Handles are transferred between programs so that clients (programs that utilize resources) can obtain access to required resources. Due to the specific locality of handles, a handle transfer initiates the creation of a handle from the handle space of the recipient program. This handle is registered as a descendant of the transferred handle and identifies the same resource.

One handle can be transferred multiple times by one or multiple programs. Each transfer initiates the creation of a new descendant of the transferred handle on the recipient program side. A program can transfer the handles that it received from other programs or from the KasperskyOS kernel (when creating handles of system resources). For this reason, a handle may have multiple generations of descendants. The generation hierarchy of handles for each resource is stored in the KasperskyOS kernel in the form of a handle inheritance tree.

A program can transfer handles for user resources and system resources if the access rights of these handles permit such a transfer. A descendant may have less access rights than an ancestor. For example, a transferring program with read-and-write permissions for a file can transfer read-only permissions. The transferring program can also prohibit the recipient program from further transferring the handle. Access rights are defined in the transferred permissions mask for the handle.

Conditions for transferring handles

For programs to transfer handles to other programs, the following conditions must be met:

1. An IPC channel is created between the programs.
2. The solution security policy (security.psl) allows interaction between the programs.
3. Interface methods are implemented for transferring handles.
4. The client program received the endpoint ID (RIID) of the server program that has methods for transferring handles.

Interface methods for transferring handles are declared in the IDL language with input (in) and/or output (out) parameters of the Handle type. Methods with input parameters of the Handle type are intended for transferring handles from the client program to the server program. Methods with output parameters of the Handle type are intended for transferring handles from the server program to the client program. No more than seven input and seven output parameters of the Handle type can be declared for one method.

Example IDL description containing declarations of interface methods for transferring handles:

For each parameter of the Handle type, the NK compiler generates a field in the *_req request structure and/or *_res response structure of the nk_handle_desc_t type (hereinafter also referred to as the transport container of the handle). This type is declared in the nk/types.h header file and comprises a structure consisting of the following three fields: handle field for the handle, rights field for the handle permissions mask, and the badge field for the resource transfer context.

Resource transfer context

The resource transfer context is the data that allows the server program to identify the resource and its state when access to the resource is requested via descendants of the transferred handle. This normally consists of a data set with various types of data (structure). For example, the transfer context of a file may include the name, path, and cursor position. A server program receives a pointer to the resource transfer context when dereferencing a handle.

Regardless of whether or not a server program is the resource provider, it can associate each handle transfer with a separate resource transfer context. This resource transfer context is bound only to the handle descendants (handle inheritance subtree) that were generated as a result of a specific transfer of the handle. This lets you define the state of a resource in relation to a separate transfer of the handle of this resource. For example, for cases when one file may be accessed multiple times, the file transfer context lets you define which specific opening of this file corresponds to a received request.

If the server program is the resource provider, each transfer of the handle of this resource is associated with the user resource context by default. In other words, the user resource context is used as the resource transfer context for each handle transfer if the particular transfer is not associated with a separate resource transfer context.

A server program that is the resource provider can use the user resource context and the resource transfer context together. For example, the name, path and size of a file is stored in the user resource context while the cursor position can be stored in multiple resource transfer contexts because each client can work with different parts of the file. Technically, joint use of the user resource context and resource transfer contexts is possible because the resource transfer contexts store a pointer to the user resource context.

If the client program uses multiple various-type resources of the server program, the resource transfer contexts (or contexts of user resources if they are used as resource transfer contexts) must be specialized objects of the KosObject type. This is necessary so that the server program can verify that the client program using a resource has sent the interface method the handle of the specific resource that corresponds to this method. This verification is required because the client program could mistakenly send the interface method a resource handle that does not correspond to this method. For example, a client program receives a file handle and sends it to an interface method for working with volumes.

To associate a handle transfer with a resource transfer context, the server program puts the handle of the resource transfer context object into the badge field of the nk_handle_desc_t structure. The resource transfer context object is the object that stores the pointer to the resource transfer context. The resource transfer context object is created by the KnHandleCreateBadge() function, which is declared in the coresrv/handle/handle_api.h header file. This function is bound to the Notification Subsystem regarding the state of resources because a server program needs to know when a resource transfer context object will be closed and terminated. The server program needs this information to free up or re-use memory that was allotted for storing the resource transfer context.

The resource transfer context object will be closed when deleting or revoking the handle descendants (see Deleting handles, Revoking handles) that were generated during its transfer in association with this object. (A transferred handle may be deleted intentionally or unintentionally, such as when a recipient client program is unexpectedly terminated.) After receiving a notification regarding the closure of a resource transfer context object, the server program deletes the handle of this object. After this, the resource transfer context object is terminated. After receiving a notification regarding the termination of the resource transfer context object, the server program frees up or re-uses the memory that was allotted for storing the resource transfer context.

One resource transfer context object can be associated with only one handle transfer.

handle_api.h (fragment)

Packaging data into the transport container of a handle

The nk_handle_desc() macro declared in the nk/types.h header file is used to package a handle, handle permissions mask and resource transfer context object handle into a handle transport container. This macro receives a variable number of arguments.

If no argument is passed to the macro, the NK_INVALID_HANDLE value will be written in the handle field of the nk_handle_desc_t structure.

If one argument is passed to the macro, this argument is interpreted as the handle.

If two arguments are passed to the macro, the first argument is interpreted as the handle and the second argument is interpreted as the handle permissions mask.

If three arguments are passed to the macro, the first argument is interpreted as the handle, the second argument is interpreted as the handle permissions mask, and the third argument is interpreted as the resource transfer context object handle.

Extracting data from the transport container of a handle

The nk_get_handle(), nk_get_rights() and nk_get_badge_op() (or nk_get_badge()) functions that are declared in the nk/types.h header file are used to extract the handle, handle permissions mask, and pointer to the resource transfer context, respectively, from the transport container of a handle. The nk_get_badge_op() and nk_get_badge() functions are used only when dereferencing handles.

Handle transfer scenarios

A scenario for transferring handles from a client program to the server program includes the following steps:

1. The transferring client program packages the handles and handle permissions masks into the fields of the *_req requests structure of the nk_handle_desc_t type.
2. The transferring client program calls the interface method for transferring handles to the server program. This method executes the Call() system call.
3. The recipient server program receives the request by executing the Recv() system call.
4. The dispatcher on the recipient server program side calls the method corresponding to the request. This method extracts the handles and handle permissions masks from the fields of the *_req request structure of the nk_handle_desc_t type.

A scenario for transferring handles from the server program to a client program includes the following steps:

1. The recipient client program calls the interface method for receiving handles from the server program. This method executes the Call() system call.
2. The transferring server program receives the request by executing the Recv() system call.
3. The dispatcher on the transferring server program side calls the method corresponding to the request. This method packages the handles, handle permissions masks and resource transfer context object handles into the fields of the *_res response structure of the nk_handle_desc_t type.
4. The transferring server program responds to the request by executing the Reply() system call.
5. On the recipient client program side, the interface method returns control. After this, the recipient client program extracts the handles and handle permissions masks from the fields of the *_res response structure of the nk_handle_desc_t type.

If the transferring program defines more access rights in the transferred handle permissions mask than the access rights defined for the transferred handle (which it owns), the transfer is not completed. In this case, the Call() system call made by the transferring or recipient client program or the Reply() system call made by the transferring server program ends with the rcSecurityDisallow error.

[Topic libkos_handles_dereference]

Dereferencing handles

When dereferencing a handle, the client program sends the server program the handle, and the server program receives a pointer to the resource transfer context, the permissions mask of the sent handle, and the ancestor of the handle sent by the client program and already owned by the server program. Dereferencing occurs when a client program that called methods for working with a resource (such as read/write or access closure) sends the server program the handle that was received from this server program when access to the resource was opened.

Dereferencing handles requires fulfillment of the same conditions and utilizes the same mechanisms and data types as when transferring handles. A handle dereferencing scenario includes the following steps:

1. The client program packages the handle into a field of the *_req request structure of the nk_handle_desc_t type.
2. The client program calls the interface method for sending the handle to the server program for the purpose of performing operations with the resource. This method executes the Call() system call.
3. The server program receives the request by executing the Recv() system call.
4. The dispatcher on the server program side calls the method corresponding to the request. This method verifies that the dereferencing operation was specifically executed instead of a handle transfer. Then the called method has the option to verify that the access rights of the dereferenced handle (that was sent by the client program) permit the requested actions with the resource, and extracts the pointer to the resource transfer context from the field of the *_req request structure of the nk_handle_desc_t type.

To perform verifications, the server program utilizes the nk_is_handle_dereferenced() and nk_get_badge_op() functions that are declared in the nk/types.h header file.

types.h (fragment)

Generally, the server program does not require the handle that was received from dereferencing because the server program normally retains the handles that it owns, for example, within the contexts of user resources. However, the server program can extract this handle from the handle transport container if necessary.

[Topic libkos_handles_revoke]

Revoking handles

A program can revoke descendants of a handle that it owns. Handles are revoked according to the handle inheritance tree.

Revoked handles are not deleted. However, you cannot query resources via revoked handles. Any function that accepts a handle will end with the rcHandleRevoked error if this function is called with a revoked handle.

Handles are revoked by using the KnHandleRevoke() and KnHandleRevokeSubtree() functions declared in the coresrv/handle/handle_api.h header file. The KnHandleRevokeSubtree() function uses the resource transfer context object that is created when transferring handles.

handle_api.h (fragment)

[Topic libkos_handles_notification]

Notifying about the state of resources

Programs can track events that occur with resources (system resources as well as user resources), and inform other programs about events involving user resources.

Functions of the Notification Subsystem are declared in the coresrv/handle/notice_api.h header file. The Notification Subsystem provides for the use of event masks.

An event mask is a value whose bits are interpreted as events that should be tracked or that have already occurred. An event mask has a size of 32 bits and consists of a general part and a specialized part. The general part describes the general events that are not specific to any particular resource (the flags of these events are defined in the handle/event_descr.h header file). For example, the general part contains the EVENT_OBJECT_DESTROYED flag, which defines the "resource termination" event. The specialized part describes the events that are specific to a particular user resource. The structure of the specialized part is defined by the resource provider by using the OBJECT_EVENT_SPEC() macro that is defined in the handle/event_descr.h header file. The resource provider must export the public header files describing the structure of the specialized part.

The scenario for receiving notifications about events that occur with a resource consists of the following steps:

1. The KnNoticeCreate() function creates a notification receiver (object that stores notifications).
2. The KnNoticeSubscribeToObject() function adds "resource–event mask" entries to the notification receiver to configure it to receive notifications about events that occur with relevant resources. The set of tracked events is defined for each resource by an event mask.
3. The KnNoticeGetEvent() function is called to extract notifications from the notification receiver.

The KnNoticeSetObjectEvent() function is used to notify a program about events that occur with a user resource. A call of this function initiates the corresponding notifications in the notification receivers that are configured to track these events that occur with this resource.

notice_api.h (fragment)

[Topic libkos_handles_delete]

Deleting handles

A program can delete the handles that it owns. Deleting a handle does not invalidate its ancestors and descendants (in contrast to revoking a handle, which actually invalidates the descendants of the handle). In other words, the ancestors and descendants of a deleted handle can still be used to provide access to the resource that they identify. Also, deleting a handle does not disrupt the handle inheritance tree associated with the resource identified by the particular handle. The place of a deleted handle is occupied by its ancestor. In other words, the ancestor of a deleted handle becomes the direct ancestor of the descendants of the deleted handle.

Handles are deleted by using the KnHandleClose() function, which is declared in the coresrv/handle/handle_api.h header file.

handle_api.h (fragment)

[Topic libkos_handles_simple_scenario]

OCap usage example

This article describes an OCap usage scenario in which the server program provides the following methods for accessing its resources:

• OpenResource() – opens access to the resource.
• UseResource() – uses the resource.
• CloseResource() – closes access to the resource.

The client program uses these methods.

IDL description of interface methods:

The scenario includes the following steps:

1. The resource provider creates the user resource context and calls the KnHandleCreateUserObject() function to create the resource handle. The resource provider saves the resource handle in the user resource context.
2. The client calls the OpenResource() method to open access to the resource.
   1. The resource provider creates the resource transfer context and calls the KnHandleCreateBadge() function to create a resource transfer context object and configure the notification receiver to receive notifications regarding the closure or termination of the resource transfer context object. The resource provider saves the handle of the resource transfer context object and the pointer to the user resource context in the resource transfer context.
   2. The resource provider uses the nk_handle_desc() macro to package the resource handle, permissions mask of the handle, and pointer to the resource transfer context object into the handle transport container.
   3. The handle is transferred from the resource provider to the client, which means that the client receives a descendant of the handle owned by the resource provider.
   4. The OpenResource() method call completes successfully. The client extracts the handle and permissions mask of the handle from the handle transport container by using the nk_get_handle() and nk_get_rights() functions, respectively. The handle permissions mask is not required by the client to query the resource, but is transferred so that the client can find out its permissions for accessing the resource.
3. The client calls the UseResource() method to utilize the resource.
   1. The handle that was received from the resource provider at step 2 is used as an argument of the UseResource() method. Before calling this method, the client uses the nk_handle_desc() macro to package the handle into the handle transport container.
   2. The handle is dereferenced, after which the resource provider receives the pointer to the resource transfer context.
   3. The resource provider uses the nk_is_handle_dereferenced() function to verify that the dereferencing operation was completed instead of a handle transfer.
   4. The resource provider verifies that the access rights of the dereferenced handle (that was sent by the client) allows the requested operation with the resource, and extracts the pointer to the resource transfer context from the handle transport container. To do so, the resource provider uses the nk_get_badge_op() function, which extracts the pointer to the resource transfer context from the handle transport container if the received permissions mask has the corresponding flags set for the requested operation.
   5. The resource provider uses the resource transfer context and the user resource context to perform the corresponding operation with the resource as requested by the client. Then the resource provider sends the client the results of this operation.
   6. The UseResource() method call completes successfully. The client receives the results of the operation performed on the resource.
4. The client calls the CloseResource() method to close access to the resource.
   1. The handle that was received from the resource provider at step 2 is used as an argument of the CloseResource() method. Before calling this method, the client uses the nk_handle_desc() macro to package the handle into the handle transport container. After the CloseResource() method is called, the client uses the KnHandleClose() function to delete the handle.
   2. The handle is dereferenced, after which the resource provider receives the pointer to the resource transfer context.
   3. The resource provider uses the nk_is_handle_dereferenced() function to verify that the dereferencing operation was completed instead of a handle transfer.
   4. The resource provider uses the nk_get_badge() function to extract the pointer to the resource transfer context from the handle transport container.
   5. The resource provider uses the KnHandleRevokeSubtree() function to revoke the handle owned by the client. The resource handle owned by the resource provider and the handle of the resource transfer context object are used as arguments of this function. The resource provider obtains access to these handles through the pointer to the resource transfer context. (Technically, the handle owned by the client does not have to be revoked because the client already deleted it. However, the revoke operation is performed in case the resource provider is not sure if the client actually deleted the handle).
   6. The CloseResource() method call completes successfully.
5. The resource provider frees up the memory that was allocated for the resource transfer context and the user resource context.
   1. The resource provider calls the KnNoticeGetEvent() function to receive a notification that the resource transfer context object was closed, and uses the KnHandleClose() function to delete the handle of the resource transfer context object.
   2. The resource provider calls the KnNoticeGetEvent() function to receive a notification that the resource transfer context object has been terminated, and frees up the memory that was allocated for the resource transfer context.
   3. The resource provider uses the KnHandleClose() function to delete the resource handle and to free up the memory that was allocated for the user resource context.

[Topic libkos_notice]

Notifications

[Topic event_mask]

Event mask

An event mask is a value whose bits are interpreted as events that should be tracked or that have already occurred. An event mask has a size of 32 bits and consists of a general part and a specialized part. The general part describes the general events that are not specific to any particular resource (the flags of these events are defined in the handle/event_descr.h header file). For example, the general part contains the EVENT_OBJECT_DESTROYED flag, which defines the "resource termination" event. The specialized part describes the events that are specific to a particular user resource. The structure of the specialized part is defined by the resource provider by using the OBJECT_EVENT_SPEC() macro that is defined in the handle/event_descr.h header file. The resource provider must export the public header files describing the structure of the specialized part.

[Topic event_desc]

EventDesc

The structure describing the notification is declared in the file coresrv/handle/notice_api.h.

eventId is the ID of the "resource–event mask" entry in the notification receiver.

eventMask is the mask of events that occurred.

[Topic notice_create]

KnNoticeCreate()

This function is declared in the file coresrv/handle/notice_api.h.

This function creates a notification receiver named notice (object that stores notifications).

If successful, the function returns rcOk, otherwise it returns an error code.

[Topic notice_get_event]

KnNoticeGetEvent()

This function is declared in the file coresrv/handle/notice_api.h.

This function extracts notifications from the notice notification receiver while waiting for events to occur within the specific number of milliseconds (msec).

Input parameter countMax defines the maximum number of notifications that can be extracted.

Output parameter events contains a set of extracted notifications of the EventDesc type.

Output parameter count contains the number of notifications that were extracted.

If successful, the function returns rcOk, otherwise it returns an error code.

Example

[Topic notice_set_object_event]

KnNoticeSetObjectEvent()

This function is declared in the file coresrv/handle/notice_api.h.

This function signals that events from the event mask evMask occurred with the object resource.

You cannot set flags of the general part of an event mask because only the KasperskyOS kernel can provide signals regarding events from the general part of an event mask.

If successful, the function returns rcOk, otherwise it returns an error code.

[Topic notice_subscribe_to_object]

KnNoticeSubscribeToObject()

This function is declared in the file coresrv/handle/notice_api.h.

This function adds a "resource–event mask" entry to the notice notification receiver so that it can receive notifications about events that occur with the object resource and match the event mask evMask.

Input parameter evId defines the entry ID that is assigned by the user and is used to identify the entry in received notifications.

If successful, the function returns rcOk, otherwise it returns an error code.

For a usage example, see KnHandleCreateUserObject().

[Topic libkos_tasks]

Processes

[Topic entity_connect]

EntityConnect()

This function is declared in the header file coresrv/entity/entity_api.h.

This function connects processes with an IPC channel. To do so, the function creates IPC handles for the client process cl and the server process sr, and then binds the handles to each other. The created channel will be included into the default group of channels (the name of this group matches the name of the server process). The connected processes must be in the stopped state.

If successful, the function returns rcOk.

[Topic entity_connect_to_service]

EntityConnectToService()

This function is declared in the header file coresrv/entity/entity_api.h.

This function connects processes with an IPC channel. To do so, the function creates IPC handles for the client process cl and the server process sr, and then binds the handles to each other. The created channel will be added to the group of channels with the specified name. The connected processes must be in the stopped state.

If successful, the function returns rcOk.

[Topic entity_info]

EntityInfo

The EntityInfo structure describing the process is declared in the file named if_connection.h.

[Topic entity_init]

EntityInit()

This function is declared in the header file coresrv/entity/entity_api.h.

This function creates a process. The info parameter defines the name of the process class and (optionally) its endpoints, arguments and environment variables.

The created process will have the default name (matching the process class name), and the default name for the executable file (also matching the process class name).

If successful, the function returns the structure describing the new process. The created process is in the stopped state.

If an error occurs, the function returns RTL_NULL.

[Topic entity_init_ex]

EntityInitEx()

This function is declared in the header file coresrv/entity/entity_api.h.

This function creates a process.

The info parameter defines the name of the process class and (optionally) its endpoints, arguments and environment variables.

The name parameter defines the name of the process. If it has the RTL_NULL value, the process class name from the info parameter will be used as the process name.

The path parameter defines the name of the executable file in the solution's ROMFS image. If it has the RTL_NULL value, the process class name from the info parameter will be used as the file name.

If successful, the function returns the structure describing the new process. The created process is in the stopped state.

If an error occurs, the function returns RTL_NULL.

[Topic entity_run]

EntityRun()

This function is declared in the header file coresrv/entity/entity_api.h.

This function starts a process that is in the stopped state. The process is described by the entity structure.

If successful, the function returns rcOk.