correcting error in openssl-pkey-get-public doc page

in openssl_verify and openssl_sign
* adding self-contained examples
* documenting that the 4th param to can be an int or a string
* improving documentation of params




git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@332644 c90b9560-bf6c-de11-be94-00142212c4b1

reference/openssl/functions/openssl-pkey-get-public.xml

@@ -32,10 +32,10 @@
         <listitem><simpara>an X.509 certificate resource</simpara></listitem>
         <listitem><simpara>a string having the format
           <filename>file://path/to/file.pem</filename>. The named file must
-          contain a PEM encoded certificate/private key (it may contain both).
+          contain a PEM encoded certificate/public key (it may contain both).
          </simpara>
         </listitem>
-        <listitem><simpara>A PEM formatted private key.</simpara></listitem>
+        <listitem><simpara>A PEM formatted public key.</simpara></listitem>
        </orderedlist>
       </para>
      </listitem>

reference/openssl/functions/openssl-sign.xml

@@ -13,12 +13,12 @@
    <methodparam><type>string</type><parameter>data</parameter></methodparam>
    <methodparam><type>string</type><parameter role="reference">signature</parameter></methodparam>
    <methodparam><type>mixed</type><parameter>priv_key_id</parameter></methodparam>
-   <methodparam choice="opt"><type>int</type><parameter>signature_alg</parameter><initializer>OPENSSL_ALGO_SHA1</initializer></methodparam>
+   <methodparam choice="opt"><type>mixed</type><parameter>signature_alg</parameter><initializer>OPENSSL_ALGO_SHA1</initializer></methodparam>
   </methodsynopsis>
   <para>
    <function>openssl_sign</function> computes a signature for the
-   specified <parameter>data</parameter> by using SHA1 for hashing
-   followed by encryption using the private key associated with
+   specified <parameter>data</parameter> by generating a cryptographic
+   digital signature using the private key associated with
    <parameter>priv_key_id</parameter>. Note that the data itself is
    not encrypted.
   </para>
@@ -32,6 +32,7 @@
      <term><parameter>data</parameter></term>
      <listitem>
       <para>
+       The string of data you wish to sign
       </para>
      </listitem>
     </varlistentry>
@@ -48,6 +49,10 @@
      <term><parameter>priv_key_id</parameter></term>
      <listitem>
       <para>
+       <type>resource</type> - a key, returned by <function>openssl_get_privatekey</function>
+      </para>
+      <para>
+       <type>string</type> - a PEM formatted key
       </para>
      </listitem>
     </varlistentry>
@@ -55,8 +60,10 @@
      <term><parameter>signature_alg</parameter></term>
      <listitem>
       <para>
-       For more information see the list of <link
-       linkend="openssl.signature-algos">Signature Algorithms</link>.
+       <type>int</type> - one of these <link linkend="openssl.signature-algos">Signature Algorithms</link>.
+      </para>
+      <para>
+       <type>string</type> - a valid string returned by <function>openssl_get_md_methods</function> example, "sha256WithRSAEncryption" or "sha384".
       </para>
      </listitem>
     </varlistentry>
@@ -106,10 +113,7 @@
 // $data is assumed to contain the data to be signed
 
 // fetch private key from file and ready it
-$fp = fopen("/src/openssl-0.9.6/demos/sign/key.pem", "r");
-$priv_key = fread($fp, 8192);
-fclose($fp);
-$pkeyid = openssl_get_privatekey($priv_key);
+$pkeyid = openssl_pkey_get_private("file://src/openssl-0.9.6/demos/sign/key.pem");
 
 // compute signature
 openssl_sign($data, $signature, $pkeyid);
@@ -120,6 +124,40 @@ openssl_free_key($pkeyid);
 ]]>
     </programlisting>
    </example>
+   <example>
+    <title><function>openssl_sign</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+//data you want to sign
+$data = 'my data';
+
+//create new private and public key
+$new_key_pair = openssl_pkey_new(array(
+    "private_key_bits" => 2048,
+    "private_key_type" => OPENSSL_KEYTYPE_RSA,
+));
+openssl_pkey_export($new_key_pair, $private_key_pem);
+
+$details = openssl_pkey_get_details($new_key_pair);
+$public_key_pem = $details['key'];
+
+//create signature
+openssl_sign($data, $signature, $private_key_pem, OPENSSL_ALGO_SHA256);
+
+//save for later
+file_put_contents('private_key.pem', $private_key_pem);
+file_put_contents('public_key.pem', $public_key_pem);
+file_put_contents('signature.dat', $signature);
+
+//verify signature
+$r = openssl_verify($data, $signature, $public_key_pem, "sha256WithRSAEncryption");
+var_dump($r);
+?>
+]]>
+    </programlisting>
+   </example>
+ 
   </para>
  </refsect1>
 

