ssl —- 套接字對(duì)象的 TLS/SSL 包裝器

源代碼: Lib/ssl.py

創(chuàng)新互聯(lián)公司網(wǎng)站建設(shè)公司是一家服務(wù)多年做網(wǎng)站建設(shè)策劃設(shè)計(jì)制作的公司,為廣大用戶提供了成都網(wǎng)站設(shè)計(jì)、成都網(wǎng)站制作，成都網(wǎng)站設(shè)計(jì)，一元廣告，成都做網(wǎng)站選創(chuàng)新互聯(lián)公司，貼合企業(yè)需求，高性價(jià)比，滿足客戶不同層次的需求一站式服務(wù)歡迎致電。

該模塊提供了對(duì)傳輸層安全（通常稱為 “安全套接字層”）加密和網(wǎng)絡(luò)套接字的對(duì)等認(rèn)證設(shè)施的訪問(wèn)，包括客戶端和服務(wù)器端。 該模塊使用 OpenSSL 庫(kù)。它可以在所有現(xiàn)代 Unix 系統(tǒng)、 Windows 、 macOS 和可能的其他平臺(tái)上使用，只要 OpenSSL 安裝在該平臺(tái)上。

備注

某些行為可能與平臺(tái)相關(guān)，因?yàn)檎{(diào)用了操作系統(tǒng)的套接字 API。已安裝的OpenSSL 版本也可能會(huì)導(dǎo)致不同的行為。比如 TLSv 1.3 與 Open SSL 1.1.1 就不一樣。

警告

在閱讀 安全考量 前不要使用此模塊。 這樣做可能會(huì)導(dǎo)致虛假的安全感，因?yàn)閟sl模塊的默認(rèn)設(shè)置不一定適合你的應(yīng)用程序。

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssembly platforms for more information.

文檔本文檔記錄``ssl`` 模塊的對(duì)象和函數(shù)；更多關(guān)于TLS,SSL,和證書的信息，請(qǐng)參閱下方的“詳情”選項(xiàng)

本模塊提供了一個(gè)類 ssl.SSLSocket，它派生自 socket.socket 類型，并提供類似套接字的包裝器，也能夠?qū)νㄟ^(guò)帶 SSL 套接字的數(shù)據(jù)進(jìn)行加密和解密。 它支持一些額外方法例如 getpeercert()，該方法可從連接的另一端獲取證書，還有 cipher()，該方法可獲取安全連接所使用的密碼。

對(duì)于更復(fù)雜的應(yīng)用程序，ssl.SSLContext 類有助于管理設(shè)置項(xiàng)和證書，進(jìn)而可以被使用 SSLContext.wrap_socket() 方法創(chuàng)建的 SSL 套接字繼承。

在 3.5.3 版更改: 更新以支持和 OpenSSL 1.1.0 的鏈接

在 3.6 版更改: OpenSSL 0.9.8、1.0.0 和 1.0.1 已過(guò)時(shí)，將不再被支持。在 ssl 模塊未來(lái)的版本中，最低需要 OpenSSL 1.0.2 或 1.1.0。

在 3.10 版更改: PEP 644 已經(jīng)實(shí)現(xiàn)。ssl 模塊需要 OpenSSL 1.1.1 以上版本的支持。

使用廢棄的常量和函數(shù)會(huì)導(dǎo)致廢棄警告。

方法、常量和異常處理

套接字創(chuàng)建

從 python 3.2 和 2.7.9 開始，建議使用 SSLContext 實(shí)例的 SSLContext.wrap_socket() 來(lái)將套接字包裝為 SSLSocket 對(duì)象。 輔助函數(shù) create_default_context() 會(huì)返回一個(gè)新的帶有安全默認(rèn)設(shè)置的上下文。 舊的 wrap_socket() 函數(shù)已被棄用，因?yàn)樗瘦^差并且不支持服務(wù)器名稱提示（SNI）和主機(jī)匹配。

客戶端套接字實(shí)例，采用默認(rèn)上下文和IPv4/IPv6雙棧:

 
 
 
 
  
  
  
  
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:

 
 
 
 
  
  
  
  
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())
 
 
 

服務(wù)器套接字實(shí)例，在localhost上監(jiān)聽I(yíng)Pv4:

 
 
 
 
  
  
  
  
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()
  
  
  
  
 ...
 
 
 

上下文創(chuàng)建

便捷函數(shù)，可以幫助創(chuàng)建 SSLContext 對(duì)象，用于常見(jiàn)的目的。

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

返回一個(gè)新的 SSLContext 對(duì)象，使用給定 purpose 的默認(rèn)設(shè)置。 該設(shè)置由 ssl 模塊選擇，并且通常是代表一個(gè)比直接調(diào)用 SSLContext 構(gòu)造器時(shí)更高的安全等級(jí)。

cafile, capath, cadata 代表用于進(jìn)行證書核驗(yàn)的可選受信任 CA 證書，與 SSLContext.load_verify_locations() 的一致。 如果三個(gè)參數(shù)均為 None，此函數(shù)可以轉(zhuǎn)而選擇信任系統(tǒng)的默認(rèn) CA 證書。

設(shè)置為： PROTOCOL_TLS_CLIENT 或 PROTOCOL_TLS_SERVER、 OP_NO_SSLv2 和 OP_NO_SSLv3，帶有不含 RC4 及未認(rèn)證的高強(qiáng)度加密密碼套件。 傳入 SERVER_AUTH 作為 purpose，會(huì)將 verify_mode 設(shè)為 CERT_REQUIRED，并加載 CA 證書（若給出 cafile、capath 或 cadata 之一）或用 SSLContext.load_default_certs() 加載默認(rèn)CA證書。

當(dāng) keylog_filename 受支持并且設(shè)置了環(huán)境變量 SSLKEYLOGFILE 時(shí)，create_default_context() 會(huì)啟用密鑰日志記錄。

備注

協(xié)議、選項(xiàng)、密碼和其他設(shè)置可隨時(shí)更改為更具約束性的值而無(wú)須事先棄用。 這些值代表了兼容性和安全性之間的合理平衡。

如果你的應(yīng)用需要特定的設(shè)置，你應(yīng)當(dāng)創(chuàng)建一個(gè) SSLContext 并自行應(yīng)用設(shè)置。

備注

如果你發(fā)現(xiàn)當(dāng)某些較舊的客戶端或服務(wù)器嘗試與用此函數(shù)創(chuàng)建的 SSLContext 進(jìn)行連接時(shí)收到了報(bào)錯(cuò)提示 “Protocol or cipher suite mismatch”，這可能是因?yàn)樗鼈冎恢С?SSL3.0 而它被此函數(shù)用 OP_NO_SSLv3 排除掉了。 SSL3.0 被廣泛認(rèn)為 完全不可用。 如果你仍希望繼續(xù)使用此函數(shù)但仍允許 SSL 3.0 連接，你可以使用以下代碼重新啟用它們:

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

3.4 新版功能.

在 3.4.4 版更改: RC4 被從默認(rèn)密碼字符串中丟棄。

在 3.6 版更改: ChaCha20/Poly1305 被添加到默認(rèn)密碼字符串中。

3DES 被從默認(rèn)密碼字符串中丟棄。

在 3.8 版更改: 增加了對(duì)密鑰日志記錄至 SSLKEYLOGFILE 的支持。

在 3.10 版更改: 當(dāng)前上下文使用 PROTOCOL_TLS_CLIENT 或 PROTOCOL_TLS_SERVER 協(xié)議而非通用的 PROTOCOL_TLS。

異常

exception ssl.SSLError

引發(fā)此異常以提示來(lái)自下層 SSL 實(shí)現(xiàn)（目前由 OpenSSL 庫(kù)提供）的錯(cuò)誤。 它表示在下層網(wǎng)絡(luò)連接之上疊加的高層級(jí)加密和驗(yàn)證層存在某種問(wèn)題。 此錯(cuò)誤是 OSError 的一個(gè)子類型。 SSLError 實(shí)例的錯(cuò)誤和消息是由 OpenSSL 庫(kù)提供的。

在 3.3 版更改: SSLError 曾經(jīng)是 socket.error 的一個(gè)子類型。

• library

  一個(gè)字符串形式的助記符，用來(lái)指明發(fā)生錯(cuò)誤的 OpenSSL 子模塊，例如 SSL, PEM 或 X509。 可能的取值范圍依賴于 OpenSSL 的版本。

  3.3 新版功能.

