[Topic whats_new]

What's new

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/drivers to KasperskyOS.
• Explore security issues in software development.

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.

Basic concepts

Frequently used terms related to KasperskyOS Community Edition are presented below:

• KasperskyOS is a microkernel operating system used for building secure software/hardware systems.
• Kaspersky Security System is a technology that lets you create a declarative description of a solution security policy and generate the Kaspersky Security Module based on this description.
• The Kaspersky Security Module is a kernel module that either allows or denies each IPC interaction in a solution.
• A solution consists of the KasperskyOS kernel, Kaspersky Security Module, and applications and system software integrated for operation within a software/hardware system.
• An entity is an application running in KasperskyOS.
• A service is a set of logically related methods available via the IPC mechanism (for example, a kernel service for allocating memory or a driver entity service for working with a block device).
• A handle is an identifier of a resource (for example, a memory area, port or network interface). This handle is used to access the specific resource.
• IPC (InterProcess Communication) is the mechanism used by entities to interact with each other and with the kernel.
• A solution security policy provides the logic for managing IPC interactions in a solution and is implemented by the Kaspersky Security Module.

[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 "Buster" version 10.7 x64.
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 partition (depending on the solution being developed).

To run examples based on the Raspberry Pi platform, you must use Raspberry Pi 4 Model B with a RAM volume equal to 2, 4, or 8 GB.

[Topic sdk_contents]

Distribution kit

The distribution kit of KasperskyOS Community Edition includes the following:

• DEB package for installation of KasperskyOS Community Edition, including:
  • Image of the KasperskyOS kernel
  • Components of KasperskyOS Community Edition
  • Set of tools for solution development (NK compiler, GCC compiler, GDB debugger, binutils toolset, QEMU emulator, and accompanying tools)
  • End User License Agreement
  • Information about third-party code (Legal Notices)
• Release Notes
• KasperskyOS Community Edition Developer's Guide (Online Help)

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

• Boost (v.1.71) 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.16) implements the TLS and SSL protocols as well as the corresponding encryption algorithms and necessary support code.

  Documentation: https://tls.mbed.org/kb

• 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

• Eclipse Mosquitto (v1.6.4) is a message broker that implements the MQTT protocol.

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

See also Information about third-party code.

[Topic imitations_and_known_problems]

Limitations and known issues

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

1. Symmetric multiprocessing (SMP) is not supported. Only one processor kernel is used.
2. Dynamically loaded libraries are not supported.
3. The maximum supported number of running applications (entities) is 32.
4. When an entity is terminated through any method (for example, return from the main execution thread), resources allocated by the entity are not released, and the entity goes to sleep. Entities cannot be started repeatedly.
5. You cannot start two or more entities with the same EDL description.
6. The system stops if no running entities remain, or if one of the driver entity threads has been terminated, normally or abnormally.

[Topic kos_overview]

KasperskyOS: overview

[Topic overview_intro]

Basic concepts of KasperskyOS

KasperskyOS-based solution

A KasperskyOS-based solution consists of a kernel, security module, and applications and system software integrated for operation within a software/hardware system. In KasperskyOS, processes are called entities. The kernel guarantees that entities are isolated and can interact only through the kernel (using system calls). Each entity in a solution has a static description, which defines the interfaces available to other entities. The specialized languages EDL, CDL and IDL are used to describe interfaces.

Cyber immune approach

A cyber immune approach is used to develop secure KasperskyOS-based solutions. This approach relies on choosing a way to divide the system into entities and setting certain rules governing their interactions (a solution security policy). A security policy is implemented by the Kaspersky Security Module, which is included in the solution.

Details about the cyber immune approach

Kaspersky Security System

Kaspersky Security System technology lets you develop and implement various security policies. Moreover, you can combine several security models, add your own models, and flexibly configure the rules for entity interactions. The specialized language PSL is used to formally describe a solution security policy. A Kaspersky Security Module for use in a specific solution is generated based on the PSL description.

KasperskyOS Community Edition

KasperskyOS Community Edition contains tools for developing secure KasperskyOS-based solutions, including:

• Image of the KasperskyOS kernel
• The NK compiler which is designed to generate the Kaspersky Security Module and auxilliary transport code
• Other tools for solution development (GCC compiler, GDB debugger, binutils toolset, QEMU emulator, and accompanying tools)
• A set of libraries that provide partial compatibility with the POSIX standard
• Components of KasperskyOS Community Edition
• Documentation
• Examples of basic KasperskyOS-based solutions

[Topic overview_cyberimmunity_basics]

Cyber immunity

The idea of cyber immunity is based on the following concepts:

• Security goals and prerequisites
• MILS concepts (security domain, separation kernel, reference monitor)
• Trusted computing base (TCB)

These concepts are considered below. Then definitions of a cyber immune system and cyber immune approach are given.

Security goals and prerequisites

Information system security is not a universal abstract concept. Whether a system is secure or not depends on chosen security goals and prerequisites.

Security goals are requirements placed on an information system, which if achieved, ensure the secure operation of the information system in every possible scenario, taking into account the security prerequisites. Example of a security goal: ensure that data is kept confidential while using a communication channel.

Security prerequisites are additional limitations placed on the conditions in which the system is used, which if satisfied, will achieve the security goals. Example of a security prerequisite: cybercriminals must not have physical access to the hardware.

MILS concepts

In the MILS (Multiple Independent Levels of Security) model, a secure information system consists of isolated security domains and a separation kernel that controls the interactions between domains. The separation kernel isolates domains and controls the information flows between them.

Each attempted interaction between security domains is checked for compliance with certain rules, which are specified by the solution security policy. If an interaction is forbidden by the current policy, then it is not allowed (it is blocked). In a MILS architecture, a separate component (reference monitor) implements the security policy. For each security domain interaction, the reference monitor returns a decision (a boolean value) regarding whether the interaction complies with the security policy. The separation kernel calls the monitor each time one domain references another.

Trusted computing base (TCB)

Trusted Computing Base (TCB) is the set of all programming code, which if vulnerable will prevent an information system from achieving its specified security goals. In the MILS model, the separation kernel and reference monitor underpin the trusted computing base.

The trusted computing base's reliability plays a key role in ensuring the security of an information system.

Cyber immune system

An information system is cyber immune (or possesses cyber immunity) if it is separated into isolated security domains, all interactions between which are independently controlled, and is:

• a description of its security goals and prerequisites;
• guarantees of the reliability of the entire trusted computing base, including an execution environment and mechanisms for interaction control;
• guarantees that security goals will be achieved in all possible use scenarios, given the specified prerequisites and an uncompromised trusted computing base.

Cyber immune approach

The cyber immune approach is a way to build cyber immune systems.

The cyber immune approach is based on:

• dividing the system into isolated security domains;
• independent control of all interactions between security domains in accordance with the specified security policy;
• ensuring the reliability of the trusted computing base.

Advantages of the cyber immune approach

The cyber immune approach lets you:

• reduce the security properties of a system as a whole to the security properties of its separate components;
• provide guarantees that a system's security goals will be achieved even if any of its untrusted components is compromised;
• reduce requirements on one or more system components relative to the requirements on the system as a whole;
• minimize damage to the system as a whole if any one of its component is compromised;
• simplify the process of system certification.

[Topic overview_isolation_and_ipc]

Isolation and interaction between entities

A cyber immune system consists of isolated parts (security domains in MILS terms) that can interact with one another only through a separation kernel, i.e. in a controlled manner. In KasperskyOS, security domains are implemented as entities.

[Topic overview_entities]

Entities

In KasperskyOS, each process is a subject in a solution security policy. When a process starts, the KasperskyOS kernel associates with it the context necessary for its execution, and with the Kaspersky Security Module – the security context necessary to control its interactions with other processes.

From the perspective of the KasperskyOS kernel, an entity is a process that has a separate address space and one or more threads of execution. The kernel guarantees isolation of the address spaces of entities. An entity can implement interfaces, and other entities can call the methods of these interfaces through the kernel.

From the perspective of the Kaspersky Security Module, an entity is a subject that other subjects (entities) can interact with. The types of interactions that are possible are specified by a description of the entity's interfaces that must match the implementation. Interface descriptions let the security module check each interaction for compliance with the solution security policy.

Additional information regarding entities

For the Kaspersky Security Module, the kernel is a subject just like an entity. Entities can call kernel methods, and these interactions are controlled like calls to methods of other entities. Accordingly, we will subsequently say that the kernel is a separate entity from the perspective of the Kaspersky Security Module.

[Topic overview_ipc]

Communication of entities (IPC)

KasperskyOS has only one way for entities to interact – through synchronous exchange of IPC messages: via a request and a response. In each interaction, there are two separate roles: client (the entity that initiates the interaction) and server (the entity that handles the request). Additionally, an entity that acts as a client in one interaction can act as a server in another.

The client and server use three system calls: Call(), Recv() and Reply():

1. The client sends a request to the server. To do this, one of the client's threads calls Call() and blocks until a response is received from the server or kernel (in the event of an error, for example).
2. A server thread calls Recv() and waits for messages. When a request is received, this thread unblocks, handles the request, and sends a response by calling Reply().
3. When a response is received (or an error occurs), the client thread unblocks and continues execution.

   

Exchanging messages as method calls

An entity's IPC request to a server is a call to one of the interfaces implemented by the server. The IPC request contains input arguments for the called method, the ID of the interface implementation (RIID), and the ID of the called method (MID). Upon receiving a request, the server entity uses these identifiers to find the method's implementation. The server calls the method's implementation, passing in the input arguments from the IPC request. After handling the request, the server entity sends the client a response that contains the method's output arguments.

IPC channels

To enable two entities to exchange messages, an IPC channel, also referred to as a "channel" or "connection", must be established between them. The channel specifies the entities' roles, i.e. "client" and "server". Additionally, an entity can have several channels in which it is the client, and several channels in which it is the server.

KasperskyOS has two mechanisms for creating IPC channels:

1. The static mechanism involves creating a channel when the entity is started (when the solution is started). Channels are created statically by the initializing Einit entity.
2. The dynamic mechanism allows started entities to establish a channel between one another.

[Topic overview_idl_cdl_edl]

Describing entities' interfaces (EDL, CDL, IDL)

To control interactions between entities, the structure of the sent IPC messages must be transparent to the security module. In KasperskyOS, this is achieved using a static declaration of entities' interfaces. Special languages are used for this: Entity Definition Language (EDL), Component Definition Language (CDL) and Interface Definition Language (IDL). If an IPC message does not match an interface description, it will be rejected by the security module.

Types of static descriptions

A description of entities' interfaces is built using an "entity-component-interface" model:

