libkos library

The libkos library is the basic KasperskyOS library that provides the set of APIs that allow programs and other libraries (for example, libc and kdf) to use core endpoints. The APIs provided by the libkos library enable solution developers to do the following:

• Manage processes, threads, and virtual memory.
• Control access to resources.
• Perform input/output operations.
• Create IPC channels.
• Manage power.
• Obtain statistical data on the system.
• Use other capabilities supported by core endpoints.

Managing handles (handle_api.h)

The API is defined in the sysroot-*-kos/include/coresrv/handle/handle_api.h header file from the KasperskyOS SDK.

The API is intended for performing operations with handles. Handles have the Handle type, which is defined in the header file sysroot-*-kos/include/handle/handletype.h from the KasperskyOS SDK.

Locality of handles

Each process receives handles from its own handle space irrespective of other processes. The handle spaces of different processes are absolutely identical in that they consist of the same set of values. Therefore, a handle is unique (has a unique value) only within the handle space of the single process that owns the particular handle. In other words, different processes may have identical handles that identify different resources, or may have different handles that identify the same resource.

Handle permissions mask

A handle permissions mask has a size of 32 bits and consists of a general part and a specialized part. The general part describes the general rights that are not specific to any particular resource (the flags of these rights are defined in the header file sysroot-*-kos/include/services/ocap.h from the KasperskyOS SDK). For example, the general part contains the OCAP_HANDLE_TRANSFER flag, which defines the permission to transfer the handle. The specialized part describes the rights that are specific to the particular user resource or system resource. The flags of the specialized part's permissions for system resources are defined in the ocap.h header file. The structure of the specialized part for user resources is defined by the resource provider by using the OCAP_HANDLE_SPEC() macro that is defined in the ocap.h header file. The resource provider must export the public header files describing the flags of the specialized part.

When the handle of a system resource is created, the permissions mask is defined by the KasperskyOS kernel, which applies permissions masks from the ocap.h header file. It applies permissions masks with names such as OCAP_*_FULL (for example, OCAP_IOPORT_FULL, OCAP_TASK_FULL, OCAP_FILE_FULL) and OCAP_IPC_* (for example, OCAP_IPC_SERVER, OCAP_IPC_LISTENER, OCAP_IPC_CLIENT).

When the handle of a user resource is created, the permissions mask is defined by the user.

When a handle is transferred, the permissions mask is defined by the user but the transferred access rights cannot be elevated above the access rights of the process.

Creating handles

Information about API functions is provided in the table below.

Creating handles of system resources

Handles of system resources are created when these resources are created. For example, handles are created when an interrupt or MMIO memory region is registered, and when a DMA buffer, thread, or process is created.

Creating handles of user resources

Handles of user resources are created by the providers of these resources by using the KnHandleCreateUserObject() or KnHandleCreateUserObjectEx() function.

The context of a user resource must be defined through the context parameter. The user resource context consists of data that allows the resource provider to identify the resource and its state when access to the resource is requested by other processes. This normally consists of a data set with various types of data (structure). For example, the context of a file may include the name, path, and cursor position. The user resource context is used as the resource transfer context or is used together with multiple resource transfer contexts.

You must use the rights parameter to define the handle permissions mask.

Creating IPC handles

An IPC handle is a handle that identifies an IPC channel. IPC handles are used to execute system calls. A client IPC handle is necessary for executing a Call() system call. A server IPC handle is necessary for executing the Recv() and Reply() system calls. A listener handle is a server IPC handle that has extended rights allowing it to add IPC channels to the set of IPC channels identified by this handle. A callable handle is a client IPC handle that simultaneously identifies the IPC channel to a server and an endpoint of this server.

A server creates a callable handle and passes it to a client so that the client can use the server endpoint. The client initializes IPC transport by using the callable handle that it received. In addition, the client specifies the INVALID_RIID value as the Runtime Implementation Identifier (RIID) in the proxy object initialization function. To create a callable handle, call the KnHandleCreateUserObjectEx() function and specify the server IPC handle and the RIID in the ipcChannel and riid parameters, respectively. Use the context parameter to specify the data to be associated with the callable handle. The server will be able to receive the pointer to this data when dereferencing the callable handle. (Even though the callable handle is an IPC handle, the kernel puts it into the base_.self field of the constant part of an IPC request.)

To create the client IPC handle, server IPC handle, and listener IPC handle and associate them with each other, call the KnHandleConnect() or KnHandleConnectEx() function. These functions are used to statically create IPC channels. The KnHandleConnect() function creates IPC handles from the handle space of the calling process. However, the client IPC handle can be transferred to another process. The KnHandleConnectEx() function can create IPC handles from the handle space of the calling process or from the handle spaces of other processes, such as the client and server.

When calling the KnHandleConnect() or KnHandleConnectEx() function with the INVALID_HANDLE value in the parameter that defines the listener handle, a new listener handle is created. However, the server IPC handle and listener IPC handle in the output parameters are the same handle. If a listener handle is specified when calling the KnHandleConnect() or KnHandleConnectEx() function, the created server IPC handle will provide the capability to receive IPC requests over all IPC channels associated with this listener handle. In this case, the server IPC handle and listener IPC handle in the output parameters are different handles. (The first IPC channel associated with the listener handle is created when calling the KnHandleConnect() or KnHandleConnectEx() function with the INVALID_HANDLE value in the parameter that defines the listener handle. The second and subsequent IPC channels associated with the listener handle are created during the second and subsequent calls of the KnHandleConnect() or KnHandleConnectEx() function specifying the listener handle that was obtained during the first call.)

To call a listener handle that is not associated with a client IPC handle and server IPC handle, call the KnHandleCreateListener() function. (The KnHandleConnect() and KnHandleConnectEx() functions create a listener handle associated with a client IPC handle and server IPC handle.) The KnHandleCreateListener() function is convenient for creating a listener handle that will be subsequently bound to callable handles.

To create a client IPC handle for querying the Kaspersky Security Module through the security interface, call the KnHandleSecurityConnect() function. This function is called by the libkos library when initializing IPC transport for querying the security module.

Information about API functions

handle_api.h functions

Transferring handles

Information about API functions is provided in the table below.

Overview of handle transfers

Handles are transferred between processes so that resource consumers can gain access to required resources. Due to the specific locality of handles, a handle transfer initiates the creation of a handle from the handle space of the recipient process. This handle is registered as a descendant of the transferred handle and identifies the same resource.

One handle can be transferred multiple times to one or more processes. Each transfer initiates the creation of a new descendant of the transferred handle on the recipient process side. A process can transfer handles that it received from other processes or the KasperskyOS kernel. For this reason, a handle may have multiple generations of descendants. The generation hierarchy of handles for each resource is stored in the KasperskyOS kernel in the form of a handle inheritance tree.

A process can transfer handles for user resources and system resources if the access rights of these handles permit such a transfer (the OCAP_HANDLE_TRANSFER flag is set in the permissions mask). A descendant may have less access rights than an ancestor. For example, a transferring process with read-and-write permissions for a file can transfer read-only permissions. The transferring process can also prohibit the recipient process from further transferring the handle. Access rights are defined in the transferred permissions mask for the handle.

Conditions for transferring handles

To enable processes to transfer handles to other processes, the following conditions must be met:

1. An IPC channel is created between the processes.
2. The solution security policy (security.psl) allows interaction between process classes.
3. Interface methods are implemented for transferring handles.

In an IDL description, signatures of interface methods for transferring handles have input (in) and/or output (out) parameters of the Handle type or array type with elements of the Handle type. Up to 255 handles can be passed through the input parameters of one method. This same number of handles can be received through output parameters.

Example IDL description that defines the signatures of interface methods for transferring handles:

For each parameter of the Handle type, the NK compiler generates a field of the nk_handle_desc_t type (hereinafter also referred to as the transport container of the handle) in the *_req IPC request structure and/or *_res IPC response structure. This type is declared in the header file sysroot-*-kos/include/nk/types.h from the KasperskyOS SDK and comprises a structure consisting of the following three fields: handle field for the handle, rights field for the handle permissions mask, and the badge field for the resource transfer context.

Resource transfer context

The resource transfer context consists of data that allows the server to identify the resource and its state when access to the resource is requested via descendants of the transferred handle. This normally consists of a data set with various types of data (structure). For example, the transfer context of a file may include the name, path, and cursor position. The server receives a pointer to the resource transfer context when dereferencing a handle.

Regardless of whether or not the server is the resource provider, the server can associate each handle transfer with a separate resource transfer context. This resource transfer context is bound only to the handle descendants (handle inheritance subtree) that were generated as a result of a specific transfer of the handle. This lets you define the state of a resource in relation to a separate transfer of the handle of this resource. For example, for cases when one file may be accessed multiple times, the file transfer context lets you define which specific opening of this file corresponds to a received IPC request.

If the server is the resource provider, each transfer of the handle of this resource is associated with the user resource context by default. In other words, the user resource context is used as the resource transfer context for each handle transfer if the particular transfer is not associated with a separate resource transfer context.

A server that is the resource provider can use both the user resource context and the resource transfer context together. For example, the name, path and size of a file is stored in the user resource context while the cursor position can be stored in multiple resource transfer contexts because each client can work with different parts of the file. Technically, joint use of the user resource context and resource transfer contexts is possible because the resource transfer contexts store a pointer to the user resource context.

If the client uses multiple various-type resources of the server, the resource transfer contexts (or contexts of user resources if they are used as resource transfer contexts) must be typified objects of the KosObject type (for details about KosObjects, see Using KosObjects (objects.h)). This is necessary so that the server can verify that the client using a resource has sent the interface method the handle of the specific resource that corresponds to this method. This verification is required because the client could mistakenly send the interface method a resource handle that does not correspond to this method. For example, a client may have received a file handle and sent it to an interface method for working with volumes.

To associate a handle transfer with a resource transfer context, the server puts the handle of the resource transfer context object into the badge field of the nk_handle_desc_t structure. The resource transfer context object is the kernel object that stores the pointer to the resource transfer context. To create a resource transfer context object, call the KnHandleCreateBadge() function. This function is bound to the notification mechanism because a server needs to know when a resource transfer context object will be closed and deleted. The server needs this information to free up or re-use memory that was allotted for storing the resource transfer context.

The resource transfer context object will be closed upon the closure or revocation of the handle descendants that comprise the handle inheritance subtree whose root node was generated by the transfer of this handle in association with this object. (A transferred handle may be closed intentionally or unintentionally, such as when a recipient client is unexpectedly terminated.) After receiving a notification regarding the closure of a resource transfer context object, the server closes the handle of this object. After this, the resource transfer context object will be deleted. After receiving a notification regarding the deletion of the resource transfer context object, the server frees up or re-uses the memory that was allotted for storing the resource transfer context.

One resource transfer context object can be associated with only one handle transfer.

Packaging data into the transport container of a handle

To package a handle, handle permissions mask, and resource transfer context object handle into a handle transport container, use the nk_handle_desc() macro that is defined in the header file sysroot-*-kos/include/nk/types.h from the KasperskyOS SDK. This macro receives a variable number of parameters.

If no parameter is passed to the macro, the NK_INVALID_HANDLE value will be written to the handle field of the nk_handle_desc_t structure. If one parameter is passed to the macro, this parameter is interpreted as the handle. If two parameters are passed to the macro, the first parameter is interpreted as the handle and the second parameter is interpreted as the handle permissions mask. If three parameters are passed to the macro, the first parameter is interpreted as the handle, the second parameter is interpreted as the handle permissions mask, and the third parameter is interpreted as the resource transfer context object handle.

Extracting data from the transport container of a handle

To extract the handle, handle permissions mask, and pointer to the resource transfer context from the transport container of a handle, use the nk_get_handle(), nk_get_rights() and nk_get_badge_op() (or nk_get_badge()) functions, respectively, which are declared in the header file sysroot-*-kos/include/nk/types.h from the KasperskyOS SDK. The nk_get_badge_op() and nk_get_badge() functions should be used only when dereferencing handles.

