mysql_ssl_rsa_setup.1

'\" t
.\"     Title: mysql_ssl_rsa_setup
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 09/17/2024
.\"    Manual: MySQL Database System
.\"    Source: MySQL 8.0
.\"  Language: English
.\"
.TH "MYSQL_SSL_RSA_SETUP" "1" "09/17/2024" "MySQL 8\&.0" "MySQL Database System"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
mysql_ssl_rsa_setup \- create SSL/RSA files
.SH "SYNOPSIS"
.HP \w'\fBmysql_ssl_rsa_setup\ [\fR\fB\fIoptions\fR\fR\fB]\fR\ 'u
\fBmysql_ssl_rsa_setup [\fR\fB\fIoptions\fR\fR\fB]\fR
.SH "DESCRIPTION"
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
\fBmysql_ssl_rsa_setup\fR
is deprecated as of MySQL 8\&.0\&.34\&. Instead, consider using MySQL server to generate missing SSL and RSA files automatically at startup (see
the section called \(lqAutomatic SSL and RSA File Generation\(rq)\&.
.sp .5v
.RE
.PP
This program creates the SSL certificate and key files and RSA key\-pair files required to support secure connections using SSL and secure password exchange using RSA over unencrypted connections, if those files are missing\&.
\fBmysql_ssl_rsa_setup\fR
can also be used to create new SSL files if the existing ones have expired\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
\fBmysql_ssl_rsa_setup\fR
uses the
\fBopenssl\fR
command, so its use is contingent on having OpenSSL installed on your machine\&.
.PP
Another way to generate SSL and RSA files, for MySQL distributions compiled using OpenSSL, is to have the server generate them automatically\&. See
Section\ \&8.3.3.1, \(lqCreating SSL and RSA Certificates and Keys using MySQL\(rq\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBImportant\fR
.ps -1
.br
.PP
\fBmysql_ssl_rsa_setup\fR
helps lower the barrier to using SSL by making it easier to generate the required files\&. However, certificates generated by
\fBmysql_ssl_rsa_setup\fR
are self\-signed, which is not very secure\&. After you gain experience using the files created by
\fBmysql_ssl_rsa_setup\fR, consider obtaining a CA certificate from a registered certificate authority\&.
.sp .5v
.RE
.PP
Invoke
\fBmysql_ssl_rsa_setup\fR
like this:
.sp
.if n \{\
.RS 4
.\}
.nf
mysql_ssl_rsa_setup [\fIoptions\fR]
.fi
.if n \{\
.RE
.\}
.PP
Typical options are
\fB\-\-datadir\fR
to specify where to create the files, and
\fB\-\-verbose\fR
to see the
\fBopenssl\fR
commands that
\fBmysql_ssl_rsa_setup\fR
executes\&.
.PP
\fBmysql_ssl_rsa_setup\fR
attempts to create SSL and RSA files using a default set of file names\&. It works as follows:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
\fBmysql_ssl_rsa_setup\fR
checks for the
\fBopenssl\fR
binary at the locations specified by the
PATH
environment variable\&. If
\fBopenssl\fR
is not found,
\fBmysql_ssl_rsa_setup\fR
does nothing\&. If
\fBopenssl\fR
is present,
\fBmysql_ssl_rsa_setup\fR
looks for default SSL and RSA files in the MySQL data directory specified by the
\fB\-\-datadir\fR
option, or the compiled\-in data directory if the
\fB\-\-datadir\fR
option is not given\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
\fBmysql_ssl_rsa_setup\fR
checks the data directory for SSL files with the following names:
.sp
.if n \{\
.RS 4
.\}
.nf
ca\&.pem
server\-cert\&.pem
server\-key\&.pem
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
If any of those files are present,
\fBmysql_ssl_rsa_setup\fR
creates no SSL files\&. Otherwise, it invokes
\fBopenssl\fR
to create them, plus some additional files:
.sp
.if n \{\
.RS 4
.\}
.nf
ca\&.pem               Self\-signed CA certificate
ca\-key\&.pem           CA private key
server\-cert\&.pem      Server certificate
server\-key\&.pem       Server private key
client\-cert\&.pem      Client certificate
client\-key\&.pem       Client private key
.fi
.if n \{\
.RE
.\}
.sp
These files enable secure client connections using SSL; see
Section\ \&8.3.1, \(lqConfiguring MySQL to Use Encrypted Connections\(rq\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  4." 4.2
.\}
\fBmysql_ssl_rsa_setup\fR
checks the data directory for RSA files with the following names:
.sp
.if n \{\
.RS 4
.\}
.nf
private_key\&.pem      Private member of private/public key pair
public_key\&.pem       Public member of private/public key pair
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  5." 4.2
.\}
If any of these files are present,
\fBmysql_ssl_rsa_setup\fR
creates no RSA files\&. Otherwise, it invokes
\fBopenssl\fR
to create them\&. These files enable secure password exchange using RSA over unencrypted connections for accounts authenticated by the
sha256_password
or
caching_sha2_password
plugin; see
Section\ \&8.4.1.3, \(lqSHA-256 Pluggable Authentication\(rq, and
Section\ \&8.4.1.2, \(lqCaching SHA-2 Pluggable Authentication\(rq\&.
.RE
.PP
For information about the characteristics of files created by
\fBmysql_ssl_rsa_setup\fR, see
Section\ \&8.3.3.1, \(lqCreating SSL and RSA Certificates and Keys using MySQL\(rq\&.
.PP
At startup, the MySQL server automatically uses the SSL files created by
\fBmysql_ssl_rsa_setup\fR
to enable SSL if no explicit SSL options are given other than
\fB\-\-ssl\fR
(possibly along with
ssl_cipher)\&. If you prefer to designate the files explicitly, invoke clients with the
\fB\-\-ssl\-ca\fR,
\fB\-\-ssl\-cert\fR, and
\fB\-\-ssl\-key\fR
options at startup to name the
ca\&.pem,
server\-cert\&.pem, and
server\-key\&.pem
files, respectively\&.
.PP
The server also automatically uses the RSA files created by
\fBmysql_ssl_rsa_setup\fR
to enable RSA if no explicit RSA options are given\&.
.PP
If the server is SSL\-enabled, clients use SSL by default for the connection\&. To specify certificate and key files explicitly, use the
\fB\-\-ssl\-ca\fR,
\fB\-\-ssl\-cert\fR, and
\fB\-\-ssl\-key\fR
options to name the
ca\&.pem,
client\-cert\&.pem, and
client\-key\&.pem
files, respectively\&. However, some additional client setup may be required first because
\fBmysql_ssl_rsa_setup\fR
by default creates those files in the data directory\&. The permissions for the data directory normally enable access only to the system account that runs the MySQL server, so client programs cannot use files located there\&. To make the files available, copy them to a directory that is readable (but
\fInot\fR
writable) by clients:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
For local clients, the MySQL installation directory can be used\&. For example, if the data directory is a subdirectory of the installation directory and your current location is the data directory, you can copy the files like this:
.sp
.if n \{\
.RS 4
.\}
.nf
cp ca\&.pem client\-cert\&.pem client\-key\&.pem \&.\&.
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
For remote clients, distribute the files using a secure channel to ensure they are not tampered with during transit\&.
.RE
.PP
If the SSL files used for a MySQL installation have expired, you can use
\fBmysql_ssl_rsa_setup\fR
to create new ones:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
Stop the server\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
Rename or remove the existing SSL files\&. You may wish to make a backup of them first\&. (The RSA files do not expire, so you need not remove them\&.
\fBmysql_ssl_rsa_setup\fR
can see that they exist and does not overwrite them\&.)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
Run
\fBmysql_ssl_rsa_setup\fR
with the
\fB\-\-datadir\fR
option to specify where to create the new files\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  4." 4.2
.\}
Restart the server\&.
.RE
.PP
\fBmysql_ssl_rsa_setup\fR
supports the following command\-line options, which can be specified on the command line or in the
[mysql_ssl_rsa_setup]
and
[mysqld]
groups of an option file\&. For information about option files used by MySQL programs, see
Section\ \&6.2.2.2, \(lqUsing Option Files\(rq\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-\-help\fR,
\fB?\fR
.TS
allbox tab(:);
lB l.
T{
Command-Line Format
T}:T{
--help
T}
.TE
.sp 1
Display a help message and exit\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-\-datadir=\fR\fB\fIdir_name\fR\fR
.TS
allbox tab(:);
lB l
lB l.
T{
Command-Line Format
T}:T{
--datadir=dir_name
T}
T{
Type
T}:T{
Directory name
T}
.TE
.sp 1
The path to the directory that
\fBmysql_ssl_rsa_setup\fR
should check for default SSL and RSA files and in which it should create files if they are missing\&. The default is the compiled\-in data directory\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-\-suffix=\fR\fB\fIstr\fR\fR
.TS
allbox tab(:);
lB l
lB l.
T{
Command-Line Format
T}:T{
--suffix=str
T}
T{
Type
T}:T{
String
T}
.TE
.sp 1
The suffix for the Common Name attribute in X\&.509 certificates\&. The suffix value is limited to 17 characters\&. The default is based on the MySQL version number\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-\-uid=name\fR,
\fB\-v\fR
.TS
allbox tab(:);
lB l.
T{
Command-Line Format
T}:T{
--uid=name
T}
.TE
.sp 1
The name of the user who should be the owner of any created files\&. The value is a user name, not a numeric user ID\&. In the absence of this option, files created by
\fBmysql_ssl_rsa_setup\fR
are owned by the user who executes it\&. This option is valid only if you execute the program as
root
on a system that supports the
chown()
system call\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-\-verbose\fR,
\fB\-v\fR
.TS
allbox tab(:);
lB l.
T{
Command-Line Format
T}:T{
--verbose
T}
.TE
.sp 1
Verbose mode\&. Produce more output about what the program does\&. For example, the program shows the
\fBopenssl\fR
commands it runs, and produces output to indicate whether it skips SSL or RSA file creation because some default file already exists\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-\-version\fR,
\fB\-V\fR
.TS
allbox tab(:);
lB l.
T{
Command-Line Format
T}:T{
--version
T}
.TE
.sp 1
Display version information and exit\&.
.RE
.SH "COPYRIGHT"
.br
.PP
Copyright \(co 1997, 2024, Oracle and/or its affiliates.
.PP
This documentation is free software; you can redistribute it and/or modify it only under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 of the License.
.PP
This documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public License along with the program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA or see http://www.gnu.org/licenses/.
.sp
.SH "SEE ALSO"
For more information, please refer to the MySQL Reference Manual,
which may already be installed locally and which is also available
online at http://dev.mysql.com/doc/.
.SH AUTHOR
Oracle Corporation (http://dev.mysql.com/).