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/06/01 13:47] – 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.3 +  * 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
  
Line 18: Line 18:
 ===== Proposal ===== ===== Proposal =====
  
-This proposal is to adopt the libsodium extension (as ext/sodium) in the PHP core in PHP 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 adopted into the PHP core, this will be changed to conform to the coding standards.+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> <code>
Line 32: Line 32:
     );     );
          
-    // If adopted as a core extension, this will be instead written as:+    // If the second vote is against the use of a namespace:
     $key = sodium_randombytes_buf(SODIUM_CRYPTO_SECRETBOX_KEYBYTES);     $key = sodium_randombytes_buf(SODIUM_CRYPTO_SECRETBOX_KEYBYTES);
     $nonce = sodium_randombytes_buf(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);     $nonce = sodium_randombytes_buf(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
Line 59: Line 59:
   * Conservative security. Great effort was taken to perform every security-critical operation in constant time.   * Conservative security. Great effort was taken to perform every security-critical operation in constant time.
   * Best-in-class elliptic curve cryptography.   * 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) =====
  
-This RFC targets PHP 7.1.+This RFC targets PHP 7.2.
  
 ===== RFC Impact ===== ===== RFC Impact =====
Line 68: Line 124:
 I'm not aware of any potential impact that adopting ext/sodium will have on other RFCs. I'm not aware of any potential impact that adopting ext/sodium will have on other RFCs.
  
-==== New Constants ====+ 
 +===== 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. See the list of all libsodium constants in the reference. In every case, \Sodium\FOO will be transformed to SODIUM_FOO.
  
 <code> <code>
