Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:93685
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain paragonie.com designates 209.85.218.43 as permitted sender)
MIME-Version: 1.0
In-Reply-To: <295c09d5-01af-1528-8e61-00dc6ee6c69e@fleshgrinder.com>
References: <CAKws9z114YcHkDaXO3o-E0JuHR10WsPzyedeF_8Q=shHDziwug@mail.gmail.com>
	<CADyq6sKr_6qi4Fnk9+yxgCA5j_xF7B7vxq7HH5_nneax5bLf5A@mail.gmail.com>
	<295c09d5-01af-1528-8e61-00dc6ee6c69e@fleshgrinder.com>
Date: Wed, 1 Jun 2016 13:53:13 -0400
Message-ID: <CAKws9z1k44MW+4JQ=BQ2W9j1=eYiNb2ieb7v5CwqesaGu7wLPw@mail.gmail.com>
To: PHP Internals <internals@lists.php.net>
Cc: Marco Pivetta <ocramius@gmail.com>
Content-Type: multipart/alternative; boundary=001a113cddece1abd505343b29a1
Subject: Re: [PHP-DEV] [RFC] Libsodium - Discussion
From: scott@paragonie.com (Scott Arciszewski)

--001a113cddece1abd505343b29a1
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

On Wed, Jun 1, 2016 at 1:26 PM, Fleshgrinder <php@fleshgrinder.com> wrote:

> 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 actual=
ly
> > does, like `sodium_encrypt_and_sign()`. While the naming may be emergin=
g
> > 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 ju=
st
> > 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
>
>
=E2=80=8BWell, for what it's worth, I did write https://github.com/paragoni=
e/halite
=E2=80=8B as a high-level abstraction.

The goal of this RFC is to get the lower-level functionality (which is
still, I promise, a high-level cryptography API) available.=E2=80=8B


Scott Arciszewski
Chief Development Officer
Paragon Initiative Enterprises <https://paragonie.com/>=E2=80=8B

--001a113cddece1abd505343b29a1--