Создание дескрипторов

Создание дескрипторов системных ресурсов

Дескрипторы системных ресурсов создаются при создании этих ресурсов, например, при регистрации прерывания или региона памяти MMIO, создании буфера DMA, потока исполнения или процесса.

Создание дескрипторов пользовательских ресурсов

Дескрипторы пользовательских ресурсов создаются поставщиками ресурсов с использованием функции KnHandleCreateUserObject() или KnHandleCreateUserObjectEx().

Через параметр context нужно задать контекст пользовательского ресурса. Контекст пользовательского ресурса – данные, позволяющие поставщику ресурса идентифицировать ресурс и его состояние, когда запрашивается доступ к ресурсу другими процессами. В общем случае это набор разнотипных данных (структура). Например, для файла контекст может включать имя, путь, положение курсора. Контекст пользовательского ресурса используется в качестве контекста передачи ресурса или совместно с несколькими контекстами передачи ресурса.

Через параметр rights нужно задать маску прав дескриптора.

Создание IPC-дескрипторов

IPC-дескриптор (англ. IPC handle) – это дескриптор, который идентифицирует IPC-канал. IPC-дескрипторы используются для выполнения системных вызовов. Клиентский IPC-дескриптор нужен для выполнения системного вызова Call(). Серверный IPC-дескриптор требуется для выполнения системных вызовов Recv() и Reply(). Серверный IPC-дескриптор, который имеет расширенные права, позволяющие добавлять IPC-каналы в набор идентифицируемых этим дескриптором IPC-каналов, называется слушающим дескриптором (англ. listener handle). Клиентский IPC-дескриптор, который идентифицирует одновременно IPC-канал до сервера и службу этого сервера, называется callable-дескриптором (англ. callable handle).

Сервер создает callable-дескриптор и передает его клиенту, чтобы клиент мог использовать службу сервера. Клиент инициализирует IPC-транспорт, используя полученный callable-дескриптор. При этом в функции инициализации прокси-объекта клиент указывает значение INVALID_RIID в качестве идентификатор службы (RIID). Чтобы создать callable-дескриптор, нужно вызвать функцию KnHandleCreateUserObjectEx(), указав в параметрах ipcChannel и riid серверный IPC-дескриптор и идентификатор службы (RIID) соответственно. Через параметр context можно задать данные для ассоциации с callable-дескриптором. Сервер сможет получить указатель на эти данные при разыменовании callable-дескриптора. (Несмотря на то что callable-дескриптор является IPC-дескриптором, он помещается ядром в поле base_.self фиксированной части IPC-запроса.)

Чтобы создать и ассоциировать между собой клиентский, серверный и слушающий IPC-дескрипторы, нужно вызвать функцию KnHandleConnect() или KnHandleConnectEx(). Эти функции используются для статического создания IPC-каналов. Функция KnHandleConnect() создает IPC-дескрипторы из пространства дескрипторов вызывающего процесса. При этом клиентский IPC-дескриптор может быть передан другому процессу. Функция KnHandleConnectEx() может создать IPC-дескрипторы как из пространства дескрипторов вызывающего процесса, так и из пространств дескрипторов других процессов: клиента и сервера.

При вызове функции KnHandleConnect() или KnHandleConnectEx() со значением INVALID_HANDLE в параметре, задающем слушающий дескриптор, создается новый слушающий дескриптор. При этом серверный и слушающий IPC-дескрипторы в выходных параметрах являются одним и тем же дескриптором. Если вызвать функцию KnHandleConnect() или KnHandleConnectEx(), указав слушающий дескриптор, то созданный серверный IPC-дескриптор обеспечит возможность получать IPC-запросы по всем IPC-каналам, ассоциированным с этим слушающим дескриптором. В этом случае серверный и слушающий IPC-дескрипторы в выходных параметрах являются разными дескрипторами. (Первый IPC-канал, ассоциированный со слушающим дескриптором, создается при вызове функции KnHandleConnect() или KnHandleConnectEx() со значением INVALID_HANDLE в параметре, задающем слушающий дескриптор. Второй и последующие IPC-каналы, ассоциированные со слушающим дескриптором, создаются при втором и последующих вызовах функции KnHandleConnect() или KnHandleConnectEx() с указанием слушающего дескриптора, полученного при первом вызове.)

