Development for KasperskyOS

Starting processes

Overview: Einit and init.yaml

Einit initializing program

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

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

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

Generating the source code of the initializing program

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

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

Syntax of init.yaml

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

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

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

Process dictionary keys in an init description

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

IPC channel dictionary keys in an init description

Example init descriptions

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

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

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

init.yaml

Starting processes from defined executable files

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

init.yaml

Starting two processes from the same executable file

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

init.yaml

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

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

init.yaml

Setting the startup parameters and environment variables of programs

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

init.yaml

Starting processes using the system program ExecutionManager

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

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

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

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

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

ExecutionManager component usage scenario

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

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

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

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

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

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

     The CMake command create_execution_manager_entity() takes the following parameters:

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

     Optional parameters:

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

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

Overview: Env program

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

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

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

Source code of the Env program

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

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

Env program usage examples

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

Example of setting startup parameters of a program

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

env.c

Example of setting environment variables of a program

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

env.c

File systems and network

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

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

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

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

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

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

Using multiple VFS programs

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

Adding VFS functionality to an application

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

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

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

Contents of the VFS component

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

VFS libraries

The vfs CMake package contains the following libraries:

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

VFS executable files

The precompiled_vfs CMake package contains the following executable files:

• VfsRamFs
• VfsSdCardFs
• VfsNet

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

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

Formal specification files and header files of VFS

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

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

Libc library API supported by VFS

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

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

Functions implemented by the vfs_fs library

Functions implemented by the vfs_net library

Creating an IPC channel to VFS

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

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

Init description of the example:

init.yaml

Including VFS functionality in a program

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

VFS component libraries in a program

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

CMakeLists.txt

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

Overview: startup parameters and environment variables of VFS

VFS program startup parameters

• -l <entry in fstab format>

  The startup parameter -l mounts the defined file system.

• -f <path to fstab file>

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

Examples of using VFS program startup parameters

Environment variables of the VFS program

• UNMAP_ROMFS

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

  Example of using the UNMAP_ROMFS environment variable

• ROOTFS = <entry in fstab format>

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

  Example of using the ROOTFS environment variable

• VFS_CLIENT_MAX_THREADS

  The VFS_CLIENT_MAX_THREADS environment variable redefines the SDK configuration parameter VFS_CLIENT_MAX_THREADS.

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

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

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

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

Default values for startup parameters and environment variables of VFS

For the VfsRamFs executable file:

For the VfsSdCardFs executable file:

For the VfsNet executable file:

Mounting file systems when VFS starts

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

Using the startup parameter -l

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

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

init.yaml.(in)

CMakeLists.txt

Using the fstab file from the ROMFS image

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

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

init.yaml.(in)

CMakeLists.txt

Using an "external" fstab file

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

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

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

init.yaml.(in)

CMakeLists.txt

Using VFS backends to separate data streams

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

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

Process interaction scenario

Init description of the example:

init.yaml

Creating a VFS backend

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

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

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

Process interaction scenario

Source code of the VFS backend

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

backend.c

Linking the Client program

Creating a static VFS backend library:

CMakeLists.txt

Linking the Client program to the static VFS backend library:

CMakeLists.txt

Setting the startup parameters and environment variables of programs

Init description of the example:

init.yaml

Dynamically configuring the network stack

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

Configurable network stack parameters

MSS configuration example:

IPC and transport

Creating IPC channels

IPC channels can be created statically or dynamically.

Statically created IPC channels

Static creation of IPC channel has the following characteristics:

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

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

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

Dynamically created IPC channels

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

Dynamic creation of IPC channel has the following characteristics:

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

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

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

Adding an endpoint from KasperskyOS Community Edition to a solution

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

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

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

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

Example of adding a GPIO driver to a solution

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

The following commands connect the gpio CMake package:

.\CMakeLists.txt

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

einit\CMakeLists.txt

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

init.yaml.in

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

security.psl.in

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

client.c

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

client\CMakeLists.txt

Creating and using your own endpoints

Overview: IPC message structure

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

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

Constant part of an IPC message

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

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

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

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

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

IPC message arena

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

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

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

Maximum IPC message size

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

IPC message structure verification by the security module

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

Implementation of IPC interaction

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

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

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

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)

Working with an IPC message arena

Arena overview

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

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

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

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

API for working with an arena

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

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

Creating an arena

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Examples of creating an arena:

