方法、常量和異常處理?

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

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

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

SSL 套接字?

class ssl.SSLSocket(socket.socket)?

SSL 套接字提供了 套接字對象 的下列方法:

• 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 套接字抽象在某些方面可能與常規的 OS 層級套接字存在差異。 特別是要查看 非阻塞型套接字說(shuō)明。

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

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

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

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

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

在 3.10 版更改: Python 內部現在使用 SSL_read_ex 和 SSL_write_ex。這些函數支持讀取和寫(xiě)入大于 2GB 的數據。寫(xiě)入零長(cháng)數據不再出現違反協(xié)議的錯誤。

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

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

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

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

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

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

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

SSLSocket.write(buf)?

將 buf 寫(xiě)入到 SSL 套接字并返回所寫(xiě)入的字節數。 buf 參數必須為支持緩沖區接口的對象。

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

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

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

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

SSLSocket.do_handshake()?

執行 SSL 設置握手。

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

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

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

SSLSocket.getpeercert(binary_form=False)?

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

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

subject 和 issuer 字段都是包含在證書(shū)中相應字段的數據結構中給出的相對專(zhuān)有名稱(chēng)（RDN）序列的元組，每個(gè) RDN 均為 name-value 對的序列。 這里是一個(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}

備注

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

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

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

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

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

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

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

SSLSocket.cipher()?

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

SSLSocket.shared_ciphers()?

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

3.5 新版功能.

SSLSocket.compression()?

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

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

3.3 新版功能.

SSLSocket.get_channel_binding(cb_type='tls-unique')?

為當前連接獲取字節串形式的通道綁定數據。 如果尚未連接或握手尚未完成則返回 None。

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

3.3 新版功能.

SSLSocket.selected_alpn_protocol()?

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

3.5 新版功能.

SSLSocket.selected_npn_protocol()?

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

3.3 新版功能.

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

SSLSocket.unwrap()?

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

SSLSocket.verify_client_post_handshake()?

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

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

如果有任何前置條件未被滿(mǎn)足（例如非 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()?

Return the actual SSL protocol version negotiated by the connection as a string, or None if no secure connection is established. As of this writing, possible return values include "SSLv2", "SSLv3", "TLSv1", "TLSv1.1" and "TLSv1.2". Recent OpenSSL versions may define more return values.

3.5 新版功能.

SSLSocket.pending()?

返回在連接上等待被讀取的已解密字節數。

SSLSocket.context?

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

3.2 新版功能.

SSLSocket.server_side?

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

3.2 新版功能.

SSLSocket.server_hostname?

服務(wù)器的主機名: str 類(lèi)型，對于服務(wù)器端套接字或者如果構造器中未指定主機名則為 None。

3.2 新版功能.

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

SSLSocket.session?

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

3.6 新版功能.

SSLSocket.session_reused?

3.6 新版功能.

SSL 上下文?

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

class ssl.SSLContext(protocol=None)?

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

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

客戶(hù)端 / 服務(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 默認設置 OP_NO_SSLv2 以禁用 SSLv2。

2(1,2)

SSLContext 默認設置 OP_NO_SSLv3 以禁用 SSLv3。

3(1,2)

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

參見(jiàn)

create_default_context() 讓 ssl 為特定目標選擇安全設置。

在 3.6 版更改: 上下文會(huì )使用安全默認值來(lái)創(chuà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é)議參數的 SSLContext 已廢棄。將來(lái)，上下文類(lèi)會(huì )要求使用 PROTOCOL_TLS_CLIENT 或 PROTOCOL_TLS_SERVER 協(xié)議。

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

SSLContext 對象具有以下方法和屬性:

SSLContext.cert_store_stats()?

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

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

>>>

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

3.4 新版功能.

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

Load a private key and the corresponding certificate. The certfile string must be the path to a single file in PEM format containing the certificate as well as any number of CA certificates needed to establish the certificate's authenticity. The keyfile string, if present, must point to a file containing the private key. Otherwise the private key will be taken from certfile as well. See the discussion of 證書(shū) for more information on how the certificate is stored in the certfile.

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

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

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

在 3.3 版更改: 新增可選參數 password。

SSLContext.load_default_certs(purpose=Purpose.SERVER_AUTH)?

Load a set of default "certification authority" (CA) certificates from default locations. On Windows it loads CA certs from the CA and ROOT system stores. On all systems it calls SSLContext.set_default_verify_paths(). In the future the method may load CA certificates from other locations, too.

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

3.4 新版功能.

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

當 verify_mode 不為 CERT_NONE 時(shí)加載一組用于驗證其他對等方證書(shū)的 "證書(shū)頒發(fā)機構" (CA) 證書(shū)。 必須至少指定 cafile 或 capath 中的一個(gè)。

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

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

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

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

在 3.4 版更改: 新增可選參數 cadata

SSLContext.get_ca_certs(binary_form=False)?

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

備注

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

3.4 新版功能.

SSLContext.get_ciphers()?

獲取已啟用密碼的列表。 該列表將按密碼的優(yōu)先級排序。 參見(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-SHA384',
  'protocol': 'TLSv1.2',
  'strength_bits': 256,
  'symmetric': 'aes-256-gcm'},
 {'aead': True,
  'alg_bits': 128,
  'auth': 'auth-rsa',
  'description': 'ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH     Au=RSA  '
                 'Enc=AESGCM(128) Mac=AEAD',
  'digest': None,
  'id': 50380847,
  'kea': 'kx-ecdhe',
  'name': 'ECDHE-RSA-AES128-GCM-SHA256',
  'protocol': 'TLSv1.2',
  'strength_bits': 128,
  'symmetric': 'aes-128-gcm'}]

