As far as I know, sodium_compat still did not had the cryptographic review that the author was strongly asking for, right? If yes, is it wise to build our crypto stuff around it?

It has not (it's in the readme Michael linked to). I'm also unsure (but not strongly against) on whether we just require min php 7.2 in the is_supported.

We do have to be very careful about documenting that clearly as a minimum in php doc blocks etc

I would not lock it to only PHP 7.2 since as noted there is a PECL extension offering support down to PHP 5.4 and is the predecessor for the core API that will be in 7.2. So depending on your server config, the polyfill is the only way to get support for PHP 5.3 and covers the other PHP branches if you can't install the PECL extension. We do have other system components which require PECL extensions that aren't part of the core PHP distro (Memcached and Redis for cache/session support) or depend on PEAR packages (Cache_Lite), so it's not unprecedented for us to have API components with extra dependencies.

Not using the polyfill though complicates this implementation quite a bit. Two main issues come to mind. First, there would be no way to support PHP 5.3 at all (in many ways that's fair, it's a dead branch anyway, but it is part of our supported version range and thus far we don't have features in core that are only available on newer PHP versions). Second, the API between PECL and core PHP 7.2 is different (PECL uses a namespaced API whereas to put the code in core everything had to move to core PHP's naming convention), so we'd have a lot of conditionals in the class for each of the functions we're using.

Second, the API between PECL and core PHP 7.2 is different (PECL uses a namespaced API whereas to put the code in core everything had to move to core PHP's naming convention), so we'd have a lot of conditionals in the class for each of the functions we're using.

Just adding sodium_compat actually nullifies that. If you're on < 7.2, it maps sodium_* to \Sodium\*. If you're on 7.2+, it will do the converse. If you want to simplify debugging paths, just use \ParagonIE_Sodium_Compat::* and it will automatically use the C extension where it can, and polyfill the rest.

@SniperSister

If yes, is it wise to build our crypto stuff around it?

First, let's assume there's some vulnerability in sodium_compat. What might it look like?

Let's begin with the attacks that have been eliminated by its design (which is enforced via unit tests and static analysis):

• It won't be a straightforward cryptanalysis break, since:
  • For shared-key encryption, we're implementing one of the eSTREAM finalists which has been hit hard by cryptographers for years and still has a higher security margin than AES.
  • For shared-key authentication, we're using PHP's built-in HMAC.
  • For public-key cryptography, we're using Curve25519.
  • If any of the above turns out to be false, the problem isn't with sodium_compat, but with all modern cryptography.
• It won't be a protocol construction flaw, since:
  • For shared-key encryption, we always Encrypt Then Authenticate.
  • For shared-key authentication, we're using hash_equals() to prevent timing side-channels.
  • For public-key encryption (ECDH over Curve25519 then shared-key encryption), we're using a Montgomery ladder construction which only sends the X coordinate. This eliminates invalid curve attacks and timing side-channels.
  • For public-key digital signatures, Ed25519 is a deterministic signature scheme, which prevents a private-key leaking security flaw.
• It won't be any of the obvious cache-timing side channels in PHP, including chr().
• It won't be any of the less-obvious (and maybe not exploitable) side-channels, including:
  • Multi-byte string bugs
  • bin2hex()
  • Integer multiplication

There is still some attack surface that sodium_compat does not, and cannot, address:

• Zeroing memory buffers is impossible from PHP.
• Some extensions and features, such as OpCache, might now or in the future introduce premature optimizations that include an accidental side-channel
• If there is a vulnerability in PHP itself, that causes a side-channel leak, we probably cannot prevent it

That's the crux of what the audit scope was meant to address: Is it possible to implement completely constant-time cryptography in PHP without just writing it in C as an extension?

Even if the answer is "No", in practical terms, you really only need to worry about local attackers (e.g. neighbors in cloud hosting) that can do attacks on the processor's caches (e.g. FLUSH+RELOAD). If you have a high security requirement where this exposure to an unproven hypothetical risk is not acceptable, it's easily mitigated by the following command:

pecl install libsodium

Whether or not it's wise to use sodium_compat is really your decision, but with this knowledge in hand, I hope whatever answer you go with is a lot clearer.

@paragonie-scott thanks a lot for the detailed explanation, that was really helpful!

@mbabker based on the feedback, I'm fine with using the polyfill.

I have tested this item ✅ successfully on b11ee6f

Works for me with the given test Instructions. Thanks!