• reason

  一個(gè)字符串形式的助記符，用來(lái)指明發(fā)生錯(cuò)誤的原因，例如 CERTIFICATE_VERIFY_FAILED。 可能的取值范圍依賴于 OpenSSL 的版本。

  3.3 新版功能.

exception ssl.SSLZeroReturnError

SSLError 的子類，當(dāng)嘗試讀取或?qū)懭肭?SSL 連接已被完全關(guān)閉時(shí)會(huì)被引發(fā)。 請(qǐng)注意這并不意味著下層的傳輸（讀取 TCP）已被關(guān)閉。

3.3 新版功能.

exception ssl.SSLWantReadError

SSLError 的子類，當(dāng)嘗試讀取或?qū)懭霐?shù)據(jù)，但在請(qǐng)求被滿足之前還需要在下層的 TCP 傳輸上接收更多數(shù)據(jù)時(shí)會(huì)被 非阻塞型 SSL 套接字 引發(fā)。

3.3 新版功能.

exception ssl.SSLWantWriteError

SSLError 的子類，當(dāng)嘗試讀取或?qū)懭霐?shù)據(jù)，但在請(qǐng)求被滿足之前還需要在下層的 TCP 傳輸上發(fā)送更多數(shù)據(jù)時(shí)會(huì)被 非阻塞型 SSL 套接字 引發(fā)。

3.3 新版功能.

exception ssl.SSLSyscallError

SSLError 的子類，當(dāng)嘗試在 SSL 套接字上執(zhí)行操作時(shí)遇到系統(tǒng)錯(cuò)誤時(shí)會(huì)被引發(fā)。 不幸的是，沒(méi)有簡(jiǎn)單的方式能檢查原始 errno 編號(hào)。

3.3 新版功能.

exception ssl.SSLEOFError

SSLError 的子類，當(dāng) SSL 連接被突然終止時(shí)會(huì)被引發(fā)。 通常，當(dāng)遇到此錯(cuò)誤時(shí)你不應(yīng)再嘗試重用下層的傳輸。

3.3 新版功能.

exception ssl.SSLCertVerificationError

SSLError 的子類，當(dāng)證書驗(yàn)證失敗時(shí)會(huì)被引發(fā)。

3.7 新版功能.

• verify_code

  一個(gè)數(shù)字形式的錯(cuò)誤編號(hào)，用于表示驗(yàn)證錯(cuò)誤。

• verify_message

  用于表示驗(yàn)證錯(cuò)誤的人類可讀的字符串。

exception ssl.CertificateError

SSLCertVerificationError 的別名。

在 3.7 版更改: 此異?，F(xiàn)在是 SSLCertVerificationError 的別名。

隨機(jī)生成

ssl.RAND_bytes(num)

返回 num 個(gè)高加密強(qiáng)度偽隨機(jī)字節(jié)數(shù)據(jù)。 如果 PRNG 未使用足夠的數(shù)據(jù)作為隨機(jī)種子或者如果當(dāng)前 RAND 方法不支持該操作則會(huì)引發(fā) SSLError。 RAND_status() 可被用來(lái)檢查 PRNG 的狀態(tài)而 RAND_add() 可被用來(lái)為 PRNG 設(shè)置隨機(jī)種子。

對(duì)于幾乎所有應(yīng)用程序都更推薦使用 os.urandom()。

請(qǐng)閱讀維基百科文章 Cryptographically secure pseudorandom number generator (CSPRNG) 以了解對(duì)于高加密強(qiáng)度生成器的具體要求。

3.3 新版功能.

ssl.RAND_pseudo_bytes(num)

返回 (bytes, is_cryptographic): bytes 是 num 個(gè)偽隨機(jī)字節(jié)數(shù)據(jù)，如果所生成的字節(jié)數(shù)據(jù)為高加密強(qiáng)度則 is_cryptographic 為 True。 如果當(dāng)前 RAND 方法不支持此操作則會(huì)引發(fā) SSLError。

所生成的偽隨機(jī)字節(jié)序列如果具有足夠的長(zhǎng)度則將會(huì)具有唯一性，并是并非不可預(yù)測(cè)。 它們可被用于非加密目的以及加密協(xié)議中的特定目的，但通常不可被用于密鑰生成等目的。

對(duì)于幾乎所有應(yīng)用程序都更推薦使用 os.urandom()。

3.3 新版功能.

3.6 版后已移除: OpenSSL 已棄用了 ssl.RAND_pseudo_bytes()，請(qǐng)改用 ssl.RAND_bytes()。

ssl.RAND_status()

如果 SSL 偽隨機(jī)數(shù)生成器已使用‘足夠的’隨機(jī)性作為種子則返回 True，否則返回 False。 你可以使用 ssl.RAND_egd() 和 ssl.RAND_add() 來(lái)增加偽隨機(jī)數(shù)生成器的隨機(jī)性。

ssl.RAND_add(bytes, entropy)

將給定的 bytes 混合到 SSL 偽隨機(jī)數(shù)生成器中。 形參 entropy (float 類型) 是數(shù)據(jù)所包含的熵的下界 (因此你可以總是使用 0.0)。 請(qǐng)查看 RFC 1750 了解有關(guān)熵源的更多信息。

在 3.5 版更改: 現(xiàn)在接受可寫的 字節(jié)類對(duì)象。

證書處理

ssl.match_hostname(cert, hostname)

驗(yàn)證 cert (使用 SSLSocket.getpeercert() 所返回的已解碼格式) 是否匹配給定的 hostname。 所應(yīng)用的規(guī)則是在 RFC 2818, RFC 5280 和 RFC 6125 中描述的檢查 HTTPS 服務(wù)器身份的規(guī)則。 除了 HTTPS，此函數(shù)還應(yīng)當(dāng)適用于各種基于 SSL 協(xié)議的服務(wù)器身份檢查操作，例如 FTPS, IMAPS, POPS 等等。

失敗時(shí)引發(fā) CertificateError。 成功時(shí)此函數(shù)無(wú)返回值:

 
 
 
 
  
  
  
  
>>> cert = {'subject': ((('commonName', 'example.com'),),)}
  
  
  
  
>>> ssl.match_hostname(cert, "example.com")
  
  
  
  
>>> ssl.match_hostname(cert, "example.org")
  
  
  
  
Traceback (most recent call last):
  
  
  
  
 File "", line 1, in 
  
  
  
  
 File "/home/py3k/Lib/ssl.py", line 130, in match_hostname
  
  
  
  
ssl.CertificateError: hostname 'example.org' doesn't match 'example.com'
 
 
 

3.2 新版功能.

在 3.3.3 版更改: 此函數(shù)現(xiàn)在遵循 RFC 6125, 6.4.3 小節(jié)，它不會(huì)匹配多個(gè)通配符 (例如 *.*.com 或 *a*.example.org) 也不匹配國(guó)際化域名 (IDN) 片段內(nèi)部的通配符。 IDN A 標(biāo)簽例如 www*.xn--pthon-kva.org 仍然受支持，但 x*.python.org 不再能匹配 xn--tda.python.org。

在 3.5 版更改: 現(xiàn)在支持匹配存在于證書的 subjectAltName 字段中的 IP 地址。

在 3.7 版更改: 此函數(shù)不再被用于 TLS 連接。 主機(jī)匹配現(xiàn)在是由 OpenSSL 執(zhí)行的。

允許位于段的最左端且為唯一字符的通配符。 部分通配符例如 www*.example.com 已不再受支持。

3.7 版后已移除.

ssl.cert_time_to_seconds(cert_time)

返回距離 Unix 紀(jì)元零時(shí)的秒數(shù)，給定的 cert_time 字符串代表來(lái)自證書的 “notBefore” 或 “notAfter” 日期值，采用 "%b %d %H:%M:%S %Y %Z" strptime 格式（C 區(qū)域）。

以下為示例代碼:

 
 
 
 
  
  
  
  
>>> import ssl
  
  
  
  
>>> timestamp = ssl.cert_time_to_seconds("Jan 5 09:34:43 2018 GMT")
  
  
  
  
>>> timestamp
  
  
  
  
1515144883
  
  
  
  
>>> from datetime import datetime
  
  
  
  
>>> print(datetime.utcfromtimestamp(timestamp))
  
  
  
  
2018-01-05 09:34:43
 
 
 

“notBefore” 或 “notAfter” 日期值必須使用 GMT (RFC 5280)。

在 3.5 版更改: 將輸入時(shí)間解讀為 UTC 時(shí)間，基于輸入字符串中指明的 ‘GMT’ 時(shí)區(qū)。 在之前使用的是本地時(shí)區(qū)。 返回一個(gè)整數(shù)（不帶輸入格式中秒的分?jǐn)?shù)部分）