3.6 新版功能.

SSLContext.set_default_verify_paths()?

從構建 OpenSSL 庫時(shí)定義的文件系統路徑中加載一組默認的 "證書(shū)頒發(fā)機構" (CA) 證書(shū)。 不幸的是，沒(méi)有一種簡(jiǎn)單的方式能知道此方法是否執行成功：如果未找到任何證書(shū)也不會(huì )返回錯誤。 不過(guò)，當 OpenSSL 庫是作為操作系統的一部分被提供時(shí)，它的配置應當是正確的。

SSLContext.set_ciphers(ciphers)?

為使用此上下文創(chuàng )建的套接字設置可用密碼。 它應當為 OpenSSL 密碼列表格式 的字符串。 如果沒(méi)有可被選擇的密碼（由于編譯時(shí)選項或其他配置禁止使用所指定的任何密碼），則將引發(fā) SSLError。

備注

在連接后，SSL 套接字的 SSLSocket.cipher() 方法將給出當前所選擇的密碼。

TLS 1.3 密碼套件不能通過(guò) set_ciphers() 禁用。

SSLContext.set_alpn_protocols(protocols)?

指定在 SSL/TLS 握手期間套接字應當通告的協(xié)議。 它應為由 ASCII 字符串組成的列表，例如 ['http/1.1', 'spdy/2']，按首選順序排列。 協(xié)議的選擇將在握手期間發(fā)生，并依據 RFC 7301 來(lái)執行。 在握手成功后，SSLSocket.selected_alpn_protocol() 方法將返回已達成一致的協(xié)議。

如果 HAS_ALPN 為 False 則此方法將引發(fā) NotImplementedError。

3.5 新版功能.

SSLContext.set_npn_protocols(protocols)?

指定在Specify which protocols the socket should advertise during the SSL/TLS 握手期間套接字應當通告的協(xié)議。 它應為由字符串組成的列表，例如 ['http/1.1', 'spdy/2']，按首選順序排列。 協(xié)議的選擇將在握手期間發(fā)生，并將依據 應用層協(xié)議協(xié)商 來(lái)執行。 在握手成功后，SSLSocket.selected_npn_protocol() 方法將返回已達成一致的協(xié)議。

如果 HAS_NPN 為 False 則此方法將引發(fā) NotImplementedError。

3.3 新版功能.

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

SSLContext.sni_callback?

注冊一個(gè)回調函數，當 TLS 客戶(hù)端指定了一個(gè)服務(wù)器名稱(chēng)提示時(shí)，該回調函數將在 SSL/TLS 服務(wù)器接收到 TLS Client Hello 握手消息后被調用。 服務(wù)器名稱(chēng)提示機制的定義見(jiàn) RFC 6066 section 3 - Server Name Indication。

每個(gè) SSLContext 只能設置一個(gè)回調。 如果 sni_callback 被設置為 None 則會(huì )禁用回調。 對該函數的后續調用將禁用之前注冊的回調。

此回調函數將附帶三個(gè)參數來(lái)調用；第一個(gè)參數是 ssl.SSLSocket，第二個(gè)參數是代表客戶(hù)端準備與之通信的服務(wù)器的字符串 (或者如果 TLS Client Hello 不包含服務(wù)器名稱(chēng)則為 None) 而第三個(gè)參數是原來(lái)的 SSLContext。 服務(wù)器名稱(chēng)參數為文本形式。 對于國際化域名，服務(wù)器名稱(chēng)是一個(gè) IDN A 標簽 ("xn--pythn-mua.org")。

此回調的一個(gè)典型用法是將 ssl.SSLSocket 的 SSLSocket.context 屬性修改為一個(gè) SSLContext 類(lèi)型的新對象，該對象代表與服務(wù)器相匹配的證書(shū)鏈。

Due to the early negotiation phase of the TLS connection, only limited methods and attributes are usable like SSLSocket.selected_alpn_protocol() and SSLSocket.context. The SSLSocket.getpeercert(), SSLSocket.cipher() and SSLSocket.compression() methods require that the TLS connection has progressed beyond the TLS Client Hello and therefore will not return meaningful values nor can they be called safely.

sni_callback 函數必須返回 None 以允許 TLS 協(xié)商繼續進(jìn)行。 如果想要 TLS 失敗，則可以返回常量 ALERT_DESCRIPTION_*。 其他返回值將導致 TLS 的致命錯誤 ALERT_DESCRIPTION_INTERNAL_ERROR。

如果從 sni_callback 函數引發(fā)了異常，則 TLS 連接將終止并發(fā)出 TLS 致命警告消息 ALERT_DESCRIPTION_HANDSHAKE_FAILURE。

