Re: [PHP-DEV] [RFC] Libsodium - Discussion

[Fleshgrinder]

On 6/1/2016 12:48 PM, Marco Pivetta wrote:

> I also agree with Remi on naming: let's avoid calling the extension
> `libsodium`.
> 

I agree here too.

On 6/1/2016 12:48 PM, Marco Pivetta wrote:
>  1. is there a particular reason why abbreviations are used? For instance,
> why `sodium_randombytes_buf()` instead of `sodium_random_bytes_buffer()`?
>  2. from a naming perspective, I'd expect `sodium_randombytes_buf()` to
> give me a buffer of random bytes (probably as a stream), but it returns the
> actual string of random bytes. Again: confusing naming
>  3. can we avoid using "themed" naming? For example, instead of
> `sodium_crypto_secretbox()`, it would be best to express what it actually
> does, like `sodium_encrypt_and_sign()`. While the naming may be emerging
> from lower layers, I still (like I did with other RFCs) disagree with
> inheriting confusing naming. This will just cause users to look up the
> naming up when reading or writing code, and ultimately add up to silly
> bugs. I can already foresee that people will use the API incorrectly just
> because of the naming.
>

I agree here too but read on.

On 6/1/2016 12:48 PM, Marco Pivetta wrote:
>  4. can't we just keep it namespaced under `Sodium`, instead of adding more
> stuff to the root level namespace? Does anyone have a reference to the
> coding standards that would cause the rename?
> 

I was the person who brought this up because it is not desired according
to the existing CODING STANDARD:

https://github.com/php/php-src/blob/master/CODING_STANDARDS

Note that it also encourages this weird C style naming with
abbreviations, hence, I would be open for discussing it. That being
said, I am not a friend of putting procedural functions into namespaces
and prefer the establish prefix approach.

That being said, I see many opportunities here to create very nice
classes that enable dependency injection, single validation, and of
course I am +1000 for namespaces here. It would also help a lot to get
some of those extremely weird names out of the window.

  namespace Sodium;

  interface SodiumException extends \Throwable {}

  class SignatureException
    extends \UnexpectedValueException
    implements SodiumException {}

  class DetachedSignature {

    public function __construct(string $detached_signature);

    public function __toString(): string;

    public function verify(string $message, PublicKey $public): bool;

  }

  class SignedMessage {

    public function __construct(string $signed_message);

    public function __toString(): string;

    public function getSignature(): DetachedSignature;

  }

  interface Key {

  }

  class PrivateKey implements Key {

    public function sign(string $message): SignedMessage;

  }

  class PublicKey implements Key {

    public function verify(SignedMessage $message): bool;

  }

  class KeyPair {

    public function __construct(PrivateKey $private, PublicKey $public);

    public static function generate(): KeyPair;

    public function getPrivate(): PrivateKey;

    public function getPublic(): PublicKey;

  }

This is of course an attempt of writing up some classes after looking at
the API for literally 5 minutes but I think it illustrated the
potential. It is also going to increase the security by a huge margin
because a private key suddenly has to be an instance of a PrivateKey and
not some arbitrary string that needs to be revalidated all the time.

The same software design principles apply as always and the current API
might be nice for C but it is definitely not for PHP in my opinion.

Of course I offer my help to find and define such an API if you guys are
interested in creating one. :)

-- 
Richard "Fleshgrinder" Fussenegger

signature.asc
Description: OpenPGP digital signature