Adding data to an arena before transmission over IPC

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

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

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

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

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

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

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

Examples of adding data to an arena:

Retrieving data from an arena after receipt over IPC

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

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

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

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

Example of receiving data from an arena:

Additional capabilities of the API

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

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

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

Information about API functions and macros

Functions and macros of arena.h

Transport code in C++

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

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

Transport code

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

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

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

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

Generating transport code for development in C++

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

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

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

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

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

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

Mapping IDL types to C++ types

Working with transport code in C++

The scenarios for developing a client and server that exchange IPC messages are presented in the sections titled Statically creating IPC channels for C++ development and Dynamically creating IPC channels for C++ development.

Statically creating IPC channels for C++ development

To implement a client program that calls a method of an endpoint provided by a server program:

1. Include the generated header file (*.edl.cpp.h) of the client program description.
2. Include the generated header files of the descriptions of the utilized interfaces (*.idl.cpp.h).
3. Include the header files from the KasperskyOS SDK:
   • sysroot-*-kos/include/kosipc/application.h
   • sysroot-*-kos/include/kosipc/api.h
   • sysroot-*-kos/include/kosipc/connect_static_channel.h
4. Create and initialize the application object by calling the kosipc::MakeApplicationAutodetect() function. (You can also use the kosipc::MakeApplication() and kosipc::MakeApplicationPureClient() functions.)
5. Get the client IPC handle of the channel and the Runtime Implementation Identifier (RIID) by calling the kosipc::ConnectStaticChannel() function.

   This function gets the name of the IPC channel (from the init.yaml file) and the qualified name of the endpoint (from the CDL and EDL descriptions of the solution component).

6. Create and initialize the proxy object for the utilized endpoint by calling the MakeProxy() function.

To implement a server program that provides endpoints to other programs:

1. Include the generated header file *.edl.cpp.h containing a description of the component structure of the program, including all provided endpoints.
2. Include the header files from the KasperskyOS SDK:
   • sysroot-*-kos/include/kosipc/event_loop.h
   • sysroot-*-kos/include/kosipc/api.h
   • sysroot-*-kos/include/kosipc/serve_static_channel.h
3. Create classes containing the implementations of interfaces that this program and its components provide as endpoints.
4. Initialize the application object by calling the kosipc::MakeApplicationAutodetect() function.
5. Create and initialize the kosipc::components::Root structure, which describes the component structure of the program and describes the interfaces of all endpoints provided by the program.
6. Bind fields of the kosipc::components::Root structure to the objects that implement the corresponding endpoints.

   Fields of the Root structure replicate the hierarchy of components and endpoints that are collectively defined by the CDL and EDL files.

7. Get the server IPC handle of the channel by calling the ServeStaticChannel() function.

   This function gets the name of the IPC channel (from the init.yaml file) and the structure created at step 5.

8. Create the kosipc::EventLoop object by calling the MakeEventLoop() function.
9. Start the loop for dispatching incoming IPC messages by calling the Run() method of the kosipc::EventLoop object.

Dynamically creating IPC channels for C++ development

Dynamic creation of an IPC channel on the client side includes the following steps:

1. Include the generated description header file (*.edl.cpp.h) in the client program.
2. Include the generated header files of the descriptions of the utilized interfaces (*.idl.cpp.h).
3. Include the header files:
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/application.h
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/make_application.h
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/connect_dynamic_channel.h
4. Get the pointers to the server name and the qualified name of the endpoint by using a name server (NameServer system program). To do so, you must connect to the name server by calling the NsCreate() function and find the server that provides the required endpoint by using the NsEnumServices() function. For more details, refer to Dynamically creating IPC channels (cm_api.h, ns_api.h).
5. Create an application object by calling the kosipc::MakeApplicationAutodetect() function. (You can also use the kosipc::MakeApplication() and kosipc::MakeApplicationPureClient() functions.)
6. Create a proxy object for the required endpoint by calling the MakeProxy() function. Use the kosipc::ConnectDynamicChannel() function call as the input parameter of the MakeProxy() function. Pass the pointers for the server name and qualified name of the endpoint obtained at step 4 to the kosipc::ConnectDynamicChannel() function.

After successful initialization of the proxy object, the client can call methods of the required endpoint.

Example

Dynamic creation of an IPC channel on the server side includes the following steps:

