Halite

Halite es una interfaz de criptografía de alto nivel que depende de libsodium para todas sus operaciones criptográficas subyacentes.

Halite fue creado por Paragon Initiative Enterprises como resultado de nuestros continuos esfuerzos por mejorar el ecosistema y hacer que la criptografía en PHP sea más segura y fácil de implementar.

Puedes leer la Documentación de Halite en línea.

Halite se publica bajo la Mozilla Public License 2.0. Hay licencias comerciales disponibles en Paragon Initiative Enterprises si deseas extender Halite sin tener que disponibilizar tus obras derivadas bajo los términos de la MPL.

Si estás satisfecho con los términos del software MPL para aplicaciones web backend pero deseas adquirir un contrato de soporte para tu aplicación que utiliza Halite, también se ofrecen en Paragon Initiative Enterprises.

Importante: Las versiones anteriores de Halite estaban disponibles bajo la GNU Public License versión 3 (GPLv3). Solo Halite 4.0.1 y versiones posteriores están disponibles bajo los términos de la Mozilla Public License.

Instalación de Halite

Antes de que puedas usar Halite, debes elegir una versión que se ajuste a los requisitos de tu proyecto. Las diferencias entre los requisitos de las versiones disponibles de Halite se resumen brevemente a continuación.

Nota: Halite 5.0.x funciona en PHP 8.0, pero el rendimiento es peor que en PHP 8.1.

Si necesitas una versión de Halite anterior a la 5.1, consulta la documentación relevante para esa rama en particular.

Para instalar Halite, primero debes instalar libsodium. Puede que necesites o no la extensión de PHP. Para la mayoría de las personas, esto significa ejecutar...

sudo apt-get install php7.2-sodium

...o un comando equivalente para tu sistema operativo y versión de PHP.

Si estás atascado, esta guía paso a paso contribuida por @aolko puede ser útil.

Una vez que tengas los requisitos previos instalados, instala Halite a través de Composer:

composer require paragonie/halite:^5

Soporte comercial para versiones antiguas de Halite

El soporte gratuito (gratis) para Halite solo se extiende a la versión principal más reciente (actualmente la 5).

Si tu empresa requiere soporte para una versión anterior de Halite, contacta con Paragon Initiative Enterprises para consultar las opciones de soporte comercial.

Si necesitas una forma sencilla de migrar desde versiones anteriores de Halite, consulta halite-legacy.

Usando Halite en tu Proyecto

Consulta la documentación. La API básica de Halite está diseñada para la simplicidad:

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

Ejemplo: Cifrar y descifrar un mensaje

Primero, genera y persiste una clave una sola vez:

<?php
use ParagonIE\Halite\KeyFactory;

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

Y luego puedes cifrar/descifrar mensajes de la siguiente manera:

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

Esto debería producir algo similar a:

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

Claves criptográficas en Halite

Importante: Halite trabaja con objetos Key, no con cadenas.

Si intentas hacer echo de un objeto clave, obtendrás una cadena vacía en lugar de su contenido. Si intentas hacer var_dump() de un objeto clave, solo obtendrás algunos datos sobre el tipo de clave que es.

Debes invocar $obj->getRawKeyMaterial() explícitamente si quieres inspeccionar el contenido binario crudo de una clave. Esto no se recomienda para la mayoría de los casos de uso.

Ejemplo: Generar una clave a partir de una contraseña

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

Una clave derivada de una contraseña se puede utilizar en lugar de una generada aleatoriamente.

Ejemplo: Cifrar un archivo grande en un sistema con poca memoria

Halite incluye una clase de criptografía de archivos que utiliza una API de transmisión para permitir que archivos grandes (por ejemplo, gigabytes) se cifren en un sistema con muy poca memoria disponible (es decir, 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 comunes de soporte

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

La solución a esto es asegurarse de que libsodium esté instalado/habilitado. Consulta más arriba en este README para más información.

Contratos de soporte

Si tu empresa utiliza esta librería en sus productos o servicios, puede que te interese adquirir un contrato de soporte de Paragon Initiative Enterprises.