From 717e4a7c30fa7b091fd70b03d1342ca35f0b678b Mon Sep 17 00:00:00 2001
From: Wez Furlong <wez@php.net>
Date: Tue, 10 Dec 2002 19:13:48 +0000
Subject: [PATCH] Some much-needed updates to the docs for openssl.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@107466 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../functions/openssl-csr-export-to-file.xml  |  19 ++-
 .../openssl/functions/openssl-csr-export.xml  |  22 ++-
 .../openssl/functions/openssl-csr-new.xml     | 148 +++++++++++++++++-
 .../openssl/functions/openssl-csr-sign.xml    |  21 ++-
 .../functions/openssl-error-string.xml        |   5 +-
 .../openssl/functions/openssl-free-key.xml    |   3 +-
 .../functions/openssl-get-privatekey.xml      |  14 +-
 .../functions/openssl-get-publickey.xml       |  11 +-
 reference/openssl/functions/openssl-open.xml  |   3 +-
 .../functions/openssl-pkcs7-decrypt.xml       |   5 +-
 .../functions/openssl-pkcs7-encrypt.xml       |   8 +-
 .../openssl/functions/openssl-pkcs7-sign.xml  |   3 +-
 .../functions/openssl-pkcs7-verify.xml        |   3 +-
 .../functions/openssl-pkey-export-to-file.xml |  15 +-
 .../openssl/functions/openssl-pkey-export.xml |  19 ++-
 .../functions/openssl-pkey-get-private.xml    |  60 +++++++
 .../functions/openssl-pkey-get-public.xml     |  55 +++++++
 .../openssl/functions/openssl-pkey-new.xml    |  11 +-
 .../functions/openssl-private-decrypt.xml     |  14 +-
 .../openssl-x509-check-private-key.xml        |   9 +-
 .../functions/openssl-x509-checkpurpose.xml   |   3 +-
 .../functions/openssl-x509-export-to-file.xml |  13 +-
 .../openssl/functions/openssl-x509-export.xml |  15 +-
 .../openssl/functions/openssl-x509-free.xml   |   3 +-
 .../openssl/functions/openssl-x509-parse.xml  |   4 +-
 .../openssl/functions/openssl-x509-read.xml   |   3 +-
 reference/openssl/reference.xml               |   3 +-
 27 files changed, 392 insertions(+), 100 deletions(-)
 create mode 100644 reference/openssl/functions/openssl-pkey-get-private.xml
 create mode 100644 reference/openssl/functions/openssl-pkey-get-public.xml

diff --git a/reference/openssl/functions/openssl-csr-export-to-file.xml b/reference/openssl/functions/openssl-csr-export-to-file.xml
index b8c710cf78..54294c141a 100644
--- a/reference/openssl/functions/openssl-csr-export-to-file.xml
+++ b/reference/openssl/functions/openssl-csr-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-csr-export-to-file">
    <refnamediv>
@@ -14,14 +14,21 @@
       <methodparam><type>string</type><parameter>outfilename</parameter></methodparam>
       <methodparam choice="opt"><type>bool</type><parameter>notext</parameter></methodparam>
      </methodsynopsis>
-     &warn.experimental.func;
     <para>
-     <function>openssl_csr_export_to_file</function> takes the CSR represented by
-     <parameter>csr</parameter> and saves it into the file named by
-     <parameter>outfilename</parameter>.  The optional <parameter>notext</parameter> affects
+     <function>openssl_csr_export_to_file</function> takes the Certificate
+     Signing Request represented by <parameter>csr</parameter> and saves it
+     as ascii-armoured text into the file named by <parameter>outfilename</parameter>.
+     &return.success;
+     The optional <parameter>notext</parameter> affects
      the verbosity of the output; if it is &false; then additional human-readable information is included
-     in the output.
+     in the output.  The default value of <parameter>notext</parameter> is
+     &true;
     </para>
+    <simpara>
+     See also <function>openssl_csr_export</function>,
+     <function>openssl_csr_new</function> and
+     <function>openssl_csr_sign</function>.
+    </simpara>
    </refsect1>
   </refentry>
 
diff --git a/reference/openssl/functions/openssl-csr-export.xml b/reference/openssl/functions/openssl-csr-export.xml
index f97c331f3c..10210e4428 100644
--- a/reference/openssl/functions/openssl-csr-export.xml
+++ b/reference/openssl/functions/openssl-csr-export.xml
@@ -1,23 +1,35 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.19 -->
   <refentry id="function.openssl-csr-export">
    <refnamediv>
     <refname>openssl_csr_export</refname>
-    <refpurpose>Exports a CSR to file or a var </refpurpose>
+    <refpurpose>Exports a CSR as a string</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
      <methodsynopsis>
       <type>bool</type><methodname>openssl_csr_export</methodname>
       <methodparam><type>resource</type><parameter>csr</parameter></methodparam>
-      <methodparam><type>string</type><parameter>out</parameter></methodparam>
+      <methodparam><type>string</type><parameter>&amp;out</parameter></methodparam>
       <methodparam choice="opt"><type>bool</type><parameter>notext</parameter></methodparam>
      </methodsynopsis>