1. Include the generated header file (*.edl.cpp.h) containing a description of the component structure of the server, including all provided endpoints, in the server program.
2. Include the header files:
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/application.h
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/event_loop.h
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/make_application.h
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/root_component.h
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/serve_dynamic_channel.h
   • /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/simple_connection_acceptor.h
3. Create classes containing the implementations of interfaces that the server provides as endpoints. Create and initialize the objects of these classes.
4. Create an application object by calling the kosipc::MakeApplicationAutodetect() function.
5. Create and initialize the kosipc::components::Root class object that describes the structure of components and endpoints of the server. This structure is generated from the descriptions in the CDL and EDL files.
6. Bind the kosipc::components::Root class object to the class objects created at step 3.
7. Create and initialize the kosipc::EventLoop class object that implements a loop for dispatching incoming IPC messages by calling the MakeEventLoop() function. Use the ServeDynamicChannel() function call as an input parameter of the MakeEventLoop() function. Pass the kosipc::components::Root class object created at step 5 to the ServeDynamicChannel() function.
8. Start the loop for dispatching incoming IPC messages in a separate thread by calling the Run() method of the kosipc::EventLoop object.
9. Create and initialize the object that implements the handler for receiving incoming requests to dynamically create an IPC channel.

   When creating an object, you can use the kosipc::SimpleConnectionAcceptor class, which is the standard implementation of the kosipc::IConnectionAcceptor interface. (The kosipc::IConnectionAcceptor interface is defined in the file named /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/kosipc/connection_acceptor.h.) In this case, the handler will implement the following logic: if the endpoint requested by the client was published on the server, the request from the client will be accepted. Otherwise, it will be rejected.

   If you need to create your own handler, you should implement your own request handling logic in the OnConnectionRequest() method inherited from the kosipc::IConnectionAcceptor interface. This method will be called by the server when it receives a request for dynamic IPC channel creation from the client.

   You must call the ServeDynamicChannel() function (see step 7) strictly before creating the kosipc::SimpleConnectionAcceptor object.

10. Create a kosipc::EventLoop class object that implements a loop for receiving incoming requests to dynamically create an IPC channel by calling the MakeEventLoop() function. Use the ServeConnectionRequests() function call as an input parameter of the MakeEventLoop() function. Pass the object created at step 9 to the ServeConnectionRequests() function.

    There can only be one loop for receiving incoming requests to dynamically create an IPC channel. The loop must work in one thread. The loop for receiving incoming requests to dynamically create an IPC channel must be created after the loop for dispatching incoming IPC channels is created (see step 7).

11. Start the loop for receiving incoming requests for a dynamic connection in the current thread by calling the Run() method of the kosipc::EventLoop object.

Example

If necessary, you can create and initialize multiple kosipc::components::Root class objects combined into a list of objects of the ServiceList type using the AddServices() method. For example, use of multiple objects enables you to separate components and endpoints of the server into groups or publish endpoints under different names.

Example

Working with KPA packages

A KPA package is a file in the proprietary KPA format that serves as packaging for a program intended for installation in a KasperskyOS-based solution. It includes the following elements:

• KPA package header. Unique sequence of bytes used to identify the KPA format.
• KPA package manifest. Data structure that describes a JSON file containing detailed information about the KPA package.
• KPA package components. Aligned byte sequences with arbitrary contents. KPA package components may include executable files, libraries, text data, or any other data required for the program to work.
• KPA package index. Data structure that describes the number of KPA package components, their checksums, and their sizes.

A compressed KPA package is a file in KPAC format. KPAC format is a variant of the ZIP format but with the following limitations: no directory hierarchy, no embedded ZIP archives, and a limit on the size and quantity of its archived files. A KPAC file contains a KPA package, its external signature, and an index file. The external signature of a KPA package is a file in the proprietary KCAT format that resides outside of the KPA package file. The external signature protects against spoofing and modifications of the KPA package itself and the index file of the KPA package. The index file of a KPA package is a file in the proprietary KIDX format that is used to check the integrity of the KPA package.

Managing KPA packages

KasperskyOS Community Edition includes the following resources for KPA package management:

• CMake library platform/kpa intended for building KPA packages during the KasperskyOS-based solution build process. When using functions of the CMake library platform/kpa, the KPA package manifest is created automatically.
• Tools that let you build a KPA package from program source files in the system where the SDK is installed and then install the KPA package in a built KasperskyOS-based solution image.
• PackageManager component that lets you install KPA packages in an operational KasperskyOS-based solution, remove KPA packages, and receive information about them.

