This is an old revision of the document!

PHP RFC: Your Title Here

  • 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.


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 ]]]])

== New parameters description

  • $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. It is the same for GCM mode like trimming the tag but it results in a different tag for CCM mode.


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 = "" ]]]] )

== New parameters description

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

Backward Incompatible Changes


Proposed PHP Version(s)

PHP 7.1

RFC Impact



To Existing Extensions


To Opcache


New Constants


Open Issues

Tag length and parameters order.

Unaffected PHP Functionality

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

Future Scope

Adding support for OCB mode once the extension supports OpenSSL 1.1

Proposed Voting Choices

50%+1 majority

Patches and Tests


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

Rejected Features

Keep this updated with features that were discussed on the mail lists.

rfc/openssl_aead.1451914897.txt.gz · Last modified: 2017/09/22 13:28 (external edit)