-     &warn.experimental.func;
     <para>
-     &warn.undocumented.func;
+     <function>openssl_csr_export</function> takes the Certificate Signing
+     Request represented by <parameter>csr</parameter> and stores it as
+     ascii-armoured text into <parameter>out</parameter>, which is passed by
+     reference.
+     &return.success;
+     The optional <parameter>notext</parameter> affects
+     the verbosity of the output; if it is &false; then additional human-readable information is included
+     in the output.  The default value of <parameter>notext</parameter> is
+     &true;
     </para>
+    <simpara>
+     See also <function>openssl_csr_export_to_file</function>,
+     <function>openssl_csr_new</function> and
+     <function>openssl_csr_sign</function>.
+    </simpara>
    </refsect1>
   </refentry>
 
diff --git a/reference/openssl/functions/openssl-csr-new.xml b/reference/openssl/functions/openssl-csr-new.xml
index 853c658513..f9724ecbf9 100644
--- a/reference/openssl/functions/openssl-csr-new.xml
+++ b/reference/openssl/functions/openssl-csr-new.xml
@@ -1,10 +1,10 @@
 <?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-csr-new">
    <refnamediv>
     <refname>openssl_csr_new</refname>
-    <refpurpose>Generates a privkey and CSR</refpurpose>
+    <refpurpose>Generates a CSR</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -12,15 +12,155 @@
       <type>bool</type><methodname>openssl_csr_new</methodname>
       <methodparam><type>array</type><parameter>dn</parameter></methodparam>
       <methodparam><type>resource</type><parameter>privkey</parameter></methodparam>
-      <methodparam choice="opt"><type>array</type><parameter>extraattribs</parameter></methodparam>
       <methodparam choice="opt"><type>array</type><parameter>configargs</parameter></methodparam>
+      <methodparam choice="opt"><type>array</type><parameter>extraattribs</parameter></methodparam>
      </methodsynopsis>
-     &warn.experimental.func;
     <para>
      <function>openssl_csr_new</function> generates a new CSR (Certificate Signing Request)
      based on the information provided by <parameter>dn</parameter>, which represents the
      Distinguished Name to be used in the certificate.
     </para>
+    <para>
+     <parameter>privkey</parameter> should be set to a private key that was
+     previously generated by <function>openssl_pkey_new</function> (or
+     otherwise obtained from the other openssl_pkey family of functions).
+     The corresponding public portion of the key will be used to sign the
+     CSR.
+    </para>
+    <para>
+     <parameter>extraattribs</parameter> is used to specify additional
+     configuration options for the CSR.  Both <parameter>dn</parameter> and
+     <parameter>extraattribs</parameter> are associative arrays whose keys are
+     converted to OIDs and applied to the relevant part of the request.
+    </para>
+    <para>
+     By default, the information in your system <literal>openssl.conf</literal>
+     is used to initialize the request; you can specify a configuration file
+     section by setting the <literal>config_section_section</literal> key of
+     <parameter>configargs</parameter>.  You can also specify and alternative
+     openssl configuration file by setting the <literal>config</literal> key
+     to the path of the file you want to use.
+     The following keys, if present in <parameter>configargs</parameter>
+     behave as their equivalents in the <literal>openssl.conf</literal>, as
+     listed in the table below.
+
+     <table>
+      <title>Configuration overrides</title>
+      <tgroup cols="3">
+       <thead>
+        <row>
+         <entry><parameter>configargs</parameter> key</entry>
+         <entry>type</entry>
+         <entry><literal>openssl.conf</literal> equivalent</entry>
+         <entry>description</entry>
+        </row>
+       </thead>
+       <tbody>
+        <row>
+         <entry>digest_alg</entry>
+         <entry><link linkend="language.types.string">string</link></entry>
+         <entry>default_md</entry>
+         <entry>Selects which digest method to use</entry>
+        </row>
+        <row>
+         <entry>x509_extensions</entry>
+         <entry><link linkend="language.types.string">string</link></entry>
+         <entry>x509_extensions</entry>
+         <entry>Selects which extensions should be used when creating an x509
+         certificate</entry>
+        </row>
+        <row>
+         <entry>req_extensions</entry>
+         <entry><link linkend="language.types.string">string</link></entry>
+         <entry>req_extensions</entry>
+         <entry>Selects which extensions should be used when creating a CSR</entry>
+        </row>
+        <row>
+         <entry>private_key_bits</entry>
+         <entry><link linkend="language.types.integer">integer</link></entry>
+         <entry>default_bits</entry>
+         <entry>Specifies how many bits should be used to generate a private
+          key</entry>
+        </row>
+        <row>
+         <entry>private_key_type</entry>
+         <entry><link linkend="language.types.integer">integer</link></entry>
+         <entry>none</entry>
+         <entry>Specifies the type of private key to create.  This can be one
+          of <constant>OPENSSL_KEYTYPE_DSA</constant>,
+          <constant>OPENSSL_KEYTYPE_DH</constant> or
+          <constant>OPENSSL_KEYTYPE_RSA</constant>.
+          The default value is <constant>OPENSSL_KEYTYPE_RSA</constant> which
+          is currently the only supported key type.
+         </entry>
+        </row>
+        <row>
+         <entry>encrypt_key</entry>
+         <entry><link linkend="language.types.boolean">booean</link></entry>
+         <entry>encrypt_key</entry>
+         <entry>Should an exported key (with passphrase) be encrypted?</entry>
+        </row>
+       </tbody>
+      </tgroup>
+     </table>
+    </para>
+    <simpara>
+     &return.success;
+    </simpara>
+    <para>
+     <example>
+      <title><function>openssl_csr_new</function> example</title>
+      <programlisting role="php">
+<![CDATA[
+// Fill in data for the distinguished name to be used in the cert
+// You must change the values of these keys to match your name and
+// company, or more precisely, the name and company of the person/site
+// that you are generating the certificate for.
+// For SSL certificates, the commonName is usually the domain name of
+// that will be using the certificate, but for S/MIME certificates,
+// the commonName will be the name of the individual who will use the
+// certificate.
+$dn = array(
+    "countryName" => "UK",
+    "stateOrProvinceName" => "Somerset",
+    "localityName" => "Glastonbury",
+    "organizationName" => "The Brain Room Limited",
+    "organizationalUnitName" => "PHP Documentation Team",
+    "commonName" => "Wez Furlong",
+    "emailAddress" => "wez@php.net"
+);
+
+// Generate a new private (and public) key pair
+$privkey = openssl_pkey_new();
+
+// Generate a certificate signing request
+$csr = openssl_csr_new($dn, $privkey);
+
+// You will usually want to create a self-signed certificate at this
+// point until your CA fulfills your request.
+// This creates a self-signed cert that is valid for 365 days
+$sscert = openssl_csr_sign($csr, null, $privkey, 365);
+
+// Now you will want to preserve your private key, CSR and self-signed
+// cert so that they can be installed into your web server, mail server
+// or mail client (depending on the intended use of the certificate).
+// This example shows how to get those things into variables, but you
+// can also store them directly into files.
+// Typically, you will send the CSR on to your CA who will then issue
+// you with the "real" certificate.
+openssl_csr_export($csr, $csrout) and debug_zval_dump($csrout);
+openssl_x509_export($sscert, $certout) and debug_zval_dump($certout);
+openssl_pkey_export($privkey, $pkeyout, "mypassword") and debug_zval_dump($pkeyout);
+
+// Show any errors that occurred here
+while (($e = openssl_error_string()) !== false) {
+    echo $e . "\n";
+}
+
+]]>
+      </programlisting>
+     </example>
+    </para>
    </refsect1>
   </refentry>
 