-SODIUM_CRYPTO_AEAD_AES256GCM_KEYBYTES => 32 +\Sodium\CRYPTO_AEAD_CHACHA20POLY1305_KEYBYTES => 32 
-SODIUM_CRYPTO_AEAD_AES256GCM_NSECBYTES => 0 +\Sodium\CRYPTO_AEAD_CHACHA20POLY1305_NSECBYTES => 0 
-SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES => 12 +\Sodium\CRYPTO_AEAD_CHACHA20POLY1305_NPUBBYTES => 8 
-SODIUM_CRYPTO_AEAD_AES256GCM_ABYTES => 16 +\Sodium\CRYPTO_AEAD_CHACHA20POLY1305_ABYTES => 16 
-SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_KEYBYTES => 32 +\Sodium\CRYPTO_AEAD_CHACHA20POLY1305_IETF_KEYBYTES => 32 
-SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NSECBYTES => 0 +\Sodium\CRYPTO_AEAD_CHACHA20POLY1305_IETF_NSECBYTES => 0 
-SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NPUBBYTES => 8 +\Sodium\CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES => 12 
-SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_ABYTES => 16 +\Sodium\CRYPTO_AEAD_CHACHA20POLY1305_IETF_ABYTES => 16  
-SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_KEYBYTES => 32 +\Sodium\CRYPTO_AUTH_BYTES => 32 
-SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NSECBYTES => 0 +\Sodium\CRYPTO_AUTH_KEYBYTES => 32 
-SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES => 12 +\Sodium\CRYPTO_BOX_SEALBYTES => 16 
-SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_ABYTES => 16 +\Sodium\CRYPTO_BOX_SECRETKEYBYTES => 32 
-SODIUM_CRYPTO_AUTH_BYTES => 32 +\Sodium\CRYPTO_BOX_PUBLICKEYBYTES => 32 
-SODIUM_CRYPTO_AUTH_KEYBYTES => 32 +\Sodium\CRYPTO_BOX_KEYPAIRBYTES => 64 
-SODIUM_CRYPTO_BOX_SEALBYTES => 16 +\Sodium\CRYPTO_BOX_MACBYTES => 16 
-SODIUM_CRYPTO_BOX_SECRETKEYBYTES => 32 +\Sodium\CRYPTO_BOX_NONCEBYTES => 24 
-SODIUM_CRYPTO_BOX_PUBLICKEYBYTES => 32 +\Sodium\CRYPTO_BOX_SEEDBYTES => 32 
-SODIUM_CRYPTO_BOX_KEYPAIRBYTES => 64 +\Sodium\CRYPTO_KX_BYTES => 32 
-SODIUM_CRYPTO_BOX_MACBYTES => 16 +\Sodium\CRYPTO_KX_PUBLICKEYBYTES => 32 
-SODIUM_CRYPTO_BOX_NONCEBYTES => 24 +\Sodium\CRYPTO_KX_SECRETKEYBYTES => 32 
-SODIUM_CRYPTO_BOX_SEEDBYTES => 32 +\Sodium\CRYPTO_GENERICHASH_BYTES => 32 
-SODIUM_CRYPTO_KX_BYTES => 32 +\Sodium\CRYPTO_GENERICHASH_BYTES_MIN => 16 
-SODIUM_CRYPTO_KX_PUBLICKEYBYTES => 32 +\Sodium\CRYPTO_GENERICHASH_BYTES_MAX => 64 
-SODIUM_CRYPTO_KX_SECRETKEYBYTES => 32 +\Sodium\CRYPTO_GENERICHASH_KEYBYTES => 32 
-SODIUM_CRYPTO_GENERICHASH_BYTES => 32 +\Sodium\CRYPTO_GENERICHASH_KEYBYTES_MIN => 16 
-SODIUM_CRYPTO_GENERICHASH_BYTES_MIN => 16 +\Sodium\CRYPTO_GENERICHASH_KEYBYTES_MAX => 64 
-SODIUM_CRYPTO_GENERICHASH_BYTES_MAX => 64 +\Sodium\CRYPTO_PWHASH_SALTBYTES => 16 
-SODIUM_CRYPTO_GENERICHASH_KEYBYTES => 32 +\Sodium\CRYPTO_PWHASH_STRPREFIX => $argon2i$ 
-SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MIN => 16 +\Sodium\CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE => 4 
-SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MAX => 64 +\Sodium\CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE => 33554432 
-SODIUM_CRYPTO_PWHASH_SALTBYTES => 16 +\Sodium\CRYPTO_PWHASH_OPSLIMIT_MODERATE => 6 
-SODIUM_CRYPTO_PWHASH_STRPREFIX => $argon2i$ +\Sodium\CRYPTO_PWHASH_MEMLIMIT_MODERATE => 134217728 
-SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE => 4 +\Sodium\CRYPTO_PWHASH_OPSLIMIT_SENSITIVE => 8 
-SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE => 33554432 +\Sodium\CRYPTO_PWHASH_MEMLIMIT_SENSITIVE => 536870912 
-SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE => 6 +\Sodium\CRYPTO_SCALARMULT_BYTES => 32 
-SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE => 134217728 +\Sodium\CRYPTO_SCALARMULT_SCALARBYTES => 32 
-SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE => 8 +\Sodium\CRYPTO_SHORTHASH_BYTES => 8 
-SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE => 536870912 +\Sodium\CRYPTO_SHORTHASH_KEYBYTES => 16 
-SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES => 32 +\Sodium\CRYPTO_SECRETBOX_KEYBYTES => 32 
-SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_STRPREFIX => $7$ +\Sodium\CRYPTO_SECRETBOX_MACBYTES => 16 
-SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE => 534288 +\Sodium\CRYPTO_SECRETBOX_NONCEBYTES => 24 
-SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE => 16777216 +\Sodium\CRYPTO_SIGN_BYTES => 64 
-SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_SENSITIVE => 33554432 +\Sodium\CRYPTO_SIGN_SEEDBYTES => 32 
-SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_SENSITIVE => 1073741824 +\Sodium\CRYPTO_SIGN_PUBLICKEYBYTES => 32 
-SODIUM_CRYPTO_SCALARMULT_BYTES => 32 +\Sodium\CRYPTO_SIGN_SECRETKEYBYTES => 64 
-SODIUM_CRYPTO_SCALARMULT_SCALARBYTES => 32 +\Sodium\CRYPTO_SIGN_KEYPAIRBYTES => 96 
-SODIUM_CRYPTO_SHORTHASH_BYTES => 8 +\Sodium\CRYPTO_STREAM_KEYBYTES => 32 
-SODIUM_CRYPTO_SHORTHASH_KEYBYTES => 16 +\Sodium\CRYPTO_STREAM_NONCEBYTES => 24
-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> </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 =====
rfc/libsodium.1464788871.txt.gz · Last modified: 2017/09/22 13:28 (external edit)

Page Tools