reference/openssl/functions/openssl-verify.xml

@@ -13,7 +13,7 @@
    <methodparam><type>string</type><parameter>data</parameter></methodparam>
    <methodparam><type>string</type><parameter>signature</parameter></methodparam>
    <methodparam><type>mixed</type><parameter>pub_key_id</parameter></methodparam>
-   <methodparam choice="opt"><type>int</type><parameter>signature_alg</parameter><initializer>OPENSSL_ALGO_SHA1</initializer></methodparam>
+   <methodparam choice="opt"><type>mixed</type><parameter>signature_alg</parameter><initializer>OPENSSL_ALGO_SHA1</initializer></methodparam>
   </methodsynopsis>
   <para>
    <function>openssl_verify</function> verifies that the
@@ -32,6 +32,7 @@
      <term><parameter>data</parameter></term>
      <listitem>
       <para>
+       The string of data used to generate the signature previously
       </para>
      </listitem>
     </varlistentry>
@@ -39,6 +40,7 @@
      <term><parameter>signature</parameter></term>
      <listitem>
       <para>
+       A raw binary string, generated by <function>openssl_sign</function> or similar means
       </para>
      </listitem>
     </varlistentry>
@@ -46,15 +48,22 @@
      <term><parameter>pub_key_id</parameter></term>
      <listitem>
       <para>
+       <type>resource</type> - a key, returned by <function>openssl_get_publickey</function>
       </para>
+      <para>
+       <type>string</type> - a PEM formatted key, example, "-----BEGIN PUBLIC KEY-----
+MIIBCgK..."
+      </para>     
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>signature_alg</parameter></term>
      <listitem>
       <para>
-       For more information see the list of <link
-       linkend="openssl.signature-algos">Signature Algorithms</link>.
+       <type>int</type> - one of these <link linkend="openssl.signature-algos">Signature Algorithms</link>.
+      </para>
+      <para>
+       <type>string</type> - a valid string returned by <function>openssl_get_md_methods</function> example, "sha1WithRSAEncryption" or "sha512".
       </para>
      </listitem>
     </varlistentry>
@@ -105,10 +114,7 @@
 // $data and $signature are assumed to contain the data and the signature
 
 // fetch public key from certificate and ready it
-$fp = fopen("/src/openssl-0.9.6/demos/sign/cert.pem", "r");
-$cert = fread($fp, 8192);
-fclose($fp);
-$pubkeyid = openssl_get_publickey($cert);
+$pubkeyid = openssl_pkey_get_public("file://src/openssl-0.9.6/demos/sign/cert.pem");
 
 // state whether signature is okay or not
 $ok = openssl_verify($data, $signature, $pubkeyid);
@@ -122,6 +128,38 @@ if ($ok == 1) {
 // free the key from memory
 openssl_free_key($pubkeyid);
 ?>
+]]>
+    </programlisting>
+   </example>
+   <example>
+    <title><function>openssl_verify</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+//data you want to sign
+$data = 'my data';
+
+//create new private and public key
+$private_key_res = openssl_pkey_new(array(
+    "private_key_bits" => 2048,
+    "private_key_type" => OPENSSL_KEYTYPE_RSA,
+));
+$details = openssl_pkey_get_details($private_key_res);
+$public_key_res = openssl_pkey_get_public($details['key']);
+
+//create signature
+openssl_sign($data, $signature, $private_key_res, "sha1WithRSAEncryption");
+
+//verify signature
+$ok = openssl_verify($data, $signature, $public_key_res, OPENSSL_ALGO_SHA1);
+if ($ok == 1) {
+    echo "valid";
+} elseif ($ok == 0) {
+    echo "invalid";
+} else {
+    echo "error: ".openssl_error_string();
+}
+?>
 ]]>
     </programlisting>
    </example>