diff --git a/reference/openssl/functions/openssl-csr-sign.xml b/reference/openssl/functions/openssl-csr-sign.xml
index e7c79742bf..6c004153c8 100644
--- a/reference/openssl/functions/openssl-csr-sign.xml
+++ b/reference/openssl/functions/openssl-csr-sign.xml
@@ -1,23 +1,34 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.19 -->
   <refentry id="function.openssl-csr-sign">
    <refnamediv>
     <refname>openssl_csr_sign</refname>
-    <refpurpose>Signs a cert with another CERT </refpurpose>
+    <refpurpose>Sign a CSR with another certificate (or itself) and generate a certificate</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
      <methodsynopsis>
       <type>resource</type><methodname>openssl_csr_sign</methodname>
       <methodparam><type>mixed</type><parameter>csr</parameter></methodparam>
-      <methodparam><type>mixed</type><parameter>x509</parameter></methodparam>
+      <methodparam><type>mixed</type><parameter>cacert</parameter></methodparam>
       <methodparam><type>mixed</type><parameter>priv_key</parameter></methodparam>
       <methodparam><type>long</type><parameter>days</parameter></methodparam>
      </methodsynopsis>
-     &warn.experimental.func;
     <para>
-     &warn.undocumented.func;
+     <function>openssl_csr_sign</function> generates an x509 certificate
+     resource from the <parameter>csr</parameter> previously generated by
+     <function>openssl_csr_new</function>.
+     The generated certificate will be signed by
+     <parameter>cacert</parameter>.  If <parameter>cacert</parameter> is &null;,
+     the generated certificate will be a self-signed certificate.
+     <parameter>priv_key</parameter> is the private key that corresponds to
+     <parameter>cacert</parameter>.
+     <parameter>days</parameter> specifies the length of time for which the
+     generated certificate will be valid, in days.
+    </para>
+    <para>
+     Returns an x509 certificate resource on success, &false; on failure.
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/openssl/functions/openssl-error-string.xml b/reference/openssl/functions/openssl-error-string.xml
index 5a2de30759..ebd0781ff9 100644
--- a/reference/openssl/functions/openssl-error-string.xml
+++ b/reference/openssl/functions/openssl-error-string.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.4 -->
   <refentry id="function.openssl-error-string">
    <refnamediv>
@@ -12,7 +12,6 @@
       <type>mixed</type><methodname>openssl_error_string</methodname>
       <void/>
      </methodsynopsis>
