Инструкция по использованию демонстрационной версии плагина шифрования Firebird Encryption Plugin Framework от IBSurgeon

В этом кратком руководстве находится описание тестирования демонстрационной версии IBSurgeon Firebird Encryption Plugin для шифрования ваших баз данных на сервере,  подключения к зашифрованным БД с клиента и выполнения backup/restore зашифрованных БД. Ограничение - демонстрационный пакет работает до 31 декабря 2018 г.

Исходные требования

1. СУБД Firebird 3.0.3+ – используйте официальный релиз 3.0.3 (32 или 64 бит). Предыдущие версии не поддерживаются данной версией плагина.
2. В случае новой установки Firebird создайте пользователя SYSDBA (остановите Firebird, выполните «gsec -user sysdba -add SYSDBA -pw masterkey», запустите Firebird)
3. Загрузите архив с файлами демонстрационной версии плагина и клиентского приложения

Шаг 1 – подготовка к шифрованию БД

У вас должна быть база данных, которую вы планируете зашифровать (в качестве такой БД можно использовать копию /examples/empbuild/employee.fdb.
Поместите базу в какой-нибудь каталог, например example c:\db\employee.fdb
Предполагается, что все действия производятся с 64-битной версией Firebird 3.0.3+. В случае 32бит используйте файлы из папки WinSrv32bit_ServerPart.

1. Создайте алиас в databases.conf

Вы можете задать плагин KeyHolder для всех баз данных на сервере. В этом случае добавьте параметр в firebird.conf:

2. Поместите загруженные файлы из папки WinSrv64bit_ServerPart\plugins в папку сервера plugins

• DbCrypt.dll
• KeyHolder.dll
• KeyHolder.conf  - этот файл содержит ключи, предназначенные только для тестирования. Не предоставляйте их конечным пользователям, и не используйте для вашего готового решения.

3. Поместите следующие файлы openssl в корневую папку установки Firebird

• fbcrypt.dll
• libcrypto-1_1-x64.dll
• libssl-1_1-x64.dll
• gbak.exe
• firebird.msg
• firebird.conf (опционально, может быть использован как пример)

4. Запустите Firebird

Шаг 2 – шифрование БД

Подсоединитесь к БД при помощи isql и зашифруйте ее
С этого момента БД будет зашифрована (на самом деле шифрование может занять некоторое время, если БД имеет размер гигабайт и более) используя серверную аутентификацию: ключи находятся в файле KeyHolder.conf.
Проверку статуса шифрования можно выполнить в isql командой show database. В конце выводимой информации вы увидите строку «Database encrypted». Если шифрование еще не завершилось, то вы увидите сообщение
Также можно проверить статус шифрования при помощи gstat, командой
gstat –h crypt
которая выдаст обычную информацию о заголовке БД, и в том числе
Если база данных большая (десятки гигабайт и более), проверить статус шифрования (или дешифрования) можно запросом результатом запроса будет % зашифрованных (или дешифрованных) страниц в БД. Не забывайте, что для обновления данных из mon$ следует сделать commit перед повторным выполнением этого запроса.

Шаг 3 – проверка переноса зашифрованной БД на другой компьютер

Можно попробовать перенести БД на компьютер с отдельной установкой Firebird 3 (без плагина шифрования, но проще попробовать удалить или переименовать скопированные ранее файлы.
Останавливаем Firebird, переименовываем keyholder.conf, запускаем Firebird
Подсоединяемся при помощи isql. Будет выдана ошибка
D:\Firebird364>isql localhost:crypt -user SYSDBA -password masterkey
Statement failed, SQLSTATE = 08004
Key not set
-IProvider::attachDatabase failed when loading mapping cache
Use CONNECT or CREATE DATABASE to specify a database
SQL>
Любая другая программа выдаст такое же сообщение
Unsuccessful execution caused by system error that does not preclude successful execution of subsequent statements.
Key not set.
IProvider::attachDatabase failed when loading mapping cache.
Если удалить dbcrypt.dll, то сообщение будет несколько иным
Invalid token.
Crypt plugin DBCRYPT failed to load.
IProvider::attachDatabase failed when loading mapping cache.
В любом случае, без плагина шифрования и ключей к базе теперь подсоединиться нельзя.

Шаг 4 – подключение к БД из приложения с ключом

Если вы удалили (или переименовали) файл dbcrypt.dll, восстановите его. Файл keyholder.conf восстанавливать не нужно.
После шифрования БД предполагаем, что база будет скопирована в клиентскую среду, в которой доступ к БД будет осуществляться только при помощи какого-либо специального приложения. 
Приложение для доступа к БД должно получить точно такой же ключ. Мы подготовили для вас пример приложения на Delphi XE8, с тем же файлом keyholder.conf, что в нашем примере. Поместите файлы приложения в отдельную папку на этом же компьютере, где есть работающий Firebird 3 (с плагином dbcrypt.dll и без keyholder.conf).

Запустите приложение из папки CryptTest\EnhancedCryptTestClient\Win32\Debug. Выполните следующие шаги:

1. Укажите путь к БД или ее алиас по кнопке "1. Setup Login". Эта база данных будет использована в тесте.
2. Укажите имя ключа и его значение. Если вы ранее указывали ключ RED, укажите Key Name = RED и скопируйте значение ключа из KeyHolder.conf.
3. Вы можете зашифровать или расшифровать базу указанным ключом. Обратите внимание - шифрование длится некоторое время, и все это время требуется наличие активного соединения с БД.
4. Нажмите Execute query для проверки работы зашифрованной БД

Никакой другой специфики от приложения для работы с базой не требуется.
В приведенном примере ключ передается из приложения на сервер. В этом случае только данное приложение может подсоединиться к БД. Любое другое приложение получит сообщение об ошибке (пример сообщений приведен выше).

Замечание: тестовое приложение может подключиться к БД только по протоколу tcp, протокол xnet не поддерживается.

В этом примере все операции с базой данных являются примером действий с зашифрованной БД. Вы можете использовать код этого приложения как пример реализации ваших приложений.

Шаг 4: backup/restore зашифрованной БД

Бэкап базы данных при помощи gbak.exe является самым частым способом создания резервной копии. Дистрибутив Firebird включает в себя утилиту gbak, но с зашифрованными базам данных без keyholder.conf на сервере она работать не будет. После шифрования базы данных только приложения, передающие на сервер ключ, могут выполнять операции с базой данных.
Поэтому мы сделали специальную версию gbak.exe, и поместили ее в Firebird Encryption Pluging Framework.
Важно заметить, что эта версия gbak.exe производит зашифрованные резервные копии: она шифрует файл бэкапа тем же ключом, которым зашифрована база данных.
Если вы запустите эту редакцию gbak.exe с опцией -?, вы увидите дополнительные параметры, которые позволяют указать имя ключа и его значение, или имя файла, содержащего нужный ключ:

    -KEYFILE              имя файла ключами шифрования БД и бэкапа
    -KEYNAME              имя ключа для шифрования
    -KEY                  значение ключа в виде "0x5A,..."

Бэкап зашифрованных БД

Для бэкапа загшифрованной БД gbak.exe должен передать ключ на сервер. Этот ключ используется при коннекте, и затем для чтения БД, и шифрования файла бэкапа.
Есть два способа указать ключ: записать его в файл, или явно указать в командной строке.

Пример указания ключа в файле:

gbak.exe -b -KEYFILE h:\Firebird\Firebird-3.0.3.32900-0_Win32\examplekeyfile.txt -KEYNAME RED localhost:h:\employee_30.fdb h:\testenc4.fbk -user SYSDBA -pass masterkey

Здесь параметр -keyfile указывает на расположение файла с ключами, а -keyname указывает на имя ключа, который нужно использовать (даже если в файле ключ всего один). Обратите внимание, что examplekeyfile.txt имеет тот же формат, что и KeyHolder.conf. Если вы выполните gbak -b -keyfile ... -keyname ... на незашифрованной БД, бэкап все равно будет зашифрован.

Пример указания ключа в командной строке:

gbak -b -KEY 0xec,0xa1,0x52,0xf6,0x4d,0x27,0xda,0x93,0x53,0xe5,0x48,0x86,0xb9,0x7d,0xe2,0x8f,0x3b,0xfa,0xb7,0x91,0x22,0x5b,0x59,0x15,0x82,0x35,0xf5,0x30,0x1f,0x04,0xdc,0x75, -keyname RED localhost:h:\employee30\employee30.fdb h:\testenc303.fbk -user SYSDBA -pass masterkey

Здесь значение ключа указано в параметре -key, а его имя - в параметре -keyname. Не смотря на то, что значение ключа явно задано, имя ключа все равно нужно указывать.

Restore бэкапа зашифрованных баз

Схема та же самая - нужно указать имя ключа и его значение. Примеры команд:

Restore с ключом из файла:

gbak -c -v -keyfile h:\Firebird\Firebird-3.0.3.32900-0_Win32\examplekeyfile.txt -keyname white  h:\testenc4.fbk localhost:h:\employeeenc4.fdb  -user SYSDBA -pass masterkey

Restore с ключом в командной строке:

gbak -c -v -key 0xec,0xa1,0x52,0xf6,0x4d,0x27,0xda,0x93,0x53,0xe5,0x48,0x86,0xb9,0x7d,0xe2,0x8f,0x3b,0xfa,0xb7,0x91,0x22,0x5b,0x59,0x15,0x82,0x35,0xf5,0x30,0x1f,0x04,0xdc,0x75, -keyname RED  h:\testenc4.fbk localhost:h:\employeeenc4.fdb  -user SYSDBA -pass masterkey

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

Мини-FAQ

Вопрос: что будет, если попытаться дешифровать БД сразу после запуска шифрования (пока оно не завершилось)?
Ответ: Статус шифрования или дешифрования сохраняется в БД, поэтому пока шифрование или дешифрование не закончилось, повторный запуск той же (или противоположной) операции выдаст сообщение об ошибке и текущий статус шифрования/дешифрования.

Вопрос: что если Firebird терминировать (перегрузить сервер) в процессе шифрования/дешифрования?
Ответ: после подсоединения к БД процесс продолжится.