ssl.get_server_certificate(addr, ssl_version=PROTOCOL_TLS_CLIENT, ca_certs=None[, timeout])

給出一個(gè)受 SSL 保護(hù)的服務(wù)器的地址 addr，形式為 (hostname, port-number) ，獲取該服務(wù)器的證書，并以 PEM 編碼的字符串返回。如果指定了 ssl_version，則使用該版本的 SSL 協(xié)議嘗試連接服務(wù)器。如果指定了 ca_certs，它應(yīng)該是一個(gè)包含根證書列表的文件，與 SSLContext.wrap_socket() 中同名參數(shù)的格式相同。該調(diào)用將嘗試根據(jù)該根證書集來(lái)驗(yàn)證服務(wù)器的證書，如果驗(yàn)證失敗則調(diào)用失敗。參數(shù) timeout 可用于指定超時(shí)時(shí)間。

在 3.3 版更改: 此函數(shù)現(xiàn)在是 IPv6 兼容的。-compatible.

在 3.5 版更改: 默認(rèn)的 ssl_version 從 PROTOCOL_SSLv3 改為 PROTOCOL_TLS 以保證與現(xiàn)代服務(wù)器的最大兼容性。

在 3.10 版更改: 加入 timeout 參數(shù)。

ssl.DER_cert_to_PEM_cert(DER_cert_bytes)

根據(jù)給定的 DER 編碼字節(jié)塊形式的證書，返回同一證書的 PEM 編碼字符串版本。

ssl.PEM_cert_to_DER_cert(PEM_cert_string)

根據(jù)給定的 ASCII PEM 字符串形式的證書，返回同一證書的 DER 編碼字節(jié)序列。

ssl.get_default_verify_paths()

返回包含 OpenSSL 的默認(rèn) cafile 和 capath 的路徑的命名元組。 此路徑與 SSLContext.set_default_verify_paths() 所使用的相同。 返回值是一個(gè) named tuple DefaultVerifyPaths:

• cafile - 解析出的 cafile 路徑或者如果文件不存在則為 None,

• capath - 解析出的 capath 路徑或者如果目錄不存在則為 None,

• openssl_cafile_env - 指向一個(gè) cafile 的 OpenSSL 環(huán)境鍵,

• openssl_cafile - 一個(gè) cafile 的硬編碼路徑,

• openssl_capath_env - 指向一個(gè) capath 的 OpenSSL 環(huán)境鍵,

• openssl_capath - 一個(gè) capath 目錄的硬編碼路徑

3.4 新版功能.

ssl.enum_certificates(store_name)

從 Windows 的系統(tǒng)證書庫(kù)中檢索證書。 store_name 可以是 CA, ROOT 或 MY 中的一個(gè)。 Windows 也可能會(huì)提供額外的證書庫(kù)。

此函數(shù)返回一個(gè)包含 (cert_bytes, encoding_type, trust) 元組的列表。 encoding_type 指明 cert_bytes 的編碼格式。 它可以為 x509_asn 以表示 X.509 ASN.1 數(shù)據(jù)或是 pkcs_7_asn 以表示 PKCS#7 ASN.1 數(shù)據(jù)。 trust 以 OIDS 集合的形式指明證書的目的，或者如果證書對(duì)于所有目的都可以信任則為 True。

示例:

 
 
 
 
  
  
  
  
>>> ssl.enum_certificates("CA")
  
  
  
  
[(b'data...', 'x509_asn', {'1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2'}),
  
  
  
  
 (b'data...', 'x509_asn', True)]
 
 
 

可用性: Windows。

3.4 新版功能.

ssl.enum_crls(store_name)

Windows 的系統(tǒng)證書庫(kù)中檢索 CRL。 store_name 可以是 CA, ROOT 或 MY 中的一個(gè)。 Windows 也可能會(huì)提供額外的證書庫(kù)。

此函數(shù)返回一個(gè)包含 (cert_bytes, encoding_type, trust) 元組的列表。 encoding_type 指明 cert_bytes 的編碼格式。 它可以為 x509_asn 以表示 X.509 ASN.1 數(shù)據(jù)或是 pkcs_7_asn 以表示 PKCS#7 ASN.1 數(shù)據(jù)。

可用性: Windows。

3.4 新版功能.

ssl.wrap_socket(sock, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ssl_version=PROTOCOL_TLS, ca_certs=None, do_handshake_on_connect=True, suppress_ragged_eofs=True, ciphers=None)

接受一個(gè) socket.socket 的實(shí)例 sock，并返回一個(gè) ssl.SSLSocket 的實(shí)例，該類型是 socket.socket 的子類型，它將下層的套接字包裝在一個(gè) SSL 上下文中。 sock 必須是一個(gè) SOCK_STREAM 套接字；其他套接字類型不被支持。

在內(nèi)部，該函數(shù)會(huì)創(chuàng)建一個(gè) SSLContext，其協(xié)議版本為 ssl_version 且 SSLContext.options 設(shè)為 cert_reqs。 如果設(shè)置了 keyfile, certfile, ca_certs 或 ciphers 等形參，則參數(shù)值會(huì)被傳給 SSLContext.load_cert_chain(), SSLContext.load_verify_locations() 以及 SSLContext.set_ciphers()。

參數(shù) server_side, do_handshake_on_connect 和 suppress_ragged_eofs 具有與 SSLContext.wrap_socket() 相同的含義。

3.7 版后已移除: 從 Python 3.2 和 2.7.9 開始，建議使用 SSLContext.wrap_socket() 來(lái)代替 wrap_socket()。 模塊級(jí)函數(shù)的功能受限并且將創(chuàng)建不安全的客戶端套接字，不帶服務(wù)器名稱提示或主機(jī)名匹配。

常量

所有常量現(xiàn)在都是 enum.IntEnum 或 enum.IntFlag 多項(xiàng)集的成員。

3.6 新版功能.

ssl.CERT_NONE

SSLContext.verify_mode 或 wrap_socket() 的 cert_reqs 形參可能的取值。 PROTOCOL_TLS_CLIENT 除外，這是默認(rèn)的模式。 對(duì)于客戶端套接字，幾乎任何證書都是可接受的。 驗(yàn)證錯(cuò)誤例如不受信任或過(guò)期的證書錯(cuò)誤會(huì)被忽略并且不會(huì)中止 TLS/SSL 握手。

在服務(wù)器模式下，不會(huì)從客戶端請(qǐng)求任何證書，因此客戶端不會(huì)發(fā)送任何用于客戶端證書身份驗(yàn)證的證書。

參見(jiàn)下文對(duì)于 安全考量 的討論。

ssl.CERT_OPTIONAL

SSLContext.verify_mode 或 wrap_socket() 的 cert_reqs 形參可能的取值。 CERT_OPTIONAL 具有與 CERT_REQUIRED 相同的含義。 對(duì)于客戶端套接字推薦改用 CERT_REQUIRED。

在服務(wù)器模式下，客戶端證書請(qǐng)求會(huì)被發(fā)送給客戶端。 客戶端可以忽略請(qǐng)求也可以發(fā)送一個(gè)證書以執(zhí)行 TLS 客戶端證書身份驗(yàn)證。 如果客戶端選擇發(fā)送證書，則將對(duì)其執(zhí)行驗(yàn)證。 任何驗(yàn)證錯(cuò)誤都將立即中止 TLS 握手。

使用此設(shè)置要求將一組有效的 CA 證書傳遞給 SSLContext.load_verify_locations() 或是作為 wrap_socket() 的 ca_certs 形參值。

ssl.CERT_REQUIRED

SSLContext.verify_mode 或 wrap_socket() 的 cert_reqs 形參可能的取值。 在此模式下，需要從套接字連接的另一端獲取證書；如果未提供證書或驗(yàn)證失敗則將引發(fā) SSLError。 此模式 不能 在客戶端模式下對(duì)證書進(jìn)行驗(yàn)證，因?yàn)樗粫?huì)匹配主機(jī)名。 check_hostname 也必須被啟用以驗(yàn)證證書的真實(shí)性。 PROTOCOL_TLS_CLIENT 會(huì)使用 CERT_REQUIRED 并默認(rèn)啟用 check_hostname。

對(duì)于服務(wù)器套接字，此模式會(huì)提供強(qiáng)制性的 TLS 客戶端證書驗(yàn)證。 客戶端證書請(qǐng)求會(huì)被發(fā)送給客戶端并且客戶端必須提供有效且受信任的證書。