-	&warn.experimental.func;
     <para>
      Returns an error message string, or &false; if there are no more error
      messages to return.
@@ -22,8 +21,6 @@
      openSSL library.  Error messages are stacked, so this function should be
      called multiple times to collect all of the information.
     </para>
-    <para><emphasis>The parameters/return type of this function may change before
-     it appears in a release version of PHP</emphasis></para>
     <para>
      <example>
       <title><function>openssl_error_string</function> example</title>
diff --git a/reference/openssl/functions/openssl-free-key.xml b/reference/openssl/functions/openssl-free-key.xml
index 2808171366..555f316d35 100644
--- a/reference/openssl/functions/openssl-free-key.xml
+++ b/reference/openssl/functions/openssl-free-key.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.1 -->
   <refentry id="function.openssl-free-key">
    <refnamediv>
@@ -12,7 +12,6 @@
       <type>void</type><methodname>openssl_free_key</methodname>
       <methodparam><type>resource</type><parameter>key_identifier</parameter></methodparam>
      </methodsynopsis>
-	&warn.experimental.func;
     <para>
      <function>openssl_free_key</function> frees the key associated with
      the specified <parameter>key_identifier</parameter> from memory.
diff --git a/reference/openssl/functions/openssl-get-privatekey.xml b/reference/openssl/functions/openssl-get-privatekey.xml
index 4bb724c677..d1ad1b83ff 100644
--- a/reference/openssl/functions/openssl-get-privatekey.xml
+++ b/reference/openssl/functions/openssl-get-privatekey.xml
@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.1 -->
   <refentry id="function.openssl-get-privatekey">
    <refnamediv>
     <refname>openssl_get_privatekey</refname>
-    <refpurpose>Prepare a PEM formatted private key for use</refpurpose>
+    <refpurpose>Get a private key</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -13,16 +13,8 @@
       <methodparam><type>mixed</type><parameter>key</parameter></methodparam>
       <methodparam choice="opt"><type>string</type><parameter>passphrase</parameter></methodparam>
      </methodsynopsis>
-	&warn.experimental.func;
     <para>
-     Returns a positive key resource identifier on success, or &false; on error.
-    </para>
-    <para>
-     <function>openssl_get_privatekey</function> parses the PEM
-     formatted private key specified by <parameter>key</parameter>
-     and prepares it for use by other functions.
-     The optional parameter <parameter>passphrase</parameter> must be used if
-     the specified key is encrypted (protected by a passphrase).
+     This is an alias for <function>openssl_pkey_get_private</function>.
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/openssl/functions/openssl-get-publickey.xml b/reference/openssl/functions/openssl-get-publickey.xml
index bd322f1c01..d6ab1564e6 100644
--- a/reference/openssl/functions/openssl-get-publickey.xml
+++ b/reference/openssl/functions/openssl-get-publickey.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.1 -->
   <refentry id="function.openssl-get-publickey">
    <refnamediv>
@@ -12,15 +12,8 @@
       <type>resource</type><methodname>openssl_get_publickey</methodname>
       <methodparam><type>mixed</type><parameter>certificate</parameter></methodparam>
      </methodsynopsis>
-	&warn.experimental.func;
     <para>
-     Returns a positive key resource identifier on success, or &false; on error.
-    </para>
-    <para>
-     <function>openssl_get_publickey</function> extracts the
-     public key from an X.509 certificate specified by
-     <parameter>certificate</parameter> and prepares it for use by other
-     functions.
+     This is an alias for <function>openssl_pkey_get_public</function>.
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/openssl/functions/openssl-open.xml b/reference/openssl/functions/openssl-open.xml
index 8fc73dec5a..93c6b1f18b 100644
--- a/reference/openssl/functions/openssl-open.xml
+++ b/reference/openssl/functions/openssl-open.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.1 -->
   <refentry id="function.openssl-open">
    <refnamediv>
@@ -15,7 +15,6 @@
       <methodparam><type>string</type><parameter>env_key</parameter></methodparam>
       <methodparam><type>mixed</type><parameter>priv_key_id</parameter></methodparam>
      </methodsynopsis>
-	&warn.experimental.func;
     <para>
      &return.success; If successful the opened
      data is returned in <parameter>open_data</parameter>.
diff --git a/reference/openssl/functions/openssl-pkcs7-decrypt.xml b/reference/openssl/functions/openssl-pkcs7-decrypt.xml
index ba7f88c542..f9f4535735 100644
--- a/reference/openssl/functions/openssl-pkcs7-decrypt.xml
+++ b/reference/openssl/functions/openssl-pkcs7-decrypt.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.4 -->
   <refentry id="function.openssl-pkcs7-decrypt">
    <refnamediv>
@@ -13,9 +13,8 @@
       <methodparam><type>string</type><parameter>infilename</parameter></methodparam>
       <methodparam><type>string</type><parameter>outfilename</parameter></methodparam>
       <methodparam><type>mixed</type><parameter>recipcert</parameter></methodparam>
-      <methodparam><type>mixed</type><parameter>recipkey</parameter></methodparam>
+      <methodparam choice="opt"><type>mixed</type><parameter>recipkey</parameter></methodparam>
      </methodsynopsis>
