From 1219ed7946c32ddcf8d06e002c004c9ab4440cd2 Mon Sep 17 00:00:00 2001
From: Hannes Magnusson <bjori@php.net>
Date: Mon, 21 Apr 2014 23:23:50 +0000
Subject: [PATCH] Document how to connect to MongoDB over SSL using stream
 context option for verifications and authentication Fixes
 https://jira.mongodb.org/browse/PHP-935

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@333392 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/mongo/connecting.xml            | 134 ++++++++++++++++++++++
 reference/mongo/mongoclient/construct.xml |  39 +------
 2 files changed, 140 insertions(+), 33 deletions(-)

diff --git a/reference/mongo/connecting.xml b/reference/mongo/connecting.xml
index ef1c366c25..d1e3be7172 100644
--- a/reference/mongo/connecting.xml
+++ b/reference/mongo/connecting.xml
@@ -12,6 +12,140 @@
   cases.
  </para>
 
+ <section xml:id="mongo.connecting.ssl">
+  <title>Connecting over SSL</title>
+  <para>
+   The driver supports connecting to <link xlink:href="&url.mongodb.docs.configure-ssl;">MongoDB over SSL</link>
+   and can optionally use <link linkend="context.ssl">SSL Stream Context</link> options to provide more details,
+   such as verifying certificates against specific certificate chain, or authenticate to
+   <link xlink:href="&url.mongodb.docs.configure-x509;">MongoDB using X509 certificates</link>.
+  </para>
+
+  <example xml:id="mongo.connecting.context.ssl">
+   <title>Connect to MongoDB Instance with SSL Encryption</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$mc = new MongoClient("mongodb://server1", array("ssl" => true));
+?>
+]]>
+   </programlisting>
+  </example>
+
+  <example xml:id="mongo.connecting.context.ssl.verify">
+   <title>Connect to MongoDB Instance with SSL Encryption, verifying it is who we think it is</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$ctx = stream_context_create(array(
+    "ssl" => array(
+        /* Optionally verify the server is who he says he is, and has been certified by CA we trust */
+        "verify_peer"       => true,
+        "allow_self_signed" => false,
+        "cafile"            => "/vagrant/certs/ca.pem",
+    ),
+));
+
+$mc = new MongoClient(
+    "mongodb://server1", 
+    array("ssl" => true), 
+    array("context" => $ctx)
+);
+?>
+]]>
+   </programlisting>
+  </example>
+
+
+  <example xml:id="mongo.connecting.context.ssl.certificate">
+   <title>Connect to MongoDB Instance that Requires Client Certificates</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$ctx = stream_context_create(array(
+    "ssl" => array(
+        "local_cert" => "/vagrant/certs/client.pem",
+        /* If the certificate we are providing was passphrase encoded, we need to set it here */
+        "passphrase" => "My Passphrase for the local_cert",
+
+        /* Optionally verify the server is who he says he is */
+        "verify_peer" => true,
+        "cafile"      => "/vagrant/certs/ca.pem",
+    ),
+));
+
+$mc = new MongoClient(
+    "mongodb://server1/?ssl=true", 
+    array(), 
+    array("context" => $ctx)
+);
+?>
+]]>
+   </programlisting>
+  </example>
+
+  <example xml:id="mongo.connecting.authenticate.ssl.x509">
+   <title>Authenticating with X.509 certificates</title>
+   <para>
+    The username is the <literal>certificate subject</literal> from the X509, which can be extracted like this:
+   </para>
+   <programlisting role="shell">
+<![CDATA[
+openssl x509 -in /vagrant/certs/ca-signed-client.pem -inform PEM -subject -nameopt RFC2253
+]]>
+   </programlisting>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$ctx = stream_context_create( array(
+    "ssl" => array(
+        "local_cert" => "/vagrant/certs/ca-signed-client.pem",
+    )
+) );
+
+$mc = new MongoClient(
+    'mongodb://username@server1/?authSource=$external&authMechanism=MONGODB-X509&ssl=true', 
+    array(), 
+    array("context" => $ctx)
+);
+?>
+]]>
+   </programlisting>
+   <para>
+    Where <literal>username</literal> is the certificate subject.
+   </para>
+  </example>
+
+  <simplesect role="changelog">
+   &reftitle.changelog;
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>1.5.0</entry>
+       <entry>
+        Added support for X509 authentication.
+       </entry>
+      </row>
+      <row>
+       <entry>1.4.0</entry>
+       <entry>
+        Added support for connecting to SSL enabled MongoDB.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </simplesect>
+
+ </section>
+
  <section xml:id="mongo.connecting.auth">
   <title>Authentication</title>
   <para>
diff --git a/reference/mongo/mongoclient/construct.xml b/reference/mongo/mongoclient/construct.xml
index 1904696231..c1676a72ef 100644
--- a/reference/mongo/mongoclient/construct.xml
+++ b/reference/mongo/mongoclient/construct.xml
@@ -410,18 +410,18 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db
      <listitem>
       <para>
        An array of options for the MongoDB driver. Options include setting
-       connection context options for SSL or logging callbacks.
+       connection <link linkend="mongo.connecting.context.ssl">context options for SSL</link>
+       or logging callbacks.
        <itemizedlist>
         <listitem>
          <para>
           <literal>"context"</literal>
          </para>
          <para>
-          A way to pass in context options. Context options allow you to
-          configure SSL certificates and are described at <link
-          linkend="context.ssl">SSL context options</link>. There is an <link
-          linkend="mongoclient.construct.context.ssl">example</link> further
-          down that shows you how to use this.
+          The Stream Context to attach to all new connections. This allows you 
+          for example to configure SSL certificates and are described at
+          <link linkend="context.ssl">SSL context options</link>. See the 
+          <link linkend="mongo.connecting.context.ssl">Connecting over SSL</link> tutorial.
          </para>
         </listitem>
        </itemizedlist>
@@ -623,33 +623,6 @@ $uri .= '?readPreference=nearest';
 $uri .= '&readPreferenceTags=dc:east';
 $m = new MongoClient($uri, array('replicaSet' => 'rs'));
 ?>
-]]>
-   </programlisting>
-   <para>
-    See the <link linkend="mongo.readpreferences">read preferences</link>
-    section of this manual for further information.
-   </para>
-  </example>
-
-  <example xml:id="mongoclient.construct.context.ssl">
-   <title><function>MongoClient::__construct</function> connecting with SSL
-   certifications example</title>
-   <programlisting role="php">
-<![CDATA[
-<?php
-$ctx = stream_context_create( array(
-    'ssl' => array(
-        'local_cert' => '/vagrant/certs/client.pem',
-        'cafile' => '/vagrant/certs/ca.pem',
-    )
-) );
-
-$m = new MongoClient(
-    "mongodb://mongod/?ssl=true", 
-    array(), 
-    array('context' => $ctx)
-);
-?>
 ]]>
    </programlisting>
    <para>