Компиляция и установка

[TOC]

Обзор

GmSSL использует CMake для сборки. Поскольку CMake — это кроссплатформенный инструмент для компиляции, установки и сборки, GmSSL можно компилировать, устанавливать и запускать на большинстве основных операционных систем. Проект GmSSL официально протестировал компиляцию на Windows (включая Visual Studio и Cygwin), Linux, Mac, Android и iOS. С помощью рабочего процесса CI GitHub проект автоматически компилируется из последнего кода.

Процесс сборки GmSSL, как и в других проектах с открытым исходным кодом на основе CMake, включает в себя конфигурацию, компиляцию, тестирование и установку. В качестве примера операционной системы рассмотрим Linux. После загрузки и распаковки исходного кода GmSSL перейдите в каталог исходного кода и выполните следующие команды:

mkdir build
cd build
cmake ..
make
make test
sudo make install

Это позволит выполнить конфигурацию, компиляцию, тестирование и установку.

После успешной компиляции с помощью команды make в каталоге build/bin будут созданы исполняемые файлы и библиотеки проекта. Для инструментов шифрования перед использованием важно провести тестирование с помощью make test. Если тестирование не пройдёт, не следует использовать программное обеспечение. Если во время тестирования возникает ошибка, можно выполнить конкретную команду теста в build/bin, например sm4test, чтобы увидеть подробную информацию об ошибке.

Выполнив sudo make install, после установки можно вызвать инструмент командной строки gmssl. В средах Linux и Mac заголовочные файлы обычно устанавливаются в /usr/local/include/gmssl, а библиотечные файлы — в /usr/local/lib.

Исходный код проекта

Исходный код GmSSL публикуется и поддерживается на GitHub.

Домашняя страница проекта на GitHub: https://github.com/guanzhi/GmSSL

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

Определение текущего состояния кода через CI

Иногда в недавно отправленном коде могут быть ошибки компиляции. Обычно эти ошибки исправляются в течение 1–2 дней. Если текущий последний код ещё не был исправлен, вы можете выбрать версию Commit без ошибок через рабочий процесс CI на GitHub.

Через рабочий процесс GitHub CI можно определить, содержит ли определённый коммит ошибки компиляции. В настоящее время в проекте GmSSL настроены следующие среды компиляции:

• CMake ubuntu-latest
• CMake windows-latest
• CMake macos-latest
• CMake-Android
• CMake-iOS

Просматривая состояние этих CI, можно определить, можно ли успешно скомпилировать код на соответствующей платформе. Если код не может быть скомпилирован на определённой платформе, можно выбрать предыдущую версию Commit, которая прошла тестирование.

Настройка параметров компиляции

На этапе выполнения cmake можно изменить параметры конфигурации по умолчанию для проекта, настроив переменные CMake. Вы можете просмотреть все инструкции option в файле CMakeLists.txt исходного кода, чтобы увидеть доступные параметры конфигурации. Например:

option(BUILD_SHARED_LIBS "Build using shared libraries" OFF)

Указывает, что проект по умолчанию генерирует статические библиотеки, а не динамические.

Создание динамических или статических библиотек

По умолчанию CMake в GmSSL генерирует динамические библиотеки. Можно настроить переменную CMake BUILD_SHARED_LIBS на ON или OFF, чтобы указать создание динамической или статической библиотеки.

cmake .. -DBUILD_SHARED_LIBS=ON

Настройка оптимизированных реализаций алгоритмов шифрования

GmSSL включает оптимизированные реализации алгоритмов шифрования для конкретных аппаратных средств и наборов инструкций, таких как оптимизация для Intel AVX2 и GPU. Эти оптимизации обеспечивают значительное повышение скорости или безопасности по сравнению со стандартными реализациями на C.

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

• ENABLE_SM3_AVX_BMI2 Оптимизация алгоритма SM3 для набора инструкций AVX + BMI2.
• ENABLE_SM3_X8_AVX2 Параллельная реализация алгоритма SM3 для набора инструкций AVX2.
• ENABLE_SM3_X16_AVX512 Параллельная реализация алгоритма SM3 для набора инструкций AVX512.
• ENABLE_SM4_AESNI_AVX Реализация алгоритма SM4 для набора инструкций AESNI +AVX.
• ENABLE_RDRND Аппаратный генератор случайных чисел на основе инструкции Intel RDRND.
• ENABLE_GF128_PCLMULQDQ Реализация режима GCM на основе инструкции Intel PCLMULQDQ.

