PHP RFC: Make Libsodium a Core Extension

• Version: 0.3
• Date: 2016-01-07
• Author: Scott Arciszewski, scott@paragonie.com
• Status: Under Discussion
• First Published at: http://wiki.php.net/rfc/libsodium

As we move towards PHP 7.0.0, we must look at the current state of cryptography in PHP. Libmcrypt hasn't been touched in eight years (last release was in 2007), leaving openssl as the only viable option for PHP 5.x and 7.0 users.

Meanwhile, ext/libsodium has been available in PECL for a while now, and has reached stability.

Libsodium is a modern cryptography library that offers authenticated encryption, high-speed elliptic curve cryptography, and much more. Unlike other cryptography standards (which are a potluck of cryptography primitives; i.e. WebCrypto), libsodium is comprised of carefully selected algorithms implemented by security experts to avoid side-channel vulnerabilities.

I maintain the ext/libsodium documentation here.

This proposal is to adopt the libsodium extension in the PHP core in PHP 7.1.0.

Currently, the libsodium extension in PECL uses the `Sodium` namespace, which runs contrary to the coding standards. If adopted into the PHP core, this will be changed to conform to the coding standards.

    // In PECL today:
    $key = \Sodium\randombytes_buf(\Sodium\CRYPTO_SECRETBOX_KEYBYTES);
    $nonce = \Sodium\randombytes_buf(\Sodium\CRYPTO_SECRETBOX_NONCEBYTES);
    $message = \Sodium\crypto_secretbox(
        $plaintext,
        $key,
        $nonce
    );
    
    // If adopted as a core extension, this will be instead written as:
    $key = sodium_randombytes_buf(SODIUM_CRYPTO_SECRETBOX_KEYBYTES);
    $nonce = sodium_randombytes_buf(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
    $message = sodium_crypto_secretbox(
        $plaintext,
        $key,
        $nonce
    );

Libsodium has a plethora of useful cryptography features:

• Password hashing and key derivation (sodium_crypto_pwhash_*)
  • Argon2i (the chosen algorithm of the Password Hashing Competition)
  • Scrypt
• ECDH over Curve25519 (sodium_crypto_box)
• Authenticated secret key encryption (sodium_crypto_secretbox)
• Ed25519 digital signatures (sodium_crypto_sign)
• AEAD Modes
  • ChaCha20-Poly1305
  • AES-256-GCM

Libsodium (like NaCl, from which it was forked) is widely regarded by cryptography and security industry experts for many reasons:

• No guesswork. The APIs are simple and powerful.
• Conservative security. Great effort was taken to perform every security-critical operation in constant time.
• Best-in-class elliptic curve cryptography.

This RFC targets PHP 7.1.

I'm not aware of any potential impact that adopting libsodium will have on other RFCs.

See the list of all libsodium constants in the reference. In every case, \Sodium\FOO will be transformed to SODIUM_FOO.

Links to external references, discussions or RFCs:

• PECL libsodium (the current implementation)
• Libsodium PHP documentation
• List of all libsodium constants