使用此設(shè)置要求將一組有效的 CA 證書傳遞給 SSLContext.load_verify_locations() 或是作為 wrap_socket() 的 ca_certs 形參值。

class ssl.VerifyMode

CERT_* 常量的 enum.IntEnum 多項(xiàng)集。

3.6 新版功能.

ssl.VERIFY_DEFAULT

SSLContext.verify_flags 可能的取值。 在此模式下，證書吊銷列表（CRL）并不會(huì)被檢查。 OpenSSL 默認(rèn)不要求也不驗(yàn)證 CRL。

3.4 新版功能.

ssl.VERIFY_CRL_CHECK_LEAF

SSLContext.verify_flags 可能的取值。 在此模式下， 只會(huì)檢查對(duì)等證書而不檢查任何中間 CA 證書。 此模式要求提供由對(duì)等證書頒發(fā)者（其直接上級(jí) CA）簽名的有效 CRL。 如果未使用 SSLContext.load_verify_locations 加載正確的 CRL，則驗(yàn)證將失敗。

3.4 新版功能.

ssl.VERIFY_CRL_CHECK_CHAIN

SSLContext.verify_flags 可能的取值。 在此模式下，會(huì)檢查對(duì)等證書鏈中所有證書的 CRL。

3.4 新版功能.

ssl.VERIFY_X509_STRICT

SSLContext.verify_flags 可能的取值，用于禁用已損壞 X.509 證書的繞過(guò)操作。

3.4 新版功能.

ssl.VERIFY_ALLOW_PROXY_CERTS

SSLContext.verify_flags 的可能取值，啟用代理證書驗(yàn)證。

3.10 新版功能.

ssl.VERIFY_X509_TRUSTED_FIRST

SSLContext.verify_flags 可能的取值。 它指示 OpenSSL 在構(gòu)建用于驗(yàn)證某個(gè)證書的信任鏈時(shí)首選受信任的證書。 此旗標(biāo)將默認(rèn)被啟用。

3.4.4 新版功能.

ssl.VERIFY_X509_PARTIAL_CHAIN

SSLContext.verify_flags 的可能取值。它指示 OpenSSL 接受信任存儲(chǔ)中的中間 CA 作為信任錨，與自我簽名的根 CA 證書的方式相同。這樣就能信任中間 CA 頒發(fā)的證書，而不一定非要去信任其祖先的根 CA。

3.10 新版功能.

class ssl.VerifyFlags

VERIFY_* 常量的 enum.IntFlag 多項(xiàng)集。

3.6 新版功能.

ssl.PROTOCOL_TLS

選擇客戶端和服務(wù)器均支持的最高協(xié)議版本。 此選項(xiàng)名稱并不準(zhǔn)確，實(shí)際上 “SSL” 和 “TLS” 協(xié)議均可被選擇。

3.6 新版功能.

3.10 版后已移除: TLS 客戶端和服務(wù)器需要不同的默認(rèn)設(shè)置來(lái)實(shí)現(xiàn)安全通信。通用的 TLS 協(xié)議常量已廢棄，而采用 PROTOCOL_TLS_CLIENT 和 PROTOCOL_TLS_SERVER。

ssl.PROTOCOL_TLS_CLIENT

自動(dòng)協(xié)商為客戶端和服務(wù)器都支持的最高版本協(xié)議，并配置當(dāng)前上下文客戶端的連接。該協(xié)議默認(rèn)啟用 CERT_REQUIRED 和 check_hostname。

3.6 新版功能.

ssl.PROTOCOL_TLS_SERVER

自動(dòng)協(xié)商為客戶端和服務(wù)器都支持的最高版本協(xié)議，并配置上下文服務(wù)器端的連接。

3.6 新版功能.

ssl.PROTOCOL_SSLv23

PROTOCOL_TLS 的別名。

3.6 版后已移除: 請(qǐng)改用 PROTOCOL_TLS。

ssl.PROTOCOL_SSLv2

選擇 SSL 版本 2 作為通道加密協(xié)議。

如果OpenSSL是用``no-ssl2``選項(xiàng)編譯的，則該協(xié)議不可用。

警告

SSL 版本 2 并不安全。 極不建議使用它。

3.6 版后已移除: OpenSSL 已經(jīng)移除了對(duì) SSLv2 的支持。

ssl.PROTOCOL_SSLv3

選擇 SSL 版本 3 作為通道加密協(xié)議。

如果OpenSSL是用``no-ssl3``選項(xiàng)編譯的，則該協(xié)議不可用。

警告

SSL 版本 3 并不安全。 極不建議使用它。

3.6 版后已移除: OpenSSL 已經(jīng)廢棄了所有特定于版本的協(xié)議。請(qǐng)換用帶有 SSLContext.minimum_version 和 SSLContext.maximum_version 的默認(rèn)協(xié)議 PROTOCOL_TLS_SERVER 或 PROTOCOL_TLS_CLIENT 。

ssl.PROTOCOL_TLSv1

選擇 TLS 版本 1.0 作為通道加密協(xié)議。

3.6 版后已移除: OpenSSL 已經(jīng)廢棄了所有特定于版本的協(xié)議。

ssl.PROTOCOL_TLSv1_1

選擇 TLS 版本 1.1 作為通道加密協(xié)議。 僅適用于 openssl 版本 1.0.1+。

3.4 新版功能.

3.6 版后已移除: OpenSSL 已經(jīng)廢棄了所有特定于版本的協(xié)議。

ssl.PROTOCOL_TLSv1_2

選用 TLS 1.2 版本作為隧道加密協(xié)議。只適用于 openssl 1.0.1 以上版本。

3.4 新版功能.

3.6 版后已移除: OpenSSL 已經(jīng)廢棄了所有特定于版本的協(xié)議。

ssl.OP_ALL

對(duì)存在于其他 SSL 實(shí)現(xiàn)中的各種缺陷啟用繞過(guò)操作。 默認(rèn)會(huì)設(shè)置此選項(xiàng)。 沒(méi)有必要設(shè)置與 OpenSSL 的 SSL_OP_ALL 常量同名的旗標(biāo)。

3.2 新版功能.

ssl.OP_NO_SSLv2

阻止 SSLv2 連接。 此選項(xiàng)僅可與 PROTOCOL_TLS 結(jié)合使用。 它會(huì)阻止對(duì)等方選擇 SSLv2 作為協(xié)議版本。

3.2 新版功能.

3.6 版后已移除: SSLv2 已被棄用

ssl.OP_NO_SSLv3

阻止 SSLv3 連接。 此選項(xiàng)僅可與 PROTOCOL_TLS 結(jié)合使用。 它會(huì)阻止對(duì)等方選擇 SSLv3 作為協(xié)議版本。

3.2 新版功能.

3.6 版后已移除: SSLv3 已被棄用

ssl.OP_NO_TLSv1

阻止 TLSv1 連接。 此選項(xiàng)僅可與 PROTOCOL_TLS 結(jié)合使用。 它會(huì)阻止對(duì)等方選擇 TLSv1 作為協(xié)議版本。

3.2 新版功能.

3.7 版后已移除: 此選項(xiàng)自 OpenSSL 1.1.0 起已被棄用，請(qǐng)改用新的 SSLContext.minimum_version 和 SSLContext.maximum_version。

ssl.OP_NO_TLSv1_1

阻止 TLSv1.1 連接。 此選項(xiàng)僅可與 PROTOCOL_TLS 結(jié)合使用。 它會(huì)阻止對(duì)等方選擇 TLSv1.1 作為協(xié)議版本。 僅適用于 openssl 版本 1.0.1+。

3.4 新版功能.

3.7 版后已移除: 此選項(xiàng)自 OpenSSL 1.1.0 起已被棄用。

ssl.OP_NO_TLSv1_2

阻止 TLSv1.2 連接。 此選項(xiàng)僅可與 PROTOCOL_TLS 結(jié)合使用。 它會(huì)阻止對(duì)等方選擇 TLSv1.2 作為協(xié)議版本。 僅適用于 openssl 版本 1.0.1+。

3.4 新版功能.

3.7 版后已移除: 此選項(xiàng)自 OpenSSL 1.1.0 起已被棄用。

ssl.OP_NO_TLSv1_3

阻止 TLSv1.3 連接。 此選項(xiàng)僅可與 PROTOCOL_TLS 結(jié)合使用。 它會(huì)阻止對(duì)等方選擇 TLSv1.3 作為協(xié)議版本。 TLS 1.3 適用于 OpenSSL 1.1.1 或更新的版本。 當(dāng) Python 編譯是基于較舊版本的 OpenSSL 時(shí)，該旗標(biāo)默認(rèn)為 0。