Компиляция небезопасных алгоритмов шифрования

Для учебных целей исходный код GmSSL содержит набор небезопасных алгоритмов шифрования, которые по умолчанию не включаются в двоичные файлы. Вы можете включить эти алгоритмы, установив ENABLE_BROKEN_CRYPTO, во время настройки. После повторной компиляции алгоритмы, включённые в библиотеку GmSSL, включают:

• DES блочное шифрование
• SHA1 хеш-функция
• MD5 хеш-функция
• RC4 потоковое шифрование

Компиляция в среде Visual Studio

CMake поддерживает генерацию различных типов Makefile с использованием разных систем сборки (Generator). В среде Windows и Visual Studio CMake может генерировать обычные решения Visual Studio (.sln), которые можно завершить в графическом интерфейсе Visual Studio, или Makefile, подобные тем, что используются в Linux, которые можно завершить в командной строке.

Генерация Makefile для компиляции

После установки Visual Studio в меню «Пуск» появится пункт «Visual Studio». Здесь вы найдёте командные строки x64 Native Tools Command Prompt for VS 2022 и другие.

C:\Program Files\Microsoft Visual Studio\2022\Community>cd /path/to/gmssl
mkdir build
cd build
cmake .. -G "NMake Makefiles"
nmake
nmake test

После завершения компиляции попытка установить напрямую приведёт к ошибке прав доступа, поскольку процессу установки требуется записать файлы в системные каталоги, а текущий пользователь, открывший командную строку, не имеет необходимых разрешений. Вы можете запустить x64 Native Tools Command Prompt for VS 2022 от имени администратора и выполнить:

nmake install

Затем gmssl программа командной строки, заголовочные и библиотечные файлы будут записаны в C:/Program Files/GmSSL/bin, C:/Program Files/GmSSL/include и C:/Program Files/GmSSL/lib соответственно. Чтобы иметь возможность запускать gmssl из любого каталога в командной строке, необходимо добавить каталог установки в системный путь, выполнив:

set path=%path%;C:\Program Files\GmSSL\bin

Завершив настройку, вы можете проверить новый путь, запустив path.

Сборка в Visual Studio GUI

После установки Visual Studio вы увидите пункт «Visual Studio» в меню «Пуск». Здесь вы найдёте командные строки x64 Native Tools Command Prompt for VS 2022 и другие.

C:\Program Files\Microsoft Visual Studio\2022\Community>cd /path/to/gmssl
mkdir build
cd build
cmake ..

После этого CMake создаст файл GmSSL.sln и множество файлов .vcxproj в папке build.

Откройте GmSSL.sln, чтобы запустить Visual Studio. Выберите «Отладка», «Выпуск», «MinSizeRel» и другие конфигурации в панели инструментов Visual Studio.

Запуск тестов в Visual Studio

Найдите проект RUN_TESTS в диспетчере ресурсов решения и запустите его, нажав правой кнопкой мыши «Отладить» → «Запустить новый экземпляр». Это запустит тесты, и результаты тестов будут отображаться в окне «Вывод». После завершения тестов появится диалоговое окно с отказом в доступе для RUN_TESTS.

Выбор 32-битной или 64-битной программы

Компиляция GmSSL с использованием различных командных строк Visual Studio позволяет создавать 32-разрядные X86 или 64-разрядные программы X86_64. Командная строка x64 Native Tools Command Prompt for VS 2022 создаёт 64-разрядную программу, а командная строка x86 Native Tools Command Prompt for VS 2022 — 32-разрядную.

Вы можете использовать диспетчер ресурсов Windows для проверки разрядности скомпилированной программы. Откройте диспетчер ресурсов и добавьте столбец «Платформа» на страницу «Процессор» через «Выбор столбцов». Таким образом, вы сможете видеть, является ли каждый процесс 32- или 64-разрядным. Запустите gmssl tlcp_client или добавьте цикл в тестовый файл, чтобы удерживать командную строку открытой в течение некоторого времени. Cygwin — это эмулирующая среда Linux для Windows. Cygwin предоставляет среду оболочки Linux и множество инструментов командной строки Linux, а также предоставляет компиляторы, заголовочные файлы и библиотеки, необходимые для разработки приложений.

