Doc #76794 [Opn->Csd]: Incorrect use of "$keypair" in LibSodium signing functions

Edit report at https://bugs.php.net/bug.php?id=76794&edit=1 ID: 76794 Updated by: cmb@php.net Reported by: craig at craigfrancis dot co dot uk Summary: Incorrect use of "$keypair" in LibSodium signing functions -Status: Open +Status: Closed Type: Documentation Problem Package: *Encryption and hash functions PHP Version: Irrelevant -Assigned To: +Assigned To: cmb Block user comment: N Private report: N New Comment: This has been fixed in the meantime. The reference for the docs are the stub file snow, e.g. <https://github.com/php/php-src/blob/php-8.0.6/ext/sodium/libsodium.stub.php>. Previous Comments: ------------------------------------------------------------------------ [2018-08-27 14:24:10] craig at craigfrancis dot co dot uk I'm assuming: https://github.com/php/php-src/blob/49a4e695845bf55e059e7f88e54b1111fe284223/ext/sodium/libsodium.c#L321 Needs to be changed from: PHP_FE(sodium_crypto_sign_detached, AI_StringAndKeyPair) To either use AI_StringAndKey (leaving it ambiguous as to the key type) PHP_FE(sodium_crypto_sign_detached, AI_StringAndKey) Or to introduce some new ARG_INFO's: ZEND_BEGIN_ARG_INFO_EX(AI_StringAndSecretKey, 0, 0, 2) ZEND_ARG_INFO(0, string) ZEND_ARG_INFO(0, secret_key) ZEND_END_ARG_INFO() ZEND_BEGIN_ARG_INFO_EX(AI_StringAndPublicKey, 0, 0, 2) ZEND_ARG_INFO(0, string) ZEND_ARG_INFO(0, public_key) ZEND_END_ARG_INFO() ... PHP_FE(sodium_crypto_sign_detached, AI_StringAndSecretKey) PHP_FE(sodium_crypto_sign_open, AI_StringAndPublicKey) ------------------------------------------------------------------------ [2018-08-27 14:07:45] craig at craigfrancis dot co dot uk Fair point... in which case the underlying code needs to be fixed. Taking sodium_crypto_sign_detached as an example: <?php $key_pair = sodium_crypto_sign_keypair(); $secret_key = sodium_crypto_sign_secretkey($key_pair); $public_key = sodium_crypto_sign_publickey($key_pair); $signature = sodium_crypto_sign_detached('Hello', $secret_key); $signature = sodium_crypto_sign_detached('Hello', $key_pair); ?> The second line, which is provided a keypair (as per the documentation), returns the following error: SodiumException: secret key size should be SODIUM_CRYPTO_SIGN_SECRETKEYBYTES bytes And if you go to the LibSodium documentation, it references "sk" (aka the secret key): "The crypto_sign_detached() function signs the message m whose length is mlen bytes, using the secret key sk..." https://download.libsodium.org/doc/public-key_cryptography/public-key_signatures.html#detached-mode Do I assume that all the LibSodium functions will need to be checked/updated? ------------------------------------------------------------------------ [2018-08-27 12:52:38] cmb@php.net In my opinion, it is most sensible to document the parameter names as they are given by reflection. E.g.: # php --rf sodium_crypto_sign_detached Function [ <internal:sodium> function sodium_crypto_sign_detached ] { - Parameters [2] { Parameter #0 [ <required> $string ] Parameter #1 [ <required> $keypair ] } } # php --rf sodium_crypto_sign Function [ <internal:sodium> function sodium_crypto_sign ] { - Parameters [2] { Parameter #0 [ <required> $string ] Parameter #1 [ <required> $keypair ] } } ------------------------------------------------------------------------ [2018-08-25 19:20:20] craig at craigfrancis dot co dot uk Description: ------------ http://www.php.net/function.sodium-crypto-sign-detached.php Needs to be changed from "$keypair" to "$secret_key". http://www.php.net/function.sodium-crypto-sign-open http://www.php.net/function.sodium-crypto-sign-verify-detached Both should use "$public_key" - not "$keypair" or "$key". This would be consistent with the use of "$secret_key" in the signing function: http://www.php.net/function.sodium-crypto-sign.php ------------------------------------------------------------------------ -- Edit this bug report at https://bugs.php.net/bug.php?id=76794&edit=1