Halite

Halite は、その基盤となる暗号化操作のすべてを libsodium に依存する高水準暗号化インターフェースです。

Halite は、Paragon Initiative Enterprises によって、エコシステムの改善と PHP における暗号化 の安全性と実装の容易さを向上させる継続的な取り組みの結果として作成されました。

Halite ドキュメント はオンラインで読むことができます。

Halite は Mozilla Public License 2.0 のもとでリリースされています。派生作品を MPL の条件のもとで公開せずに Halite を拡張したい場合は、商用ライセンス を Paragon Initiative Enterprises から取得できます。

バックエンド Web アプリケーション向けの MPL ソフトウェアの条件に満足しているが、Halite を使用するアプリケーション向けのサポート契約を購入したい場合は、それも Paragon Initiative Enterprises が提供しています。

重要: 以前のバージョンの Halite は GNU Public License バージョン 3 (GPLv3) のもとで提供されていました。Mozilla Public License の条件のもとで利用できるのは Halite 4.0.1 以降のみです。

Halite のインストール

Halite を使用する前に、プロジェクトの要件に合うバージョンを選択する必要があります。利用可能な Halite のバージョンごとの要件の違いを以下に簡単に示します。

注: Halite 5.0.x は PHP 8.0 で動作しますが、パフォーマンスは PHP 8.1 よりも劣ります。

5.1 より前のバージョンの Halite が必要な場合は、そのブランチに固有のドキュメントを参照してください。

Halite をインストールするには、まず libsodium をインストール する必要があります。 PHP 拡張機能が必要な場合と不要な場合があります。ほとんどの人にとって、これは次のコマンドを実行することを意味します...

sudo apt-get install php7.2-sodium

...または、お使いのオペレーティングシステムと PHP バージョンに応じた同等のコマンドを実行します。

行き詰まった場合は、@aolko によるこのステップバイステップガイド が役立つかもしれません。

前提条件をインストールしたら、Composer を通じて Halite をインストールします:

composer require paragonie/halite:^5

旧バージョンの Halite 向け商用サポート

Halite の無料サポートは、最新のメジャーバージョン (現在は 5) にのみ適用されます。

お使いの企業で旧バージョンの Halite のサポートが必要な場合は、Paragon Initiative Enterprises にお問い合わせ のうえ、商用サポートのオプションについてご照会ください。

旧バージョンの Halite から簡単に移行する方法が必要な場合は、halite-legacy を確認してください。

プロジェクトで Halite を使用する

ドキュメント を確認してください。基本的な Halite API はシンプルさを重視して設計されています:

• 暗号化
  • 対称
    • 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 MB 未満など) でも大きなファイル (数ギガバイトなど) を暗号化できます。

<?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 からサポート契約を購入すること に関心があるかもしれません。