rfc:libsodium
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision | ||
rfc:libsodium [2016/06/01 07:49] – sarciszewski | rfc:libsodium [2017/02/10 21:02] – Voting closes sarciszewski | ||
---|---|---|---|
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, | * Author: Scott Arciszewski, | ||
- | * Status: | + | * Status: |
* First Published at: http:// | * First Published at: http:// | ||
Line 10: | Line 10: | ||
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. | 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, | + | Meanwhile, libsodium |
Libsodium is a modern cryptography library that offers authenticated encryption, high-speed elliptic curve cryptography, | Libsodium is a modern cryptography library that offers authenticated encryption, high-speed elliptic curve cryptography, | ||
- | I maintain the ext/ | + | I maintain the documentation |
===== Proposal ===== | ===== Proposal ===== | ||
- | This proposal is to adopt the libsodium extension in the PHP core in PHP 7.1.0. | + | This proposal is to adopt the libsodium extension |
- | 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 |
< | < | ||
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:// | ||
+ | |||
+ | 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 ===== | ||
- | I'm not aware of any potential impact that adopting | + | I'm not aware of any potential impact that adopting |
+ | |||
+ | |||
+ | ===== 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. | ||
+ | |||
+ | < | ||
+ | \Sodium\CRYPTO_AEAD_CHACHA20POLY1305_KEYBYTES => | ||
+ | \Sodium\CRYPTO_AEAD_CHACHA20POLY1305_NSECBYTES => | ||
+ | \Sodium\CRYPTO_AEAD_CHACHA20POLY1305_NPUBBYTES => | ||
+ | \Sodium\CRYPTO_AEAD_CHACHA20POLY1305_ABYTES => | ||
+ | \Sodium\CRYPTO_AEAD_CHACHA20POLY1305_IETF_KEYBYTES => | ||
+ | \Sodium\CRYPTO_AEAD_CHACHA20POLY1305_IETF_NSECBYTES => | ||
+ | \Sodium\CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES => | ||
+ | \Sodium\CRYPTO_AEAD_CHACHA20POLY1305_IETF_ABYTES => | ||
+ | \Sodium\CRYPTO_AUTH_BYTES => | ||
+ | \Sodium\CRYPTO_AUTH_KEYBYTES => | ||
+ | \Sodium\CRYPTO_BOX_SEALBYTES => | ||
+ | \Sodium\CRYPTO_BOX_SECRETKEYBYTES => | ||
+ | \Sodium\CRYPTO_BOX_PUBLICKEYBYTES => | ||
+ | \Sodium\CRYPTO_BOX_KEYPAIRBYTES => | ||
+ | \Sodium\CRYPTO_BOX_MACBYTES => | ||
+ | \Sodium\CRYPTO_BOX_NONCEBYTES => | ||
+ | \Sodium\CRYPTO_BOX_SEEDBYTES => | ||
+ | \Sodium\CRYPTO_KX_BYTES => | ||
+ | \Sodium\CRYPTO_KX_PUBLICKEYBYTES => | ||
+ | \Sodium\CRYPTO_KX_SECRETKEYBYTES => | ||
+ | \Sodium\CRYPTO_GENERICHASH_BYTES => | ||
+ | \Sodium\CRYPTO_GENERICHASH_BYTES_MIN => | ||
+ | \Sodium\CRYPTO_GENERICHASH_BYTES_MAX => | ||
+ | \Sodium\CRYPTO_GENERICHASH_KEYBYTES => | ||
+ | \Sodium\CRYPTO_GENERICHASH_KEYBYTES_MIN => | ||
+ | \Sodium\CRYPTO_GENERICHASH_KEYBYTES_MAX => | ||
+ | \Sodium\CRYPTO_PWHASH_SALTBYTES => | ||
+ | \Sodium\CRYPTO_PWHASH_STRPREFIX => | ||
+ | \Sodium\CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE => | ||
+ | \Sodium\CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE => | ||
+ | \Sodium\CRYPTO_PWHASH_OPSLIMIT_MODERATE => | ||
+ | \Sodium\CRYPTO_PWHASH_MEMLIMIT_MODERATE => | ||
+ | \Sodium\CRYPTO_PWHASH_OPSLIMIT_SENSITIVE => | ||
+ | \Sodium\CRYPTO_PWHASH_MEMLIMIT_SENSITIVE => | ||
+ | \Sodium\CRYPTO_SCALARMULT_BYTES => | ||
+ | \Sodium\CRYPTO_SCALARMULT_SCALARBYTES => | ||
+ | \Sodium\CRYPTO_SHORTHASH_BYTES => | ||
+ | \Sodium\CRYPTO_SHORTHASH_KEYBYTES => | ||
+ | \Sodium\CRYPTO_SECRETBOX_KEYBYTES => | ||
+ | \Sodium\CRYPTO_SECRETBOX_MACBYTES => | ||
+ | \Sodium\CRYPTO_SECRETBOX_NONCEBYTES => | ||
+ | \Sodium\CRYPTO_SIGN_BYTES => | ||
+ | \Sodium\CRYPTO_SIGN_SEEDBYTES => | ||
+ | \Sodium\CRYPTO_SIGN_PUBLICKEYBYTES => | ||
+ | \Sodium\CRYPTO_SIGN_SECRETKEYBYTES => | ||
+ | \Sodium\CRYPTO_SIGN_KEYPAIRBYTES => | ||
+ | \Sodium\CRYPTO_STREAM_KEYBYTES => | ||
+ | \Sodium\CRYPTO_STREAM_NONCEBYTES => | ||
+ | </ | ||
+ | |||
+ | ===== 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=" | ||
+ | * Yes | ||
+ | * No | ||
+ | </ | ||
- | ==== New Constants ==== | + | Second vote: Vote YES to keep the namespace (\Sodium\etc), |
- | See the list of all libsodium constants in the reference. In every case, < | + | <doodle title=" |
+ | * Yes, \Sodium\foo | ||
+ | * No, sodium_foo | ||
+ | </doodle> | ||
===== References ===== | ===== References ===== |
rfc/libsodium.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1