-	&warn.experimental.func;
     <para>
      Decrypts the S/MIME encrypted message contained in the file specified by
      <parameter>infilename</parameter> using the certificate and it's
diff --git a/reference/openssl/functions/openssl-pkcs7-encrypt.xml b/reference/openssl/functions/openssl-pkcs7-encrypt.xml
index 800a45f159..86d2f005bc 100644
--- a/reference/openssl/functions/openssl-pkcs7-encrypt.xml
+++ b/reference/openssl/functions/openssl-pkcs7-encrypt.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.4 -->
   <refentry id="function.openssl-pkcs7-encrypt">
    <refnamediv>
@@ -16,7 +16,6 @@
       <methodparam><type>array</type><parameter>headers</parameter></methodparam>
       <methodparam choice="opt"><type>long</type><parameter>flags</parameter></methodparam>
      </methodsynopsis>
-	&warn.experimental.func;
     <para>
      <function>openssl_pkcs7_encrypt</function> takes the contents of the
      file named <parameter>infile</parameter> and encrypts them using an RC2
@@ -52,7 +51,7 @@ HQ
 EOD;
 
 // load key
-$key = implode("", file("nighthawk.pem"));
+$key = file_get_contents("nighthawk.pem");
 
 // save message to file
 $fp = fopen("msg.txt", "w");
