add_kss_pal_qemu_tests()

Before reading this section, you are advised to familiarize yourself with the general principles of creating and testing a security policy for a KasperskyOS-based solution.

This section describes the add_kss_pal_qemu_tests() function of the CMake library test_generator:

• Function syntax
• Function parameters
• Artifacts generated by the function
• Building and running PAL tests that the function was used to create
• Function usage examples

Function syntax

This function is declared in a file located in KasperskyOS Community Edition at the following path: toolchain/share/cmake/Modules/test-generator/add_kss_pal_qemu_tests.cmake. The file is available only in the distribution package of KasperskyOS Community Edition for QEMU.

add_kss_pal_qemu_tests(...)

This function generates the Einit initializing program and other artifacts required for building and running a PAL test (also a test in the PAL language) of a security policy for a KasperskyOS-based solution.

Function parameters

• TEST_NAME_PREFIX <PREFIX>

  The prefix used to create the names of PAL test executable files and directories containing artifacts.

  The name of each PAL test executable file is generated according to the following template: <PREFIX>PalTest<N>, where N is the PSL file index in the list of PSL files specified via the PSL_FILES parameter.

  The path to the directory containing artifacts is generated according to the following template: <program build directory>/<PREFIX>/pal-test/.

• USE_GENERATE_KOS_TEST <ON|OFF>

  Method for generating PAL test artifacts. When set to ON, the generate_kos_test() function is used for each PAL test to generate the full set of artifacts required for running the test in KasperskyOS. When set to OFF, only the following parts of PAL test artifacts are generated: executable file, initialization description files, and security policies. The default value is ON.

• PSL_FILES <FILE1> [<FILE2>…]

  List of paths to PSL files (*.psl or *.psl.in). For each PSL file on this list, a PAL test named <PREFIX>PalTest<N> is created: PREFIX is the prefix specified in the TEST_NAME_PREFIX parameter, and N is the index of the PSL file on the list.

• ENTITIES <ENTITY1> [<ENTITY2>…]

  List of CMake targets for building program executables required for testing the security policy for a KasperskyOS-based solution. This parameter is required if *.psl.in templates are used. These programs will be automatically added to the PAL test security policy and initialization description files.

• DEPENDS <TARGET1> [<TARGET2>…]

  A list of CMake targets whose execution will cause the PSL file-dependent IDL, CDL, and EDL files to be put into the directories where the nk-psl-gen-c compiler can find them. Specifying the dependencies ensures that these CMake targets will be built before starting the compilation of PSL files, thereby making the IDL, CDL, and EDL files available to the nk-psl-gen-c compiler.

• CUSTOM_VFS <NAME>

  Name of the CMake target of the custom VFS server implementation. When this parameter is specified, the executable files of PAL tests will use the specified implementation to access the file system. This parameter is used if USE_GENERATE_KOS_TEST is set to ON.

• FSTAB_FILE <PATH>

  Path to the custom fstab file. This parameter is used if USE_GENERATE_KOS_TEST is set to ON.

• ENV_VARS <VAR1=VAL1> [<VAR2=VAL2>…]

  List of environment variables passed to PAL test executables at startup. This parameter is used if USE_GENERATE_KOS_TEST is set to ON.

• GINGER_ENABLE <ON|OFF>

  Enables (ON) or disables (OFF) the Ginger template engine.

• GINGER_DEFINITIONS <DEF1> [<DEF2>…]

  The set of variables used when expanding Ginger PSL templates.

• GINGER_DUMP_DIR <DIR>

  Path to the directory where intermediate PSL files received from Ginger PSL templates will be stored. If this parameter is not specified, the intermediate files are not saved.

• TAGS <TAG1> [<TAG2>…]

  List of PAL test tags. Tags can be used to group and filter PAL tests.

Artifacts generated by the function

The add_kss_pal_qemu_tests() function generates the artifacts required for building and running a PAL test in KasperskyOS. Artifacts are generated in the following directories:

• Solution build directory: the solution build root directory specified in the -B option of the cmake command (normally the build directory). It is designated by the ${CMAKE_BINARY_DIR} variable in the CMakeList.txt build files.
• Program build directory: the subdirectory in the root directory where the program included in the solution is built: <name of solution build directory>/<name of directory containing program source code >. For example, the build/einit directory will be the build subdirectory of the Einit program. It is designated by the ${CMAKE_CURRENT_BINARY_DIR} variable in the CMakeList.txt build files.

The following artifacts are generated in the solution build directory:

• Script containing commands to run this solution in QEMU: bin/tests/gtest_<PAL test name>.qemu.sh
• YAML file containing the test parameters: ./bin/tests/qemu-<PAL test name>-test-conf.yaml
• Bootable solution image ./generated/einit_<PAL test name>/kos-qemu-image-<PAL test name>
• Build files of the Einit initialization program for the PAL test in the directory ./generated/einit_<PAL test name>/
• Fstab file with the name ./generated/fstab_<PAL test name>/fstab

In the program build directory:

• Disk image ./<PAL test name>-images/system_hdd.img. After starting the PAL test, the junit report output_junit.xml will be written to the disk.
• PAL test executable file ./<PAL test name>
• PAL test EDL description ./pal-test/<PAL test name>.edl
• Automatically generated transport code ./pal-test/<PAL test name>.edl.h
• Source code generated by the nk-psl-gen-c tool:
  • C-language audit decoder ./pal-test/security.psl.audit.c
  • PAL tests in C++ ./pal-test/security.psl.test.cpp
  • Kaspersky Security Module ./pal-test/security.psl.ksm.cpp

Building and running the PAL test

The process of building and running a PAL test is described in step 4 of the test procedure in the section titled Creating and performing tests for a KasperskyOS-based solution security policy.

You can also build and run PAL tests using the KasperskyOS SDK Extension for Visual Studio Code. For more details, please refer to the Extension functions section that describes how to run tests of solution security policies.

Example

# Minimum required version of the CMake build system for the project.

cmake_minimum_required (VERSION 3.25)

# Name of the CMake project.

project (pal_tests)

# Connect the CMake library named platform.

include (platform)

# Statically link executable files.

initialize_platform (FORCE_STATIC)

# Include the CMake library containing the solution image build scripts.

include (platform/image)

# Include the CMake library named nk for working with the NK compiler (nk-gen-c).

include (platform/nk)

# Connect the test_generator CMake library module add_kss_pal_qemu_tests to the project.

include (test-generator/add_kss_pal_qemu_tests)

# Create a CMake target for generating an .idl.h file

# for the specified IDL file by using the NK compiler.

nk_build_idl_files (${PROJECT_NAME}_idl_files

NK_MODULE pal_tests

IDL "${NK_RESOURCES}/pal_tests/${IDL_FILE}")

# Create a CMake target for generating an .edl.h file

# for the specified EDL file by using the NK compiler.

nk_build_edl_files (${PROJECT_NAME}_edl_files

DEPENDS ${PROJECT_NAME}_idl_files

NK_MODULE pal_tests

EDL "${NK_RESOURCES}/pal_tests/${EDL_FILE})

add_kss_pal_qemu_tests (

PSL_FILES

src/security.psl

DEPENDS

${PROJECT_NAME}_edl_files)

For more details, see the pal_tests example located in examples directory, in the KasperskyOS Community Edition.

Page top