halite

Галит

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

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

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

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

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

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

Установка Халита

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

	PHP	либнатрий	PECL либнатрий	Поддерживать
Халит 5.1 и новее	8.1.0	1.0.18	Н/Д (стандарт)	Активный
Галит 5.0.x	8.0.0	1.0.18	Н/Д (стандарт)	Активный
Галит 4.1+	7.2.0	1.0.15	Н/Д (стандарт)	Не поддерживается
Галит 4.0	7.2.0	1.0.13	Н/Д (стандарт)	Не поддерживается
Галит 3	7.0.0	1.0.9	1.0.6/2.0.4	Не поддерживается
Галит 2	7.0.0	1.0.9	1.0.6	Не поддерживается
Галит 1	5.6.0	1.0.6	1.0.2	Не поддерживается

Примечание. 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 разработан для простоты:

• Шифрование
  • Симметричный
    • SymmetricCrypto::encrypt ( HiddenString , EncryptionKey ): string
    • SymmetricCrypto::encryptWithAD ( HiddenString , EncryptionKey , string ): string
    • SymmetricCrypto::decrypt ( string , EncryptionKey ): HiddenString
    • SymmetricCrypto::decryptWithAD ( string , EncryptionKey , string ): HiddenString
  • Асимметричный
    • Анонимный
      • AsymmetricCrypto::seal ( HiddenString , EncryptionPublicKey ): string
      • AsymmetricCrypto::unseal ( string , EncryptionSecretKey ): HiddenString
    • Аутентифицированный
      • AsymmetricCrypto::encrypt ( HiddenString , EncryptionSecretKey , EncryptionPublicKey ): string
      • AsymmetricCrypto::encryptWithAD ( HiddenString , EncryptionSecretKey , EncryptionPublicKey , string ): string
      • AsymmetricCrypto::decrypt ( string , EncryptionSecretKey , EncryptionPublicKey ): HiddenString
      • AsymmetricCrypto::decryptWithAD ( string , EncryptionSecretKey , EncryptionPublicKey , string ): HiddenString
• Аутентификация
  • Симметричный
    • SymmetricCrypto::authenticate ( string , AuthenticationKey ): string
    • SymmetricCrypto::verify ( string , AuthenticationKey , string ): bool
  • Асимметричный
    • AsymmetricCrypto::sign ( string , SignatureSecretKey ): string
    • AsymmetricCrypto::verify ( string , SignaturePublicKey , string ): bool

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

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

 <?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 = "xddx7bx1ex38x75x9fx72x86x0axe9xc8x58xf6x16x0dx3b" ;

$ 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: невозможно стереть память

Неустранимая ошибка PHP: Uncaught SodiumException: это не реализовано, поскольку невозможно безопасно стереть память из PHP.

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

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

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