如果 OpenSSL library 庫在構建時(shí)定義了 OPENSSL_NO_TLSEXT 則此方法將返回 NotImplementedError。

3.7 新版功能.

SSLContext.set_servername_callback(server_name_callback)?

這是被保留用于向下兼容的舊式 API。 在可能的情況下，你應當改用 sni_callback。 給出的 server_name_callback 類(lèi)似于 sni_callback，不同之處在于當服務(wù)器主機名是 IDN 編碼的國際化域名時(shí)，server_name_callback 會(huì )接收到一個(gè)已編碼的 U 標簽 ("pyth?n.org")。

如果發(fā)生了服務(wù)器名稱(chēng)解碼錯誤。 TLS 連接將終止并向客戶(hù)端發(fā)出 ALERT_DESCRIPTION_INTERNAL_ERROR 最嚴重 TLS 警告消息。

3.4 新版功能.

SSLContext.load_dh_params(dhfile)?

加載密鑰生成參數用于 Diffie-Hellman (DH) 密鑰交換。 使用 DH 密鑰交換能以消耗（服務(wù)器和客戶(hù)端的）計算資源為代價(jià)提升前向保密性。 dhfile 參數應當為指向一個(gè)包含 PEM 格式的 DH 形參的文件的路徑。

此設置不會(huì )應用于客戶(hù)端套接字。 你還可以使用 OP_SINGLE_DH_USE 選項來(lái)進(jìn)一步提升安全性。

3.3 新版功能.

SSLContext.set_ecdh_curve(curve_name)?

為基于橢圓曲線(xiàn)的 Elliptic Curve-based Diffie-Hellman (ECDH) 密鑰交換設置曲線(xiàn)名稱(chēng)。 ECDH 顯著(zhù)快于常規 DH 同時(shí)據信同樣安全。 curve_name 形參應為描述某個(gè)知名橢圓曲線(xiàn)的字符串，例如受到廣泛支持的曲線(xiàn) prime256v1。

此設置不會(huì )應用于客戶(hù)端套接字。 你還可以使用 OP_SINGLE_ECDH_USE 選項來(lái)進(jìn)一步提升安全性。

如果 HAS_ECDH 為 False 則此方法將不可用。

3.3 新版功能.

參見(jiàn)

SSL/TLS 與完美的前向保密性

Vincent Bernat。

SSLContext.wrap_socket(sock, server_side=False, do_handshake_on_connect=True, suppress_ragged_eofs=True, server_hostname=None, session=None)?

包裝一個(gè)現有的 Python 套接字 sock 并返回一個(gè) SSLContext.sslsocket_class 的實(shí)例 (默認為 SSLSocket)。 返回的 SSL 套接字會(huì )綁定上下文、設置以及證書(shū)。 sock 必須是一個(gè) SOCK_STREAM 套接字；其他套接字類(lèi)型不被支持。

形參 server_side 是一個(gè)布爾值，它標明希望從該套接字獲得服務(wù)器端行為還是客戶(hù)端行為。

對于客戶(hù)端套接字，上下文的構造會(huì )延遲執行；如果下層的套接字尚未連接，上下文的構造將在對套接字調用 connect() 之后執行。 對于服務(wù)器端套接字，如果套接字沒(méi)有遠端對等方，它會(huì )被視為一個(gè)監聽(tīng)套接字，并且服務(wù)器端 SSL 包裝操作會(huì )在通過(guò) accept() 方法所接受的客戶(hù)端連接上自動(dòng)執行。 此方法可能會(huì )引發(fā) SSLError。

在客戶(hù)端連接上，可選形參 server_hostname 指定所要連接的服務(wù)的主機名。 這允許單個(gè)服務(wù)器托管具有單獨證書(shū)的多個(gè)基于 SSL 的服務(wù)，很類(lèi)似于 HTTP 虛擬主機。 如果 server_side 為真值則指定 server_hostname 將引發(fā) ValueError。

形參 do_handshake_on_connect 指明是否要在調用 socket.connect() 之后自動(dòng)執行 SSL 握手，還是要通過(guò)發(fā)起調用 SSLSocket.do_handshake() 方法讓?xiě)贸绦蝻@式地調用它。 顯式地調用 SSLSocket.do_handshake() 可給予程序對握手中所涉及的套接字 I/O 阻塞行為的控制。

形參 suppress_ragged_eofs 指明 SSLSocket.recv() 方法應當如何從連接的另一端發(fā)送非預期的 EOF 信號。 如果指定為 True (默認值)，它將返回正常的 EOF (空字節串對象) 來(lái)響應從下層套接字引發(fā)的非預期的 EOF 錯誤；如果指定為 False，它將向調用方引發(fā)異常。

session，參見(jiàn) session。

在 3.5 版更改: 總是允許傳送 server_hostname，即使 OpenSSL 沒(méi)有 SNI。

在 3.6 版更改: 增加了 session 參數。

在 3.7 版更改: The method returns an instance of SSLContext.sslsocket_class instead of hard-coded SSLSocket.

SSLContext.sslsocket_class?

SSLContext.wrap_socket() 的返回類(lèi)型，默認為 SSLSocket。 該屬性可以在類(lèi)實(shí)例上被重載以便返回自定義的 SSLSocket 的子類(lèi)。

