Building a KasperskyOS-based solution

This section contains the following information:

• Description of the KasperskyOS-based solution build process.
• Descriptions of the scripts, libraries and build templates provided in KasperskyOS Community Edition.

Building a solution image

A KasperskyOS-based solution consists of system software (including the KasperskyOS kernel and Kaspersky Security Module) and application software integrated for operation within a software/hardware system.

For more details, refer to Structure and startup of the solution image.

System programs and application software

Programs are divided into two types according to their purpose:

• System programs create the infrastructure for application software. For example, they facilitate hardware operations, support the IPC mechanism, and implement file systems and network protocols. System programs are included in KasperskyOS Community Edition. If necessary, you can develop your own system programs.
• Application software is designed for interaction with a solution user and for performing user tasks. Application software is not included in KasperskyOS Community Edition.

Building programs during the solution build process

During a solution build, programs are divided into the following two types:

• System programs provided as executable files in KasperskyOS Community Edition.
• System programs or application software that requires linking to an executable file.

Programs that require linking are divided into the following types:

• System programs that implement an IPC interface whose ready-to-use transport libraries are provided in KasperskyOS Community Edition.
• Application software that implements its own IPC interface. To build this software, transport methods and types need to be generated by using the NK compiler.
• Client programs that do not provide endpoints.

Building a solution image

KasperskyOS Community Edition provides an image of the KasperskyOS kernel and the executable files of some system programs and driver applications that are ready to use in a solution.

A specialized Einit program intended for starting all other programs, and a Kaspersky Security Module are built for each specific solution and are therefore not already provided in KasperskyOS Community Edition. Instead, the toolchain provided in KasperskyOS Community Edition includes the tools for building these resources.

The general step-by-step build scenario is described in the article titled Build process overview. A solution image can be built as follows:

• [Recommended] Using scripts of the CMake build system, which is provided in KasperskyOS Community Edition.
• Without CMake: using other automated build systems or manually with scripts and compilers provided in KasperskyOS Community Edition.

Build process overview

To build a solution image, the following is required:

1. Prepare EDL, CDL and IDL descriptions of applications, an init description file (init.yaml by default), and files containing a description of the solution security policy (security.psl by default).

   When building with CMake, an EDL description can be generated by using the generate_edl_file() command.

2. Generate *.edl.h files for all programs except the system programs provided in KasperskyOS Community Edition.
   • When building with CMake, the nk_build_edl_files() command is used for this purpose.
   • When building without CMake, the NK compiler must be used for this.
3. For programs that implement their own IPC interface, generate code of the transport methods and types that are used for generating, sending, receiving and processing IPC messages.
   • When building with CMake, the nk_build_idl_files() and nk_build_cdl_files() commands are used for these purposes.
   • When building without CMake, the NK compiler must be used for this.
4. Build all programs that are part of the solution, and link them to the transport libraries of system programs or applications if necessary. To build applications that implement their own IPC interface, you will need the code containing transport methods and types that was generated at step 3.
   • When building with CMake, standard build commands are used for this purpose. The necessary cross-compilation configuration is done automatically.
   • When building without CMake, the cross compilers included in KasperskyOS Community Edition must be manually used for this purpose.
5. Build the Einit initializing program.
   • When building with CMake, the Einit program is built during the solution image build process using the build_kos_qemu_image() and build_kos_hw_image() commands.
   • When building without CMake, the einit tool must be used to generate the code of the Einit program. Then the Einit application must be built using the cross compiler that is provided in KasperskyOS Community Edition.
6. Build the Kaspersky Security Module.
   • When building with CMake, the security module is built during the solution image build process using the build_kos_qemu_image() and build_kos_hw_image() commands.
   • When building without CMake, the makekss script must be used for this purpose.
7. Create the solution image.
   • When building with CMake, the build_kos_qemu_image() and build_kos_hw_image() commands are used for this purpose.
   • When building without CMake, the makeimg script must be used for this.

Example 1

For the basic hello example included in KasperskyOS Community Edition that contains one application that does not provide any services, the build scenario looks as follows:

Example 2

The echo example included in KasperskyOS Community Edition describes a basic case of interaction between two programs via an IPC mechanism. To set up this interaction, you will need to implement an interface with the Ping method on a server and put the Ping service into a new component (for example, Ping), and an instance of this component needs to be put into the EDL description of the Server program.

If a solution contains programs that utilize an IPC mechanism, the build scenario looks as follows:

Using CMake from the contents of KasperskyOS Community Edition

To automate the process of preparing the solution image, you need to configure the CMake build system. You can base this system on the build system parameters used in the examples from KasperskyOS Community Edition.

CMakeLists.txt files use the standard CMake syntax, and commands and macros from libraries provided in KasperskyOS Community Edition.

Recommended structure of project directories

