Non-commercial report will be facilitated through Github issues. We offer no guarantees of our availability to resolve questions about integrating sodium_compat into third-party software for free, but will strive to fix any bugs (security-related or otherwise) in our library.

Support Contracts

If your company uses this library in their products or services, you may be interested in purchasing a support contract from Paragon Initiative Enterprises.

Using Sodium Compat

True Polyfill

As per the second vote on the libsodium RFC, PHP 7.2 uses sodium_ instead of \Sodium\.

<?php
requireonce "/path/to/sodiumcompat/autoload.php";
$alicekp = sodiumcryptosignkeypair(); $alicesk = sodiumcryptosignsecretkey($alice_kp); $alicepk = sodiumcryptosignpublickey($alice_kp);
$message = 'This is a test message.'; $signature = sodiumcryptosigndetached($message, $alicesk); if (sodiumcryptosignverifydetached($signature, $message, $alice_pk)) {     echo 'OK', PHP_EOL; } else {     throw new Exception('Invalid signature'); }

General-Use Polyfill

If your users are on PHP < 5.3, or you want to write code that will work whether or not the PECL extension is available, you'll want to use the ParagonIESodiumCompat class for most of your libsodium needs.

The above example, written for general use:

<?php
requireonce "/path/to/sodiumcompat/autoload.php";
$alicekp = ParagonIESodiumCompat::cryptosign_keypair(); $alicesk = ParagonIESodiumCompat::cryptosignsecretkey($alicekp); $alicepk = ParagonIESodiumCompat::cryptosignpublickey($alicekp);
$message = 'This is a test message.'; $signature = ParagonIESodiumCompat::cryptosigndetached($message, $alice_sk); if (ParagonIESodiumCompat::cryptosignverifydetached($signature, $message, $alicepk)) {     echo 'OK', PHP_EOL; } else {     throw new Exception('Invalid signature'); }

Generally: If you replace sodium with ParagonIESodium_Compat::, any code already written for the libsodium PHP extension should work with our polyfill without additional code changes.

Since this doesn't require a namespace, this API is exposed on PHP 5.2.

Since version 0.7.0, we have our own namespaced API (ParagonIE\Sodium\*) to allow brevity in software that uses PHP 5.3+. This is useful if you want to use our file cryptography features without writing ParagonIESodiumFile every time. This is not exposed on PHP < 5.3, so if your project supports PHP < 5.3, use the underscore method instead.

To learn how to use Libsodium, read Using Libsodium in PHP Projects.

Help, Sodium_Compat is Slow! How can I make it fast?

There are three ways to make it fast:

• Use a newer version of PHP (at least 7.2).
• Install the libsodium PHP extension from PECL.
• Only if the previous two options are not available for you:

How can I tell if sodium_compat will be slow, at runtime?

Since version 1.8, you can use the polyfillisfast() static method to determine if sodium_compat will be slow at runtime.

<?php
if (ParagonIESodiumCompat::polyfillisfast()) {
    // Use libsodium now
    $process->execute();
} else {
    // Defer to a cron job or other sort of asynchronous process
    $process->enqueue();
}

Documentation

First, you'll want to read the Libsodium Quick Reference. It aims to answer, "Which function should I use for [common problem]?".

If you don't find the answers in the Quick Reference page, check out Using Libsodium in PHP Projects.

Finally, the official libsodium documentation (which was written for the C library, not the PHP library) also contains a lot of insightful technical information you may find helpful.

API Coverage

Recommended reading: Libsodium Quick Reference

• Mainline NaCl Features

• PECL Libsodium Features

Cryptography Primitives Provided

• X25519 - Elliptic Curve Diffie Hellman over Curve25519
• Ed25519 - Edwards curve Digital Signature Algorithm over Curve25519
• Xsalsa20 - Extended-nonce Salsa20 stream cipher
• ChaCha20 - Stream cipher
• Xchacha20 - Extended-nonce ChaCha20 stream cipher
• Poly1305 - Polynomial Evaluation Message Authentication Code modulo 2^130 - 5
• BLAKE2b - Cryptographic Hash Function
• SipHash-2-4 - Fast hash, but not collision-resistant; ideal for hash tables.

Features Excluded from this Polyfill

• sodium_memzero() - Although we expose this API endpoint, we can't reliably

• sodiumcryptopwhash() - It's not feasible to polyfill scrypt or Argon2

PHPCompatibility Ruleset

For sodiumcompat users and that utilize PHPCompatibility in their CI process, there is now a custom ruleset available which can be used to prevent false positives being thrown by PHPCompatibility for the native PHP functionality being polyfilled by this repo.