From 6b6201edd9c0bff89474efbecc212ab6c7ec3d7d Mon Sep 17 00:00:00 2001
From: Christoph Michael Becker <cmb@php.net>
Date: Thu, 12 Jan 2017 18:31:07 +0000
Subject: [PATCH] Added docs for parameters of openssl_encrypt and
 openssl_decrypt introduced in https://wiki.php.net/rfc/openssl_aead

--
Provided by anonymous 77751 (me@jiripudil.cz)

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@341653 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../openssl/functions/openssl-decrypt.xml     | 22 +++++++++++++
 .../openssl/functions/openssl-encrypt.xml     | 31 +++++++++++++++++++
 2 files changed, 53 insertions(+)

diff --git a/reference/openssl/functions/openssl-decrypt.xml b/reference/openssl/functions/openssl-decrypt.xml
index c90f6ca986..6b0784b4b1 100644
--- a/reference/openssl/functions/openssl-decrypt.xml
+++ b/reference/openssl/functions/openssl-decrypt.xml
@@ -16,6 +16,8 @@
    <methodparam><type>string</type><parameter>password</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>0</initializer></methodparam>
    <methodparam choice="opt"><type>string</type><parameter>iv</parameter><initializer>""</initializer></methodparam>
+   <methodparam choice="opt"><type>string</type><parameter>tag</parameter><initializer>""</initializer></methodparam>
+   <methodparam choice="opt"><type>string</type><parameter>aad</parameter><initializer>""</initializer></methodparam>
   </methodsynopsis>
   <para>
    Takes a raw or base64 encoded string and decrypts it using a given method and key.
@@ -71,6 +73,22 @@
       </para>
      </listitem>
     </varlistentry>
+    <varlistentry>
+     <term><parameter>tag</parameter></term>
+     <listitem>
+      <para>
+       The authentication tag in AEAD cipher mode. If it is incorrect, the authentication fails and the function returns &false;.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>aad</parameter></term>
+     <listitem>
+      <para>
+       Additional authentication data.
+      </para>
+     </listitem>
+    </varlistentry>
    </variablelist>
   </para>
  </refsect1>
@@ -117,6 +135,10 @@
        The <parameter>raw_output</parameter> was changed to <parameter>options</parameter>.
       </entry>
      </row>
+     <row>
+      <entry>7.1.0</entry>
+      <entry>The <parameter>tag</parameter> and <parameter>aad</parameter> parameters were added.</entry>
+     </row>
     </tbody>
    </tgroup>
   </informaltable>
diff --git a/reference/openssl/functions/openssl-encrypt.xml b/reference/openssl/functions/openssl-encrypt.xml
index ebaba71df6..61e303b9b1 100644
--- a/reference/openssl/functions/openssl-encrypt.xml
+++ b/reference/openssl/functions/openssl-encrypt.xml
@@ -16,6 +16,9 @@
    <methodparam><type>string</type><parameter>password</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>0</initializer></methodparam>
    <methodparam choice="opt"><type>string</type><parameter>iv</parameter><initializer>""</initializer></methodparam>
+   <methodparam choice="opt"><type>string</type><parameter role="reference">tag</parameter><initializer>NULL</initializer></methodparam>
+   <methodparam choice="opt"><type>string</type><parameter>aad</parameter><initializer>""</initializer></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>tag_length</parameter><initializer>16</initializer></methodparam>
   </methodsynopsis>
   <para>
    Encrypts given data with given method and key, returns a raw
@@ -69,6 +72,30 @@
       </para>
      </listitem>
     </varlistentry>
+    <varlistentry>
+     <term><parameter>tag</parameter></term>
+     <listitem>
+      <para>
+       The authentication tag passed by reference when using AEAD cipher mode (GCM or CCM).
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>aad</parameter></term>
+     <listitem>
+      <para>
+       Additional authentication data.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>tag_length</parameter></term>
+     <listitem>
+      <para>
+       The length of the authentication <parameter>tag</parameter>. Its value can be between 4 and 16 for GCM mode.
+      </para>
+     </listitem>
+    </varlistentry>
    </variablelist>
   </para>
  </refsect1>
@@ -115,6 +142,10 @@
        The <parameter>raw_output</parameter> was changed to <parameter>options</parameter>.
       </entry>
      </row>
+     <row>
+      <entry>7.1.0</entry>
+      <entry>The <parameter>tag</parameter>, <parameter>aad</parameter> and <parameter>tag_length</parameter> parameters were added.</entry>
+     </row>
     </tbody>
    </tgroup>
   </informaltable>