FirebirdSQL logo
 Написание плагиновЗаключение 

IWriter

Интерфейс IWriter — записывает блок параметров аутентификации.

  1. reset

    void reset()

    очищает целевой блок.

  2. add

    void add(StatusType* status, const char* name)

    добавляет имя логина.

  3. setType

    void setType(StatusType* status, const char* value)

    устанавливает тип добавленного логина (пользователь, роль, группа ит.д.).

  4. setDb

    void setDb(StatusType* status, const char* value)

    устанавливает базу данных безопасности, в которой была выполненааутентификация.

IBlob

Интерфейс IBlob заменяет isc_blob_handle.

  1. getInfo

    void getInfo(StatusType* status,
             unsigned itemsLength,
             const unsigned char* items,
             unsigned bufferLength,
             unsigned char* buffer)

    заменяет isc_blob_info().

  2. getSegment

    int getSegment(StatusType* status,
               unsigned bufferLength,
               void* buffer,
               unsigned* segmentLength)

    заменяет isc_get_segment(). В отличие от него никогда не возвращаютсяошибки isc_segstr_eof и isc_segment (которые на самом деле неявляются ошибками), вместо этого возвращаются коды завершенияIStatus::RESULT_NO_DATA и IStatus::RESULT_SEGMENT, обычно возвращаетIStatus::RESULT_OK.

  3. putSegment

    void putSegment(StatusType* status,
                unsigned length,
                const void* buffer)

    заменяет isc_put_segment().

  4. cancel

    void cancel(StatusType* status)

    заменяет isc_cancel_blob(). В случае успеха освобождает интерфейс.

  5. close

    void close(StatusType* status)

    заменяет isc_close_blob(). В случае успеха освобождает интерфейс.

  6. seek

    int seek(StatusType* status,
         int mode,
         int offset)

    заменяет isc_seek_blob().

IServerBlock

Интерфейс IServerBlock используется серверной частью модуляаутентификации для обмена данными с клиентом.

  1. getLogin

    const char* getLogin()

    возвращает имя пользователя, переданное от клиента.

  2. getData

    const unsigned char* getData(unsigned* length)

    возвращает данные аутентификации, переданные от клиента.

  3. putData

    void putData(StatusType* status, unsigned length, const void* data)

    передаёт данные аутентификации клиенту.

  4. newKey

    ICryptKey* newKey(StatusType* status)

    создаёт новый ключ шифрования и добавляет его в список доступных дляплагинов шифрования сетевого трафика.

IServer

Интерфейс IServer является основным интерфейсом серверной части плагинааутентификации.

  1. authenticate

    int authenticate(StatusType* status,
                 IServerBlock* sBlock,
                 IWriter* writerInterface)

    Выполняет один этап аутентификации. Обмен данными с клиентомосуществляется с использованием интерфейса sBlock. Когда создаетсянекоторый элемент аутентификации, его следует добавить в блокаутентификации с помощью writerInterface. Возможные значения возвратаопределяются в интерфейсе IAuth.

  2. setDbCryptCallback

    void setDbCryptCallback(StatusType* status, ICryptKeyCallback* cryptCallback)

    Устанавливает интерфейс обратного вызова шифрования базы данных, которыйбудет использоваться для последующих подключений к базе данных исервисам.

Плагин аутентификации на клиентской стороне

IClientBlock

Интерфейс IClientBlock используется клиентской стороной модуляаутентификации для обмена данными с сервером.

  1. getLogin

    const char* getLogin()

    Возвращает имя пользователя, если оно присутствует в DPB.

  2. getPassword

    const char* getPassword()

    Возвращает пароль, если он присутствует в DPB.

  3. getData

    const unsigned char* getData(unsigned* length)

    Возвращает данные аутентификации, переданные с сервера.

  4. putData

    void putData(StatusType* status, unsigned length, const void* data)

    Передаёт данные аутентификации на сервер.

  5. newKey

    ICryptKey* newKey(StatusType* status)

    Создаёт новый ключ шифрования и добавляет его в список доступных дляплагинов шифрования сетевого трафика

  6. getAuthBlock

    IAuthBlock* getAuthBlock(StatusType* status)

IClient

