20-install-guide.rst

Инструкция по сборке и установке

Получение исходных текстов библиотеки

Cтабильная версия библиотеки распространяется в виде архива с исходными текстами, в котором x обозначает старший номер релиза, а y младший номер релиза:

libakrypt-0.x.y.tar.bz2

Для разархивирования пользователи unix-систем могут выполнить команду:

tar -xjvf libakrypt-0.x.y.tar.bz2

Эту команду, как и все последующие, необходимо выполнять в консоли от имени обычного пользователя. Пользователи Windows могут воспользоваться для разархивирования исходных текстов программой 7-Zip.

После разархивирования должен появиться корневой каталог libakrypt-0.x, содержащий следующие подкаталоги:

• aktool - консольная утилита, использующая функции библиотеки,

• cert - доверенные корневые сертификаты открытых ключей библиотеки,

• cmake - управляющие файлы для системы сборки,

• doc - документация,

• examples - примеры, иллюстрирующие применение функций библиотеки:

  • examples/faq - примеры использования функций библиотеки,
  • examples/scripts - скрипты командной оболочки bash, позволяющие протестировать цепочки последовательных вызовов утилиты aktool,
  • examples/test - функциональные тесты для разрабочиков библиотеки,

• source - исходные тексты библиотеки,

Последняя, возможно не самая стабильная, версия исходных текстов библиотеки может быть получена из репозитория на сайте МИЭМ. Для клонирования репозитория необходимо выполнить из командной строки следующую команду:

git clone https://git.miem.hse.ru/axelkenzo/libakrypt-0.x

Необходимая документация и описание процедуры установки распределенной системы управления версиями git могут быть найдены на сайте git-scm.org. Например, в Debian или Ubuntu, установка git может быть выполнена следующей командой, запущенной с правами суперпользователя:

apt install git

Система сборки

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

Установка cmake, как правило, доступна для стандартных средств операционной системы. Например, в Debian или Ubuntu, установка cmake может быть выполнена следующей командой:

apt install cmake

Данная команда также должна выполняться с правами суперпользователя.

Результат сборки

В результате сборки библиотеки должны быть скомпилированы:

• служебная библиотека libakrypt-base, которая может самостоятельно использоваться в других проектах,
• библиотека libakrypt,
• консольная утилита aktool,
• набор тестовых программ и примеров использования криптографических преобразований (по-умолчанию, отключено).

Зависимости библиотеки

Текущая версия библиотеки зависит только от стандартной библиотеки языка Си libc.

Консольная утилита aktool зависит от следующих библиотек:

• libakrypt-base,
• libakrypt,
• libbz2 (опционально, используется при архивировании данных перед шифрованием),
• libintl (опционально, используется для русификации вывода сообщений),
• libiconv (опционально, используется для динамической перекодировки строк).

Последние две библиотеки, в Linux-системах входит в состав библиотеки libc. Их дополнительная установка может потребоваться во FreeBSD, MacOS или Windows (последнее имеет смысл только при использовании системы сборки mingw).

Поэтому, для установки опциональных зависимостей в Debian или Ubuntu, достаточно выполнить команду:

apt install libbz2-dev

TODO: Одной из важных, хотя и не первостепенных задач, стоящих перед авторами библиотеки, является сборка минимальной и переносимой конфигурации библиотеки libc, для полного исключения зависимостей при сборке приложений (что-то вроде diet libc, newlib или musl).

Сборка в Unix

Основной средой разработки библиотеки libakrypt является Linux, поэтому процесс сборки под Unix-like операционными системами является максимально простой процедурой.

Сборка библиотеки по-умолчанию

После получения исходных кодов и их разархивации, для сборки библиотеки выполните в консоли следующую последовательность команд:

mkdir build
cd build
cmake -DCMAKE_C_FLAGS="-march=native" ../libakrypt-0.x
make

В результате сборки, по-умолчанию, будут собраны как динамическая, так и статическая версии библиотеки --- libakrypt.so и libakrypt.a, вспомогательная библиотека libakrypt-base (соотвественно динамическая и статическая версии). а также консольная утилита aktool.

Для отключения сборки, например, статической версии необходимо использовать флаг AK_STATIC_LIB, передаваемый cmake:

cmake -DAK_STATIC_LIB=OFF ../libakrypt-0.x

Аналогичным образом отключается сборка динамической версии библиотеки:

cmake -DAK_SHARED_LIB=OFF ../libakrypt-0.x

Сборка различными компиляторами

Приведенная нами выше последовательность команд использует для сборки библиотеки найденный cmake компилятор по-умолчанию -- в Linux это, как правило, компилятор gcc, во FreeBSD и MacOS это clang. Если Вы хотите использовать другой компилятор, то Вам необходимо использовать при вызове cmake опцию CMAKE_C_COMPILER, в явном виде определяющую имя компилятора.