@@ -61,8 +60,7 @@ fclose($fp);
 
 // encrypt it
 if (openssl_pkcs7_encrypt("msg.txt", "enc.txt", $key,
-    array("To" => "nighthawk@example.com", // keyed
-syntax
+    array("To" => "nighthawk@example.com", // keyed syntax
           "From: HQ <hq@example.com>", // indexed syntax
           "Subject" => "Eyes only")))
 {
diff --git a/reference/openssl/functions/openssl-pkcs7-sign.xml b/reference/openssl/functions/openssl-pkcs7-sign.xml
index 7dedf62c22..c4b7e4a794 100644
--- a/reference/openssl/functions/openssl-pkcs7-sign.xml
+++ b/reference/openssl/functions/openssl-pkcs7-sign.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.4 -->
  <refentry id="function.openssl-pkcs7-sign">
   <refnamediv>
@@ -18,7 +18,6 @@
      <methodparam choice="opt"><type>long</type><parameter>flags</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>extracertsfilename</parameter></methodparam>
     </methodsynopsis>
-	&warn.experimental.func;
    <para>
     <function>openssl_pkcs7_sign</function> takes the contents of the file
     named <parameter>infilename</parameter> and signs them using the
diff --git a/reference/openssl/functions/openssl-pkcs7-verify.xml b/reference/openssl/functions/openssl-pkcs7-verify.xml
index 13a0dd655c..b04bf2b281 100644
--- a/reference/openssl/functions/openssl-pkcs7-verify.xml
+++ b/reference/openssl/functions/openssl-pkcs7-verify.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.4 -->
  <refentry id="function.openssl-pkcs7-verify">
   <refnamediv>
@@ -16,7 +16,6 @@
      <methodparam choice="opt"><type>array</type><parameter>cainfo</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>extracerts</parameter></methodparam>
     </methodsynopsis>
-	&warn.experimental.func;
    <para>
     <function>openssl_pkcs7_verify</function> reads the S/MIME message
     contained in the filename specified by <parameter>filename</parameter> and
diff --git a/reference/openssl/functions/openssl-pkey-export-to-file.xml b/reference/openssl/functions/openssl-pkey-export-to-file.xml
index 928f88f058..6e1b8213eb 100644
--- a/reference/openssl/functions/openssl-pkey-export-to-file.xml
+++ b/reference/openssl/functions/openssl-pkey-export-to-file.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.19 -->
   <refentry id="function.openssl-pkey-export-to-file">
    <refnamediv>
@@ -13,11 +13,18 @@
       <methodparam><type>mixed</type><parameter>key</parameter></methodparam>
       <methodparam><type>string</type><parameter>outfilename</parameter></methodparam>
       <methodparam choice="opt"><type>string</type><parameter>passphrase</parameter></methodparam>
-      <methodparam choice="opt"><type>array</type><parameter>config_args</parameter></methodparam>
+      <methodparam choice="opt"><type>array</type><parameter>configargs</parameter></methodparam>
      </methodsynopsis>
-     &warn.experimental.func;
     <para>
-     &warn.undocumented.func;
+     <function>openssl_pkey_export_to_file</function> saves an ascii-armoured
+     (PEM encoded) rendition of <parameter>key</parameter> into the file named
+     by <parameter>outfilename</parameter>.  The key can be optionally
+     protected by a <parameter>passphrase</parameter>.
+     <parameter>configargs</parameter> can be used to fine-tune the export
+     process by specifying and/or overriding options for the openssl
+     configuration file.  See <function>openssl_csr_new</function> for more
+     information about <parameter>configargs</parameter>.
+     &return.success;
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/openssl/functions/openssl-pkey-export.xml b/reference/openssl/functions/openssl-pkey-export.xml
index 887064df2c..f6b332759b 100644
--- a/reference/openssl/functions/openssl-pkey-export.xml
+++ b/reference/openssl/functions/openssl-pkey-export.xml
@@ -1,23 +1,30 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.19 -->
   <refentry id="function.openssl-pkey-export">
    <refnamediv>
     <refname>openssl_pkey_export</refname>
-    <refpurpose>Gets an exportable representation of a key into a string or file </refpurpose>
+    <refpurpose>Gets an exportable representation of a key into a string</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
      <methodsynopsis>
       <type>bool</type><methodname>openssl_pkey_export</methodname>
       <methodparam><type>mixed</type><parameter>key</parameter></methodparam>
-      <methodparam><type>mixed</type><parameter>out</parameter></methodparam>
+      <methodparam><type>string</type><parameter>&amp;out</parameter></methodparam>
       <methodparam choice="opt"><type>string</type><parameter>passphrase</parameter></methodparam>
-      <methodparam choice="opt"><type>array</type><parameter>config_args</parameter></methodparam>
+      <methodparam choice="opt"><type>array</type><parameter>configargs</parameter></methodparam>
      </methodsynopsis>
-     &warn.experimental.func;
     <para>
-     &warn.undocumented.func;
+     <function>openssl_pkey_export</function> exports
+     <parameter>key</parameter> as a PEM encoded string and stores it into
+     <parameter>out</parameter> (which is passed by reference).
+     The key is optionally protected by <parameter>passphrase</parameter>.
+     <parameter>configargs</parameter> can be used to fine-tune the export
+     process by specifying and/or overriding options for the openssl
+     configuration file.  See <function>openssl_csr_new</function> for more
+     information about <parameter>configargs</parameter>.
+     &return.success;
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/openssl/functions/openssl-pkey-get-private.xml b/reference/openssl/functions/openssl-pkey-get-private.xml
new file mode 100644
index 0000000000..d67ab106d4
--- /dev/null
+++ b/reference/openssl/functions/openssl-pkey-get-private.xml
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: 1.1 $ -->
+<!-- splitted from ./en/functions/openssl.xml, last change in rev 1.1 -->
+  <refentry id="function.openssl-pkey-get-private">
+   <refnamediv>
+    <refname>openssl_pkey_get_private</refname>
+    <refpurpose>Get a private key</refpurpose>
+   </refnamediv>
+   <refsect1>
+    <title>Description</title>
+     <methodsynopsis>
+      <type>resource</type><methodname>openssl_get_privatekey</methodname>
+      <methodparam><type>mixed</type><parameter>key</parameter></methodparam>
+      <methodparam choice="opt"><type>string</type><parameter>passphrase</parameter></methodparam>
+     </methodsynopsis>
+    <para>
+     Returns a positive key resource identifier on success, or &false; on error.
+    </para>
+    <para>
+     <function>openssl_get_privatekey</function> parses 
+     <parameter>key</parameter> and prepares it for use by other functions.
+
+     <parameter>key</parameter> can be one of the following:
+     <orderedlist>
+      <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).
+       </simpara>
+      </listitem>
+      <listitem><simpara>A PEM formatted private key.</simpara></listitem>
+     </orderedlist>
+     
+    </para>
+    <para>
+     The optional parameter <parameter>passphrase</parameter> must be used if
+     the specified key is encrypted (protected by a passphrase).
+    </para>
+   </refsect1>
+  </refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"../../../../manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/openssl/functions/openssl-pkey-get-public.xml b/reference/openssl/functions/openssl-pkey-get-public.xml
new file mode 100644
index 0000000000..c100d65e6f
--- /dev/null
+++ b/reference/openssl/functions/openssl-pkey-get-public.xml
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: 1.1 $ -->
+<!-- splitted from ./en/functions/openssl.xml, last change in rev 1.1 -->
+  <refentry id="function.openssl-pkey-get-public">
+   <refnamediv>
+    <refname>openssl_pkey_get_public</refname> 
+    <refpurpose>Extract public key from certificate and prepare it for use</refpurpose>
+   </refnamediv>
+   <refsect1>
+    <title>Description</title>
+     <methodsynopsis>
+      <type>resource</type><methodname>openssl_pkey_get_public</methodname>
+      <methodparam><type>mixed</type><parameter>certificate</parameter></methodparam>
+     </methodsynopsis>
+    <para>
+     Returns a positive key resource identifier on success, or &false; on error.
+    </para>
+    <para>
+     <function>openssl_get_publickey</function> extracts the
+     public key from <parameter>certificate</parameter> and
+     prepares it for use by other functions.
+     <parameter>certificate</parameter> can be one of the following:
+     <orderedlist>
+      <listitem>an X.509 certificate resource</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).
+       </simpara>
+      </listitem>
+      <listitem><simpara>A PEM formatted private key.</simpara></listitem>
+     </orderedlist>
+    </para>
+   </refsect1>
+  </refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"../../../../manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/openssl/functions/openssl-pkey-new.xml b/reference/openssl/functions/openssl-pkey-new.xml
index a40cffb67a..8073667c02 100644
--- a/reference/openssl/functions/openssl-pkey-new.xml
+++ b/reference/openssl/functions/openssl-pkey-new.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.19 -->
   <refentry id="function.openssl-pkey-new">
    <refnamediv>