3.7 新版功能.

SSLContext.wrap_bio(incoming, outgoing, server_side=False, server_hostname=None, session=None)?

包裝 BIO 對象 incoming 和 outgoing 并返回一個(gè) SSLContext.sslobject_class (默認為 SSLObject) 的實(shí)例。 SSL 例程將從 BIO 中讀取輸入數據并將數據寫(xiě)入到 outgoing BIO。

server_side, server_hostname 和 session 形參具有與 SSLContext.wrap_socket() 中相同的含義。

在 3.6 版更改: 增加了 session 參數。

在 3.7 版更改: The method returns an instance of SSLContext.sslobject_class instead of hard-coded SSLObject.

SSLContext.sslobject_class?

SSLContext.wrap_bio() 的返回類(lèi)型，默認為 SSLObject。 該屬性可以在類(lèi)實(shí)例上被重載以便返回自定義的 SSLObject 的子類(lèi)。

3.7 新版功能.

SSLContext.session_stats()?

獲取該上下文創(chuàng )建或管理的 SSL 會(huì )話(huà)的統計數據。返回一個(gè)字典，將每`塊信息 <https://www.openssl.org/docs/man1.1.1/ssl/SSL_CTX_sess_number.html>`_ 映射到數字值。例如，下面是自該上下文創(chuàng )建以來(lái)會(huì )話(huà)緩存中的總點(diǎn)擊率和失誤率：

>>>

>>> stats = context.session_stats()
>>> stats['hits'], stats['misses']
(0, 0)

SSLContext.check_hostname?

是否要將匹配 SSLSocket.do_handshake() 中對等方證書(shū)的主機名。 該上下文的 verify_mode 必須被設為 CERT_OPTIONAL 或 CERT_REQUIRED，并且你必須將 server_hostname 傳給 wrap_socket() 以便匹配主機名。 啟用主機名檢查會(huì )自動(dòng)將 verify_mode 從 CERT_NONE 設為 CERT_REQUIRED。 只要啟用了主機名檢查就無(wú)法將其設回 CERT_NONE。 PROTOCOL_TLS_CLIENT 協(xié)議默認啟用主機名檢查。 對于其他協(xié)議，則必須顯式地啟用主機名檢查。

示例:

import socket, ssl

context = ssl.SSLContext(ssl.PROTOCOL_TLSv1_2)
context.verify_mode = ssl.CERT_REQUIRED
context.check_hostname = True
context.load_default_certs()

s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
ssl_sock = context.wrap_socket(s, server_hostname='www.verisign.com')
ssl_sock.connect(('www.verisign.com', 443))

3.4 新版功能.

在 3.7 版更改: 現在當主機名檢查被啟用且 verify_mode 為 CERT_NONE 時(shí) verify_mode 會(huì )自動(dòng)更改為 CERT_REQUIRED。 在之前版本中同樣的操作將失敗并引發(fā) ValueError。

SSLContext.keylog_filename?

每當生成或接收到密鑰時(shí)，將 TLS 密鑰寫(xiě)入到一個(gè)密鑰日志文件。 密鑰日志文件的設計僅適用于調試目的。 文件的格式由 NSS 指明并為許多流量分析工具例如 Wireshark 所使用。 日志文件會(huì )以追加模式打開(kāi)。 寫(xiě)入操作會(huì )在線(xiàn)程之間同步，但不會(huì )在進(jìn)程之間同步。

3.8 新版功能.

SSLContext.maximum_version?

一個(gè)代表所支持的最高 TLS 版本的 TLSVersion 枚舉成員。 該值默認為 TLSVersion.MAXIMUM_SUPPORTED。 這個(gè)屬性對于 PROTOCOL_TLS, PROTOCOL_TLS_CLIENT 和 PROTOCOL_TLS_SERVER 以外的其他協(xié)議來(lái)說(shuō)都是只讀的。

maximum_version, minimum_version 和 SSLContext.options 等屬性都會(huì )影響上下文所支持的 SSL 和 TLS 版本。 這個(gè)實(shí)現不會(huì )阻止無(wú)效的組合。 例如一個(gè) options 為 OP_NO_TLSv1_2 而 maximum_version 設為 TLSVersion.TLSv1_2 的上下文將無(wú)法建立 TLS 1.2 連接。

3.7 新版功能.

SSLContext.minimum_version?

與 SSLContext.maximum_version 類(lèi)似，區別在于它是所支持的最低版本或為 TLSVersion.MINIMUM_SUPPORTED。

3.7 新版功能.

SSLContext.num_tickets?

控制 TLS_PROTOCOL_SERVER 上下文的 TLS 1.3 會(huì )話(huà)憑據數量。這個(gè)設置不會(huì )影響 TLS 1.0 - 1.2 的連接。

3.8 新版功能.

SSLContext.options?

一個(gè)代表此上下文中所啟用的 SSL 選項集的整數。 默認值為 OP_ALL，但你也可以通過(guò)在選項間進(jìn)行 OR 運算來(lái)指定其他選項例如 OP_NO_SSLv2。

