Halite

Halite는 모든 내부 암호화 작업을 libsodium에 의존하는 고수준 암호화 인터페이스입니다.

Halite는 Paragon Initiative Enterprises가 생태계를 개선하고 PHP에서의 암호화를 더 안전하고 구현하기 쉽게 만들기 위한 지속적인 노력의 결과로 만들었습니다.

Halite 문서를 온라인에서 읽을 수 있습니다.

Halite는 Mozilla Public License 2.0으로 배포됩니다. 파생 저작물을 MPL 조건으로 공개하지 않고 Halite를 확장하려는 경우 Paragon Initiative Enterprises에서 상업용 라이선스를 제공합니다.

백엔드 웹 애플리케이션용 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');
// 솔트를 생성하려면 random_bytes(16); 사용:
$salt = "\xdd\x7b\x1e\x38\x75\x9f\x72\x86\x0a\xe9\xc8\x58\xf6\x16\x0d\x3b";

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

비밀번호에서 파생된 키는 무작위로 생성된 키 대신 사용할 수 있습니다.

예제: 메모리가 적은 시스템에서 대용량 파일 암호화하기

Halite에는 스트리밍 API를 활용하는 파일 암호화 클래스가 포함되어 있어 사용 가능한 메모리가 매우 적은(예: 8MB 미만) 시스템에서 대용량 파일(예: 기가바이트)을 암호화할 수 있습니다.

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

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

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

일반적인 지원 문제

포착되지 않은 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의 지원 계약 구매에 관심이 있을 수 있습니다.