Handle transfer scenarios

The scenario for transferring handles from a client to the server includes the following steps:

1. The client packages the handles and handle permissions masks into fields of the *_req IPC requests structure of the nk_handle_desc_t type.
2. The client calls the interface method for transferring handles to the server. The Call() system call is executed when this method is called.
3. The server receives an IPC request by executing the Recv() system call.
4. The dispatcher on the server side calls the method corresponding to the IPC request. This method extracts the handles and handle permissions masks from fields of the *_req IPC request structure of the nk_handle_desc_t type.

The scenario for transferring handles from the server to a client includes the following steps:

1. The client calls the interface method for receiving handles from the server. The Call() system call is executed when this method is called.
2. The server receives an IPC request by executing the Recv() system call.
3. The dispatcher on the server side calls the method corresponding to the IPC request. This method packages the handles, handle permissions masks and resource transfer context object handles into fields of the *_res IPC response structure of the nk_handle_desc_t type.
4. The server responds to the IPC request by executing the Reply() system call.
5. On the client side, the interface method returns control. After this, the client extracts the handles and handle permissions masks from fields of the *_res IPC response structure of the nk_handle_desc_t type.

If the transferring process defines more access rights in the transferred handle permissions mask than the access rights defined for the transferred handle (which it owns), the transfer is not completed. In this case, the Call() system call executed by the transferring or recipient client or the Reply() system call executed by the transferring server ends with the rcSecurityDisallow error.

Information about API functions

handle_api.h functions

Duplicating handles

Handle duplication is similar to a handle transfer, but duplication is performed within a process. A handle descendant is created in the same process and from the same handle space. The rights of the handle descendant may be less than or equal to the rights of the original handle. Handle duplication can be associated with a resource transfer context object. This lets you use the notification mechanism to track the closure or revocation of all handle descendants that form the handle inheritance subtree whose root node was generated by the duplication operation. It also provides the capability to revoke these descendants.

To duplicate a handle, call the KnHandleCopy() function. To do so, the OCAP_HANDLE_COPY flag must be set in the handle permissions mask.

Information about API functions is provided in the table below.

handle_api.h functions

Dereferencing handles

When dereferencing a handle, the client sends the handle to the server, and the server receives a pointer to the resource transfer context, the permissions mask of the sent handle, and the ancestor of the handle sent by the client and already owned by the server. Dereferencing occurs when a resource consumer that called methods for working with a resource (such as read/write or access closure) sends the resource provider the handle that was received from this resource provider when access to the resource was opened.

Dereferencing handles requires fulfillment of the same conditions and utilizes the same mechanisms and data types as when transferring handles. A handle dereferencing scenario includes the following steps:

1. The client packages the handle into a field of the *_req IPC request structure of the nk_handle_desc_t type.
2. The client calls the interface method for sending the handle to the server for the purpose of performing operations with the resource. The Call() system call is executed when this method is called.
3. The server receives the IPC request by executing the Recv() system call.
4. The dispatcher on the server side calls the method corresponding to the IPC request. This method verifies that the dereferencing operation was specifically executed instead of a handle transfer. Then the called method has the option to verify that the access rights of the dereferenced handle (that was sent by the client) permit the requested actions with the resource, and extracts the pointer to the resource transfer context from the field of the *_req request structure of the nk_handle_desc_t type.

To perform verification, the server uses the nk_is_handle_dereferenced() and nk_get_badge_op() functions that are declared in the header file sysroot-*-kos/include/nk/types.h from the KasperskyOS SDK.

types.h (fragment)

Generally, the server does not require the handle that was received from dereferencing because the server normally retains the handles that it owns, for example, within the contexts of user resources. However, the server can extract this handle from the handle transport container if necessary.

Revoking handles

A process can revoke descendants of a handle that it owns. Handles are revoked according to the handle inheritance tree.

Revoked handles are not closed. However, you cannot query resources via revoked handles. Any function that receives the handle will end with the rcHandleRevoked error if the function is called with a revoked handle.

To revoke handle descendants, call the KnHandleRevoke() or KnHandleRevokeSubtree() function. The KnHandleRevokeSubtree() function uses the resource transfer context object that is created when transferring handles.

If each handle of a system resource in all processes that own these handles are closed (see Closing handles) or revoked, this system resource will be deleted.

Information about API functions is provided in the table below.

handle_api.h functions

Closing handles

A process can close the handles that it owns. Closing a handle terminates the association between an ID and a resource, thereby releasing the ID. Closing a handle does not invalidate its ancestors and descendants (in contrast to revoking a handle, which actually invalidates the descendants of the handle). In other words, the ancestors and descendants of a closed handle can still be used to provide access to the resource that they identify. Also, closing a handle does not disrupt the handle inheritance tree associated with the resource identified by the particular handle. The place of a closed handle is occupied by its ancestor. In other words, the ancestor of a closed handle becomes the direct ancestor of the descendants of the closed handle.

To close the handle, call the KnHandleClose() function.

If each handle of a system resource in all processes that own these handles are revoked (see Revoking handles) or closed, this system resource will be deleted.

Information about API functions is provided in the table below.

handle_api.h functions

Getting a security ID (SID)

By getting the SID values for different handles, you can determine whether these handles identify different resources or the same resource.

To get a security ID for a handle, call the KnHandleGetSidByHandle() function. To do so, the OCAP_HANDLE_GET_SID flag must be set in the handle permissions mask.

Information about API functions is provided in the table below.

handle_api.h functions

OCap usage example

This example describes an OCap usage scenario in which the resource provider provides the following methods for accessing its resources:

• OpenResource() – opens access to the resource.
• UseResource() – uses the resource.
• CloseResource() – closes access to the resource.

The resource consumer uses these methods.

IDL description:

The scenario includes the following steps:

1. The resource provider creates the user resource context and calls the KnHandleCreateUserObject() function to create the resource handle. The resource provider saves the resource handle in the user resource context.
2. The resource consumer calls the OpenResource() method to open access to the resource.
   1. The resource provider creates the resource transfer context and calls the KnHandleCreateBadge() function to create a resource transfer context object and configure the notification receiver to receive notifications regarding the closure and deletion of the resource transfer context object. The resource provider saves the handle of the resource transfer context object and the pointer to the user resource context in the resource transfer context.
   2. The resource provider uses the nk_handle_desc() macro to package the resource handle, permissions mask of the handle, and pointer to the resource transfer context object into the handle transport container.
   3. The handle is transferred from the resource provider to the resource consumer, which means that the resource consumer receives a descendant of the handle owned by the resource provider.
   4. The OpenResource() method call completes successfully. The resource consumer extracts the handle and permissions mask of the handle from the handle transport container by using the nk_get_handle() and nk_get_rights() functions, respectively. The handle permissions mask is not required by the resource consumer to query the resource, but is transferred so that the resource consumer can find out its permissions for accessing the resource.
3. The resource consumer calls the UseResource() method to utilize the resource.
   1. The handle that was received from the resource provider at step 2 is used as a parameter of the UseResource() method. Before calling this method, the resource consumer uses the nk_handle_desc() macro to package the handle into the handle transport container.
   2. The handle is dereferenced, after which the resource provider receives the pointer to the resource transfer context.
   3. The resource provider uses the nk_is_handle_dereferenced() function to verify that the dereferencing operation was completed instead of a handle transfer.
   4. The resource provider verifies that the access rights of the dereferenced handle (that was sent by the resource consumer) allows the requested operation with the resource, and extracts the pointer to the resource transfer context from the handle transport container. To do so, the resource provider uses the nk_get_badge_op() function, which extracts the pointer to the resource transfer context from the handle transport container if the received permissions mask has the corresponding flags set for the requested operation.
   5. The resource provider uses the resource transfer context and the user resource context to perform the corresponding operation with the resource as requested by the resource consumer. Then the resource provider sends the results of this operation to the resource consumer.
   6. The UseResource() method call completes successfully. The resource consumer receives the results of the operation performed with the resource.
4. The resource consumer calls the CloseResource() method to close access to the resource.
   1. The handle that was received from the resource provider at step 2 is used as a parameter of the CloseResource() method. Before calling this method, the resource consumer uses the nk_handle_desc() macro to package the handle into the handle transport container. After the CloseResource() method is called, the resource consumer uses the KnHandleClose() function to close the handle.
   2. The handle is dereferenced, after which the resource provider receives the pointer to the resource transfer context.
   3. The resource provider uses the nk_is_handle_dereferenced() function to verify that the dereferencing operation was completed instead of a handle transfer.
   4. The resource provider uses the nk_get_badge() function to extract the pointer to the resource transfer context from the handle transport container.
   5. The resource provider uses the KnHandleRevokeSubtree() function to revoke the handle owned by the resource consumer. The resource handle owned by the resource provider and the handle of the resource transfer context object are used as parameters of this function. The resource provider obtains access to these handles through the pointer to the resource transfer context. (Technically, the handle owned by the resource consumer does not have to be revoked because the resource consumer already closed it. However, the revoke operation is performed in case the resource provider is not sure if the resource consumer actually closed the handle).
   6. The CloseResource() method call completes successfully.
5. The resource provider frees up the memory that was allocated for the resource transfer context and user resource context.
   1. The resource provider calls the KnNoticeGetEvent() function to receive a notification that the resource transfer context object was closed, and uses the KnHandleClose() function to close the handle of the resource transfer context object.
   2. The resource provider calls the KnNoticeGetEvent() function to receive a notification that the resource transfer context object was deleted, and frees up the memory that was allocated for the resource transfer context.
   3. The resource provider uses the KnHandleClose() function to close the resource handle and free up the memory that was allocated for the user resource context.

Managing virtual memory (vmm_api.h)

The API is defined in the header file sysroot-*-kos/include/coresrv/vmm/vmm_api.h from the KasperskyOS SDK.

The API is designed to allocate and free memory, create shared memory, and prepare ELF image segments to be loaded into process memory.

Allocating and freeing memory

Information about API functions is provided in the table below.

Using the API

Virtual memory pages may be free, reserved, or committed. Free pages that are used to allocate a virtual memory region become reserved pages. Reserved pages may or may not be mapped to physical memory. Reserved pages that are mapped to physical memory are committed pages.

Pages of a virtual memory region that are allocated by the KnVmAllocate() function call can be committed in three different ways:

1. Fully committed when the region is allocated.
2. Fully or partially committed after allocation of the region (by calling the KnVmCommit() function).
3. Committed whenever virtual addresses are queried (so-called "lazy" mode).

When the first option is used, the entire required volume of physical memory is allocated immediately after the virtual memory region is reserved. When the second or third option is used, the virtual memory region is reserved without allocating physical memory. This lets you conserve physical memory if a reserved virtual memory region will not actually be required or will only be partially used. In addition, a virtual memory region can be allocated faster if its allocation does not include commitment.

When in "lazy" mode, physical memory is allocated only when the virtual memory region is actually queried. In this case, the page containing the queried address and several pages before and after this address are committed.

If you call the KnVmAllocate() function with the VMM_FLAG_COMMIT and VMM_FLAG_LOCKED flags, the virtual memory region will be reserved and fully committed. If you call the KnVmAllocate() function with the VMM_FLAG_COMMIT flag but without the VMM_FLAG_LOCKED flag, the virtual memory region will be reserved and committed only in "lazy" mode. If you call the KnVmAllocate() function with the VMM_FLAG_LOCKED flag but without the VMM_FLAG_COMMIT flag, the virtual memory region will be reserved without commitment and a subsequent call of the KnVmCommit() function will fully commit this region. If you call the KnVmAllocate() function without the VMM_FLAG_COMMIT and VMM_FLAG_LOCKED flags, the virtual memory region will be reserved without commitment and a subsequent call of the KnVmCommit() function will commit this region in "lazy" mode.

A virtual memory region is allocated when the MDL buffer, DMA buffer or MMIO memory region is mapped to process memory. This region is allocated by the mapping function.