Интерфейс IClient является основным интерфейсом клиентской сторонымодуля аутентификации.

  1. authenticate

    int authenticate(StatusType* status,
                 IClientBlock* cBlock)

    выполняет один этап аутентификации. Обмен данными с серверомосуществляется с использованием интерфейса cBlock. Возможные значениявозврата определяются в интерфейсе IAuth. AUTH_SUCCESS обрабатываетсяклиентской стороной как AUTH_MORE_DATA (т.е. клиент отправляетсгенерированные данные на сервер и ждет ответа от него).

Плагин управления пользователями

Этот плагин активно связан с серверной частью проверки подлинности — онподготавливает список пользователей для плагина аутентификации. Длякаждого плагина проверки подлинности требуется менеджер пользователей —некоторые из них могут получить доступ к списку пользователей, созданныхс использованием не Firebird программного обеспечения (например,AuthSspi). Запись, описывающая пользователя, состоит из несколькихполей, и поддерживать выполнение нескольких операций, таких какдобавление пользователя, изменение пользователя, получение спискапользователей и т. д. Плагин должен уметь интерпретировать команды,полученные в интерфейсе IUser.

IUserField

Интерфейс IUserField не используется как автономный интерфейс, онявляется базовым для ICharUserField и IIntUserField.

  1. entered

    int entered()

    возвращает ненулевое значение, если было введено (присвоено) значениедля поля.

  2. specified

    int specified()

    возвращает ненулевое значение, если для поля было присвоено значениеNULL.

  3. setEntered

    void setEntered(StatusType* status, int newValue)

    устанавливает entered флаг в 0 или ненулевое значение для поля. Нетспособа назначить NULL для поля, потому что он никогда не требуется.NULL, если они используются, назначаются реализациями интерфейсами и,следовательно, имеют полный доступ к их внутренним элементам.

ICharUserField

Интерфейс ICharUserField:

  1. get

    const char* get()

    возвращает значение поля как C-строку (\0 терминальную).

  2. set

    void set(StatusType* status, const char* newValue)

    присваивает значение полю. Устанавливает флаг entered в true.

IIntUserField

Интерфейс IIntUserField:

  1. get

    int get()

    возвращает значение поля.

  2. set

    void set(StatusType* status, int newValue)

    присваивает значение полю. Устанавливает флаг entered в true.

IUser

Интерфейс IUser — это список методов доступа к полям, включенным взапись о пользователе.

  1. operation

    unsigned operation()

    код операции (см. список ниже).

  2. userName

    ICharUserField* userName()

    имя пользователя.

  3. password

    ICharUserField* password()

    пароль.

  4. firstName

    ICharUserField* firstName()

    это и 2 следующие компоненты полного имени пользователя.

  5. lastName

    ICharUserField* lastName()

  6. middleName

    ICharUserField* middleName()

  7. comment

    ICharUserField* comment()

    комментарий (из SQL оператора COMMENT ON USER IS …).

  8. attributes

    ICharUserField* attributes()

    теги в форме tag1=val1, tag2=val2, …, tagN=valN. Val может бытьпустым, что означает, что тег будет удален.

  9. active

    IIntUserField* active()

    изменяет настройку ACTIVE/INACTIVE для пользователя.

  10. admin

    IIntUserField* admin()

    устанавливает/отменяет права администратора для пользователя.

  11. clear

    void clear(StatusType* status)

    устанавливает, что все поля не введены и не указаны.

Константы, определенные пользовательским интерфейсом — действующие кодыопераций.

  • OP_USER_ADD — добавление пользователя.

  • OP_USER_MODIFY — редактирование пользователя.

  • OP_USER_DELETE — удаление пользователя.

  • OP_USER_DISPLAY — отображение пользователя.

  • OP_USER_SET_MAP — включение отображения администраторов Windows нароль RDB$ADMIN.

  • OP_USER_DROP_MAP — выключение отображения администраторов Windows нароль RDB$ADMIN.

IListUsers

