Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:108586
MIME-Version: 1.0
Date: Fri, 14 Feb 2020 09:46:31 -0800
Message-ID: <CADbOR2hOzZwtv6Y3_DuJQa4E1EzfDHrbxGiBqmqmHLcJbzG+rg@mail.gmail.com>
To: internals <internals@lists.php.net>
Content-Type: multipart/alternative; boundary="000000000000d78e5a059e8cc9cd"
Subject: Problems with mysqli code and documentation
From: zardozrocks@gmail.com (j adams)

--000000000000d78e5a059e8cc9cd
Content-Type: text/plain; charset="UTF-8"

I had considerable difficulty getting mysqli_connect to use SSL/TSL to
connect to a db and I think some things need to be improved. I apologize
for also describing documentation issues here, but I'll describe the coding
issues first. I may need some help to prompt the documentation team to
remedy some issues. It is my feeling that PHP's credibility as a viable
modern language depends in large part on reliable and well-documented
encryption functionality to satisfy security best practices for vital
database connectivity. PHP's documentation has been one of its great assets
over the years and I hope to see that great tradition continued robustly.

CONTEXT
An email from Amazon informed me they are upgrading the certificates for
their Relational Database Servers (RDS). This prompted me to try and
connect from PHP to an RDS MySQL server using SSL/TSL. The experience was
difficult and unhappy. It's tricky mostly because the documentation on
mysqli features relating to SSL/TLS is poor, but also because the
underlying PHP code doesn't make use of a variable (or more?) in the
underlying source code.

CODING/DEV ISSUES
1) As pointed out here
<https://stackoverflow.com/questions/54299690/does-mysqli-verify-server-certificates-by-default-when-using-ssl?answertab=votes#tab-top>,
the constant MYSQLI_OPT_SSL_VERIFY_SERVER_CERT is defined in PHP
<https://github.com/php/php-src/search?q=MYSQLI_OPT_SSL_VERIFY_SERVER_CERT&unscoped_q=MYSQLI_OPT_SSL_VERIFY_SERVER_CERT>
but apparently doesn't do anything at all. A decision needs to be made
about whether to remove this constant or to somehow reconcile its relation
to the constant MYSQLI_CLIENT_SSL_DONT_VERIFY_SERVER_CERT. The former
constant is supplied to the function mysqli_options and does absolutely
nothing, the latter is a flag to the function mysqli_real_connect and does
appear to prevent validation of the server's SSL/TLS certificate during
handshaking. There may be other orphaned variables that are not used, I
don't know.

2) If one specifies "localhost" as the host when trying to mysqli_connect
using SSL/TLS, then the connection will fail with these warnings:
PHP Warning:  mysqli_real_connect(): this stream does not support
SSL/crypto in /path/to/file.php on line XX
PHP Warning:  mysqli_real_connect(): Cannot connect to MySQL by using SSL
in /path/to/file.php on line XX
PHP Warning:  mysqli_real_connect(): [2002]  (trying to connect via (null))
in /path/to/file.php on line XX
PHP Warning:  mysqli_real_connect(): (HY000/2002):  in /path/to/file.php on
line XX

That's four warnings and a highly cryptic problem which is not easily
diagnosed because there is no documentation or user comments to clarify the
issue. Using 127.0.0.1 instead of localhost seems to remedy the problem for
some reason surely related to transport, but it would certainly be
preferable if the PHP code was smart enough to recognize the situation
enough to provide a single, more meaningful warning.

DOCUMENTATION (AND POSSIBLY CODING) ISSUES
A) mysqli_ssl_set <https://www.php.net/manual/en/mysqli.ssl-set.php> has no
usage examples and the parameter descriptions border on useless. For
example:

key
    The path name to the key file.
cert
    The path name to the certificate file.
ca
    The path name to the certificate authority file.

No mention is made of format. No effort is made to describe whether these
are client keys/certs or server keys/certs. Is this a private key or public
key? I admit my knowledge of the relation between certificates and the
certificate authority file is a little fuzzy, but I'm hardly a novice
programmer and feel this documentation leaves a lot to be desired. Most of
the coding examples I find using this function set only the ca, leaving the
majority of the numerous other parameters empty. The documentation does not
describe what happens when these values are NULL or what happens of the
specified file paths don't exist. It doesn't describe what string values
are permissible -- which is especially disconcerting for the cipher
parameter, which surely admits only certain constants? For some reason this
function always returns a TRUE value, and does not throw any exceptions
(e.g., if the files don't exist). What doe these parameters do? What does
this function do?

B) documentation for mysqli_real_connect
<https://www.php.net/manual/en/mysqli.real-connect.php> does not
sufficiently describe how it differs from mysqli_connect. E.g., it doesn't
mention that mysqli_real_connect is helpful in lieu of mysqli_connect if
you must set options like connect timeouts, etc. It does not provide any
examples that use the flags parameter. Why do we have these two distinct
functions? Is there some way to use mysqli_ssl_set with mysqli_connect? Or
must one always use mysqli_real_connect?

In digging further into the MySQLi documentation, I see that there is a lot
of helpful detail on the Quick Start articles, and would suggest that the
level of detail in Quick Start should be the bare minimum, with the details
being moved into the documentation of the functions themselves.

C) The mysqli_options page
<https://www.php.net/manual/en/mysqli.options.php> lists
MYSQLI_OPT_SSL_VERIFY_SERVER_CERT but does not describe anything about it.
As mentioned above, this constant does nothing and should probably be
removed. This page also does not have a link to to the MySQLi predefined
constants page for additional detail.

I hope I haven't offended anyone with this message. I love PHP and want to
see it be the best development language there is.

--000000000000d78e5a059e8cc9cd--