A protected page may reside at the beginning and/or end of the virtual memory region. This page is never committed. Any query of this page will result in an exception signaling that the region boundaries have been exceeded.

To change the access rights to the virtual memory region, call the KnVmProtect() function. You can fully close and then re-open access to a region while retaining is contents.

To free physical memory while retaining the reservation of virtual addresses, call the KnVmDecommit() or KnVmReset() function. In this case, the contents of the virtual memory region will be lost. After freeing physical memory by calling the KnVmDecommit() function, you must call the KnVmCommit() function to subsequently use the virtual memory region. After freeing physical memory by calling the KnVmReset() function, the virtual memory region can be used without any additional actions required. This virtual memory region will correspond to memory allocated by calling the KnVmAllocate() function with the VMM_FLAG_COMMIT flag but without the VMM_FLAG_LOCKED flag.

To free the virtual memory region, call the KnVmUnmap() function. When this function is called, the reserved pages will become free regardless of whether or not they were committed, and the physical memory mapped to committed pages is also freed.

The KnVmCommit(), KnVmProtect(), KnVmDecommit(), KnVmReset(), and KnVmUnmap() functions can be applied for the entire allocated virtual memory region or for a portion of it.

The functions presented in this section provide the basis for implementing memory allocation/deallocation functions of the libkos library, and functions of POSIX interfaces such as malloc(), calloc(), realloc(), free(), mmap(), and munmap().

Information about API functions

vmm_api.h functions

Creating shared memory

Information about API functions is provided in the table below.

Using the API

An MDL buffer is used to create shared memory. An MDL buffer consists of one or more physical memory regions that can be mapped to the memory of multiple processes at the same time. A kernel object known as a memory descriptor list is used to map the MDL buffer to process memory. A memory descriptor list (MDL) is a data structure containing the addresses and sizes of physical memory regions comprising the MDL buffer. The MDL buffer handle identifies the memory descriptor list.

To create shared memory, a process needs to create an MDL buffer, map it to its own memory, and pass the MDL buffer handle via IPC to other processes that also need to map this MDL buffer to their own memory.

To create an MDL buffer, call the KnPmmMdlCreate(), KnPmmMdlCreateFromBuf() or KnPmmMdlCreateFromVm() function. The KnPmmMdlCreateFromBuf() function creates an MDL buffer and copies data to it. The KnPmmMdlCreateFromVm() function creates an MDL buffer and maps it to the memory of the calling process.

To reserve a virtual memory region and map the MDL buffer to it, call the KnPmmMdlMap() function. An MDL buffer can be mapped to multiple virtual memory regions of the same process.

An MDL buffer can be used to transfer large volumes of data between processes without creating shared memory. In this case, you must make sure that the MDL buffer is not mapped to the memory of multiple processes at the same time. Interacting processes must take turns mapping the MDL buffer to their own memory, reading and/or writing data and then freeing the virtual memory region that is mapped to this MDL buffer.

Deleting an MDL buffer

To delete an MDL buffer, complete the following steps:

1. Free the virtual memory regions mapped to the MDL buffer in all processes that are using this MDL buffer.

   To complete this step, use the KnVmUnmap() function.

2. Close or revoke each MDL buffer handle in all processes that own these handles.

   To complete this step, use the KnHandleClose() and/or KnHandleRevoke() functions that are declared in the header file sysroot-*-kos/include/coresrv/handle/handle_api.h from the KasperskyOS SDK.

Information about API functions

vmm_api.h functions

Preparing ELF image segments to be loaded into process memory

Information about API functions is provided in the table below.

Using the API

MDL buffers are used not only to create shared memory, but also to load ELF image segments into the memory of a new process. (ELF image segments are loaded by the Einit initializing program, for example.)

The KnVmSegInitFromVm() and KnVmSegInitFromBuf() functions create an MDL buffer and put the ELF image segment into it so that this segment can then be loaded into the memory of a new process.

Deleting MDL buffers containing ELF image segments

To delete MDL buffers containing ELF image segments, you must terminate the new process whose memory is mapped to these MDL buffers. You also need to complete the following steps before or after termination of this process:

1. Free the virtual memory regions that are mapped to the MDL buffers in the process that created these MDL buffers.

   This step is required only for MDL buffers that were created using the KnVmSegInitFromVm() function.

   To complete this step, use the KnVmUnmap() function.

2. Close the handles of MDL buffers in the process that created these MDL buffers.

   To complete this step, use the KnHandleClose() function, which is declared in the header file sysroot-*-kos/include/coresrv/handle/handle_api.h from the KasperskyOS SDK.

Information about API functions

vmm_api.h functions

Allocating and freeing memory (alloc.h)

The API is defined in the header file sysroot-*-kos/include/kos/alloc.h from the KasperskyOS SDK.

The API is intended for allocating and freeing memory. Allocated memory is a committed virtual memory region that can be accessed for read-and-write operations.

Information about API functions is provided in the table below.

alloc.h functions

Using DMA (dma.h)

The API is defined in the header file sysroot-*-kos/include/coresrv/io/dma.h from the KasperskyOS SDK.

The API is designed to set up data exchange between devices and RAM in direct memory access (DMA) mode in which the processor is not used.

Information about API functions is provided in the table below.

Using the API

The standard scenario for API usage includes the following steps:

1. Creating a DMA buffer.

   DMA buffer consists of one or more physical memory regions (blocks) that are used for DMA. A DMA buffer consisting of multiple blocks can be used if the device supports "scatter/gather DMA" mode. A DMA buffer consisting of one block can be used only if the device supports "scatter/gather DMA" or "continuous DMA" mode. The likelihood of creating a DMA buffer consisting of one large block is lower than the likelihood of creating a DMA buffer consisting of multiple small blocks. This is especially relevant when physical memory is highly fragmented.

   If the device supports only "continuous DMA" mode, you must use a DMA buffer consisting of one block even if IOMMU is enabled.

   To complete this step, call the KnIoDmaCreate() or KnIoDmaCreateContinuous() function. The KnIoDmaCreateContinuous() function creates a DMA buffer consisting of one block. The KnIoDmaCreate() function creates a DMA buffer consisting of one block if the 2^order value is equal to the memory page size value, or if the 2^order value is the next largest value of the memory page size in the ascending ordered set {2^(order-1);memory page size;2^order}. If the value of the memory page size is greater than the 2^order value, the KnIoDmaCreate() function can create a DMA buffer consisting of multiple blocks.

   The DMA buffer handle can be transferred to another process via IPC.

2. Mapping the DMA buffer to the memory of processes.

   One DMA buffer can be mapped to multiple virtual memory regions of one or more processes that own the handle of this DMA buffer. Mapping allows processes to receive read-and/or-write access to the DMA buffer.

   To reserve a virtual memory region and map the DMA buffer to it, call the KnIoDmaMap() function.

   A handle received when calling the KnIoDmaMap() function cannot be transferred to another process via IPC.

3. Opening access to the DMA buffer for a device via the KnIoDmaBegin() or KnIoDmaBeginEx() function call.

   The KnIoDmaBegin() or KnIoDmaBeginEx() function must be called to create a kernel object containing the addresses and sizes of blocks comprising the DMA buffer. A device needs this information to use the DMA buffer. A device can work with physical addresses and/or virtual addresses depending on whether IOMMU is enabled. If IOMMU is enabled, you must use the KnIoDmaBegin() or KnIoDmaBeginEx() function, and the object will contain virtual and physical addresses of blocks. If IOMMU is not enabled, you must use the KnIoDmaBegin() function, and the object will contain physical addresses of blocks only.

   When IOMMU is enabled, the device must be attached to an IOMMU domain.

   A handle received when calling the KnIoDmaBegin() or KnIoDmaBeginEx() function cannot be transferred to another process via IPC.

4. Information about the DMA buffer is received.

   At this step, get the addresses and sizes of blocks from the kernel object that was created by calling the KnIoDmaBegin() or KnIoDmaBeginEx() function. The received addresses and sizes will need to be passed to the device by using MMIO, for example. After receiving this information, the device can write to the DMA buffer and/or read from it.

   To complete this step, call one of the following functions:

   • KnIoDmaGetInfo()
   • KnIoDmaGetPhysInfo()
   • KnIoDmaContinuousGetDmaAddr()
   • KnIoDmaContinuousGetPhysAddr()

   The KnIoDmaGetInfo() and KnIoDmaGetPhysInfo() functions get the memory page number (frame) and the order for each block. (The memory page number multiplied by the memory page size results in the block address. The 2^order value is the block size in memory pages.) These functions use the output parameter outInfo to pass the KosObject that contains the structure with information about the DMA buffer (for details about KosObjects, see Using KosObjects (objects.h)). The type of structure is defined in the header file sysroot-*-kos/include/io/io_dma.h from the KasperskyOS SDK. The KnIoDmaGetInfo() function inserts data into all fields of the structure, while the KnIoDmaGetPhysInfo() function inserts data only into the count and descriptors fields while writing zeros to all other fields. When using the KnIoDmaGetInfo() function, the descriptors array contains virtual memory page numbers if IOMMU is enabled, and it contains physical memory page numbers if IOMMU is not enabled. When using the KnIoDmaGetPhysInfo() function, the descriptors array contains physical memory page numbers regardless of whether or not IOMMU is enabled.

   The KnIoDmaContinuousGetDmaAddr() and KnIoDmaContinuousGetPhysAddr() functions can be used if the DMA buffer consists of one block. These functions let you get the block address. (The accepted block size should be the DMA buffer size that was defined when it was created.) The KnIoDmaContinuousGetDmaAddr() function uses the output parameter addr to pass the virtual address if IOMMU is enabled or the physical address if IOMMU is not enabled. The KnIoDmaContinuousGetPhysAddr() function uses the output parameter addr to pass the physical address, regardless of whether or not IOMMU is enabled.

   On Raspberry Pi 4 B, the KnIoDmaGetPhysInfo() function lets you get the actual physical page numbers, while the KnIoDmaGetInfo() function lets you get the offset physical page numbers because some devices use Visual Processing Unit (VPU) translation for DMA. Similarly, the KnIoDmaContinuousGetPhysAddr() and KnIoDmaContinuousGetDmaAddr() functions let you get the actual and offset physical address, respectively.

Closing access to the DMA buffer for a device

Access to the DMA buffer can be closed only if IOMMU is enabled. If you delete the kernel object that was created when the KnIoDmaBegin() or KnIoDmaBeginEx() function was called, device access to the DMA buffer will be closed. To delete this object, you must close its handle.

Deleting a DMA buffer

To delete a DMA buffer, complete the following steps:

1. Free the virtual memory regions that were reserved during KnIoDmaMap() function calls.

   To complete this step, you must close the handles that were received from KnIoDmaMap() function calls.

   This step must be completed for all processes whose memory is mapped to the DMA buffer.

2. Delete the kernel object that was created by the KnIoDmaBegin() or KnIoDmaBeginEx() function call.

   To complete this step, you must close the handle that was received when the KnIoDmaBegin() or KnIoDmaBeginEx() function was called.

3. Close or revoke each DMA buffer handle in all processes that own these handles.

Information about API functions

dma.h functions

Memory-mapped I/O (mmio.h)

The API is defined in the header file sysroot-*-kos/include/coresrv/io/mmio.h from the KasperskyOS SDK.

The API is intended for working with MMIO memory. MMIO memory consists of physical addresses that are mapped to registers and memory of devices. (Portions of one physical address space are used for physical memory addressing and access to registers and memory of devices.)

Information about API functions is provided in the table below.

Using the API

The standard scenario for API usage includes the following steps:

1. The MMIO memory region corresponding to the relevant device is registered.

   To complete this step, call the KnRegisterPhyMem() function.

   The handle of an MMIO memory region can be transferred to another process via IPC.

2. Mapping the MMIO memory region to the memory of a process.

   An MMIO memory region can only be mapped to one virtual memory region of only one process at one time. (However, an MMIO memory region may be mapped to the virtual memory of different processes that own the handle of this region at different times.) Mapping allows the process to receive read-and/or-write access to the MMIO memory region.

   To reserve a virtual memory region and map the MMIO memory region to it, call the KnIoMapMem() function.

   A handle received when calling the KnIoMapMem() function cannot be transferred to another process via IPC.