Интерфейс IListUsers — это обратный вызов, используемый плагиномпроверки подлинности при запросе списка пользователей. Плагин заполняетинтерфейс IUser для всех элементов всписке пользователей один за другим и для каждого пользователя вызываетметод list() этого интерфейса.

  1. list

    void list(StatusType* status, IUser* user)

    функция обратного вызова. Реализация может делать с полученными даннымито что хочет. Например, она может поместить данные из пользовательскогопараметра в выходной поток сервиса или разместить в специальных таблицахSEC$ группы.

ILogonInfo

Интерфейс ILogonInfo содержит данные, переданные плагину управленияпользователями для подключения к базе данных безопасности сдействительными учётными данными.

  1. name

    const char* name()

    возвращает имя пользователя текущего подключения.

  2. role

    const char* role()

    возвращает активную роль текущего подключения.

  3. networkProtocol

    const char* networkProtocol()

    возвращает сетевой протокол текущего подключения. В настоящее время неиспользуется плагинами.

  4. remoteAddress

    const char* remoteAddress()

    возвращает удаленный адрес текущего подключения. В настоящее время неиспользуется плагинами.

  5. authBlock

    const unsigned char* authBlock(unsigned* length)

    возвращает блок аутентификации текущего подключения. Если не NULLпереписывает имя пользователя.

IConfig

Интерфейс IConfig — общий интерфейс файла конфигурации.

  1. find

    IConfigEntry* find(StatusType* status, const char* name)

    Находит запись по имени.

  2. findValue

    IConfigEntry* findValue(StatusType* status, const char* name, const char* value)

    Находит запись по имени и значению

  3. findPos

    IConfigEntry* findPos(StatusType* status, const char* name, unsigned pos)

    Находит запись по имени и позиции. Если файл конфигурации содержитстроки:

    Db=DBA
Db=DBB
Db=DBC

    вызов findPos(status, "Db", 2) вернет запись со значением DBB.

IManagement

Интерфейс IManagement является основным интерфейсом плагина управленияпользователями.

  1. start

    void start(StatusType* status, ILogonInfo* logonInfo)

    запускает плагин, при необходимости он подключается к базе данныхбезопасности для управления пользователями (использовать это или нет эторешение, зависящее от плагинов), используя учетные данные из logonInfo.

  2. execute

    int execute(StatusType* status, IUser* user, IListUsers* callback)

    выполняет команду, предоставляемую методом operation() параметра user.При необходимости будет использоваться интерфейс обратного вызова.Параметр callback может иметь значение NULL для команд, не требующихполучения списка пользователей.

  3. commit

    void commit(StatusType* status)

    подтверждает изменения, выполненные вызовами метода execute().

  4. rollback

    void rollback(StatusType* status)

    отменяет изменения, выполненные вызовами метода execute().

Плагин шифрования базы данных

Возможность шифрования базы данных присутствовала в Firebird со времёнInterbase, но соответствующие места в коде были закомментированы.Реализация была сомнительной — ключ шифрования всегда отправлялся отклиента в DPB, не было сделано попыток скрыть его от внешнего мира, и непредлагалось путей для шифрования существующих баз данных. Firebird 3.0решает большинство проблем, за исключением, вероятно, худшей — какуправлять ключами шифрования. Мы предлагаем различные типы решений, ноони требуют усилий в плагинах, т. е. нет красивого способа работы сключами как, например, для плагинов шифрования сетевого трафика.

Перед запуском с собственным плагином шифрования базы данных следуетпринять во внимание следующее. Мы видим два основных случая для которыхиспользуется шифрование базы данных — во-первых, может оно потребоватьсяизбежать утечки данных, если сервер базы данных физически украден, аво-вторых, оно может использоваться для защиты данных в базе данных,которая распространяется вместе со специальным приложением, обращающимсяк этим данным. Требования к этим случаям совершенно разные. В первомслучае мы можем доверять серверу базы данных, что он не модифицирован,чтобы красть ключи, переданные в плагин безопасности, то есть мыожидаем, что этот ключ не будет отправлен на неподходящий сервер. Вовтором случае сервер может быть каким-то образом модифицирован для кражиключей (если они передаются из приложения в плагин через код сервера)или даже данных (в качестве последнего места для снятия дампов из кэша,где они находятся в не зашифрованном виде). Поэтому ваш плагин долженубедиться, что он работает с не измененными двоичными файлами Firebird ивашим приложением перед отправкой ключа в плагин, например, плагин можетпотребоваться от них какой-то цифровой подписи. Кроме того, еслииспользуется сетевой доступ к серверу, то хорошей идеей являетсяпроверка того, что сетевой канал зашифрован (разбор выводаIUtil::getFbVersion()) или используется собственный ключ шифрования.Вся эта работа должна выполняться в плагине (и в приложении, работающимс ним), то есть алгоритм шифрования блока базы данных сам по себе можетоказаться наиболее простой частью плагина шифрования базы данных,особенно когда для него используется некоторая стандартная библиотека.

