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 transport code based on the IDL, CDL, and EDL descriptions. Transport code is needed for generating, sending, receiving, and processing IPC messages.

• nk-psl-gen-c

  The nk-psl-gen-c compiler generates the C-language source code of the Kaspersky Security Module based on the solution security policy description and the IDL, CDL, and EDL descriptions. The nk-psl-gen-c compiler also generates the C-language source code of solution security policy tests based on solution security policy tests in PAL.

• einit

  The einit tool automates 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 transport code based on the IDL, CDL, and EDL descriptions.

The nk-gen-c compiler receives the IDL, CDL or EDL file and creates the following files:

• A *.*dl.h file containing the transport code.
• A *.*dl.nk.d file that lists the created *.*dl.h file's dependencies on the IDL and CDL files. The *.*dl.nk.d file is created for the build system.

Syntax of the shell command for starting the nk-gen-c compiler:

Basic parameters:

• FILE

  Path to the IDL, CDL, or EDL file for which you need to generate transport code.

• -I <PATH>

  These parameters are used to define the paths to directories containing the auxiliary files required for generating transport code. (The auxiliary files are located in the sysroot-*-kos/include directory from the KasperskyOS SDK.) These parameters can also be used to define the paths to directories containing IDL and CDL files that are referenced by the file defined via the FILE parameter.

• -o <PATH>

  Path to an existing directory where the created files will be placed. If this parameter is not specified, the created files will be put into the current directory.

• -h|--help

  Prints the Help text.

• --version

  Prints the version of the nk-gen-c compiler.

• --extended-errors

  This parameter provides the capability to use interface methods with one or more error parameters of user-defined IDL types. (The client works with error parameters like it works with output parameters.)

  If the --extended-errors parameter is not specified, you can use interface methods only with one status error parameter of the IDL type UInt16 whose value is passed to the client via return code of the interface method. This mechanism is obsolete and will no longer be supported in the future, so you are advised to always specify the --extended-errors parameter.

Selective generation of transport code

To reduce the volume of generated transport code, you can use flags for selective generation of transport code. For example, you can use the --server flag for programs that implement endpoints, and use the --client flag for programs that utilize the endpoints.

Flags for selective generation of transport code for an IDL file:

• --types

  The transport code includes the types corresponding to the IDL types from the defined IDL file, and the types corresponding to this file's imported IDL types that are used in IDL types of the defined IDL file. However, the types corresponding to imported IDL constants and to the aliases of imported IDL types are not included in the *.idl.h file. To use the types corresponding to imported IDL constants and to the aliases of imported IDL types, you must separately generate the transport code for the IDL files from which you are importing.

• --interface

  The transport code corresponds to the --types flag, and includes the types of structures of the constant part of IPC requests and IPC responses for interface methods whose signatures are specified in the defined IDL file. In addition, the transport code contains constants indicating the sizes of IPC message arenas.

• --client

  The transport code corresponds to the --interface flag, and includes the proxy object type, proxy object initialization method, and the interface methods specified in the defined IDL file.

• --server

  The transport code corresponds to the --interface flag, and includes the types and dispatcher (dispatch method) used to process IPC requests corresponding to the interface methods specified in the defined IDL file.

Flags for selective generation of transport code for a CDL or EDL file:

• --types

  The transport code includes the types corresponding to the IDL types that are used in the method parameters of endpoints provided by the component (for the defined CDL file) or process class (for the defined EDL file).

• --endpoints

  The transport code corresponds to the --types flag, and includes the types of structures of the constant part of IPC requests and IPC responses for the methods of endpoints provided by the component (for the defined CDL file) or process class (for the defined EDL file). In addition, the transport code contains constants indicating the sizes of IPC message arenas.

• --client

  The transport code corresponds to the --types flag, and includes the types of structures of the constant part of IPC requests and IPC responses for the methods of endpoints provided by the component (for the defined CDL file) or process class (for the defined EDL file). In addition, the transport code contains constants indicating the sizes of IPC message arenas, and the proxy object types, proxy object initialization methods, and methods of endpoints provided by the component (for the defined CDL file) or process class (for the defined EDL file).

• --server

  The transport code corresponds to the --types flag, and includes the types and dispatchers (dispatch methods) used to process IPC requests corresponding to the endpoints provided by the component (for the defined CDL file) or process class (for the defined EDL file). In addition, the transport code contains constants indicating the sizes of IPC message arenas, and the stub types, stub initialization methods, and the types of structures of the constant part of IPC requests and IPC responses for the methods of endpoints provided by the component (for the defined CDL file) or process class (for the defined EDL file).