3. Reading data from the MMIO memory region and writing data to it via process memory.

   The 8-, 16- and 32-bit words that are read from the MMIO memory region or written to it are values of device registers or contents of device memory.

   To complete this step, use the IoReadMmReg8|16|32(), IoReadMmBuffer8|16|32(), IoWriteMmReg8|16|32(), and IoWriteMmBuffer8|16|32() functions.

Deregistering an MMIO memory region

To deregister an MMIO memory region, complete the following steps:

1. Free the virtual memory region that was allocated when the KnIoMapMem() function was called.

   To complete this step, call the KnHandleClose() function and specify the handle that was received when the KnIoMapMem() function was called. (The KnHandleClose() function is declared in the header file sysroot-*-kos/include/coresrv/handle/handle_api.h from the KasperskyOS SDK.)

2. Close or revoke each MMIO memory region handle in all processes that own these handles.

   To complete this step, use the KnHandleClose() and/or KnHandleRevoke() functions that are declared in the header file sysroot-*-kos/include/coresrv/handle/handle_api.h from the KasperskyOS SDK.

Information about API functions

mmio.h functions

Managing interrupt processing (irq.h)

The API is defined in the header file sysroot-*-kos/include/coresrv/io/irq.h from the KasperskyOS SDK.

The API manages the handling of hardware interrupts. A hardware interrupt is a signal sent from a device to direct the processor to immediately pause execution of the current program and instead handle an event related to this device. For example, pressing a key on the keyboard invokes a hardware interrupt that ensures the required response to this pressed key (for example, input of a character).

A hardware interrupt occurs when the device queries the interrupt controller. This query can be transmitted through a hardware interrupt line between the device and the interrupt controller or through MMIO memory. In the second case, the device writes to MMIO memory by calling the Message Signaled Interrupt (MSI).

Each hardware interrupt line corresponds to one interrupt with a unique number.

Information about API functions is provided in the table below.

Using the API

To attach an interrupt to its handler, complete the following steps:

1. Registering an interrupt by calling the KnRegisterIrq() function.

   One interrupt can be registered multiple times in one or more processes.

   The handle of an interrupt can be transferred to another process via IPC.

2. Attaching a thread to an interrupt by calling the KnIoAttachIrq() function.

   This step is performed by the thread in whose context the interrupt will be handled.

   When using the handle received from the KnRegisterIrq() function call, you can attach only one thread to an interrupt. To attach multiple threads in one or more processes to an interrupt, use different handles for this interrupt received from separate KnRegisterIrq() function calls. In this case, the KnIoAttachIrq() function must be called with the same flags in the flags parameter.

   A handle received when calling the KnIoAttachIrq() function cannot be transferred to another process via IPC.

To deny (mask) an interrupt, call the KnIoDisableIrq() function. To allow (unmask) an interrupt, call the KnIoEnableIrq() function. Even though these functions receive an interrupt handle that is used to attach only one thread to the interrupt, their action is applied to all threads that are attached to this interrupt. These functions must be called outside of the threads attached to the interrupt. After an interrupt is registered and a thread is attached to it, this interrupt does not require unmasking.

To initiate detachment of a thread from an interrupt, call the KnIoDetachIrq() function outside of the thread that is attached to the interrupt. Detachment is performed by the thread attached to the interrupt by calling the KnThreadDetachIrq() function declared in the header file sysroot-*-kos/include/coresrv/thread/thread_api.h from the KasperskyOS SDK.

Handling an interrupt

After attaching to an interrupt, a thread calls the Call() function declared in the header file sysroot-*-kos/include/coresrv/syscalls.h from the KasperskyOS SDK. The thread is locked as a result of this call. When an interrupt occurs or the KnIoDetachIrq() function is called, the KasperskyOS kernel sends an IPC message to the process that contains this thread. This IPC message contains a request to handle the interrupt or a request to detach the thread from the interrupt. When a process receives an IPC message, the Call() function in the thread attached to the interrupt returns control and provides the contents of the IPC message to the thread. The thread extracts the request from the IPC message and either processes the interrupt or detaches from the interrupt. If the interrupt is processed, information about its failure or success upon completion is added to the response IPC message that is sent to the kernel by the next Call() function call in the loop.

When processing an interrupt, use the IoGetIrqRequest() and IoSetIrqAnswer() functions that are declared in the header file sysroot-*-kos/include/io/io_irq.h from the KasperskyOS SDK. These functions let you extract data from IPC messages and add data to IPC messages for data exchange between the kernel and the thread attached to the interrupt.

The standard interrupt processing loop includes the following steps:

1. Adding information about the failure or success of interrupt processing to an IPC message by calling the IoSetIrqAnswer() function.
2. Sending the IPC message to the kernel and receiving an IPC message from the kernel.

   To complete this step, call the Call() functions. In the handle parameter, you must specify the handle that was received when the KnIoAttachIrq() function was called. You must use the msgOut parameter to define the IPC message that will be sent to the kernel, and use the msgIn parameter to define the IPC message that will be received from the kernel.

3. Extracting a request from the IPC message received from the kernel by calling the IoGetIrqRequest() function.
4. Processing the interrupt or detaching from the interrupt depending on the request.

   If the request requires detachment from the interrupt, exit the interrupt processing loop and call the KnThreadDetachIrq() function.

Deregistering an interrupt

To deregister an interrupt, complete the following steps:

1. Detach the thread from the interrupt.

   To complete this step, call the KnThreadDetachIrq() function.

2. Close the handle that was received when the KnIoAttachIrq() function was called.

   To complete this step, call the KnHandleClose() function. (The KnHandleClose() function is declared in the header file sysroot-*-kos/include/coresrv/handle/handle_api.h from the KasperskyOS SDK.)

3. Close or revoke each interrupt handle in all processes that own these handles.

   To complete this step, use the KnHandleClose() and/or KnHandleRevoke() functions that are declared in the header file sysroot-*-kos/include/coresrv/handle/handle_api.h from the KasperskyOS SDK.

One interrupt can be registered multiple times, but completion of these steps cancels only one registration. The other registrations will remain active. Each registration of one interrupt must be canceled separately.

Information about API functions

irq.h functions

Managing threads (high-level API thread.h)

The API is defined in the header file sysroot-*-kos/include/kos/thread.h from the KasperskyOS SDK.

Main capabilities of the API:

• Create, terminate, and lock threads.
• Resume execution of locked threads.
• Register functions that are called when creating and terminating threads.

Information about API functions is provided in the table below.

Creating threads

To create a thread, call the KosThreadCreate() or KosThreadCreateDetached() function. These functions create a standard thread with priority ranging from 0–15. (For details about standard threads, see Managing threads (low-level API thread_api.h)).

Terminating threads

When a thread is terminated, it is permanently deleted from the scheduler. A thread is terminated in the following cases:

• The function executed by the thread is exited.

  The root function (not a nested function) performed by the thread must be exited by the return operator.

• The KosThreadTerminate() or KosThreadExit() function is called.

  The KosThreadExit() function terminates the thread even if the function is called from a nested function instead of the root function executed by the thread.

• The process was terminated or switched to the "frozen" state.

  For details about the "frozen" state, see Managing processes (low-level API task_api.h).

Thread exit codes are defined by the developer of the KasperskyOS-based solution. These codes should be specified in the exitCode parameter of the KosThreadTerminate() and KosThreadExit() functions, and when calling the return operator in the function executed by the thread. To get the thread exit code, call the KosThreadWait() function. If successful, this function returns the thread exit code. Otherwise, it returns -1. Therefore, thread exit codes must differ from -1 to avoid ambiguity.

Registering functions that are called when creating and terminating threads

To register a function that is called when threads of a process are created and terminated, call the KosThreadCallbackRegister() function from this process.

The registered function is called in the following cases:

• A thread is created by calling the KosThreadCreate() function.
• The thread that was created by calling the KosThreadCreate() function is terminated as a result of exiting a function executed by this thread.
• The thread is terminated by calling the KosThreadExit() function.

You can register multiple functions, and each of them will be called when a thread is created and terminated. When a thread is created, the registered function is called with the KosThreadCallbackReasonCreate argument in the reason parameter. When the thread is terminated, the registered function is called with the KosThreadCallbackReasonDestroy argument in the reason parameter.

Guaranteeing that a function can only be called once

The callback function defined through the initRoutine parameter is called only when the KosThreadOnce() function is called for the first time. This does not occur on repeated calls of the KosThreadOnce() function (even from other threads), and the KosThreadOnce() function simply returns control. For example, this ensures that a driver is initialized only once when multiple software components use this driver and start its initialization irrespective of each other.

Special considerations for threads attached to interrupts

After a thread is attached to an interrupt, the thread becomes a real-time thread with a FIFO scheduler class and a priority higher than 31. (For details about attaching a thread to an interrupt, see Managing interrupt processing (irq.h). For details about the FIFO real-time thread scheduler class, see Managing threads (low-level API thread_api.h)).

Defining and getting the base address of the TLS for threads

A thread local storage (TLS) is process memory in which a thread can store data in isolation from other threads. The base address for TLS is defined and received by the KosThreadTlsSet() and KosThreadTlsGet() functions, respectively. These functions are intended for use by the libc library.

Getting the base address and stack limit of threads

The KosThreadGetStack() function gets the base address and stack limit of the thread. This function is intended for use by the libc library.

Freeing resources of terminated threads

Resources of a thread include its stack, context, and TCB (for details about a TCB, see Managing threads (low-level API thread_api.h)). To release thread resources after the thread terminates, call the KosThreadWait() function to wait for completion of the thread. (Exceptions to this case are the initial thread of a process and a thread created by the KosThreadCreateDetached() function.) Thread resources are also released upon termination of the process that includes these threads.

Information about API functions

thread.h functions

Managing threads (low-level API thread_api.h)

The API is defined in the header file sysroot-*-kos/include/coresrv/thread/thread_api.h from the KasperskyOS SDK.

Main capabilities of the API:

• Create, terminate, and lock threads.
• Resume execution of locked threads.
• Change the priorities and scheduler classes of threads.
• Handle exceptions.
• Detach threads from interrupts.
• Attach threads to processors (processor cores).

Information about API functions is provided in the table below.

Creating threads. Thread scheduler classes

To create a thread, call the KnThreadCreateByHandle() function. You can use the flags parameter of this function for the created thread to define the following scheduler classes:

• Class for scheduling standard threads.
• Class for scheduling FIFO real-time threads (First In, First Out).
• Class for scheduling RR real-time threads Round-Robin).

The priority of a standard thread can take values ranging from 0 to 15. The higher the priority of a standard thread, the larger the time slice allocated to this thread and the more frequently these time slices are allocated. One standard thread with a high priority can occupy multiple consecutive places in the thread queue. Standard threads cannot supersede other standard threads or real-time threads, regardless of their respective priorities. If a real-time thread appears in the queue, the current standard thread immediately transfers control to the real-time thread. If there are no real-time threads in the queue, the current standard thread transfers control to the next standard thread if the current one is terminated, becomes locked, uses up its time slice or gives it up to the next standard thread.

The priority of a real-time thread can take values ranging from 0 to 31. Higher-priority real-time threads supersede lower-priority real-time threads. Real-time threads also supersede standard threads, regardless of their respective priorities. Control is transferred from the current real-time thread to the next real-time thread in the queue in the following cases:

• The current real-time thread with a FIFO scheduler class is terminated or locked, or a real-time thread with a higher priority appears in the queue.

  Until the real-time thread with a FIFO scheduler class is terminated, locked, or superseded by a real-time thread with a higher priority, it can retain control indefinitely and not transfer control to the next real-time thread.