ICryptKeyCallback

Интерфейс ICryptKeyCallback должен обеспечивать передачу ключашифрования в плагин шифрования базы данных или плагин хранителя ключа.

  1. callback

    unsigned callback(unsigned dataLength,
                  const void* data,
                  unsigned bufferLength,
                  void* buffer)

    при выполнении обратного вызова информация передается в обоихнаправлениях. Источник ключа получает dataLength байт данных и можетотправлять bufferLength байт в буфер. Возвращает фактическое количествобайтов, помещенных в буфер.

IDbCryptInfo

Интерфейс IDbCryptInfo передается движку IDbCryptPlugin. Плагин можетсохранить этот интерфейс и использовать, когда это необходимо, дляполучения дополнительной информации о базе данных.

  1. getDatabaseFullPath

    const char* getDatabaseFullPath(StatusType* status)

    возвращает полное (включая путь) имя первичного файла базы данных.

IDbCryptPlugin

Интерфейс IDbCryptPlugin является основным интерфейсом плагинашифрования базы данных.

  1. setKey

    void setKey(StatusType* status,
            unsigned length,
            IKeyHolderPlugin** sources,
            const char* keyName)

    используется для предоставления информации плагину шифрования базыданных о ключе шифрования. Firebird никогда не передает ключи для этоготипа плагина напрямую. Вместо этого массивIKeyHolderPlugins заданнойдлины передается в плагин шифрования, который должен получить от одногоиз них интерфейсICryptKeyCallback и затемполучить ключ, используя его. Параметр keyName — это имя ключа, котороебыло введено в операторе ALTER DATABASE ENCRYPT …​.

  2. encrypt

    void encrypt(StatusType* status,
             unsigned length,
             const void* from,
             void* to)

    шифрует данные перед записью блока в файл базы данных

  3. decrypt

    void decrypt(StatusType* status,
             unsigned length,
             const void* from,
             void* to)

    расшифровывает данные после чтения блока из файла базы данных.

  4. setInfo

    void setInfo(StatusType* status,
             IDbCryptInfo* info)

    в этом методе плагин шифрования обычно сохраняет информационныйинтерфейс для будущего использования.

Хранитель ключа для плагина шифрования базы данных

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

IKeyHolderPlugin

Интерфейс IKeyHolderPlugin является основным интерфейсом для плагинахранения ключей шифрования.

  1. keyCallback

    int keyCallback(StatusType* status,
                ICryptKeyCallback* callback)

    используется для передачи интерфейсаICryptKeyCallback вподключение (если он предоставляется пользователем с вызовомIProvider::setDbCryptCallback()). Этот вызов всегда выполняется в моментподключения к базе данных, и некоторые держатели ключа могут отклонитьподключение, если не был предоставлен удовлетворительный ключ.

  2. keyHandle

    ICryptKeyCallback* keyHandle(StatusType* status,
                             const char* keyName)

    предназначен для непосредственного вызова интерфейсомIDbCryptPlugin для полученияинтерфейса обратного вызова для именованного ключа из держателя ключа.Это позволяет использовать код Firebird с открытым исходным кодом так,чтобы никогда не касаться фактических ключей, избегая возможности кражиключа, изменяющим код Firebird. После получения интерфейсаICryptKeyCallback плагиншифрования запускает обмен данными, используя его. Держатель ключа может(например) проверить цифровую подпись плагина шифрования перед отправкойему ключа, чтобы избежать использования модифицированного плагинашифрования, способного украсть секретный ключ.

  3. useOnlyOwnKeys

    FB_BOOLEAN useOnlyOwnKeys(StatusType* status)

    информирует Firebird о том, будет ли использоваться ключ,предоставленный другим держателем ключа, или нет. Имеет смысл только дляSuperServer — только он может делиться ключами шифрования базы данныхмежду подключениями. Возвращая FB_TRUE из этого метода, принудительнозаставляет Firebird убедиться, что этот конкретный держатель ключа (и,следовательно, связанное с ним подключение) предоставляет правильныйключ шифрования, прежде чем позволить ему работать с базой данных.

  4. chainHandle

    ICryptKeyCallback* chainHandle(StatusType* status)

    поддержка цепочки держателей ключей. В некоторых случаях ключ долженпроходить через более чем один держатель ключа, прежде чем он достигнетплагина шифрования базы данных. Это необходимо (например) для поддержкиEXECUTE STATEMENT в зашифрованной базе данных. Это всего лишь пример —цепочки также используются в некоторых других случаях. Интерфейсобратного вызова, возвращенный этим методом, может отличаться отвозвращаемого функцией keyHandle() (см. выше). Как правило, он должениметь возможность дублировать ключи один в один, полученные изIKeyHolderPlugin при вызове функции keyCallback().