在 3.6 版更改: SSLContext.options 返回 Options 旗標:

>>>

>>> ssl.create_default_context().options  
<Options.OP_ALL|OP_NO_SSLv3|OP_NO_SSLv2|OP_NO_COMPRESSION: 2197947391>

3.7 版后已移除: 自 OpenSSL 1.1.0 起，所有 OP_NO_SSL* 和 OP_NO_TLS* 選項已被棄用，請改用新的 SSLContext.minimum_version 和 SSLContext.maximum_version。

SSLContext.post_handshake_auth?

啟用 TLS 1.3 握手后客戶(hù)端身份驗證。 握手后驗證默認是被禁用的，服務(wù)器只能在初始握手期間請求 TLS 客戶(hù)端證書(shū)。 當啟用時(shí)，服務(wù)器可以在握手之后的任何時(shí)候請求 TLS 客戶(hù)端證書(shū)。

當在客戶(hù)端套接字上啟用時(shí)，客戶(hù)端會(huì )向服務(wù)器發(fā)信號說(shuō)明它支持握手后身份驗證。

當在服務(wù)器端套接字上啟用時(shí)，SSLContext.verify_mode 也必須被設為 CERT_OPTIONAL 或 CERT_REQUIRED。 實(shí)際的客戶(hù)端證書(shū)交換會(huì )被延遲直至 SSLSocket.verify_client_post_handshake() 被調用并執行了一些 I/O 操作后再進(jìn)行。

3.8 新版功能.

SSLContext.protocol?

構造上下文時(shí)所選擇的協(xié)議版本。 這個(gè)屬性是只讀的。

SSLContext.hostname_checks_common_name?

在沒(méi)有目標替代名稱(chēng)擴展的情況下 check_hostname 是否要回退為驗證證書(shū)的通用名稱(chēng)（默認為真值）。

3.7 新版功能.

在 3.10 版更改: 此旗標在 OpenSSL 1.1.1k 之前的版本上不起作用。 Python 3.8.9, 3.9.3, 和 3.10 包含了針對之前版本的變通處理。

SSLContext.security_level?

整數值，代表上下文的 安全級別。 本屬性只讀。

3.10 新版功能.

SSLContext.verify_flags?

證書(shū)驗證操作的標志位?？梢杂谩盎颉钡姆绞浇M合在一起設置 VERIFY_CRL_CHECK_LEAF 這類(lèi)標志。默認情況下，OpenSSL 既不需要也不驗證證書(shū)吊銷(xiāo)列表（CRL）。

3.4 新版功能.

在 3.6 版更改: SSLContext.verify_flags 返回 VerifyFlags 旗標:

>>>

>>> ssl.create_default_context().verify_flags  
<VerifyFlags.VERIFY_X509_TRUSTED_FIRST: 32768>

SSLContext.verify_mode?

是否要嘗試驗證其他對等方的證書(shū)以及如果驗證失敗應采取何種行為。 該屬性值必須為 CERT_NONE, CERT_OPTIONAL 或 CERT_REQUIRED 之一。

在 3.6 版更改: SSLContext.verify_mode 返回 VerifyMode 枚舉:

>>>

>>> ssl.create_default_context().verify_mode  
<VerifyMode.CERT_REQUIRED: 2>

證書(shū)?

總的來(lái)說(shuō)證書(shū)是公鑰/私鑰系統的一個(gè)組成部分。 在這個(gè)系統中，每 個(gè) 主體 (可能是一臺機器、一個(gè)人或者一個(gè)組織) 都會(huì )分配到唯一的包含兩部分的加密密鑰。 一部分密鑰是公開(kāi)的，稱(chēng)為 公鑰；另一部分密鑰是保密的，稱(chēng)為 私鑰。 這兩個(gè)部分是互相關(guān)聯(lián)的，就是說(shuō)如果你用其中一個(gè)部分來(lái)加密一條消息，你將能用并且 只能 用另一個(gè)部分來(lái)解密它。

在一個(gè)證書(shū)中包含有兩個(gè)主體的相關(guān)信息。 它包含 目標方 的名稱(chēng)和目標方的公鑰。 它還包含由第二個(gè)主體 頒發(fā)方 所發(fā)布的聲明：目標方的身份與他們所宣稱(chēng)的一致，包含的公鑰也確實(shí)是目標方的公鑰。 頒發(fā)方的聲明使用頒發(fā)方的私鑰進(jìn)行簽名，該私鑰的內容只有頒發(fā)方自己才知道。 但是，任何人都可以找到頒發(fā)方的公鑰，用它來(lái)解密這個(gè)聲明，并將其與證書(shū)中的其他信息進(jìn)行比較來(lái)驗證頒發(fā)方聲明的真實(shí)性。 證書(shū)還包含有關(guān)其有效期限的信息。 這被表示為兩個(gè)字段，即 "notBefore" 和 "notAfter"。