• The current real-time thread with an RR scheduler class is terminated, locked or uses up its time slice, or a real-time thread with a higher priority appears in the queue.

  A real-time thread with an RR scheduler class that is not terminated, locked, or superseded by a higher-priority real-time thread transfers control to the next one upon expiry of its time slice if the next one is a real-time thread with the same priority. Otherwise, it transfers control to itself again.

• The current real-time thread has given up its time slice to the next real-time thread with the same priority in the queue.

  A real-time thread can give up its time slice to the next one in the queue if the next one is a real-time thread with the same priority. Otherwise, it transfers control to itself again.

Execution of lower-priority real-time threads begins only after each of the real-time threads with a higher priority is terminated or locked. Real-time threads with the same priority form a queue based on the FIFO principle.

The thread scheduler class can be changed by calling the KnThreadSetSchedPolicyByHandle() function. This function also changes the size of the time slice allocated to a real-time thread with an RR scheduler class. This value is the only parameter of a real-time thread RR scheduler class that has a default value of 10 ms but can take values ranging from 2 ms to 100 ms. The scheduler class of standard threads and the scheduler class of FIFO real-time threads do not have parameters.

The priority of a thread can be changed by calling the KnThreadSetSchedPolicyByHandle() or KnThreadSetPriorityByHandle() function.

After a thread is attached to an interrupt, the thread becomes a real-time thread with a FIFO scheduler class and a priority higher than 31, irrespective of the specific scheduler class and priority this thread had before it was attached to the interrupt. Managing interrupt processing (irq.h).)

Creating thread handles

A thread handle is created whenever a thread is created by the KnThreadCreateByHandle() function call. A thread (including the initial thread) can also create its own handle by calling the KnThreadOpenCurrent() function.

A thread handle cannot be transferred to another process via IPC.

Handling exceptions

To register an exception handling function for a thread, call the KnThreadSetExceptionHandler() function. This function deregisters the previous exception handling function and returns its ID. By saving this ID, you can subsequently register the previous exception handling function again.

To get information about the last exception of a thread, call the KnThreadGetLastException() function in the exception handler.

Detaching threads from interrupts

To detach a thread from an interrupt, call the KnThreadDetachIrq() function. (For more details about using the KnThreadDetachIrq() function, see Managing interrupt processing (irq.h).)

After a thread is detached from an interrupt, the thread receives the scheduler class and priority that it had before it was attached to the interrupt.

Attaching threads to processors (processor cores)

To restrict the set of processors (processor cores) that can be used to execute a thread, define an affinity mask for this thread. An affinity mask is a bit mask indicating which specific processors or processor cores must execute the thread.

To create, adjust, and perform other operations with affinity masks, use the API that is defined in the header file sysroot-*-kos/include/rtl/cpuset.h from the KasperskyOS SDK.

To define a thread affinity mask, call the KnThreadSetAffinityByHandle() function.

Terminating threads

When a thread is terminated, it is permanently deleted from the scheduler. A thread is terminated in the following cases:

• The function executed by the thread is exited.

  The root function (not a nested function) performed by the thread must be exited by the return operator.

• The KnThreadTerminateByHandle() or KnThreadExit() function is called.

  The KnThreadExit() function terminates the thread even if the function is called from a nested function instead of the root function executed by the thread.

• The process was terminated or switched to the "frozen" state.

  For details about the "frozen" state, see Managing processes (low-level API task_api.h).

Thread exit codes are defined by the developer of the KasperskyOS-based solution. These codes should be specified in the code parameter of the KnThreadTerminateByHandle() and KnThreadExit() functions, and when calling the return operator in the function executed by the thread. To get the thread exit code, call the KnThreadWaitByHandle() function.

Getting the address of the TCB and defining the base address of a TLS for threads

A thread control block (TCB) is a structure containing thread information that is used by the kernel to manage this specific thread. The type of structure is defined in the header file sysroot-*-kos/include/thread/tcbpage.h from the KasperskyOS SDK. A TCB contains the base address of the thread local storage (TLS). The KnThreadGetTcb() function gets the TCB address. The KnThreadSetTls() function defines the base address of the TLS. These functions are intended for use by the libc library.

Getting thread information

The KnThreadGetInfoByHandle() function gets the base address and stack limit of the thread, and the thread identifier (TID). This function is intended for use by the libc library.

Freeing resources of terminated threads

Resources of a thread include its stack, context, and TCB. To free the resources of a thread after the thread is terminated, you need to close its handle before or after termination of this thread by calling the KnHandleClose() function, which is declared in the header file sysroot-*-kos/include/coresrv/handle/handle_api.h from the KasperskyOS SDK (an exception to this case is the initial thread of a process whose resources are freed without calling the KnHandleClose() function if the initial thread did not create its own handle by calling the KnThreadOpenCurrent() function). Resources of threads are also freed upon termination of the process that includes these threads.

Information about API functions

thread_api.h functions

Managing processes (high-level API task.h)

The API is defined in the header file sysroot-*-kos/include/kos/task.h from the KasperskyOS SDK.

The API lets you create, start and terminate processes, and statically create IPC channels and pass handles.

Information about API functions is provided in the table below.

Creating processes

To create a process, call one of the following functions:

• KosTaskInitEx()
• KosTaskInit()
• KosTaskInitFromSegEx()
• KosTaskInitFromSeg()
• KosTaskLaunch()

Using the params parameter, these functions receive parameters of the created process via a structure containing the following fields:

• eiid – pointer to the process class name.
• endpointsCount – number of provided endpoints.

  The field can have a zero value if the process does not provide endpoints.

• endpoints – pointer to the array of structures containing the characteristics of provided endpoints (names and RIIDs of endpoints, names of interfaces).

  The type of structure is defined in the header file sysroot-*-kos/include/services/handle/if_connection.h from the KasperskyOS SDK.

  The field can have the RTL_NULL value if the process does not provide endpoints.

• args – pointer to the array of program startup parameters.

  The RTL_NULL value must be the last element of the array.

• envs – pointer to the array of environment variables of the program.

  The RTL_NULL value must be the last element of the array.

• flags:
  • KOS_TASK_FLAGS_NONE – no flags.
  • KOS_TASK_FLAG_DUMPABLE – the process switches to the "frozen" state as a result of an unhandled exception.

    For details about the "frozen" state, see Managing processes (low-level API task_api.h).

• componentTree – pointer to the structure containing information from the formal specification of the solution component.

  The type of structure is defined in the header file sysroot-*-kos/include/nk/types.h from the KasperskyOS SDK. This structure is an element of automatically generated transport code.

  If the field has a value other than RTL_NULL, the values in the eiid, endpointsCount and endpoints fields will be ignored, and the process class name and parameters of the provided endpoints (including the parameters of endpoints of embedded components) will be taken from the formal specification of the solution component.

The KosTaskInitEx(), KosTaskInit(), KosTaskInitFromSegEx() and KosTaskInitFromSeg() functions use the outTask output parameter to pass the pointer to the address of the object describing the child process. This object is a structure that is created in the memory of the parent process and the child process. The developer of a KasperskyOS-based solution does not need to perform operations with the fields of this structure. However, the pointer to this structure must be used as the process ID when calling API functions. A child process can get the address of the object describing it by calling the KosTaskGetSelf() function.

If statically created IPC channels are used for access to endpoints provided by a server process, the object describing this server process must be linked to the structures containing information about endpoints from the formal specification of the solution component. This is necessary so that client processes can receive information about endpoints provided by the server process when creating a static IPC channel. To link an object describing a child server process to structures containing information about endpoints from the formal specification of the solution component, this information must be passed through the componentTree field of the params parameter when calling the KosTaskInit*() functions or KosTaskLaunch() function. A server process that is already running can link the object describing it to structures containing information about endpoints from the formal specification of the solution component by calling the KosTaskSetComponentTree() function. This is required if the running server process does not have a parent process.

When the KosTaskInitEx(), KosTaskInit() or KosTaskLaunch() function is called, the ELF image from the defined executable file in ROMFS is loaded into the memory of the created process. If the ELF image contains the symbol table .symtab and string table .strtab, they are loaded into process memory. Using these tables, the kernel receives the names of functions for generating stack backtrace data (call stack information).

To get information about the ELF image loaded into process memory, call the KosTaskGetElfSegs() function.

When the KosTaskInit() or KosTaskLaunch() function is called, one of the following values is used as the process name and executable file name:

• Value of the eiid field, if the value of the componentTree field is equal to RTL_NULL.
• Name of the process class from the formal specification of the solution component, if the componentTree field value is different from RTL_NULL.

Likewise, these values are applied as the process name and/or executable file name if you call the KosTaskInitEx() or KosTaskInitFromSegEx() function with the RTL_NULL value in the name parameter and/or the path parameter. These values are also applied as the process name if you call the KosTaskInitFromSeg() function with the RTL_NULL value in the name parameter.

To use the KosTaskInitFromSegEx() and KosTaskInitFromSeg() functions, MDL buffers containing the ELF image segments must be created in advance. You must use the segs parameter to define the ELF image segments to be loaded into the memory of the created process.

You must use the entry and relocBase parameters of the KosTaskInitFromSegEx() function to define the program entry point and the ELF image load offset, respectively. The program entry point is the sum of the address specified in the e_entry field of the ELF image header and the ELF image load offset. The KnElfCreateVmSegEx() function declared in the header file sysroot-*-kos/include/coresrv/elf/elf_api.h from the KasperskyOS SDK generates a random offset for loading the ELF image and calculates the address of the program entry point according to this offset. (The ELF image load offset must be a random value to ensure ASLR support. For details about ASLR, see Managing processes (low-level API task_api.h).)

You can use the KosTaskInitFromSegEx() function to load the symbol table .symtab, string table .strtab and ELF image header into the memory of the created process. The ELF image header should be loaded if data from this header must be available in the created process.

Data passed to the KosTaskInitFromSegEx() function via the segs, entry, and relocBase parameters and the parameters associated with loading the symbol table .symtab and string table .strtab are prepared by the KnElfCreateVmSegEx() function declared in the header file sysroot-*-kos/include/coresrv/elf/elf_api.h from the KasperskyOS SDK.

The KosTaskInitFromSeg() function is a simplified version of the KosTaskInitFromSegEx() function and does not let you load the symbol table .symtab, string table .strtab and ELF image header into process memory, and does not let you define the ELF image load offset (instead, it sets a null offset).

The KosTaskLaunch() function creates and immediately starts a process without the capability to statically create IPC channels.

Statically created IPC channels

Before starting processes, you can create IPC channels between them. You can create multiple IPC channels with different names between one client process and one server process. You can create IPC channels with the same name between one server process and multiple client processes.

To create an IPC channel with a name matching the name of a server process class, call the KosTaskConnect() function.

To create an IPC channel with a defined name, call the KosTaskConnectToService() function.

To use the created IPC channel, you need to get the client IPC handle on the client process side by calling the ServiceLocatorConnect() function. On the server process side, you need to get the server IPC handle by calling the ServiceLocatorRegister() function. These functions use the channelName parameter to receive the name of the IPC channel. (The ServiceLocatorConnect() and ServiceLocatorRegister() functions are declared in the header file sysroot-*-kos/include/coresrv/sl/sl_api.h from the KasperskyOS SDK.)

Transferring handles

A parent process can transfer one or more handles to a child process that is not yet running. (General information about transferring handles is provided in the Transferring handles section.)

To pass a handle to a child process, call the KosTaskTransferResource() function while specifying the handle of the resource transfer context object, the permissions mask, and the conditional name of the descendant of the transferred handle in addition to the other parameters.

To find the descendant of a handle transferred by a parent process, call the KosTaskLookupResource() function while specifying the conditional name of the descendant of the handle that was defined by the parent process when calling the KosTaskTransferResource() function.

Starting processes

To create and immediately start a process without statically creating IPC channels, call the KosTaskLaunch() function.

To start an already created process for which you can create the necessary IPC channels before starting this process, call the KosTaskRunEx() or KosTaskRun() function.

Use the fsBackend parameter of the KosTaskRunEx() function to specify whether to use the kernel or the system program fsusr to support the ROMFS file system for the started process. Use of the fsusr program ensures that the ROMFS image resides in the user space. The user space can host a significantly larger ROMFS image than the kernel space.