IConfigManager

Интерфейс IConfigManager — общий интерфейс для доступа к различнымобъектам конфигурации.

  1. getDirectory

    const char* getDirectory(unsigned code)

    Возвращает местоположение соответствующего каталога в текущем экземпляреFirebird. См. коды каталогов для этого вызова ниже.

  2. getFirebirdConf

    IFirebirdConf* getFirebirdConf()

    Возвращает интерфейс для доступа к значениям конфигурации по умолчанию(из firebird.conf).

  3. getDatabaseConf

    IFirebirdConf* getDatabaseConf(const char* dbName)

    Возвращает интерфейс для доступа к конфигурации, специфичной для базыданных (берёт в расчёт firebird.conf и соответствующую частьdatabase.conf).

  4. getPluginConfig

    IConfig* getPluginConfig(const char* configuredPlugin)

    Возвращает интерфейс для доступа к конфигурации именованного плагина.

  5. getInstallDirectory

    const char* getInstallDirectory()

    Возвращает каталог, в котором установлен firebird.

  6. getRootDirectory

    const char* getRootDirectory()

    Возвращает корневой каталог текущего экземпляра, в случае с единственнымэкземпляром обычно совпадает с каталогом установки.

  7. getDefaultSecurityDb

    const char* getDefaultSecurityDb()

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

Коды каталогов:

  • DIR_BIN — bin (утилиты наподобие isql, gbak, gstat);

  • DIR_SBIN — sbin (fbguard и firebird сервер);

  • DIR_CONF — каталог файлов конфигурации (firebird.conf,databases.conf, plugins.conf);

  • DIR_LIB — lib (fbclient, ib_util);

  • DIR_INC — include (ibase.h, firebird/Interfaces.h);

  • DIR_DOC — каталог документации;

  • DIR_UDF — UDF (ib_udf, fbudf);

  • DIR_SAMPLE — каталог примеров;

  • DIR_SAMPLEDB — каталог, где расположена база данных примеров(employee.fdb);

  • DIR_HELP — qli help (help.fdb);

  • DIR_INTL — каталог библиотек интернационализации (fbintl);

  • DIR_MISC — различные файлы (как манифест деинсталлятора и другое);

  • DIR_SECDB — каталог, где расположена база данных безопасности(securityN.fdb);

  • DIR_MSG — каталог, где расположен файл сообщений (firebird.msg);

  • DIR_LOG — каталог, где расположен лог файл (firebird.log);

  • DIR_GUARD — каталог, где расположена блокировка хранителя (fb_guard);

  • DIR_PLUGINS — директория плагинов ([lib]Engine12.\{dll|so}).

IConfigEntry

Интерфейс IConfigEntry — представляет запись (Key = Values с возможнымиподзаголовками (подзаписями)) в файле конфигурации firebird.

  1. getName

    const char* getName()

    Возвращает имя ключа.

  2. getValue

    const char* getValue()

    Возвращает значение в качестве символьной строки.

  3. getIntValue

    ISC_INT64 getIntValue()

    Обрабатывает значение как целое и возвращает его.

  4. getBoolValue

    FB_BOOLEAN getBoolValue()

    Обрабатывает значение как boolean и возвращает его.

  5. getSubConfig

    IConfig* getSubConfig(StatusType* status)

    Рассматривает подзаголовки как отдельный файл конфигурации и возвращаетинтерфейс IConfig для него.