Чтобы создать слушающий дескриптор, не связанный с клиентским и серверным IPC-дескрипторами, нужно вызвать функцию KnHandleCreateListener(). (Функции KnHandleConnect() и KnHandleConnectEx() создают слушающий дескриптор, связанный с клиентским и серверным IPC-дескрипторами.) Функцию KnHandleCreateListener() удобно использовать, чтобы создать слушающий дескриптор, с которым впоследствии будут связаны callable-дескрипторы.

Чтобы создать клиентский IPC-дескриптор для обращения к модулю безопасности Kaspersky Security Module через интерфейс безопасности, нужно вызвать функцию KnHandleSecurityConnect(). Эта функция вызывается библиотекой libkos при инициализации IPC-транспорта для обращения к модулю безопасности.

Сведения о функциях API

Функции handle_api.h

Функция

Сведения о функции

KnHandleCreateUserObject()

Назначение

Создает дескриптор.

Параметры

  • [in] type – тип дескриптора. Фиктивный параметр, который должен принимать значение от константы HANDLE_TYPE_USER_FIRST до константы HANDLE_TYPE_USER_LAST, определенных в заголовочном файле sysroot-*-kos/include/handle/handletype.h из состава KasperskyOS SDK.
  • [in] rights – маска прав дескриптора.
  • [in,optional] context – указатель на данные, которые нужно ассоциировать с дескриптором, или RTL_NULL, если эта ассоциация не требуется.
  • [out] handle – указатель на дескриптор.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

KnHandleCreateUserObjectEx()

Назначение

Создает дескриптор.

Параметры

  • [in] type – тип дескриптора. Фиктивный параметр, который должен принимать значение от константы HANDLE_TYPE_USER_FIRST до константы HANDLE_TYPE_USER_LAST, определенных в заголовочном файле sysroot-*-kos/include/handle/handletype.h из состава KasperskyOS SDK.
  • [in] rights – маска прав дескриптора.
  • [in,optional] context – указатель на данные, которые нужно ассоциировать с дескриптором, или RTL_NULL, если эта ассоциация не требуется.
  • [in,optional] ipcChannel – серверный IPC-дескриптор или INVALID_HANDLE, если не требуется создавать callable-дескриптор.
  • [in,optional] riid – идентификатор службы (RIID) или INVALID_RIID, если не требуется создавать callable-дескриптор.
  • [out] handle – указатель на дескриптор.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

KnHandleConnect()

Назначение

Создает и связывает между собой клиентский, серверный и слушающий IPC-дескрипторы.

Параметры

  • [in,optional] ls – слушающий дескриптор или INVALID_HANDLE, чтобы создать его.
  • [out,optional] outLs – указатель на слушающий дескриптор. Можно указать RTL_NULL, если через параметр ls задан слушающий дескриптор.
  • [out,optional] outSr – указатель на серверный IPC-дескриптор или RTL_NULL, чтобы не создавать серверный IPC-дескриптор, если через параметр ls задан слушающий дескриптор.
  • [out] outCl – указатель на клиентский IPC-дескриптор.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

KnHandleConnectEx()

Назначение

Создает и связывает между собой клиентский, серверный и слушающий IPC-дескрипторы.

Параметры

  • [in] server – дескриптор серверного процесса.
  • [in,optional] srListener – слушающий дескриптор из пространства дескрипторов серверного процесса или INVALID_HANDLE, чтобы создать его.
  • [in] client – дескриптор клиентского процесса.
  • [out,optional] outSrListener – указатель на слушающий дескриптор из пространства дескрипторов серверного процесса. Можно указать RTL_NULL, если через параметр srListener задан слушающий дескриптор.
  • [out,optional] outSrEndpoint – указатель на серверный IPC-дескриптор из пространства дескрипторов серверного процесса или RTL_NULL, чтобы не создавать серверный IPC-дескриптор, если через параметр srListener задан слушающий дескриптор.
  • [out] outClEndpoint – указатель на клиентский IPC-дескриптор из пространства дескрипторов клиентского процесса.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

KnHandleSecurityConnect()

Назначение

Создает клиентский IPC-дескриптор для обращения к модулю безопасности Kaspersky Security Module через интерфейс безопасности.

Параметры

  • [out] client – указатель на дескриптор.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

KnHandleCreateListener()

Назначение

Создает слушающий дескриптор, не связанный с клиентским и серверным IPC-дескрипторами.

Параметры

  • [out] listener – указатель на слушающий дескриптор.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

В начало