`ssl` --- socket 物件的 TLS/SSL 包裝器¶

原始碼：Lib/ssl.py

這個模組向用戶端及伺服器端提供了對於網路 socket 的傳輸層安全性協定（或稱為「安全通訊協定 (Secure Sockets Layer)」）加密及身分驗證功能。這個模組使用 OpenSSL 套件。

This is an optional module. If it is missing from your copy of CPython, look for documentation from your distributor (that is, whoever provided Python to you). If you are the distributor, see 可選模組的需求.

備註

由於呼叫了作業系統的 socket APIs，有些行為會根據平台而有所不同。OpenSSL 的安裝版本也會對模組的運作產生影響。例如，OpenSSL 版本 1.1.1 附帶 TLSv1.3。

警告

在使用此模組之前，請閱讀 Security considerations。如果不這樣做，可能會產生錯誤的安全性認知，因為 ssl 模組的預設設定未必適合你的應用程式。

可用性: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱 WebAssembly 平台。

這個章節記錄了 ssl 模組的物件及函式；關於 TSL、SSL、以及憑證的更多資訊，可以去參考此章節底部的「詳情」部分。

此模組提供了一個 ssl.SSLSocket 類別，它是從 socket.socket 衍生出來的，並且提供類似 socket 的包裝器，讓使用 SSL 進行資料傳輸時，可以進行資料的加密及解密。它也提供了一些額外的方法，如 getpeercert()，用於取得連結另一端的憑證；以及 cipher()，用於搜尋用於安全連接的加密方法 (cipher)；和 get_verified_chain()、get_unverified_chain() 能用於取得憑證鏈。

對於更複雜的應用程式，ssl.SSLContext 類別有助於管理設定及認證，然後可以透過 SSLContext.wrap_socket() 方法建立的 SSL socket 繼承這些設定和認證。

在 3.5.3 版的變更: 更新以支援與 OpenSSL 1.1.0 進行連結

在 3.6 版的變更: OpenSSL 0.9.8, 1.0.0 及 1.0.1 版本已被棄用且不再支援。在未來 ssl 模組將需要至少 OpenSSL 1.0.2 版本或 1.1.0 版本。

在 3.10 版的變更: PEP 644 已經被實作。ssl 模組需要 OpenSSL 1.1.1 以上的版本才能使用。

使用已經被棄用的常數或函式將會導致棄用警示。

函式、常數與例外¶

Socket 建立¶

SSLSocket 實例必須使用 SSLContext.wrap_socket() 方法來建立。輔助函式 create_default_context() 會回傳有安全預設設定的新語境 (context)。

使用預設語境及 IPv4/IPv6 雙協定堆疊的用戶端 socket 範例：

import socket
import ssl

hostname = 'www.python.org'
context = ssl.create_default_context()

with socket.create_connection((hostname, 443)) as sock:
    with context.wrap_socket(sock, server_hostname=hostname) as ssock:
        print(ssock.version())

使用自訂語境及 IPv4 的用戶端 socket範例：

hostname = 'www.python.org'
# PROTOCOL_TLS_CLIENT requires valid cert chain and hostname
context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
context.load_verify_locations('path/to/cabundle.pem')

with socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0) as sock:
    with context.wrap_socket(sock, server_hostname=hostname) as ssock:
        print(ssock.version())

在本地 IPv4 上監聽伺服器 socket 的範例：

context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
context.load_cert_chain('/path/to/certchain.pem', '/path/to/private.key')

with socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0) as sock:
    sock.bind(('127.0.0.1', 8443))
    sock.listen(5)
    with context.wrap_socket(sock, server_side=True) as ssock:
        conn, addr = ssock.accept()
        ...

語境建立¶

一個可以幫忙建立出 SSLContext 物件以用於一般目的的方便函式。

ssl.create_default_context(purpose=Purpose.SERVER_AUTH, *, cafile=None, capath=None, cadata=None)¶

回傳一個新的 SSLContext 物件，使用給定 purpose 的預設值。這些設定是由 ssl 模組選擇，通常比直接呼叫 SSLContext 建構函式有更高的安全性。

cafile, capath, cadata 是用來選擇用於憑證認證的 CA 憑證，就像 SSLContext.load_verify_locations() 一樣。如果三個值都是 None，此函式會自動選擇系統預設的 CA 憑證。

這些設定包含：PROTOCOL_TLS_CLIENT 或 PROTOCOL_TLS_SERVER、OP_NO_SSLv2、以及 OP_NO_SSLv3，使用高等加密套件但不包含 RC4 和未經身份驗證的加密套件。如果將 purpose 設定為 SERVER_AUTH，則會把 verify_mode 設為 CERT_REQUIRED 並使用設定的 CA 憑證(當 cafile、capath 或 cadata 其中一個值有被設定時) 或使用預設的 CA 憑證 SSLContext.load_default_certs() 。

當系統有支援 keylog_filename 並且有設定環境變數 SSLKEYLOGFILE 時 create_default_context() 會啟用密鑰日誌記錄 (logging)。

The default settings for this context include VERIFY_X509_PARTIAL_CHAIN and VERIFY_X509_STRICT. These make the underlying OpenSSL implementation behave more like a conforming implementation of RFC 5280, in exchange for a small amount of incompatibility with older X.509 certificates.

備註

協定、選項、加密方式和其它設定可以在不捨棄舊值的情況下直接更改成新的值，這些值代表了在相容性和安全性之間取得的合理平衡。

如果你的應用程式需要特殊的設定，你應該要自行建立一個 SSLContext 並自行調整設定。

備註

如果你發現某些舊的用戶端或伺服器常適用此函式建立的 SSLContext 連線時，收到 "Protocol or cipher suite mismatch" 錯誤，這可能是因為他們的系統僅支援 SSL3.0，然而 SSL3.0 已被此函式用 OP_NO_SSLv3 排除。目前廣泛認為 SSL3.0 已經被完全破解。如果你仍然希望在允許 SSL3.0 連線的情況下使用此函式，可以使用下面的方法：

ctx = ssl.create_default_context(Purpose.CLIENT_AUTH)
ctx.options &= ~ssl.OP_NO_SSLv3

備註

This context enables VERIFY_X509_STRICT by default, which may reject pre-RFC 5280 or malformed certificates that the underlying OpenSSL implementation otherwise would accept. While disabling this is not recommended, you can do so using:

ctx = ssl.create_default_context()
ctx.verify_flags &= ~ssl.VERIFY_X509_STRICT

在 3.4 版被加入.

在 3.4.4 版的變更: 把 RC4 從預設加密方法字串中捨棄。

在 3.6 版的變更: 把 ChaCha20/Poly1305 加入預設加密方法字串。

把 3DES 從預設加密方法字串中捨棄。

在 3.8 版的變更: 增加了 SSLKEYLOGFILE 對密鑰日誌記錄 (logging) 的支援。

在 3.10 版的變更: 目前語境使用 PROTOCOL_TLS_CLIENT 協定或 PROTOCOL_TLS_SERVER 協定而非通用的 PROTOCOL_TLS。

在 3.13 版的變更: The context now uses VERIFY_X509_PARTIAL_CHAIN and VERIFY_X509_STRICT in its default verify flags.

例外¶

ssl --- socket 物件的 TLS/SSL 包裝器¶

函式、常數與例外¶

Socket 建立¶

語境建立¶

例外¶

`ssl` --- socket 物件的 TLS/SSL 包裝器¶