From 4e0ca4601de48412b93cad230957ee4b5a94c3ba Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michal=20=C4=8Ciha=C5=99?= <michal@cihar.com>
Date: Mon, 18 Apr 2016 16:28:03 +0200
Subject: [PATCH] Document setup with Google Cloud SQL
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document what needs to be done to connect to Google Cloud SQL.

Fixes #12146

Signed-off-by: Michal Čihař <michal@cihar.com>
---
 ChangeLog      |  1 +
 doc/config.rst | 61 +++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 61 insertions(+), 1 deletion(-)

diff --git a/ChangeLog b/ChangeLog
index ef123db500..33cebede5d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -13,6 +13,7 @@ phpMyAdmin - ChangeLog
 - issue #12129 Improve performance of database structure page
 - issue #12159 Fix PHP error if user did unpack new version over old one
 - issue #12165 Fix parsing of expression 0
+- issue #12146 Document setup with Google Cloud SQL
 
 4.6.0.0 (2016-03-22)
 + issue #11456 Disabled storage engines
diff --git a/doc/config.rst b/doc/config.rst
index 87128eba90..1ef6fedd19 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -254,6 +254,8 @@ Server connection settings
 
     We strongly recommend the ``'mysqli'`` extension when using this option.
 
+    .. seealso:: :ref:`example-google-ssl`
+
 .. config:option:: $cfg['Servers'][$i]['ssl_key']
 
     :type: string
@@ -267,6 +269,8 @@ Server connection settings
 
         $cfg['Servers'][$i]['ssl_key'] = '/etc/mysql/server-key.pem';
 
+    .. seealso:: :ref:`example-google-ssl`
+
 .. config:option:: $cfg['Servers'][$i]['ssl_cert']
 
     :type: string
@@ -274,6 +278,8 @@ Server connection settings
 
     Path to the cert file when using SSL for connecting to the MySQL server.
 
+    .. seealso:: :ref:`example-google-ssl`
+
 .. config:option:: $cfg['Servers'][$i]['ssl_ca']
 
     :type: string
@@ -281,6 +287,8 @@ Server connection settings
 
     Path to the CA file when using SSL for connecting to the MySQL server.
 
+    .. seealso:: :ref:`example-google-ssl`
+
 .. config:option:: $cfg['Servers'][$i]['ssl_ca_path']
 
     :type: string
@@ -288,6 +296,8 @@ Server connection settings
 
     Directory containing trusted SSL CA certificates in PEM format.
 
+    .. seealso:: :ref:`example-google-ssl`
+
 .. config:option:: $cfg['Servers'][$i]['ssl_ciphers']
 
     :type: string
@@ -295,6 +305,8 @@ Server connection settings
 
     List of allowable ciphers for SSL connections to the MySQL server.
 
+    .. seealso:: :ref:`example-google-ssl`
+
 .. config:option:: $cfg['Servers'][$i]['ssl_verify']
 
     :type: boolean
@@ -305,9 +317,15 @@ Server connection settings
     there is a chance your SSL connection will fail due to validation.
     Setting this to ``false`` will disable the validation check.
 
+    Since PHP 5.6.0 it also verifies whether server name matches CN of it's
+    certificate. There is currently no way to disable just this check without
+    disabling complete SSL verification.
+
     .. note::
 
-        This flag only works with PHP 5.6.16 or later
+        This flag only works with PHP 5.6.16 or later.
+
+    .. seealso:: :ref:`example-google-ssl`
 
 .. config:option:: $cfg['Servers'][$i]['connect_type']
 
@@ -2885,3 +2903,44 @@ Developer
 
     Enable to let server present itself as demo server.
     This is used for <http://demo.phpmyadmin.net/>.
+
+
+Examples
+--------
+
+See following configuration snippets for usual setups of phpMyAdmin.
+
+.. _example-google-ssl:
+
+Google Cloud SQL with SSL
++++++++++++++++++++++++++
+
+To connect to Google Could SQL, you currently need to disable certificate
+verification. This is caused by the certficate being issued for CN matching
+your instance name, but you connect to an IP address and PHP tries to match
+these two. With verfication you end up with error message like::
+
+    Peer certificate CN=`api-project-851612429544:pmatest' did not match expected CN=`8.8.8.8'
+
+.. warning::
+
+    With disabled verification your traffic is encrypted, but you're open to
+    man in the middle attacks.
+
+To connect phpMyAdmin to Google Cloud SQL using SSL download the client and
+server certificates and tell phpMyAdmin to use them:
+
+.. code-block:: php
+
+    // IP address of your instance
+    $cfg['Servers'][2]['host'] = '8.8.8.8';
+    // Use SSL for connection
+    $cfg['Servers'][$i]['ssl'] = true;
+    // Client secret key
+    $cfg['Servers'][$i]['ssl_key'] = '../client-key.pem';
+    // Client certificate
+    $cfg['Servers'][$i]['ssl_cert'] = '../client-cert.pem';
+    // Server certification authority
+    $cfg['Servers'][$i]['ssl_ca'] = '../server-ca.pem';
+    // Disable SSL verification (see above note)
+    $cfg['Servers'][$i]['ssl_verify'] = false;