From 5b848aeb03fc31ee104960eea4d1c7367b4ee83a Mon Sep 17 00:00:00 2001
From: Mark Jones <mjones@php.net>
Date: Wed, 6 Sep 2017 20:12:43 +0000
Subject: [PATCH] documenting openssl encrypt/decrypt

https://bugs.php.net/bug.php?id=71817


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@343016 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../openssl/functions/openssl-decrypt.xml     |  7 +--
 .../openssl/functions/openssl-encrypt.xml     | 62 ++++++++++++++++++-
 2 files changed, 64 insertions(+), 5 deletions(-)

diff --git a/reference/openssl/functions/openssl-decrypt.xml b/reference/openssl/functions/openssl-decrypt.xml
index de9195edbc..ef6a802c32 100644
--- a/reference/openssl/functions/openssl-decrypt.xml
+++ b/reference/openssl/functions/openssl-decrypt.xml
@@ -23,8 +23,6 @@
    Takes a raw or base64 encoded string and decrypts it using a given method and key.
   </para>
 
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -35,7 +33,7 @@
      <term><parameter>data</parameter></term>
      <listitem>
       <para>
-       The data.
+       The encrypted message to be decrypted.
       </para>
      </listitem>
     </varlistentry>
@@ -43,7 +41,8 @@
      <term><parameter>method</parameter></term>
      <listitem>
       <para>
-       The cipher method.
+       The cipher method. For a list of available cipher methods, use 
+       <function>openssl_get_cipher_methods</function>.  
       </para>
      </listitem>
     </varlistentry>
diff --git a/reference/openssl/functions/openssl-encrypt.xml b/reference/openssl/functions/openssl-encrypt.xml
index de7ddfb671..be59ac678a 100644
--- a/reference/openssl/functions/openssl-encrypt.xml
+++ b/reference/openssl/functions/openssl-encrypt.xml
@@ -34,7 +34,7 @@
      <term><parameter>data</parameter></term>
      <listitem>
       <para>
-       The data.
+       The plaintext message data to be encrypted.
       </para>
      </listitem>
     </varlistentry>
@@ -151,6 +151,66 @@
   </informaltable>
  </refsect1>
 
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>AES Authenticated Encryption in GCM mode example for PHP 7.1+</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+//$key should have been previously generated in a cryptographically safe way, like openssl_random_pseudo_bytes
+$plaintext = "message to be encrypted";
+$cipher = "aes-128-gcm";
+if (in_array($cipher, openssl_get_cipher_methods()))
+{
+	$ivlen = openssl_cipher_iv_length($cipher);
+	$iv = openssl_random_pseudo_bytes($ivlen);
+	$ciphertext = openssl_encrypt($plaintext, $cipher, $key, $options=0, $iv, $tag);
+	//store $cipher, $iv, and $tag for decryption later
+	$original_plaintext = openssl_decrypt($ciphertext, $cipher, $key, $options=0, $iv, $tag);
+	echo $original_plaintext."\n";
+}
+?>
+]]>
+    </programlisting>
+   </example>
+
+   <example>
+    <title>AES Authenticated Encryption example for PHP 5.6+</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+//$key previously generated safely, ie: openssl_random_pseudo_bytes
+$plaintext = "message to be encrypted";
+$ivlen = openssl_cipher_iv_length($cipher="AES-128-CBC");
+$iv = openssl_random_pseudo_bytes($ivlen);
+$ciphertext_raw = openssl_encrypt($plaintext, $cipher, $key, $options=OPENSSL_RAW_DATA, $iv);
+$hmac = hash_hmac('sha256', $ciphertext_raw, $key, $as_binary=true);
+$ciphertext = base64_encode( $iv.$hmac.$ciphertext_raw );
+
+//decrypt later....
+$c = base64_decode($ciphertext);
+$ivlen = openssl_cipher_iv_length($cipher="AES-128-CBC");
+$iv = substr($c, 0, $ivlen);
+$hmac = substr($c, $ivlen, $sha2len=32);
+$ciphertext_raw = substr($c, $ivlen+$sha2len);
+$original_plaintext = openssl_decrypt($ciphertext_raw, $cipher, $key, $options=OPENSSL_RAW_DATA, $iv);
+$calcmac = hash_hmac('sha256', $ciphertext_raw, $key, $as_binary=true);
+if (hash_equals($hmac, $calcmac))//PHP 5.6+ timing attack safe comparison
+{
+	echo $original_plaintext."\n";
+}
+?>
+]]>
+    </programlisting>
+   </example>
+
+  </para>
+ </refsect1>
+
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>