wez Wed Dec 11 10:50:47 2002 EDT
Added files:
/phpdoc/en/reference/openssl note-openssl-cnf.xml
Modified files:
/phpdoc/en/reference/openssl configure.xml
/phpdoc/en/reference/openssl/functions openssl-csr-new.xml
openssl-csr-sign.xml
openssl-pkey-export-to-file.xml
openssl-pkey-export.xml
openssl-pkey-new.xml
Log:
Document openssl.cnf related issues, and add an example of how to act as a
certificate authority using PHP.
Index: phpdoc/en/reference/openssl/configure.xml
diff -u phpdoc/en/reference/openssl/configure.xml:1.1
phpdoc/en/reference/openssl/configure.xml:1.2
--- phpdoc/en/reference/openssl/configure.xml:1.1 Sun Dec 1 12:10:14 2002
+++ phpdoc/en/reference/openssl/configure.xml Wed Dec 11 10:50:47 2002
@@ -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>
@@ -13,6 +13,50 @@
<emphasis>libeay32.dll</emphasis> from the DLL folder of the PHP/Win32 binary
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>
Index: phpdoc/en/reference/openssl/functions/openssl-csr-new.xml
diff -u phpdoc/en/reference/openssl/functions/openssl-csr-new.xml:1.4
phpdoc/en/reference/openssl/functions/openssl-csr-new.xml:1.5
--- phpdoc/en/reference/openssl/functions/openssl-csr-new.xml:1.4 Tue Dec 10
14:13:48 2002
+++ phpdoc/en/reference/openssl/functions/openssl-csr-new.xml Wed Dec 11 10:50:47
+2002
@@ -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
Index: phpdoc/en/reference/openssl/functions/openssl-csr-sign.xml
diff -u phpdoc/en/reference/openssl/functions/openssl-csr-sign.xml:1.4
phpdoc/en/reference/openssl/functions/openssl-csr-sign.xml:1.5
--- phpdoc/en/reference/openssl/functions/openssl-csr-sign.xml:1.4 Tue Dec 10
14:54:46 2002
+++ phpdoc/en/reference/openssl/functions/openssl-csr-sign.xml Wed Dec 11 10:50:47
+2002
@@ -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>
Index: phpdoc/en/reference/openssl/functions/openssl-pkey-export-to-file.xml
diff -u phpdoc/en/reference/openssl/functions/openssl-pkey-export-to-file.xml:1.3
phpdoc/en/reference/openssl/functions/openssl-pkey-export-to-file.xml:1.4
--- phpdoc/en/reference/openssl/functions/openssl-pkey-export-to-file.xml:1.3 Tue
Dec 10 14:13:48 2002
+++ phpdoc/en/reference/openssl/functions/openssl-pkey-export-to-file.xml Wed
+Dec 11 10:50:47 2002
@@ -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>
Index: phpdoc/en/reference/openssl/functions/openssl-pkey-export.xml
diff -u phpdoc/en/reference/openssl/functions/openssl-pkey-export.xml:1.3
phpdoc/en/reference/openssl/functions/openssl-pkey-export.xml:1.4
--- phpdoc/en/reference/openssl/functions/openssl-pkey-export.xml:1.3 Tue Dec 10
14:13:48 2002
+++ phpdoc/en/reference/openssl/functions/openssl-pkey-export.xml Wed Dec 11
+10:50:47 2002
@@ -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>
Index: phpdoc/en/reference/openssl/functions/openssl-pkey-new.xml
diff -u phpdoc/en/reference/openssl/functions/openssl-pkey-new.xml:1.3
phpdoc/en/reference/openssl/functions/openssl-pkey-new.xml:1.4
--- phpdoc/en/reference/openssl/functions/openssl-pkey-new.xml:1.3 Tue Dec 10
14:13:48 2002
+++ phpdoc/en/reference/openssl/functions/openssl-pkey-new.xml Wed Dec 11 10:50:47
+2002
@@ -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>
Index: phpdoc/en/reference/openssl/note-openssl-cnf.xml
+++ phpdoc/en/reference/openssl/note-openssl-cnf.xml
<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>
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