@@ -12,9 +12,14 @@
       <type>resource</type><methodname>openssl_pkey_new</methodname>
       <methodparam choice="opt"><type>array</type><parameter>configargs</parameter></methodparam>
      </methodsynopsis>
-     &warn.experimental.func;
     <para>
-     &warn.undocumented.func;
+     <function>openssl_pkey_new</function> generates a new private and public
+     key pair.  The public component of the key can be obtained using
+     <function>openssl_pkey_get_public</function>.
+     You can finetune the key generation (such as specifying the number of
+     bits) using <parameter>configargs</parameter>.  See
+     <function>openssl_csr_new</function> for more information about
+     <parameter>configargs</parameter>.
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/openssl/functions/openssl-private-decrypt.xml b/reference/openssl/functions/openssl-private-decrypt.xml
index 1bf1684d00..fcdb7d5da4 100644
--- a/reference/openssl/functions/openssl-private-decrypt.xml
+++ b/reference/openssl/functions/openssl-private-decrypt.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.19 -->
   <refentry id="function.openssl-private-decrypt">
    <refnamediv>
@@ -11,13 +11,19 @@
      <methodsynopsis>
       <type>bool</type><methodname>openssl_private_decrypt</methodname>
       <methodparam><type>string</type><parameter>data</parameter></methodparam>
-      <methodparam><type>string</type><parameter>crypted</parameter></methodparam>
+      <methodparam><type>string</type><parameter>&amp;decrypted</parameter></methodparam>
       <methodparam><type>mixed</type><parameter>key</parameter></methodparam>
       <methodparam choice="opt"><type>int</type><parameter>padding</parameter></methodparam>
      </methodsynopsis>
-     &warn.experimental.func;
     <para>
-     &warn.undocumented.func;
+     <function>openssl_private_decrypt</function> decrypts
+     <parameter>data</parameter> that was previous encrypted via
+     <function>openssl_private_encrypt</function> and stores the result into
+     <parameter>decrypted</parameter>.  <parameter>key</parameter> must be the
+     private key corresponding that was used to encrypt the
+     data.  <parameter>padding</parameter> defaults to OPENSSL_PKCS1_PADDING,
+     but can also be one of OPENSSL_SSLV23_PADDING, OPENSSL_PKCS1_OAEP_PADDING
+     OPENSSL_NO_PADDING.
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/openssl/functions/openssl-x509-check-private-key.xml b/reference/openssl/functions/openssl-x509-check-private-key.xml
index 2679242deb..5acd6edfc6 100644
--- a/reference/openssl/functions/openssl-x509-check-private-key.xml
+++ b/reference/openssl/functions/openssl-x509-check-private-key.xml
@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.19 -->
   <refentry id="function.openssl-x509-check-private-key">
    <refnamediv>
     <refname>openssl_x509_check_private_key</refname>
-    <refpurpose>Checks if a private key corresponds to a CERT </refpurpose>
+    <refpurpose>Checks if a private key corresponds to a certificate</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -13,9 +13,10 @@
       <methodparam><type>mixed</type><parameter>cert</parameter></methodparam>
       <methodparam><type>mixed</type><parameter>key</parameter></methodparam>
      </methodsynopsis>
-     &warn.experimental.func;
     <para>
-     &warn.undocumented.func;
+     <function>openssl_x509_check_private_key</function> returns &true; if
+     <parameter>key</parameter> is the private key that corresponds to
+     <parameter>cert</parameter>, or &false; otherwise.
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/openssl/functions/openssl-x509-checkpurpose.xml b/reference/openssl/functions/openssl-x509-checkpurpose.xml
index 609184a973..dd8379baea 100644
--- a/reference/openssl/functions/openssl-x509-checkpurpose.xml
+++ b/reference/openssl/functions/openssl-x509-checkpurpose.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.4 -->
  <refentry id="function.openssl-x509-checkpurpose">
   <refnamediv>
@@ -16,7 +16,6 @@
      <methodparam><type>array</type><parameter>cainfo</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>untrustedfile</parameter></methodparam>
     </methodsynopsis>
-	&warn.experimental.func;
    <para>
     Returns &true; if the certificate can be used for the intended purpose,
     &false; if it cannot, or -1 on error.
diff --git a/reference/openssl/functions/openssl-x509-export-to-file.xml b/reference/openssl/functions/openssl-x509-export-to-file.xml
index 4d5ef68ee7..b78ec0924e 100644
--- a/reference/openssl/functions/openssl-x509-export-to-file.xml
+++ b/reference/openssl/functions/openssl-x509-export-to-file.xml
@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.19 -->
   <refentry id="function.openssl-x509-export-to-file">
    <refnamediv>
     <refname>openssl_x509_export_to_file</refname>