Printing diagnostic information about sending and receiving IPC messages

Transport code can generate diagnostic information about sending and receiving IPC messages and print this data via standard error. To generate transport code with these capabilities, use the following parameters:

• --trace-client-ipc {headers|dump}

  The code for printing diagnostic information is executed directly before the Call() system call is executed and immediately after it is executed. If the headers value is specified, the diagnostic information includes the endpoint method ID (MID), the endpoint ID (RIID), the size of the constant part of the IPC message (in bytes), the contents of the IPC message arena handle, the size of the IPC message arena (in bytes), and the size of the utilized part of the IPC message arena (in bytes). If the dump value is specified, the diagnostic information additionally includes the contents of the constant part and arena of the IPC message in hexadecimal format.

  When using this parameter, you must either specify the selective generation flag for transport code --client or refrain from specifying a selective generation flag for transport code.

• --trace-server-ipc {headers|dump}

  The code for printing diagnostic information is executed directly before calling the function that implements the interface method, and immediately after the completion of this function. In other words, it is executed when the dispatcher (dispatch method) is called in the interval between execution of the Recv() and Reply() system calls. If the headers value is specified, the diagnostic information includes the endpoint method ID (MID), the endpoint ID (RIID), the size of the constant part of the IPC message (in bytes), the contents of the IPC message arena handle, the size of the IPC message arena (in bytes), and the size of the utilized part of the IPC message arena (in bytes). If the dump value is specified, the diagnostic information additionally includes the contents of the constant part and arena of the IPC message in hexadecimal format.

  When using this parameter, you must either specify the selective generation flag for transport code --server or refrain from specifying a selective generation flag for transport code.

• --ipc-trace-method-filter <METHOD>[,METHOD]...

  Diagnostic information is printed if only the defined interface methods are called. For the METHOD value, you can use the interface method name or the construct <package name>:<interface method name>. The package name and interface method name are specified in the IDL file.

  If this parameter is not specified, diagnostic information is printed when any interface method is called.

  This parameter can be specified multiple times. For example, you can specify all required interface methods in one parameter or specify each required interface method in a separate parameter.

nk-psl-gen-c

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

The nk-psl-gen-c compiler can also generate the C-language source code of solution security policy tests based on solution security policy tests in PAL.

Syntax of the shell command for starting the nk-psl-gen-c compiler:

Parameters:

• INPUT

  Path to the top-level file of the solution security policy description. This is normally the security.psl file.

• {-I|--include-dir} <DIR>

  These parameters are used to define the paths to directories containing IDL, CDL, and EDL files pertaining to the solution, and the paths to directories containing auxiliary files from the KasperskyOS SDK (common, sysroot-*-kos/include, toolchain/include).

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

  Path to the file that will save the source code of the Kaspersky Security Module and (optionally) the source code of solution security policy tests. The path must include existing directories.

• --out-tests <FILE>

  Path to the file that will save the source code of the solution security policy tests.

• {-t|--tests} <ARG>

  Defines whether the source code of solution security policy tests must be generated. ARG can take the following values:

  • skip: – source code of tests is not generated. This value is used by default if the -t, --tests <ARG> parameter is not specified.
  • generate: – source code of tests is generated. If the source code of tests is generated, you are advised to use the --out-tests <FILE> parameter. Otherwise, the source code of tests will be saved in the same file containing the source code of the Kaspersky Security Module, which may lead to errors during the build.
• {-a|--audit} <FILE>

  Path to the file that will save the C-language source code of the audit decoder.

• -h|--help

  Prints the Help text.

• --version

  Prints the version of the nk-psl-gen-c compiler.

einit

The einit tool automates 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

The toolchain provided in the KasperskyOS SDK includes one or more GCC compilers. The toolchain/bin directory contains the following files:

• Executable files of compilers (for example, x86_64-pc-kos-gcc, arm-kos-g++)
• Executable files of linkers (for example, x86_64-pc-kos-ld, arm-kos-ld)
• Executable files of assemblers (for example, x86_64-pc-kos-as, arm-kos-as)

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

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 is the standard C library.
2. libm is the library that implements the mathematical functions of the standard C language library.
3. libvfs_stubs is the 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 (environment variables, arguments of the main function, and custom configurations).
6. libsrvtransport-u is the library that supports IPC between processes and the kernel.