When creating a KasperskyOS-based solution, it is recommended to use the following directory structure in a project to simplify the use of CMake scripts:

• In the project root, create a CMakeLists.txt boot file containing the general build instructions for the entire solution.
• The source code of each program being developed should be placed into a separate directory within the src subdirectory.
• Create CMakeLists.txt files for building each application in the corresponding directories.
• To generate the source code of the Einit program, you should create a separate einit directory containing the src subdirectory in which you should put the init.yaml.in and security.psl.in templates.

  Any other files that need to be included in the solution image can also be put into this directory.

• Create a CMakeLists.txt file for building the Einit program in the einit directory.
• The files of EDL, CDL and IDL descriptions should be put into the resources directory in the project root.
• [Optional] Create a cross-build.sh build script containing the commands to start generating build files (cmake command), to build the solution (make command), and to start the solution.

Example structure of project directories

Building a project

To prepare for a build using the CMake build system, the following is required:

1. Prepare a CMakeLists.txt boot file containing the general build instructions for the entire solution.
2. Prepare CMakeLists.txt files for each application to be built.
3. Prepare a CMakeLists.txt file for the Einit program.
4. Prepare the init.yaml.in and security.psl.in templates.

To perform cross-compilation using the CMake build automation system, the following is required:

1. Create a subdirectory for the build.

   BUILD=$PWD/.build

   mkdir -p $BUILD && cd $BUILD

2. Prior to starting generation of build scripts (cmake command), set the following values for environment variables:
   • export LANG=C
   • export PKG_CONFIG=""
   • export SDK_PREFIX="/opt/KasperskyOS-Community-Edition-<version>"
   • export PATH="$SDK_PREFIX/toolchain/bin:$PATH"
   • export INSTALL_PREFIX=$BUILD/../install
   • export TARGET="aarch64-kos"
3. When starting generation of build scripts (cmake command), specify the following:
   • -G "Unix Makefiles" parameter
   • Path to the file with the build system extension (toolchain.cmake) in the CMAKE_TOOLCHAIN_FILE variable.

     The file with the build system extension is located in the following directory: /opt/KasperskyOS-Community-Edition-<version>/toolchain/share/toolchain-aarch64-kos.cmake

   • Value of the CMAKE_BUILD_TYPE:STRING=Debug variable
   • Value of the CMAKE_INSTALL_PREFIX:STRING=$INSTALL_PREFIX variable
   • Path to the CMakeLists.txt boot file
4. When starting the build (make command), specify one of the build targets.

   The target name must match the build target name passed to the solution build command in the CMakeLists.txt file for the Einit program.

Example cross-build.sh build script

cross-build.sh

CMakeLists.txt boot file

The CMakeLists.txt boot file contains general build instructions for the entire solution.

The CMakeLists.txt boot file must contain the following commands:

• cmake_minimum_required (VERSION 3.12) indicates the minimum supported version of CMake.

  For a KasperskyOS-based solution build, CMake version 3.12 or later is required.

  The required version of CMake is provided in KasperskyOS Community Edition and is used by default.

• include (platform) connects the platform library of CMake.
• initialize_platform() initializes the platform library.
• project_header_default("STANDARD_GNU_11:YES" "STRICT_WARNINGS:NO") sets the flags of the compiler and linker.
• [Optional] Connect and configure packages for the provided system programs and drivers that need to be included in the solution:
  • A package is connected by using the find_package() command.
  • After connecting a package, you must add the package-related directories to the list of search directories by using the include_directories() command.
  • For some packages, you must also set the values of properties by using the set_target_properties() command.

  CMake descriptions of system programs and drivers provided in KasperskyOS Community Edition, and descriptions of their exported variables and properties are located in the corresponding files at /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/lib/cmake/<program name>/<program name>-config.cmake

• The Einit initializing program must be built using the add_subdirectory(einit) command.
• All applications to be built must be added by using the add_subdirectory(<program directory name>) command.

Example CMakeLists.txt boot file

CMakeLists.txt

CMakeLists.txt files for building applications

The CMakeLists.txt file for building an application must contain the following commands:

• include (platform/nk) connects the CMake library for working with the NK compiler.
• project_header_default ("STANDARD_GNU_11:YES" "STRICT_WARNINGS:NO") sets the flags of the compiler and linker.
• An EDL description of a process class for a program can be generated by using the generate_edl_file() command.
• If the program provides endpoints using an IPC mechanism, the following transport code must be generated:
  1. idl.h files are generated by the nk_build_idl_files() command
  2. cdl.h files are generated by the nk_build_cdl_files() command
  3. edl.h files are generated by the nk_build_edl_files() command
