rfc:libsodium

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
rfc:libsodium [2016/03/15 17:42] – sarciszewskirfc:libsodium [2017/09/22 13:28] (current) – external edit 127.0.0.1
Line 1: Line 1:
 ====== PHP RFC: Make Libsodium a Core Extension ====== ====== PHP RFC: Make Libsodium a Core Extension ======
-  * Version: 0.2 +  * Version: 0.5.1 
-  * Date: 2016-01-07+  * Date: 2016-01-11
   * Author: Scott Arciszewski, scott@paragonie.com   * Author: Scott Arciszewski, scott@paragonie.com
-  * Status: Under Discussion+  * Status: Implemented
   * First Published at: http://wiki.php.net/rfc/libsodium   * First Published at: http://wiki.php.net/rfc/libsodium
  
 ===== Introduction ===== ===== Introduction =====
  
-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.+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.
  
-Libsodium is a modern cryptography library that offers authenticated encryption, high-speed elliptic curve cryptography, and much more. I maintain the documentation [[https://paragonie.com/book/pecl-libsodium|here]].+Meanwhile, libsodium bindings have 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 documentation for the PHP extension [[https://paragonie.com/book/pecl-libsodium|here]].
  
 ===== Proposal ===== ===== Proposal =====
  
-We should include the libsodium extension in the PHP core in a future release of PHP 7, preferably 7.1.0.+This proposal is to adopt the libsodium extension (as ext/sodium) in the PHP core in PHP 7.2.0. 
 + 
 +Currently, the libsodium extension in PECL uses the `Sodium` namespace, which runs contrary to the coding standards. If this RFC adopted into the PHP core, the namespace can be changed to conform to the coding standards (pending the outcome of a secondary vote). 
 + 
 +<code> 
 +    // 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 the second vote is against the use of a namespace: 
 +    $key = sodium_randombytes_buf(SODIUM_CRYPTO_SECRETBOX_KEYBYTES); 
 +    $nonce = sodium_randombytes_buf(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES); 
 +    $message = sodium_crypto_secretbox( 
 +        $plaintext, 
 +        $key, 
 +        $nonce 
 +    ); 
 +</code> 
 + 
 +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. 
 + 
 + 
 +===== Libsodium API Subset ===== 
 + 
 + 
 + 
 +  * Mainline NaCl Features 
 +    * \Sodium\crypto_auth() 
 +    * \Sodium\crypto_auth_verify() 
 +    * \Sodium\crypto_box() 
 +    * \Sodium\crypto_box_open() 
 +    * \Sodium\crypto_scalarmult() 
 +    * \Sodium\crypto_secretbox() 
 +    * \Sodium\crypto_secretbox_open() 
 +    * \Sodium\crypto_sign() 
 +    * \Sodium\crypto_sign_open() 
 +  * PECL Libsodium Features 
 +    * \Sodium\crypto_aead_chacha20poly1305_encrypt() 
 +    * \Sodium\crypto_aead_chacha20poly1305_decrypt() 
 +    * \Sodium\crypto_aead_chacha20poly1305_ietf_encrypt() 
 +    * \Sodium\crypto_aead_chacha20poly1305_ietf_decrypt() 
 +    * \Sodium\crypto_box_keypair() 
 +    * \Sodium\crypto_box_keypair_from_secretkey_and_publickey() 
 +    * \Sodium\crypto_box_publickey() 
 +    * \Sodium\crypto_box_publickey_from_secretkey() 
 +    * \Sodium\crypto_box_seal() 
 +    * \Sodium\crypto_box_seal_open() 
 +    * \Sodium\crypto_box_secretkey() 
 +    * \Sodium\crypto_generichash() 
 +    * \Sodium\crypto_generichash_init() 
 +    * \Sodium\crypto_generichash_update() 
 +    * \Sodium\crypto_generichash_final() 
 +    * \Sodium\crypto_kx() 
 +    * \Sodium\crypto_pwhash() 
 +    * \Sodium\crypto_pwhash_str() 
 +    * \Sodium\crypto_pwhash_str_verify() 
 +    * \Sodium\crypto_shorthash() 
 +    * \Sodium\crypto_sign_detached() 
 +    * \Sodium\crypto_sign_keypair() 
 +    * \Sodium\crypto_sign_publickey() 
 +    * \Sodium\crypto_sign_publickey_from_secretkey() 
 +    * \Sodium\crypto_sign_secretkey() 
 +    * \Sodium\crypto_sign_verify_detached() 
 +    * \Sodium\crypto_stream() 
 +    * \Sodium\crypto_stream_xor() 
 +    * \Sodium\compare() 
 +    * \Sodium\memzero() 
 +    * \Sodium\increment() 
 + 
 +Because crypto_aead_encrypt() will be the CAESAR finalist, we should tentatively commit to adding that one day. https://competitions.cr.yp.to/caesar.html 
 + 
 +We don't need crypto_aead_aes256gcm since that's provided by OpenSSL. We only provide ChaCha20-Poly1305 for e.g. Noise protocol integrations. 
 + 
 +We don't need scrypt; we have crypto_pwhash() which is Argon2i. 
 + 
 +We don't need several other utilities (bin2hex, hex2bin, etc.). Instead, we should make those existing mainline functions cache-timing safe. We MAY decide to add function aliases (e.g. \Sodium\bin2hex() -> \bin2hex()) for compatibility with software already written for ext/sodium.
  
 ===== Proposed PHP Version(s) ===== ===== Proposed PHP Version(s) =====
-An ideal target version would be 7.1.0.+ 
 +This RFC targets PHP 7.2.
  
 ===== RFC Impact ===== ===== RFC Impact =====
  
-==== New Constants ==== +I'm not aware of any potential impact that adopting ext/sodium will have on other RFCs. 
-All new constants will be contained within the Sodium class in the global namespace. (See the list in the references section.)+ 
 + 
 +===== Future Scope ===== 
 + 
 +With libsodium in the PHP core, we may be able to update the Phar extension to support Ed25519 signatures. This will be a great boon for authentic PHP Archive distribution. The current best option, OpenSSL, may provide inadequate security. 
 + 
 +===== New Constants ===== 
 + 
 +See the list of all libsodium constants in the reference. In every case, \Sodium\FOO will be transformed to SODIUM_FOO. 
 + 
 +<code> 
 +\Sodium\CRYPTO_AEAD_CHACHA20POLY1305_KEYBYTES => 32 
 +\Sodium\CRYPTO_AEAD_CHACHA20POLY1305_NSECBYTES => 0 
 +\Sodium\CRYPTO_AEAD_CHACHA20POLY1305_NPUBBYTES => 8 
 +\Sodium\CRYPTO_AEAD_CHACHA20POLY1305_ABYTES => 16 
 +\Sodium\CRYPTO_AEAD_CHACHA20POLY1305_IETF_KEYBYTES => 32 
 +\Sodium\CRYPTO_AEAD_CHACHA20POLY1305_IETF_NSECBYTES => 0 
 +\Sodium\CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES => 12 
 +\Sodium\CRYPTO_AEAD_CHACHA20POLY1305_IETF_ABYTES => 16  
 +\Sodium\CRYPTO_AUTH_BYTES => 32 
 +\Sodium\CRYPTO_AUTH_KEYBYTES => 32 
 +\Sodium\CRYPTO_BOX_SEALBYTES => 16 
 +\Sodium\CRYPTO_BOX_SECRETKEYBYTES => 32 
 +\Sodium\CRYPTO_BOX_PUBLICKEYBYTES => 32 
 +\Sodium\CRYPTO_BOX_KEYPAIRBYTES => 64 
 +\Sodium\CRYPTO_BOX_MACBYTES => 16 
 +\Sodium\CRYPTO_BOX_NONCEBYTES => 24 
 +\Sodium\CRYPTO_BOX_SEEDBYTES => 32 
 +\Sodium\CRYPTO_KX_BYTES => 32 
 +\Sodium\CRYPTO_KX_PUBLICKEYBYTES => 32 
 +\Sodium\CRYPTO_KX_SECRETKEYBYTES => 32 
 +\Sodium\CRYPTO_GENERICHASH_BYTES => 32 
 +\Sodium\CRYPTO_GENERICHASH_BYTES_MIN => 16 
 +\Sodium\CRYPTO_GENERICHASH_BYTES_MAX => 64 
 +\Sodium\CRYPTO_GENERICHASH_KEYBYTES => 32 
 +\Sodium\CRYPTO_GENERICHASH_KEYBYTES_MIN => 16 
 +\Sodium\CRYPTO_GENERICHASH_KEYBYTES_MAX => 64 
 +\Sodium\CRYPTO_PWHASH_SALTBYTES => 16 
 +\Sodium\CRYPTO_PWHASH_STRPREFIX => $argon2i$ 
 +\Sodium\CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE => 4 
 +\Sodium\CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE => 33554432 
 +\Sodium\CRYPTO_PWHASH_OPSLIMIT_MODERATE => 6 
 +\Sodium\CRYPTO_PWHASH_MEMLIMIT_MODERATE => 134217728 
 +\Sodium\CRYPTO_PWHASH_OPSLIMIT_SENSITIVE => 8 
 +\Sodium\CRYPTO_PWHASH_MEMLIMIT_SENSITIVE => 536870912 
 +\Sodium\CRYPTO_SCALARMULT_BYTES => 32 
 +\Sodium\CRYPTO_SCALARMULT_SCALARBYTES => 32 
 +\Sodium\CRYPTO_SHORTHASH_BYTES => 8 
 +\Sodium\CRYPTO_SHORTHASH_KEYBYTES => 16 
 +\Sodium\CRYPTO_SECRETBOX_KEYBYTES => 32 
 +\Sodium\CRYPTO_SECRETBOX_MACBYTES => 16 
 +\Sodium\CRYPTO_SECRETBOX_NONCEBYTES => 24 
 +\Sodium\CRYPTO_SIGN_BYTES => 64 
 +\Sodium\CRYPTO_SIGN_SEEDBYTES => 32 
 +\Sodium\CRYPTO_SIGN_PUBLICKEYBYTES => 32 
 +\Sodium\CRYPTO_SIGN_SECRETKEYBYTES => 64 
 +\Sodium\CRYPTO_SIGN_KEYPAIRBYTES => 96 
 +\Sodium\CRYPTO_STREAM_KEYBYTES => 32 
 +\Sodium\CRYPTO_STREAM_NONCEBYTES => 24 
 +</code> 
 + 
 +===== Proposed Voting Choices ===== 
 + 
 + 
 +Voting starts on 2017-02-03 20:42 UTC and closes on 2017-02-10 21:00 UTC. 
 + 
 +Vote YES to add ext/sodium to PHP 7.2. As per new voting rules, a 2/3 majority is required. 
 + 
 +<doodle title="Libsodium as a Core Extension in PHP 7.2" auth="sarciszewski" voteType="single" closed="true"> 
 +   * Yes 
 +   * No 
 +</doodle> 
 + 
 +Second vote: Vote YES to keep the namespace (\Sodium\etc), vote NO to switch to a prefix in the global namespace (sodium_etc). A 2/3 majority is also required for "Yes" to be accepted. The default is for "No". 
 + 
 +<doodle title="Use the current PECL syntax?" auth="sarciszewski" voteType="single" closed="true"> 
 +   * Yes, \Sodium\foo 
 +   * No, sodium_foo 
 +</doodle> 
 + 
 +===== Implementation ===== 
 +  
 +  - merged to PHP 7.2+ in http://git.php.net/?p=php-src.git;a=commit;h=5cfa26c18189ae5e0ae8bb1eac5dd0e213a2bb3e 
 +  - PHP manual section: yet missing
  
 ===== References ===== ===== References =====
Line 29: Line 213:
   * [[https://github.com/jedisct1/libsodium-php|PECL libsodium]] (the current implementation)   * [[https://github.com/jedisct1/libsodium-php|PECL libsodium]] (the current implementation)
   * [[https://paragonie.com/book/pecl-libsodium|Libsodium PHP documentation]]   * [[https://paragonie.com/book/pecl-libsodium|Libsodium PHP documentation]]
-  * [[https://paragonie.com/book/pecl-libsodium/read/01-quick-start.md|List of all libsodium constants and functions]]+  * [[https://paragonie.com/book/pecl-libsodium/read/01-quick-start.md#constant-index|List of all libsodium constants]]
rfc/libsodium.1458063775.txt.gz · Last modified: 2017/09/22 13:28 (external edit)

Page Tools