IDecFloat16

Интерфейс IDecFloat16 помогает работать с типом данных DECFLOAT(16).

  1. toBcd

    void toBcd(const FB_DEC16* from, int* sign, unsigned char* bcd, int* exp)

    Преобразует десятичное значение с плавающей запятой в BCD.

  2. toString

    void toString(StatusType* status, const FB_DEC16* from, unsigned bufferLength, char* buffer)

    Преобразует десятичное значение с плавающей запятой в строку.

  3. fromBcd

    void fromBcd(int sign, const unsigned char* bcd, int exp, FB_DEC16* to)

    Собирает десятичное значение с плавающей запятой из BCD.

  4. fromString

    void fromString(StatusType* status, const char* from, FB_DEC16* to)

    Собирает десятичное значение с плавающей запятой из строки.

IDecFloat34

Интерфейс IDecFloat34 помогает работать с типом данных DECFLOAT(34).

  1. toBcd

    void toBcd(const FB_DEC34* from, int* sign, unsigned char* bcd, int* exp)

    Преобразует десятичное значение с плавающей запятой в BCD.

  2. toString

    void toString(StatusType* status, const FB_DEC34* from, unsigned bufferLength, char* buffer)

    Преобразует десятичное значение с плавающей запятой в строку.

  3. fromBcd

    void fromBcd(int sign, const unsigned char* bcd, int exp, FB_DEC34* to)

    Собирает десятичное значение с плавающей запятой из BCD.

  4. fromString

    void fromString(StatusType* status, const char* from, FB_DEC34* to)

    Собирает десятичное значение с плавающей запятой из строки.

Не интерфейсные объекты, используемые в API

Note

Они находятся в специальном заголовке Message.h C++

Следующие 3 класса используются для представления типов DATE, TIME иTIMESTAMP (datetime) при использовании макроса FB_MESSAGE. Членыструктуры данных, представляющие статическое сообщение, соответствуютполям типов FB_DATE/FB_TIME/ FB_TIMESTAMP, будут иметь тип одного изэтих классов. Для получения доступа к полям даты и времени в статическихсообщениях необходимо знать методы и члены класса (которые достаточносамо описательны, чтобы не описывать их здесь).

FbDate

Методы класса FbDate:

  1. decode

    void decode(IUtil* util,
            unsigned* year,
            unsigned* month,
            unsigned* day)

  2. getYear

    unsigned getYear(IUtil* util)

  3. getMonth

    unsigned getMonth(IUtil* util)

  4. getDay

    unsigned getDay(IUtil* util)

  5. encode

    void encode(IUtil* util,
            unsigned year,
            unsigned month,
            unsigned day)

FbTime

Методы класса FbTime:

  1. decode

    void decode(IUtil* util,
            unsigned* hours,
            unsigned* minutes,
            unsigned* seconds,
            unsigned* fractions)

  2. getHours

    unsigned getHours(IUtil* util)

  3. getMinutes

    unsigned getMinutes(IUtil* util)

  4. getSeconds

    unsigned getSeconds(IUtil* util)

  5. getFractions

    unsigned getFractions(IUtil* util)

  6. encode

    void encode(IUtil* util,
            unsigned hours,
            unsigned minutes,
            unsigned seconds,
            unsigned fractions)

FbTimestamp

Члены класса `FbTimestamp `:

  1. date

    FbDate date;

  2. time

    FbTime time;

FbChar и FbVarChar

Следующие два шаблона используются в статических сообщениях дляпредставления полей CHAR(N) и VARCHAR(N).

template <unsigned N>
struct FbChar
{
    char str[N];
};
template <unsigned N>
struct FbVarChar
{
    ISC_USHORT length;
    char str[N];
    void set(const char* s);
};

Заключение

В этом документе отсутствуют три типа плагинов — ExternalEngine, Trace и Replicator.Информация о них будет доступна в следующем выпуске.