Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:81534
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.213.181 as permitted sender)
MIME-Version: 1.0
Sender: rdlowrey@gmail.com
Date: Sun, 1 Feb 2015 12:49:19 -0500
Message-ID: <CAH8MpnktGy27BGFyH9i+tdfuMbti8KzHEXp=KD5LWy0vnKtxMw@mail.gmail.com>
To: "internals@lists.php.net" <internals@lists.php.net>
Content-Type: multipart/alternative; boundary=001a11346e3c04a3ec050e0a7575
Subject: Re: OpenSSL ext. improvements for authenticated cipher modes.
From: rdlowrey@php.net (Daniel Lowrey)

--001a11346e3c04a3ec050e0a7575
Content-Type: text/plain; charset=UTF-8

> Hi list,
>
> A couple of bug reports have highlighted the fact that our
> openssl_encrypt and openssl_decrupt functions have no way of getting
> or setting tags required for authenticated cipher modes (i.e. GCM,
> CCM, OCB (not sure if this is available in OpenSSL)).
>
> https://bugs.php.net/bug.php?id=68962
> https://bugs.php.net/bug.php?id=67304
>
> Further to this, we have no way of setting any associated data.
>
> I think we absolutely must provide a method for users to be able to
> use authenticated encryption, and would like some opinions on how much
> flexibility we give users, and the best method for exposing this
> functionality.
>
> At the very basic end of the spectrum, we could have openssl_get_tag
> and openssl_set_tag, or add an extra parameter to the end of
> openssl_encrypt and openssl_decrypt (pass by ref for encrypt, like
> preg $matches) this would cover the majority of use cases.
>
> However I absolutely think that the associated data also needs to be
> supported, and possibly the ability to change the tag length.
>
> At this point we're starting to get into the territory where an
> $options array is needed, or we add a lot of parameters to the end of
> functions. I don't really think it's good to add up to 3 more params
> to these functions.
>
> What do you guys and girls think is the best way of tackling this?

How about ...

Old API:
--------
string openssl_decrypt ( string $data , string $method , string $password
[, int $options = 0 [, string $iv = "" ]] )
string openssl_encrypt ( string $data , string $method , string $password
[, int $options = 0 [, string $iv = "" ]] )

New:
--------
mixed openssl_decrypt ( string $data , string $method , string $password [,
mixed $options = 0 [, string $iv = "" ]] )
string openssl_encrypt ( string $data , string $method , string $password
[, mixed $options = 0 [, string $iv = "" ]] )

The main changes are:

  - the $options parameter becomes mixed (either long or array) in both
functions
  - a long $options parameter triggers E_DEPRECATED in php7 (expects array)
  - the presence of an $iv triggers E_DEPRECATED in php7 (scheduled for
removal)
  - openssl_decrypt() now returns mixed ... if $options['get_tag'] == true
then return [$decryptedString, $tag], otherwise return $decrypted string as
before to preserve BC.
  - the encrypt function could use $options['set_tag'] to define that (or
any other secondary information needed for the operation).

This has zero BC implications, emits deprecation warnings for the old way
of doing it and finally provides a schedule for eventual removal of the
excessively verbose API in PHP8.

What I would prefer NOT to see is piling on more optional parameters to
these already too-long function signatures. Also, I don't really like the
idea of adding "state" to this operation with new
openssl_set_tag/openssl_get_tag functions.

Thoughts?

--001a11346e3c04a3ec050e0a7575--