KPA package manifest

A KPA package manifest is a JSON file that contains the information required when installing and using a KPA package. A list of the main keys for the KPA package manifest is presented in the table below.

Main keys of a KPA package manifest

Application object

The application object includes keys containing information about the program installed from the KPA package. A list of these keys is provided in the table below.

List of keys of an application object

Platform object

The platform object includes keys containing information about the target platform of the program. A list of these keys is provided in the table below.

List of keys of a platform object

List of "components" objects

The list of components objects includes keys containing information about the components added to the KPA package. A list of these keys is provided in the table below.

List of keys for describing a component instance in the list of components objects

List of runConfiguration objects

The list of runConfiguration objects includes keys containing information about the possible startup configurations of the program. A list of these keys is provided in the table below.

List of keys for describing a startup configuration instance for the list of runConfiguration objects

PrivateStorage object

The privateStorage object includes keys containing information about program data storage. A list of these keys is provided in the table below.

The privateStorage object is not supported in the current version of KasperskyOS Community Edition.

List of keys of a privateStorage object

Tools for managing KPA packages

KasperskyOS Community Edition includes the following tools for managing KPA packages:

• cas-pack for building a KPA package in a system where the SDK is installed.
• cas-inspect for getting information about KPA package contents when working with the SDK.
• cas-pm for installing one or more KPA packages in a built KasperskyOS-based solution image.

The executable files of these tools are located in the directory /opt/KasperskyOS-Community-Edition-<version>/toolchain/bin/.

cas-pack tool

KasperskyOS Community Edition includes the cas-pack tool (the toolchain/bin/cas-pack executable file) intended for building a KPA package in a system where the KasperskyOS Community Edition SDK is installed.

Syntax of the shell command for running the cas-pack tool:

Parameters:

• {-o|--output} <FILE>

  Full name of the built KPA package file.

• --manifest <FILE>

  Full name of the KPA package manifest file.

• <FILES>

  List of the full names of files that will be included in the KPA package. Use a space to separate list items. You can use the * character to select all files in the directory.

• --verify

  Verification of the presence of all KPA package components specified in its manifest and the absence of unspecified components, and calculation of the checksums of KPA package components and their comparison with those specified in the KPA package manifest.

• --version

  Tool version.

• -h|--help

  Help text.

Example of the shell command for running the cas-pack tool:

cas-inspect tool

The KasperskyOS Community Edition is delivered with the cas-inspect tool (toolchain/bin/cas-inspect executable file), which lets you get information about the contents of KPA package when working with SDK.

Syntax of the shell command for running the cas-inspect tool:

Parameters:

• {-i|--input} <PACKAGE>

  Path to the KPA package (*.kpa file).

• <COMMAND>

  Commands:

  • dump – prints to standard output the KPA package manifest and information about KPA package components, which includes the size in bytes (Size), offset in bytes (Offset – relative to the end of the KPA package manifest, and Absolute – relative to the start of the KPA package), and the checksum (Digest). This parameter is applied by default.
  • read <manifest|blobs|<hash> – prints the KPA package manifest (read manifest), the contents of all KPA package components (read blobs), or the contents of one KPA package component with the defined checksum (read <hash>). When using the -o <path> parameter, the output is printed to a file. Otherwise, it is printed to the standard output.
  • list – prints the checksum, offset (in bytes) relative to the start of the KPA package, and the size (in bytes) for all KPA package components to the standard output.
  • read-files <FILES>... – prints the contents of a KPA package component based on the component file name. You can specify multiple names of KPA package component files if you separate these names with a space. When using the -o <path> parameter, the output is printed to a file.
  • list-files – prints to standard output a list of all names of KPA package component files included in the KPA package manifest.
• -o <path>

  Path to the file or directory for saving data when using the commands read {manifest|blobs|<hash>} and read-files <FILES>.... When printing the KPA package manifest (read manifest) or the contents of the KPA package component with the defined checksum (read <hash>), you must specify the file path. When printing the contents of all program components (read blobs), you must specify the path to the directory where each program component will be saved in a separate file with a name matching the checksum of the specific component. When printing the contents of all KPA package components (read-files <FILES>...), you must specify the path to the directory where each KPA package component will be saved in a separate file with the name of the specific component.

