{"id":20790387,"url":"https://github.com/paragonie/sodium_compat","last_synced_at":"2025-05-14T03:11:12.135Z","repository":{"id":15109841,"uuid":"74724363","full_name":"paragonie/sodium_compat","owner":"paragonie","description":"Pure PHP polyfill for ext/sodium","archived":false,"fork":false,"pushed_at":"2024-09-10T16:39:40.000Z","size":1635,"stargazers_count":916,"open_issues_count":0,"forks_count":64,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-05-14T00:54:47.037Z","etag":null,"topics":["blake2b","cryptography","cryptography-library","curve25519","ed25519","libsodium","php","php-polyfill","security","siphash","sodium","sodium-compat","x25519","xchacha20-poly1305","xsalsa20poly1305"],"latest_commit_sha":null,"homepage":"https://paragonie.com","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paragonie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-25T04:01:36.000Z","updated_at":"2025-05-08T15:34:05.000Z","dependencies_parsed_at":"2022-07-14T06:50:33.721Z","dependency_job_id":"2a37bc2e-f013-48a4-a603-c45507f26f84","html_url":"https://github.com/paragonie/sodium_compat","commit_stats":{"total_commits":690,"total_committers":24,"mean_commits":28.75,"dds":0.08115942028985512,"last_synced_commit":"a673d5f310477027cead2e2f2b6db5d8368157cb"},"previous_names":[],"tags_count":73,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paragonie%2Fsodium_compat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paragonie%2Fsodium_compat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paragonie%2Fsodium_compat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paragonie%2Fsodium_compat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paragonie","download_url":"https://codeload.github.com/paragonie/sodium_compat/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254059518,"owners_count":22007771,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blake2b","cryptography","cryptography-library","curve25519","ed25519","libsodium","php","php-polyfill","security","siphash","sodium","sodium-compat","x25519","xchacha20-poly1305","xsalsa20poly1305"],"created_at":"2024-11-17T15:34:36.208Z","updated_at":"2025-05-14T03:11:07.095Z","avatar_url":"https://github.com/paragonie.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sodium Compat\n\n[![Build Status](https://github.com/paragonie/sodium_compat/actions/workflows/ci.yml/badge.svg)](https://github.com/paragonie/sodium_compat/actions)\n[![Psalm Status](https://github.com/paragonie/sodium_compat/actions/workflows/psalm.yml/badge.svg)](https://github.com/paragonie/sodium_compat/actions)\n[![Latest Stable Version](https://poser.pugx.org/paragonie/sodium_compat/v/stable)](https://packagist.org/packages/paragonie/sodium_compat)\n[![Latest Unstable Version](https://poser.pugx.org/paragonie/sodium_compat/v/unstable)](https://packagist.org/packages/paragonie/sodium_compat)\n[![License](https://poser.pugx.org/paragonie/sodium_compat/license)](https://packagist.org/packages/paragonie/sodium_compat)\n[![Downloads](https://img.shields.io/packagist/dt/paragonie/sodium_compat.svg)](https://packagist.org/packages/paragonie/sodium_compat)\n\nSodium Compat is a pure PHP polyfill for the Sodium cryptography library \n(libsodium), a core extension in PHP 7.2.0+ and otherwise [available in PECL](https://pecl.php.net/package/libsodium).\n\nIf you have the PHP extension installed, Sodium Compat will opportunistically\nand transparently use the PHP extension instead of our implementation.\n\n## Major Versions and Branches\n\nsodium_compat v1.21.0 was the last v1.x release from the master branch. From now\non, all future releases that support PHP 5.2 - 8.0 and 32-bit integers will be\n[in the `v1.x` branch](https://github.com/paragonie/sodium_compat/tree/v1.x).\n\nNewer versions of sodium_compat (i.e., v2.0.0) will continue to live in the master\nbranch, unless a new major version is needed. The goal of this work is to improve\ncode readability and performance, while reducing boilerplate code.\n\nWhen in doubt, refer to the README file in [the master branch](https://github.com/paragonie/sodium_compat/blob/master/README.md)\nfor the latest in version information.\n\n### Which version should I use?\n\n| sodium_compat version | PHP versions supported | 32-bit support? | Branch                                                        |\n|-----------------------|------------------------|-----------------|---------------------------------------------------------------|\n| `v1.x.y`              | 5.2.4 - LATEST         | YES             | [v1.x](https://github.com/paragonie/sodium_compat/tree/v1.x)  |\n| `v2.x.y`              | 8.1 - LATEST           | NO              | **master**                                                    |\n\nIf you need 32-bit PHP support (`PHP_INT_SIZE == 4`), continue using sodium_compat v1.x.\nIf you want improved performance and smaller dependencies, use v2.x.\n\nWe recommend libraries and frameworks set a Composer version constraint as follows:\n\n```javascript\n{\n    \"require\": {\n        /* ... */\n        \"paragonie/sodium_compat\": \"\u003e= 1\"\n        /* ... */\n    }\n}\n```\n\nApplications should, conversely, specify the actual version that matters to them \nand their deployments.\n\n## IMPORTANT!\n\nThis cryptography library has not been formally audited by an independent third \nparty that specializes in cryptography or cryptanalysis.\n\nIf you require such an audit before you can use sodium_compat in your projects\nand have the funds for such an audit, please open an issue or contact \n`security at paragonie dot com` so we can help get the ball rolling.\n\nHowever, sodium_compat has been adopted by high profile open source projects,\nsuch as [Joomla!](https://github.com/joomla/joomla-cms/blob/459d74686d2a638ec51149d7c44ddab8075852be/composer.json#L40)\nand [Magento](https://github.com/magento/magento2/blob/8fd89cfdf52c561ac0ca7bc20fd38ef688e201b0/composer.json#L44).\nFurthermore, sodium_compat was developed by Paragon Initiative Enterprises, a\ncompany that *specializes* in secure PHP development and PHP cryptography, and\nhas been informally reviewed by many other security experts who also specialize\nin PHP.\n\nIf you'd like to learn more about the defensive security measures we've taken\nto prevent sodium_compat from being a source of vulnerability in your systems,\nplease read [*Cryptographically Secure PHP Development*](https://paragonie.com/blog/2017/02/cryptographically-secure-php-development).\n\n# Installing Sodium Compat\n\nIf you're using Composer:\n\n```bash\ncomposer require paragonie/sodium_compat\n```\n\n### Install From Source\n\nIf you're not using Composer, download a [release tarball](https://github.com/paragonie/sodium_compat/releases)\n(which should be signed with [our GnuPG public key](https://paragonie.com/static/gpg-public-key.txt)), extract\nits contents, then include our `autoload.php` script in your project.\n\n```php\n\u003c?php\nrequire_once \"/path/to/sodium_compat/autoload.php\";\n```\n\n### PHP Archives (Phar) Releases\n\nSince version 1.3.0, [sodium_compat releases](https://github.com/paragonie/sodium_compat/releases) include a\nPHP Archive (.phar file) and associated GPG signature. First, download both files and verify them with our\nGPG public key, like so:\n\n```bash\n# Getting our public key from the keyserver:\ngpg --fingerprint 7F52D5C61D1255C731362E826B97A1C2826404DA\nif [ $? -ne 0 ]; then\n    echo -e \"\\033[33mDownloading PGP Public Key...\\033[0m\"\n    gpg  --keyserver pgp.mit.edu --recv-keys 7F52D5C61D1255C731362E826B97A1C2826404DA\n    # Security \u003csecurity@paragonie.com\u003e\n    gpg --fingerprint 7F52D5C61D1255C731362E826B97A1C2826404DA\n    if [ $? -ne 0 ]; then\n        echo -e \"\\033[31mCould not download PGP public key for verification\\033[0m\"\n        exit 1\n    fi\nfi\n\n# Verifying the PHP Archive\ngpg --verify sodium-compat.phar.sig sodium-compat.phar\n```\n\nNow, simply include this .phar file in your application.\n\n```php\n\u003c?php\nrequire_once \"/path/to/sodium-compat.phar\";\n```\n\n# Support\n\n[Commercial support for libsodium](https://download.libsodium.org/doc/commercial_support/) is available\nfrom multiple vendors. If you need help using sodium_compat in one of your projects, [contact Paragon Initiative Enterprises](https://paragonie.com/contact). \n\nNon-commercial report will be facilitated through [Github issues](https://github.com/paragonie/sodium_compat/issues).\nWe offer no guarantees of our availability to resolve questions about integrating sodium_compat into third-party\nsoftware for free, but will strive to fix any bugs (security-related or otherwise) in our library.\n\n## Support Contracts\n\nIf your company uses this library in their products or services, you may be\ninterested in [purchasing a support contract from Paragon Initiative Enterprises](https://paragonie.com/enterprise).\n\n# Using Sodium Compat\n\n## True Polyfill\n\nAs per the [second vote on the libsodium RFC](https://wiki.php.net/rfc/libsodium#proposed_voting_choices),\nPHP 7.2 uses `sodium_*` instead of `\\Sodium\\*`.\n\n```php\n\u003c?php\nrequire_once \"/path/to/sodium_compat/autoload.php\";\n\n$alice_kp = sodium_crypto_sign_keypair();\n$alice_sk = sodium_crypto_sign_secretkey($alice_kp);\n$alice_pk = sodium_crypto_sign_publickey($alice_kp);\n\n$message = 'This is a test message.';\n$signature = sodium_crypto_sign_detached($message, $alice_sk);\nif (sodium_crypto_sign_verify_detached($signature, $message, $alice_pk)) {\n    echo 'OK', PHP_EOL;\n} else {\n    throw new Exception('Invalid signature');\n}\n```\n\n## General-Use Polyfill\n\nIf your users are on PHP \u003c 5.3, or you want to write code that will work\nwhether or not the PECL extension is available, you'll want to use the\n**`ParagonIE_Sodium_Compat`** class for most of your libsodium needs.\n\nThe above example, written for general use:\n\n```php\n\u003c?php\nrequire_once \"/path/to/sodium_compat/autoload.php\";\n\n$alice_kp = ParagonIE_Sodium_Compat::crypto_sign_keypair();\n$alice_sk = ParagonIE_Sodium_Compat::crypto_sign_secretkey($alice_kp);\n$alice_pk = ParagonIE_Sodium_Compat::crypto_sign_publickey($alice_kp);\n\n$message = 'This is a test message.';\n$signature = ParagonIE_Sodium_Compat::crypto_sign_detached($message, $alice_sk);\nif (ParagonIE_Sodium_Compat::crypto_sign_verify_detached($signature, $message, $alice_pk)) {\n    echo 'OK', PHP_EOL;\n} else {\n    throw new Exception('Invalid signature');\n}\n```\n\nGenerally: If you replace `sodium_` with `ParagonIE_Sodium_Compat::`, any\ncode already written for the libsodium PHP extension should work with our\npolyfill without additional code changes.\n\nSince this doesn't require a namespace, this API *is* exposed on PHP 5.2.\n\nSince version 0.7.0, we have our own namespaced API (`ParagonIE\\Sodium\\*`) to allow brevity\nin software that uses PHP 5.3+. This is useful if you want to use our file cryptography\nfeatures without writing `ParagonIE_Sodium_File` every time. This is not exposed on PHP \u003c 5.3,\nso if your project supports PHP \u003c 5.3, use the underscore method instead.\n\nTo learn how to use Libsodium, read [*Using Libsodium in PHP Projects*](https://paragonie.com/book/pecl-libsodium).\n\n## Help, Sodium_Compat is Slow! How can I make it fast?\n\nThere are three ways to make it fast:\n\n1. Use a newer version of PHP (at least 7.2).\n2. [Install the libsodium PHP extension from PECL](https://paragonie.com/book/pecl-libsodium/read/00-intro.md#installing-libsodium).\n3. Only if the previous two options are not available for you:\n   1. Verify that [the processor you're using actually implements constant-time multiplication](https://bearssl.org/ctmul.html).\n      Sodium_compat does, but it must trade some speed in order to attain cross-platform security.\n   2. Only if you are 100% certain that your processor is safe, you can set `ParagonIE_Sodium_Compat::$fastMult = true;`\n      without harming the security of your cryptography keys. If your processor *isn't* safe, then decide whether you\n      want speed or security because you can't have both.\n\n### How can I tell if sodium_compat will be slow, at runtime?\n\nSince version 1.8, you can use the `polyfill_is_fast()` static method to\ndetermine if sodium_compat will be slow at runtime.\n\n```php\n\u003c?php\nif (ParagonIE_Sodium_Compat::polyfill_is_fast()) {\n    // Use libsodium now\n    $process-\u003eexecute();\n} else {\n    // Defer to a cron job or other sort of asynchronous process\n    $process-\u003eenqueue();\n}\n```\n\n## Documentation\n\nFirst, you'll want to read the [Libsodium Quick Reference](https://paragonie.com/blog/2017/06/libsodium-quick-reference-quick-comparison-similar-functions-and-which-one-use).\nIt aims to answer, \"Which function should I use for [common problem]?\".\n\nIf you don't find the answers in the Quick Reference page, check out\n[*Using Libsodium in PHP Projects*](https://paragonie.com/book/pecl-libsodium).\n\nFinally, the [official libsodium documentation](https://download.libsodium.org/doc/) \n(which was written for the C library, not the PHP library) also contains a lot of\ninsightful technical information you may find helpful.\n\n## API Coverage\n\n**Recommended reading:** [Libsodium Quick Reference](https://paragonie.com/blog/2017/06/libsodium-quick-reference-quick-comparison-similar-functions-and-which-one-use)\n\n* Mainline NaCl Features\n    * `crypto_auth()`\n    * `crypto_auth_verify()`\n    * `crypto_box()`\n    * `crypto_box_open()`\n    * `crypto_scalarmult()`\n    * `crypto_secretbox()`\n    * `crypto_secretbox_open()`\n    * `crypto_sign()`\n    * `crypto_sign_open()`\n* PECL Libsodium Features\n    * `crypto_aead_aegis128l_encrypt()`\n    * `crypto_aead_aegis128l_decrypt()`\n    * `crypto_aead_aegis256_encrypt()`\n    * `crypto_aead_aegis256_decrypt()`\n    * `crypto_aead_aes256gcm_encrypt()`\n    * `crypto_aead_aes256gcm_decrypt()`\n    * `crypto_aead_chacha20poly1305_encrypt()`\n    * `crypto_aead_chacha20poly1305_decrypt()`\n    * `crypto_aead_chacha20poly1305_ietf_encrypt()`\n    * `crypto_aead_chacha20poly1305_ietf_decrypt()`\n    * `crypto_aead_xchacha20poly1305_ietf_encrypt()`\n    * `crypto_aead_xchacha20poly1305_ietf_decrypt()`\n    * `crypto_box_xchacha20poly1305()`\n    * `crypto_box_xchacha20poly1305_open()`\n    * `crypto_box_seal()`\n    * `crypto_box_seal_open()`\n    * `crypto_generichash()`\n    * `crypto_generichash_init()`\n    * `crypto_generichash_update()`\n    * `crypto_generichash_final()`\n    * `crypto_kx()`\n    * `crypto_secretbox_xchacha20poly1305()`\n    * `crypto_secretbox_xchacha20poly1305_open()`\n    * `crypto_shorthash()`\n    * `crypto_sign_detached()`\n    * `crypto_sign_ed25519_pk_to_curve25519()`\n    * `crypto_sign_ed25519_sk_to_curve25519()`\n    * `crypto_sign_verify_detached()`\n    * For advanced users only:\n        * `crypto_core_ristretto255_add()`\n        * `crypto_core_ristretto255_from_hash()`\n        * `crypto_core_ristretto255_is_valid_point()`\n        * `crypto_core_ristretto255_random()`\n        * `crypto_core_ristretto255_scalar_add()`\n        * `crypto_core_ristretto255_scalar_complement()`\n        * `crypto_core_ristretto255_scalar_invert()`\n        * `crypto_core_ristretto255_scalar_mul()`\n        * `crypto_core_ristretto255_scalar_negate()`\n        * `crypto_core_ristretto255_scalar_random()`\n        * `crypto_core_ristretto255_scalar_reduce()`\n        * `crypto_core_ristretto255_scalar_sub()`\n        * `crypto_core_ristretto255_sub()`\n        * `crypto_scalarmult_ristretto255_base()`\n        * `crypto_scalarmult_ristretto255()`\n        * `crypto_stream()`\n        * `crypto_stream_keygen()`\n        * `crypto_stream_xor()`\n        * `crypto_stream_xchacha20()`\n        * `crypto_stream_xchacha20_keygen()`\n        * `crypto_stream_xchacha20_xor()`\n        * `crypto_stream_xchacha20_xor_ic()`\n    * Other utilities (e.g. `crypto_*_keypair()`)\n        * `add()`\n        * `base642bin()`\n        * `bin2base64()`\n        * `bin2hex()`\n        * `hex2bin()`\n        * `crypto_kdf_derive_from_key()`\n        * `crypto_kx_client_session_keys()`\n        * `crypto_kx_server_session_keys()`\n        * `crypto_secretstream_xchacha20poly1305_init_push()`\n        * `crypto_secretstream_xchacha20poly1305_push()`\n        * `crypto_secretstream_xchacha20poly1305_init_pull()`\n        * `crypto_secretstream_xchacha20poly1305_pull()`\n        * `crypto_secretstream_xchacha20poly1305_rekey()`\n        * `pad()`\n        * `unpad()`\n\n### Cryptography Primitives Provided\n\n* **X25519** - Elliptic Curve Diffie Hellman over Curve25519\n* **Ed25519** - Edwards curve Digital Signature Algorithm over Curve25519\n* **Xsalsa20** - Extended-nonce Salsa20 stream cipher\n* **ChaCha20** - Stream cipher\n* **Xchacha20** - Extended-nonce ChaCha20 stream cipher\n* **Poly1305** - Polynomial Evaluation Message Authentication Code modulo 2^130 - 5\n* **BLAKE2b** - Cryptographic Hash Function\n* **SipHash-2-4** - Fast hash, but not collision-resistant; ideal for hash tables.\n\n### Features Excluded from this Polyfill\n\n* `sodium_memzero()` - Although we expose this API endpoint, we can't reliably\n  zero buffers from PHP.\n  \n  If you have the PHP extension installed, sodium_compat\n  will use the native implementation to zero out the string provided. Otherwise\n  it will throw a `SodiumException`.\n* `sodium_crypto_pwhash()` - It's not feasible to polyfill scrypt or Argon2\n  into PHP and get reasonable performance. Users would feel motivated to select\n  parameters that downgrade security to avoid denial of service (DoS) attacks.\n  \n  The only winning move is not to play.\n  \n  If ext/sodium or ext/libsodium is installed, these API methods will fallthrough\n  to the extension. Otherwise, our polyfill library will throw a `SodiumException`.\n  \n  To detect support for Argon2i at runtime, use\n  `ParagonIE_Sodium_Compat::crypto_pwhash_is_available()`, which returns a\n   boolean value (`TRUE` or `FALSE`).\n* Libsodium's HKDF API (`crypto_kdf_hkdf_*()`) is not included because PHP has\n  its own [HMAC features](https://php.met/hash_hmac) amd it was not deemed necessary.\n\n### PHPCompatibility Ruleset\n\nFor sodium_compat users and that utilize [`PHPCompatibility`](https://github.com/PHPCompatibility/PHPCompatibility)\nin their CI process, there is now a custom ruleset available which can be used\nto prevent false positives being thrown by `PHPCompatibility` for the native\nPHP functionality being polyfilled by this repo.\n\nYou can find the repo for the `PHPCompatibilityParagonieSodiumCompat` ruleset\nhere [on Github](https://github.com/PHPCompatibility/PHPCompatibilityParagonie) \nand [on Packagist](https://packagist.org/packages/phpcompatibility/phpcompatibility-paragonie).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparagonie%2Fsodium_compat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparagonie%2Fsodium_compat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparagonie%2Fsodium_compat/lists"}