Halite

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

Halite был создан Paragon Initiative Enterprises в рамках наших постоянных усилий по улучшению экосистемы и повышению безопасности и простоты внедрения криптографии в PHP.

Вы можете прочитать документацию Halite онлайн.

Halite выпускается под лицензией Mozilla Public License 2.0. Коммерческие лицензии доступны в Paragon Initiative Enterprises, если вы хотите расширить Halite, не распространяя свои производные работы на условиях MPL.

Если вас устраивают условия MPL-программного обеспечения для серверных веб-приложений, но вы хотели бы приобрести контракт на поддержку для своего приложения, использующего Halite, такие контракты также предлагаются Paragon Initiative Enterprises.

Важно: Более ранние версии Halite были доступны под GNU Public License версии 3 (GPLv3). Только Halite 4.0.1 и новее доступны на условиях Mozilla Public License.

Установка Halite

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

Примечание: Halite 5.0.x работает на PHP 8.0, но производительность ниже, чем на PHP 8.1.

Если вам нужна версия Halite до 5.1, обратитесь к документации, соответствующей этой конкретной ветке.

Чтобы установить Halite, сначала необходимо установить libsodium. Расширение PHP может понадобиться, а может и нет. Для большинства людей это означает выполнение...

sudo apt-get install php7.2-sodium

...или эквивалентной команды для вашей операционной системы и версии PHP.

Если у вас возникли трудности, может помочь это пошаговое руководство, предоставленное @aolko.

После установки необходимых компонентов установите Halite через Composer:

composer require paragonie/halite:^5

Коммерческая поддержка старых версий Halite

Бесплатная поддержка Halite распространяется только на самую последнюю основную версию (в настоящее время 5).

Если вашей компании требуется поддержка более старой версии Halite, свяжитесь с Paragon Initiative Enterprises, чтобы узнать о вариантах коммерческой поддержки.

Если вам нужен простой способ миграции со старых версий Halite, обратите внимание на halite-legacy.

Использование Halite в вашем проекте

Ознакомьтесь с документацией. Базовый API Halite спроектирован с упором на простоту:

• Шифрование
  • Симметричное
    • Symmetric\Crypto::encrypt(HiddenString, EncryptionKey): string
    • Symmetric\Crypto::encryptWithAD(HiddenString, EncryptionKey, string): string
    • Symmetric\Crypto::decrypt(string, ):

Пример: шифрование и дешифрование сообщения

Сначала сгенерируйте и сохраните ключ ровно один раз:

<?php
use ParagonIE\Halite\KeyFactory;

$encKey = KeyFactory::generateEncryptionKey();
KeyFactory::save($encKey, '/path/outside/webroot/encryption.key');

После этого вы можете шифровать/дешифровать сообщения следующим образом:

<?php
use ParagonIE\Halite\KeyFactory;
use ParagonIE\Halite\Symmetric\Crypto as Symmetric;
use ParagonIE\HiddenString\HiddenString;

$encryptionKey = KeyFactory::loadEncryptionKey('/path/outside/webroot/encryption.key');

$message = new HiddenString('This is a confidential message for your eyes only.');
$ciphertext = Symmetric::encrypt($message, $encryptionKey);

$decrypted = Symmetric::decrypt($ciphertext, $encryptionKey);

var_dump($decrypted->getString() === $message->getString()); // bool(true)

В результате должно получиться нечто похожее на:

MUIDAEpQznohvNlQ-ZRk-ZZ59Mmox75D_FgAIrXY2cUfStoeL-GIeAe0m-uaeURQdPsVmc5XxRw3-2x5ZAsZH_es37qqFuLFjUI-XK9uG0s30YTsorWfpHdbnqzhRuUOI09c-cKrfMQkNBNm0dDDwZazjTC48zWikRHSHXg8NXerVDebzng1aufc_S-osI_zQuLbZDODujEnpbPZhMMcm4-SWuyVXcBPdGZolJyT

Криптографические ключи в Halite

Важно: Halite работает с объектами Key, а не со строками.

Если вы попытаетесь выполнить echo объекта ключа, вы получите пустую строку, а не его содержимое. Если вы попытаетесь выполнить var_dump() для объекта ключа, вы получите только некоторые сведения о типе этого ключа.

Чтобы просмотреть необработанное бинарное содержимое ключа, необходимо явно вызвать $obj->getRawKeyMaterial(). В большинстве случаев делать это не рекомендуется.

Пример: создание ключа из пароля

<?php
use ParagonIE\Halite\KeyFactory;
use ParagonIE\HiddenString\HiddenString;

$passwd = new HiddenString('correct horse battery staple');
// Use random_bytes(16); to generate the salt:
$salt = "\xdd\x7b\x1e\x38\x75\x9f\x72\x86\x0a\xe9\xc8\x58\xf6\x16\x0d\x3b";

$encryptionKey = KeyFactory::deriveEncryptionKey($passwd, $salt);

Ключ, полученный из пароля, можно использовать вместо случайно сгенерированного.

Пример: шифрование большого файла в системе с малым объёмом памяти

Halite включает класс для криптографической работы с файлами, который использует потоковый API, позволяя шифровать большие файлы (например, гигабайты) в системе с очень небольшим объёмом доступной памяти (т.е. менее 8 МБ).

<?php
use ParagonIE\Halite\File;
use ParagonIE\Halite\KeyFactory;

$encryptionKey = KeyFactory::loadEncryptionKey('/path/outside/webroot/encryption.key');

File::encrypt('input.txt', 'output.txt', $encryptionKey);

Распространённые проблемы поддержки

Uncaught SodiumException: Cannot Wipe Memory

PHP Fatal error: Uncaught SodiumException: This is not implemented, as it is not possible to securely wipe memory from PHP

Решение — убедиться, что libsodium установлен и включён. Дополнительную информацию см. выше в этом README.

Контракты на поддержку

Если ваша компания использует эту библиотеку в своих продуктах или услугах, вас может заинтересовать приобретение контракта на поддержку у Paragon Initiative Enterprises.