• An IDL description declares an interface, as well as user types and constants (optional). Taken together, all of the IDL descriptions in a solution encompass all the interfaces implemented in the solution.
• A CDL description lists the interfaces implemented by a component. Components make it possible to group interface implementations. Components can include other components.
• An entity's EDL description declare instances of the components included in the entity. An entity may include no components.

Example

Below are static declarations of a solution consisting of a Client entity that does not implement a single interface, and a Server entity that implements the FileOps interface.

For more details, refer to Syntax of static declarations.

[Topic overview_ipc_transport]

IPC transport

To implement entity interactions, we need transport code, which is responsible for properly creating, packing, sending, unpacking, and dispatching IPC messages. Developing solutions for KasperskyOS does not require writing your own transport code. Instead, you can use special tools and libraries included in KasperskyOS Community Edition.

Transport code for developed components

Someone developing new components for KasperskyOS can generate transport code based on static definitions of the components. To achieve this, KasperskyOS Community Edition includes the NK compiler. The NK compiler lets you generate transport methods and types for use by both clients and servers.

Transport code for included components

The functionality of most components included in KasperskyOS Community Edition may be used in a solution both locally (through static linking with the developed code) and via IPC.

The following transport libraries are used to separate a component into a server entity and use it via IPC:

• The component's client library converts local calls into IPC requests to the driver entity.
• The component's server library receives IPC requests to the driver entity and converts them into local calls.

To use a component via IPC, it's enough to link its implementation to the server library, and to link the client entity to the client library.

For more details, refer to IPC and transport.

[Topic overview_interaction_control]

Interaction control

In a cyber immune system, each attempted interaction between isolated parts of the system (security domains in MILS terms) is checked for compliance with certain rules that are specified by the system's security policy. If an interaction is forbidden by the current policy, then it is not allowed. Below we consider how this principle is implemented in KasperskyOS.

[Topic overview_ksm]

Kaspersky Security Module

For each developed solution, Kaspersky Security System technology lets you generate code for the Kaspersky Security Module that implements the specified security policy. The security module controls all interactions between entities, i.e. in MILS terms, it is a security monitor.

Controlling IPC messages

The kernel calls the Kaspersky Security Module each time one entity sends a message to another entity. The security module checks whether the message structure corresponds to the description of the called method. If so, then the security module calls all the rules associated with this message and makes a decision: "allowed" or "denied". The kernel enforces the resulting decision, i.e. delivers the message only if the decision is "allowed".

IPC responses are controlled just like IPC requests. This may be used, for example, to guarantee the integrity of responses.

The kernel delivers the IPC message only if Kaspersky Security Module allows delivery

Controlling startup of entities

The kernel also calls the security module each time when an entity is started. This is usually used to initialize the entity's security context.

Security interface

Entities can directly query the Kaspersky Security Module using the security interface to report information about their state or the context of some event. Additionally, the security module enforces all rules associated with the called method of the security interface. Then the entity itself can use the decision received from the security module. The security interface is used, for example, to implement entities that control access to resources.

[Topic overview_psl]

Policy Specification Language (PSL)

The most important part of Kaspersky Security System technology is the PSL language (Policy Specification Language). It lets you describe a solution security policy formally, close to the terms of the task itself. The resulting PSL description is used to generate the code of a Kaspersky Security Module for the specific solution. This is done by using the NK compiler provided in KasperskyOS Community Edition. Thus, a solution's PSL description is the connecting link between the informal description of a policy and its implementation.

The PSL language lets you use various data structures and combine several security models.

[Topic overview_resource_acces_control]

Managing access to resources

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. By receiving a handle, a process obtains access to the resource that is identified by this handle. Processes can transfer handles to other processes. 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 models being used. For example, a security context may contain the state of a resource and the levels of integrity of subjects and/or access objects. If a security context stores the state of a resource, this lets you allow certain actions to be taken 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 management by the KasperskyOS kernel

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

Each handle is associated with rights to access the resource identified by this handle, which means it is a capability in OCap terms. By receiving a handle, a process obtains the rights to access the resource that is identified by this handle. The kernel assigns rights to access system resources and verifies these rights when processes attempt to use the system resources. The kernel also 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 management by resource providers

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

If a resource is queried by its name (for example, to open it), the security module cannot be used to manage 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.

Processes that use the resources provided by resource providers or by the kernel are referred to as resource consumers. When a resource consumer opens a user resource, the resource provider sends the consumer the handle associated with the rights to access this resource. In addition, the resource provider decides which specific rights for accessing the resource will be granted to the resource consumer. Before actions are taken on a resource 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.

[Topic overview_trusty_tcb]

TCB reliability

A cyber immune system must provide guarantees regarding the reliability of the entire trusted computing base (TCB). These guarantees can be provided only if the trusted computing base is sufficiently compact. Below we will consider how this requirement is achieved in KasperskyOS-based solutions.

[Topic overview_microkernel_architecture]

Microkernel architecture

The foundation of any solution's trusted computing base is the kernel. The KasperskyOS kernel consists of just three system calls and performs only a small number of the most important functions, including the isolation and interaction of entities, scheduling, and memory management. As a result, the kernel is compact and has a small attack surface, which minimizes the number of potential vulnerabilities.

Moreover, device drivers and resource providers (for example, file system implementations) are user applications. Potential errors in them cannot affect the stability of the kernel. However, a KasperskyOS-based solution may have a potentially untrusted device driver or resource provider. This reduces the solution's trusted computing base and increases its reliability.

The combination of a microkernel architecture and security module makes it possible to control all interactions between a driver (or resource provider) and other entities, as well as all interactions with the kernel to ensure compliance with the specified solution security policy.

[Topic overview_trusted_components]

Reliability of trusted components

A solution's trusted computing base may include various trusted components, in addition to the KasperskyOS microkernel and security module. Depending on the security goals and prerequisites, device drivers and resource provider may be trusted components. The KasperskyOS architecture and toolset lets you increase the reliability of trusted components.

Removing a trusted component into a separate entity

A solution developer can increase TCB reliability by reducing the size of trusted components. To achieve this, they should be separated from the remaining (untrusted) code, i.e. removed into separate entities. KasperskyOS Community Edition includes transport libraries and tools for generating transport code, which lets you implement nearly any component as a separate entity for which every interaction is controlled.

Creating duplicate components

Another way to raise TCB reliability is to limit the influence of untrusted components on trusted components by separating their threads. To do this, a component can be used independently in several entities. For example, the VFS component is responsible for implementing file systems and the network stack in KasperskyOS. If we include VFS instances in different entities, each of them will work with its own implementation of the file system and/or network stack. This is how separation of the threads of trusted and untrusted entities are separated and, accordingly, how TCB reliability is increased.

[Topic arch_solution_image]

KasperskyOS-based solution image

The boot image of a final KasperskyOS-based solution contains the following:

• Image of the KasperskyOS kernel
• Security module
• Einit entity, which starts all other entities
• All entities included in the solution, including drivers, service entities, and entities that implement the business logic

Building a solution image

A solution image is built using a specialized script that is provided in KasperskyOS Community Edition.

The KasperskyOS kernel image, service entities and driver entities are included in KasperskyOS Community Edition. A security module and Einit entity are built for each specific solution.

Starting a solution

A solution is started as follows:

1. The bootloader loads the KasperskyOS kernel.
2. The kernel finds the security module and loads it.
3. The kernel starts the Einit entity.
4. The Einit entity starts all other entities 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 sdk_install_and_remove]

Installation and removal

Installation

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

To deploy the package using gdebi, 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-arm-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-arm-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:

   $ sudo ./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 running_sample_programs_rpi]

Running examples on Raspberry Pi 4 B

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 ARMv7, which will automatically run the example. To do this, run the following commands:

   $ sudo apt install gcc-arm-linux-gnueabi gcc-arm-linux-gnueabihf git bison flex

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

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

   $ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- rpi_4_32b_defconfig

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

   # the 'Enable a default value for bootcmd' option. In the 'bootcmd value' field, enter

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

   # Then exit the menu after saving the settings.

   $ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- menuconfig

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

2. Format the SD card. To do this, connect the SD card to the computer and run the following commands:

   $ wget https://downloads.raspberrypi.org/raspbian_lite_latest

   $ unzip raspbian_lite_latest

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

   # for the SD card.

   $ sudo dd bs=4M if=$(ls *raspbian*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

4. Copy the configuration file for the U-Boot bootloader to the SD card. To do so, go to the directory /opt/KasperskyOS-Community-Edition-<version>/examples and run the following commands:

   $ sudo cp config.txt ~/mnt/fat32/config.txt

   $ sync

   $ sudo umount ~/mnt/fat32

Running an example on a 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. 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

3. Connect the bootable SD card to the Raspberry Pi 4 B.
4. 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 ch1_posix]

Part 1. Simple application (POSIX)

KasperskyOS Community Edition includes a set of libraries (libc, libm and libpthread) ensuring that the developed applications are partially compatible with the POSIX family of standards.

This part of the Guide illustrates the following:

• Printing a string to the screen by using fprintf()
• Using VFS component for working with a network and file systems
• Creating the Einit initializing entity
• POSIX support limitations

[Topic hello_example]

hello example

In the software development world, learning a new technology traditionally starts with using that technology to greet the world. We will keep that tradition with KasperskyOS, so we begin with an example that displays Hello world! on the screen.

The hello.c code looks familiar and simple to a developer that uses C, and is fully compatible with POSIX:

To run the Hello file in KasperskyOS, multiple additional actions are required.

EDL description of the Hello entity

A static description of the Hello entity consists of a single file named Hello.edl that must indicate the entity name:

The second part of the Guide shows examples of more complex EDL descriptions, and also presents CDL and IDL descriptions.

Creating the Einit initializing entity

If you want the Hello entity to start after the operating system is loaded, all you need to do is specify its name in the init.yaml file and build an Einit entity from it.

Build scheme for the hello example

The general build scheme for the hello example looks as follows:

Building and running the hello example

See the Building and running examples section.

[Topic vfs_chapter]

VFS: working with a network and files

[Topic vfs_overview]

VFS: overview

The VFS component contains the implementations of file systems and the network stack. POSIX calls for working with file systems and the network are sent to the VFS component, which then calls the block device driver or network driver, respectively.

Multiple copies of the VFS component can be added to a solution to separate the data streams of different entities. Each VFS copy is built separately and can contain the entire VFS functionality or a specific part of it, for example:

• One or more file systems
• Network stack
• Network stack and network driver

The VFS component can be used either directly (through static linking) or via IPC (as a separate entity). Use of VFS functionality via IPC enables the solution developer to do the following:

• Use a solution security policy to control method calls that work with the network and file systems.
• Connect multiple client entities to one VFS entity.
• Connect one client entity to two VFS entities to separately work with the network and file systems.

[Topic vfs_entity_build]

Building a VFS entity

KasperskyOS Community Edition does not provide a ready-to-use image for an entity containing the VFS component. The solution developer can independently build one or more entities that each include the specific VFS functionality necessary for the solution.

Building a network VFS

To build a "network" VFS entity containing a network driver, the file containing the main() function must be linked to the vfs_server, vfs_net and dnet_implementation libraries:

Using a "network" VFS entity linked to a network driver

To use a network driver via IPC (as a separate entity), the dnet_client library must be used instead of the dnet_implementation library:

Using a "network" VFS entity and a network driver as a separate entity

Building a file VFS

To build a "file" VFS entity, the file containing the main() function must be linked to the vfs_server and vfs_fs libraries and to the libraries for implementing file systems:

In this example, the VFS entity is prepared to connect to the ramdisk driver entity.

A block device driver cannot be linked to VFS and is always used via IPC:

Using a "file" VFS entity and a driver as a separate entity

[Topic vfs_env_entity]

Env entity

The Env service entity allows running entities to pass arguments and environment variables. When started, each entity automatically sends a request to the Env entity and receives the necessary data.

By including the Env entity in the solution, you can mount file systems when VFS is started, connect one client entity to two VFS entities, and perform many other tasks.

To use the Env entity in your solution, the following is required:

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

2. Build an image of the entity by linking it to the env_server library.