在 Python 中應用證書(shū)時(shí)，客戶(hù)端或服務(wù)器可以用證書(shū)來(lái)證明自己的身份。 還可以要求網(wǎng)絡(luò )連接的另一方提供證書(shū)，提供的證書(shū)可以用于驗證以滿(mǎn)足客戶(hù)端或服務(wù)器的驗證要求。 如果驗證失敗，連接嘗試可被設置為引發(fā)一個(gè)異常。 驗證是由下層的 OpenSSL 框架來(lái)自動(dòng)執行的；應用程序本身不必關(guān)注其內部的機制。 但是應用程序通常需要提供一組證書(shū)以允許此過(guò)程的發(fā)生。

Python 使用文件來(lái)包含證書(shū)。 它們應當采用 "PEM" 格式 (參見(jiàn) RFC 1422)，這是一種帶有頭部行和尾部行的 base-64 編碼包裝形式:

-----BEGIN CERTIFICATE-----
... (certificate in base64 PEM encoding) ...
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
... (certificate for your server)...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (the certificate for the CA)...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (the root certificate for the CA's issuer)...
-----END CERTIFICATE-----

-----BEGIN RSA PRIVATE KEY-----
... (private key in base64 encoding) ...
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
... (certificate in base64 PEM encoding) ...
-----END CERTIFICATE-----

% openssl req -new -x509 -days 365 -nodes -out cert.pem -keyout cert.pem
Generating a 1024 bit RSA private key
.......++++++
.............................++++++
writing new private key to 'cert.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:MyState
Locality Name (eg, city) []:Some City
Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Organization, Inc.
Organizational Unit Name (eg, section) []:My Group
Common Name (eg, YOUR name) []:myserver.mygroup.myorganization.com
Email Address []:ops@myserver.mygroup.myorganization.com
%

例子?

try:
    import ssl
except ImportError:
    pass
else:
    ...  # do something that requires SSL support

>>> context = ssl.create_default_context()

>>> context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
>>> context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")

>>> conn = context.wrap_socket(socket.socket(socket.AF_INET),
...                            server_hostname="www.python.org")
>>> conn.connect(("www.python.org", 443))

>>> cert = conn.getpeercert()

>>> pprint.pprint(cert)
{'OCSP': ('http://ocsp.digicert.com',),
 'caIssuers': ('http://cacerts.digicert.com/DigiCertSHA2ExtendedValidationServerCA.crt',),
 'crlDistributionPoints': ('http://crl3.digicert.com/sha2-ev-server-g1.crl',
                           'http://crl4.digicert.com/sha2-ev-server-g1.crl'),
 'issuer': ((('countryName', 'US'),),
            (('organizationName', 'DigiCert Inc'),),
            (('organizationalUnitName', 'www.digicert.com'),),
            (('commonName', 'DigiCert SHA2 Extended Validation Server CA'),)),
 'notAfter': 'Sep  9 12:00:00 2016 GMT',
 'notBefore': 'Sep  5 00:00:00 2014 GMT',
 'serialNumber': '01BB6F00122B177F36CAB49CEA8B6B26',
 'subject': ((('businessCategory', 'Private Organization'),),
             (('1.3.6.1.4.1.311.60.2.1.3', 'US'),),
             (('1.3.6.1.4.1.311.60.2.1.2', 'Delaware'),),
             (('serialNumber', '3359300'),),
             (('streetAddress', '16 Allen Rd'),),
             (('postalCode', '03894-4801'),),
             (('countryName', 'US'),),
             (('stateOrProvinceName', 'NH'),),
             (('localityName', 'Wolfeboro'),),
             (('organizationName', 'Python Software Foundation'),),
             (('commonName', 'www.python.org'),)),
 'subjectAltName': (('DNS', 'www.python.org'),
                    ('DNS', 'python.org'),
                    ('DNS', 'pypi.org'),
                    ('DNS', 'docs.python.org'),
                    ('DNS', 'testpypi.org'),
                    ('DNS', 'bugs.python.org'),
                    ('DNS', 'wiki.python.org'),
                    ('DNS', 'hg.python.org'),
                    ('DNS', 'mail.python.org'),
                    ('DNS', 'packaging.python.org'),
                    ('DNS', 'pythonhosted.org'),
                    ('DNS', 'www.pythonhosted.org'),
                    ('DNS', 'test.pythonhosted.org'),
                    ('DNS', 'us.pycon.org'),
                    ('DNS', 'id.python.org')),
 'version': 3}

>>> conn.sendall(b"HEAD / HTTP/1.0\r\nHost: linuxfr.org\r\n\r\n")
>>> pprint.pprint(conn.recv(1024).split(b"\r\n"))
[b'HTTP/1.1 200 OK',
 b'Date: Sat, 18 Oct 2014 18:27:20 GMT',
 b'Server: nginx',
 b'Content-Type: text/html; charset=utf-8',
 b'X-Frame-Options: SAMEORIGIN',
 b'Content-Length: 45679',
 b'Accept-Ranges: bytes',
 b'Via: 1.1 varnish',
 b'Age: 2188',
 b'X-Served-By: cache-lcy1134-LCY',
 b'X-Cache: HIT',
 b'X-Cache-Hits: 11',
 b'Vary: Cookie',
 b'Strict-Transport-Security: max-age=63072000; includeSubDomains',
 b'Connection: close',
 b'',
 b'']

import socket, ssl

context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
context.load_cert_chain(certfile="mycertfile", keyfile="mykeyfile")

bindsocket = socket.socket()
bindsocket.bind(('myaddr.example.com', 10023))
bindsocket.listen(5)

while True:
    newsocket, fromaddr = bindsocket.accept()
    connstream = context.wrap_socket(newsocket, server_side=True)
    try:
        deal_with_client(connstream)
    finally:
        connstream.shutdown(socket.SHUT_RDWR)
        connstream.close()

def deal_with_client(connstream):
    data = connstream.recv(1024)
    # empty data means the client is finished with us
    while data:
        if not do_something(connstream, data):
            # we'll assume do_something returns False
            # when we're finished with client
            break
        data = connstream.recv(1024)
    # finished with client

關(guān)于非阻塞套接字的說(shuō)明?

在非阻塞模式下 SSL 套接字的行為與常規套接字略有不同。 當使用非阻塞模式時(shí)，你需要注意下面這些事情:

• 如果一個(gè) I/O 操作會(huì )阻塞，大多數 SSLSocket 方法都將引發(fā) SSLWantWriteError 或 SSLWantReadError 而非 BlockingIOError。 如果有必要在下層套接字上執行讀取操作將引發(fā) SSLWantReadError，在下層套接字上執行寫(xiě)入操作則將引發(fā) SSLWantWriteError。 請注意嘗試 寫(xiě)入 到 SSL 套接字可能需要先從下層套接字 讀取，而嘗試從 SSL 套接字 讀取 則可能需要先向下層套接字 寫(xiě)入。

  在 3.5 版更改: 在較早的 Python 版本中，SSLSocket.send() 方法會(huì )返回零值而非引發(fā) SSLWantWriteError 或 SSLWantReadError。

• 調用 select() 將告訴你可以從 OS 層級的套接字讀?。ɑ蛳蚱鋵?xiě)入），但這并不意味著(zhù)在上面的 SSL 層有足夠的數據。 例如，可能只有部分 SSL 幀已經(jīng)到達。 因此，你必須準備好處理 SSLSocket.recv() 和 SSLSocket.send() 失敗的情況，并在再次調用 select() 之后重新嘗試。

