Halite

Halite é uma interface de criptografia de alto nível que depende do libsodium para todas as suas operações de criptografia subjacentes.

Halite foi criado pela Paragon Initiative Enterprises como resultado de nossos esforços contínuos para melhorar o ecossistema e tornar a criptografia em PHP mais segura e fácil de implementar.

Você pode ler a Documentação do Halite online.

Halite é distribuído sob a Mozilla Public License 2.0. Licenças comerciais estão disponíveis na Paragon Initiative Enterprises se você desejar estender o Halite sem disponibilizar seus trabalhos derivados sob os termos da MPL.

Se você está satisfeito com os termos do software MPL para aplicações web de backend, mas gostaria de adquirir um contrato de suporte para sua aplicação que usa Halite, eles também são oferecidos pela Paragon Initiative Enterprises.

Importante: Versões anteriores do Halite estavam disponíveis sob a GNU Public License versão 3 (GPLv3). Apenas Halite 4.0.1 e mais recentes estão disponíveis sob os termos da Mozilla Public License.

Instalando o Halite

Antes de usar o Halite, você deve escolher uma versão que atenda aos requisitos do seu projeto. As diferenças entre os requisitos das versões disponíveis do Halite são brevemente destacadas abaixo.

Nota: Halite 5.0.x funciona no PHP 8.0, mas o desempenho é pior do que no PHP 8.1.

Se você precisar de uma versão do Halite anterior à 5.1, consulte a documentação relevante para esse ramo específico.

Para instalar o Halite, você primeiro precisa instalar o libsodium. Você pode ou não precisar da extensão PHP. Para a maioria das pessoas, isso significa executar...

sudo apt-get install php7.2-sodium

...ou um comando equivalente para o seu sistema operacional e versão do PHP.

Se você estiver com dificuldades, este guia passo a passo contribuído por @aolko pode ser útil.

Depois de instalar os pré-requisitos, instale o Halite via Composer:

composer require paragonie/halite:^5

Suporte Comercial para Versões Antigas do Halite

O suporte gratuito (sem custo) para o Halite se estende apenas à versão principal mais recente (atualmente a 5).

Se sua empresa precisar de suporte para uma versão antiga do Halite, entre em contato com a Paragon Initiative Enterprises para saber sobre as opções de suporte comercial.

Se você precisar de uma maneira fácil de migrar de versões antigas do Halite, confira halite-legacy.

Usando o Halite em Seu Projeto

Consulte a documentação. A API básica do Halite é projetada para simplicidade:

• Criptografia
  • Simétrica
    • Symmetric\Crypto::encrypt(HiddenString, EncryptionKey): string
    • Symmetric\Crypto::encryptWithAD(HiddenString, EncryptionKey, string): string
    • Symmetric\Crypto::decrypt(string, ):

Exemplo: Criptografando e Descriptografando uma mensagem

Primeiro, gere e persista uma chave exatamente uma vez:

<?php
use ParagonIE\Halite\KeyFactory;

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

E então você pode criptografar/descriptografar mensagens assim:

<?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)

Isso deve produzir algo semelhante a:

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

Chaves Criptográficas no Halite

Importante: o Halite trabalha com objetos Key, não com strings.

Se você tentar usar echo em um objeto de chave, obterá uma string vazia em vez de seu conteúdo. Se você tentar usar var_dump() em um objeto de chave, obterá apenas alguns fatos sobre o tipo de chave que ele é.

Você deve invocar $obj->getRawKeyMaterial() explicitamente se quiser inspecionar o conteúdo binário bruto de uma chave. Isso não é recomendado para a maioria dos casos de uso.

Exemplo: Gerando uma chave a partir de uma senha

<?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);

Uma chave derivada de uma senha pode ser usada no lugar de uma gerada aleatoriamente.

Exemplo: Criptografando um arquivo grande em um sistema com pouca memória

O Halite inclui uma classe de criptografia de arquivos que utiliza uma API de streaming para permitir que arquivos grandes (ex.: gigabytes) sejam criptografados em um sistema com muito pouca memória disponível (ou seja, menos de 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);

Problemas Comuns de Suporte

SodiumException Não Capturada: Cannot Wipe Memory

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

A solução para isso é garantir que o libsodium esteja instalado/habilitado. Veja acima neste README para mais informações.

Contratos de Suporte

Se sua empresa usa esta biblioteca em seus produtos ou serviços, você pode ter interesse em adquirir um contrato de suporte da Paragon Initiative Enterprises.