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()。mysql_ssl_set() 除非在用戶端程式庫中啟用 SSL 支援，否則不會執行任何操作。

呼叫 mysql_ssl_set() 以取得加密連線是可選的，因為預設情況下，如果伺服器支援加密連線，MySQL 程式會嘗試使用加密連線，如果無法建立加密連線，則會回復為未加密的連線（請參閱設定 MySQL 使用加密連線）。mysql_ssl_set() 對於必須指定特定憑證和金鑰檔案、加密密碼等的應用程式可能很有用。

mysql_ssl_set() 指定 SSL 資訊，例如憑證和金鑰檔案，以便在有此類連線時建立加密連線，但並未強制要求取得的連線必須加密。若要要求加密連線，請使用第 3.6.1 節「支援加密連線」中描述的技術。

為了提高相對於預設加密提供的安全性，用戶端可以提供與伺服器使用的 CA 憑證相符的 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_ssl_set()，而是直接呼叫 mysql_options()，省略選項值為 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() 呼叫會傳回錯誤。