sodium_compat
Version 2.1.0
Sodium Compat es un polyfill de PHP puro para la biblioteca de criptografía de sodio (libsodium), una extensión principal en PHP 7.2.0+ y disponible en PECL.
Si tiene instalada la extensión PHP, Sodium Compat utilizará de manera oportunista y transparente la extensión PHP en lugar de nuestra implementación.
sodio_compat v1.21.0 fue la última versión v1.x de la rama maestra. De ahora en adelante, todas las versiones futuras que admitan PHP 5.2 - 8.0 y enteros de 32 bits estarán en la rama v1.x
Las versiones más nuevas de sodio_compat (es decir, v2.0.0) seguirán viviendo en la rama maestra, a menos que se necesite una nueva versión principal. El objetivo de este trabajo es mejorar la legibilidad y el rendimiento del código, al tiempo que se reduce el código repetitivo.
En caso de duda, consulte el archivo README en la rama master para obtener la información más reciente sobre la versión.
| versión de compatibilidad de sodio | Versiones de PHP compatibles | ¿Soporte de 32 bits? | Rama |
|---|---|---|---|
v1.xy | 5.2.4 - ÚLTIMO | SÍ | v1.x |
v2.xy | 8.1 - ÚLTIMO | NO | maestro |
Si necesita compatibilidad con PHP de 32 bits ( PHP_INT_SIZE == 4 ), continúe usando sodio_compat v1.x. Si desea un rendimiento mejorado y dependencias más pequeñas, utilice v2.x.
Recomendamos que las bibliotecas y los marcos establezcan una restricción de versión de Composer de la siguiente manera:
{
"require" : {
/* ... */
"paragonie/sodium_compat" : ">= 1"
/* ... */
}
}Por el contrario, las aplicaciones deben especificar la versión real que les importa y sus implementaciones.
Esta biblioteca de criptografía no ha sido auditada formalmente por un tercero independiente que se especialice en criptografía o criptoanálisis.
Si necesita una auditoría de este tipo antes de poder usar sodio_compat en sus proyectos y tener los fondos para dicha auditoría, abra un problema o comuníquese security at paragonie dot com para que podamos ayudarlo a poner las cosas en marcha.
Sin embargo, sodio_compat ha sido adoptado por proyectos de código abierto de alto perfil, como Joomla! y Magento. Además, sodio_compat fue desarrollado por Paragon Initiative Enterprises, una empresa que se especializa en desarrollo PHP seguro y criptografía PHP, y ha sido revisado informalmente por muchos otros expertos en seguridad que también se especializan en PHP.
Si desea obtener más información sobre las medidas de seguridad defensivas que hemos tomado para evitar que sodio_compat sea una fuente de vulnerabilidad en sus sistemas, lea Desarrollo PHP criptográficamente seguro .
Si estás usando Composer:
composer require paragonie/sodium_compat Si no está utilizando Composer, descargue un archivo tar de lanzamiento (que debe estar firmado con nuestra clave pública GnuPG), extraiga su contenido y luego incluya nuestro script autoload.php en su proyecto.
<?php
require_once " /path/to/sodium_compat/autoload.php " ;Desde la versión 1.3.0, las versiones de sodio_compat incluyen un archivo PHP (archivo .phar) y una firma GPG asociada. Primero, descargue ambos archivos y verifíquelos con nuestra clave pública GPG, así:
# Getting our public key from the keyserver:
gpg --fingerprint 7F52D5C61D1255C731362E826B97A1C2826404DA
if [ $? -ne 0 ] ; then
echo -e " 33[33mDownloading PGP Public Key... 33[0m "
gpg --keyserver pgp.mit.edu --recv-keys 7F52D5C61D1255C731362E826B97A1C2826404DA
# Security <[email protected]>
gpg --fingerprint 7F52D5C61D1255C731362E826B97A1C2826404DA
if [ $? -ne 0 ] ; then
echo -e " 33[31mCould not download PGP public key for verification 33[0m "
exit 1
fi
fi
# Verifying the PHP Archive
gpg --verify sodium-compat.phar.sig sodium-compat.pharAhora, simplemente incluya este archivo .phar en su aplicación.
<?php
require_once " /path/to/sodium-compat.phar " ;El soporte comercial para libsodium está disponible a través de varios proveedores. Si necesita ayuda para utilizar sodio_compat en uno de sus proyectos, comuníquese con Paragon Initiative Enterprises.
Los informes no comerciales se facilitarán a través de ediciones de Github. No ofrecemos garantías de nuestra disponibilidad para resolver preguntas sobre la integración de sodio_compat en software de terceros de forma gratuita, pero nos esforzaremos por corregir cualquier error (relacionado con la seguridad o de otro tipo) en nuestra biblioteca.
Si su empresa utiliza esta biblioteca en sus productos o servicios, es posible que le interese adquirir un contrato de soporte de Paragon Initiative Enterprises.
Según la segunda votación en el RFC de libsodium, PHP 7.2 usa sodium_* en lugar de Sodium* .
<?php
require_once " /path/to/sodium_compat/autoload.php " ;
$ alice_kp = sodium_crypto_sign_keypair ();
$ alice_sk = sodium_crypto_sign_secretkey ( $ alice_kp );
$ alice_pk = sodium_crypto_sign_publickey ( $ alice_kp );
$ message = ' This is a test message. ' ;
$ signature = sodium_crypto_sign_detached ( $ message , $ alice_sk );
if ( sodium_crypto_sign_verify_detached ( $ signature , $ message , $ alice_pk )) {
echo ' OK ' , PHP_EOL ;
} else {
throw new Exception ( ' Invalid signature ' );
} Si sus usuarios usan PHP < 5.3, o desea escribir código que funcione independientemente de que la extensión PECL esté disponible o no, querrá usar la clase ParagonIE_Sodium_Compat para la mayoría de sus necesidades de libsodium.
El ejemplo anterior, escrito para uso general:
<?php
require_once " /path/to/sodium_compat/autoload.php " ;
$ alice_kp = ParagonIE_Sodium_Compat:: crypto_sign_keypair ();
$ alice_sk = ParagonIE_Sodium_Compat:: crypto_sign_secretkey ( $ alice_kp );
$ alice_pk = ParagonIE_Sodium_Compat:: crypto_sign_publickey ( $ alice_kp );
$ message = ' This is a test message. ' ;
$ signature = ParagonIE_Sodium_Compat:: crypto_sign_detached ( $ message , $ alice_sk );
if (ParagonIE_Sodium_Compat:: crypto_sign_verify_detached ( $ signature , $ message , $ alice_pk )) {
echo ' OK ' , PHP_EOL ;
} else {
throw new Exception ( ' Invalid signature ' );
} Generalmente: si reemplaza sodium_ con ParagonIE_Sodium_Compat:: , cualquier código ya escrito para la extensión PHP libsodium debería funcionar con nuestro polyfill sin cambios de código adicionales.
Dado que esto no requiere un espacio de nombres, esta API está expuesta en PHP 5.2.
Desde la versión 0.7.0, tenemos nuestra propia API con espacio de nombres ( ParagonIESodium* ) para permitir la brevedad en el software que utiliza PHP 5.3+. Esto es útil si desea utilizar nuestras funciones de criptografía de archivos sin escribir ParagonIE_Sodium_File cada vez. Esto no está expuesto en PHP < 5.3, por lo que si su proyecto admite PHP < 5.3, utilice el método de guión bajo.
Para aprender a usar Libsodium, lea Uso de Libsodium en proyectos PHP .
Hay tres formas de hacerlo rápido:
ParagonIE_Sodium_Compat::$fastMult = true; sin dañar la seguridad de sus claves criptográficas. Si su procesador no es seguro, decida si desea velocidad o seguridad porque no puede tener ambas. Desde la versión 1.8, puede utilizar el método estático polyfill_is_fast() para determinar si sodio_compat será lento en tiempo de ejecución.
<?php
if (ParagonIE_Sodium_Compat:: polyfill_is_fast ()) {
// Use libsodium now
$ process -> execute ();
} else {
// Defer to a cron job or other sort of asynchronous process
$ process -> enqueue ();
}Primero, querrás leer la Referencia rápida de Libsodium. Su objetivo es responder: "¿Qué función debo utilizar para [problema común]?".
Si no encuentra las respuestas en la página de Referencia rápida, consulte Uso de Libsodium en proyectos PHP .
Finalmente, la documentación oficial de libsodium (que fue escrita para la biblioteca C, no para la biblioteca PHP) también contiene mucha información técnica reveladora que puede resultarle útil.
Lectura recomendada: Referencia rápida de Libsodium
crypto_auth()crypto_auth_verify()crypto_box()crypto_box_open()crypto_scalarmult()crypto_secretbox()crypto_secretbox_open()crypto_sign()crypto_sign_open()crypto_aead_aegis128l_encrypt()crypto_aead_aegis128l_decrypt()crypto_aead_aegis256_encrypt()crypto_aead_aegis256_decrypt()crypto_aead_aes256gcm_encrypt()crypto_aead_aes256gcm_decrypt()crypto_aead_chacha20poly1305_encrypt()crypto_aead_chacha20poly1305_decrypt()crypto_aead_chacha20poly1305_ietf_encrypt()crypto_aead_chacha20poly1305_ietf_decrypt()crypto_aead_xchacha20poly1305_ietf_encrypt()crypto_aead_xchacha20poly1305_ietf_decrypt()crypto_box_xchacha20poly1305()crypto_box_xchacha20poly1305_open()crypto_box_seal()crypto_box_seal_open()crypto_generichash()crypto_generichash_init()crypto_generichash_update()crypto_generichash_final()crypto_kx()crypto_secretbox_xchacha20poly1305()crypto_secretbox_xchacha20poly1305_open()crypto_shorthash()crypto_sign_detached()crypto_sign_ed25519_pk_to_curve25519()crypto_sign_ed25519_sk_to_curve25519()crypto_sign_verify_detached()crypto_core_ristretto255_add()crypto_core_ristretto255_from_hash()crypto_core_ristretto255_is_valid_point()crypto_core_ristretto255_random()crypto_core_ristretto255_scalar_add()crypto_core_ristretto255_scalar_complement()crypto_core_ristretto255_scalar_invert()crypto_core_ristretto255_scalar_mul()crypto_core_ristretto255_scalar_negate()crypto_core_ristretto255_scalar_random()crypto_core_ristretto255_scalar_reduce()crypto_core_ristretto255_scalar_sub()crypto_core_ristretto255_sub()crypto_scalarmult_ristretto255_base()crypto_scalarmult_ristretto255()crypto_stream()crypto_stream_keygen()crypto_stream_xor()crypto_stream_xchacha20()crypto_stream_xchacha20_keygen()crypto_stream_xchacha20_xor()crypto_stream_xchacha20_xor_ic()crypto_*_keypair() )add()base642bin()bin2base64()bin2hex()hex2bin()crypto_kdf_derive_from_key()crypto_kx_client_session_keys()crypto_kx_server_session_keys()crypto_secretstream_xchacha20poly1305_init_push()crypto_secretstream_xchacha20poly1305_push()crypto_secretstream_xchacha20poly1305_init_pull()crypto_secretstream_xchacha20poly1305_pull()crypto_secretstream_xchacha20poly1305_rekey()pad()unpad() sodium_memzero() : aunque exponemos este punto final de API, no podemos poner a cero de manera confiable los búferes desde PHP.
Si tiene instalada la extensión PHP, sodio_compat utilizará la implementación nativa para poner a cero la cadena proporcionada. De lo contrario, arrojará una SodiumException .
sodium_crypto_pwhash() : no es factible realizar un polyfill de scrypt o Argon2 en PHP y obtener un rendimiento razonable. Los usuarios se sentirían motivados a seleccionar parámetros que reduzcan la seguridad para evitar ataques de denegación de servicio (DoS).
El único movimiento ganador es no jugar.
Si ext/sodium o ext/libsodium están instalados, estos métodos API pasarán a la extensión. De lo contrario, nuestra biblioteca polyfill generará una SodiumException .
Para detectar compatibilidad con Argon2i en tiempo de ejecución, utilice ParagonIE_Sodium_Compat::crypto_pwhash_is_available() , que devuelve un valor booleano ( TRUE o FALSE ).
La API HKDF de Libsodium ( crypto_kdf_hkdf_*() ) no está incluida porque PHP tiene sus propias características HMAC y no se consideró necesaria.
Para los usuarios de sodio_compat y que utilizan PHPCompatibility en su proceso de CI, ahora hay un conjunto de reglas personalizado disponible que se puede usar para evitar que PHPCompatibility arroje falsos positivos para la funcionalidad PHP nativa que este repositorio completa en forma policompleta.
Puede encontrar el repositorio del conjunto de reglas PHPCompatibilityParagonieSodiumCompat aquí en Github y en Packagist.
