If you have the PHP extension installed, Sodium Compat will opportunistically
and transparently use the PHP extension instead of our implementation.

IMPORTANT!

This cryptography library has not been formally audited by an independent third
party that specializes in cryptography or cryptanalysis.

If you require such an audit before you can use sodium_compat in your projects
and have the funds for such an audit, please open an issue or contact
security at paragonie dot com so we can help get the ball rolling.

Support

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.

The polyfill does not expose this API on PHP < 5.3, or if you have the PHP
extension installed already.

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

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
ParagonIE_Sodium_Compat class for most of your libsodium needs.

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

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 ParagonIE_Sodium_File every time. This is not exposed on PHP < 5.3,
so if your project supports PHP < 5.3, use the underscore method instead.

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

Only if the previous two options are not available for you:
1. Verify that the processor you're using actually implements constant-time multiplication.
Sodium_compat does, but it must trade some speed in order to attain cross-platform security.
2. Only if you are 100% certain that your processor is safe, you can set ParagonIE_Sodium_Compat::$fastMult = true;
without harming the security of your cryptography keys. If your processor isn't safe, then decide whether you
want speed or security because you can't have both.

Help, my PHP only has 32-Bit Integers! It's super slow!

Some features of sodium_compat are incredibly slow with PHP 5 on Windows
(in particular: public-key cryptography (encryption and signatures) is
affected), and there is nothing we can do about that, due to platform
restrictions on integers.

For acceptable performance, we highly recommend Windows users to version 1.0.6
of the libsodium extension from PECL or. Alternatively, simply upgrade to PHP 7
and the slowdown will be greatly reduced.

This is also true of non-Windows 32-bit operating systems, or if somehow PHP
was compiled where PHP_INT_SIZE equals 4 instead of 8.

Features Excluded from this Polyfill

\Sodium\memzero() - Although we expose this API endpoint, we can't reliably
zero buffers from PHP.

If you have the PHP extension installed, sodium_compat
will use the native implementation to zero out the string provided. Otherwise
it will throw a SodiumException.

\Sodium\crypto_pwhash() - It's not feasible to polyfill scrypt or Argon2
into PHP and get reasonable performance. Users would feel motivated to select
parameters that downgrade security to avoid denial of service (DoS) attacks.

The only winning move is not to play.

If ext/sodium or ext/libsodium is installed, these API methods will fallthrough
to the extension. Otherwise, our polyfill library will throw a SodiumException.

To detect support for Argon2i at runtime, use
ParagonIE_Sodium_Compat::crypto_pwhash_is_available(), which returns a
boolean value (TRUE or FALSE).