cvs: phpdoc /en/reference/openssl configure.xml note-openssl-cnf.xml /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

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>