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

版本 8.4

MySQL 8.4 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_real_connect() 之前调用 mysql_ssl_set()。除非在客户端库中启用了 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() 调用将返回错误。