KasperskyOS Community Edition 1.3

Using sessions (session.h)

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

The API is intended for use in the code of resource providers that provide access to user resources via IPC, and in the code of programs that utilize user resources locally (without IPC). The API lets you organize session-based management of access to user resources. A session consists of a sequence of actions, such as opening access to a resource, using the resource, and closing access to the resource. When access to a resource is opened, a session is created. Closing access to the resource terminates the session. Multiple operations can be simultaneously performed with a resource in one session. A resource can be used in exclusive mode or multi-access mode. In the latter case, the resource must be opened multiple times (possibly with different access permissions). In other words, the resource will be used via multiple, simultaneously existing sessions (parallel sessions).

In the API description, an "object" refers to a KosObject, which is an abstraction of a resource (for details about KosObjects, see Using KosObjects (objects.h)). The type of session and session context are also KosObjects. (A session context contains information about this session, such as the resource access permissions and the counter for active operations with the resource.)

Information about API functions is provided in the table below.

Creating a session type

A session type is created before sessions are created. To create a session type, call the KosSessionCreateType() function.

You must use the objectType parameter to define the type of objects for which the created type of sessions are intended. The object type must inherit the type with the ID kosSessionBaseObjectType.

Use the sessionType parameter to define the type of session contexts. You can specify the base type of session contexts with the ID kosSessionBaseSessionType or the type that inherits it. The base type of session contexts corresponds to the structure containing data such as the pointer to the object, the resource access permissions, the resource handle permissions mask that is transferred to resource consumers, and the counter of active operations with the resource during the session (the type of this structure is not exported to programs, but instead is used by the libkos library). You can add additional information to the session context by creating your own session context type that inherits the base type. For example, the session context for device usage may additionally contain pointers to functions that are called by solution programs to work with the device.

You must use the ops parameter to define the callback functions that are called when creating and terminating sessions. The callback functions for the open and close IDs must be defined. You do not have to define the callback function for the closeComplete ID, therefore this ID can be set to RTL_NULL.

The callback function corresponding to the open ID is called when creating a session and receives the pointers to the object, session context, data passed to the KosSessionOpenObject() function via the openCtx parameter, and the buffer for saving the resource handle permissions mask transferred to resource consumers. In this callback function, you can check the status of the resource, define the resource handle permissions mask transferred to resource consumers, and write data to the object or session context, for example. If the return code is different from rcOk, a session will not be created.

The callback function corresponding to the close ID is called when the session is terminated, irrespective of whether operations with the resource were completed (the counter of active operations in the closed session may be greater than zero), and receives pointers to the object and session context. In this callback function, you can interrupt active operations in a terminated session and write data to an object or session context, for example. Any return code is acceptable.

The callback function corresponding to the closeComplete ID is called when a session is terminated only after completion of all operations with the resource (the counter of active operations in the completed session is equal to zero) and receives the pointers to the object and session context. In this callback function, you can write data to an object, for example.

Registering an object

After creating a session type, you must register the required objects as objects that can be linked to sessions of this type. To register an object, call the KosSessionRegisterObject() function.

You cannot register one object to be linked to different types of sessions at the same time.

After registration, the object is ready to be opened.

Opening an object

When an object is opened, a session linked to this object is created, and an object is opened when there is a request to open access to a resource. This may be a request via IPC from the resource consumer or a local request from another program component.

To open an object, call the KosSessionOpenObject() function. You must use the requiredRights parameter to define the resource access permissions in the created session, and use the shareMode parameter to define the multi-access permissions for a resource to properly restrict access to this resource for parallel sessions. For example, if read-and-write permissions are defined via the requiredRights parameter and the shareMode parameter is set to 0, the created session requires exclusive read-and-write access to the resource. If read-and-write permissions are defined via the requiredRights parameter but only read permissions are defined via the shareMode parameter, the created session requires read-and-write permissions and allows read operations in parallel sessions. If read permissions are defined via the requiredRights parameter but read-and-write permissions are defined via the shareMode parameter, the created session requires read-access and allows read-and-write operations in parallel sessions.

If a resource needs to be used in multi-access mode, you must consider the following conditions when the object is opened a second time and subsequent times:

• The access permissions defined via the requiredRights parameter cannot exceed the minimal access permissions defined via the shareMode parameter for all parallel sessions linked to this object.
• The access permissions defined via the shareMode parameter must include all of the access permissions defined via the requiredRights parameter for all parallel sessions linked to this object.

The session context will be created after the object is opened.

If a program uses resources locally, after the object is opened, the program component managing the resources must pass the pointer of the created session context to the program component that uses the resources. When subsequently requesting operations with a resource, the program component using the resources must pass this pointer to the program component managing the resources for session identification.

After opening an object, the resource provider must transfer the resource handle to the consumer. The session context must be used as the resource transfer context so that the consumer can receive the handle of the resource linked to the session. When subsequently requesting operations with a resource, the consumer must put the received resource handle into IPC requests so that the provider receives the pointer to the session context after dereferencing this handle. To fill the resource handle transport container with data for transfer to a resource consumer, call the KosSessionContextToIpcHandle() function. This function receives the session context via the sessionCtx parameter and transfers the resource handle transport container via the desc parameter.