Так, следующий вызов позволит произвести сборку библиотеки с помощью компилятора clang:

cmake -DCMAKE_C_COMPILER=clang ../libakrypt-0.x

Аналогично, следующий вызов позволит произвести сборку библиотеки с помощью компилятора tcc (Tiny C Compiler):

cmake -DCMAKE_C_COMPILER=tcc ../libakrypt-0.x

Отметим, что через опцию CMAKE_C_COMPILER можно указывать только те компиляторы, которые поддерживаются cmake. Перечень поддерживаемых компиляторов можно найти в документации по cmake (см. раздел cmake-compile-features, supported compilers).

Сборка в Windows

Под управлением операционной системы семейства Windows может быть собрана как статическая, так и динамическая версия библиотеки. Далее мы описываем способ сборки библиотеки не использующий графические средства разработки.

Сборка с использованием компилятора MSVC

На настоящий момент протестирована успешная сборка библиотеки с помощью компилятора MSVC версий 10 и старше. Скачать бесплатно распространяемую среду сборки от Microsoft можно скачать здесь.

Для сборки библиотеки необходимо запустить командную строку Visual Studio, в которой переменными среды окружения установлен доступ к компилятору и системе сборки. (Ищем в меню строку: x64 Native Tools Command Prompt for MSVC 2022). После чего необходимо создать каталог для сборки, например, выполнив команду:

mkdir build-msvc

Далее, нужно перейти в созданный каталог и запустить cmake для конфигурации сборки:

cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE="Release" ..\libakrypt-0.x

Флаг -G определяет имя механизма, используемого далее для сборки исходных текстов. Аргумент -DCMAKE_BUILD_TYPE с параметром "Release" указывает компилятору, что нужно исключить из компилируемых файлов отладочную информацию.

Сборка библиотеки и тестовых примеров выполняется следующей командой:

nmake

Если -G не будет указан, то cmake создаст проект для графической среды Visual Studio.

По умолчанию для операционной системы Windows также будут собраны статическая и динамическая версии библиотеки. Механизм отключения сборки либо статической, либо динамической версии библиотеки аналогичен приведенному выше.

Сборка с использованием компилятора GCC

Для сборки компилятором gcc Вам необходимо установить набор программ из проекта MinGW (Minimalist GNU for Windows). Версия компилятора для 32-х битных систем может быть найдена на сайте mingw.org. Различные варианты 64-х битных версий компилятора GCC могут быть найдены на сайте mingw-w64.org.

Для сборки библиотеки (в 32-х битной ОС) в командной строке msys можно выполнить следующую последовательность команд:

mkdir build
cd build
cmake -G "MinGW Makefiles" -DCMAKE_C_FLAGS="-march=native" ../libakrypt-0.x
mingw32-make.exe

Для сборки библиотеки в 64-х битной версии OC достаточно изменить послений вызов команды mingw32-make.exe

Tip

Авторами используется проект MSyS2, содержащий последие версии компилятора gcc, а также консоль, эмулирующую работу unix-системы и поддерживающую стандартные консольные команды, такие как ls, cat и т.п.

Для сборки библиотеки в консоли MSYS необходимо установить необходимый софт (компилятор + систему сборки):

pacman -Suy
pacman -S mingw-w64-ucrt-x86_64-gcc
pacman -S git make cmake

После чего выполнить команды сборки библиотеки:

cmake -DAK_TESTS=ON -DAK_EXAMPLES=ON ../libakrypt-0.x

Сборка без libc

Вполне возможно собрать библиотеку, утилиту aktool и тестовые примеры без использования библиотеки glibc, заменив ее на другую реализацию стандартной билиотеки языка Си (именно такая замена, неявно для пользователя, происходит при сборке библиотеки с помощью компилятора MinGW). Далее рассматриваются несколько примеров.

Сборка с musl

Ниже мы описываем несколько простых шагов, которые позволят использовать библиотеку musl вместо glibc.

1. Необходимо собрать и инсталировать библиотеку musl. После скачивания исходных текстов библиотеки достаточно выполнить:

   tar -xzvf musl-1.2.3.tar.gz
   cd musl-1.2.3
   configure --prefix=/usr/local/musl
   make install

   Аргумент команды configure устанавливает каталог, в который будут помещены заголовочные файлы, а также собранные статическая и динамическая библиотеки. При этом в каталоге /usr/local/musl/bin будет помещен скрипт musl-gcc, примерно, следующего содержания:

   #!/bin/sh
   exec "${REALGCC:-gcc}" "$@" -specs "/usr/local/musl/lib/musl-gcc.specs"

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