3.7 新版功能.

3.7 版后已移除: 此選項(xiàng)自 OpenSSL 1.1.0 起已被棄用。 它被添加到 2.7.15, 3.6.3 和 3.7.0 是為了向下兼容 OpenSSL 1.0.2。

ssl.OP_NO_RENEGOTIATION

禁用所有 TLSv1.2 和更早版本的重協(xié)商操作。 不發(fā)送 HelloRequest 消息，并忽略通過(guò) ClientHello 發(fā)起的重協(xié)商請(qǐng)求。

此選項(xiàng)僅適用于 OpenSSL 1.1.0h 及更新的版本。

3.7 新版功能.

ssl.OP_CIPHER_SERVER_PREFERENCE

使用服務(wù)器的密碼順序首選項(xiàng)，而不是客戶端的首選項(xiàng)。 此選項(xiàng)在客戶端套接字和 SSLv2 服務(wù)器套接字上無(wú)效。

3.3 新版功能.

ssl.OP_SINGLE_DH_USE

阻止對(duì)于單獨(dú)的 SSL 會(huì)話重用相同的 DH 密鑰。 這會(huì)提升前向保密性但需要更多的計(jì)算資源。 此選項(xiàng)僅適用于服務(wù)器套接字。

3.3 新版功能.

ssl.OP_SINGLE_ECDH_USE

阻止對(duì)于單獨(dú)的 SSL 會(huì)話重用相同的 ECDH 密鑰。 這會(huì)提升前向保密性但需要更多的計(jì)算資源。 此選項(xiàng)僅適用于服務(wù)器套接字。

3.3 新版功能.

ssl.OP_ENABLE_MIDDLEBOX_COMPAT

在 TLS 1.3 握手中發(fā)送虛擬更改密碼規(guī)格（CCS）消息以使得 TLS 1.3 連接看起來(lái)更像是 TLS 1.2 連接。

此選項(xiàng)僅適用于 OpenSSL 1.1.1 及更新的版本。

3.8 新版功能.

ssl.OP_NO_COMPRESSION

在 SSL 通道上禁用壓縮。 這適用于應(yīng)用協(xié)議支持自己的壓縮方案的情況。

3.3 新版功能.

class ssl.Options

OP_* 常量的 enum.IntFlag 多項(xiàng)集。

ssl.OP_NO_TICKET

阻止客戶端請(qǐng)求會(huì)話憑據(jù)。

3.6 新版功能.

ssl.OP_IGNORE_UNEXPECTED_EOF

忽略 TLS 連接的意外關(guān)閉。

此選項(xiàng)僅適用于 OpenSSL 3.0.0 及更新的版本。

3.10 新版功能.

ssl.HAS_ALPN

OpenSSL 庫(kù)是否具有對(duì) RFC 7301 中描述的 應(yīng)用層協(xié)議協(xié)商 TLS 擴(kuò)展的內(nèi)置支持。

3.5 新版功能.

ssl.HAS_NEVER_CHECK_COMMON_NAME

OpenSSL 庫(kù)是否具有對(duì)不檢測(cè)目標(biāo)通用名稱的內(nèi)置支持且 SSLContext.hostname_checks_common_name 為可寫狀態(tài)。

3.7 新版功能.

ssl.HAS_ECDH

OpenSSL 庫(kù)是否具有對(duì)基于橢圓曲線的 Diffie-Hellman 密鑰交換的內(nèi)置支持。 此常量應(yīng)當(dāng)為真值，除非發(fā)布者明確地禁用了此功能。

3.3 新版功能.

ssl.HAS_SNI

OpenSSL 庫(kù)是否具有對(duì) 服務(wù)器名稱提示 擴(kuò)展（在 RFC 6066 中定義）的內(nèi)置支持。

3.2 新版功能.

ssl.HAS_NPN

OpenSSL 庫(kù)是否具有對(duì) 應(yīng)用層協(xié)議協(xié)商 中描述的 下一協(xié)議協(xié)商 的內(nèi)置支持。 當(dāng)此常量為真值時(shí)，你可以使用 SSLContext.set_npn_protocols() 方法來(lái)公告你想要支持的協(xié)議。

3.3 新版功能.

ssl.HAS_SSLv2

OpenSSL 庫(kù)是否具有對(duì) SSL 2.0 協(xié)議的內(nèi)置支持。

3.7 新版功能.

ssl.HAS_SSLv3

OpenSSL 庫(kù)是否具有對(duì) SSL 3.0 協(xié)議的內(nèi)置支持。

3.7 新版功能.

ssl.HAS_TLSv1

OpenSSL 庫(kù)是否具有對(duì) TLS 1.0 協(xié)議的內(nèi)置支持。

3.7 新版功能.

ssl.HAS_TLSv1_1

OpenSSL 庫(kù)是否具有對(duì) TLS 1.1 協(xié)議的內(nèi)置支持。

3.7 新版功能.

ssl.HAS_TLSv1_2

OpenSSL 庫(kù)是否具有對(duì) TLS 1.2 協(xié)議的內(nèi)置支持。

3.7 新版功能.

ssl.HAS_TLSv1_3

OpenSSL 庫(kù)是否具有對(duì) TLS 1.3 協(xié)議的內(nèi)置支持。

3.7 新版功能.

ssl.CHANNEL_BINDING_TYPES

受支持的 TLS 通道綁定類型組成的列表。 此列表中的字符串可被用作傳給 SSLSocket.get_channel_binding() 的參數(shù)。

3.3 新版功能.

ssl.OPENSSL_VERSION

解釋器所加載的 OpenSSL 庫(kù)的版本字符串:

 
 
 
 
  
  
  
  
>>> ssl.OPENSSL_VERSION
  
  
  
  
'OpenSSL 1.0.2k 26 Jan 2017'
 
 
 

3.2 新版功能.

ssl.OPENSSL_VERSION_INFO

代表 OpenSSL 庫(kù)的版本信息的五個(gè)整數(shù)所組成的元組:

 
 
 
 
  
  
  
  
>>> ssl.OPENSSL_VERSION_INFO
  
  
  
  
(1, 0, 2, 11, 15)
 
 
 

3.2 新版功能.

ssl.OPENSSL_VERSION_NUMBER

OpenSSL 庫(kù)的原始版本號(hào)，以單個(gè)整數(shù)表示:

 
 
 
 
  
  
  
  
>>> ssl.OPENSSL_VERSION_NUMBER
  
  
  
  
268443839
  
  
  
  
>>> hex(ssl.OPENSSL_VERSION_NUMBER)
  
  
  
  
'0x100020bf'
 
 
 

3.2 新版功能.

ssl.ALERT_DESCRIPTION_HANDSHAKE_FAILURE

ssl.ALERT_DESCRIPTION_INTERNAL_ERROR

ALERT_DESCRIPTION_*

來(lái)自 RFC 5246 等文檔的警報(bào)描述。 IANA TLS Alert Registry 中包含了這個(gè)列表及對(duì)定義其含義的 RFC 引用。

被用作 SSLContext.set_servername_callback() 中的回調(diào)函數(shù)的返回值。

3.4 新版功能.

class ssl.AlertDescription

ALERT_DESCRIPTION_* 常量的 enum.IntEnum 多項(xiàng)集。

3.6 新版功能.

Purpose.SERVER_AUTH

用于 create_default_context() 和 SSLContext.load_default_certs() 的參數(shù)。表示上下文可用于驗(yàn)證網(wǎng)絡(luò)服務(wù)器（因此，它將被用于創(chuàng)建客戶端套接字）。

3.4 新版功能.

Purpose.CLIENT_AUTH

用于 create_default_context() 和 SSLContext.load_default_certs() 的參數(shù)。 表示上下文可用于驗(yàn)證網(wǎng)絡(luò)客戶（因此，它將被用于創(chuàng)建服務(wù)器端套接字）。

3.4 新版功能.

class ssl.SSLErrorNumber

SSL_ERROR_* 常量的 enum.IntEnum 多項(xiàng)集。

3.6 新版功能.

class ssl.TLSVersion

SSLContext.maximum_version 和 SSLContext.minimum_version 中的 SSL 和 TLS 版本的 enum.IntEnum 多項(xiàng)集。

3.7 新版功能.

TLSVersion.MINIMUM_SUPPORTED

TLSVersion.MAXIMUM_SUPPORTED