The KosSessionContextToIpcHandle() function takes the permissions mask defined in the callback function that is called when creating the session and puts this permissions mask into the resource handle transport container. The access permissions defined in this mask must not exceed the session access permissions defined via the requiredRights parameter of the KosSessionOpenObject() function. However, the same access permission may correspond to different bits in the permissions mask and in the value defined via the requiredRights parameter of the KosSessionOpenObject() function.

The KosSessionContextToIpcHandle() function defines the session context as the resource transfer context. The session context will be automatically deleted (and therefore the session will be terminated) after closure or revocation of the resource handles that were generated by the transfer of the resource handle that was received by calling the KosSessionContextToIpcHandle() function. If you need to prevent automatic termination of a session for subsequent termination via the KosSessionCloseObject() function call, prior to transferring the resource handle you must increment the counter for links to the context of this session by calling the KosRefObject() function from the objects.h API. In this case, after calling the KosSessionCloseObject() function, you must decrement the counter for links to the session context by calling the KosPutObject() function from the objects.h API.

Performing operations with a resource

An operation with a resource (for example, reading, writing, or getting parameters) is performed by request via IPC from the resource consumer or by local request from another program component.

The scenario for performing an operation with a resource includes the followings steps:

1. Verify the resource access permissions.

   When processing a local request, call the KosSessionGetOpenRights() function. This function gets information about session resource access permissions defined via the requiredRights parameter of the KosSessionOpenObject() function to compare these permissions with the permissions needed to perform the operation.

   During IPC request processing, you must call the KosSessionIpcHandleToSession() function, which gets the session context and verifies whether the permissions mask of the resource handle that the resource consumer put into the IPC request corresponds to the requested operation. The resource handle transport container received from the resource consumer must be passed to the function via the desc parameter. In the operation parameter, you must specify the resource access permissions that are needed to perform the requested operation. In the type parameter, you must specify the ID of the session type to verify that the type of session context matches the session type. If you set the type parameter to RTL_NULL, you must verify the type of session context prior to converting the pointer type that was received via the sessionCtx parameter. Verification of the session context type is mandatory because the resource provider may create sessions with contexts of different types while the resource consumer may erroneously make an IPC request with the resource handle matching a session with a different type of context. To verify the context type, use the objects.h API.

2. Increment the counter for active operations in the session by calling the KosSessionRef() function.

   This function verifies that the session has not terminated. In the type parameter, you must specify the ID of the session type to verify that the type of session context matches the session type. You can use the object parameter to receive a pointer to the object.

3. Perform the requested actions with the resource.
4. Decrement the counter for active operations in the session by calling the KosSessionPut() function.

Getting a resource handle

A resource handle may be required for using notifications or for querying the Kaspersky Security Module through the security interface, for example. To get a resource handle for an object or session context, call the KosSessionGetObjectHandle() or KosSessionGetObjectHandleBySession() function, respectively.

Enumerating sessions linked to an object

You may need to enumerate sessions linked to an object to notify each of the resource consumers using a resource about the state of that resource, for example. To enumerate sessions linked to an object, call the KosSessionWalk() function. Use the handler parameter to define the callback function that is called for each session during enumeration and receives pointers to the object, session context and data that is passed to the KosSessionWalk() function via the walkCtx parameter. In this callback function, you can send a notification about the state of a resource to consumers of that resource, for example.

Closing an object

When an object is closed, one of the sessions linked to this object is terminated. A session will not be terminated until all operations in this session are terminated (in other words, when the counter of active operations is equal to zero). When a session is terminated, the handles of the resource linked to this session are automatically revoked.

An object is closed when there is a request to close access to the resource. This may be a request via IPC from the resource consumer or a local request from another program component. After making a request to close access to a resource, the resource consumer must close the handle of this resource. (If the resource consumer terminates without making a request to close access to the resource, or closes the resource handle without making this request, the corresponding session will be automatically terminated under the condition that the resource consumer has not additionally incremented the counter for links to the context of this session.)

To close an object, call the KosSessionCloseObject() or KosSessionCloseObjectByIpcHandle() function.

The KosSessionCloseObject() function terminates the session corresponding to the session context that was defined via the sessionCtx parameter.

The KosSessionCloseObjectByIpcHandle() function terminates the session linked to the resource handle that the resource consumer put into the IPC request to close access to the resource. The received resource handle transport container must be passed to the function via the desc parameter. In the type parameter, you must specify the ID of the session type to verify that the type of session context matches the session type.

Deregistering an object

When an object is deregistered, all sessions linked to this object are terminated and it is no longer possible to open this object. A session will not be terminated until all operations in this session are terminated (in other words, when the counter of active operations is equal to zero). When a session is terminated, the handles of the resource linked to this session are automatically revoked. (Revocation does not close resource handles, therefore revoked handles need to be closed.)

To deregister an object, call the KosSessionUnregisterObject() function.

Deleting a session type

A session type must be deleted if there are no registered objects for which sessions of this type can be used, and there will be no more registrations. For example, a session type must be deleted when the resource provider is terminated.

To delete a session type, call the KosSessionDestroyType() function.

Information about API functions

session.h functions