Version 1.4.0

• Implemented the *_keygen() functions which are present in ext/sodium (#52)
• Added crypto_pwhash_is_available() for projects that depend on sodium_compat and need feature detection (#55)
• Implemented crypto_aead_aes256gcm_* API (available on PHP 7.1+ only). You can use the is_available() method at runtime to detect if this option is available.
• Converted a lot of exception types to use a new SodiumException (as per ext/sodium). There are still places that a TypeError will be thrown.

This is the final release of sodium_compat before PHP 7.2 is released. All open source projects are encouraged to set 1.4 as the minimum version supported.

Version 1.3.1

Contains no significant changes since v1.3.0, we just wanted to make sure that the PHP Archives are reproducible from the source code.

We have an upcoming blog post about reproducible PHP Archive builds that will be worth a read if you're curious about this effort.

Version 1.3.0

• Consistent API compatibility (i.e. returning false when decryption fails)
• Significant performance boost to public key cryptography operations on 64-bit systems
• Additionally, we're now bundling GPG-signed PHP archives with our releases. See below.

Version 1.2.0

This is a small release, but it required a deceptively large amount of behind-the-scenes effort to get it ready.

• Sodium_compat now works on 32-bit operating systems, including 64-bit Windows with PHP 5. However, some features (i.e. public key cryptography) are very slow.
  • In future versions, we may provide alternative backend implementations leverage GMP / BCMath (if the extensions are installed, otherwise, falls back to what we have now).
• Added crypto_sign_ed25519_sk_to_curve25519().
  • We neglected its sister function, crypto_sign_ed25519_pk_to_curve25519(), due to added complexity and a desire to get this out the gate. If you need it today, this will do the trick:
    $pk = \Sodium\crypto_box_publickey_from_secretkey(\Sodium\crypto_sign_ed25519_sk_to_curve25519($sk));
  • The missing function will probably be added in v1.3.0.

Version 1.1.0

• Fixed #35 which would have broken PHP 5.2 compatibility.
• Fixed #36 which adds fallthrough methods for crypto_pwhash if available, and throws an error if not.
• UNFIXED: #38 -- sodium_compat produces incorrect results on 32-bit operating systems. For the time being, we are documenting the error and will fix it in a future release. If you attempt to use sodium_compat on a system that doesn't support 64-bit integers, a RuntimeException will be thrown.

Version 1.0.1

Fixes a regression that was causing code to break on PHP < 5.6.

Version 1.0.0

The PHP implementation of libsodium is now believed to be stable. We believe this to be the case due to several factors:

• Our unit test suite, which also includes a comprehensive (borderline pedantic) set of test cases to ensure compatibility with PECL libsodium
• All changes have been verified through Psalm (a static analysis tool) as part of our continuous integration
• An internal code review from our development team (not a substitute for an audit)

The last low-hanging fruit were whitespace issues that made the code slightly harder to read and verify.

Sodium Compat has not been audited by an independent third party. Some open source projects may not adopt this library until that situation changes. Audits are expensive, but well worth the expense.

Some general advice for PHP developers:

• If an audit were to be conducted and any vulnerabilities found, the only likely outcome is side-channels (e.g. cache timing leaks with OpCache) that are only a threat on PHP 7.1 and below without the PHP extension from PECL. Our inputs always produce valid outputs (as proven by our compatibility test suites).
• If you desire to use some of the new cryptography features in PHP 7.2 without requiring your users upgrade to 7.2, sodium_compat can provide a reasonable level of security for your users even without PECL.
• If security against local attackers (e.g. cross-VM attacks on cloud providers) is a huge concern, wait for PHP 7.2 or install the PHP extension from PECL and they should no longer be a concern.

We strongly recommend the PHP extension from PECL or PHP 7.2. But for all else, this should be adequate.

EDIT: Version 1.0.1 fixes a regression from a fix between 0.8.1 and 1.0.0 that only affects you if you're on PHP < 5.6.0.

Version 0.8.1 (Final Beta Release)

Unless any serious issues are found, the next release will include documentation changes and will be v1.0.0.

Version 0.8.0

• Implemented a pedantic compatibility test suite (suggested by @defuse)
• Fixed a bug with crypto_generichash() erroring on weird output sizes (e.g. 17).

Version 0.7.0 (Pencils Down)

• Implemented XChaCha20, based on libsodium 1.0.12.
• Add a namespaced API for PHP >= 5.3.0 projects. (ParagonIE_Sodium_Compat => ParagonIE\Sodium\Compat.)
• The messages for the TypeErrors thrown by Sodium_compat are now more helpful.

This is the pencils down pre-release tag. We'll find out if version 1.0.0 is going to exist after we're audited. If anyone would like to see the audit happen, see this GoFundMe campaign.