受支持的最低和最高 SSL 或 TLS 版本。 這些常量被稱為魔術(shù)常量。 它們的值并不反映可用的最低和最高 TLS/SSL 版本。

TLSVersion.SSLv3

TLSVersion.TLSv1

TLSVersion.TLSv1_1

TLSVersion.TLSv1_2

TLSVersion.TLSv1_3

SSL 3.0 至 TLS 1.3。

3.10 版后已移除: 所有 TLSVersion 成員，除 TLSVersion.TLSv1_2 和 TLSVersion.TLSv1_3 之外均已廢棄。

SSL 套接字

class ssl.SSLSocket(socket.socket)

SSL 套接字提供了 套接字對(duì)象 的下列方法:

• accept()

• bind()

• close()

• connect()

• detach()

• fileno()

• getpeername(), getsockname()

• getsockopt(), setsockopt()

• gettimeout(), settimeout(), setblocking()

• listen()

• makefile()

• recv(), recv_into() (but passing a non-zero flags argument is not allowed)

• send(), sendall() (with the same limitation)

• sendfile() (but os.sendfile will be used for plain-text sockets only, else send() will be used)

• shutdown()

但是，由于 SSL（和 TLS）協(xié)議在 TCP 之上具有自己的框架，因此 SSL 套接字抽象在某些方面可能與常規(guī)的 OS 層級(jí)套接字存在差異。 特別是要查看 非阻塞型套接字說(shuō)明。

SSLSocket 的實(shí)例必須使用 SSLContext.wrap_socket() 方法來(lái)創(chuàng)建。

在 3.5 版更改: 新增了 sendfile() 方法。

在 3.5 版更改: shutdown() 不會(huì)在每次接收或發(fā)送字節(jié)數(shù)據(jù)后重置套接字超時(shí)。 現(xiàn)在套接字超時(shí)為關(guān)閉的最大總持續(xù)時(shí)間。

3.6 版后已移除: 直接創(chuàng)建 SSLSocket 實(shí)例的做法已被棄用，請(qǐng)使用 SSLContext.wrap_socket() 來(lái)包裝套接字。

在 3.7 版更改: SSLSocket 的實(shí)例必須使用 wrap_socket() 來(lái)創(chuàng)建。 在較早的版本中，直接創(chuàng)建實(shí)例是可能的。 但這從未被記入文檔或是被正式支持。

在 3.10 版更改: Python 內(nèi)部現(xiàn)在使用 SSL_read_ex 和 SSL_write_ex。這些函數(shù)支持讀取和寫入大于 2GB 的數(shù)據(jù)。寫入零長(zhǎng)數(shù)據(jù)不再出現(xiàn)違反協(xié)議的錯(cuò)誤。

SSL 套接字還具有下列方法和屬性:

SSLSocket.read(len=1024, buffer=None)

從 SSL 套接字讀取至多 len 個(gè)字節(jié)的數(shù)據(jù)并將結(jié)果作為 bytes 實(shí)例返回。 如果指定了 buffer，則改為讀取到緩沖區(qū)，并返回所讀取的字節(jié)數(shù)。

如果套接字為 非阻塞型 則會(huì)引發(fā) SSLWantReadError 或 SSLWantWriteError 且讀取將阻塞。

由于在任何時(shí)候重新協(xié)商都是可能的，因此調(diào)用 read() 也可能導(dǎo)致寫入操作。

在 3.5 版更改: 套接字超時(shí)在每次接收或發(fā)送字節(jié)數(shù)據(jù)后不會(huì)再被重置。 現(xiàn)在套接字超時(shí)為讀取至多 len 個(gè)字節(jié)數(shù)據(jù)的最大總持續(xù)時(shí)間。

3.6 版后已移除: 請(qǐng)使用 recv() 來(lái)代替 read()。

SSLSocket.write(buf)

將 buf 寫入到 SSL 套接字并返回所寫入的字節(jié)數(shù)。 buf 參數(shù)必須為支持緩沖區(qū)接口的對(duì)象。

如果套接字為 非阻塞型 則會(huì)引發(fā) SSLWantReadError 或 SSLWantWriteError 且讀取將阻塞。

由于在任何時(shí)候重新協(xié)商都是可能的，因此調(diào)用 write() 也可能導(dǎo)致讀取操作。

在 3.5 版更改: 套接字超時(shí)在每次接收或發(fā)送字節(jié)數(shù)據(jù)后不會(huì)再被重置。 現(xiàn)在套接字超時(shí)為寫入 buf 的最大總持續(xù)時(shí)間。

3.6 版后已移除: 請(qǐng)使用 send() 來(lái)代替 write()。

備注

read() 和 write() 方法是讀寫未加密的應(yīng)用級(jí)數(shù)據(jù)，并將其解密/加密為帶加密的線路級(jí)數(shù)據(jù)的低層級(jí)方法。 這些方法需要有激活的 SSL 連接，即握手已完成而 SSLSocket.unwrap() 尚未被調(diào)用。

通常你應(yīng)當(dāng)使用套接字 API 方法例如 recv() 和 send() 來(lái)代替這些方法。

SSLSocket.do_handshake()

執(zhí)行 SSL 設(shè)置握手。

在 3.4 版更改: 當(dāng)套接字的 context 的 check_hostname 屬性為真值時(shí)此握手方法還會(huì)執(zhí)行 match_hostname()。

在 3.5 版更改: 套接字超時(shí)在每次接收或發(fā)送字節(jié)數(shù)據(jù)時(shí)不會(huì)再被重置。 現(xiàn)在套接字超時(shí)為握手的最大總持續(xù)時(shí)間。

在 3.7 版更改: 主機(jī)名或 IP 地址會(huì)在握手期間由 OpenSSL 進(jìn)行匹配。 函數(shù) match_hostname() 將不再被使用。 在 OpenSSL 拒絕主機(jī)名和 IP 地址的情況下，握手將提前被中止并向?qū)Φ确桨l(fā)送 TLS 警告消息。

SSLSocket.getpeercert(binary_form=False)

如果連接另一端的對(duì)等方?jīng)]有證書，則返回 None。 如果 SSL 握手還未完成，則會(huì)引發(fā) ValueError。

如果 binary_form 形參為 False，并且從對(duì)等方接收到了證書，此方法將返回一個(gè) dict 實(shí)例。 如果證書未通過(guò)驗(yàn)證，則字典將為空。 如果證書通過(guò)驗(yàn)證，它將返回由多個(gè)密鑰組成的字典，其中包括 subject (證書頒發(fā)給的主體) 和 issuer (頒發(fā)證書的主體)。 如果證書包含一個(gè) Subject Alternative Name 擴(kuò)展的實(shí)例 (see RFC 3280)，則字典中還將有一個(gè) subjectAltName 鍵。

subject 和 issuer 字段都是包含在證書中相應(yīng)字段的數(shù)據(jù)結(jié)構(gòu)中給出的相對(duì)專有名稱（RDN）序列的元組，每個(gè) RDN 均為 name-value 對(duì)的序列。 這里是一個(gè)實(shí)際的示例:

 
 
 
 
  
  
  
  
{'issuer': ((('countryName', 'IL'),),
  
  
  
  
 (('organizationName', 'StartCom Ltd.'),),
  
  
  
  
 (('organizationalUnitName',
  
  
  
  
 'Secure Digital Certificate Signing'),),
  
  
  
  
 (('commonName',
  
  
  
  
 'StartCom Class 2 Primary Intermediate Server CA'),)),
  
  
  
  
 'notAfter': 'Nov 22 08:15:19 2013 GMT',
  
  
  
  
 'notBefore': 'Nov 21 03:09:52 2011 GMT',
  
  
  
  
 'serialNumber': '95F0',
  
  
  
  
 'subject': ((('description', '571208-SLe257oHY9fVQ07Z'),),
  
  
  
  
 (('countryName', 'US'),),
  
  
  
  
 (('stateOrProvinceName', 'California'),),
  
  
  
  
 (('localityName', 'San Francisco'),),
  
  
  
  
 (('organizationName', 'Electronic Frontier Foundation, Inc.'),),
  
  
  
  
 (('commonName', '*.eff.org'),),
  
  
  
  
 (('emailAddress', 'hostmaster@eff.org'),)),
  
  
  
  
 'subjectAltName': (('DNS', '*.eff.org'), ('DNS', 'eff.org')),
  
  
  
  
 'version': 3}
 
 
 

備注

要驗(yàn)證特定服務(wù)的證書，你可以使用 match_hostname() 函數(shù)。