2. Для сборки библиотеки достаточно выполнить следующую последовательность команд, в явном виде указав упомянутый выше скрипт:

   cmake -DCMAKE_C_COMPILER="musl-gcc" ../libakrypt-0.x
   make

Кросс-компиляция

Кросс-компиляция это процесс, в котором вы компилируете на одной машине программы, которые будут выполняться на другой машине. Машина на которой происходит компиляция называется хостом (host machine), а машина, для которой предназначается программа, называется таргетом или целевой машиной (target machine).

Сборка для MIPS

Приведем пример кросс-компиляции для случая, когда в качестве хоста выступает машина с архитектурой x86 под управлением ОС Linux, а целевой машиной служат машины с архитектурой mips - как 32-х разрядная, так и 64-х разрядная. Для начала необходимо установить соответствующий компилятор и программные средства для тестирования (мы используем Debian):

apt install gcc-mips-linux-gnu gcc-mips64-linux-gnuabi64
apt install qemu-system-mips

В первой строке мы устанавливаем кросс-компилятор gcc для mips-архитектуры процессора, а во второй - виртуальную машину qemu.

Теперь для сборки библиотеки и запуска тестовых примеров под архитектурой mips32r2 достаточно выполнить:

cmake -DCMAKE_C_COMPILER="mips-linux-gnu-gcc" -DCMAKE_C_FLAGS="-march=mips32r2" ../libakrypt-0.x/
make
qemu-mips-static -L /usr/mips-linux-gnu/ ./example-hello

В первой строке мы настраиваем сборку библиотеки с использованием компилятора mips-linux-gnu-gcc, реализующего процесс генерации кода, исполняемого на mips32r2 архитектуре. В третьей строке мы используем виртуальную машину qemu для запуска скомпилированного кода.

Аналогично, для сборки библиотеки и запуска тестовых примеров под архитектурой mips64r2 достаточно выполнить:

cmake -DCMAKE_C_COMPILER=mips64-linux-gnuabi64-gcc -DCMAKE_C_FLAGS="-march=mips64r2" ../libakrypt-0.x/
make
qemu-mips64-static -L /usr/mips64-linux-gnuabi64/ ./test-bckey04

Сборка для Petalinux

Еще один пример - это сборка библиотеки для Petalinux - версии linux, исполняемой на эмулируемом ПЛИС Xilinx 7200 процессоре ARM Cortex-A9.

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

apt install gcc-arm-linux-gnueabihf
apt install qemu-system-arm qemu-user

Теперь для сборки библиотеки и запуска тестовых примеров достаточно выполнить:

cmake -DCMAKE_C_COMPILER="arm-linux-gnueabihf-gcc" -DCMAKE_C_FLAGS="-mthumb"
                                               -DAK_STATIC_LIB=ON -DAK_SHARED_LIB=OFF ../libakrypt-0.x
make
qemu-arm -L /usr/arm-linux-gnueabihf ./example-hello

Еще несколько примеров кросс-компиляции под arm можно найти на следующем сайте.

Сборка тестовых примеров и тестирование криптографических алгоритмов

При сборке библиотеки компилятор также собирает ряд тестовых примеров, используя для этого статическую версию библиотеки. После сборки библиотеки с переданным cmake флагом -DAK_TESTS=ON, для запуска системы тестов под Unix или MSyS2 достаточно запустить:

make test

В консоли Windows при использовании компилятора MSVC необходимо будет запустить:

nmake test

После прохождения тестов будет выведена информация об общем числе успешно пройденных тестов, а также времени их работы.

Также, для тестирования корректной работы библиотеки может быть использована утилита aktool, собираемая вместе с библиотекой. Вызов:

aktool test --crypto --audit 2 --audit-file stderr

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

Инсталляция библиотеки

В текущей версии библиотеки поддерживается процесс инсталляции библиотеки только под Unix-системами.

Инсталляция под Unix-системами

По умолчанию предполагается, что библиотека будет установлена в каталог /usr/local. Для изменения этого каталога можно передать в cmake путь установки в явном виде. Например, следующий вызов позволяет установить библиотеку в католог /usr:

cmake -DCMAKE_INSTALL_PREFIX=/usr ../libakrypt-0.x

После успешной сборки библиотеки, для ее инсталляции, достаточно выполнить команду:

make install

Перечень установленных файлов записан в файл install_manifest.txt.

Внимание. Команда инсталляции библиотеки должна выполняться с правами суперпользователя.

Для деинсталляции бибилиотеки и удаления установленных ранее файлов нужно выполнить в каталоге сборки (build) команду:

xargs rm < install_manifest.txt

Данная команда также должна выполняться с правами суперпользователя.

