Creating handles

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 endpoint ID (RIID) in the proxy object initialization function. To create a callable handle, call the KnHandleCreateUserObjectEx() function and specify the server IPC handle and the endpoint ID (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

Function	Information about the function
KnHandleCreateUserObject()	Purpose Creates a handle. Parameters [in] type – handle type. Fictitious parameter that must take a value ranging from the HANDLE_TYPE_USER_FIRST constant to the HANDLE_TYPE_USER_LAST constant as defined in the header file sysroot-*-kos/include/handle/handletype.h from the KasperskyOS SDK. [in] rights – handle permissions mask. [in,optional] context – pointer to the data that should be associated with the handle, or RTL_NULL if this association is not required. [out] handle – pointer to the handle. Returned values If successful, the function returns rcOk, otherwise it returns an error code.
KnHandleCreateUserObjectEx()	Purpose Creates a handle. Parameters [in] type – handle type. Fictitious parameter that must take a value ranging from the HANDLE_TYPE_USER_FIRST constant to the HANDLE_TYPE_USER_LAST constant as defined in the header file sysroot-*-kos/include/handle/handletype.h from the KasperskyOS SDK. [in] rights – handle permissions mask. [in,optional] context – pointer to the data that should be associated with the handle, or RTL_NULL if this association is not required. [in,optional] ipcChannel – server IPC handle, or INVALID_HANDLE if you do not need to create a callable handle. [in,optional] riid – endpoint ID (RIID), or INVALID_RIID if you do not need to create a callable handle. [out] handle – pointer to the handle. Returned values If successful, the function returns rcOk, otherwise it returns an error code.
KnHandleConnect()	Purpose Creates and connects the client, server, and listener IPC handles. Parameters [in,optional] ls – listener handle, or INVALID_HANDLE if you need to create it. [out,optional] outLs – pointer to the listener handle. You can specify RTL_NULL if the ls parameter is used to define the listener handle. [out,optional] outSr – pointer to the server IPC handle, or RTL_NULL to not create a server IPC handle if the ls parameter is used to define the listener handle. [out] outCl – pointer to the client IPC handle. Returned values If successful, the function returns rcOk, otherwise it returns an error code.
KnHandleConnectEx()	Purpose Creates and connects the client, server, and listener IPC handles. Parameters [in] server – handle of the server process. [in,optional] srListener – listener handle from the handle space of the server process, or INVALID_HANDLE if you need to create it. [in] client – handle of the client process. [out,optional] outSrListener – pointer to the listener handle from the handle space of the server process. You can specify RTL_NULL if the srListener parameter is used to define the listener handle. [out,optional] outSrEndpoint – pointer to the server IPC handle from the handle space of the server process, or RTL_NULL to not create a server IPC handle if the srListener parameter is used to define the listener handle. [out] outClEndpoint – pointer to the client IPC handle from the handle space of the client process. Returned values If successful, the function returns rcOk, otherwise it returns an error code.
KnHandleSecurityConnect()	Purpose Creates a client IPC handle for querying the Kaspersky Security Module through the security interface. Parameters [out] client – pointer to the handle. Returned values If successful, the function returns rcOk, otherwise it returns an error code.
KnHandleCreateListener()	Purpose Creates a listener handle that is not associated with a client IPC handle and server IPC handle. Parameters [out] listener – pointer to the listener handle. Returned values If successful, the function returns rcOk, otherwise it returns an error code.

Page top