IPC and transport

IPC implementation

IPC basics in KasperskyOS

In KasperskyOS, the only means of interprocess communication (IPC) is exchange of messages.

Types of messages and roles of entities

Messaging in KasperskyOS is built on a client-server model.

When two entities interact, one of them is the client (client entity), and the other is the server (server entity). The client initiates the interaction by sending a request message (or simply "request"). The server receives the request and responds by sending a response message (or simply "response") to the client.

IPC channels

To enable two entities to exchange messages, an IPC channel, also referred to as "channel" or "connection", must be established between them. Each entity can have multiple connections, acting as a client for some entities while acting as a server for others.

System calls

KasperskyOS provides three system calls for IPC message exchange: Call, Recv and Reply. The corresponding functions are declared in the syscalls.h file:

• Call() is used by the client to send a request and receive a response. It receives an IPC handle, buffer containing the request, and buffer for the response.
• Recv() is used by the server to receive a request. It receives an IPC handle and buffer for the request.
• Reply() is used by the server to send a response. It receives an IPC handle and buffer for the response.

The Call() and Recv() system calls are locking calls, meaning that messages are exchanged according to the rendezvous principle:

• The server thread that executes the Recv() call remains locked until a request is received.
• The client thread that executes the Call() call remains locked until a response is received from the server.

IPC channels

IPC channels connect entities with each other and are used for IPC messaging.

The channel is provided by a pair of IPC handles (client and server), which are linked to each other.

Two entities linked by an IPC channel

A channel is directional. The entity associated with the client handle of the channel (client entity) can send requests and receive responses over this channel. The entity associated with the server handle of the channel (server entity) can receive requests and send responses over this channel.

An entity can have multiple connections (channels) with other entities, acting as a client in some connections while acting as a server in others.

Entity A is a client for the C entity and a server for the B entity. Designations: cl_1, cl_2 – client IPC handles; srv_1, srv_2 – server IPC handles.

Creating and using channels

IPC channels can be created statically or dynamically.

Statically created IPC channels are created by the Einit entity when the solution is started. The code of the Einit entity is generated based on the init description that specifies all channels (connections) that need to be created.

In addition to statically created IPC channels, entities may use dynamically created IPC channels.

To send and receive an IPC message over a specific channel, the corresponding values of IPC handles (client and server) must be known. Service Locator is used to obtain the values of IPC handles.

Dynamically created IPC channels

The capability to dynamically create IPC channels allows you to change the topology of interaction between entities on the fly. This is necessary if it is unknown which specific server entity will become the resource provider required by a client entity. For example, you may not know which specific drive you will need to write data to.

In contrast to a statically created IPC channel, a dynamically created IPC channel has the following characteristics:

• It is created between entities that have been started.
• It is created jointly by the client entity and server entity.
• It can be deleted.
• It involves the use of a name server (kl.core.NameServer entity), which facilitates the transfer of information about available interface implementations from server entities to client entities.

A dynamically created IPC channel uses the following functions:

• Name Server interface
• Connection Manager

The Name Server interface is provided for the user in the following files:

• coresrv/ns/ns_api.h is a header file of the libkos library;
• coresrv/ns/NameServer.idl is an IDL description of the IPC interface of the Name Server.

The Connection Manager is provided for the user in the following files:

• coresrv/cm/cm_api.h is a header file of the libkos library;
• services/cm/CM.idl is an IDL description of the Connection Manager's IPC interface.

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

1. A client entity, server entity and name server are started.
2. The server entity connects to the name server by using the NsCreate() function and publishes the server entity name, interface name, and interface implementation name by using the NsPublishService() function.
3. The client entity uses the NsCreate() function to connect to the name server and then uses the NsEnumServices() function to search for the name of the server entity and the name of the interface implementation based on the interface name.
4. The client entity uses the KnCmConnect() function to request access to the interface implementation and passes the found server entity name and interface implementation name as arguments to the function.
5. The server entity calls the KnCmListen() function to check if the client entity sent a request to access the provided interface implementation.
6. The server entity accepts the request to access the provided interface implementation by using the KnCmAccept() function, to which it passes the client entity name and interface implementation name received from the KnCmListen() function as arguments.

The server entity can use the NsUnPublishService() function to unpublish interface implementations that were previously published on the name server.

The server entity can use the KnCmDrop() function to reject requests to access interface implementations.

The listener handle is a server IPC handle with expanded rights. It is created when the KnCmAccept() function is called with the INVALID_HANDLE argument in the listener parameter. If a listener handle is passed to the KnCmAccept() function when it is called, the created server IPC handle will provide the capability to receive 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 argument 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, to which the listener handle obtained during the first call is passed.)

If the dynamically created IPC channel is no longer required, its client and server handles should be deleted. The IPC channel can be created again if necessary.