• add_executable (<program name> "<path to the file containing the program source code>") adds the program build target.
• add_dependencies (<program name> <name of the edl.h file build target>) adds a program build dependency on edl.h file generation.
• target_link_libraries (<program name> <list of libraries>) determines the libraries that need to be linked with the program during the build.

  For example, if the program uses file I/O or network I/O, it must be linked with the ${vfs_CLIENT_LIB} transport library.

  CMake descriptions of system programs and drivers provided in KasperskyOS Community Edition, and descriptions of their exported variables and properties are located in the corresponding files at /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/lib/cmake/<program name>/<program name>-config.cmake

• To automatically add descriptions of IPC channels to the init.yaml file when building a solution, you must define the EXTRA_CONNECTIONS property and assign it a value with descriptions of the relevant IPC channels.

  Example of creating an IPC channel between a Client process and a Server process:

  set_target_properties (Client PROPERTIES

  EXTRA_CONNECTIONS

  " - target: Server

  id: server_connection")

  When building this solution, the description of this IPC channel will be automatically added to the init.yaml file when processing macros of the init.yaml.in template.

• To automatically add a list of arguments for the main() function and a dictionary of environment variables to the init.yaml file when building a solution, you must define the EXTRA_ARGS and EXTRA_ENV properties and assign the appropriate values to them.

  Example of sending the Client program the "-v" argument of the main() function and the environment variable VAR1 set to VALUE1:

  set_target_properties (Client PROPERTIES

  EXTRA_ARGS

  " - \"-v\""

  EXTRA_ENV

  " VAR1: VALUE1")

  When building this solution, the description of the main() function argument and the environment variable value will be automatically added to the init.yaml file when processing macros of the init.yaml.in template.

Example CMakeLists.txt file for building a simple application

CMakeLists.txt

CMakeLists.txt file for building the Einit program

The CMakeLists.txt file for building the Einit initializing program must contain the following commands:

• include (platform/image) connects the CMake library that contains the solution image build scripts.
• project_header_default ("STANDARD_GNU_11:YES" "STRICT_WARNINGS:NO") sets the flags of the compiler and linker.
• Configure the packages of system programs and drivers that need to be included in the solution.
  • A package is connected by using the find_package () command.
  • For some packages, you must also set the values of properties by using the set_target_properties () command.

  CMake descriptions of system programs and drivers provided in KasperskyOS Community Edition, and descriptions of their exported variables and properties are located in the corresponding files at /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/lib/cmake/<program name>/<program name>-config.cmake

• To automatically add descriptions of IPC channels between processes of system programs to the init.yaml file when building a solution, you must add these channels to the EXTRA_CONNECTIONS property for the corresponding programs.

  For example, the VFS program does not have a channel for connecting to the Env program by default. To automatically add a description of this channel to the init.yaml file during a solution build, you must add the following call to the CMakeLists.txt file for building the Einit program:

  set_target_properties (${vfs_ENTITY} PROPERTIES

  EXTRA_CONNECTIONS

  " - target: env.Env

  id: {var: ENV_SERVICE_NAME, include: env/env.h}"

  When building this solution, the description of this IPC channel will be automatically added to the init.yaml file when processing macros of the init.yaml.in template.

• To automatically add a list of arguments for the main() function and a dictionary of environment variables to the init.yaml file when building a solution, you must define the EXTRA_ARGS and EXTRA_ENV properties and assign the appropriate values to them.

Example of sending the VfsEntity program the "-f fstab" argument of the main() function and the environment variable ROOTFS set to ramdisk0,0 / ext2 0:

When building this solution, the description of the main() function argument and the environment variable value will be automatically added to the init.yaml file when processing macros of the init.yaml.in template.

• set(ENTITIES <full list of programs included in the solution>) defines the ENTITIES variable containing a list of executable files of all programs included in the solution.
• One or both commands for building the solution image:
  • build_kos_hw_image() creates the build target that can then be used to build the image for the hardware platform using make.
  • build_kos_qemu_image() creates the build target that can then be used to build the image for running in QEMU using make.

Example CMakeLists.txt file for building the Einit program

CMakeLists.txt

init.yaml.in template

The init.yaml.in template is used to automatically generate a part of the init.yaml file prior to building the Einit program using CMake tools.

When using the init.yaml.in template, you do not have to manually add descriptions of system programs and the IPC channels for connecting to them to the init.yaml file.

The init.yaml.in template must contain the following data:

• Root entities key.
• List of all applications included in the solution.
• For applications that use an IPC mechanism, you must specify a list of IPC channels that connect this application to other applications.

  The IPC channels that connect this application to other applications are either indicated manually or specified in the CMakeLists.txt file for this application using the EXTRA_CONNECTIONS property.

  To specify a list of IPC channels that connect this application to system programs that are included in KasperskyOS Community Edition, the following macros are used:

  • @INIT_<program name>_ENTITY_CONNECTIONS@ – during the build, this is replaced with the list of IPC channels containing all system programs that are linked to the application. The target and id fields are filled according to the connect.yaml files from KasperskyOS Community Edition located in /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include/<system program name>).

    This macro needs to be used if the application does not have connections to other applications but instead connects only to system programs. This macro adds the root connections key.

  • @INIT_<program name>_ENTITY_CONNECTIONS+@ – during the build, the list of IPC channels containing all system programs that are linked to the application is added to the manually defined list of IPC channels. This macro does not add the root connections key.

    This macro needs to be used if the application has connections to other applications that were manually indicated in the init.yaml.in template.

• The @INIT_<program name>_ENTITY_CONNECTIONS@ and @INIT_<program name>_ENTITY_CONNECTIONS+@ macros also add the list of connections for each program defined in the EXTRA_CONNECTIONS property when building this program.
• If you need to pass main() function arguments defined in the EXTRA_ARGS property to a program when building this program, you need to use the following macros:
  • @INIT_<program name>_ENTITY_ARGS@ – during the build, this is replaced with the list of arguments of the main() function defined in the EXTRA_ARGS property. This macro adds the root args key.
  • @INIT_<program name>_ENTITY_ARGS+@ – during the build, this macro adds the list of main() function arguments defined in the EXTRA_ARGS property to the list of manually defined arguments. This macro does not add the root args key.
• If you need to pass the values of environment variables defined in the EXTRA_ENV property to a program when building this program, you need to use the following macros:
  • @INIT_<program name>_ENTITY_ENV@ – during the build, this is replaced with the dictionary of environment variables and their values defined in the EXTRA_ENV property. This macro adds the root env key.
  • @INIT_<program name>_ENTITY_ENV+@ – during the build, this macro adds the dictionary of environment variables and their values defined in the EXTRA_ENV property to the manually defined variables. This macro does not add the root env key.
• @INIT_EXTERNAL_ENTITIES@ – during the build, this macro is replaced with the list of system programs linked to the application and their IPC channels, main() function arguments, and values of environment variables.

Example init.yaml.in template

init.yaml.in

When building the Einit program from this template, the following init.yaml file will be generated:

init.yaml

security.psl.in template

The security.psl.in template is used to automatically generate a part of the security.psl file prior to building the Einit program using CMake tools.

The security.psl file contains part of the solution security policy description.

When using the security.psl.in template, you do not have to manually add EDL descriptions of system programs to the security.psl file.

The security.psl.in template must contain a manually created solution security policy description, including the following declarations:

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

To automatically include system programs, the @INIT_EXTERNAL_ENTITIES@ macro must be used.

Example security.psl.in template

security.psl.in

CMake libraries in KasperskyOS Community Edition

This section contains a description of the libraries that are provided in KasperskyOS Community Edition for automatically building a KasperskyOS-based solution.

platform library

The platform library contains the following commands:

• initialize_platform() is the command for initializing the platform library.
• project_header_default() is a command for indicating the linker and compiler flags for the current project.

These commands are used in CMakeLists.txt files for the Einit program and application software.

nk library

This section contains a description of the commands and macros of the CMake library for working with the NK compiler.

generate_edl_file()

This command is declared in the file /opt/KasperskyOS-Community-Edition-<version>toolchain/share/cmake/Modules/platform/nk2.cmake.

This command generates an EDL file containing a description of the process class.

Parameters:

• NAME is the name of the process class. Required parameter.
• PREFIX is the name of the global module associated with the EDL file. The name of the project must be indicated in this parameter.
• EDL_COMPONENTS is the name of the component and its instance that will be included in the EDL file. For example: EDL_COMPONENTS "env: kl.Env". To include multiple components, you need to use multiple EDL_COMPONENTS parameters.
• SECURITY is the qualified name of the security interface method that will be included in the EDL file.
• OUTPUT_DIR is the directory in which the EDL file will be created. The default directory is ${CMAKE_CURRENT_BINARY_DIR}.
• OUTPUT_FILE is the name of the EDL file being created. The default name is ${OUTPUT_DIR}/${NAME}.edl.

This command exports the EDL_FILE variable and sets it equal to the path to the generated EDL file.

Example call:

For an example of using this command, see the article titled "CMakeLists.txt files for building application software".

nk_build_idl_files()

This command is declared in the file /opt/KasperskyOS-Community-Edition-<version>toolchain/share/cmake/Modules/platform/nk2.cmake.

This command creates a CMake target for generating .idl.h files for one or more defined IDL files using the NK compiler.

Parameters:

• NAME is the name of the CMake target for building .idl.h files. If a target has not yet been created, it will be created by using add_library() with the specified name. Required parameter.
• NOINSTALL – if this option is specified, files will only be generated in the working directory but will not be installed in global directories: ${CMAKE_BINARY_DIR}/_headers_ ${CMAKE_BINARY_DIR}/_headers_/${PROJECT_NAME}.
• NK_MODULE is the global module associated with the interface. The name of the project must be indicated in this parameter.
• WORKING_DIRECTORY is the working directory for calling the NK compiler, which by default is the following: ${CMAKE_CURRENT_BINARY_DIR}.
• DEPENDS refers to the additional build targets on which the IDL file depends.

  To add multiple targets, you need to use multiple DEPENDS parameters.

• IDL is the path to the IDL file for which the idl.h file is being generated. Required parameter.

  To add multiple IDL files, you need to use multiple IDL parameters.

  If one IDL file imports another IDL file, idl.h files need to be generated in the order necessary for compliance with dependencies (with the most deeply nested first).

• NK_FLAGS are additional flags for the NK compiler.

Example call:

For an example of using this command, see the article titled "CMakeLists.txt files for building application software".

nk_build_cdl_files()

This command is declared in the file /opt/KasperskyOS-Community-Edition-<version>toolchain/share/cmake/Modules/platform/nk2.cmake.

This command creates a CMake target for generating .cdl.h files for one or more defined CDL files using the NK compiler.

Parameters:

• NAME is the name of the CMake target for building .cdl.h files. If a target has not yet been created, it will be created by using add_library() with the specified name. Required parameter.
• NOINSTALL – if this option is specified, files will only be generated in the working directory but are not installed in global directories: ${CMAKE_BINARY_DIR}/_headers_ ${CMAKE_BINARY_DIR}/_headers_/${PROJECT_NAME}.
• IDL_TARGET is the target when building .idl.h files for IDL files containing descriptions of endpoints provided by components described in CDL files.
• NK_MODULE is the global module associated with the component. The name of the project must be indicated in this parameter.
• WORKING_DIRECTORY is the working directory for calling the NK compiler, which by default is the following: ${CMAKE_CURRENT_BINARY_DIR}.
• DEPENDS refers to the additional build targets on which the CDL file depends.

  To add multiple targets, you need to use multiple DEPENDS parameters.

• CDL is the path to the CDL file for which the cdl.h file is being generated. Required parameter.

  To add multiple CDL files, you need to use multiple CDL parameters.

• NK_FLAGS are additional flags for the NK compiler.

Example call:

For an example of using this command, see the article titled "CMakeLists.txt files for building application software".

nk_build_edl_files()

This command is declared in the file /opt/KasperskyOS-Community-Edition-<version>toolchain/share/cmake/Modules/platform/nk2.cmake.

This command creates a CMake target for generating an .edl.h file for one defined EDL file using the NK compiler.

Parameters:

• NAME is the name of the CMake target for building an .edl.h file. If a target has not yet been created, it will be created by using add_library() with the specified name. Required parameter.
• NOINSTALL – if this option is specified, files will only be generated in the working directory but are not installed in global directories: ${CMAKE_BINARY_DIR}/_headers_ ${CMAKE_BINARY_DIR}/_headers_/${PROJECT_NAME}.
• CDL_TARGET is the target when building .cdl.h files for CDL files containing descriptions of components of the EDL file for which the build is being performed.
• IDL_TARGET is the target when building .idl.h files for IDL files containing descriptions of interfaces of the EDL file for which the build is being performed.
• NK_MODULE is the global module associated with the EDL file. The name of the project must be indicated in this parameter.
• WORKING_DIRECTORY is the working directory for calling the NK compiler, which by default is the following: ${CMAKE_CURRENT_BINARY_DIR}.
• DEPENDS refers to the additional build targets on which the EDL file depends.

  To add multiple targets, you need to use multiple DEPENDS parameters.

• EDL is the path to the EDL file for which the edl.h file is being generated. Required parameter.
• NK_FLAGS are additional flags for the NK compiler.

Example calls:

For an example of using this command, see the article titled "CMakeLists.txt files for building application software".

image library

This section contains a description of the commands and macros of the CMake library named image that is included in KasperskyOS Community Edition and contains solution image build scripts.

build_kos_hw_image()

This command is declared in the file /opt/KasperskyOS-Community-Edition-<version>toolchain/share/cmake/Modules/platform/image.cmake.

This command creates a CMake target for building a solution image that can then be used to build the image for the hardware platform using make.

Parameters:

• NAME is the name of the CMake target for building a solution image. Required parameter.
• PERFCNT_KERNEL – use the kernel with performance counters if it is available in KasperskyOS Community Edition.
• EINIT_ENTITY is the name of the executable file that will be used to start the Einit program.
• EXTRA_XDL_DIR refers to additional directories to include when building the Einit program.
• CONNECTIONS_CFG is the path to the init.yaml file or init.yaml.in template.
• SECURITY_PSL is the path to the security.psl file or security.psl.in template.
• KLOG_ENTITY is the target for building the Klog system program, which is responsible for the security audit. If the target is not specified, the audit is not performed.
• IMAGE_BINARY_DIR_BIN is the directory for the final image and other artifacts. The default directory is CMAKE_CURRENT_BINARY_DIR.
• IMAGE_FILES are the executable files of applications and system programs (except the Einit program) and any other files to be added to the ROMFS image.

  To add multiple applications or files, you can use multiple IMAGE_FILES parameters.

• <path to files> are free parameters like IMAGE_FILES.

Example call:

For an example of using this command, see the article titled "CMakeLists.txt files for building the Einit program".

build_kos_qemu_image()

This command is declared in the file /opt/KasperskyOS-Community-Edition-<version>toolchain/share/cmake/Modules/platform/image.cmake.

This command creates a CMake target for building a solution image that can then be used to build the image for QEMU using make.

Parameters:

• NAME is the name of the CMake target for building a solution image. Required parameter.
• PERFCNT_KERNEL – use the kernel with performance counters if it is available in KasperskyOS Community Edition.
• EINIT_ENTITY is the name of the executable file that will be used to start the Einit program.
• EXTRA_XDL_DIR refers to additional directories to include when building the Einit program.
• CONNECTIONS_CFG is the path to the init.yaml file or init.yaml.in template.
• SECURITY_PSL is the path to the security.psl file or security.psl.in template.
• KLOG_ENTITY is the target for building the Klog system program, which is responsible for the security audit. If the target is not specified, the audit is not performed.
• QEMU_FLAGS are additional flags for running QEMU.
• IMAGE_BINARY_DIR_BIN is the directory for the final image and other artifacts. It matches CMAKE_CURRENT_BINARY_DIR by default.
• IMAGE_FILES are the executable files of applications and system programs (except the Einit program) and any other files to be added to the ROMFS image.

  To add multiple applications or files, you can use multiple IMAGE_FILES parameters.

• <path to files> are free parameters like IMAGE_FILES.

Example call:

For an example of using this command, see the article titled "CMakeLists.txt files for building the Einit program".

Building without CMake

This section contains a description of the scripts, tools, compilers and build templates provided in KasperskyOS Community Edition.

These tools can be used:

• In other build systems.
• To perform individual steps of the build.
• To analyze the build specifications and write a custom build system.

The general scenario for building a solution image is described in the article titled Build process overview.

Tools for building a solution

This section contains a description of the scripts, tools, compilers and build templates provided in KasperskyOS Community Edition.

Build scripts and tools

KasperskyOS Community Edition includes the following build scripts and tools:

• nk-gen-c

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

• nk-psl-gen-c

  The nk-psl-gen-c compiler generates the source code of the Kaspersky Security Module based on the solution security policy description (security.psl) and the EDL, CDL and IDL descriptions included in the solution.

• einit

  The einit tool lets you automate the creation of code for the Einit initializing program. This program is the first to start when KasperskyOS is loaded. Then it starts all other programs and creates IPC channels between them.

• makekss

  The makekss script creates the Kaspersky Security Module.

• makeimg

  The makeimg script creates the final boot image of the KasperskyOS-based solution with all programs to be started and the Kaspersky Security Module.

nk-gen-c

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

The NK compiler receives the EDL, CDL or IDL file and creates the following files:

• H file containing a declaration and implementation of transport methods and types.
• D file that lists the dependencies of the created C file. This file can be used for building automation using the make tool.

Syntax for using the NK compiler:

Parameters:

• FILE

  Path to the EDL, CDL or IDL description for which you need to generate transport methods and types.

• -I PATH

  Path to the folder containing auxiliary files required for generating transport methods and types. By default, these files are located in the directory /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include.

  It may also be used for adding other folders to search for the files required for generating the methods and types.

  To indicate more than one folder. you can use several -I switches.

• -o PATH

  Path to an existing folder where files containing transport methods and types will be created.

• -h, --help

  Displays the Help text.

• --version

  Displays the nk-gen-c version.

• --enforce-alignment-check

  Enables mandatory alignment checks for queries to memory, even if this check is disabled for the target platform. If these checks are enabled, the NK compiler adds additional alignment checks to the code of the IPC message validators.

  By default, memory query alignment check settings are defined for each platform in the file named system.platform.

• --extended-errors

  Enables extended error handling in the code of transport methods.

Selective generation

To reduce the amount of code generated by the NK compiler, you can use selective generation flags. For example, it is convenient to use the --server flag for programs that implement endpoints, and to use the --client flag for programs that are clients of the endpoints.

Selective generation flags for IDL files:

• --types

  The compiler will create only the constants and types, including the redefined ones (typedef), from the input IDL file, and the types from imported IDL files that are used in the types of the input file.

  However, constants and redefined types from imported IDL files will not be explicitly included in the generated files. If you need to use types from imported files in code, you need to separately generate H files for each such IDL file.

• --interface

  The compiler will generate files created with the --types flag, and the structures of request and response messages for all methods of this endpoint.

• --client

  The compiler will generate files created with the --interface flag, and the client proxy objects and functions of their initialization for all methods of this endpoint.

• --server

  The compiler will generate files created with the --interface flag, and the types and methods of the dispatcher of this endpoint.

Selective generation flags for CDL files and EDL files:

• --types

  The compiler will generate files created with the --types flag for all endpoints provided by this component.

  However, only the types that are used in parameters of interface methods will be explicitly included in the generated files.

• --interface

  The compiler will generate files created with the --types flag for this component/process class, and files generated with the --interface flag for all services provided by this component.

• --client

  The compiler will generate files created with the --interface flag, and the client proxy objects and functions of their initialization for all endpoints provided by this component.

• --server

  The compiler will generate files created with the --interface flag, and the types and methods of the dispatcher of this component/process class and the types and methods of dispatchers for all endpoints provided by this component.

nk-psl-gen-c

The nk-psl-gen-c compiler generates the source code of the Kaspersky Security Module based on the solution security policy description and the EDL, CDL and IDL descriptions included in the solution. This code is used by the makekss script.

The nk-psl-gen-c compiler also lets you generate and run code of tests written in the PAL language for the solution security policy.

Syntax for using the nk-psl-gen-c compiler:

Parameters:

• FILE

  Path to the PSL description of the solution security policy (security.psl)

• -I,--include-dir PATH

  Path to the folder containing auxiliary files required for generating transport methods and types. By default, these files are located in the directory /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include.

  The nk-psl-gen-c compiler will require access to all EDL, CDL and IDL descriptions. To enable the nk-psl-gen-c compiler to find these descriptions, you need to pass the paths to these descriptions using the -I switch.

  To indicate more than one folder. you can use several -I switches.

• -o,--output PATH

  Path to the created file containing the security module code.

• -t, --tests ARG

  Flag for controlling code generation and starting tests for the solution security policy. Possible values:

  • skip means that the code of tests is not generated. This value is used by default if the --tests flag is not indicated.
  • generate means that the code of tests is generated but it is not compiled and is not executed.
  • run means that the code of tests is generated, compiled using the gcc compiler, and executed.
• -a, --audit PATH

  Path to the created file containing the code of the audit decoder.

• -h, --help

  Displays the Help text.

• --version

  Displays the nk-psl-gen-c version.

einit

The einit tool lets you automate the creation of code for the Einit initializing program.

The einit tool receives the solution initialization description (the init.yaml file by default) and EDL, CDL and IDL descriptions, and creates a file containing the source code of the Einit initializing program. Then the Einit program must be built using the C-language cross compiler that is provided in KasperskyOS Community Edition.

Syntax for using the einit tool:

Parameters:

• FILE

  Path to the init.yaml file.

• -I PATH

  Path to the directory containing the auxiliary files (including EDL, CDL and IDL descriptions) required for generating the initializing program. By default, these files are located in the directory /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include.

• -o, --out-file PATH

  Path to the created .c file containing the code of the initializing program.

• -h, --help

  Displays the Help text.

makekss

The makekss script creates the Kaspersky Security Module.

The script calls the nk-psl-gen-c compiler to generate the source code of the security module, then compiles the resulting code by calling the C compiler that is provided in KasperskyOS Community Edition.

The script creates the security module from the solution security policy description.

Syntax for using the makekss script:

Parameters:

• FILE

  Path to the top-level file of the solution security policy description.

• --target=ARCH

  Processor architecture for which the build is intended.

• --module=-lPATH

  Path to the ksm_kss library. This key is passed to the C compiler for linking to this library.

• --with-nk=PATH

  Path to the nk-psl-gen-c compiler that will be used to generate the source code of the security module. By default, the compiler is located in /opt/KasperskyOS-Community-Edition-<version>/toolchain/bin/nk-psl-gen-c.

• --with-nktype="TYPE"

  Indicates the type of NK compiler that will be used. To use the nk-psl-gen-c compiler, indicate the psl type.

• --with-nkflags="FLAGS"

  Parameters used when calling the nk-psl-gen-c compiler.

  The nk-psl-gen-c compiler will require access to all EDL, CDL and IDL descriptions. To enable the nk-psl-gen-c compiler to find these descriptions, you need to pass the paths to these descriptions in the --with-nkflags parameter by using the -I switch of the nk-psl-gen-c compiler.

• --output=PATH

  Path to the created security module file.

• --with-cc=PATH

  Path to the C compiler that will be used to build the security module. The compiler provided in KasperskyOS Community Edition is used by default.

• --with-cflags=FLAGS

  Parameters used when calling the C compiler.

• -h, --help

  Displays the Help text.

makeimg

The makeimg script creates the final boot image of the KasperskyOS-based solution with all executable files of programs and the Kaspersky Security Module.

The script receives a list of files, including the executable files of all applications that need to be added to ROMFS of the loaded image, and creates the following files:

• Solution image
• Solution image without character tables (.stripped)
• Solution image with debug character tables (.dbg.syms)

Syntax for using the makeimg script:

Parameters:

• FILES

  List of paths to files, including the executable files of all applications that need to be added to ROMFS.

  The security module (ksm.module) must be explicitly specified, or else it will not be included in the solution image. The Einit application does not need to be indicated because it will be automatically included in the solution image.

• --target=ARCH

  Architecture for which the build is intended.

• --sys-root=PATH

  Path to the root directory sysroot. By default, this directory is located in /opt/KasperskyOS-Community-Edition-version/sysroot-aarch64-kos/.

• --with-toolchain=PATH

  Path to the set of auxiliary tools required for the solution build. By default, these tools are located in /opt/KasperskyOS-Community-Edition-<version>/toolchain/.

• --ldscript=PATH

  Path to the linker script required for the solution build. By default, this script is located in /opt/KasperskyOS-Community-Edition-<version>/libexec/aarch64-kos/.

• --img-src=PATH

  Path to the precompiled KasperskyOS kernel. By default, the kernel is located in /opt/KasperskyOS-Community-Edition-<version>/libexec/aarch64-kos/.

• --img-dst=PATH

  Path to the created image file.

• --with-init=PATH

  Path to the executable file of the Einit initializing program.

• --with-extra-asflags=FLAGS

  Additional flags for the AS Assembler.

• --with-extra-ldflags=FLAGS

  Additional flags for the LD Linker.

• -h, --help

  Displays the Help text.

Cross compilers

Properties of KasperskyOS cross compilers

The cross compilers included in KasperskyOS Community Edition support processors that have the aarch64 architecture.

The KasperskyOS Community Edition toolchain includes the following tools for cross compilation:

• GCC:
  • aarch64-kos-gcc
  • aarch64-kos-g++
• Binutils:
  • AS Assembler: aarch64-kos-as
  • LD Linker: aarch64-kos-ld

In addition to standard macros, an additional macro __KOS__=1 is defined in GCC. Using this macro lets you simplify porting of the software code to KasperskyOS, and also simplifies development of platform-independent applications.

To view the list of standard macros of GCC, run the following command:

Linker operation specifics

When building the executable file of an application, by default the linker links the following libraries in the specified order:

1. libc – standard C library.
2. libm – library that implements the mathematical functions of the standard C language library.
3. libvfs_stubs – library that contains stubs of I/O functions (for example, open, socket, read, write).
4. libkos is the library for accessing the KasperskyOS core endpoints.
5. libenv is the library of the subsystem for configuring the environment of applications (environmental variables, arguments of the main function, and custom configurations).
6. libsrvtransport-u is the library that supports IPC between processes and the kernel.

Example build without using CMake

Below is an example of a script for building a basic example. This example contains a single application called Hello, which does not provide any endpoints.

build.sh

Creating a bootable drive containing the solution image

To create a bootable drive containing the solution image:

1. Connect the drive from which you plan to run the solution image on target devices.
2. Find the block device corresponding to the connected drive, for example, by using the following command:

   fdisk -l

3. If required, create a new drive partition on which the solution image will be deployed by using the fdisk tool, for example.
4. If there is no file system on the partition, create one by using the mkfs tool, for example.

   You can use any file system that is supported by the GRUB 2 bootloader.

5. Mount the drive.

   mkdir /mnt/kos_device && mount /dev/sdXY /mnt/kos_device

   Here, /mnt/kos_device is the mount point, /dev/sdXY is the block device name, X is the letter corresponding to the connected drive, and Y is the partition number.

6. Install the GRUB 2 operating system bootloader on the drive.

   To install GRUB 2, run the following command:

   grub-install --force --removable \
--boot-directory=/mnt/kos_device/boot /dev/sdX

   Here, /mnt/kos_device is the mount point, /dev/sdX is the block device name, and X is the letter corresponding to the connected drive.

7. Copy the solution image to the root directory of the mounted drive.
8. In the /mnt/kos_device/boot/grub/grub.cfg file, add the menuentry section that points to the solution image.

   menuentry "KasperskyOS" {

   multiboot /my_kasperskyos.img

   boot

   }

9. Unmount the drive.

   umount /mnt/kos_device

   Here, /mnt/kos_device is the mount point.

After performing these actions, you can start KasperskyOS from this drive.