Document openssl.cnf related issues, and add an example of how to act as a

certificate authority using PHP.


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

reference/openssl/configure.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <section id="openssl.installation">
  &reftitle.install;
  <para>
@@ -14,6 +14,50 @@
    package to the SYSTEM32 folder of your windows machine. (Ex: C:\WINNT\SYSTEM32
    or C:\WINDOWS\SYSTEM32)
   </simpara>
+  <simpara>
+   Additionally, if you are planning to use the key generation and certificate
+   signing functions, you will need to install a valid
+   <filename>openssl.cnf</filename> on your system.  As of PHP 4.3.0, we
+   include a sample configuration file in the <filename>openssl</filename> of
+   our win32 binary distribution.  If you are using PHP 4.2.0 or later and are
+   missing the file, you can obtain it from <ulink url="&url.openssl;">the
+   OpenSSL home page</ulink> or by downloading the PHP 4.3.0 release and using
+   the configuration file from there.
+  </simpara>
+  <para>
+   PHP will search for the <filename>openssl.cnf</filename> using the
+   following logic:
+   <itemizedlist>
+    <listitem>
+     <simpara>the <literal>OPENSSL_CONF</literal> environmental variable, if
+      set, will be used as the path (including filename) of the configuration
+      file.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>the <literal>SSLEAY_CONF</literal> environmental variable, if
+      set, will be used as the path (including filename) of the configuration
+      file.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>The file <filename>openssl.cnf</filename> will be assumed to be
+      found in the default certificate area, as configured at the time that
+      the openssl DLL was compiled.  This is usually means that the default
+      filename is <filename>c:\usr\local\ssl\openssl.cnf</filename>.
+     </simpara>
+    </listitem>
+   </itemizedlist>
+  </para>
+  <simpara>
+   In your installation, you need to decide whether to install the
+   configuration file at <filename>c:\usr\local\ssl\openssl.cnf</filename> or
+   whether to install it someplace else and use environmental variables
+   (possibly on a per-virtual-host basis) to locate the configuration file.
+   Note that it is possible to override the default path from the script using
+   the <parameter>configargs</parameter> of the functions that require a
+   configuration file.
+  </simpara>
  </note>
 </section>
 

reference/openssl/functions/openssl-csr-new.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.19 -->
   <refentry id="function.openssl-csr-new">
    <refnamediv>
@@ -33,6 +33,7 @@
      <parameter>extraattribs</parameter> are associative arrays whose keys are
      converted to OIDs and applied to the relevant part of the request.
     </para>
+    &reference.openssl.note-openssl-cnf;
     <para>
      By default, the information in your system <literal>openssl.conf</literal>
      is used to initialize the request; you can specify a configuration file
@@ -109,7 +110,8 @@
     </simpara>
     <para>
      <example>
-      <title><function>openssl_csr_new</function> example</title>
+      <title><function>openssl_csr_new</function> example - creating a
+       self-signed-certificate</title>
       <programlisting role="php">
 <![CDATA[
 // Fill in data for the distinguished name to be used in the cert

reference/openssl/functions/openssl-csr-sign.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.19 -->
   <refentry id="function.openssl-csr-sign">
    <refnamediv>
@@ -33,6 +33,43 @@
     <para>
      Returns an x509 certificate resource on success, &false; on failure.
     </para>
+    &reference.openssl.note-openssl-cnf;
+    <para>
+     <example>
+      <title><function>openssl_csr_sign</function> example - signing a
+       CSR (how to implement your own CA)</title>
+      <programlisting role="php">
+<![CDATA[
+// Let's assume that this script is set to receive a CSR that has
+// been pasted into a textarea from another page
+$csrdata = $_POST["CSR"];
+
+// We will sign the request using our own "certificate authority"
+// certificate.  You can use any certificate to sign another, but
+// the process is worthless unless the signing certificate is trusted
+// by the software/users that will deal with the newly signed certificate
+
+// We need our CA cert and it's private key
+$cacert = "file://path/to/ca.crt";
+$privkey = array("file://path/to/ca.key", "your_ca_key_passphrase");
+
+$userscert = openssl_csr_sign($csrdata, $cacert, $privkey, 365);
+
+// Now display the generated certificate so that the user can
+// copy and paste it into their local configuration (such as a file
+// to hold the certificate for their SSL server)
+openssl_x509_export($sscert, $certout) and echo $certout;
+
+// Show any errors that occurred here
+while (($e = openssl_error_string()) !== false) {
+    echo $e . "\n";
+}
+
+]]>
+      </programlisting>
+     </example>
+    </para>
+
    </refsect1>
   </refentry>
 

reference/openssl/functions/openssl-pkey-export-to-file.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.19 -->
   <refentry id="function.openssl-pkey-export-to-file">
    <refnamediv>
@@ -26,6 +26,7 @@
      information about <parameter>configargs</parameter>.
      &return.success;
     </para>
+    &reference.openssl.note-openssl-cnf;
    </refsect1>
   </refentry>
 

reference/openssl/functions/openssl-pkey-export.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.19 -->
   <refentry id="function.openssl-pkey-export">
    <refnamediv>
@@ -26,6 +26,7 @@
      information about <parameter>configargs</parameter>.
      &return.success;
     </para>
+    &reference.openssl.note-openssl-cnf;
    </refsect1>
   </refentry>
 

reference/openssl/functions/openssl-pkey-new.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.19 -->
   <refentry id="function.openssl-pkey-new">
    <refnamediv>
@@ -21,6 +21,7 @@
      <function>openssl_csr_new</function> for more information about
      <parameter>configargs</parameter>.
     </para>
+    &reference.openssl.note-openssl-cnf;
    </refsect1>
   </refentry>
 

reference/openssl/note-openssl-cnf.xml

@@ -0,0 +1,8 @@
+    <note>
+     <simpara>
+      You need to have a valid <filename>openssl.cnf</filename> installed for
+      this function to operate correctly.
+      See the notes under <link linkend="openssl.installation"/> for more
+      information.
+     </simpara>
+    </note>