PHP RFC: OpenSSL AEAD support

• Version: 0.1
• Date: 2016-01-02
• Author: Jakub Zelenka, bukka@php.net
• Status: Draft

The PHP OpenSSL extension provides functions for data encryption (openssl_encrypt) and decryption (openssl_decrypt). These function works fine for all cipher algorithms (cipher + mode) except ciphers with AEAD (Authenticated Encrypt with Associated Data) mode. These modes requires special handling in OpenSSL and a need for supplying resp. retrieving of the authenticated tag and optionally AAD (associated application data).

There are two AEAD modes supported by OpenSSL (up to version 1.0.2) - GCM (Galois Counter Mode) and CCM (Counter with CBC-MAC). Both of these modes currently fails on decryption as there is no way how to supply an authentication tag and there are some internal OpenSSL API that doesn't allow it to use it in the same way (e.g. there is no context finalization for CCM mode).

This RFC proposes adding extra parameters to openssl_encrypt resp. openssl_decrypt for retrieving resp. supplying an authenticated tag and AAD. These parameters are optional and are used only for supported AEAD modes (GCM and CCM). The parameters differs for each function.

The new prototype for openssl_encrypt is following:

string openssl_encrypt ( string $data , string $method , string $password 
    [, int $options = 0 [, string $iv = "" [, string &$tag = "" [, string $aad = "" [, int $tag_length = 16 ]]]])

• $tag - The authentication tag will be saved to the variable passed as a reference on successful encryption. If the encryption fails, then the variable is unchanged. The resulted tag length is as supplied in the $tag_length parameter.
• $aad - Additional authentication data.
• $tag_length - The tag length can be set before the encryption. The tag length can be between 4 and 16 GCM mode where it is the same like trimming the tag. However CCM has no limit and the resulted tag is different for each lenght

The new prototype for openssl_decrypt is following:

string openssl_decrypt ( string $data , string $method , string $password 
    [, int $options = 0 [, string $iv = "" [, string $tag = "" [, string $aad = "" ]]]] )

• $tag - The authentication tag that will be authenticated. If it's incorrect, then the function returns FALSE.
• $aad - Additional authentication data.

none

PHP 7.1

none

none

none

none

Tag length and parameters order.

The current encryption and decryption is unaffected. The new parameters are optional.

Adding support for OCB mode once the extension supports OpenSSL 1.1

50%+1 majority

https://github.com/php/php-src/compare/master...bukka:openssl_aead

After the project is implemented, this section should contain

1. the version(s) it was merged to
2. a link to the git commit(s)
3. a link to the PHP manual entry for the feature

Links to external references, discussions or RFCs

There has been discussion about introducing an object that would wrap the context and offered functions for setting tag, AAD, key, IV and making partials updates. However such functionality is already implemented in crypto extension and requires much more code (about extra 1000 lines) to address all possible exceptions. The main thing is that this is not contradicting to this proposal as it could easily co-exist as we will still have to keep openssl_ecrypt and openssl_decrypt working. This proposal is just about extending these two function for AEAD mode support.