Приложения, ориентированные на разработку в Linux, обычно зависят от таких файлов заголовков, как unistd.h, sys/socket.h и других, а также от функций POSIX. Visual Studio не предоставляет реализацию этих функций POSIX, поэтому такие приложения нельзя скомпилировать непосредственно в среде Windows. Cygwin упаковывает функции операционной системы Windows и предоставляет интерфейс уровня POSIX и динамическую библиотеку (cygwin1.dll), а также полный набор инструментов компиляции Linux, таких как GCC и CMake. Это означает, что доступны все стандартные заголовочные файлы среды Linux, и код, зависящий от компилятора GCC, может быть скомпилирован (в отличие от Visual Studio, где компилятор cl не полностью поддерживает синтаксис C99). Таким образом, стандартные приложения Linux могут быть перенесены в среду Windows с помощью Cygwin и скомпилированы как локальные приложения Windows. Среда оболочки Linux, предоставляемая Cygwin, также позволяет использовать сценарии оболочки.

Исполняемые программы, созданные в среде Cygwin, являются собственными программами Windows, но отличаются от программ, созданных в Visual Studio тем, что программы, скомпилированные в Cygwin, должны зависеть от динамической библиотеки cygwin1.dll. Поскольку все вызовы функций POSIX должны проходить через эту динамическую библиотеку, которая переводит их в системные вызовы Windows (например, WinSock2), распространение программ Cygwin не так удобно, поскольку необходимо включать большой файл библиотеки cygwin1.dll. Кроме того, если приложение использует большое количество системных вызовов, использование Cygwin в качестве промежуточного слоя может привести к определённым накладным расходам и теоретически может снизить эффективность по сравнению с приложениями, созданными в Visual Studio.

В целом, если вы хотите быстро попробовать функции командной строки GmSSL в среде Windows и вам нужно использовать некоторые распространённые инструменты оболочки Linux для экспериментов и тестирования или вы не знакомы со средой разработки Visual Studio, то Cygwin может стать удобным выбором.

Подготовка среды Cygwin

Установка и настройка Cygwin выполняются с помощью единого приложения setup-x86_64.exe. Его можно загрузить с веб-сайта Cygwin https://www.cygwin.com/.

Обратите внимание, что при первой установке могут отсутствовать все необходимые программы. Вы можете запустить программу setup-x86_64.exe снова, чтобы настроить и обновить среду. Некоторые инструменты, такие как CMake, имеют собственные установочные пакеты для Windows. В среде Cygwin нет необходимости устанавливать эти инструменты отдельно, и это не рекомендуется. Все зависимые инструменты Linux должны управляться и настраиваться через среду Cygwin.

После установки и настройки вы можете открыть командную строку, запустив приложение Cygwin64 Terminal.

Компиляция GmSSL в среде Cygwin

Среда Cygwin имеет некоторые тонкие отличия от стандартной среды Linux. Во-первых, в командной строке Cygwin файловая система представляет собой структуру каталогов, подобную файловой системе Linux. Если исходный код уже загружен в операционную систему Windows (например, загружен в каталог пользователя «Downloads»), то сначала необходимо скопировать исходный код в файловую систему Cygwin пользователя (например, текущий каталог пользователя по умолчанию ~). В файловой системе Cygwin Windows файловая система отображается в каталоге /cygdrive, а файл GmSSL-master.zip из каталога «Downloads» текущего пользователя Guan Zhi отображается как /cygdrive/c/Users/Guan Zhi/Downloads/GmSSL-master.zip.

cp "/cygdrive/c/Users/Guan Zhi/Downloads/GmSSL-master.zip" ~/

Затем можно выполнить компиляцию и установку, следуя аналогичному процессу в среде Linux:

unzip GmSSL-master.zip
cd GmSSL-master
mkdir build
cd build
cmake ..
make
make test
make install

Поскольку пользователь сам обладает системными полномочиями в среде Cygwin, sudo не требуется при выполнении команды make install.

После завершения установки вы можете выполнить команду gmssl в командной строке Cygwin или запустить демонстрационный скрипт в исходном коде в каталоге demo.

Обратите внимание, что если вы попытаетесь скопировать исполняемые программы gmssl непосредственно из каталога Cygwin в файловую систему Windows, при запуске будет выдана ошибка о том, что не удалось найти cygwin1.dll. При запуске или распространении исполняемых программ необходимо решить проблему зависимости от этой динамической библиотеки.

Проблемы

Похоже, опция CMake BUILD_SHARED_LIBS не работает, всегда генерируя как статические, так и динамические библиотеки.

Динамические библиотеки Cygwin имеют особое название, начинающееся с cyg.

Далее в тексте идёт информация о компиляции для iOS и Android, а также о создании пакетов установки. Однако в запросе не было указано, что делать с этим текстом, поэтому он не переведён.