To enable the use of a ROMFS file system residing in the user space, include the fsusr program into the KasperskyOS-based solution and create an IPC channel named kl.core.FSUsr from the process that needs to use this file system to the process named kl.core.FSUsr. (The client portion of the fsusr program is included in the libkos library.) To check whether the fsusr program is included in your KasperskyOS SDK, verify that the sysroot-*-kos/bin/fsusr executable file is available.

To specify how to support the file system in an already running process, call the KosTaskSetSelfFSBackend() function. This function can be used as follows. The parent process indicates that the fsusr program supports its ROMFS file system, and loads the required ROMFS image by calling the KnFsChange() function. (The KnFsChange() function is declared in the header file sysroot-*-kos/include/coresrv/fs/fs_api.h from the KasperskyOS SDK.) Then the parent process starts the child process by calling the KosTaskRunEx() function and specifies that the ROMFS file system for the child process is supported by the fsusr program. As a result, the child process will use the ROMFS image that is placed in the user space by the parent process by default.

If the parent process does not need to terminate the child process or wait for its termination, the object describing the child process must be deleted and the counter for links to it must be reset by using the KosTaskPut() function after the child process is started. The KosTaskLaunch() function calls the KosTaskPut() function after the child process is started.

Terminating processes

The API terminates and waits for termination of child processes.

To terminate a child process, call the KosTaskStop() or KosTaskStopAndWait() function.

To wait for a child process to terminate on its own initiative, call the KosTaskWait() function.

To ensure that the kernel object describing a child process is deleted after this process is terminated, its handle in the parent process must be closed before or after termination of the child process. The handle of the child process is closed when the object describing the child process is deleted from the memory of the parent process. To delete an object describing a child process, reset the counter for links to this object by using the KosTaskPut() function. The KosTaskLaunch() function calls the KosTaskPut() function after the child process is started.

For details about terminating processes, see Managing processes (low-level API task_api.h).

Information about API functions

task.h functions

Managing processes (low-level API task_api.h)

The API is defined in the header file sysroot-*-kos/include/coresrv/task/task_api.h from the KasperskyOS SDK.

Main capabilities of the API:

• Create, start, and terminate processes.
• Handle exceptions.
• Get information about processes, including information about the reasons for their termination.
• Define priorities and scheduler classes for initial threads of processes.

Information about API functions is provided in the table below.

Creating and starting processes

To create a process, call the KnTaskCreate() or KnTaskCreateEx() function. These functions create an "empty" process, which is a process in whose memory the ELF image of the program is not loaded. Before starting this process, complete the following steps:

1. Create a seed value by calling the KosRandomGenerate() function, which is declared in the header file sysroot-*-kos/include/kos/random/random_api.h from the KasperskyOS SDK.

   This step is required for completion of the next step.

2. Define the seed value by calling the KnTaskReseedAslr() function.

   This step is required for address space layout randomization. Address Space Layout Randomization (ASLR) is the use of random addresses for the location of data structures (ELF image, dynamic libraries, stack and heap) in process memory to make it harder to exploit vulnerabilities associated with a conventional process address space structure that is known by a hacker in advance.

   The KnTaskReseedAslr() function defines the seed value of the random number generator that is used to automatically select the base address of an allocated virtual memory region in functions such as KnVmAllocate(), KnPmmMdlMap(), KnIoDmaMap(), and KnTaskVmReserve(). The stack and heap are created in the process and dynamic libraries are loaded into the process memory by the operating system using the KnVmAllocate() function. The addr parameter is set to zero so that the address of the allocated virtual memory region is selected automatically (as a random value).

3. Wipe the seed value created at step 1 from memory.

   This step is required for security purposes. To complete this step, use the RtlRandomMemSanitize() function, which is declared in the header file sysroot-*-kos/include/rtl/random.h from the KasperskyOS SDK.

4. Load ELF image segments into process memory by using the KnTaskLoadSeg() function.

   In the loadAddr field of the seg parameter, specify the load address of the ELF image segment. To ensure ASLR support (as a supplement to step 2), the load address of the ELF image segment specified in the ELF file must be increased by the ELF image load offset. The ELF image load offset must be a random value. The KnElfCreateVmSegEx() function declared in the header file sysroot-*-kos/include/coresrv/elf/elf_api.h from the KasperskyOS SDK generates the random offset for loading the ELF image and calculates the load addresses of ELF image segments according to this offset.

   As a result of this step, MDL buffers that contain ELF image segments will be mapped to virtual memory of the process.

5. [Optional] Load the symbol table .symtab and string table .strtab into process memory by calling the KnTaskLoadElfSyms() function.

   The load addresses of ELF image segments containing the symbol table .symtab and string table .strtab must be calculated just like the load addresses of other ELF image segments. This calculation is performed by the KnElfCreateVmSegEx() function declared in the header file sysroot-*-kos/include/coresrv/elf/elf_api.h from the KasperskyOS SDK.

   The kernel uses the symbol table .symtab and string table .strtab to get the names of functions for generating stack backtrace data (call stack information).

6. Define the program entry point and the ELF image load offset by calling the KnTaskSetInitialState() function.

   The program entry point is the sum of the address specified in the e_entry field of the ELF image header and the ELF image load offset. The KnElfCreateVmSegEx() function declared in the header file sysroot-*-kos/include/coresrv/elf/elf_api.h from the KasperskyOS SDK generates a random offset for loading the ELF image and calculates the address of the program entry point according to this offset.

7. [Optional] Load the ELF image header into process memory by calling the KnTaskSetElfHdr() function.

   This step must be completed if data from the ELF image header must be available in the created process.

The handle of a process can be transferred to another process via IPC.

By default, the initial thread of a process is a standard thread whose priority can take values ranging from 0 to 15. (For details about thread scheduler classes, see Managing threads (low-level API thread_api.h).) To change the scheduler class and/or priority of the initial thread of a process, call the KnTaskSetInitialPolicy() function. To change the priority of the initial thread of a process, call the KnTaskSetInitialThreadPriority() function. The KnTaskSetInitialPolicy() and KnTaskSetInitialThreadPriority() functions can be used after the program entry point is defined. These functions can also be used after starting the process.

To start the process, call the KnTaskResume() function. A running process cannot be stopped.

Before a process is started, it receives data from its parent process via a static connection page. A static connection page (SCP) is a set of structures containing data for statically creating IPC channels, startup parameters, and environment variables of a program. A parent process writes data to the SCP of a child process by calling the KnTaskSetEnv() function. When a child process is started, it reads data from the SCP by calling the KnTaskGetEnv() function, then it deletes the SCP by calling the KnTaskFreeEnv() function. All three functions do not need to be explicitly called because their calls are made by the libkos library.

Terminating processes

Process termination includes the following:

• Terminating all threads of the process.
• Freeing the memory of the process.
• Freeing system resources and user resources that are exclusively owned by the process.

  When a process is terminated, all the handles that it owns are closed. If a closed handle was the only handle of a resource, this resource is freed.

A process can be terminated for the following reasons:

• On its own initiative.

  The KnTaskExit() function is called, or all threads of the process are terminated.

• By external request.

  The KnTaskTerminate() function is called.

• As a result of an unhandled exception (crash).

  By calling the KnTaskPanic() function, a process can purposefully initiate an exception that cannot be handled and leads to the process terminating. This assures that the process can terminate itself. (For example, if the process contains threads attached to interrupts, the KnTaskExit() cannot terminate the process, while the KnTaskPanic() function can.)

The exit codes of processes are defined by the developer of the KasperskyOS-based solution. These codes must be specified in the status parameter of the KnTaskExit() function. If a process was terminated due to the termination of all its threads, the exit code of this process will be the exit code of its initial thread. To get the exit code of a process that was terminated on its own initiative, call the KnTaskGetExitCode() function.

To get information regarding the reason for process termination, call the KnTaskGetExitStatus() function. This function determines whether a process was terminated on its own initiative, by external request, or unexpectedly.

To get information about an unhandled exception that led to an unexpected termination of a process, call the KnTaskGetExceptionInfo() function. This information includes the exception code and the context of the thread in which this exception occurred.

If the process was created by calling the KnTaskCreateEx() function with the TaskExceptionFreezesTask flag in the flags parameter, an unhandled exception will cause this process to switch to a "frozen" state instead of terminating. When a process is switched to a "frozen" state, its threads are terminated as a result of the unhandled exception but its resources are not freed, which means that you can get information about this process. To get the context of a thread that is part of a frozen process, call the KnTaskGetThreadContext() function. To get information about the virtual memory region that belongs to a frozen process, call the KnTaskGetNextVmRegion() function. This information includes the base address and size of the virtual memory region, and the access rights to this virtual memory region. Before a process switches to the frozen state, stack backtrace data (call stack information) is printed for the thread in which the unhandled exception occurred. To terminate a frozen process, call the KnTaskTerminateAfterFreezing() function.

To ensure that the kernel object describing a process is deleted after this process is terminated, each of its handles must be closed or revoked in all processes that own these handles before or after termination of this process. To do so, use the KnHandleClose() and/or KnHandleRevoke() functions that are declared in the header file sysroot-*-kos/include/coresrv/handle/handle_api.h from the KasperskyOS SDK.

Handling exceptions

To register an exception handling function, call the KnTaskSetExceptionHandler() function. This function deregisters the previous exception handling function and returns its ID. By saving this ID, you can subsequently register the previous exception handling function again.

An exception handling function is called when an exception occurs in any process thread. If the exception is successfully handled, this function returns a value other than zero. Otherwise it returns zero. The input parameter of the exception handling function is a structure containing information about the exception. The type of this structure is defined in the header file sysroot-*-kos/include/thread/tcbpage.h from the KasperskyOS SDK.

If an exception handling function registered at the process level failed to successfully handle an exception, the exception handling function registered at the level of the thread in which the exception occurred will be called. (For details about handling exceptions at the thread level, see Managing threads (low-level API thread_api.h)).

Reserving memory in a child process

The API includes the KnTaskVmReserve() and KnTaskVmFree() functions, which reserve and free virtual memory regions, respectively, in a child process that does not yet have a defined program entry point. These functions comprise only a part of the functionality intended to increase control of the parent process over the virtual address space of a child process. This functionality is currently under development.

Getting the GSI address

Global system information (GSI) is a structure containing system information, such as the timer count since the kernel started, the timer counts per second, the number of processors (processor cores) in active state, and processor cache data. The type of structure is defined in the header file sysroot-*-kos/include/task/pcbpage.h from the KasperskyOS SDK. The KnTaskGetGsi() function gets the GSI address. This function is intended for use by the libc library.

Getting the PCB address

A process control block (PCB) is a structure containing process information that is used by the kernel to manage this process. The type of structure is defined in the header file sysroot-*-kos/include/task/pcbpage.h from the KasperskyOS SDK. The KnTaskGetPcb() function gets the PCB address. This function is intended for use by the libc library.

Information about API functions

task_api.h functions

Initializing IPC transport for interprocess communication and managing IPC request processing (transport-kos.h, transport-kos-dispatch.h)

APIs are defined in the header files transport-kos.h and transport-kos-dispatch.h from the KasperskyOS SDK that are located at the path sysroot-*-kos/include/coresrv/nk.

API capabilities:

• Initialize IPC transport on the client side and on the server side.

  IPC transport is an add-on that works on top of system calls for sending and receiving IPC messages and works separately with the constant part and arena of IPC messages. Transport code works on top of this add-on.

• Start the loop for processing IPC requests on the server side.
• Copy data to the IPC message arena.

Information about API functions is provided in the tables below.

This section contains API usage examples. In these examples, programs acting as servers have the following formal specification:

FsDriver.edl

Operations.cdl

FileIface.idl

Initializing IPC transport for interprocess communication

To initialize IPC transport for interaction with other processes, call the NkKosTransport_Init() or NkKosTransportSync_Init() function declared in the header file transport-kos.h.