如果 binary_form 形參為 True，并且提供了證書，此方法會(huì)將整個(gè)證書的 DER 編碼形式作為字節(jié)序列返回，或者如果對(duì)等方未提供證書則返回 None。 對(duì)等方是否提供證書取決于 SSL 套接字的角色:

• 對(duì)于客戶端 SSL 套接字，服務(wù)器將總是提供證書，無(wú)論是否需要進(jìn)行驗(yàn)證;

• 對(duì)于服務(wù)器 SSL 套接字，客戶端將僅在服務(wù)器要求時(shí)才提供證書；因此如果你使用了 CERT_NONE (而不是 CERT_OPTIONAL 或 CERT_REQUIRED) 則 getpeercert() 將返回 None。

在 3.2 版更改: 返回的字典包括額外的條目例如 issuer 和 notBefore。

在 3.4 版更改: 如果握手未完成則會(huì)引發(fā) ValueError。 返回的字典包括額外的 X509v3 擴(kuò)展條目例如 crlDistributionPoints, caIssuers 和 OCSP URI。

在 3.9 版更改: IPv6 地址字符串不再附帶末尾換行符。

SSLSocket.cipher()

返回由三個(gè)值組成的元組，其中包含所使用的密碼名稱，定義其使用方式的 SSL 協(xié)議版本，以及所使用的加密比特位數(shù)。 如果尚未建立連接，則返回 None。

SSLSocket.shared_ciphers()

返回在握手期間由客戶端共享的密碼列表。 所返回列表的每個(gè)條目都是由三個(gè)值組成的元組，其中包括密碼名稱，定義其使用方式的 SSL 協(xié)議版本，以及密碼所使用的加密比特位數(shù)。 如果尚未建立連接或套接字為客戶端套接字則 shared_ciphers() 將返回 None。

3.5 新版功能.

SSLSocket.compression()

以字符串形式返回所使用的壓縮算法，或者如果連接沒(méi)有使用壓縮則返回 None。

如果高層級(jí)的協(xié)議支持自己的壓縮機(jī)制，你可以使用 OP_NO_COMPRESSION 來(lái)禁用 SSL 層級(jí)的壓縮。

3.3 新版功能.

SSLSocket.get_channel_binding(cb_type=’tls-unique’)

為當(dāng)前連接獲取字節(jié)串形式的通道綁定數(shù)據(jù)。 如果尚未連接或握手尚未完成則返回 None。

cb_type 形參允許選擇需要的通道綁定類型。 有效的通道綁定類型在 CHANNEL_BINDING_TYPES 列表中列出。 目前只支持由 RFC 5929 所定義的 ‘tls-unique’ 通道綁定。 如果請(qǐng)求了一個(gè)不受支持的通道綁定類型則將引發(fā) ValueError。

3.3 新版功能.

SSLSocket.selected_alpn_protocol()

返回在 TLS 握手期間所選擇的協(xié)議。 如果 SSLContext.set_alpn_protocols() 未被調(diào)用，如果另一方不支持 ALPN，如果此套接字不支持任何客戶端所用的協(xié)議，或者如果握手尚未發(fā)生，則將返回 None。

3.5 新版功能.

SSLSocket.selected_npn_protocol()

返回在Return the higher-level protocol that was selected during the TLS/SSL 握手期間所選擇的高層級(jí)協(xié)議。 如果 SSLContext.set_npn_protocols() 未被調(diào)用，或者如果另一方不支持 NPN，或者如果握手尚未發(fā)生，則將返回 None。

3.3 新版功能.

3.10 版后已移除: NPN 已被 ALPN 取代。

SSLSocket.unwrap()

執(zhí)行 SSL 關(guān)閉握手，這會(huì)從下層的套接字中移除 TLS 層，并返回下層的套接字對(duì)象。 這可被用來(lái)通過(guò)一個(gè)連接將加密操作轉(zhuǎn)為非加密。 返回的套接字應(yīng)當(dāng)總是被用于同連接另一方的進(jìn)一步通信，而不是原始的套接字。

SSLSocket.verify_client_post_handshake()

向一個(gè) TLS 1.3 客戶端請(qǐng)求握手后身份驗(yàn)證（PHA）。 只有在初始 TLS 握手之后且雙方都啟用了 PHA 的情況下才能為服務(wù)器端套接字的 TLS 1.3 連接啟用 PHA，參見(jiàn) SSLContext.post_handshake_auth。

此方法不會(huì)立即執(zhí)行證書交換。 服務(wù)器端會(huì)在下一次寫入事件期間發(fā)送 CertificateRequest 并期待客戶端在下一次讀取事件期間附帶證書進(jìn)行響應(yīng)。

如果有任何前置條件未被滿足（例如非 TLS 1.3，PHA 未啟用），則會(huì)引發(fā) SSLError。

備注

僅在 OpenSSL 1.1.1 且 TLS 1.3 被啟用時(shí)可用。 沒(méi)有 TLS 1.3 支持，此方法將引發(fā) NotImplementedError。

3.8 新版功能.

SSLSocket.version()

以字符串形式返回由連接協(xié)商確定的實(shí)際 SSL 協(xié)議版本，或者如果未建立安全連接則返回 None。 在撰寫本文檔時(shí)，可能的返回值包括 "SSLv2", "SSLv3", "TLSv1", "TLSv1.1" 和 "TLSv1.2"。 最新的 OpenSSL 版本可能會(huì)定義更多的返回值。

3.5 新版功能.

SSLSocket.pending()

返回在連接上等待被讀取的已解密字節(jié)數(shù)。

SSLSocket.context

此 SSL 套接字所聯(lián)結(jié)的 SSLContext 對(duì)象。 如果 SSL 套接字是使用已棄用的 wrap_socket() 函數(shù) (而非 SSLContext.wrap_socket()) 創(chuàng)建的，則這將是為此 SSL 套接字創(chuàng)建的自定義上下文對(duì)象。

3.2 新版功能.

SSLSocket.server_side

一個(gè)布爾值，對(duì)于服務(wù)器端套接字為 True 而對(duì)于客戶端套接字則為 False。

3.2 新版功能.

SSLSocket.server_hostname

服務(wù)器的主機(jī)名: str 類型，對(duì)于服務(wù)器端套接字或者如果構(gòu)造器中未指定主機(jī)名則為 None。

3.2 新版功能.

在 3.7 版更改: 現(xiàn)在該屬性將始終為 ASCII 文本。 當(dāng) server_hostname 為一個(gè)國(guó)際化域名（IDN）時(shí)，該屬性現(xiàn)在會(huì)保存為 A 標(biāo)簽形式 ("xn--pythn-mua.org") 而非 U 標(biāo)簽形式 ("pyth?n.org")。

SSLSocket.session

用于 SSL 連接的 SSLSession。 該會(huì)話將在執(zhí)行 TLS 握手后對(duì)客戶端和服務(wù)器端套接字可用。 對(duì)于客戶端套接字該會(huì)話可以在調(diào)用 do_handshake() 之前被設(shè)置以重用一個(gè)會(huì)話。

3.6 新版功能.

SSLSocket.session_reused

3.6 新版功能.

SSL 上下文

3.2 新版功能.

SSL 上下文可保存各種比單獨(dú) SSL 連接壽命更長(zhǎng)的數(shù)據(jù)，例如 SSL 配置選項(xiàng)，證書和私鑰等。 它還可為服務(wù)器端套接字管理緩存，以加快來(lái)自相同客戶端的重復(fù)連接。

class ssl.SSLContext(protocol=None)

創(chuàng)建一個(gè)新的 SSL 上下文。 你可以傳入 protocol，它必須為此模塊中定義的 PROTOCOL_* 常量之一。 該形參指定要使用哪個(gè) SSL 協(xié)議版本。 通常，服務(wù)器會(huì)選擇一個(gè)特定的協(xié)議版本，而客戶端必須適應(yīng)服務(wù)器的選擇。 大多數(shù)版本都不能與其他版本互操作。 如果未指定，則默認(rèn)值為 PROTOCOL_TLS；它提供了與其他版本的最大兼容性。

這個(gè)表顯示了客戶端（橫向）的哪個(gè)版本能夠連接服務(wù)器（縱向）的哪個(gè)版本。

客戶端 / 服務(wù)器

SSLv2

SSLv3

TLS 3

TLSv1

TLSv1.1

TLSv1.2

SSLv2

是

否

否 1

否

否

否

SSLv3

否

是

否 2

否

否

否

TLS (SSLv23) 3

否 1

否 2

是

是

是

是

TLSv1

否

否

是

是

否

否

