MySQL :: MySQL 9.0 C API 开发者指南 :: 5.4.82 mysql_ssl_set()

版本 9.0

8.4 当前
8.0
5.7

MySQL 9.0 C API 开发者指南 / ... / mysql_ssl_set()

5.4.82 mysql_ssl_set()

bool
mysql_ssl_set(MYSQL *mysql,
              const char *key,
              const char *cert,
              const char *ca,
              const char *capath,
              const char *cipher)

说明

注意

从 MySQL 8.0.35 开始，mysql_ssl_set() 已弃用，并将在未来的 MySQL 版本中移除。所有 mysql_ssl_set() 参数都有等效的 mysql_options() TLS 选项。

mysql_ssl_set() 用于使用 SSL 建立加密连接。 mysql 参数必须是有效的连接句柄。任何未使用的 SSL 参数都可以指定为 NULL。

如果使用 mysql_ssl_set()，则必须在 mysql_real_connect() 之前调用。除非在客户端库中启用了 SSL 支持，否则 mysql_ssl_set() 不执行任何操作。

调用 mysql_ssl_set() 来获取加密连接是可选的，因为默认情况下，如果服务器支持加密连接，MySQL 程序会尝试使用加密连接，如果无法建立加密连接，则会回退到未加密连接（请参阅配置 MySQL 以使用加密连接）。对于必须指定特定证书和密钥文件、加密密码等的应用程序来说，mysql_ssl_set() 可能很有用。

mysql_ssl_set() 指定 SSL 信息（例如用于建立加密连接的证书和密钥文件，如果此类连接可用），但不要求获取的连接必须加密。要要求加密连接，请使用第 3.6.1 节“对加密连接的支持” 中描述的技术。

为了获得相对于默认加密提供的额外安全性，客户端可以提供与服务器使用的证书相匹配的 CA 证书，并启用主机名身份验证。这样，服务器和客户端就信任同一个 CA 证书，并且客户端会验证它所连接的主机是否是预期的主机。有关详细信息，请参阅第 3.6.1 节“对加密连接的支持”。

mysql_ssl_set() 是一个便捷函数，它实际上等效于以下一组 mysql_options() 调用：

mysql_options(mysql, MYSQL_OPT_SSL_KEY,    key);
mysql_options(mysql, MYSQL_OPT_SSL_CERT,   cert);
mysql_options(mysql, MYSQL_OPT_SSL_CA,     ca);
mysql_options(mysql, MYSQL_OPT_SSL_CAPATH, capath);
mysql_options(mysql, MYSQL_OPT_SSL_CIPHER, cipher);

由于这种等效性，应用程序可以调用 mysql_options() 来代替调用 mysql_ssl_set()，省略对选项值为 NULL 的选项的调用。此外，mysql_options() 提供了 mysql_ssl_set() 中没有的加密连接选项，例如用于指定连接安全状态的 MYSQL_OPT_SSL_MODE，以及用于指定客户端允许用于加密连接的协议的 MYSQL_OPT_TLS_VERSION。

参数

mysql：由 mysql_init() 返回的连接句柄。
key：客户端私钥文件的路径名。
cert：客户端公钥证书文件的路径名。
ca：证书颁发机构 (CA) 证书文件的路径名。如果使用此选项，则必须指定与服务器使用的证书相同的证书。
capath：包含受信任的 SSL CA 证书文件的目录的路径名。
cipher：允许用于 SSL 加密的密码列表。

返回值

如果操作成功，则此函数返回 false，否则返回 true。如果 SSL 设置不正确，则在尝试连接时，后续的 mysql_real_connect() 调用将返回错误。