• 相反地，由于 SSL 層具有自己的幀機制，一個(gè) SSL 套接字可能仍有可讀取的數據而 select() 并不知道這一點(diǎn)。 因此，你應當先調用 SSLSocket.recv() 取走所有潛在的可用數據，然后只在必要時(shí)對 select() 調用執行阻塞。

  (當然，類(lèi)似的保留規則在使用其他原語(yǔ)例如 poll()，或 selectors 模塊中的原語(yǔ)時(shí)也適用)

• SSL 握手本身將是非阻塞的: SSLSocket.do_handshake() 方法必須不斷重試直至其成功返回。 下面是一個(gè)使用 select() 來(lái)等待套接字就緒的簡(jiǎn)短例子:

  while True:
      try:
          sock.do_handshake()
          break
      except ssl.SSLWantReadError:
          select.select([sock], [], [])
      except ssl.SSLWantWriteError:
          select.select([], [sock], [])
  

內存 BIO 支持?

自從 SSL 模塊在 Python 2.6 起被引入之后，SSLSocket 類(lèi)提供了兩個(gè)互相關(guān)聯(lián)但彼此獨立的功能分塊:

• SSL 協(xié)議處理

• 網(wǎng)絡(luò ) IO

網(wǎng)絡(luò ) IO API 與 socket.socket 所提供的功能一致，SSLSocket 也是從那里繼承而來(lái)的。 這允許 SSL 套接字被用作常規套接字的替代，使得向現有應用程序添加 SSL 支持變得非常容易。

將 SSL 協(xié)議處理與網(wǎng)絡(luò ) IO 結合使用通常都能運行良好，但在某些情況下則不能。 此情況的一個(gè)例子是 async IO 框架，該框架要使用不同的 IO 多路復用模型而非 (基于就緒狀態(tài)的) "在文件描述器上執行選擇/輪詢(xún)" 模型，該模型是 socket.socket 和內部 OpenSSL 套接字 IO 例程正常運行的假設前提。 這種情況在該模型效率不高的 Windows 平臺上最為常見(jiàn)。 為此還提供了一個(gè) SSLSocket 的簡(jiǎn)化形式，稱(chēng)為 SSLObject。

class ssl.SSLObject?

SSLSocket 的簡(jiǎn)化形式，表示一個(gè)不包含任何網(wǎng)絡(luò ) IO 方法的 SSL 協(xié)議實(shí)例。 這個(gè)類(lèi)通常由想要通過(guò)內存緩沖區為 SSL 實(shí)現異步 IO 的框架作者來(lái)使用。

這個(gè)類(lèi)在低層級 SSL 對象上實(shí)現了一個(gè)接口，與 OpenSSL 所實(shí)現的類(lèi)似。 此對象會(huì )捕獲 SSL 連接的狀態(tài)但其本身不提供任何網(wǎng)絡(luò ) IO。 IO 需要通過(guò)單獨的 "BIO" 對象來(lái)執行，該對象是 OpenSSL 的 IO 抽象層。