Example use of the NkKosTransport_Init() function on the client side:

If a client needs to use several endpoints, the same number of proxy objects must be initialized. When initializing each proxy object, you need to specify the IPC transport that is associated through the client IPC handle with the relevant server. When initializing multiple proxy objects pertaining to the endpoints of one server, you can specify the same IPC transport that is associated with this server.

Example use of the NkKosTransport_Init() function on the server side:

If a server processes IPC requests received through multiple IPC channels, the following special considerations should be taken into account:

• If a listener handle is associated with all IPC channels, IPC interaction with all clients can use the same IPC transport associated with this listener handle.
• If IPC channels are associated with different listener handles, IPC interaction with each group of clients corresponding to the same listener handle must use a separate IPC transport associated with this listener handle. In this case, IPC requests can be processed in parallel threads if you are using a thread-safe implementation of endpoint methods.

The NkKosTransportSync_Init() function initializes IPC transport with support for interrupting the Call() and Recv() locking system calls. (For example, an interrupt of these calls may be required for correct termination of the process that is executing them.) To interrupt the Call() and Recv() system calls, use the API ipc_api.h.

The NkKosSetTransportTimeouts() function declared in the header file transport-kos.h defines the maximum lockout duration for Call() and Recv() system calls used for IPC transport.

Starting the IPC request processing loop

The IPC request processing loop on a server includes the following steps:

1. Receive an IPC request.
2. Process the IPC request.
3. Send an IPC response.

Each step of this loop can be completed separately by sequentially calling the nk_transport_recv(), dispatcher, and nk_transport_reply() functions. (The nk_transport_recv() and nk_transport_reply() functions are declared in the header file sysroot-*-kos/include/nk/transport.h from the KasperskyOS SDK.) You can also call the NkKosTransport_Dispatch(), NkKosDoDispatch() or NkKosDoDispatchEx() function in which this loop is completed in its entirety. (The NkKosTransport_Dispatch() function is declared in the header file transport-kos.h, and the NkKosDoDispatch() and NkKosDoDispatchEx() functions are declared in the header file transport-kos-dispatch.h.) Use of the NkKosDoDispatch() or NkKosDoDispatchEx() function is more convenient than the NkKosTransport_Dispatch() function because they require fewer preparatory operations (for example, you do not need to initialize IPC transport).

You can initialize the structure passed to the NkKosDoDispatch() or NkKosDoDispatchEx() function via the info parameter by using the macros defined in the header file transport-kos-dispatch.h. You can use the syncHandle parameter of the NkKosDoDispatchEx() function to interrupt the system call Recv(). You can use the cb parameter of the NkKosDoDispatchEx() function to define the callback functions that are called after completing the Recv() and Reply() system calls, and after exiting the IPC request processing loop (you do not need to define all functions). The callback function corresponding to the enterDispatchProcessing pointer is called immediately after the Recv() system call is completed. The callback function corresponding to the leaveDispatchProcessing pointer is called immediately after the Reply() system call is completed. The callback function corresponding to the stopDispatchLoop pointer is called immediately after exiting the IPC request processing loop. The callbackContext pointer is passed to each of these callback functions. These callback functions can be used to implement a thread pool, for example.

The NkKosTransport_Dispatch(), NkKosDoDispatch(), and NkKosDoDispatchEx() functions can be called from parallel threads if you are using a thread-safe implementation of endpoint methods.

Example use of the NkKosDoDispatch() function:

Example use of the NkKosTransport_Dispatch() function:

Copying data to the IPC message arena

To copy a string to the IPC message arena, call the NkKosCopyStringToArena() function declared in the header file transport-kos.h. This function reserves a segment of the arena and copies a string to this segment.

Example use of the NkKosCopyStringToArena() function:

Information about API functions

transport-kos.h functions

transport-kos-dispatch.h functions

Initializing IPC transport for querying the security module (transport-kos-security.h)

The API is defined in the header file sysroot-*-kos/include/coresrv/nk/transport-kos-security.h from the KasperskyOS SDK.

The API initializes IPC transport for querying the Kaspersky Security Module via the security interface. Transport code works on top of IPC transport.

Information about API functions is provided in the table below.

This section contains an API usage example. In this example, the program that queries the security module has the following formal specification:

Verifier.edl

Approve.idl

Fragment of the policy description in the example:

security.psl

Using the API

To initialize IPC transport for querying the security module, call the NkKosSecurityTransport_Init() function.

Example use of the NkKosSecurityTransport_Init() function:

If a process needs to use several security interfaces, the same number of proxy objects must be initialized by specifying the same IPC transport and the unique IDs of the security interfaces.

Information about API functions

transport-kos-security.h functions

Generating random numbers (random_api.h)

The API is defined in the header file sysroot-*-kos/include/kos/random/random_api.h from the KasperskyOS SDK.

The API generates random numbers and includes functions that can be used to ensure high entropy (high level of unpredictability) of the seed value of the random number generator. The start number of the random number generator (seed) determines the sequence of the generated random numbers. In other words, if the same seed value is set, the generator creates identical sequences of random numbers. (The entropy of these numbers is fully determined by the entropy of the seed value, which means that these numbers are not entirely random, but pseudorandom.)

The random number generator of one process does not depend on the random number generators of other processes.

Information about API functions is provided in the table below.

Using the API

To generate a sequence of random byte values, call the KosRandomGenerate() or KosRandomGenerateEx() function.

Example use of the KosRandomGenerate() function:

The KosRandomGenerateEx() function gets the quality level of the generated random values through the output parameter quality. The quality level can be high or low. High-quality random values are random values that are generated while fulfilling all of the following conditions:

1. When the seed value is changed, at least one entropy source is registered and data is successfully received from all registered entropy sources.

   To register the entropy source, call the KosRandomRegisterSrc() function. This function uses the callback parameter to receive the pointer to a callback function of the following type:

   typedef Retcode (*KosRandomSeedMethod)(void *context, rtl_size_t size, void *output);

   Using the context parameters, this callback function receives data with the specified size of bytes from the entropy source and writes this data to the output buffer. If the function returns rcOk, it is assumed that data was successfully received from the entropy source. An entropy source can be a digitalized signal of a sensor or a hardware-based random number generator, for example.

   To deregister an entropy source, call the KosRandomUnregisterSrc() function.

2. The random number generator is initialized if the quality level was low before changing the seed value while fulfilling condition 1.

   If the quality level is low, it cannot be changed to high without initializing the random number generator.

   To initialize a random number generator, call the KosRandomInitSeed() function. The entropy of data passed through the seed parameter must be guaranteed by the calling process.

3. The counter of random byte values that were generated after changing the seed value while fulfilling condition 1 does not exceed the system-defined limit.
4. The counter of time that has elapsed since changing the seed value while fulfilling condition 1 does not exceed the system-defined limit.

If at least one of these conditions is not fulfilled, the generated random values are deemed low-quality values.

When a process is started, the seed value is automatically defined by the system. Then the seed value is modified when doing the following:

• Generating a sequence of random values.

  Each successful call of the KosRandomGenerateEx() function with the size parameter greater than zero and each successful call of the KosRandomGenerate() function results in a change of the seed value of the random number generator, but not each seed change results in the receipt of data from registered entropy sources. The registered entropy sources are used only when condition 3 or 4 is not fulfilled. If at least one entropy source is registered, the time counter for the change in the seed value is reset. If data from at least one entropy source is successfully received, the counter of generated random byte values is also reset.

  The quality level may change from high to low.

• Initializing a random number generator.

  Each successful call of the KosRandomInitSeed() function changes the seed value by using the data that is passed through the seed parameter and received from registered entropy sources. If at least one registered entropy source is available, the counters for generated byte values and the time of a change in the seed value are reset. Otherwise, only the counter of generated random byte values is reset.

  The quality level may change from high to low, and vice versa.

• Registering an entropy source.

  Each successful call of the KosRandomRegisterSrc() function changes the seed value by using the data only from the registered entropy source. The counter of the generated random byte values is also reset.

  The quality level may not change.

A possible scenario for generating high-quality random values includes the following steps:

1. Register at least one source of entropy by calling the KosRandomRegisterSrc() function.
2. Generate a sequence of random values by calling the KosRandomGenerateEx() function.
3. Check the quality level of the random values.

   If the quality level is low, initialize the random number generator by calling the KosRandomInitSeed() function, and proceed to step 2.

   If the quality level is high, proceed to step 4.

4. Use random values.

To get the quality level without generating random values, call the KosRandomGenerateEx() function with the values 0 and RTL_NULL in the size and output parameters, respectively.

Information about API functions

random_api.h functions

Getting and changing time values (time_api.h)

The API is defined in the header file sysroot-*-kos/include/coresrv/time/time_api.h from the KasperskyOS SDK.

Main capabilities of the API:

• Get and modify the system time
• Get the monotonic time that has elapsed since the moment the KasperskyOS kernel was started
• Get the resolution of the sources of system time and monotonic time

Information about API functions is provided in the table below.

time_api.h functions

Using notifications (notice_api.h)

The API is defined in the sysroot-*-kos/include/coresrv/handle/notice_api.h header file from the KasperskyOS SDK.

The API can track events associated with (both system and user) resources, and inform other processes and threads about events involving user resources.

Information about API functions is provided in the table below.

Using the API

The notification mechanism uses an event mask. An event mask is a value whose bits are interpreted as events that should be tracked or that have already occurred. An event mask has a size of 32 bits and consists of a general part and a specialized part. The common part describes events that are not specific to any resources. The specialized part describes events that are specific to certain resources. Specialized part flags for system resources and common part flags are defined in the sysroot-*-kos/include/handle/event_descr.h header file from KasperskyOS SDK. (For example, the common part flag EVENT_OBJECT_DESTROYED signifies resource termination, and the specialized part flag EVENT_TASK_COMPLETED signifies process termination.) Specialized part flags for a user resource are defined by the resource provider with the help of the OBJECT_EVENT_SPEC() and OBJECT_EVENT_USER() macros, which are defined in the sysroot-*-kos/include/handle/event_descr.h header file from the KasperskyOS SDK. The resource provider must export the public header files describing the flags of the specialized part.

The standard scenario for receiving notifications about events associated with resources consists of the following steps:

1. Creating a notification receiver (KasperskyOS kernel object that collects notifications) by calling the KnNoticeCreate() function.

   The notification receiver ID is the pointer to the KosObject containing the handle of the notification receiver (for details about KosObjects, see Using KosObjects (objects.h)). Destruction of this object will cause the destruction of the notification receiver. If you need to create a copy of the notification receiver ID (for example, for use in another thread), you must increment the counter of links to the KosObject by calling the KosRefObject() function to ensure that this object exists while the created copy of the ID exists. If the copy of the notification receiver ID is no longer needed, you must decrement the counter of links to the KosObject by calling the KosPutObject() function to make sure that this object is destroyed if there are no other links.

2. Adding "resource—event mask" entries to the notification receiver to configure it to get notifications about events associated with relevant resources.

   To add a "resource—event mask" entry to the notification receiver, you need to call the KnNoticeSubscribeToObject() function. (The OCAP_HANDLE_GET_EVENT flag should be set in the handle permissions mask of the resource stated in the object parameter.) Several "resource—event mask" entries can be added for one resource, and the entry identifiers do not need to be unique. Tracked events for each "resource—event mask" entry should be defined with an event mask that may match one or several events.

   "Resource—event mask" entries added to the notification receiver can be fully or partially removed to prevent the receiver from getting notifications that match these entries. To remove all "resource—event mask" entries from the receiver, you need to call the KnNoticeDropAndWake() function. To remove from the receiver "resource—event mask" entries that refer to the same resource, you need to call the KnNoticeUnsubscribeFromObject() function. To remove from the receiver a "resource—event mask" entry with a specific identifier, you need to call the KnNoticeUnsubscribeFromEvent() function.

   "Resource—event mask" entries can be added to the notification receiver or removed from it throughout the entire lifetime of this notification receiver.

