IDL descriptions are placed into separate *.idl files and contain declarations in the Interface Definition Language (IDL):
package <package name>
import <package name>
interface {
<interface method name([parameters])>;
[...]
}
Each method signature is indicated in a separate line. The method name must not contain any underscores _. Each method in the list has a unique name. The parameters of methods are divided into input parameters (in), output parameters (out), and parameters for transmitting error information (error). The order of parameters in the description is important: first input parameters, then output parameters, then error parameters. Methods of the security interface cannot have output parameters and error parameters.
Input parameters and output parameters are transmitted in IPC requests and IPC responses, respectively. Error parameters are transmitted in IPC responses if the server cannot correctly handle the corresponding IPC requests.
The server can inform a client about IPC request processing errors via error parameters as well as through output parameters of interface methods. If the server sets the error flag in an IPC response when an error occurs, this IPC response will contain the error parameters without any output parameters. Otherwise this IPC response will contain output parameters just like when requests are correctly processed. (The error flag is set in IPC responses by using the nk_err_reset() macro defined in the nk/types.h header file from the KasperskyOS SDK.)
An IPC response sent with the error flag set and an IPC response with the error flag not set are considered to be different types of events for the Kaspersky Security Module. When describing a solution security policy, this difference lets you conveniently distinguish between the processing of events associated with the correct execution of IPC requests and the processing of events associated with incorrect execution of IPC requests. If the server does not set the error flag in IPC responses, the security module must check the values of output parameters indicating errors to properly process events related to the incorrect execution of IPC requests. (A client can check the state of the error flag in an IPC response even if the corresponding interface method does not contain error parameters. To do so, the client uses the nk_msg_check_err() macro defined in the nk/types.h header file from the KasperskyOS SDK.)
Signatures of interface methods cannot be imported from other IDL files.
The IDL language is case sensitive.
Single-line comments and multi-line comments can be used in an IDL description.
At least one optional declaration is used in a IDL description. If an IDL description does not use at least one optional declaration, this description will correspond to an "empty" package that does not assign any interface methods or data types (including from other IDL descriptions).
Some IDL files from the KasperskyOS SDK do not describe interface methods, but instead only contain definitions of data types. These IDL files are used only as exporters of data types.
If a package contains a description of interface methods, the interface name matches the package name.
Examples of IDL files
Env.idl
package kl.Env
// Definitions of data types for interface method parameters
typedef string<128> Name;
typedef string<256> Arg;
typedef sequence<Arg,256> Args;
// Interface includes one method.
interface {
Read(in Name name, out Args args, out Args envs);
}
Kpm.idl
package kl.Kpm
// Import data types for parameters of interface methods
import kl.core.Types
// Definition of data type for parameters of interface methods
typedef string<64> String;
/* Interface includes multiple methods.
* Some methods do not have any parameters. */
interface {
Shutdown();
Reboot();
PowerButtonPressedWait();
TerminationSignalWait(in UInt32 entityId, in String entityName);
EntityTerminated(in UInt32 entityId);
Terminate(in UInt32 callingEntityId);
}
MessageBusSubs.idl
package kl.MessageBusSubs
// Import data types for interface method parameters
import kl.MessageBusTypes
/* Interface includes a method that has
* input and output parameters, and
* an error parameter.*/
interface {
Wait(in ClientId id,
out Message topic,
out BundleId dataId,
error ResultCode result);
}
WaylandTypes.idl
// Package contains only definitions of data types.
package kl.WaylandTypes
typedef UInt32 ClientId;
typedef bytes<8192> Buffer;
typedef string<4096> ConnectionId;
typedef SInt32 SsizeT;
typedef UInt32 SizeT;
typedef SInt32 ShmFd;
typedef SInt32 ShmId;
typedef bytes<16384000> ShmBuffer;