TLSv1.1

否

否

是

否

是

否

TLSv1.2

否

否

是

否

否

是

備注

• 1(1,2)

  SSLContext 默認(rèn)設(shè)置 OP_NO_SSLv2 以禁用 SSLv2。

  2(1,2)

  SSLContext 默認(rèn)設(shè)置 OP_NO_SSLv3 以禁用 SSLv3。

  3(1,2)

  TLS 1.3 協(xié)議在 OpenSSL >= 1.1.1 中設(shè)置 PROTOCOL_TLS 時(shí)可用。 沒(méi)有專門針對(duì) TLS 1.3 的 PROTOCOL 常量。

參見(jiàn)

create_default_context() 讓 ssl 為特定目標(biāo)選擇安全設(shè)置。

在 3.6 版更改: 上下文會(huì)使用安全默認(rèn)值來(lái)創(chuàng)建。 默認(rèn)設(shè)置的選項(xiàng)有 OP_NO_COMPRESSION, OP_CIPHER_SERVER_PREFERENCE, OP_SINGLE_DH_USE, OP_SINGLE_ECDH_USE, OP_NO_SSLv2 (except for PROTOCOL_SSLv2) 和 OP_NO_SSLv3 (except for PROTOCOL_SSLv3)。 初始密碼集列表只包含 HIGH 密碼，不包含 NULL 密碼和 MD5 密碼 (PROTOCOL_SSLv2 除外)。

3.10 版后已移除: 不帶協(xié)議參數(shù)的 SSLContext 已廢棄。將來(lái)，上下文類會(huì)要求使用 PROTOCOL_TLS_CLIENT 或 PROTOCOL_TLS_SERVER 協(xié)議。

在 3.10 版更改: 現(xiàn)在默認(rèn)的密碼套件只包含安全的 AES 和 ChaCha20 密碼，具有前向保密性和安全級(jí)別2。禁止使用少于 2048 位的 RSA 和 DH 密鑰以及少于 224 位的ECC密鑰。 PROTOCOL_TLS 、 PROTOCOL_TLS_CLIENT 和 PROTOCOL_TLS_SERVER 至少使用 TLS 1.2 版本。

SSLContext 對(duì)象具有以下方法和屬性:

SSLContext.cert_store_stats()

獲取以字典表示的有關(guān)已加載的 X.509 證書數(shù)量，被標(biāo)記為 CA 證書的 X.509 證書數(shù)量以及證書吊銷列表的統(tǒng)計(jì)信息。

具有一個(gè) CA 證書和一個(gè)其他證書的上下文示例:

 
 
 
 
  
  
  
  
>>> context.cert_store_stats()
  
  
  
  
{'crl': 0, 'x509_ca': 1, 'x509': 2}
 
 
 

3.4 新版功能.

SSLContext.load_cert_chain(certfile, keyfile=None, password=None)

加載一個(gè)私鑰及對(duì)應(yīng)的證書。 certfile 字符串必須為以 PEM 格式表示的單個(gè)文件路徑，該文件中包含證書以及確立證書真實(shí)性所需的任意數(shù)量的 CA 證書。 如果存在 keyfile 字符串，它必須指向一個(gè)包含私鑰的文件。 否則私鑰也將從 certfile 中提取。 請(qǐng)參閱 證書 中的討論來(lái)了解有關(guān)如何將證書存儲(chǔ)至 certfile 的更多信息。

password 參數(shù)可以是一個(gè)函數(shù)，調(diào)用時(shí)將得到用于解密私鑰的密碼。 它在私鑰被加密且需要密碼時(shí)才會(huì)被調(diào)用。 它調(diào)用時(shí)將不帶任何參數(shù)，并且應(yīng)當(dāng)返回一個(gè)字符串、字節(jié)串或字節(jié)數(shù)組。 如果返回值是一個(gè)字符串，在用它解密私鑰之前它將以 UTF-8 進(jìn)行編碼。 或者也可以直接將字符串、字節(jié)串或字節(jié)數(shù)組值作為 password 參數(shù)提供。 如果私鑰未被加密且不需要密碼則它將被忽略。

如果未指定 password 參數(shù)且需要一個(gè)密碼，將會(huì)使用 OpenSSL 內(nèi)置的密碼提示機(jī)制來(lái)交互式地提示用戶輸入密碼。

如果私鑰不能匹配證書則會(huì)引發(fā) SSLError。

在 3.3 版更改: 新增可選參數(shù) password。

SSLContext.load_default_certs(purpose=Purpose.SERVER_AUTH)

從默認(rèn)位置加載一組默認(rèn)的 “證書頒發(fā)機(jī)構(gòu)” (CA) 證書。 在 Windows 上它將從 CA 和 ROOT 系統(tǒng)存儲(chǔ)中加載 CA 證書。 在所有系統(tǒng)上它會(huì)調(diào)用 SSLContext.set_default_verify_paths() 。 將來(lái)該方法也可能會(huì)從其他位置加載 CA 證書。

purpose 旗標(biāo)指明要加載哪一類 CA 證書。 默認(rèn)設(shè)置 Purpose.SERVER_AUTH 加載被標(biāo)記且被信任用于 TLS Web 服務(wù)器驗(yàn)證（客戶端套接字）的證書。 Purpose.CLIENT_AUTH 則加載用于在服務(wù)器端進(jìn)行客戶端證書驗(yàn)證的 CA 證書。

3.4 新版功能.

SSLContext.load_verify_locations(cafile=None, capath=None, cadata=None)

當(dāng) verify_mode 不為 CERT_NONE 時(shí)加載一組用于驗(yàn)證其他對(duì)等方證書的 “證書頒發(fā)機(jī)構(gòu)” (CA) 證書。 必須至少指定 cafile 或 capath 中的一個(gè)。

此方法還可加載 PEM 或 DER 格式的證書吊銷列表 (CRL)，為此必須正確配置 SSLContext.verify_flags。

如果存在 cafile 字符串，它應(yīng)為 PEM 格式的級(jí)聯(lián) CA 證書文件的路徑。 請(qǐng)參閱 證書 中的討論來(lái)了解有關(guān)如何處理此文件中的證書的更多信息。

如果存在 capath 字符串，它應(yīng)為包含多個(gè) PEM 格式的 CA 證書的目錄的路徑，并遵循 OpenSSL 專屬布局。

如果存在 cadata 對(duì)象，它應(yīng)為一個(gè)或多個(gè) PEM 編碼的證書的 ASCII 字符串或者 DER 編碼的證書的 bytes-like object。 與 capath 一樣 PEM 編碼的證書之外的多余行會(huì)被忽略，但至少要有一個(gè)證書。

在 3.4 版更改: 新增可選參數(shù) cadata

SSLContext.get_ca_certs(binary_form=False)

獲取已離開法人 “證書頒發(fā)機(jī)構(gòu)” (CA) 證書列表。 如果 binary_form 形參為 False 則每個(gè)列表?xiàng)l目都是一個(gè)類似于 SSLSocket.getpeercert() 輸出的字典。 在其他情況下此方法將返回一個(gè) DER 編碼的證書的列表。 返回的列表不包含來(lái)自 capath 的證書，除非 SSL 連接請(qǐng)求并加載了一個(gè)證書。

備注

capath 目錄中的證書不會(huì)被加載，除非它們已至少被使用過(guò)一次。

3.4 新版功能.

SSLContext.get_ciphers()

獲取已啟用密碼的列表。 該列表將按密碼的優(yōu)先級(jí)排序。 參見(jiàn) SSLContext.set_ciphers()。

示例:

 
 
 
 
  
  
  
  
>>> ctx = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
  
  
  
  
>>> ctx.set_ciphers('ECDHE+AESGCM:!ECDSA')
  
  
  
  
>>> ctx.get_ciphers()
  
  
  
  
[{'aead': True,
  
  
  
  
 'alg_bits': 256,
  
  
  
  
 'auth': 'auth-rsa',
  
  
  
  
 'description': 'ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH Au=RSA '
  
  
  
  
 'Enc=AESGCM(256) Mac=AEAD',
  
  
  
  
 'digest': None,
  
  
  
  
 'id': 50380848,
  
  
  
  
 'kea': 'kx-ecdhe',
  
  
  
  
 'name': 'ECDHE-RSA-AES256-GCM                                                

                                                分享標(biāo)題：創(chuàng)新互聯(lián)Python教程：ssl —- 套接字對(duì)象的 TLS/SSL 包裝器                                                

                                                鏈接URL：http://m.5511xx.com/article/dhdhcsh.html