3. In the init description, indicate that the Env entity must be started and connected to the selected entities (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 entity image in the solution image.

Env entity code

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

• ENV_REGISTER_ARGS(name,argarr) – arguments from the argarr array will be passed to the entity named name.
• ENV_REGISTER_VARS(name,envarr) – environment variables from the envarr array will be passed to the "name" entity.
• ENV_REGISTER_PROGRAM_ENVIRONMENT(name,argarr,envarr) – arguments and environment variables will be passed to the entity named name.
• envServerRun() – initialize the server part of the entity so that it can respond to requests.

Example:

Init.yaml example for use of the Env entity

In the next example, the Client entity will be connected to the Env entity whose image is located in the env folder:

[Topic vfs_separate]

Connecting a client entity to one or two VFS entities

Calls of network- and file POSIX functions can be forwarded to two separate VFS components by connecting a client entity to two different VFS entities. If such data stream separation is not required (for example, if the client only works with the network), connecting the client entity to a single VFS entity is enough.

Connecting to one VFS entity

The name of the IPC channel between the client entity and the VFS entity must be defined by the _VFS_CONNECTION_ID macro declared in the vfs/defs.h file. In this case, "network" calls and "file" calls will be sent to this VFS entity.

Example:

Connecting to two VFS entities

Let's examine a client entity that is connected to two different VFS entities. We will name them "network" VFS and "file" VFS.

The _VFS_NETWORK_BACKEND environment variable is used so that "network" calls from the client entity are sent only to the "network" VFS:

• For the "network" VFS entity: _VFS_NETWORK_BACKEND=server:<name of the IPC channel to the "network" VFS>
• For the client entity: _VFS_NETWORK_BACKEND=client: <name of the IPC channel to the "network" VFS>

The analogous _VFS_FILESYSTEM_BACKEND environment variable is used to send "file" calls:

• For the "file" VFS entity: _VFS_FILESYSTEM_BACKEND=server:<name of the IPC channel to the "file" VFS>
• For the client entity: _VFS_FILESYSTEM_BACKEND=client: <name of the IPC channel to the "file" VFS>

As a result, the functions for working with the network and files will be sent to two different VFS entities.

In the next example, the Client entity is connected to two VFS entities – the "network" VfsFirst entity and the "file" VfsSecond entity:

Env entity code:

[Topic vfs_mount_filesystems]

Mounting file systems when VFS starts

By default, the VFS component provides access to the following:

• RAMFS file system. RAMFS is mounted to the root directory by default.
• ROMFS object storage. The storage contains non-executable files (including configuration files) that are added to the solution image during the build. The ROMFS file system is not mounted by default. However, the storage can be accessed indirectly through the -f argument, for example.

If you need to mount other file systems, this can be done either by using the mount() call after the VFS starts or immediately when the VFS starts by passing the following arguments and environment variables to it:

• -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.

• 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.

Example:

[Topic posix_uns_ifaces]

POSIX support limitations

KasperskyOS uses a limited POSIX interface oriented toward the POSIX.1-2008 standard (without XSI support). These limitations are primarily due to security precautions.

Limitations affect the following:

• Interaction between processes
• Interaction between threads via signals
• Standard input/output
• Asynchronous input/output
• Use of robust mutexes
• Terminal operations
• Shell usage
• Management of file handles

Limitations include:

• Unimplemented interfaces
• Interfaces that are implemented with deviations from the POSIX.1-2008 standard
• Stub interfaces that do not perform any operations except assign the ENOSYS value to the errno variable and return the value -1

Limitations on interaction between processes

Limitations on interaction between threads via signals

Standard input/output limitations

Asynchronous input/output limitations

Limitations on the use of robust mutexes

Terminal operation limitations

Shell operation limitations

Limitations on management of file handles

Page top

[Topic ch2_interaction]

Part 2. Interaction between entities

The preceding part of the Guide shows how to configure interaction with the entities provided in KasperskyOS Community Edition. To do so, just add several strings to the init.yaml file and link the client library of the entity (vfs_remote).

But how do you create a server entity, or in other words, an application that provides functionality to other (client) entities? To do so, utilize IPC transport, auxiliary tools and libraries provided in KasperskyOS Community Edition.

This part of the Guide illustrates the following:

• Mechanism for interaction between entities in KasperskyOS
• Tools and libraries that implement transport
• Step-by-step actions for exchanging IPC messages

[Topic ipc_transport_instruments]

IPC transport tools

To set up interactions between entities, you do not have to implement the correct packaging and unpacking of messages from scratch. In addition, you do not have to write separate code for creating IPC channels.

To resolve these and other problems associated with IPC transport, KasperskyOS provides a special set of tools:

• NkKosTransport
• EDL, CDL and IDL descriptions
• NK compiler
• Init description and einit tool
• Service Locator

NkKosTransport

NkKosTransport is a convenient wrapper for the Call, Recv and Reply system calls. It lets you work separately with messages' constant parts and arenas.

The nk_transport_call(), nk_transport_recv() and nk_transport_reply() functions are used to call transport.

Example:

The NkKosTransport structure and methods for working with it are declared in the transport-kos.h file:

For more details about the constant part and the arena, refer to IPC message structure.

For more details about using NkKosTransport, refer to NkKosTransport.

EDL, CDL and IDL descriptions

The EDL, CDL and IDL languages are used to describe interfaces that implement server entities.

For more details, refer to Description of entities, components, and interfaces (EDL, CDL, IDL).

Description files (*.edl, *.cdl and *.idl) are processed by the NK compiler during the build. This results in the creation of the *.edl.h, *.cdl.h, and *.idl.h files, which contain the transport methods and types used on the client and on the server.

NK compiler

Based on the EDL-, CDL- and IDL descriptions, the NK compiler (nk-gen-c) generates a set of transport methods and types. The transport methods and types are needed for generating, sending, receiving and processing IPC messages.

Most important transport methods:

• Interface methods. When an interface method is called on the client, the server is sent an IPC request for calling the appropriate method.
• Dispatch methods (dispatchers). When receiving a request, the server calls the dispatcher, which in turn calls the implementation of the appropriate method.

Most important transport types:

• Types that define the structure of the constant part of a message. They are sent to interface methods, dispatchers and transport functions (nk_transport_recv(), nk_transport_reply()).
• Types of proxy objects. A proxy object is used as an argument in an interface method.

For more details, refer to Generated methods and types.

Init description and einit tool

The einit tool lets you automate the creation of code of the Einit initializing entity. This entity is the first to start when KasperskyOS is loaded. Then it starts the other entities and creates channels (connections) between them.

To enable the Einit entity to create a connection between entities A and B during startup, you need to specify the following in the init.yaml file:

For more details, refer to Entity startup.

Service Locator

The Service Locator is a library containing the following functions:

• ServiceLocatorConnect() lets you find out the client IPC handle of the channel with a specified name.
• ServiceLocatorRegister() lets you find out the server IPC handle of the channel with a specified name.
• ServiceLocatorGetRiid() lets you find out the RIID (Runtime Interface ID) using an interface implementation name.

The values of the IPC handle and RIID are used during NkKosTransport initialization.

To use Service Locator, you need to include the sl_api.h file in the entity code:

For more details, refer to Service Locator.

[Topic echo_example]

echo example

The echo example demonstrates the use of IPC transport.

It shows how to use the main tools that let you implement interaction between entities.

[Topic about_echo_example]

About the echo example

The echo example describes a basic case of interaction between two entities:

1. The Client entity sends a number (value) to the Server entity.
2. The Server entity modifies this number and sends the new number (result) to the Client entity.
3. The Client entity prints the result to the screen.

   

To set up this interaction between entities:

1. Connect the Client and Server entities by using the init description.
2. On the server, implement an interface with a single Ping method that has one input argument (the original number (value)) and one output argument (the modified number (result)).

   Description of the Ping method in the IDL language:

   Ping(in UInt32 value, out UInt32 result);

   

3. Create static description files in the EDL, CDL and IDL languages. Use the NK compiler to generate files containing transport methods and types (proxy object, dispatchers, etc.).
4. In the code of the Client entity, initialize all required objects (transport, proxy object, request structure, etc.) and call the interface method.
5. In the code of the Server entity, prepare all the required objects (transport, component dispatcher and entity dispatcher, etc.), accept the request from the client, process it and send a response.

The echo example consists of the following source files:

• client/src/client.c – implementation of the Client entity.
• server/src/server.c – implementation of the Server entity.
• resources/Server.edl, resources/Client.edl, resources/Ping.cdl, resources/Ping.idl – static descriptions.
• init.yaml – init description.

[Topic echo_client_implementation]

Implementation of the Client entity in the echo example

The code of the Client entity uses the transport types and methods that will be generated during the solution build by the NK compiler based on the IDL description of the Ping interface.

However, to obtain the descriptions of types and signatures of methods required for implementing the entity, you can use the NK compiler immediately after creating an EDL description of the entity, CDL descriptions of components and IDL descriptions of the interfaces used for interaction. As a result, the required types and signatures of methods will be declared in the generated *.h files.

In the Client entity implementation, the following is required:

1. Get the client IPC handle of the connection (channel) by using the ServiceLocatorConnect() function.

   Input the name of the IPC server_connection predefined in the init.yaml file.

2. Initialize NkKosTransport by passing the obtained IPC handle to the NkKosTransport_Init() function.
3. Obtain the ID of the required interface (RIID) by using the ServiceLocatorGetRiid() function.
4. Input the full name of the Ping interface implementation. It consists of the names of the component instance (Echo.ping) and interface (ping) that were previously defined in Server.edl and Ping.cdl.
5. Initialize the proxy object by passing the transport and interface ID to the Ping_proxy_init() function.
6. Prepare the request and response structures.
7. Call the Ping_Ping() interface method by passing the proxy object and the pointers to the request and response.

[Topic echo_server_implementation]

Implementation of the Server entity in the echo example

The code of the Server entity uses the transport types and methods that will be generated during the solution build by the NK compiler based on the EDL description of the Server entity.

However, to obtain the types and signatures of methods required for implementing the entity, you can use the NK compiler immediately after creating an EDL description of the entity, CDL descriptions of components and IDL descriptions of the interfaces used for interaction. As a result, the required types and signatures of methods will be declared in the generated *.h files.

In the server entity implementation, the following is required:

1. Implement the Ping() method.

   The signature of the Ping() method implementation must exactly match the signature of the Ping_Ping() interface method that is declared in the Ping.idl.h file.

2. Get the server IPC handle of the connection (channel) by using the ServiceLocatorRegister() function.

   Input the name of the IPC server_connection predefined in the init.yaml file.

3. Initialize NkKosTransport by passing the obtained IPC handle to the NkKosTransport_Init() function.
4. Prepare the request and response structures.
5. Initialize the dispatch method (dispatcher) of the Ping component by using the Ping_component_init() function.
6. Initialize the dispatch method (dispatcher) of the Server entity by using the Server_entity_init() function.
7. Receive a request by calling nk_transport_recv().
8. Process the received request by calling the Server_entity_dispatch() dispatcher.

   The dispatcher calls the required implementation of the method based on the interface ID (RIID) received from the client.

9. Send the response to the Client entity by calling nk_transport_reply().

[Topic echo_description_files]

Description files in the echo example

Description of the Client entity

The Client entity does not implement an interface, so all you need to do is declare the entity name in its EDL description:

Server entity description

The description of the Server entity must contain information stating that it implements the Ping interface. Using static descriptions, you need to insert the implementation of the Ping interface into the new component (for example, Ping) and insert the instance of this component into the Server entity.

The Server entity contains an instance of the Ping component:

The Ping component contains the implementation of the Ping interface:

The Ping package contains a declaration of the Ping interface:

Init description

To enable the Client entity to call a method of the Server entity, a connection (IPC channel) must be created between them.

To do so, in the init description indicate that the Client and Server entities must be started and connect them:

The Server entity is indicated as - target, so it will perform the server entity role, meaning it will accept requests from the Client entity and respond to them.

[Topic echo_example_build]

Building and running the echo example

See the Building and running examples section.

The build scheme for the echo example looks as follows:

Page top

[Topic ch3_security]

Part 3. Solution security policy

Preceding parts of the Guide show how to implement interaction between entities. For simplicity, all solutions were built without a security module (ksm.module), which is provided by Kaspersky Security System.

Kaspersky Security System is the subsystem that monitors queries sent between entities and other events. This means that you can divide a solution into entities, manage their interactions, and thereby enhance the security of the solution.

This part of the Guide illustrates the following:

• PSL language syntax
• Security models supported in Kaspersky Security System
• Example of a solution security policy

[Topic ssp_descr_general_inf]

General information about a solution security policy description

In simplified terms, a solution security policy description consists of bindings that associate descriptions of security events with calls of methods provided by objects of security models. A security model object is an instance of a class whose definition is a formal representation of the security model (in a PSL file). Formal representations of security models contain signatures of methods of security models that determine the permissibility of interactions between different entities and between entities and the KasperskyOS kernel. These methods are divided into two types:

• Rules of security models are methods of security models that return a "granted" or "denied" result. Security model rules can change security contexts (for information about a security context, see "Managing access to resources").
• Expressions of security models are methods of security models that return values that can be used as input data for other methods of security models.

A security model object provides methods that are specific to one security model and stores the parameters used by these methods (for example, the initial state of a finite-state machine or the size of a container for specific data). The same object can be applied for multiple resources. However, this object will independently use the security contexts of these resources. Likewise, multiple objects of one or more security models can be applied for the same resource. In this case, different objects will use the security context of the same resource without any reciprocal influence.

Security events serve as signals indicating the initiation of interaction between different entities and between entities and the KasperskyOS kernel. Security events include the following events:

• Clients send IPC requests.
• Servers or the kernel send IPC responses.
• The kernel or entities initialize the startup of entities.
• The kernel starts.
• Entities query the Kaspersky Security Module via the security interface.

Security events are processed by the security module.

Security models

The KasperskyOS SDK provides PSL files that describe the following security models:

• Base – methods that implement basic logic.
• Pred – methods that implement comparison operations.
• Bool – methods that implement logical operations.
• Math – methods that implement integer arithmetic operations.
• Struct – methods that provide access to structural data elements (for example, access to parameters of interface methods transmitted in IPC messages).
• Regex – methods for text data validation based on regular expressions.
• HashSet – methods for working with one-dimensional tables associated with resources.
• StaticMap – methods for working with two-dimensional "key–value" tables associated with resources.
• Flow – methods for working with finite-state machines associated with resources.

Security event processing by the Kaspersky Security Module

The Kaspersky Security Module calls all methods (rules and expressions) of security models related to an occurring security event. If all rules returned the "granted" result, the security module returns the "granted" decision. If even one rule returned the "denied" result, the security module returns the "denied" decision.

If even one method related to an occurring security event cannot be correctly performed, the security module returns the "denied" decision.

If no rule is related to an occurring security event, the security module returns the "denied" decision. In other words, all interactions between solution components and between those components and the KasperskyOS kernel are denied by default (Default Deny principle) unless those interactions are explicitly allowed by the solution security policy.

Security audit

A security audit (hereinafter also referred to as an audit) is the following sequence of actions. The Kaspersky Security Module notifies the KasperskyOS kernel about decisions made by this module. Then the kernel forwards this data to the system program Klog, which decodes this information and forwards it to the system program KlogStorage (data is transmitted via IPC). The latter prints the received data via standard output or saves it to a file.

Security audit data (hereinafter referred to as audit data) refers to information about decisions made by the Kaspersky Security Module, which includes the actual decisions ("granted" or "denied"), descriptions of security events, results from calling methods of security models, and data on incorrect IPC messages.

[Topic ssp_descr_psl_syntax_intro]

PSL language syntax

Basic rules

1. Declarations can be listed in any sequence in a file.
2. One declaration can be written to one or multiple lines. The second and subsequent lines of the declaration must be written with indentations relative to the first line. The closing brace that completes the declaration can be written on the top line.
3. A multi-line declaration utilizes different-sized indentations to reflect the nesting of constructs comprising this declaration. Lines of a multi-line construct enclosed in braces and the opening brace must be written with an indentation relative to the first line of this construct. The closing brace of a multi-line construct can be written with an indentation or on the first line of the construct.
4. Single-line comments and multi-line comments are supported:

   /* This is a comment

   And this, too */

   // Another comment

Types of declarations

The PSL language has the following types of declarations:

• Describing the global parameters of a solution security policy
• Including PSL files
• Including EDL files
• Creating objects of security models
• Binding methods of security models to security events
• Describing security audit profiles

[Topic ssp_descr_psl_syntax_global_params]

Describing the global parameters of a solution security policy

Global parameters include the following parameters of a solution security policy:

• Execute interface used by the KasperskyOS kernel when querying the Kaspersky Security Module to notify it about kernel startup or about initiating the startup of entities by the kernel or other entities. To assign this interface, use the following declaration:

  execute: kl.core.Execute

  KasperskyOS currently supports only one Execute interface defined in the file named kl/core/Execute.idl. (This interface consists of one main method, which has no parameters and does not perform any actions. The main method is reserved for potential future use.)

• [Optional] Global security audit profile and initial security audit level. To define these parameters, use the following declaration:

  audit default = <security audit profile name> <security audit level>

  Example:

  audit default = global 0

  The default global profile is the empty security audit profile described in the file named toolchain/include/nk/base.psl from the KasperskyOS SDK, and the default security audit level is 0.

[Topic ssp_descr_psl_syntax_include_psl]

Including PSL files

To include a PSL file, use the following declaration:

The link to the PSL file is the file path (without the extension and dot before it) relative to the directory that is included in the set of directories where the nk-psl-gen-c compiler searches for PSL-, IDL-, CDL-, and EDL files. (This set of directories is defined by parameters of the makekss script in the format "-I <path to files>".) A dot is used as a separator in a path description. A declaration is ended by the ._ character sequence.

Example:

This declaration includes the flow_part.psl file, which is located in the policy_parts directory. The policy_parts directory must reside in one of the directories where the nk-psl-gen-c compiler searches for PSL-, IDL-, CDL-, and EDL files. For example, the policy_parts directory may reside in the same directory as the PSL file containing this declaration.

Including a PSL file containing a formal representation of a security model

To use the methods of a required security model, include a PSL file containing a formal representation of this model. PSL files containing formal representations of security models are located in the <KOS_KASPERSKY> SDK at the following path:

toolchain/include/nk

Example:

[Topic ssp_descr_psl_syntax_include_edl]

Including EDL files

To include an EDL file for the KasperskyOS kernel, use the following declaration:

To include an EDL file for an application or system program (or for a driver), use the following declaration:

The link to the EDL file is the file path (without the extension and dot before it) relative to the directory that is included in the set of directories where the nk-psl-gen-c compiler searches for PSL-, IDL-, CDL-, and EDL files. (This set of directories is defined by parameters of the makekss script in the format "-I <path to files>".) A dot is used as a separator in a path description.

Example:

The nk-psl-gen-c compiler finds IDL- and CDL files via EDL files because EDL files contain links to the corresponding CDL files, and the CDL files contain links to the corresponding CDL- and IDL files.

[Topic ssp_descr_psl_syntax_create_objects]

Creating objects of security models

To call the methods of a required security model, create an object for this security model.

To create a security model object, use the following declaration:

The parameters of a security model object are specific to the security model. A description of parameters and examples of creating objects of various security models are provided in the "Security models" section.

[Topic ssp_descr_psl_syntax_binding]

Binding methods of security models to security events

To bind methods of security models to a security event, use the following declaration:

Security event type

The following specifiers are used to define the security event type:

• request – sending IPC requests.
• response –sending IPC responses.
• error – sending IPC responses containing information about errors.
• security – entities attempting to query the Kaspersky Security Module via the security interface.
• execute – initializing the startups of entities or the startup of the KasperskyOS kernel.

Security event selectors

Security event selectors let you clarify the description of the defined type of security event. The following selectors are used:

• src=<kernel/entity class name> – entities of the defined class or the KasperskyOS kernel are the sources of IPC messages.
• dst=<kernel/entity class name> – entities of the defined class or the kernel are the recipients of IPC messages.
• interface=<interface name> – describes the following security events:
  • Clients attempt to query servers or the kernel via the interface with the defined name.
  • Entities query the Kaspersky Security Module via the security interface with the defined name.
  • The kernel or servers send clients the results from processing queries via the interface with the defined name.
• endpoint=<qualified service name> – describes the following security events:
  • Clients attempt to use the service of servers or the kernel with the defined name.
  • The kernel or servers send clients the results from using the service with the defined name.
• method=<method name> – describes the following security events:
  • Clients attempt to query servers or the kernel by calling the method of the service with the defined name.
  • Entities query the security module by calling the method of the security interface with the defined name.
  • The kernel or servers send clients the results from calling the method of the service with the defined name.
  • The kernel notifies the security module about its startup by calling the method of the execute interface with the defined name.
  • The kernel initiates the startup of entities by calling the method of the execute interface with the defined name.
  • Entities initiate the startup of other entities, which results in the kernel calling the method of the execute interface with the defined name.

Entity classes, interfaces, services, and methods must be named the same as they are in the IDL, CDL, and EDL descriptions. The kernel must be named kl.core.Core.

If selectors are not specified, the participants of a security event are considered to be all events and the kernel (except security events in which the kernel is not involved).

You can use combinations of selectors. Selectors can be separated by commas.

There are restrictions on the use of selectors. The interface and endpoint selectors cannot be used for security events of the execute type. The dst and endpoint selectors cannot be used for security events of the security type.

There are also restrictions on combinations of selectors. For security events of the request, response and error types, the method selector can only be used together with one or both of the endpoint and interface selectors. (The method, endpoint and interface selectors must be consistent, which means that the method must correspond to the service or interface, and the service must correspond to the interface.) For security events of the request type, the endpoint selector can be used only together with the dst selector. For security events of the response and error types, the endpoint selector can be used only together with the src selector.

Security audit profile

A security audit profile is defined by the construct audit <security audit profile name>. If a security audit profile is not defined, the global security audit profile is used.

Called rules of security models

Called rules of security models are defined by a list from the following type of constructs:

Input data for security model rules may be values returned by expressions of security models. The following construct is used to call a security model expression:

Parameters of interface methods can also be used as input data for methods of security models (rules and expressions). (For details about obtaining access to parameters of interface methods, see "Struct security model"). In addition, input data for methods of security models can also be the SID values of entities and the KasperskyOS kernel that are defined by the src_sid and dst_sid reserved words. The first reserved word refers to the SID of the entity (or kernel) that is the source of the IPC message. The second reserved word refers to the SID of the entity (or kernel) that is the recipient of the IPC message (dst_sid cannot be used for queries to the Kaspersky Security Module).

Embedded constructs for binding methods of security models to security events

In one declaration, you can bind methods of security models to different security events of the same type. To do so, use the match sections that consist of the following types of constructs:

Match sections can be embedded into another match section. A match section simultaneously uses its own security event selectors and the security event selectors at the level of the declaration and all match sections in which this match section is "wrapped". By default, a match section applies the security audit profile of its own container (match section of the preceding level or the declaration level), but you can define a separate security audit profile for the match section.

In one declaration, you can define different variants for processing a security event depending on the conditions in which this event occurred (for example, depending on the state of the finite-state machine associated with the resource). To do so, use the conditional sections that are elements of the following construct:

The choice construct can be used within a match section. A conditional section uses the security event selectors and security audit profile of its own container, but you can define a separate security audit profile for a conditional section.

If multiple conditions described in the choice construct are simultaneously fulfilled when a security event is processed, only the one conditional section corresponding to the first matching condition on the list is triggered.

Page top

[Topic ssp_descr_psl_syntax_audit]

Describing security audit profiles

To perform a security audit, you need to associate objects of security models with a security audit profile(s). A security audit profile (hereinafter also referred to as an audit profile) combines security audit configurations (hereinafter also referred to as audit configurations), each of which defines the objects of security models covered by the audit, and the audit completion conditions. You can define a global audit profile (for more details, see "Describing the global parameters of a solution security policy") and/or assign an audit profile(s) at the level of declarations for binding security model methods to security events, and/or assign an audit profile(s) at the level of match sections or choice sections (for more details, see "Binding methods of security models to security events").

To describe a security audit profile, use the following declaration:

Security audit level

The security audit level (hereinafter referred to as the audit level) is a global parameter of a solution security policy and consists of an unsigned integer that defines the active security audit configuration. (The word "level" here refers to the configuration variant and does not necessarily involve a hierarchy.) The audit level can be changed during operation of the Kaspersky Security Module. This is done by using a specialized method of the Base security model that is called when entities query the security module via the security interface (for more details, see "Base security model"). The initial audit level is assigned together with the global audit profile (for more details, see "Describing the global parameters of a solution security policy"). An empty audit profile can be explicitly assigned as the global audit profile.

You can define multiple audit configurations in an audit profile. In different configurations, different security model objects can be covered by the audit and different audit completion conditions can be applied. Audit configurations in a profile correspond to different audit levels. If a profile does not have an audit configuration corresponding to the current audit level, the security module will activate the configuration that corresponds to the next-lowest audit level. If a profile does not have an audit configuration for an audit level equal to or less than the current level, the security module will not use this profile (in other words, an audit will not be performed for this profile).

Audit levels can be used to regulate the level of detail of an audit, for example. The higher the audit level, the higher the level of detail. The higher the level of detail, the more security model objects are covered by the audit and/or the less restrictions are applied in the audit completion conditions.

Another example of applying audit levels is the capability to shift the audit from one subsystem to another subsystem (for example, shift an audit related to drivers to an audit related to applications, or shift an audit related to the network subsystem to an audit related to the graphic subsystem).

Name of the security model object

The security model object name is indicated so that the methods provided by this object can be covered by the audit. These methods will be covered by the audit whenever they are called, provided that the audit completion conditions are observed.

Security audit completion conditions

Security audit completion conditions are defined separately for each object of a security model.

To define audit completion conditions related to the results from calling rules of security models, use the following constructs:

• ["granted"] – the audit is performed if the called rule returned the "granted" result.
• ["denied"] – the audit is performed if the called rule returned the "denied" result.
• ["granted", "denied"] – the audit is performed if the called rule returned the "granted" or "denied" result.
• [] – the audit is not performed, regardless of the result returned by the called rule.

Audit completion conditions related to results from calling rules are not applied to expressions. These conditions must be defined (with any possible construct) even if the security model contains only expressions because this is required by the PSL language syntax.

Audit completion conditions specific to security models are defined by constructs specific to these models. These conditions are applied to rules and to expressions. For example, one of these conditions can be the state of a finite-state machine.

Security audit profile for a security audit route

A security audit route includes the kernel and the Klog and KlogStorage entities, which are connected by IPC channels based on the "kernel – Klog – KlogStorage" scenario. Security model methods that are associated with transmission of audit data via this route must not be covered by the audit. Otherwise, this will lead to an avalanche of audit data because any data transmission will give rise to new data.

To "suppress" an audit that was defined by a profile with a wider scope (for example, by a global profile or a profile at the level of a declaration for binding security model methods to security events), assign an empty audit profile at the level of the declaration for binding security model methods to security events or at the level of the match section or choice section.

Page top

[Topic ssp_descr_psl_syntax_data_types]

PSL data types

The data types supported in the PSL language are presented in the table below.

PSL data types

Aliases of certain PSL types

The nk/base.psl file from the KasperskyOS SDK defines the data types that are used as the types of parameters (or structural elements of parameters) and returned values for methods of various security models. Aliases and definitions of these types are presented in the table below.

Aliases and definitions of certain data types in PSL

Mapping IDL types to PSL types

Data types of the IDL language are used to describe the parameters of interface methods. The input data for security model methods have types from the PSL language. The set of data types in the IDL language differs from the set of data types in the PSL language. Parameters of interface methods transmitted in IPC messages can be used as input data for methods of security models, so the author of a solution security policy needs to understand which IDL types are mapped to PSL types.

Integer types of IDL are mapped to integer types of PSL and to variant types of PSL that combine these integer types (including with other types). For example, signed integer types of IDL are mapped to the Signed type in PSL, and integer types of IDL are mapped to the ScalarLiteral type in PSL.

The Handle type in IDL is mapped to the HandleDesc type in PSL.

Unions and structures of IDL are mapped to PSL dictionaries.

Arrays and sequences of IDL are mapped to arrays and sequences of PSL, respectively.

String buffers in IDL are mapped to the text type in PSL.

Byte buffers in IDL are not currently mapped to PSL types, so the data contained in byte buffers cannot be used as inputs for security model methods.

[Topic security_configuration_basic_example]

Example of a basic solution security policy

Below is a basic solution security policy in which "everything is allowed" for a solution consisting of Client and Server user entities, an Einit entity, and the KasperskyOS kernel provided by the kl.core.Core entity.

This policy allows the following:

• All interactions between entities (sending any requests and responses)
• Startup of all entities

[Topic ssp_descr_security_models_intro]

Security models

[Topic ssp_descr_security_models_pred]

Pred security model

The Pred security model lets you perform comparison operations.

A PSL file containing a description of the Pred security model is located in the KasperskyOS SDK at the following path:

toolchain/include/nk/basic.psl

Pred security model object

The basic.psl file contains a declaration that creates a Pred security model object named pred. Consequently, inclusion of the basic.psl file into the solution security policy description will create a Pred security model object by default.

A Pred security model object does not have any parameters and cannot be covered by a security audit.

It is not necessary to create additional Pred security model objects.

Pred security model methods

A Pred security model contains expressions that perform comparison operations and return values of the Boolean type. To call these expressions, use the following comparison operators:

• <ScalarLiteral> == <ScalarLiteral> – "equals".
• <ScalarLiteral> != <ScalarLiteral> – "does not equal".
• <Number> < <Number> – "is less than".
• <Number> <= <Number> – "is less than or equal to".
• <Number> > <Number> – "is greater than".
• <Number> >= <Number> – "is greater than or equal to".

The Pred security model also contains the empty expression that lets you determine whether data contains its own structural elements. This expression returns values of the Boolean type. If data does not contain its own structural elements (for example, a set is empty), the expression returns true, otherwise it returns false. To call the expression, use the following construct:

[Topic ssp_descr_security_models_bool]

Bool security model

The Bool security model lets you perform logical operations.

A PSL file containing a description of the Bool security model is located in the KasperskyOS SDK at the following path:

toolchain/include/nk/basic.psl

Bool security model object

The basic.psl file contains a declaration that creates a Bool security model object named bool. Consequently, inclusion of the basic.psl file into the solution security policy description will create a Bool security model object by default.

A Bool security model object does not have any parameters and cannot be covered by a security audit.

It is not necessary to create additional Bool security model objects.

Bool security model methods

The Bool security model contains expressions that perform logical operations and return values of the Boolean type. To call these expressions, use the following logical operators:

• ! <Boolean> – "logical NOT".
• <Boolean> && <Boolean> – "logical AND".
• <Boolean> || <Boolean> – "logical OR".
• <Boolean> ==> <Boolean> – "implication" (! <Boolean> || <Boolean>).

The Bool security model also contains the all, any and cond expressions.

The expression all performs a "logical AND" for an arbitrary number of values of Boolean type. It returns values of the Boolean type. It returns true if an empty list of values ([]) is passed via the parameter. To call the expression, use the following construct:

The expression any performs a "logical OR" for an arbitrary number of values of Boolean type. It returns values of the Boolean type. It returns false if an empty list of values ([]) is passed via the parameter. To call the expression, use the following construct:

cond expression performs a ternary conditional operation. Returns values of the ScalarLiteral type. To call the expression, use the following construct:

In addition to expressions, the Bool security model includes the assert rule that works the same as the rule of the same name included in the Base security model.

[Topic ssp_descr_security_models_math]

Math security model

The Math security model lets you perform integer arithmetic operations.

A PSL file containing a description of the Math security model is located in the KasperskyOS SDK at the following path:

toolchain/include/nk/basic.psl

Math security model object

The basic.psl file contains a declaration that creates a Math security model object named math. Consequently, inclusion of the basic.psl file into the solution security policy description will create a Math security model object by default.

A Math security model object does not have any parameters and cannot be covered by a security audit.

It is not necessary to create additional Math security model objects.

Math security model methods

The Math security model contains expressions that perform integer arithmetic operations. To call a part of these expressions, use the following arithmetic operators:

• <Number> + <Number> – "addition". Returns values of the Number type.
• <Number> - <Number> – "subtraction". Returns values of the Number type.
• <Number> * <Number> – "multiplication". Returns values of the Number type.

The other expressions are as follows:

• neg <Signed> – "change number sign". Returns values of the Singed type.
• abs <Singed> – "get module of number". Returns values of the Singed type.
• sum <List<Number>> – "add numbers from list". Returns values of the Number type. It returns 0 if an empty list of values ([]) is passed via the parameter.
• product <List<Number>> – "multiply numbers from list". Returns values of the Number type. It returns 1 if an empty list of values ([]) is passed via the parameter.

To call these expressions, use the following construct:

[Topic ssp_descr_security_models_struct]

Struct security model

The Struct security model lets you obtain access to structural data elements.

A PSL file containing a description of the Struct security model is located in the KasperskyOS SDK at the following path:

toolchain/include/nk/basic.psl

Struct security model object

The basic.psl file contains a declaration that creates a Struct security model object named struct. Consequently, inclusion of the basic.psl file into the solution security policy description will create a Struct security model object by default.

A Struct security model object does not have any parameters and cannot be covered by a security audit.

It is not necessary to create additional Struct security model objects.

Struct security model methods

The Struct security model contains expressions that provide access to structural data elements. To call these expressions, use the following constructs:

• <{...}>.<field name> – "get access to dictionary field". the type of returned data corresponds to the type of dictionary field.
• <List | Set | Sequence | Array>.[<element number>] – "get access to data element". The type of returned data corresponds to the type of elements. The numbering of elements starts with zero. When out of bounds of dataset, the expression terminates with an error and the Kaspersky Security Module returns the "denied" decision.
• <HandleDesc>.handle – "get SID". Returns values of the Handle type. (For details on the correlation between handles and SID values, see "Managing access to resources").
• <HandleDesc>.rights – "get handle permissions mask". Returns values of the UInt32 type.

Parameters of interface methods are saved in a special dictionary named message. To obtain access to an interface method parameter, use the following construct:

The parameter name is specified in accordance with the IDL description.

To obtain access to structural elements of parameters, use the constructs corresponding to expressions of the Struct security model.

[Topic ssp_descr_security_models_base]

Base security model

The Base security model lets you implement basic logic.

A PSL file containing a description of the Base security model is located in the KasperskyOS SDK at the following path:

toolchain/include/nk/base.psl

Base security model object

The base.psl file contains a declaration that creates a Base security model object named base. Consequently, inclusion of the base.psl file into the solution security policy description will create a Base security model object by default. Methods of this object can be called without indicating the object name.

A Base security model object does not have any parameters.

A Base security model object can be covered by a security audit. There are no audit completion conditions specific to the Base security model.

It is necessary to create additional objects of the Base security model in the following cases:

• You need to configure a security audit differently for different objects of the Base security model (for example, you can apply different audit profiles or different audit configurations of the same profile for different objects).
• You need to distinguish between calls of methods provided by different objects of the Base security model (audit data includes the name of the security model method and the name of the object that provides this method, so you can verify that the method of a specific object was called).

Base security model methods

The Base security model contains the following rules:

• grant ()

  It has a parameter of the () type. It returns the "granted" result.

  Example:

  /* A client of the foo class is allowed to query

  * a server of the bar class. */

  request src=foo dst=bar { grant () }

• assert <Boolean>

  It returns the "granted" result if the true value is passed via the parameter. Otherwise it returns the "denied" result.

  Example:

  /* Any client in the solution will be allowed to query a server of the foo class

  * by calling the Send method of the net.Net service if the port parameter of the Send method

  * will be used to pass a value greater than 80. Otherwise any client in the solution

  * will be prohibited from querying a server of the foo class by calling the Send method

  * of the net.Net service. */

  request dst=foo endpoint=net.Net method=Send { assert (message.port > 80) }

• deny <Boolean | ()>

  It returns the "denied" result if the true or () value is passed via the parameter. Otherwise it returns the "granted" result.

  Example:

  /* A server of the foo class is not allowed to respond

  * to a client of the bar class. */

  response src=foo dst=bar { deny () }

• set_level <UInt8>

  It sets the security audit level equal to the value passed via this parameter. It returns the "granted" result. (For more details about the security audit level, see "Describing security audit profiles".)

  Example:

  /* An entity of the foo class will receive the "allowed" decision from the

  * Kaspersky Security Module if it calls the SetAuditLevel security interface method

  * to change the security audit level. */

  security src=foo method=SetAuditLevel { set_level (message.audit_level) }

[Topic ssp_descr_security_models_regex]

Regex security model

The Regex security model lets you implement text data validation based on statically defined regular expressions.

A PSL file containing a description of the Regex security model is located in the KasperskyOS SDK at the following path:

toolchain/include/nk/regex.psl

Regex security model object

The regex.psl file contains a declaration that creates a Regex security model object named re. Consequently, inclusion of the regex.psl file into the solution security policy description will create a Regex security model object by default.

A Regex security model object does not have any parameters.

A Regex security model object can be covered by a security audit. You can also define the audit completion conditions specific to the Regex security model. To do so, use the following constructs in the audit configuration description:

• emit : ["match"] – the audit is performed if the match method is called.
• emit : ["select"] – the audit is performed if the select method is called.
• emit : ["match", "select"] – the audit is performed if the match or select method is called.
• emit : [] – the audit is not performed.

It is necessary to create additional objects of the Regex security model in the following cases:

• You need to configure a security audit differently for different objects of the Regex security model (for example, you can apply different audit profiles or different audit configurations of the same profile for different objects).
• You need to distinguish between calls of methods provided by different objects of the Regex security model (audit data includes the name of the security model method and the name of the object that provides this method, so you can verify that the method of a specific object was called).

Regex security model methods

The Regex security model contains the following expressions:

• match {text : <Text>, pattern : <Text>}

  Returns a value of the Boolean type. If the specified text matches the pattern regular expression, it returns true. Otherwise it returns false.

  Example:

  assert (re.match {text : message.text, pattern : "^[0-9]*$"})

• select {text : <Text>}

  It is intended to be used as an expression that verifies fulfillment of the conditions in the choice construct (for details on the choice construct, see "Binding methods of security models to security events"). It checks whether the specified text matches regular expressions. Depending on the results of this check, various options for security event processing can be performed.

  Example:

  choice (re.select {text : "hello world"}) {

  "^hello .*": grant ()

  ".*world$" : grant ()

  _ : deny ()

  }

[Topic ssp_descr_security_models_hashset]

HashSet security model

The HashSet security model lets you associate resources with one-dimensional tables of unique values of the same type, add or delete these values, and check whether a defined value is in the table. For example, an entity whose context includes a running network server can be associated with the set of ports that this server is allowed to open. This association can be used to check whether the server is allowed to initiate the opening of a port.

A PSL file containing a description of the HashSet security model is located in the KasperskyOS SDK at the following path:

toolchain/include/nk/hashmap.psl

[Topic ssp_descr_security_models_hashset_object]

HashSet security model object

To use the HashSet security model, you need to create an object or objects of this model.

A HashSet security model object contains a pool of one-dimensional tables of the same size intended for storing the values of one type. A resource can be associated with only one table from the tables pool of each HashSet security model object.

A HashSet security model object has the following parameters:

• type Entry – type of values in tables (these can be integer types, Boolean type, and dictionaries and tuples based on integer types and the Boolean type).
• config – configuration of the pool of tables:
  • set_size – size of the table.
  • pool_size – number of tables in the pool.

All parameters of a HashSet security model object are required.

Example:

A HashSet security model object can be covered by a security audit. There are no audit completion conditions specific to the HashSet security model.

It is necessary to create multiple objects of the HashSet security model in the following cases:

• You need to configure a security audit differently for different objects of the HashSet security model (for example, you can apply different audit profiles or different audit configurations of the same profile for different objects).
• You need to distinguish between calls of methods provided by different objects of the HashSet security model (audit data includes the name of the security model method and the name of the object that provides this method, so you can verify that the method of a specific object was called).
• You need to use tables of different sizes and/or with different types of values.

[Topic ssp_descr_security_models_hashset_init]

HashSet security model init rule

It associates a free table from the tables pool with the resource that has the security ID sid. If the free table contains values after its previous use, these values are deleted.

It returns the "allowed" result if an association was created between the table and the resource.

It returns the "denied" result in the following cases:

• There are no free tables in the pool.
• The resource with the security ID sid is already associated with a table from the tables pool of the HashSet security model object being used.
• Security ID sid is out of the permissible range.

Example:

[Topic ssp_descr_security_models_hashset_fini]

HashSet security model fini rule

It deletes the association between the table and the resource that has the security ID sid (the table becomes free).

It returns the "allowed" result if the association between the table and the resource was deleted.

It returns the "denied" result in the following cases:

• The resource with the security ID sid is not associated with a table from the tables pool of the HashSet security model object being used.
• Security ID sid is out of the permissible range.

[Topic ssp_descr_security_models_hashset_add]

HashSet security model add rule

It adds the entry value to the table associated with the resource that has the security ID sid.

It returns the "allowed" result in the following cases:

• The rule added the entry value to the table.
• The table already contains the entry value.

It returns the "denied" result in the following cases:

• The table is completely filled.
• The resource with the security ID sid is not associated with a table from the tables pool of the HashSet security model object being used.
• Security ID sid is out of the permissible range.

Example:

[Topic ssp_descr_security_models_hashset_remove]

HashSet security model remove rule

It deletes the entry value from the table associated with the resource that has the security ID sid.

It returns the "allowed" result in the following cases:

• The rule deleted the entry value from the table.
• The table does not have the entry value.

It returns the "denied" result in the following cases:

• The resource with the security ID sid is not associated with a table from the tables pool of the HashSet security model object being used.
• Security ID sid is out of the permissible range.

[Topic ssp_descr_security_models_hashset_contains]

HashSet security model contains expression

It checks whether the entry value is in the table associated with the resource that has the security ID sid.

It returns a value of the Boolean type. If the entry value is in the table, it returns true. Otherwise it returns false.

It runs incorrectly in the following cases:

• The resource with the security ID sid is not associated with a table from the tables pool of the HashSet security model object being used.
• Security ID sid is out of the permissible range.

If the expression runs incorrectly, the Kaspersky Security Module returns the "denied" decision.

Example:

[Topic ssp_descr_security_models_staticmap]

StaticMap security model

The StaticMap security model lets you associate resources with two-dimensional "key–value" tables, read and modify the values of keys. For example, an entity whose context includes a running driver can be associated with the MMIO memory region that this driver is allowed to use. This will require two keys whose values define the starting address and the size of the MMIO memory region. This association can be used to check whether the driver can call the MMIO memory region that it is attempting to access.

Keys in the table have the same type but are unique and immutable. The values of keys in the table have the same type.

There are two simultaneous instances of the table: base table and working table. Both instances are initialized by the same data. Changes are made first to the working instance and then can be added to the base instance, or vice versa: the working instance can be changed by using previous values from the base instance. The values of keys can be read from the base instance or working instance of the table.

A PSL file containing a description of the StaticMap security model is located in the KasperskyOS SDK at the following path:

toolchain/include/nk/staticmap.psl

[Topic ssp_descr_security_models_staticmap_object]

StaticMap security model object

To use the StaticMap security model, you need to create an object or objects of this model.

A StaticMap security model object contains a pool of two-dimensional "key–value" tables that have the same size. A resource can be associated with only one table from the tables pool of each StaticMap security model object.

A StaticMap security model object has the following parameters:

• type Value – type of values of keys in tables (integer types are supported).
• config – configuration of the pool of tables:
  • keys – table containing keys and their default values (keys have the Key = Text | List<UInt8> type).
  • pool_size – number of tables in the pool.

All parameters of a StaticMap security model object are required.

Example:

A StaticMap security model object can be covered by a security audit. There are no audit completion conditions specific to the StaticMap security model.

It is necessary to create multiple objects of the StaticMap security model in the following cases:

• You need to configure a security audit differently for different objects of the StaticMap security model (for example, you can apply different audit profiles or different audit configurations of the same profile for different objects).
• You need to distinguish between calls of methods provided by different objects of the StaticMap security model (audit data includes the name of the security model method and the name of the object that provides this method, so you can verify that the method of a specific object was called).
• You need to use tables with different sets of keys and/or different types of key values.

[Topic ssp_descr_security_models_staticmap_init]

StaticMap security model init rule

It associates a free table from the tables pool with the resource that has the security ID sid. Keys are initialized by the default values.

It returns the "allowed" result if an association was created between the table and the resource.

It returns the "denied" result in the following cases:

• There are no free tables in the pool.
• The resource with the security ID sid is already associated with a table from the tables pool of the StaticMap security model object being used.
• Security ID sid is out of the permissible range.

Example:

[Topic ssp_descr_security_models_staticmap_fini]

StaticMap security model fini rule

It deletes the association between the table and the resource that has the security ID sid (the table becomes free).

It returns the "allowed" result if the association between the table and the resource was deleted.

It returns the "denied" result in the following cases:

• The resource with the security ID sid is not associated with a table from the tables pool of the StaticMap security model object being used.
• Security ID sid is out of the permissible range.

[Topic ssp_descr_security_models_staticmap_set]

StaticMap security model set rule

It assigns the specified value to the specified key in the working instance of the table associated with the resource that has the security ID sid.

It returns the "allowed" result if the specified value was assigned to the specified key. (The current value of the key will be overwritten even if it is equal to the new value.)

It returns the "denied" result in the following cases:

• The specified key is not in the table.
• The resource with the security ID sid is not associated with a table from the tables pool of the StaticMap security model object being used.
• Security ID sid is out of the permissible range.

Example:

[Topic ssp_descr_security_models_staticmap_commit]

StaticMap security model commit rule

It copies the values of keys from the working instance to the base instance of the table associated with the resource that has the security ID sid.

It returns the "allowed" result if the values of keys were copied from the working instance to the base instance of the table.

It returns the "denied" result in the following cases:

• The resource with the security ID sid is not associated with a table from the tables pool of the StaticMap security model object being used.
• Security ID sid is out of the permissible range.

[Topic ssp_descr_security_models_staticmap_rollback]

StaticMap security model rollback rule

It copies the values of keys from the base instance to the working instance of the table associated with the resource that has the security ID sid.

It returns the "allowed" result if the values of keys were copied from the base instance to the working instance of the table.

It returns the "denied" result in the following cases:

• The resource with the security ID sid is not associated with a table from the tables pool of the StaticMap security model object being used.
• Security ID sid is out of the permissible range.

[Topic ssp_descr_security_models_staticmap_get]

StaticMap security model get expression

It returns the value of the specified key from the base instance of the table associated with the resource that has the security ID sid.

It returns a value of the Value type.

It runs incorrectly in the following cases:

• The specified key is not in the table.
• The resource with the security ID sid is not associated with a table from the tables pool of the StaticMap security model object being used.
• Security ID sid is out of the permissible range.

If the expression runs incorrectly, the Kaspersky Security Module returns the "denied" decision.

Example:

[Topic ssp_descr_security_models_staticmap_get_u]

StaticMap security model get_uncommited expression

It returns the value of the specified key from the working instance of the table associated with the resource that has the security ID sid.

It returns a value of the Value type.

It runs incorrectly in the following cases:

• The specified key is not in the table.
• The resource with the security ID sid is not associated with a table from the tables pool of the StaticMap security model object being used.
• Security ID sid is out of the permissible range.

If the expression runs incorrectly, the Kaspersky Security Module returns the "denied" decision.

[Topic ssp_descr_security_models_flow]

Flow security model

The Flow security model lets you associate resources with finite-state machines, receive and modify the states of finite-state machines, and check whether the state of the finite-state machine is within the defined set of states. For example, an entity can be associated with a finite-state machine to allow or prohibit this entity from using storage and/or the network depending on the state of the finite-state machine.

A PSL file containing a description of the Flow security model is located in the KasperskyOS SDK at the following path:

toolchain/include/nk/flow.psl

[Topic ssp_descr_security_models_flow_object]

Flow security model object

To use the Flow security model, you need to create an object or objects of this model.

One Flow security model object lets you associate a set of resources with a set of finite-state machines that have the same configuration. A resource can be associated with only one finite-state machine of each Flow security model object.

A Flow security model object has the following parameters:

• type State – type that determines the set of states of the finite-state machine (variant type that combines text literals).
• config – configuration of the finite-state machine:
  • states – set of states of the finite-state machine (must match the set of states defined by the State type).
  • initial – initial state of the finite-state machine.
  • transitions – description of the permissible transitions between states of the finite-state machine.

All parameters of a Flow security model object are required.

Example:

Diagram of finite-state machine states in the example

A Flow security model object can be covered by a security audit. You can also define the audit completion conditions specific to the Flow security model. To do so, use the following construct in the audit configuration description:

omit : [<"state 1">[,] ...] – the audit is not performed if the finite-state machine is in one of the listed states.

It is necessary to create multiple objects of the Flow security model in the following cases:

• You need to configure a security audit differently for different objects of the Flow security model (for example, you can apply different audit profiles or different audit configurations of the same profile for different objects).
• You need to distinguish between calls of methods provided by different objects of the Flow security model (audit data includes the name of the security model method and the name of the object that provides this method, so you can verify that the method of a specific object was called).
• You need to use finite-state machines with different configurations.

[Topic ssp_descr_security_models_flow_init]

Flow security model init rule

It creates a finite-state machine and associates it with the resource that has the security ID sid. The created finite-state machine has the configuration defined in the settings of the Flow security model object being used.

It returns the "allowed" result if an association was created between the finite-state machine and the resource.

It returns the "denied" result in the following cases:

• The resource with the security ID sid is already associated with a finite-state machine of the Flow security model object being used.
• Security ID sid is out of the permissible range.

Example:

[Topic ssp_descr_security_models_flow_fini]

Flow security model fini rule

It deletes the association between the finite-state machine and the resource that has the security ID sid. The finite-state machine that is no longer associated with the resource is destroyed.

It returns the "allowed" result if the association between the finite-state machine and the resource was deleted.

It returns the "denied" result in the following cases:

• The resource with the security ID sid is not associated with a finite-state machine of the Flow security model object being used.
• Security ID sid is out of the permissible range.

[Topic ssp_descr_security_models_flow_enter]

Flow security model enter rule

It switches the finite-state machine associated with the resource that has the security ID sid to the specified state.

It returns the "allowed" result if the finite-state machine was switched to the specified state.

It returns the "denied" result in the following cases:

• The transition to the specified state from the current state is not permitted by the configuration of the finite-state machine.
• The resource with the security ID sid is not associated with a finite-state machine of the Flow security model object being used.
• Security ID sid is out of the permissible range.

Example:

[Topic ssp_descr_security_models_flow_allow]

Flow security model allow rule

It verifies that the state of the finite-state machine associated with the resource that has the security ID sid is in the set of defined states.

It returns the "allowed" result if the state of the finite-state machine is in the set of defined states.

It returns the "denied" result in the following cases:

• The state of the finite-state machine is not in the set of defined states.
• The resource with the security ID sid is not associated with a finite-state machine of the Flow security model object being used.
• Security ID sid is out of the permissible range.

Example:

[Topic ssp_descr_security_models_flow_query]

Flow security model query expression

It is intended to be used as an expression that verifies fulfillment of the conditions in the choice construct (for details on the choice construct, see "Binding methods of security models to security events"). It checks the state of the finite-state machine associated with the resource that has the security ID sid. Depending on the results of this check, various options for security event processing can be performed.

It runs incorrectly in the following cases:

• The resource with the security ID sid is not associated with a finite-state machine of the Flow security model object being used.
• Security ID sid is out of the permissible range.

If the expression runs incorrectly, the Kaspersky Security Module returns the "denied" decision.

Example:

[Topic ping_example]

ping example

The ping example demonstrates the use of a solution security policy to control interactions between entities.

[Topic about_ping_example]

About the ping example

The ping example includes two entities: Client and Server.

The Server entity provides two identical Ping and Pong methods that receive a number and return a modified number:

The Client entity calls both of these methods in a different sequence. If the method call is denied by the solution security policy, the Failed to call... message is displayed.

The ping example implements a solution security policy (security.psl) based on the Flow security model.

Components of the ping example

The ping example consists of the following files:

• client/src/client.c
• resources/edl/Client.edl
• server/src/server.c
• resources/edl/Server.edl, resources/cdl/Control.cdl, resources/idl/Connection.idl
• init.yaml
• security.psl

[Topic ping_client_implementation]

Implementation of the Client entity in the ping example

The Client entity calls the Ping and Pong methods in a varying sequence.

[Topic ping_server_implementation]

Implementation of the Server entity in the ping example

[Topic ping_description_files]

Description files in the ping example

Description of the Client entity

The Client entity does not implement an interface, so all you need to do is declare the entity name in the EDL description.

Server entity description

The Server entity implements a Connection interface, which contains two methods: Ping and Pong. As in the echo example, you must declare a separate component, such as Control, which contains a Connection interface implementation.

In the EDL description of the Server entity, you must indicate that it contains an instance of the Control component:

In the CDL description of the Control component, you must indicate that it contains a Connection interface implementation:

In the Connection package, you must declare the Connection interface, which contains two methods: Ping and Pong:

Init description

To enable the Client entity to call a Server entity method, an IPC channel must be created between them.

[Topic ping_flow]

Solution security policy in the ping example

The solution security policy in this example allows you to start all entities, and allows any entity to query the Core and Server entities. Calls to the Server entity are managed by methods of the Flow security model.

The finite-state machine described in the configuration of the request_state Flow security model object has two states: ping_next and pong_next. The initial state is ping_next. Only transitions from ping_next to pong_next and the reverse are allowed.

When the Ping and Pong methods are called, the current state of the request_state object is checked. In the ping_next state, only a Ping call is allowed, in which case the state changes to pong_next. Likewise, in the pong_next state, only a Pong call is allowed, in which case the state changes to ping_next.

Therefore, the Ping and Pong methods can be called only in succession.

[Topic ping_example_build]

Building and running the ping example

See the Building and running examples section.

[Topic pal_tests]

Testing a solution security policy based on the Policy Assertion Language (PAL)

The basic scenario for using the Policy Assertion Language (PAL) is to create test scenarios for checking solution security policies written in PSL.

The PAL language lets you generate and send requests to the security module and verify that the received decisions comply with the expected decisions. To run test scenarios written in PAL, you do not need to generate code of client-server interactions because PAL operates at the level of abstraction of the security module.

General syntax

A test scenario is a sequence of requests to the security module, with an expected decision indicated for each of these requests.

Test scenarios can be combined into groups. A group of scenarios may also contain the setup and finally sections, which will be executed before and after the execution of each scenario in this group, respectively. This can be used to define common start conditions or to check common invariants.

The modular assert declaration is used to declare a group of test scenarios:

Syntax of requests

To configure requests within test scenarios, the following types of declarations are used:

In this case:

• <expectation> – expected decision: grant, deny or any.

  When expecting the any decision, the decision of the security module is ignored, but an error when completing the request will mark the test scenario as unsuccessful.

  When the expected decision is not explicitly indicated, the grant decision is expected.

• <title> – optional parameter containing a text header of the described request.
• <operation> – one of the types of queries to the security module: execute, security, request or response.
• <event selectors> – the permissible selectors of an event coincide with the selectors used when binding methods of security models to security events. For example, you can indicate the message recipient entity or the called method.
• {message} – optional parameter containing the value for arguments of the called method. The value of this parameter must match the operation and selectors of the request. An empty number of arguments {} is used by default.

Example:

Abbreviated format of requests

For convenience, you can also use the following abbreviated formats of requests:

• When performing the execute operation, you can save the handle of the started entity to a variable by using the <- operator.
• Abbreviated format for the security operation: <entity> ! <path.to.method> {message}

  When executed, it is expanded to the full format: security src=<entity> method=<path.to.method> {message}

• Abbreviated format for the request operation: <client> ~> <server> : <path.to.method.implementation> {message}

  When executed, it is expanded to the full format: request src=<client> dst=<server> endpoint=<path.to.implementation> method=<method> {message}

• Abbreviated format for the response operation: <client> <~ <server> : <path.to.method.implementation> {message}

  When executed, it is expanded to the full format: response src=<server> dst=<client> endpoint=<path.to.implementation> method=<method> {message}

Example:

Running tests

To run test scenarios written in PAL, use the --tests run flag when starting the nk-psl-gen-c compiler:

The nk-psl-gen-c compiler generates code of the security module and code of test scenarios, uses gcc to compile them, and then runs them.

To generate code of test scenarios without compiling and running them, use the --tests generate flag.

[Topic kos_api_reference]

KasperskyOS API

[Topic static_definitions]

Description of entities, components, and interfaces (EDL, CDL, IDL)

All entities, components and interfaces used in the solution must be statically described using the EDL, CDL and IDL languages. The corresponding descriptions are saved in the *.edl, *.cdl and *.idl files, respectively.

Description files are used when building a solution for the following purposes:

• Generating header files containing transport methods and types
• Building a security module

[Topic entity_component_interface_model]

Entity-Component-Interface model

Each entity can provide one or more interaction interfaces. Multiple interfaces can be combined into a component. Components can be embedded into other components. All entities, components and interfaces used in the solution must be statically described.

In KasperskyOS, there are three types of static description files:

• An EDL file contains a description of the entity in the Entity Definition Language (EDL): its name, components and interfaces, and other information.
• A CDL file contains a description of the component in the Component Definition Language,hereinafter referred to as CDL. The component description includes its name, set of included components and implemented interfaces.
• An IDL file contains a description of the package containing one interface in the Interface Definition Language (IDL). The description includes the package name, a declaration of the interface included in it, and a declaration of the types and named constants.

The Server entity includes instances of the Terminal and Serial components containing various implementations of the Console interface.

[Topic edl]

EDL

Each entity in KasperskyOS must be described in the Entity Definition Language (EDL), in a separate file named <entity name>.edl.

An EDL file contains the following sections – the order is important:

1. Name of the entity. Required section beginning with the reserved word entity, which is followed by the entity name.

   The entity name must begin with an uppercase letter and must not contain an underscore (_).

2. Security interface used by the entity. This section is optional. It must be added only if the entity uses a security interface. It is declared with the reserved word security, which should be followed by the full name of the interface.
3. List of implementations of interfaces that are provided by the entity. This is optional, and is described in the interfaces section. Each interface implementation is specified with a separate string in the following format:

   interfaces {

   <interface implementation name>:<interface name>

   }

   An entity can contain several implementations of one interface. All implemented interfaces must be described in the IDL language in IDL files.

   The interface implementation name must not contain an underscore (_).

4. List of instances of components included in the entity. This is optional, and is described in the components section. Each component instance is specified with a separate string in the following format:

   components {

   <component instance name>:<component name>

   }

   For each specified component, a separate file named <component name>.cdl needs to be created, containing a description of the component in the CDL language. Multiple instances of the same component can be added to an entity, and each instance can have a separate state (see the example of UartDriver entity below).

   The component instance name must not contain an underscore (_).

The interfaces and components sections are optional and are added only for server entities. Implementations of interfaces declared in the interfaces section and implementations that are included in components from the components section can be used by client entities.

EDL supports single-line comments and multi-line C++-style comments:

Examples of EDL files

At its simplest, the entity does not use a security interface and does not provide functionality to other entities, like the hello entity from the hello example. An EDL description for such an entity contains only the reserved word entity and the entity name.

In the following example, the EFoo entity contains a single interface implementation and does not use a security interface.

In the following example, the UartDriver entity contains two instances of the UartComp component: one for each UART device.

The UartDriver entity does not use a security interface.

[Topic cdl]

CDL

Each component used in the solution must be described in the CDL language, in a separate <component name>.cdl file.

A CDL file includes the following sections:

1. The name of the component. The reserved word component is placed before the component name.

   The component name must begin with an uppercase letter and must not contain an underscore (_).

2. Security interface within this component. This section is optional. It must be added only if the component contains a security interface. It is declared with the reserved word security, which should be followed by the full name of the interface.
3. A list of interface implementations included in this component. Interfaces are declared in the interfaces section in which each interface implementation is specified with a separate string in the following format:

   interfaces {

   <interface implementation name>:<interface name>

   }

   A component can contain several implementations of one interface. All implemented interfaces must be described in the IDL language in IDL files.

   The interface implementation name must not contain an underscore (_).

4. The list of instances of components embedded in this component. This section is optional. It should be added if the component contains embedded components. Components are declared in the components section in which each component instance is specified with a separate string in the following format:

   components {

   <component instance name>:<component name>

   }

   For each specified component, a separate file named <component name>.cdl needs to be created, containing a description of the component in the CDL language. Multiple instances of the same component can be added to a component, and each instance can have a separate state.

   The component instance name must not contain an underscore (_).

CDL supports single-line comments and multi-line C++-style comments.

Examples of CDL files

At its simplest, the component contains a single interface implementation similar to the ping component from the echo example.

In the following example, the CoFoo component contains implementations of two interfaces declared in two different packages named Foo and Baz (i.e. in the Foo.idl and Bar.idl files):

In the following example, the CoFoo component contains a single interface implementation and an embedded component.