sodium_compat
Version 2.1.0
Sodium Compat est un polyfill PHP pur pour la bibliothèque de cryptographie Sodium (libsodium), une extension principale de PHP 7.2.0+ et autrement disponible dans PECL.
Si l'extension PHP est installée, Sodium Compat utilisera de manière opportuniste et transparente l'extension PHP au lieu de notre implémentation.
sodium_compat v1.21.0 était la dernière version v1.x de la branche master. Désormais, toutes les futures versions prenant en charge PHP 5.2 - 8.0 et les entiers 32 bits seront dans la branche v1.x
Les versions plus récentes de sodium_compat (c'est-à-dire v2.0.0) continueront à vivre dans la branche master, à moins qu'une nouvelle version majeure ne soit nécessaire. L’objectif de ce travail est d’améliorer la lisibilité et les performances du code, tout en réduisant le code passe-partout.
En cas de doute, reportez-vous au fichier README dans la branche master pour obtenir les dernières informations sur la version.
| version sodium_compat | Versions PHP prises en charge | Prise en charge 32 bits ? | Bifurquer |
|---|---|---|---|
v1.xy | 5.2.4 - DERNIÈRES | OUI | v1.x |
v2.xy | 8.1 - DERNIÈRES | NON | maître |
Si vous avez besoin du support PHP 32 bits ( PHP_INT_SIZE == 4 ), continuez à utiliser sodium_compat v1.x. Si vous souhaitez des performances améliorées et des dépendances plus petites, utilisez la v2.x.
Nous recommandons aux bibliothèques et aux frameworks de définir une contrainte de version Composer comme suit :
{
"require" : {
/* ... */
"paragonie/sodium_compat" : ">= 1"
/* ... */
}
}Les applications doivent, à l’inverse, spécifier la version réelle qui compte pour elles et pour leurs déploiements.
Cette bibliothèque de cryptographie n'a pas été formellement auditée par un tiers indépendant spécialisé dans la cryptographie ou la cryptanalyse.
Si vous avez besoin d'un tel audit avant de pouvoir utiliser sodium_compat dans vos projets et disposer des fonds pour un tel audit, veuillez ouvrir un problème ou contacter security at paragonie dot com afin que nous puissions vous aider à lancer le processus.
Cependant, sodium_compat a été adopté par des projets open source de grande envergure, tels que Joomla! et Magento. De plus, sodium_compat a été développé par Paragon Initiative Enterprises, une société spécialisée dans le développement PHP sécurisé et la cryptographie PHP, et a été examiné de manière informelle par de nombreux autres experts en sécurité également spécialisés dans PHP.
Si vous souhaitez en savoir plus sur les mesures de sécurité défensives que nous avons prises pour empêcher sodium_compat d'être une source de vulnérabilité dans vos systèmes, veuillez lire Développement PHP cryptographiquement sécurisé .
Si vous utilisez Composer :
composer require paragonie/sodium_compat Si vous n'utilisez pas Composer, téléchargez une archive tar de version (qui doit être signée avec notre clé publique GnuPG), extrayez son contenu, puis incluez notre script autoload.php dans votre projet.
<?php
require_once " /path/to/sodium_compat/autoload.php " ;Depuis la version 1.3.0, les versions sodium_compat incluent une archive PHP (fichier .phar) et la signature GPG associée. Tout d'abord, téléchargez les deux fichiers et vérifiez-les avec notre clé publique GPG, comme ceci :
# 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.pharMaintenant, incluez simplement ce fichier .phar dans votre application.
<?php
require_once " /path/to/sodium-compat.phar " ;Un support commercial pour libsodium est disponible auprès de plusieurs fournisseurs. Si vous avez besoin d'aide pour utiliser sodium_compat dans l'un de vos projets, contactez Paragon Initiative Enterprises.
Le rapport non commercial sera facilité via les problèmes Github. Nous n'offrons aucune garantie quant à notre disponibilité pour résoudre gratuitement les questions concernant l'intégration de sodium_compat dans des logiciels tiers, mais nous nous efforcerons de corriger tout bug (lié à la sécurité ou autre) dans notre bibliothèque.
Si votre entreprise utilise cette bibliothèque dans ses produits ou services, vous pourriez être intéressé par l'achat d'un contrat de support auprès de Paragon Initiative Enterprises.
Conformément au deuxième vote sur la RFC libsodium, PHP 7.2 utilise sodium_* au lieu 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 vos utilisateurs utilisent PHP < 5.3 ou si vous souhaitez écrire du code qui fonctionnera que l'extension PECL soit disponible ou non, vous souhaiterez utiliser la classe ParagonIE_Sodium_Compat pour la plupart de vos besoins en libsodium.
L'exemple ci-dessus, écrit pour un usage général :
<?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 ' );
} Généralement : si vous remplacez sodium_ par ParagonIE_Sodium_Compat:: , tout code déjà écrit pour l'extension PHP libsodium devrait fonctionner avec notre polyfill sans modifications de code supplémentaires.
Comme cela ne nécessite pas d'espace de noms, cette API est exposée sur PHP 5.2.
Depuis la version 0.7.0, nous disposons de notre propre API avec espace de noms ( ParagonIESodium* ) pour permettre la concision des logiciels qui utilisent PHP 5.3+. Ceci est utile si vous souhaitez utiliser nos fonctionnalités de cryptographie de fichiers sans écrire ParagonIE_Sodium_File à chaque fois. Ceci n'est pas exposé sur PHP < 5.3, donc si votre projet prend en charge PHP < 5.3, utilisez plutôt la méthode de soulignement.
Pour savoir comment utiliser Libsodium, lisez Utilisation de Libsodium dans les projets PHP .
Il existe trois façons de le rendre rapide :
ParagonIE_Sodium_Compat::$fastMult = true; sans nuire à la sécurité de vos clés de cryptographie. Si votre processeur n'est pas sûr, décidez si vous souhaitez de la vitesse ou de la sécurité, car vous ne pouvez pas avoir les deux. Depuis la version 1.8, vous pouvez utiliser la méthode statique polyfill_is_fast() pour déterminer si sodium_compat sera lent à l'exécution.
<?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 ();
}Tout d’abord, vous voudrez lire la référence rapide Libsodium. Il vise à répondre : « Quelle fonction dois-je utiliser pour [problème courant] ?
Si vous ne trouvez pas les réponses dans la page de référence rapide, consultez Utilisation de Libsodium dans les projets PHP .
Enfin, la documentation officielle de libsodium (qui a été écrite pour la bibliothèque C, pas pour la bibliothèque PHP) contient également de nombreuses informations techniques utiles qui pourraient vous être utiles.
Lecture recommandée : Référence rapide 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() - Bien que nous exposions ce point de terminaison d'API, nous ne pouvons pas mettre à zéro de manière fiable les tampons de PHP.
Si l'extension PHP est installée, sodium_compat utilisera l'implémentation native pour mettre à zéro la chaîne fournie. Sinon, il lancera une SodiumException .
sodium_crypto_pwhash() - Il n'est pas possible de polyfiller scrypt ou Argon2 dans PHP et d'obtenir des performances raisonnables. Les utilisateurs se sentiraient motivés à sélectionner des paramètres qui dégradent la sécurité pour éviter les attaques par déni de service (DoS).
Le seul geste gagnant est de ne pas jouer.
Si ext/sodium ou ext/libsodium est installé, ces méthodes API passeront à l'extension. Sinon, notre bibliothèque polyfill lancera une SodiumException .
Pour détecter la prise en charge d'Argon2i au moment de l'exécution, utilisez ParagonIE_Sodium_Compat::crypto_pwhash_is_available() , qui renvoie une valeur booléenne ( TRUE ou FALSE ).
L'API HKDF de Libsodium ( crypto_kdf_hkdf_*() ) n'est pas incluse car PHP possède ses propres fonctionnalités HMAC et cela n'a pas été jugé nécessaire.
Pour les utilisateurs de sodium_compat et qui utilisent PHPCompatibility dans leur processus CI, il existe désormais un ensemble de règles personnalisées disponible qui peut être utilisé pour empêcher les faux positifs d'être générés par PHPCompatibility pour la fonctionnalité PHP native polyremplie par ce dépôt.
Vous pouvez trouver le dépôt de l'ensemble de règles PHPCompatibilityParagonieSodiumCompat ici sur Github et sur Packagist.
