IPC and transport

Creating IPC channels

Overview: creating IPC channels

There are two methods for creating IPC channels: static and dynamic.

Static creation of IPC channels is simpler to implement because you can use the init description for this purpose.

Dynamic creation of IPC channels lets you change the topology of interaction between processes on the fly. This is necessary if it is unknown which specific server contains the endpoint required by the client. For example, you may not know which specific drive you will need to write data to.

Statically creating an IPC channel

The static method has the following distinguishing characteristics:

• The client and server are in the stopped state when the IPC channel is created.
• Creation of this channel is initiated by the parent process that starts the client and server (this is normally Einit).
• The created IPC channel cannot be deleted.
• To get the IPC handle and endpoint ID (riid) after the IPC channel is created, the client and server must use the endpoint locator interface (coresrv/sl/sl_api.h).

Dynamically creating an IPC channel

The dynamic method has the following distinguishing characteristics:

• The client and server are already running at the time of creating the IPC channel.
• Creation of the channel is initiated jointly by the client and server.
• The created IPC channel can be deleted.
• The client and server get the IPC handle and endpoint ID (riid) immediately after the IPC channel is successfully created.

Creating IPC channels using init.yaml

This section contains init descriptions that demonstrate the specific features of creating IPC channels. Examples of defining properties and arguments of processes via init descriptions are examined in a separate article.

The file containing an init description is usually named init.yaml, but it can have any name.

Connecting and starting a client process and server process

In the next example, two processes will be started: one process of the Client class and one process of the Server class. The names of the processes are not specified, so they will match the names of their respective process classes. The names of the executable files are not specified either, so they will also match the names of their respective classes. The processes will be connected by an IPC channel named server_connection.

init.yaml

Page top

Dynamically created IPC channels

A dynamically created IPC channel uses the following functions:

• Name Server interface
• Connection Manager interface

An IPC channel is dynamically created according to the following scenario:

1. The following processes are started: client, server, and name server.
2. The server connects to the name server by using the NsCreate() call and publishes the server name, interface name, and endpoint name by using the NsPublishService() call.
3. The client uses the NsCreate() call to connect to the name server and then uses the NsEnumServices() call to search for the server name and endpoint name based on the interface name.
4. The client uses the KnCmConnect() call to request access to the endpoint and passes the found server name and endpoint name as arguments.
5. The server calls the KnCmListen() function to check for requests to access the endpoint.
6. The server accepts the client request to access the endpoint by using the KnCmAccept() call and passes the client name and endpoint name received from the KnCmListen() call as arguments.

The server can use the NsUnPublishService() call to unpublish endpoints that were previously published on the name server.

The server can use the KnCmDrop() call to reject requests to access endpoints.

Using endpoints from KasperskyOS Community Edition

Adding an endpoint to a solution

To ensure that a Client program can use some specific functionality via the IPC mechanism, the following is required:

1. In KasperskyOS Community Edition, find the executable file (we'll call it Server) that implements the necessary functionality. (The term "functionality" used here refers to one or more endpoints that have their own IPC interfaces)
2. Inhclude the CMake package containing the Server file and its client library.
3. Add the Server executable file to the solution image.
4. Edit the init description so that when the solution starts, the Einit program starts a new server process from the Server executable file and connects it, using an IPC channel, to the process started from the Client file.

   You must indicate the correct name of the IPC channel so that the transport libraries can identify this channel and find its IPC handles. The correct name of the IPC channel normally matches the name of the server process class. VFS is an exception in this case.

5. Edit the PSL description to allow startup of the server process and IPC interaction between the client and the server.
6. In the source code of the Client program, include the server methods header file.
7. Link the Client program with the client library.

Example of adding a GPIO driver to a solution

KasperskyOS Community Edition includes a gpio_hw file that implements GPIO driver functionality.

The following commands connect the gpio CMake package:

.\CMakeLists.txt

The gpio_hw executable file is added to a solution image by using the gpio_HW_ENTITY variable, whose name can be found in the configuration file of the package at /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/lib/cmake/gpio/gpio-config.cmake:

einit\CMakeLists.txt

The following strings need to be added to the init description:

init.yaml.in

The following strings need to be added to the PSL description:

security.psl.in

In the code of the Client program, you need to include the header file in which the GPIO driver methods are declared:

client.c

Finally, you need to link the Client program with the GPIO client library:

client\CMakeLists.txt

Creating and using your own endpoints

Overview: IPC message structure

In KasperskyOS, all interactions between processes have statically defined types. The permissible structures of an IPC message are defined by the description of the interfaces of the process that receives the message (server).

A correct IPC message (request and response) contains a constant part and an arena.

Constant part of a message

The constant part of a message contains arguments of a fixed size, and the RIID and MID.

Fixed-size arguments can be arguments of any IDL types except the sequence type.

The RIID and MID identify the interface and method being called:

• The RIID (Runtime Implementation ID) is the number of the process endpoint being called, starting at zero.
• The MID (Method ID) is the number of the method within the interface that contains it, starting at zero.

The type of the constant part of the message is generated by the NK compiler based on the IDL description of the interface. A separate structure is generated for each interface method. Union types are also generated for storing any request to a process, component or interface. For more details, refer to Example generation of transport methods and types.

Arena

The arena is a buffer for storing variable-size arguments (sequence IDL type).

Message structure verification by the security module

Prior to calling message-related rules, the Kaspersky Security Module verifies that the sent message is correct. Requests and responses are both validated. If the message has an incorrect structure, it will be rejected without calling the security model methods associated with it.

Forming a message structure

KasperskyOS Community Edition includes the following tools that make it easier for the developer to create and package an IPC message:

• The transport-kos library for working with NkKosTransport.
• The NK compiler that lets you generate special methods and types.

Simple IPC message generation is demonstrated in the echo and ping examples (/opt/KasperskyOS-Community-Edition-<version>/examples/).

Finding an IPC handle

The client and server IPC handles must be found if there are no ready-to-use transport libraries for the utilized endpoint (for example, if you wrote your own endpoint). To independently work with IPC transport, you need to first initialize it by using the NkKosTransport_Init() method and pass the IPC handle of the utilized channel as the second argument.

For more details, see the echo and ping examples (/opt/KasperskyOS-Community-Edition-<version>/examples/)

Finding an IPC handle when statically creating a channel

When statically creating an IPC channel, both the client and server can find out their IPC handles immediately after startup by using the ServiceLocatorRegister() and ServiceLocatorConnect() methods and specifying the name of the created IPC channel.

For example, if the IPC channel is named server_connection, the following must be called on the client side:

The following must be called on the server side:

For more details, see the echo and ping examples (/opt/KasperskyOS-Community-Edition-<version>/examples/), and the header file /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include/coresrv/sl/sl_api.h.

Finding an IPC handle when dynamically creating a channel

Both the client and server receive their own IPC handles immediately after dynamic creation of an IPC channel is successful.

The client IPC handle is one of the output (out) arguments of the KnCmConnect() method. The server IPC handle is an output argument of the KnCmAccept() method. For more details, see the header file /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include/coresrv/cm/cm_api.h.

Finding an endpoint ID (riid)

The endpoint ID (riid) must be found on the client side if there are no ready-to-use transport libraries for the utilized endpoint (for example, if you wrote your own endpoint). To call methods of the server, you must first call the proxy object initialization method on the client side and pass the endpoint ID as the third argument. For example, for the Filesystem interface:

For more details, see the echo and ping examples (/opt/KasperskyOS-Community-Edition-<version>/examples/)

Finding a service ID when statically creating a channel

When statically creating an IPC channel, the client can find out the ID of the necessary endpoint by using the ServiceLocatorGetRiid() method and specifying the IPC channel handle and the fully qualified name of the endpoint. For example, if the OpsComp component instance contains the FS endpoint, the following must be called on the client side:

For more details, see the echo and ping examples (/opt/KasperskyOS-Community-Edition-<version>/examples/), and the header file /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include/coresrv/sl/sl_api.h.

Finding a service ID when dynamically creating a channel

The client receives the endpoint ID immediately after dynamic creation of an IPC channel is successful. The client IPC handle is one of the output (out) arguments of the KnCmConnect() method. For more details, see the header file /opt/KasperskyOS-Community-Edition-<version>/sysroot-aarch64-kos/include/coresrv/cm/cm_api.h.

Example generation of transport methods and types

When building a solution, the NK compiler uses the EDL, CDL and IDL descriptions to generate a set of special methods and types that simplify the creation, forwarding, receipt and processing of IPC messages.

As an example, we will examine the Server process class that provides the FS endpoint, which contains a single Open() method:

Server.edl

Operations.cdl

Filesystem.idl

These descriptions will be used to generate the files named Server.edl.h, Operations.cdl.h, and Filesystem.idl.h, which contain the following methods and types:

Methods and types that are common to the client and server

• Abstract interfaces containing the pointers to the implementations of the methods included in them.

  In our example, one abstract interface (Filesystem) will be generated:

  typedef struct Filesystem {

  const struct Filesystem_ops *ops;

  } Filesystem;

  typedef nk_err_t

  Filesystem_Open_fn(struct Filesystem *, const

  struct Filesystem_Open_req *,

  const struct nk_arena *,

  struct Filesystem_Open_res *,

  struct nk_arena *);

  typedef struct Filesystem_ops {

  Filesystem_Open_fn *Open;

  } Filesystem_ops;

• Set of interface methods.

  When calling an interface method, the corresponding values of the RIID and MID are automatically inserted into the request.

  In our example, a single Filesystem_Open interface method will be generated:

  nk_err_t Filesystem_Open(struct Filesystem *self,

  struct Filesystem_Open_req *req,

  const

  struct nk_arena *req_arena,

  struct Filesystem_Open_res *res,

  struct nk_arena *res_arena)

Methods and types used only on the client

• Types of proxy objects.

  A proxy object is used as an argument in an interface method. In our example, a single Filesystem_proxy proxy object type will be generated:

  typedef struct Filesystem_proxy {

  struct Filesystem base;

  struct nk_transport *transport;

  nk_iid_t iid;

  } Filesystem_proxy;

• Functions for initializing proxy objects.

  In our example, the single initializing function Filesystem_proxy_init will be generated:

  void Filesystem_proxy_init(struct Filesystem_proxy *self,

  struct nk_transport *transport,

  nk_iid_t iid)

• Types that define the structure of the constant part of a message for each specific method.

  In our example, two such types will be generated: Filesystem_Open_req (for a request) and Filesystem_Open_res (for a response).

  typedef struct __nk_packed Filesystem_Open_req {

  __nk_alignas(8)

  struct nk_message base_;

  __nk_alignas(4) nk_ptr_t name;

  } Filesystem_Open_req;

  typedef struct Filesystem_Open_res {

  union {

  struct {

  __nk_alignas(8)

  struct nk_message base_;

  __nk_alignas(4) nk_uint32_t h;

  };

  struct {

  __nk_alignas(8)

  struct nk_message base_;

  __nk_alignas(4) nk_uint32_t h;

  } res_;

  struct Filesystem_Open_err err_;

  };

  } Filesystem_Open_res;

Methods and types used only on the server

• Type containing all endpoints of a component, and the initializing function. (For each server component.)

  If there are embedded components, this type also contains their instances, and the initializing function takes their corresponding initialized structures. Therefore, if embedded components are present, their initialization must begin with the most deeply embedded component.

  In our example, the Operations_component structure and Operations_component_init function will be generated:

  typedef struct Operations_component {

  struct Filesystem *FS;

  };

  void Operations_component_init(struct Operations_component *self,

  struct Filesystem *FS)

• Type containing all endpoints provided directly by the server; all instances of components included in the server; and the initializing function.

  In our example, the Server_entity structure and Server_entity_init function will be generated:

  #define Server_entity Server_component

  typedef struct Server_component {

  struct : Operations_component *OpsComp;

  } Server_component;

  void Server_entity_init(struct Server_entity *self,

  struct Operations_component *OpsComp)

• Types that define the structure of the constant part of a message for any method of a specific interface.

  In our example, two such types will be generated: Filesystem_req (for a request) and Filesystem_res (for a response).

  typedef union Filesystem_req {

  struct nk_message base_;

  struct Filesystem_Open_req Open;

  };

  typedef union Filesystem_res {

  struct nk_message base_;

  struct Filesystem_Open_res Open;

  };

• Types that define the structure of the constant part of a message for any method of any endpoint of a specific component.

  If embedded components are present, these types also contain structures of the constant part of a message for any method of any endpoint included in all embedded components.

  In our example, two such types will be generated: Operations_component_req (for a request) and Operations_component_res (for a response).

  typedef union Operations_component_req {

  struct nk_message base_;

  Filesystem_req FS;

  } Operations_component_req;

  typedef union Operations_component_res {

  struct nk_message base_;

  Filesystem_res FS;

  } Operations_component_res;

• Types that define the structure of the constant part of a message for any method of any endpoint of a specific component whose instance is included in the server.

  If embedded components are present, these types also contain structures of the constant part of a message for any method of any endpoint included in all embedded components.

  In our example, two such types will be generated: Server_entity_req (for a request) and Server_entity_res (for a response).

  #define Server_entity_req Server_component_req

  typedef union Server_component_req {

  struct nk_message base_;

  Filesystem_req OpsComp_FS;

  } Server_component_req;

  #define Server_entity_res Server_component_res

  typedef union Server_component_res {

  struct nk_message base_;

  Filesystem_res OpsComp_FS;

  } Server_component_res;

• Dispatch methods (dispatchers) for a separate interface, component, or process class.

  Dispatchers analyze the received query (the RIID and MID values), call the implementation of the corresponding method, and then save the response in the buffer. In our example, three dispatchers will be generated: Filesystem_interface_dispatch, Operations_component_dispatch, and Server_entity_dispatch.

  The process class dispatcher handles the request and calls the methods implemented by this class. If the request contains an incorrect RIID (for example, an RIID for a different endpoint that this process class does not have) or an incorrect MID, the dispatcher returns NK_EOK or NK_ENOENT.

  nk_err_t Server_entity_dispatch(struct Server_entity *self,

  const

  struct nk_message *req,

  const

  struct nk_arena *req_arena,

  struct nk_message *res,

  struct nk_arena *res_arena)

  In special cases, you can use dispatchers of the interface and the component. They take an additional argument: interface implementation ID (nk_iid_t). The request will be handled only if the passed argument and RIID from the request match, and if the MID is correct. Otherwise, the dispatchers return NK_EOK or NK_ENOENT.

  nk_err_t Operations_component_dispatch(struct Operations_component *self,

  nk_iid_t iidOffset,

  const

  struct nk_message *req,

  const

  struct nk_arena *req_arena,

  struct nk_message *res,

  struct nk_arena *res_arena)

  nk_err_t Filesystem_interface_dispatch(struct Filesystem *impl,

  nk_iid_t iid,

  const

  struct nk_message *req,

  const

  struct nk_arena *req_arena,

  struct nk_message *res,

  struct nk_arena *res_arena)