rfc:openssl_aead

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

Introduction

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.

Proposal

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.

Encryption

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.

Decryption

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

none

Proposed PHP Version(s)

PHP 7.1

RFC Impact

To SAPIs

none

To Existing Extensions

none

To Opcache

none

New Constants

none

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

Implementation

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

References

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)