Differences

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

--- rfc:libsodium [2016/06/01 14:09] – sarciszewski
+++ rfc:libsodium [2017/08/08 15:27] – this RFC has already been implemented cmb
@@ Line 1: / Line 1: @@
 ====== 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
-  * Status: Under Discussion
+  * Status: Implemented
   * First Published at: http://wiki.php.net/rfc/libsodium
@@ Line 18: / Line 18: @@
 ===== 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 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).
@@ Line 59: / Line 59: @@
   * 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) =====
-This RFC targets PHP 7.1.
+This RFC targets PHP 7.2.
 ===== RFC Impact =====
@@ Line 68: / Line 124: @@
 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.
 <code>
-\Sodium\CRYPTO_AEAD_AES256GCM_KEYBYTES	=>	32
-\Sodium\CRYPTO_AEAD_AES256GCM_NSECBYTES	=>	0
-\Sodium\CRYPTO_AEAD_AES256GCM_NPUBBYTES	=>	12
-\Sodium\CRYPTO_AEAD_AES256GCM_ABYTES	=>	16
 \Sodium\CRYPTO_AEAD_CHACHA20POLY1305_KEYBYTES	=>	32
 \Sodium\CRYPTO_AEAD_CHACHA20POLY1305_NSECBYTES	=>	0
@@ Line 84: / Line 141: @@
 \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
@@ Line 111: / Line 168: @@
 \Sodium\CRYPTO_PWHASH_OPSLIMIT_SENSITIVE	=>	8
 \Sodium\CRYPTO_PWHASH_MEMLIMIT_SENSITIVE	=>	536870912
-\Sodium\CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES	=>	32
-\Sodium\CRYPTO_PWHASH_SCRYPTSALSA208SHA256_STRPREFIX	=>	$7$
-\Sodium\CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE	=>	534288
-\Sodium\CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE	=>	16777216
-\Sodium\CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_SENSITIVE	=>	33554432
-\Sodium\CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_SENSITIVE	=>	1073741824
 \Sodium\CRYPTO_SCALARMULT_BYTES	=>	32
 \Sodium\CRYPTO_SCALARMULT_SCALARBYTES	=>	32
@@ Line 132: / Line 183: @@
 \Sodium\CRYPTO_STREAM_NONCEBYTES	=>	24
 </code>
 ===== Proposed Voting Choices =====
-Vote YES to add ext/sodium to PHP 7.1. A 50%+1 majority should be sufficient.
-Second vote: Vote YES to keep the namespace (\Sodium\etc), vote NO to switch to a prefix in the global namespace (sodium_etc). This constitutes an inconsistency with PHP's coding standard and therefore should require a 2/3 majority.
+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 =====

Differences

Page Tools