Messaging overview

Let us examine two entities (client and server) that have an IPC channel established between them. Let cl be the client IPC handle of this channel while sr is the server IPC handle of this channel.

Client entity code:

Server entity code:

Messages are exchanged as follows:

1. One of the client threads executes the Call() system call, passing as arguments the cl handle (client handle of the utilized channel), the pointer to the buffer containing the request message, and the pointer to the buffer for the response.
2. The request message is sent to Kaspersky Security System to be checked. If Kaspersky Security System returns an "allowed" decision, we proceed to step 3. Otherwise, the Call() is terminated with the rcSecurityDisallow error code, and we proceed to step 9.
3. If the server is waiting for a request from this client—i.e. the server has executed the Recv() call, passing sr as the first argument—we proceed to step 4. Otherwise, the client thread remains locked until one of the server threads executes a Recv() system call with the first sr argument.
4. The request message is copied to the address space of the server. The server thread is unlocked, and the Recv() call is terminated with an rcOk code.
5. The server processes the received message. The client thread remains locked.
6. The server executes the Reply() system call, passing as arguments the sr handle and the pointer to the buffer with the response message.
7. The response message is sent to Kaspersky Security System to be checked. If Kaspersky Security System returns an "allowed" decision, we proceed to step 8. Otherwise, the Call() and Reply() calls are terminated with an rcSecurityDisallow error code (see step 3).
8. The response message is copied to the address space of the client. The server thread is unlocked, and the Reply() call is terminated with an rcOk code. The client thread is unlocked, and the Call() is terminated with an rcOk code.
9. The exchange is complete.

If an error occurs when sending the request (insufficient memory, invalid message format, etc.), the threads are unlocked and the Call() and Reply() calls return an error code.

Service Locator

Service Locator is a small library that lets you:

• find out the value of an IPC handle based on the connection name;
• find out the value of the interface ID (RIID) based on the name of the interface implementation.

To use Service Locator, you need to include the sl_api.h file in the entity code:

Main functions of Service Locator

Client-side functions:

• ServiceLocatorConnect() receives the connection name and returns the client IPC handle corresponding to this connection (channel).
• ServiceLocatorGetRiid() receives the IPC handle and interface implementation name in the format <component instance name>.<interface implementation name>. Returns a corresponding RIID (sequence number of the interface implementation).

The connection name is specified in the init.yaml file, the component instance name is specified in the EDL file, and the interface implementation name is specified in the CDL file.

Server-side functions:

• ServiceLocatorRegister() receives the connection name and returns the server IPC handle corresponding to this connection (channel). If the channel is part of a group, the function returns the listener handle of this group.

Example use of Service Locator

Examine the next solution consisting of two entities: Client and Server.

The client entity does not implement any interface.

The server entity contains an instance of the Ping component. Instance name: ping_comp.

The Ping component contains a named implementation of the Ping interface declared in the Ping.idl file. Implementation name: ping_impl.

(For brevity, the Ping.idl file is not provided.)

In the init description, we indicate that the Client and Server entities must be connected through a channel named server_connection:

Use of Service Locator on the client side:

Use Service Locator on the server side:

Channel groups

The channels in which an entity serves as a server may be combined into one or more groups.

Each group of channels has its own listener handle.

Two IPC channels have the same name, "second_connection_to_A", and are combined into a group. Another channel, named "first_connection_to_A", is not included in this group. Designations: cl_1, cl_2, cl_3 – client IPC handles; srv_1 – server IPC handle; ls_1 – listener IPC handle.

Creating a group of channels using an init description

For channels to form a group, they must connect to the same server entity and have identical names. For example, to produce the system of channels depicted above, the following init description can be used:

Messaging within a channel group

Let us look at how messages are exchanged for the group of channels described above.

The client entities B and C receive a client handle value based on the name of the first_connection_to_A connection and send a request:

Server entity A receives the listener handle value ls_1. Entity A awaits requests over two channels at the same time (from B and from C), using the ls_1 handle. After receiving and processing the request, entity A sends a response using the ls_1 handle. The response will be sent to the client that initiated the request:

Transport

IPC message structure

In KasperskyOS, all interactions between entities have statically defined types. The permissible structures of an IPC message are defined in the IDL description of the interfaces of the entity 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 entity interface implementation being called, starting at zero.
• The MID (Method ID) is the number of the method within the interface that contains it, starting at zero.

For example, for the Ping method of the Ping interface (the Ping component of the Server entity in the echo example), the NK compiler will create the Ping_Ping_req type for the constant part of the request and the Ping_Ping_res type for the constant part of the response. The following union types will also be generated:

• Ping_req and Ping_res are constant parts of the request and response for any method of the Ping interface.
• Ping_component_req and Ping_component_res are constant parts of the request and response for any method of any interface whose implementation is included in the Ping component.

  If embedded components are present, these types also contain structures of the constant part of a message for any method of any interface whose implementations are included in all embedded components. For more details, refer to Generated methods and types.

• Server_entity_req and Server_entity_res are the constant parts of the request and response for any method of any interface whose implementation is included in any component whose instance is included in the Server entity.

Arena

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

Validating a message in Kaspersky Security System

The Kaspersky Security Module verifies that the structure of the message being sent 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.

NkKosTransport

NkKosTransport is a convenient wrapper for the Call, Recv and Reply system calls. It lets you work separately with messages' constant parts and arenas.

The NkKosTransport structure and methods for working with it are declared in the transport-kos.h file.

To initialize the transport, it is sufficient to call the NkKosTransport_Init() function by specifying the IPC handle of the channel that should be used to transmit messages (handle):

The functions nk_transport_call(), nk_transport_recv() and nk_transport_reply() declared in transport.h (included in the transport-kos.h file) are used to call the transport.

The nk_transport_call() function is intended for sending a request and receiving a response:

The nk_transport_recv() function is intended for receiving a request:

The nk_transport_reply() function is intended for sending a response:

Page top

Generated 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.

Examine the static description of the Server entity from the echo example. This description consists of three files: Server.edl, Ping.cdl and Ping.idl:

These files will be used to generate the files named Server.edl.h, Ping.cdl.h, and Ping.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 (Ping) will be generated:

  struct Ping_ops {

  nk_err_t (*Ping)(struct Ping *,

  const struct Ping_req *,

  const struct nk_arena *,

  struct Ping_res *,

  struct nk_arena *); };

  struct Ping {

  const struct Ping_ops *ops;

  };

• Set of interface methods.

  When calling an interface method, corresponding values of the RIID and MID are automatically inserted into the request, after which the nk_transport_call() function is called.

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

  nk_err_t Ping_Ping(struct Ping *,

  const struct Ping_Ping_req *,

  const struct nk_arena *,

  struct Ping_Ping_res *,

  struct nk_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 Ping_proxy proxy object type will be generated:

  struct Ping_proxy {

  struct Ping base;

  struct nk_transport *transport;

  nk_iid_t iid;

  };

• Functions for initializing proxy objects.

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

  void Ping_proxy_init(struct Ping_proxy *, struct nk_transport *, nk_iid_t);

• 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: Ping_Ping_req (for a request) and Ping_Ping_res (for a response).

  struct Ping_Ping_req {

  struct nk_message base_;

  nk_uint32_t value;

  };

  struct Ping_Ping_res {

  struct nk_message base_;

  nk_uint32_t result;

  };

Methods and types used only on the server

• Type containing implementations of all component interfaces, 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 Ping_component structure and Ping_component_init function will be generated:

  struct Ping_component {

  struct Ping *pingImpl;

  };

  void Ping_component_init(struct Ping_component *, struct Ping *);

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

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

  struct Server_entity {

  struct Ping_component *pingComp;

  };

  void Server_entity_init(struct Server_entity *, struct Ping_component *);

• 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: Ping_req (for a request) and Ping_res (for a response).

  union Ping_req {

  struct nk_message base_;

  struct Ping_Ping_req Ping;

  };

  union Ping_res {

  struct nk_message base_;

  struct Ping_Ping_res Ping;

  };

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

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

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

  union Ping_component_req {

  struct nk_message base_;

  union Ping_req pingImpl;

  };

  union Ping_component_res {

  struct nk_message base_;

  union Ping_res pingImpl;

  };

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

  If embedded components are present, these types also contain structures of the constant part of a message for any method of any interface whose implementations are 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).

  union Server_entity_req {

  struct nk_message base_;

  union Ping_req pingComp_pingImpl;

  };

  union Server_entity_res {

  struct nk_message base_;

  union Ping_res pingComp_pingImpl;

  };

• Dispatch methods (dispatchers) for a separate interface, component, or the entity.

  Dispatchers analyze the received request (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: Ping_dispatch, Ping_component_dispatch, and Server_entity_dispatch.

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

  nk_err_t Server_entity_dispatch(struct Server_entity *,

  const union Server_entity_req *,

  const struct nk_arena *,

  union Server_entity_res *,

  struct nk_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 Ping_dispatch(struct Ping *,

  nk_iid_t,

  const union Ping_req *,

  const struct nk_arena *,

  union Ping_res *,

  struct nk_arena *);

  nk_err_t Ping_component_dispatch(struct Ping_component *,

  nk_iid_t,

  const union Ping_component_req *,

  const struct nk_arena *,

  union Ping_component_res *,

  struct nk_arena *);