-    <refpurpose>Exports a CERT to file or a var </refpurpose>
+    <refpurpose>Exports a certificate to file</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -14,9 +14,14 @@
       <methodparam><type>string</type><parameter>outfilename</parameter></methodparam>
       <methodparam choice="opt"><type>bool</type><parameter>notext</parameter></methodparam>
      </methodsynopsis>
-     &warn.experimental.func;
     <para>
-     &warn.undocumented.func;
+     <function>openssl_x509_export_to_file</function> stores
+     <parameter>x509</parameter> into a file named by
+     <parameter>outfilename</parameter> in a PEM encoded format.
+     The optional parameter <parameter>notext</parameter> default to &true;.
+     If set to &false;, additional human readable text will also be stored
+     into the output file.
+     &return.success;
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/openssl/functions/openssl-x509-export.xml b/reference/openssl/functions/openssl-x509-export.xml
index 28b198d0ba..dfd132f550 100644
--- a/reference/openssl/functions/openssl-x509-export.xml
+++ b/reference/openssl/functions/openssl-x509-export.xml
@@ -1,22 +1,27 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.19 -->
   <refentry id="function.openssl-x509-export">
    <refnamediv>
     <refname>openssl_x509_export</refname>
-    <refpurpose>Exports a CERT to file or a var </refpurpose>
+    <refpurpose>Exports a certificate as a string</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
      <methodsynopsis>
       <type>bool</type><methodname>openssl_x509_export</methodname>
       <methodparam><type>mixed</type><parameter>x509</parameter></methodparam>
-      <methodparam><type>string</type><parameter>outfilename</parameter></methodparam>
+      <methodparam><type>string</type><parameter>&amp;output</parameter></methodparam>
       <methodparam choice="opt"><type>bool</type><parameter>notext</parameter></methodparam>
      </methodsynopsis>
-     &warn.experimental.func;
     <para>
-     &warn.undocumented.func;
+     <function>openssl_x509_export</function> stores
+     <parameter>x509</parameter> into a file named by
+     <parameter>outfilename</parameter> in a PEM encoded format.
+     The optional parameter <parameter>notext</parameter> default to &true;.
+     If set to &false;, additional human readable text will also be stored
+     into <parameter>output</parameter>.
+     &return.success;
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/openssl/functions/openssl-x509-free.xml b/reference/openssl/functions/openssl-x509-free.xml
index 51a9606206..114206640a 100644
--- a/reference/openssl/functions/openssl-x509-free.xml
+++ b/reference/openssl/functions/openssl-x509-free.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.4 -->
  <refentry id="function.openssl-x509-free">
   <refnamediv>
@@ -12,7 +12,6 @@
      <type>void</type><methodname>openssl_x509_free</methodname>
      <methodparam><type>resource</type><parameter>x509cert</parameter></methodparam>
     </methodsynopsis>
-	&warn.experimental.func;
    <para>
     <function>openssl_x509_free</function> frees the certificate associated
     with the specified <parameter>x509cert</parameter> resource from memory.
diff --git a/reference/openssl/functions/openssl-x509-parse.xml b/reference/openssl/functions/openssl-x509-parse.xml
index 3d9e63ba13..74b56fd496 100644
--- a/reference/openssl/functions/openssl-x509-parse.xml
+++ b/reference/openssl/functions/openssl-x509-parse.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.4 -->
  <refentry id="function.openssl-x509-parse">
   <refnamediv>
@@ -14,7 +14,7 @@
      <methodparam><type>mixed</type><parameter>x509cert</parameter></methodparam>
      <methodparam choice="opt"><type>bool</type><parameter>shortnames</parameter></methodparam>
     </methodsynopsis>
-	&warn.experimental.func;
+    &warn.experimental.func;
    <para>
     <function>openssl_x509_parse</function> returns information about the
     supplied <parameter>x509cert</parameter>, including fields such as subject
diff --git a/reference/openssl/functions/openssl-x509-read.xml b/reference/openssl/functions/openssl-x509-read.xml
index e58eac39f6..f24acbdfec 100644
--- a/reference/openssl/functions/openssl-x509-read.xml
+++ b/reference/openssl/functions/openssl-x509-read.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/openssl.xml, last change in rev 1.4 -->
  <refentry id="function.openssl-x509-read">
   <refnamediv>
@@ -13,7 +13,6 @@
      <type>resource</type><methodname>openssl_x509_read</methodname>
      <methodparam><type>mixed</type><parameter>x509certdata</parameter></methodparam>
     </methodsynopsis>
-	&warn.experimental.func;
    <para>
     <function>openssl_x509_read</function> parses the certificate supplied by
     <parameter>x509certdata</parameter> and returns a resource identifier for
diff --git a/reference/openssl/reference.xml b/reference/openssl/reference.xml
index 4f70974c19..1a1115ebf9 100644
--- a/reference/openssl/reference.xml
+++ b/reference/openssl/reference.xml
@@ -1,10 +1,9 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
  <reference id="ref.openssl">
   <title>OpenSSL functions</title>
   <titleabbrev>OpenSSL</titleabbrev>
   <partintro>
-  &warn.experimental;
    <section id="openssl.intro">
    &reftitle.intro;
     <para>