Перечень опций для сборки библиотеки

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

Применение опции производится с помощью следующего вызова:

cmake -D<имя опции>=<значение опции>  ../libakrypt-0.x

Вывести значения установленных опций можно с помощью вызова:

cmake -L ../libakrypt-0.x

AK_BASE

Опция AK_BASE определяется в CMakeLists.txt следующим образом:

option( AK_BASE "Build two separate libraries - libkrypt and libakrypt-base" OFF )

Опция AK_BASE устанавливает должна ли библиотека собираться в виде одного или двух исполняемых (объектных) файлов. Если опция включена (значение ON), то при сборке сознаются два файла libakrypt-base.so(.a) и libakrypt.so(.a), первый из которых содержит реализацию вспомогательных преобразований, а второй только криптографические преобразования.

Принимаемые значения: ON, OFF.

Значение по-умолчанию: OFF.

AK_CA_PATH

Опция AK_CA_PATH устанавливает каталог для инсталляции и последующего поиска доверенных корневых сертификатов.

Принимаемые значения: произвольная строка символов.

Значение по умолчанию: в Unix-подобных системах значением является каталог ${CMAKE_INSTALL_PREFIX}/share/ca-certificates/libakrypt, для Windows-подобных систем значение не определено.

AK_CONFIG_PATH

Опция AK_CONFIG_PATH устанавливает каталог инсталляции и последующего поиска конфигурационного файла libakrypt.conf, содержащего точные значения технических и криптографических характеристик библиотеки.

Принимаемые значения: произвольная строка символов.

Значение по умолчанию: в Unix-подобных системах значением является каталог /etc, для Windows-подобных систем значение не определено.

AK_EXAMPLES

Опция AK_EXAMPLES определяется в CMakeLists.txt следующим образом:

option( AK_EXAMPLES "Build examples for libakrypt" OFF )

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

Принимаемые значения: ON, OFF.

Значение по-умолчанию: OFF.

После сборки примеров становится доступной команда, запускающая процесс тестирования:

make test

AK_LOCALE_PATH

Опция AK_LOCALE_PATH определяет каталог для инсталляции и последующего использования файлов русификации утилиты aktool. Для ОС Windows значения не имеет.

Принимаемые значения: произвольная строка символов.

Значение по умолчанию: в Linux-подобных системах значением является каталог /usr/share/locale, для FreeBSD систем - каталог /usr/local/share/locale.

AK_SHARED_LIB

Опция AK_SHARED_LIB определяется в CMakeLists.txt следующим образом:

option( AK_SHARED_LIB "Build the shared library" ON )

Опция устанавливает, нужно ли собирать динамическую версию библиотеки. Отметим, что одновременно может быть собрана только одна версия библиотеки либо динамическая, либо статическая.

Принимаемые значения: ON, OFF.

Значение по-умолчанию: ON.

AK_STATIC_LIB

Опция AK_STATIC_LIB определяется в CMakeLists.txt следующим образом:

option( AK_STATIC_LIB "Build the static library" ON )

Опция устанавливает, нужно ли собирать статическую версию библиотеки. Отметим, что одновременно может быть собрана только одна версия библиотеки либо динамическая, либо статическая.

Принимаемые значения: ON, OFF.

Значение по-умолчанию: ON.

AK_TESTS

Опция AK_TESTS определяется в CMakeLists.txt следующим образом:

option( AK_TESTS "Build tests for libakrypt" OFF )

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

Принимаемые значения: ON, OFF.

Значение по-умолчанию: OFF.

После сборки тестовых примеров становится доступной команда, запускающая процесс тестирования:

make test

AK_TESTS_GMP

Опция AK_TESTS_GMP определяется в CMakeLists.txt следующим образом:

option( AK_TESTS_GMP "Build comparison tests for gmp and libakrypt" OFF )

Опция добавляет к сборке библиотеки сборку нескольких тестовых примеров, проводящих вычисления с использованием библиотеки libgmp. Данные тестовые примеры сравнивают корректность реализации арифметических операций с большими целыми числами для библиотеки libakrypt и библиотеки libgmp. Включение этой опции автоматически приводит к включению опции AK_TESTS.

Принимаемые значения: ON, OFF.

Значение по-умолчанию: OFF.

После сборки тестовых примеров становится доступной команда, запускающая процесс тестирования:

make test

AK_TOOL

Опция AK_TOOL определяется в CMakeLists.txt следующим образом:

option( AK_TOOL "Build aktool utility" ON )

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

Принимаемые значения: ON, OFF.

Значение по-умолчанию: ON.

После сборки утилиты корректность сборки и работы утилиты может быть проверна с помощью следующего вызова

aktool t --crypto