3. Extracting notifications from the receiver by using the KnNoticeGetEvent() or KnNoticeGetEventEx() function.

   You can set the waiting time for notifications to appear in the receiver when calling the KnNoticeGetEvent() or KnNoticeGetEventEx() function. Threads that are locked while waiting for notifications to appear in the receiver will resume when notifications appear, even if these notifications match "resource—event mask" entries that were added to the receiver during the waiting period.

   Threads that are locked while waiting for notifications to appear in the receiver will resume their execution and will not be locked upon subsequent calls of the KnNoticeGetEvent() or KnNoticeGetEventEx() function if all "resource—event mask" entries are removed from this receiver by calling the KnNoticeDropAndWake() function. If you add at least one "resource—event mask" entry to the notification receiver after calling the KnNoticeDropAndWake() function, threads that get notifications from that receiver will be locked again on KnNoticeGetEvent() or KnNoticeGetEventEx() function calls for the defined waiting time as long as there are no notifications. If all "resource—event mask" entries are removed from the notification receiver by using the KnNoticeUnsubscribeFromObject() and/or KnNoticeUnsubscribeFromEvent() function, threads waiting for notifications to appear in the receiver will not resume until the timeout elapses, and they will be locked during the waiting period upon subsequent calls of the KnNoticeGetEvent() or KnNoticeGetEventEx() function.

4. Terminate operations with the notification receiver by calling the KnNoticeRelease() function.

   The KnNoticeRelease() function removes all "resource—event mask" entries from the notification receiver and makes it impossible to add new ones. Threads that are locked while waiting for notifications to appear in the receiver will resume their execution and will not be locked upon subsequent calls of the KnNoticeGetEvent() or KnNoticeGetEventEx() function. In addition, the KnNoticeRelease() function decrements the counter of links to the KosObject containing the handle of the notification receiver. If there are no other links to this object, the notification receiver will be destroyed. Otherwise, the notification receiver will exist until all other links are deleted.

To notify other processes and/or threads about events associated with the user resource, you need to call the KnNoticeSetObjectEvent() function. Calling the function results in notifications appearing in receivers configured to get events defined with the evMask parameter and associated with the user resource defined with the object parameter. You cannot set flags of the general part of an event mask in the evMask parameter, because only the kernel can signal about events that match the general part of an event mask. If the process calling the KnNoticeSetObjectEvent() function created the user resource handle stated in the object parameter, you can set flags defined by the OBJECT_EVENT_SPEC() and OBJECT_EVENT_USER() macros in the evMask parameter. If the process calling the KnNoticeSetObjectEvent() function received the user resource handle stated in the object parameter from another process, you can set only those flags defined by the OBJECT_EVENT_USER() macro in the evMask parameter, while the permissions mask of the resulting handle must have a OCAP_HANDLE_SET_EVENT flag set.

Information about API functions

notice_api.h functions

Dynamically creating IPC channels (cm_api.h, ns_api.h)

APIs are defined in the following header files from the KasperskyOS SDK:

• sysroot-*-kos/include/coresrv/cm/cm_api.h
• sysroot-*-kos/include/coresrv/ns/ns_api.h

The APIs dynamically create IPC channels.

Information about API functions is provided in the tables below.

Using the API

To ensure that servers can notify clients about the endpoints that they provide, the solution should include a name server, which is provided by the NameServer system program (executable file sysroot-*-kos/bin/ns from the KasperskyOS SDK). IPC channels from clients and servers to a name server can be statically created (these IPC channels must be named kl.core.NameServer). If this is not done, attempts will be made to dynamically create these IPC channels whenever clients and servers call the NsCreate() function. A name server does not have to be included in a solution if the clients initially already have information about the names of servers and the endpoints provided by these servers.

The names of endpoints and interfaces should be defined according to the formal specifications of solution components. (For information about the qualified name of an endpoint, see Binding methods of security models to security events.) Instead of the qualified name of an endpoint, you can use any conditional name of this endpoint. The names of clients and servers are defined in the init description. You can also get a process name by calling the KnTaskGetName() function from the API task_api.h.

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

1. Connect to the name server by calling the NsCreate() function.
2. Publish the provided endpoints on the name server by using the NsPublishService() function.

   To unpublish an endpoint, call the NsUnPublishService() function.

3. Receive a client request to create an IPC channel by calling the KnCmListen() function.

   The KnCmListen() function gets the first request in the queue without deleting this request but instead putting it at the end of the queue. If there is only one request in the queue, multiple consecutive calls of the KnCmListen() function will provide the same result. A request is deleted from the queue when the KnCmAccept() or KnCmDrop() function is called.

4. You can accept a client request to create an IPC channel by calling the KnCmAccept() function.

   To decline a client request, call the KnCmDrop() function.

   A listener handle is created when the KnCmAccept() function is called with the INVALID_HANDLE value in the listener parameter. If a listener handle is specified, the created server IPC handle will provide the capability to receive IPC requests over all IPC channels associated with this listener handle. (The first IPC channel associated with the listener handle is created when the KnCmAccept() function is called with the INVALID_HANDLE value in the listener parameter. The second and subsequent IPC channels associated with the listener handle are created during the second and subsequent calls of the KnCmAccept() function specifying the handle that was obtained during the first call.) In the listener parameter of the KnCmAccept() function, you can specify the listener handle received using the KnHandleConnect(), KnHandleConnectEx() and KnHandleCreateListener() functions from the API handle_api.h, and the ServiceLocatorRegister() function declared in the header file sysroot-*-kos/include/coresrv/sl/sl_api.h from the KasperskyOS SDK. In the rsid parameter of the KnCmAccept() function, you must specify the endpoint ID (RIID), which is a constant in the automatically generated transport code (for example: FsDriver_operationsComp_fileOperations_iid).

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

1. Connect to the name server by calling the NsCreate() function.
2. Find the server providing the required endpoint by using the NsEnumServices() function.

   To get a full list of endpoints with a defined interface, call the function several times while incrementing the index until you receive the rcResourceNotFound error.

3. Fulfill the request to create an IPC channel with the necessary server by calling the KnCmConnect() function.

You can connect multiple clients and servers to the name server. Each client and server can create multiple connections to the name server. A server can unpublish an endpoint that was published by another server.

To delete a connection to the name server, call the NsDestroy() function.

Deleting dynamically created IPC channels

A dynamically created IPC channel will be deleted when its client IPC handle and server IPC handle are closed.

Information about API functions

ns_api.h functions

cm_api.h functions

Using synchronization primitives (event.h, mutex.h, rwlock.h, semaphore.h, condvar.h)

The libkos library provides APIs that enable use of the following synchronization primitives:

• Events (event.h)
• Mutexes (mutex.h)
• Read-write locks (rwlock.h)
• Semaphores (semaphore.h)
• Conditional variables (condvar.h)

The header files are located in the KasperskyOS SDK at sysroot-*-kos/include/kos.

The APIs are intended for synchronizing threads that belong to the same process.

Events

An event is a synchronization primitive that is used to notify one or more threads about the fulfillment of a condition required by these threads. The notified thread waits for the event to switch from a non-signaling state to a signaling state, and the notifying thread changes the state of this event.

The standard API usage scenario for working with events includes the following steps:

1. An event is initialized via the KosEventInit() function call.
2. The event is used by threads:
   • The notified threads wait for the event to switch from non-signaling state to signaling state via the KosEventWait() or KosEventWaitTimeout() function call.
   • The notifying threads change the state of the event via the KosEventSet() and KosEventReset() function calls.

Information about the API event functions is provided in the table below.

event.h functions

Mutexes

A mutex is a synchronization primitive that ensures mutually exclusive execution of critical sections (areas of code where resources shared between threads are queried). One thread captures the mutex and executes a critical section. Meanwhile, other threads wait for the mutex to be freed and attempt to capture this mutex to execute other critical sections. A mutex can be freed only by the specific thread that captured it. You can use a recursive mutex, which can be captured by the same thread multiple times.

The standard API usage scenario for working with mutexes includes the following steps:

1. A mutex is initialized via the KosMutexInit() or KosMutexInitEx() function call.
2. The mutex is used by threads:
   1. The mutex is captured via the KosMutexTryLock(), KosMutexLock() or KosMutexLockTimeout() function call.
   2. The mutex is freed via the KosMutexUnlock() function call.

Information about the API mutex functions is provided in the table below.

mutex.h functions

Read-write locks

A read-write lock is a synchronization primitive used to allow access to resources shared between threads: write access for one thread or read access for multiple threads at the same time.

The standard API usage scenario for working with read-write locks includes the following steps:

1. A read-write lock is initialized by the KosRWLockInit() function call.
2. The read-write lock is used by threads:
   1. The read-write lock is captured for write operations (via the KosRWLockWrite() or KosRWLockTryWrite() function call) or for read operations (via the KosRWLockRead() or KosRWLockTryRead() function call).
   2. The read-write lock is freed via the KosRWLockUnlock() function call.

Information about the API read-write lock functions is provided in the table below.

rwlock.h functions

Semaphores

A semaphore is a synchronization primitive that is based on a counter whose value can be atomically modified. The value of the counter normally reflects the number of available resources shared between threads. To execute a critical section, the thread waits until the counter value becomes greater than zero. If the counter value is greater than zero, it is decremented by one and the thread executes the critical section. After the critical section is executed, the thread signals the semaphore and the counter value is increased.

The standard API usage scenario for working with semaphores includes the following steps:

1. A semaphore is initialized via the KosSemaphoreInit() function call.
2. The semaphore is used by threads:
   1. They wait for the semaphore via the KosSemaphoreWait(), KosSemaphoreWaitTimeout() or KosSemaphoreTryWait() function call.
   2. The semaphore is signaled via the KosSemaphoreSignal() or KosSemaphoreSignalN() function call.
3. Deallocating semaphore resources by calling the KosSemaphoreDeinit() function.

Information about the API semaphore functions is provided in the table below.

semaphore.h functions

Conditional variables

A conditional variable is a synchronization primitive that is used to notify one or more threads about the fulfillment of a condition required by these threads. A conditional variable is used together with a mutex. The notifying and notified threads capture a mutex to execute critical sections. During execution of a critical section, the notified thread verifies that its required condition was fulfilled (for example, the data has been prepared by the notifying thread). If the condition is fulfilled, the notified thread executes the critical section and frees the mutex. If the condition is not fulfilled, the notified thread is locked at the conditional variable and waits for the condition to be fulfilled. When this happens, the mutex is automatically freed. During execution of a critical section, the notifying thread verifies fulfillment of the condition required by the notified thread. If the condition is fulfilled, the notifying thread signals this fulfillment through the conditional variable and frees the mutex. The notified thread that was locked and waiting for the fulfillment of its required condition resumes execution of the critical section while automatically capturing the mutex. After the critical section is executed, the notified thread frees the mutex.

The standard API usage scenario for working with conditional variables includes the following steps:

1. The conditional variable and mutex are initialized.

   To initialize a conditional variable, you need to call the KosCondvarInit() function.

2. The conditional variable and mutex are used by threads.

Use of a conditional variable and mutex by notified threads includes the following steps:

1. The mutex is captured.
2. Condition fulfillment is verified.
3. The KosCondvarWait() or KosCondvarWaitTimeout() function is called to wait for condition fulfillment.

   After the KosCondvarWait() or KosCondvarWaitTimeout() function is returned, you normally need to re-verify that the condition is fulfilled because another notified thread also received the signal and may have voided this condition again. (For example, another thread could have extracted the data prepared by the notifying thread). To do so, you need to use the following construct:

   while(<condition>) <call of KosCondvarWait() or KosCondvarWaitTimeout()>
4. The mutex is freed.

Use of a conditional variable and mutex by notifying threads includes the following steps:

1. The mutex is captured.
2. Condition fulfillment is verified.
3. Fulfillment of the condition is signaled via the KosCondvarSignal() or KosCondvarBroadcast() function call.
4. The mutex is freed.

Information about the API conditional variable functions is provided in the table below.

condvar.h functions