• --verify

  Verification of the presence of all KPA package components specified in its manifest and the absence of unspecified KPA package components, and calculation of the checksums of KPA package components and their comparison with those specified in the KPA package manifest.

• -h|--help

  Help text.

• --version

  Tool version.

Examples of shell commands for running the cas-inspect tool:

cas-pm tool

KasperskyOS Community Edition includes the cas-pm tool (the toolchain/bin/cas-pm executable file), which installs KPA packages in a built KasperskyOS-based solution image.

Syntax of the shell command for running the cas-pm tool:

Parameters:

• {-p|--pkgsdir} <DIR>

  SDK host system path to the directory containing the KPA packages to be installed.

• {-d|--dbpath} <PATH>

  Full name of the SQLite database file that contains data on the installed KPA packages. If the database has not yet been created, it will be automatically generated upon startup of the tool with the specified name, and information about the installed KPA packages will be added to it.

  To ensure that the PackageManager component can detect the database after startup of the KasperskyOS-based solution, complete the following steps:

  1. After calling the cas-pm tool, copy the database file into the file system that will be put into the KasperskyOS-based solution image. If the full name of the database file was originally specified in this file system, this step can be omitted.
  2. The full name of the database file in the file system that will be put into the KasperskyOS-based solution image must be passed to the CMake command create_package_manager_entity() via the DB_PATH parameter (for more details, see PackageManager component usage scenario).
• {-a|--appsdir} <DIR>

  SDK host system path to the directory intended for storing KPA packages before they are written to the KasperskyOS-based solution image.

• --rootdir <DIR>

  Relative directory that will be used for installing KPA packages to the KasperskyOS-based solution image. Specify the directory in the file system that will be put into the KasperskyOS-based solution image. Information about the location of KPA packages will be entered into the database and will be required by the PackageManager component when removing KPA packages.

• {-l|--layout} <PATH>

  Full name of the JSON file that is used to redefine the paths for installing KPA package components. Specify the full file name in the system where the SDK is installed. By default, when a KPA package is installed, its components are put into directories depending on the specific type of KPA package component (for more details, see the componentType key in the article titled List of "components" objects). To change the names of the default directories, define your own values for the keys: bin, res, lib and manifestLocale. To ensure that the PackageManager component can detect KPA package components after the KasperskyOS-based solution is started, the name of this file must be passed in the CUSTOM_LAYOUT parameter of the CMake command create_package_manager_entity() (for more details, see PackageManager component usage scenario).

  Example of a custom_layout_schema.json file:

  { "bin" : "custom-bin-path", "res" : "CustomResPath", "lib" : "CustomLibPath", "manifestLocale" : "Custom_manifestLocale_Path" }
• {-e|--extention} <ARG>

  Extension for a KPA package file. The default value is kpa.

• {-r|--reinstall}

  Reinstallation of KPA packages.

• -v[v...]

  Log level for actions performed by the tool. The number of v characters indicates the log level. Messages are printed to standard output. Available values:

  • -v

    This level logs non-detailed information about normal operation of the tool, and errors and warnings about potential problems.

  • -vv[v...]

    This level adds detailed logging of tool operation information that may be useful to developers for troubleshooting.

• --sign-ext <ARG>

  Extension for a KPA package external signature file. For more details about a KPA package external signature, see Working with KPA packages.

• --index-ext <ARG>

  Extension for a KPA package index file. For more details about a KPA package index file, see Working with KPA packages.

• <PACKAGES>

  List of full names of installed KPA packages in the system where the SDK is installed. You do not need to specify the file extension. Use a space to separate list items.

• --version

  Tool version.

• -h|--help

  Help text.

Examples of shell commands for running the cas-pm tool:

PackageManager component usage scenario

The PackageManager component provides an API for managing KPA packages in solutions that are based on KasperskyOS.

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

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

Adding the PackageManager component to a KasperskyOS-based solution

Hereinafter the "client" refers to the program that uses the PackageManager component API to manage KPA packages.

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