這個(gè)類(lèi)沒(méi)有公有構造器。 SSLObject 實(shí)例必須使用 wrap_bio() 方法來(lái)創(chuàng )建。 此方法將創(chuàng )建 SSLObject 實(shí)例并將其綁定到一個(gè) BIO 對。 其中 incoming BIO 用來(lái)將數據從 Python 傳遞到 SSL 協(xié)議實(shí)例，而 outgoing BIO 用來(lái)進(jìn)行數據反向傳遞。

可以使用以下方法：

• context

• server_side

• server_hostname

• session

• session_reused

• read()

• write()

• getpeercert()

• selected_alpn_protocol()

• selected_npn_protocol()

• cipher()

• shared_ciphers()

• compression()

• pending()

• do_handshake()

• verify_client_post_handshake()

• unwrap()

• get_channel_binding()

• version()

與 SSLSocket 相比，此對象缺少下列特性:

• 任何形式的網(wǎng)絡(luò ) IO; recv() 和 send() 僅對下層的 MemoryBIO 緩沖區執行讀取和寫(xiě)入。

• 不存在 do_handshake_on_connect 機制。 你必須總是手動(dòng)調用 do_handshake() 來(lái)開(kāi)始握手操作。

• 不存在對 suppress_ragged_eofs 的處理。 所有違反協(xié)議的文件結束條件將通過(guò) SSLEOFError 異常來(lái)報告。

• 方法 unwrap() 的調用不返回任何東西，不會(huì )如 SSL 套接字那樣返回下層的套接字。

• server_name_callback 回調被傳給 SSLContext.set_servername_callback() 時(shí)將獲得一個(gè) SSLObject 實(shí)例而非 SSLSocket 實(shí)例作為其第一個(gè)形參。

有關(guān) SSLObject 用法的一些說(shuō)明:

• 在 SSLObject 上的所有 IO 都是 非阻塞的。 這意味著(zhù)例如 read() 在其需要比 incoming BIO 可用的更多數據時(shí)將會(huì )引發(fā) SSLWantReadError。

• 不存在模塊層級的 wrap_bio() 調用，就像 wrap_socket() 那樣。 SSLObject 總是通過(guò) SSLContext 來(lái)創(chuàng )建。

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

SSLObject 會(huì )使用內存緩沖區與外部世界通信。 MemoryBIO 類(lèi)提供了可被用于此目的的內存緩沖區。 它包裝了一個(gè) OpenSSL 內存 BIO (Basic IO) 對象:

class ssl.MemoryBIO?

一個(gè)可被用來(lái)在 Python 和 SSL 協(xié)議實(shí)例之間傳遞數據的內存緩沖區。

pending?

返回當前存在于內存緩沖區的字節數。

eof?

一個(gè)表明內存 BIO 目前是否位于文件末尾的布爾值。

read(n=- 1)?

從內存緩沖區讀取至多 n 個(gè)字節。 如果 n 未指定或為負值，則返回全部字節數據。

write(buf)?

將字節數據從 buf 寫(xiě)入到內存 BIO。 buf 參數必須為支持緩沖區協(xié)議的對象。

返回值為寫(xiě)入的字節數，它總是與 buf 的長(cháng)度相等。

write_eof()?

將一個(gè) EOF 標記寫(xiě)入到內存 BIO。 在此方法被調用以后，再調用 write() 將是非法的。 屬性 eof will 在緩沖區當前的所有數據都被讀取之后將變?yōu)檎嬷怠?/p>

SSL 會(huì )話(huà)?

class ssl.SSLSession?

session 所使用的會(huì )話(huà)對象。

id?

time?

timeout?

ticket_lifetime_hint?

has_ticket?

安全考量?

>>> import ssl, smtplib
>>> smtp = smtplib.SMTP("mail.python.org", port=587)
>>> context = ssl.create_default_context()
>>> smtp.starttls(context=context)
(220, b'2.0.0 Ready to start TLS')

>>> client_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
>>> client_context.minimum_version = ssl.TLSVersion.TLSv1_3
>>> client_context.maximum_version = ssl.TLSVersion.TLSv1_3

TLS 1.3?

TLS 1.3 協(xié)議的行為與低版本的 TLS/SSL 略有不同。某些 TLS 1.3 新特性還不可用。

• TLS 1.3 使用一組不同的加密套件集。 默認情況下所有 AES-GCM 和 ChaCha20 加密套件都會(huì )被啟用。 SSLContext.set_ciphers() 方法還不能啟用或禁用任何 TLS 1.3 加密，但 SSLContext.get_ciphers() 會(huì )返回它們。

• 會(huì )話(huà)憑據不再會(huì )作為初始握手的組成部分被發(fā)送而是以不同的方式來(lái)處理。 SSLSocket.session 和 SSLSession 與 TLS 1.3 不兼容。

• 客戶(hù)端證書(shū)在初始握手期間也不會(huì )再被驗證。 服務(wù)器可以在任何時(shí)候請求證書(shū)。 客戶(hù)端會(huì )在它們從服務(wù)器發(fā)送或接收應用數據時(shí)處理證書(shū)請求。

• 早期數據、延遲的 TLS 客戶(hù)端證書(shū)請求、簽名算法配置和密鑰重生成等 TLS 1.3 特性尚未被支持。