1. Add the PackageManager program to a solution. To add PackageManager to a solution:
   • Add the following commands to the CMakeLists.txt root file:
   find_package (package_manager REQUIRED) include_directories (${package_manager_INCLUDE}) add_subdirectory (package_manager)
   • The PackageManager component is provided in the SDK as a set of static libraries and header files, and is built for a specific solution by using the CMake command create_package_manager_entity() from the CMake library package_manager.

     To build the PackageManager program, create a directory named package_manager in the root directory of the project. In the new directory, create a CMakeLists.txt file containing the create_package_manager_entity() command.

     The CMake command create_package_manager_entity() takes the following parameters:

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

     Optional parameters:

     • DEPENDS – additional dependencies for building the PackageManager program.
     • MAIN_CONN_NAME – name of the IPC channel for connecting to the PackageManager process. It must match the value of the mainConnection variable when calling the PackageManager API in the client code.
     • ROOT_PATH – path to the root directory for service files of the PackageManager program. The default value is "/ROOT".
     • PKGS_DIR – path to the directory containing the KPA packages to be installed.
     • PKG_EXTENSION – extension for the KPA package file.
     • DB_PATH – full name of the SQLite database file in the KasperskyOS-based solution image containing data on the installed KPA packages.
     • APPS_DIR – path to the directory where the KPA packages will be installed.
     • VFS_CLIENT_LIB – name of the client transport library used to connect the PackageManager program to the VFS program.
     • NK_MODULE_NAME – path for installing the header files of the PackageManager component in the SDK relative to the directory /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/. Default value: kl/package_manager.
     • AUDIT_CONN_NAME – name of the IPC channel for connecting to the AuditStorage process.
     • WITHOUT_SIGN_MODE – external signature verification mode: true – lack of an external signature is not considered an error, false – lack of an external signature is considered an error. The default value is false.
     • MANIFEST_SCHEMA_BUILD_STORE – path to the build directory of the KasperskyOS-based solution image containing the manifest schema.
     • MANIFEST_SCHEMA_RUNTIME_PATH – path to the directory of the started KasperskyOS-based solution containing the manifest schema.
     • PATH_TO_ADDITIONAL_EXTENSIONS_SCHEMAS – path to the directory containing additional manifest schemas for objects of an arbitrary format that are defined in the extentions key value of the KPA package manifest.
     • CUSTOM_LAYOUT – full name of the JSON file that is used to redefine the paths for installing KPA package components.
   include (package_manager/create_package_manager_entity) create_package_manager_entity( ENTITY PkgMgrEntity NK_MODULE_NAME "package_manager" MAIN_CONN_NAME "PkgMgrEntity" ROOT_PATH "/" PKGS_DIR "/packages" PKG_EXTENSION "kpa" DB_PATH "${DB_PATH}" APPS_DIR "${APPS_PATH}" MANIFEST_SCHEMA_BUILD_STORE "${CMAKE_BINARY_DIR}/rootdir/schema" MANIFEST_SCHEMA_RUNTIME_PATH "/schema" PATH_TO_ADDITIONAL_EXTENSIONS_SCHEMAS "${CMAKE_SOURCE_DIR}/resources/additional_extensions/" CUSTOM_LAYOUT "/custom_layout_schema.json" VFS_CLIENT_LIB vfs::client AUDIT_CONN_NAME "audit_storage" WITHOUT_SIGN_MODE TRUE)
   • When building a solution (CMakeLists.txt file for the Einit program), add the PackageManager program executable file to the KasperskyOS-based solution image:
2. Link the client executable file to the client proxy library of PackageManager by adding the following command to the CMakeLists.txt file for building the client:
   target_link_libraries (<name of the CMake target for building the client> ${package_manager_CLIENT_LIBS})
3. Add permissions for the necessary events to the solution security policy description:
   1. To enable the PackageManager program to manage KPA packages, the solution security policy must allow the following interactions for the package_manager.PkgMgrEntity process class:
      • Access to all endpoints of the VFS program.
      • Access to the core endpoints Sync, VMM, Thread, HAL, Handle, FS, Notice, CM and Profiler (their descriptions are located in the directory sysroot-*-kos/include/kl/core from the SDK).
   2. To enable a client to call the PackageManager program, the solution security policy must allow the following interactions for the client process class:
      • Access to the appropriate endpoints of the PackageManager program (their descriptions are located in the directory sysroot-*-kos/include/kl/package_manager from the SDK).
4. Use of the PackageManager program API in the client code.

   Use the header file component/package_manager/kos_ipc/package_manager_proxy.h for this. For more details, refer to PackageManager component.