توابع، ثابت‌ها و استثناها¶

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() (اما ارسال مقدار غیرصفر برای آرگومان flags مجاز نیست)

• send()، sendall() (با همان محدودیت)

• sendfile() (ممکن است فقط زمانی کارایی بالایی داشته باشد که TLS هسته با تنظیم OP_ENABLE_KTLS فعال شده باشد یا زمانی که یک سوکت متن‌ساده است، در غیر این صورت از send() استفاده خواهد شد)

• shutdown()

با این حال، از آن‌جا که پروتکل SSL (و TLS) قاب‌بندی خاص خود را بر فراز TCP دارد، انتزاع سوکت‌های SSL می‌تواند از برخی جهات با مشخصات سوکت‌های عادی در سطح سیستم‌عامل متفاوت باشد. به‌ویژه یادداشت‌ها درباره سوکت‌های غیرمسدودکننده را ببینید.

نمونه‌های SSLSocket باید با استفاده از متد SSLContext.wrap_socket() ایجاد شوند.

تغییر یافته در نسخه‌ی 3.5: متد sendfile() افزوده شد.

تغییر یافته در نسخه‌ی 3.5: shutdown() هر بار که بایت‌هایی دریافت یا ارسال می‌شوند، مهلت زمانی سوکت را بازنشانی نمی‌کند. مهلت زمانی سوکت اکنون حداکثر مدت‌زمان کل خاموش‌سازی است.

منسوخ شده از نسخه‌ی 3.6: ایجاد مستقیم یک نمونه‌ی SSLSocket منسوخ شده است؛ برای پیچیدن (wrap) یک سوکت از SSLContext.wrap_socket() استفاده کنید.

تغییر یافته در نسخه‌ی 3.7: نمونه‌های SSLSocket باید با wrap_socket() ایجاد شوند. در نسخه‌های پیشین، امکان ایجاد مستقیم نمونه‌ها وجود داشت. این مورد هرگز مستند نشده بود یا به‌صورت رسمی پشتیبانی نمی‌شد.

تغییر یافته در نسخه‌ی 3.10: پایتون اکنون به‌صورت داخلی از SSL_read_ex و SSL_write_ex استفاده می‌کند. این توابع از خواندن و نوشتن داده‌های بزرگ‌تر از ۲ GB پشتیبانی می‌کنند. نوشتن داده با طول صفر دیگر با خطای نقض پروتکل شکست نمی‌خورد.

تغییر یافته در نسخه‌ی 3.15: پایتون اکنون در صورت امکان به‌طور داخلی از SSL_sendfile استفاده می‌کند. این تابع یک پرونده را با کارایی بیشتری ارسال می‌کند زیرا رمزگذاری TLS را در هسته (kernel) انجام می‌دهد تا از تعویض زمینه‌ی اضافی جلوگیری کند.

سوکت‌های SSL همچنین دارای متدها و ویژگی‌های اضافی زیر هستند:

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

حداکثر تا len بایت داده را از سوکت SSL می‌خواند و نتیجه را به‌صورت یک نمونه bytes برمی‌گرداند. اگر buffer مشخص شده باشد، در عوض داده‌ها را در بافر می‌خواند و تعداد بایت‌های خوانده‌شده را برمی‌گرداند.

اگر سوکت غیرمسدودکننده باشد و خواندن مسدود شود، SSLWantReadError یا SSLWantWriteError را پرتاب می‌کند.

از آن‌جا که در هر زمان امکان مذاکره‌ی مجدد وجود دارد، فراخوانی read() می‌تواند باعث انجام عملیات نوشتن نیز شود.

تغییر یافته در نسخه‌ی 3.5: مهلت سوکت دیگر هر بار که بایت‌هایی دریافت یا ارسال می‌شوند بازنشانی نمی‌شود. مهلت سوکت اکنون حداکثر مدت‌زمان کل برای خواندن تا len بایت است.

منسوخ شده از نسخه‌ی 3.6: به‌جای read() از recv() استفاده کنید.

SSLSocket.write(data)¶

data را روی سوکت SSL می‌نویسد و تعداد بایت‌های نوشته‌شده را برمی‌گرداند. آرگومان data باید شیءای باشد که رابط بافر (buffer interface) را پشتیبانی می‌کند.

اگر سوکت غیرمسدودکننده باشد و نوشتن باعث مسدود شدن شود، SSLWantReadError یا SSLWantWriteError پرتاب می‌شود.

از آن‌جا که در هر زمان امکان مذاکره‌ی مجدد وجود دارد، فراخوانی write() نیز می‌تواند باعث انجام عملیات خواندن شود.

تغییر یافته در نسخه‌ی 3.5: مهلت سوکت دیگر هر بار که بایت‌هایی دریافت یا ارسال می‌شوند، بازنشانی نمی‌شود. مهلت سوکت اکنون حداکثر مدت‌زمان کل برای نوشتن data است.

منسوخ شده از نسخه‌ی 3.6: از send() به جای write() استفاده کنید.

SSLSocket.do_handshake(block=False)¶

دست‌دهی (handshake) راه‌اندازی SSL را انجام دهید.

اگر block صحیح باشد و مهلت زمانی دریافت‌شده از gettimeout() صفر باشد، سوکت تا انجام دست‌دهی در حالت مسدودکننده تنظیم می‌شود.

تغییر یافته در نسخه‌ی 3.4: متد دست‌دهی همچنین هنگامی که ویژگی check_hostname در context سوکت true باشد، match_hostname() را اجرا می‌کند.

تغییر یافته در نسخه‌ی 3.5: مهلت زمانی سوکت دیگر هر بار که بایت‌ها دریافت یا ارسال می‌شوند، بازنشانی نمی‌شود. مهلت زمانی سوکت اکنون حداکثر مدت‌زمان کل دست‌دهی است.

تغییر یافته در نسخه‌ی 3.7: نام میزبان یا نشانی IP در طول دست‌دهی توسط OpenSSL تطبیق داده می‌شود. دیگر از تابع match_hostname() استفاده نمی‌شود. در صورتی که OpenSSL یک نام میزبان یا نشانی IP را رد کند، دست‌دهی در مراحل اولیه قطع می‌شود و یک پیام هشدار TLS به طرف مقابل ارسال می‌شود.

SSLSocket.getpeercert(binary_form=False)¶

اگر گواهی برای همتای سمت دیگر اتصال وجود نداشته باشد، None را برمی‌گرداند. اگر دست‌دهی SSL هنوز انجام نشده باشد، ValueError را پرتاب می‌کند.

اگر پارامتر binary_form برابر False باشد و گواهی از طرف مقابل دریافت شده باشد، این متد نمونه‌ای از dict را برمی‌گرداند. اگر گواهی اعتبارسنجی نشده باشد، دیکشنری خالی است. اگر گواهی اعتبارسنجی شده باشد، یک دیکشنری با چندین کلید برمی‌گرداند، از جمله subject (هویتی که گواهی برای آن صادر شده است) و issuer (هویتی که گواهی را صادر کرده است). اگر گواهی شامل نمونه‌ای از افزونه Subject Alternative Name باشد (به RFC 3280 مراجعه کنید)، کلید subjectAltName نیز در دیکشنری وجود خواهد داشت.

فیلدهای subject و issuer تاپل‌هایی شامل دنباله‌ای از نام‌های متمایز نسبی (RDNs) هستند که در ساختار داده‌ی گواهی برای فیلدهای مربوطه آمده‌اند، و هر RDN دنباله‌ای از جفت‌های نام-مقدار است. در اینجا یک مثال واقعی آمده است:

{'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', '[email protected]'),)),
 'subjectAltName': (('DNS', '*.eff.org'), ('DNS', 'eff.org')),
 'version': 3}

اگر پارامتر binary_form برابر True باشد و گواهی‌ای ارائه شده باشد، این متد قالب کدگذاری‌شده با DER کل گواهی را به‌صورت دنباله‌ای از بایت‌ها بازمی‌گرداند، یا اگر همتا گواهی‌ای ارائه نکرده باشد، None بازمی‌گرداند. اینکه همتا گواهی‌ای ارائه می‌کند یا نه، به نقش سوکت SSL بستگی دارد:

• برای یک سوکت SSL کلاینت، سرور همیشه یک گواهی ارائه می‌دهد، صرف‌نظر از اینکه اعتبارسنجی الزامی بوده باشد یا خیر؛

• برای یک سوکت SSL سرور، کلاینت فقط در صورت درخواست سرور یک گواهی ارائه می‌کند؛ بنابراین اگر از CERT_NONE استفاده کرده باشید (به‌جای CERT_OPTIONAL یا CERT_REQUIRED)، getpeercert() مقدار None را برمی‌گرداند.

همچنین SSLContext.check_hostname را ببینید.

تغییر یافته در نسخه‌ی 3.2: دیکشنری برگردانده‌شده شامل آیتم‌های اضافی مانند issuer و notBefore می‌شود.

تغییر یافته در نسخه‌ی 3.4: هنگامی که دست‌دهی انجام نشده باشد، ValueError پرتاب می‌شود. دیکشنری برگردانده‌شده شامل آیتم‌های اضافی افزونه‌ی X509v3 مانند crlDistributionPoints، caIssuers و URIهای OCSP است.

تغییر یافته در نسخه‌ی 3.9: رشته‌های نشانی IPv6 دیگر دارای خط جدید در انتها نیستند.

SSLSocket.get_verified_chain()¶

زنجیره‌ی گواهی تأییدشده‌ای که از سوی طرف مقابل کانال SSL ارائه شده است را به‌صورت فهرستی از بایت‌های کدگذاری‌شده با DER برمی‌گرداند. اگر تأیید گواهی غیرفعال شده باشد، این متد همانند get_unverified_chain() عمل می‌کند.

The verified chain is not stored with a session, so the list is empty when the session is resumed (see session_reused).

اضافه شده در نسخه‌ی 3.13.

SSLSocket.get_unverified_chain()¶

زنجیره‌ی گواهی خام ارائه‌شده توسط طرف مقابل کانال SSL را به‌صورت فهرستی از بایت‌های کدگذاری‌شده با DER بازمی‌گرداند.

No certificates are exchanged when a session is resumed (see session_reused); the list then holds what was stored with the session, which for a session resumed from a ticket on the server side is the peer's own certificate only.

اضافه شده در نسخه‌ی 3.13.

SSLSocket.cipher()¶

یک تاپل سه‌مقداری شامل نام رمزنگار استفاده‌شده، نسخه پروتکل SSL که استفاده از آن را تعریف می‌کند، و تعداد بیت‌های محرمانه استفاده‌شده را برمی‌گرداند. اگر هیچ اتصالی برقرار نشده باشد، None را برمی‌گرداند.

SSLSocket.shared_ciphers()¶

فهرست رمزنگارهای موجود در هر دو کلاینت و سرور (server) را برمی‌گرداند. هر آیتم از فهرست برگردانده‌شده، یک تاپل سه‌مقداری است که شامل نام رمزنگار، نسخه‌ی پروتکل SSL که استفاده از آن را تعریف می‌کند، و تعداد بیت‌های محرمانه‌ای است که رمزنگار از آن‌ها استفاده می‌کند. shared_ciphers() در صورتی که هیچ اتصالی برقرار نشده باشد یا سوکت از نوع کلاینت باشد، None را برمی‌گرداند.

اضافه شده در نسخه‌ی 3.5.

SSLSocket.group()¶

گروه مورد استفاده برای توافق کلید روی این اتصال را برمی‌گرداند. اگر هیچ اتصالی برقرار نشده باشد، None را برمی‌گرداند.

اضافه شده در نسخه‌ی 3.15.

SSLSocket.client_sigalg()¶

الگوریتم امضای مورد استفاده برای انجام احراز هویت کلاینت مبتنی بر گواهی روی این اتصال را برمی‌گرداند، یا اگر هیچ اتصالی برقرار نشده باشد یا احراز هویت کلاینت انجام نشده باشد، None را برمی‌گرداند.

اضافه شده در نسخه‌ی 3.15.

SSLSocket.server_sigalg()¶

الگوریتم امضای مورد استفاده توسط سرور برای تکمیل دست‌دهی TLS روی این اتصال را برمی‌گرداند، یا اگر هیچ اتصالی برقرار نشده باشد یا مجموعه رمز امضایی نداشته باشد، None را برمی‌گرداند.

اضافه شده در نسخه‌ی 3.15.

SSLSocket.compression()¶

الگوریتم فشرده‌سازی مورد استفاده را به‌صورت یک رشته برمی‌گرداند، یا اگر اتصال فشرده‌نشده باشد None برمی‌گرداند.

اگر پروتکل سطح بالاتر از سازوکار فشرده‌سازی خود پشتیبانی کند، می‌توانید از OP_NO_COMPRESSION برای غیرفعال کردن فشرده‌سازی سطح SSL استفاده کنید.

اضافه شده در نسخه‌ی 3.3.

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

داده‌های پیوند کانال (channel binding) را برای اتصال جاری، به‌صورت یک شیء بایتی دریافت می‌کند. اگر اتصال برقرار نباشد یا دست‌دهی کامل نشده باشد، None برمی‌گرداند.

پارامتر cb_type امکان انتخاب نوع اتصال کانال (channel binding) دلخواه را فراهم می‌کند. انواع معتبر اتصال کانال (channel binding) در فهرست CHANNEL_BINDING_TYPES آمده‌اند. در حال حاضر تنها اتصال کانال (channel binding) 'tls-unique'، که در RFC 5929 تعریف شده است، پشتیبانی می‌شود. اگر یک نوع اتصال کانال (channel binding) پشتیبانی‌نشده درخواست شود، ValueError پرتاب می‌شود.

اضافه شده در نسخه‌ی 3.3.

SSLSocket.selected_alpn_protocol()¶

پروتکل انتخاب‌شده در جریان دست‌دهی TLS را برمی‌گرداند. اگر SSLContext.set_alpn_protocols() فراخوانی نشده باشد، اگر طرف مقابل از ALPN پشتیبانی نکند، اگر این سوکت از هیچ‌یک از پروتکل‌های پیشنهادی کلاینت پشتیبانی نکند، یا اگر دست‌دهی هنوز انجام نشده باشد، None برگردانده می‌شود.

اضافه شده در نسخه‌ی 3.5.

SSLSocket.selected_npn_protocol()¶

پروتکل سطح بالاتری را که در جریان دست‌دهی TLS/SSL انتخاب شده است، برمی‌گرداند. اگر SSLContext.set_npn_protocols() فراخوانی نشده باشد، یا طرف مقابل از NPN پشتیبانی نکند، یا دست‌دهی هنوز انجام نشده باشد، None برمی‌گرداند.

اضافه شده در نسخه‌ی 3.3.

منسوخ شده از نسخه‌ی 3.10: NPN با ALPN جایگزین شده است

SSLSocket.unwrap()¶

دست‌دهی خاموش‌سازی SSL را انجام می‌دهد، که لایه TLS را از سوکت زیرین برمی‌دارد و شیء سوکت زیرین را برمی‌گرداند. می‌توان از آن برای گذار از عملیات رمزگذاری‌شده بر بستر یک اتصال به عملیات رمزگذاری‌نشده استفاده کرد. همیشه باید برای ارتباط بیشتر با طرف دیگر اتصال، به‌جای سوکت اصلی از سوکت برگردانده‌شده استفاده شود.

SSLSocket.verify_client_post_handshake()¶

احراز هویت پس از دست‌دهی (PHA) را از یک کلاینت TLS 1.3 درخواست می‌کند. PHA فقط می‌تواند از یک سوکت سمت سرور برای یک اتصال TLS 1.3، پس از دست‌دهی اولیه‌ی TLS و با فعال بودن PHA در هر دو طرف آغاز شود؛ SSLContext.post_handshake_auth را ببینید.

این متد تبادل گواهی را بلافاصله انجام نمی‌دهد. سمت سرور یک CertificateRequest را در رویداد نوشتن بعدی ارسال می‌کند و انتظار دارد کلاینت در رویداد خواندن بعدی با یک گواهی پاسخ دهد.

اگر یکی از پیش‌شرط‌ها برآورده نشود (مثلاً TLS 1.3 نباشد یا PHA فعال نباشد)، یک SSLError پرتاب می‌شود.

نکته

فقط زمانی در دسترس است که OpenSSL 1.1.1 و TLS 1.3 فعال باشند. بدون پشتیبانی از TLS 1.3، این متد استثنای NotImplementedError را پرتاب می‌کند.

اضافه شده در نسخه‌ی 3.8.

SSLSocket.version()¶

نسخه‌ی واقعی پروتکل SSL را که در اتصال توافق‌شده است، به‌صورت یک رشته برمی‌گرداند، یا اگر هیچ اتصال امنی برقرار نباشد، None برمی‌گرداند. در زمان نگارش این متن، مقادیر بازگشتی ممکن شامل "SSLv2"، "SSLv3"، "TLSv1"، "TLSv1.1" و "TLSv1.2" هستند. نسخه‌های جدید OpenSSL ممکن است مقادیر بازگشتی بیشتری تعریف کنند.

اضافه شده در نسخه‌ی 3.5.

SSLSocket.pending()¶

تعداد بایت‌های از پیش رمزگشایی‌شده‌ی موجود برای خواندن را که روی اتصال در انتظار هستند بازمی‌گرداند.

SSLSocket.context¶

شیء SSLContext که این سوکت SSL به آن وابسته است.

اضافه شده در نسخه‌ی 3.2.

SSLSocket.server_side¶

یک بولی که برای سوکت‌های سمت سرور True و برای سوکت‌های سمت کلاینت False است.

اضافه شده در نسخه‌ی 3.2.

SSLSocket.server_hostname¶

نام میزبان سرور: از نوع str، یا None برای سوکت سمت سرور یا اگر نام میزبان در سازنده مشخص نشده باشد.

اضافه شده در نسخه‌ی 3.2.

تغییر یافته در نسخه‌ی 3.7: این ویژگی اکنون همیشه متن ASCII است. هنگامی که server_hostname یک نام دامنه بین‌المللی‌شده (IDN) باشد، این ویژگی اکنون قالب A-label را ذخیره می‌کند ("xn--pythn-mua.org")، نه قالب U-label را ("pythön.org").

SSLSocket.session¶

SSLSession برای این اتصال SSL. این نشست پس از انجام دست‌دهی TLS برای سوکت‌های سمت کلاینت و سرور در دسترس است. برای سوکت‌های کلاینت، می‌توان نشست را پیش از فراخوانی do_handshake() برای استفاده مجدد از یک نشست تنظیم کرد.

اضافه شده در نسخه‌ی 3.6.

SSLSocket.session_reused¶

اضافه شده در نسخه‌ی 3.6.

زمینه‌های SSL¶

یک زمینه SSL داده‌های مختلفی را با طول عمر بیشتر از یک اتصال SSL واحد نگه می‌دارد، مانند گزینه‌های پیکربندی SSL، گواهی‌ها و کلیدهای خصوصی. همچنین یک نهانگاه از نشست‌های SSL را برای سوکت‌های سمت سرور مدیریت می‌کند تا سرعت اتصال‌های مکرر از همان کلاینت‌ها را افزایش دهد.

class ssl.SSLContext(protocol=None)¶

یک زمینه SSL جدید ایجاد کنید. می‌توانید protocol را ارسال کنید که باید یکی از ثابت‌های PROTOCOL_* تعریف‌شده در این ماژول باشد. این پارامتر مشخص می‌کند که از کدام نسخه از پروتکل SSL استفاده شود. معمولاً، سرور یک نسخه خاص از پروتکل را انتخاب می‌کند و کلاینت باید خود را با انتخاب سرور سازگار کند. بیشتر نسخه‌ها با سایر نسخه‌ها تعامل‌پذیر نیستند. اگر مشخص نشده باشد، مقدار پیش‌فرض PROTOCOL_TLS است؛ این مقدار بیشترین سازگاری را با سایر نسخه‌ها فراهم می‌کند.

در اینجا جدولی آمده است که نشان می‌دهد کدام نسخه‌ها در یک کلاینت (در ستون کناری) می‌توانند به کدام نسخه‌ها در یک سرور (در ردیف بالایی) متصل شوند:

کلاینت / سرور	SSLv2	SSLv3	TLS [3]	TLSv1	TLSv1.1	TLSv1.2
SSLv2	بله	خیر	خیر [1]	خیر	خیر	خیر
SSLv3	خیر	بله	خیر [2]	خیر	خیر	خیر
TLS (SSLv23) [3]	خیر [1]	خیر [2]	بله	بله	بله	بله
TLSv1	خیر	خیر	بله	بله	خیر	خیر
TLSv1.1	خیر	خیر	بله	خیر	بله	خیر
TLSv1.2	خیر	خیر	بله	خیر	خیر	بله

پانویس‌ها

همچنین ببینید

create_default_context() به ماژول ssl اجازه می‌دهد تنظیمات امنیتی را برای منظوری مشخص انتخاب کند.

تغییر یافته در نسخه‌ی 3.6: زمینه با مقادیر پیش‌فرض امن ایجاد می‌شود. گزینه‌های OP_NO_COMPRESSION، OP_CIPHER_SERVER_PREFERENCE، OP_SINGLE_DH_USE، OP_SINGLE_ECDH_USE، OP_NO_SSLv2 و OP_NO_SSLv3 (به‌جز PROTOCOL_SSLv3) به‌طور پیش‌فرض تنظیم شده‌اند. فهرست اولیه‌ی مجموعه‌رمزها فقط شامل رمزهای HIGH است و هیچ رمز NULL و هیچ رمز MD5 ندارد.

منسوخ شده از نسخه‌ی 3.10: SSLContext بدون آرگومان پروتکل منسوخ شده است. کلاس زمینه در آینده به پروتکل PROTOCOL_TLS_CLIENT یا PROTOCOL_TLS_SERVER نیاز خواهد داشت.

تغییر یافته در نسخه‌ی 3.10: مجموعه‌های رمزنگاری پیش‌فرض اکنون فقط شامل رمزهای امن AES و ChaCha20 با رازداری پیش‌رو (forward secrecy) و سطح امنیت ۲ هستند. کلیدهای RSA و DH با کمتر از ۲۰۴۸ بیت و کلیدهای ECC با کمتر از ۲۲۴ بیت ممنوع هستند. PROTOCOL_TLS، PROTOCOL_TLS_CLIENT و PROTOCOL_TLS_SERVER از TLS 1.2 به‌عنوان حداقل نسخه‌ی TLS استفاده می‌کنند.

نکته

SSLContext پس از آنکه توسط یک اتصال استفاده شد، تنها تغییر محدودی را می‌پذیرد. افزودن گواهی‌های جدید به مخزن اعتماد داخلی مجاز است، اما تغییر رمزها، تنظیمات صحت‌سنجی، یا گواهی‌های mTLS ممکن است منجر به رفتار غیرمنتظره شود.

نکته

SSLContext برای اشتراک‌گذاری و استفاده توسط چندین اتصال طراحی شده است. بنابراین، تا زمانی که پس از استفاده توسط یک اتصال پیکربندی مجدد نشود، ایمن از نظر نخی است.

اشیای SSLContext دارای متدها و ویژگی‌های زیر هستند:

SSLContext.cert_store_stats()¶

آمار مربوط به تعداد گواهی‌های X.509 بارگذاری‌شده، تعداد گواهی‌های X.509 علامت‌گذاری‌شده به‌عنوان گواهی CA و فهرست‌های ابطال گواهی را به‌صورت دیکشنری دریافت کنید.

مثالی برای یک زمینه با یک گواهی CA و یک گواهی دیگر:

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

اضافه شده در نسخه‌ی 3.4.

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

یک کلید خصوصی و گواهی مربوطه را بارگذاری می‌کند. رشته‌ی certfile باید مسیر یک پرونده واحد در قالب PEM حاوی گواهی و همچنین هر تعداد گواهی CA مورد نیاز برای احراز اصالت گواهی باشد. رشته‌ی keyfile، در صورت وجود، باید به پرونده‌ای حاوی کلید خصوصی اشاره کند. در غیر این صورت، کلید خصوصی نیز از certfile گرفته می‌شود. برای اطلاعات بیشتر درباره‌ی نحوه‌ی ذخیره‌ی گواهی در certfile، مبحث گواهی‌ها را ببینید.

آرگومان password می‌تواند تابعی باشد که برای دریافت گذرواژه جهت رمزگشایی کلید خصوصی فراخوانی می‌شود. این تابع فقط در صورتی فراخوانی خواهد شد که کلید خصوصی رمزنگاری‌شده باشد و به یک گذرواژه نیاز باشد. این تابع بدون آرگومان فراخوانی می‌شود و باید یک رشته، bytes یا bytearray برگرداند. اگر مقدار بازگشتی یک رشته باشد، پیش از استفاده از آن برای رمزگشایی کلید، به‌صورت UTF-8 کدگذاری خواهد شد. به‌عنوان جایگزین، می‌توان یک مقدار رشته، bytes یا bytearray را مستقیماً به‌عنوان آرگومان password ارائه کرد. اگر کلید خصوصی رمزنگاری‌نشده باشد و نیازی به گذرواژه نباشد، این مقدار نادیده گرفته خواهد شد.

اگر آرگومان password تعیین نشده باشد و به یک گذرواژه نیاز باشد، از سازوکار توکار درخواست گذرواژه در OpenSSL برای درخواست تعاملی گذرواژه از کاربر استفاده می‌شود.

اگر کلید خصوصی با گواهی مطابقت نداشته باشد، یک SSLError پرتاب می‌شود.

تغییر یافته در نسخه‌ی 3.3: آرگومان اختیاری جدید password.

SSLContext.load_default_certs(purpose=Purpose.SERVER_AUTH)¶

بارگذاری مجموعه‌ای از گواهی‌های پیش‌فرض «مرجع صدور گواهی» (CA) از مکان‌های پیش‌فرض. در ویندوز، گواهی‌های CA را از مخزن‌های سیستمی CA و ROOT بارگذاری می‌کند. در تمام سیستم‌ها، SSLContext.set_default_verify_paths() را فراخوانی می‌کند. در آینده، این متد ممکن است گواهی‌های CA را از مکان‌های دیگر نیز بارگذاری کند.

پرچم purpose مشخص می‌کند که چه نوع گواهی‌های CA بارگذاری شوند. تنظیم پیش‌فرض Purpose.SERVER_AUTH گواهی‌هایی را بارگذاری می‌کند که برای احراز هویت سرور وب TLS (سوکت‌های سمت کلاینت) علامت‌گذاری شده‌اند و مورد اعتماد هستند. Purpose.CLIENT_AUTH گواهی‌های CA را برای تأیید گواهی کلاینت در سمت سرور بارگذاری می‌کند.

اضافه شده در نسخه‌ی 3.4.

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

مجموعه‌ای از گواهی‌های «مرجع صدور گواهی» (CA) را بارگذاری می‌کند که برای اعتبارسنجی گواهی‌های سایر همتایان، هنگامی که verify_mode مقداری غیر از CERT_NONE باشد، استفاده می‌شوند. حداقل یکی از cafile یا capath باید مشخص شود.

این متد همچنین می‌تواند فهرست‌های لغو گواهی (CRL) را در قالب PEM یا DER بارگذاری کند. برای استفاده از CRLها، باید SSLContext.verify_flags به‌درستی پیکربندی شود.

رشته‌ی cafile، در صورت وجود، مسیر یک پرونده حاوی گواهی‌های CA به‌هم‌پیوسته در قالب PEM است. برای اطلاعات بیشتر درباره‌ی نحوه‌ی چیدمان گواهی‌ها در این پرونده، بحث گواهی‌ها را ببینید.

رشته‌ی capath، در صورت وجود، مسیر پوشه‌ای است که شامل چندین گواهی CA در قالب PEM است و از چیدمان خاص OpenSSL پیروی می‌کند.

شیء cadata، در صورت وجود، یا یک رشته‌ی ASCII از یک یا چند گواهی کدگذاری‌شده با PEM است یا یک bytes-like object از گواهی‌های کدگذاری‌شده با DER. مانند capath، سطرهای اضافی اطراف گواهی‌های کدگذاری‌شده با PEM نادیده گرفته می‌شوند، اما حداقل یک گواهی باید موجود باشد.

تغییر یافته در نسخه‌ی 3.4: آرگومان اختیاری جدید cadata

SSLContext.get_ca_certs(binary_form=False)¶

فهرستی از گواهی‌های بارگذاری‌شده‌ی «مرجع صدور گواهی» (CA) را دریافت کنید. اگر پارامتر binary_form برابر False باشد، هر آیتم فهرست یک دیکشنری مانند خروجی SSLSocket.getpeercert() است. در غیر این صورت، متد فهرستی از گواهی‌های کدگذاری‌شده با DER را برمی‌گرداند. فهرست برگردانده‌شده شامل گواهی‌های capath نمی‌شود، مگر اینکه گواهی‌ای توسط یک اتصال SSL درخواست و بارگذاری شده باشد.

نکته

گواهی‌های موجود در یک پوشه capath بارگذاری نمی‌شوند، مگر اینکه حداقل یک بار استفاده شده باشند.

اضافه شده در نسخه‌ی 3.4.

SSLContext.get_ciphers()¶

فهرستی از رمزنگارهای فعال را دریافت کنید. این فهرست به ترتیب اولویت رمزنگارها مرتب شده است. 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.get_groups(*, include_aliases=False)¶

فهرستی از گروه‌های پیاده‌سازی‌شده برای توافق کلید را با در نظر گرفتن مقادیر کنونی minimum_version و maximum_version مربوط به TLS دریافت کنید. برای نمونه:

>>> ctx = ssl.create_default_context()
>>> ctx.minimum_version = ssl.TLSVersion.TLSv1_3
>>> ctx.maximum_version = ssl.TLSVersion.TLSv1_3
>>> ctx.get_groups()
['secp256r1', 'secp384r1', 'secp521r1', 'x25519', 'x448', ...]

به طور پیش‌فرض، این متد فقط نام‌های ترجیحی IANA را برای گروه‌های موجود برمی‌گرداند. با این حال، اگر پارامتر include_aliases روی True تنظیم شود، این متد هرگونه نام مستعار مرتبط مانند نام‌های منحنی ECDH پشتیبانی‌شده در نسخه‌های قدیمی‌تر OpenSSL را نیز برخواهد گرداند.

اضافه شده در نسخه‌ی 3.15.

SSLContext.set_default_verify_paths()¶

بارگذاری مجموعه‌ای از گواهی‌های پیش‌فرض «مرجع صدور گواهی» (CA) از یک مسیر سامانه فایل‌بندی که هنگام ساخت کتابخانه OpenSSL تعریف شده است. متأسفانه، راه آسانی برای اطلاع از موفقیت این متد وجود ندارد: اگر هیچ گواهی‌ای یافت نشود، هیچ خطایی بازگردانده نمی‌شود. با این حال، وقتی کتابخانه OpenSSL به‌عنوان بخشی از سیستم‌عامل ارائه شده باشد، احتمالاً به‌درستی پیکربندی شده است.

SSLContext.set_ciphers(ciphers, /)¶

رمزهای مجاز را برای سوکت‌های ایجادشده با این زمینه هنگام اتصال با استفاده از TLS 1.2 و نسخه‌های پیشین تنظیم کنید. آرگومان ciphers باید رشته‌ای در قالب OpenSSL cipher list format باشد. برای تنظیم رمزهای مجاز TLS 1.3، از SSLContext.set_ciphersuites() استفاده کنید.

اگر هیچ رمز (cipher) قابل انتخابی وجود نداشته باشد (به این دلیل که گزینه‌های زمان کامپایل یا پیکربندی‌های دیگر استفاده از تمام رمزهای مشخص‌شده را ممنوع کرده‌اند)، یک SSLError بالا برده می‌شود.

نکته

هنگام اتصال، متد SSLSocket.cipher() سوکت‌های SSL جزئیاتی را درباره‌ی رمز مذاکره‌شده بازخواهد گرداند.

SSLContext.set_ciphersuites(ciphersuites, /)¶

رمزهای مجاز را برای سوکت‌های ایجادشده با این زمینه هنگام اتصال با استفاده از TLS 1.3 تنظیم کنید. آرگومان ciphersuites باید رشته‌ای جدا شده با دو نقطه از نام رمزهای TLS 1.3 باشد. اگر هیچ رمزی انتخاب نشود (به‌دلیل اینکه گزینه‌های زمان کامپایل یا پیکربندی‌های دیگر استفاده از تمام رمزهای مشخص‌شده را ممنوع می‌کنند)، یک SSLError بالا آورده خواهد شد.

نکته

هنگام اتصال، متد SSLSocket.cipher() سوکت‌های SSL جزئیاتی را درباره‌ی رمز مذاکره‌شده بازخواهد گرداند.

اضافه شده در نسخه‌ی 3.15.

SSLContext.set_groups(groups, /)¶

گروه‌های مجاز برای توافق کلید را برای سوکت‌های ایجادشده با این زمینه تنظیم کنید. این مقدار باید یک رشته در قالب OpenSSL group list format باشد.

نکته

هنگام اتصال، متد SSLSocket.group() سوکت‌های SSL گروه استفاده‌شده برای توافق کلید روی آن اتصال را بازخواهد گرداند.

اضافه شده در نسخه‌ی 3.15.

SSLContext.set_client_sigalgs(sigalgs, /)¶

الگوریتم‌های امضای مجاز برای احراز هویت کلاینت مبتنی بر گواهی را تنظیم کنید. این مقدار باید یک رشته در قالب OpenSSL client sigalgs list format باشد.

نکته

هنگام اتصال، متد SSLSocket.client_sigalg() سوکت‌های SSL الگوریتم امضای استفاده‌شده برای انجام احراز هویت کلاینت مبتنی بر گواهی روی آن اتصال را بازخواهد گرداند.

اضافه شده در نسخه‌ی 3.15.

SSLContext.set_server_sigalgs(sigalgs, /)¶

الگوریتم‌های امضای مجاز برای سرور جهت تکمیل دست‌دهی TLS را تنظیم کنید. این مقدار باید یک رشته در قالب OpenSSL sigalgs list format باشد.

نکته

هنگام اتصال، متد SSLSocket.server_sigalg() سوکت‌های SSL الگوریتم امضای استفاده‌شده توسط سرور برای تکمیل دست‌دهی TLS روی آن اتصال را بازخواهد گرداند.

اضافه شده در نسخه‌ی 3.15.

SSLContext.set_alpn_protocols(alpn_protocols)¶

مشخص کنید که سوکت باید در طول دست‌دهی SSL/TLS کدام پروتکل‌ها را اعلام کند. این باید فهرستی از رشته‌های ASCII، مانند ['http/1.1', 'spdy/2']، مرتب‌شده بر اساس ترجیح باشد. انتخاب یک پروتکل در طول دست‌دهی انجام خواهد شد و مطابق RFC 7301 صورت خواهد گرفت. پس از یک دست‌دهی موفق، متد SSLSocket.selected_alpn_protocol() پروتکل توافق‌شده را برمی‌گرداند.

اگر HAS_ALPN برابر False باشد، این متد NotImplementedError را پرتاب خواهد کرد.

اضافه شده در نسخه‌ی 3.5.

SSLContext.set_npn_protocols(npn_protocols)¶

مشخص کنید که سوکت باید در حین دست‌دهی SSL/TLS کدام پروتکل‌ها را اعلام کند. این باید فهرستی از رشته‌ها باشد، مانند ['http/1.1', 'spdy/2']، که به ترتیب اولویت مرتب‌شده است. انتخاب یک پروتکل در حین دست‌دهی انجام خواهد شد و مطابق Application Layer Protocol Negotiation صورت خواهد گرفت. پس از یک دست‌دهی موفق، متد SSLSocket.selected_npn_protocol() پروتکل توافق‌شده را برمی‌گرداند.

اگر HAS_NPN برابر False باشد، این متد NotImplementedError را پرتاب می‌کند.

اضافه شده در نسخه‌ی 3.3.

منسوخ شده از نسخه‌ی 3.10: NPN با ALPN جایگزین شده است

SSLContext.sni_callback¶

یک تابع کال‌بک را ثبت کنید که پس از دریافت پیام دست‌دهی TLS Client Hello توسط سرور SSL/TLS، هنگامی که کلاینت TLS نشانگر نام سرور (Server Name Indication) را مشخص کرده باشد، فراخوانی می‌شود. سازوکار نشانگر نام سرور در بخش ۳ از RFC 6066 با عنوان Server Name Indication مشخص شده است.

برای هر SSLContext تنها می‌توان یک کال‌بک تنظیم کرد. اگر sni_callback روی None تنظیم شود، کال‌بک غیرفعال می‌شود. فراخوانی مجدد این تابع، کال‌بک ثبت‌شده‌ی پیشین را غیرفعال خواهد کرد.

تابع کال‌بک با ۳ آرگومان فراخوانی می‌شود؛ اولی ssl.SSLSocket است، دومی رشته‌ای است که نام سرور مورد نظر کلاینت برای برقراری ارتباط را نشان می‌دهد (یا اگر TLS Client Hello حاوی نام سرور نباشد، None) و آرگومان سوم SSLContext اصلی است. آرگومان نام سرور متن است. برای IDN، نام سرور یک IDN A-label است ("xn--pythn-mua.org").

یک کاربرد رایج این کال‌بک، تغییر ویژگی SSLSocket.context مربوط به ssl.SSLSocket به شیء جدیدی از نوع SSLContext است که نشان‌دهنده‌ی زنجیره‌ی گواهی‌ای است که با نام سرور مطابقت دارد.

اگر کال‌بک یک زمینه‌ی جدید به SSLSocket.context اختصاص دهد، هرگونه پیام ClientHello بعدی روی همان اتصال (برای مثال پس از یک TLS 1.3 HelloRetryRequest) به sni_callback زمینه‌ی جدید فرستاده می‌شود، اگر زمینه‌ی مذکور آن را داشته باشد؛ کال‌بک اصلی دیگر برای آن اتصال فراخوانی نمی‌شود.

به دلیل مرحله‌ی اولیه‌ی مذاکره‌ی اتصال TLS، تنها متدها و ویژگی‌های محدودی قابل استفاده هستند، مانند SSLSocket.selected_alpn_protocol() و SSLSocket.context. متدهای SSLSocket.getpeercert()، SSLSocket.get_verified_chain()، SSLSocket.get_unverified_chain()، SSLSocket.cipher() و SSLSocket.compression() نیاز دارند که اتصال TLS از TLS Client Hello فراتر رفته باشد؛ بنابراین نه مقادیر معناداری برمی‌گردانند و نه می‌توان آن‌ها را به‌طور امن فراخوانی کرد.

تابع sni_callback باید None را برگرداند تا اجازه دهد مذاکره TLS ادامه یابد. اگر نیاز به شکست TLS باشد، می‌توان یک ثابت ALERT_DESCRIPTION_* را برگرداند. مقادیر بازگشتی دیگر باعث خطای مهلک TLS با ALERT_DESCRIPTION_INTERNAL_ERROR خواهند شد.

اگر استثنایی از تابع sni_callback پرتاب شود، اتصال TLS با یک پیام هشدار وخیم TLS ALERT_DESCRIPTION_HANDSHAKE_FAILURE خاتمه می‌یابد.

اگر OPENSSL_NO_TLSEXT هنگام ساخت کتابخانه OpenSSL تعریف‌شده باشد، این متد NotImplementedError را پرتاب خواهد کرد.

اضافه شده در نسخه‌ی 3.7.

تغییر یافته در نسخه‌ی 3.15: پس از اینکه کال‌بک یک SSLSocket.context جدید اختصاص داد، پیام‌های ClientHello بعدی روی اتصال به sni_callback زمینه‌ی جدید فرستاده می‌شوند.

SSLContext.set_servername_callback(server_name_callback)¶

این یک API قدیمی است که برای سازگاری با نسخه‌های قبلی حفظ شده است. در صورت امکان، باید به‌جای آن از sni_callback استفاده کنید. server_name_callback داده‌شده مشابه sni_callback است، با این تفاوت که وقتی نام میزبان سرور یک IDN کدگذاری‌شده با IDN باشد، server_name_callback یک U-label کدگشایی‌شده را دریافت می‌کند ("pythön.org").

اگر در کدگشایی نام سرور خطایی رخ دهد، اتصال TLS با یک پیام هشدار مهلک TLS ALERT_DESCRIPTION_INTERNAL_ERROR به کلاینت خاتمه خواهد یافت.

اضافه شده در نسخه‌ی 3.4.

SSLContext.load_dh_params(dhfile, /)¶

پارامترهای تولید کلید برای تبادل کلید Diffie-Hellman (DH) را بارگذاری کنید. استفاده از تبادل کلید DH، رازداری پیش‌رو (forward secrecy) را به بهای مصرف منابع محاسباتی (هم در سمت سرور و هم در سمت کلاینت) بهبود می‌بخشد. پارامتر dhfile باید مسیر پرونده‌ای حاوی پارامترهای DH در قالب PEM باشد.

این تنظیم به سوکت‌های کلاینت اعمال نمی‌شود. همچنین می‌توانید از گزینه OP_SINGLE_DH_USE برای بهبود بیشتر امنیت استفاده کنید.

اضافه شده در نسخه‌ی 3.3.

SSLContext.set_ecdh_curve(curve_name, /)¶

نام منحنی را برای تبادل کلید دیفی-هلمن مبتنی بر منحنی بیضوی (ECDH) تنظیم کنید. ECDH به‌طور قابل‌توجهی سریع‌تر از DH معمولی است، در حالی که می‌توان گفت به همان اندازه امن است. پارامتر curve_name باید رشته‌ای باشد که یک منحنی بیضوی شناخته‌شده را توصیف می‌کند، برای مثال prime256v1 برای منحنی‌ای که به‌طور گسترده پشتیبانی می‌شود.

این تنظیم برای سوکت‌های کلاینت اعمال نمی‌شود. همچنین می‌توانید از گزینه OP_SINGLE_ECDH_USE برای بهبود بیشتر امنیت استفاده کنید.

اگر HAS_ECDH برابر False باشد، این متد در دسترس نیست.

اضافه شده در نسخه‌ی 3.3.

همچنین ببینید

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

سوکت پایتون موجود sock را می‌پیچد و نمونه‌ای از SSLContext.sslsocket_class (پیش‌فرض SSLSocket) را برمی‌گرداند. سوکت SSL برگردانده‌شده به زمینه، تنظیمات و گواهی‌های آن وابسته است. sock باید یک سوکت SOCK_STREAM باشد؛ سایر انواع سوکت پشتیبانی نمی‌شوند.

پارامتر server_side یک بولی است که مشخص می‌کند آیا رفتار سمت سرور یا رفتار سمت کلاینت از این سوکت مورد انتظار است.

برای سوکت‌های سمت کلاینت، ساخت زمینه با تأخیر انجام می‌شود؛ اگر سوکت زیرین هنوز متصل نشده باشد، ساخت زمینه پس از فراخوانی connect() روی سوکت انجام خواهد شد. برای سوکت‌های سمت سرور، اگر سوکت همتای راه دوری نداشته باشد، فرض می‌شود که یک سوکت شنود است، و پیچیدن SSL در سمت سرور به‌طور خودکار روی اتصال‌های کلاینت پذیرفته‌شده از طریق متد accept() انجام می‌شود. این متد ممکن است SSLError را پرتاب کند.

در اتصال‌های کلاینت، پارامتر اختیاری server_hostname نام میزبان سرویسی را که به آن متصل می‌شویم مشخص می‌کند. این به یک سرور واحد امکان می‌دهد تا چندین سرویس مبتنی بر SSL با گواهی‌های متمایز را میزبانی کند، بسیار مشابه میزبان‌های مجازی HTTP. مشخص کردن server_hostname در صورتی که server_side برابر true باشد، باعث پرتاب ValueError می‌شود.

پارامتر do_handshake_on_connect مشخص می‌کند که آیا دست‌دهی SSL (SSL handshake) به‌طور خودکار پس از انجام socket.connect() انجام شود، یا اینکه برنامه کاربردی آن را به‌صورت صریح با فراخوانی متد SSLSocket.do_handshake() فراخوانی خواهد کرد. فراخوانی صریح SSLSocket.do_handshake() کنترل رفتار مسدودسازی ورودی/خروجی سوکت درگیر در دست‌دهی را به برنامه می‌دهد.

پارامتر suppress_ragged_eofs مشخص می‌کند که متد SSLSocket.recv() باید EOF غیرمنتظره از سوی دیگر اتصال را چگونه اعلام کند. اگر به‌صورت True (پیش‌فرض) مشخص شده باشد، در پاسخ به خطاهای EOF غیرمنتظره که از سوکت زیرین پرتاب می‌شوند، یک EOF معمولی (یک شیء bytes خالی) را برمی‌گرداند؛ اگر False باشد، استثناها را به فراخواننده پرتاب خواهد کرد.

session، session را ببینید.

برای دربرگرفتن یک SSLSocket در یک SSLSocket دیگر، از SSLContext.wrap_bio() استفاده کنید.

تغییر یافته در نسخه‌ی 3.5: همیشه اجازه دهید server_hostname ارسال شود، حتی اگر OpenSSL فاقد SNI باشد.

تغییر یافته در نسخه‌ی 3.6: آرگومان session افزوده شد.

تغییر یافته در نسخه‌ی 3.7: این متد به‌جای SSLSocket سخت‌کدشده، نمونه‌ای از SSLContext.sslsocket_class را برمی‌گرداند.

SSLContext.sslsocket_class¶

نوع بازگشتی SSLContext.wrap_socket()، به‌طور پیش‌فرض SSLSocket است. می‌توان این ویژگی را در نمونه‌های SSLContext مقداردهی کرد تا یک زیرکلاس سفارشی از SSLSocket بازگردانده شود.

اضافه شده در نسخه‌ی 3.7.

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

اشیای BIO incoming و outgoing را دربرمی‌گیرد و نمونه‌ای از SSLContext.sslobject_class (پیش‌فرض SSLObject) برمی‌گرداند. روال‌های SSL داده‌های ورودی را از BIO ورودی می‌خوانند و داده‌ها را در BIO خروجی می‌نویسند.

پارامترهای server_side، server_hostname و session معنایی مشابه با SSLContext.wrap_socket() دارند و به همان شکل اعتبارسنجی می‌شوند: به‌ویژه هنگامی که check_hostname فعال است اما هیچ server_hostnameی داده نشده است، یک ValueError بالا آورده می‌شود، زیرا هیچ نامی برای مطابقت دادن با گواهی همتا وجود نخواهد داشت.

تغییر یافته در نسخه‌ی 3.6: آرگومان session افزوده شد.

تغییر یافته در نسخه‌ی 3.7: این متد به‌جای SSLObject سخت‌کد، نمونه‌ای از SSLContext.sslobject_class را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.15: پارامترهای server_side، server_hostname و session اکنون مانند روشی که SSLContext.wrap_socket() آن‌ها را اعتبارسنجی می‌کند، اعتبارسنجی می‌شوند. پیش‌تر، یک زمینه با check_hostname فعال و بدون server_hostname پذیرفته می‌شد و زنجیره‌ی گواهی را تأیید می‌کرد اما هرگز هویت همتا را بررسی نمی‌کرد.

SSLContext.sslobject_class¶

نوع بازگشتی SSLContext.wrap_bio()، به‌طور پیش‌فرض SSLObject است. می‌توان این ویژگی را در نمونه‌ای از کلاس بازنویسی کرد تا یک زیرکلاس سفارشی از SSLObject بازگردانده شود.

اضافه شده در نسخه‌ی 3.7.

SSLContext.session_stats()¶

آمار نشست‌های SSL ایجادشده یا مدیریت‌شده توسط این زمینه را دریافت کنید. یک دیکشنری بازگردانده می‌شود که نام هر قطعه‌ای از اطلاعات را به مقدار عددی آن نگاشت می‌کند. برای مثال، در اینجا تعداد کل برخوردها و عدم‌برخوردها در نهانگاه نشست از زمان ایجاد زمینه آمده است:

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

SSLContext.check_hostname¶

اینکه آیا باید نام میزبان گواهی همتا در SSLSocket.do_handshake() تطبیق داده شود یا خیر. verify_mode زمینه باید روی CERT_OPTIONAL یا CERT_REQUIRED تنظیم شده باشد و شما باید برای تطبیق نام میزبان، server_hostname را به wrap_socket() ارسال کنید. فعال‌سازی بررسی نام میزبان، verify_mode را به‌طور خودکار از CERT_NONE به CERT_REQUIRED تنظیم می‌کند. تا زمانی که بررسی نام میزبان فعال است، نمی‌توان آن را دوباره روی CERT_NONE تنظیم کرد. پروتکل PROTOCOL_TLS_CLIENT بررسی نام میزبان را به‌صورت پیش‌فرض فعال می‌کند. در پروتکل‌های دیگر، بررسی نام میزبان باید به‌صورت صریح فعال شود.

مثال:

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 باشد، verify_mode به‌طور خودکار به CERT_REQUIRED تغییر می‌کند. پیش‌تر، همین عملیات با یک ValueError شکست می‌خورد.

SSLContext.keylog_filename¶

کلیدهای TLS را هر زمان که ماده‌ی کلید (key material) تولید یا دریافت شود، در یک پرونده گزارش کلید (keylog file) می‌نویسد. پرونده گزارش کلید فقط برای اهداف اشکال‌زدایی طراحی شده است. قالب پرونده توسط NSS مشخص شده است و توسط بسیاری از تحلیل‌گرهای ترافیک مانند Wireshark استفاده می‌شود. پرونده گزارش در حالت فقط-افزودنی (append-only) باز می‌شود. نوشتن‌ها بین نخ‌ها همگام‌سازی می‌شوند، اما بین فرآیندها همگام‌سازی نمی‌شوند.

اضافه شده در نسخه‌ی 3.8.

SSLContext.maximum_version¶

یک عضو enum از TLSVersion که نشان‌دهنده‌ی بالاترین نسخه‌ی پشتیبانی‌شده‌ی TLS است. مقدار آن به‌طور پیش‌فرض برابر با TLSVersion.MAXIMUM_SUPPORTED است. این ویژگی برای پروتکل‌هایی غیر از PROTOCOL_TLS، PROTOCOL_TLS_CLIENT و PROTOCOL_TLS_SERVER فقط‌خواندنی است.

ویژگی‌های maximum_version، minimum_version و SSLContext.options همگی بر نسخه‌های پشتیبانی‌شده‌ی SSL و TLS زمینه اثر می‌گذارند. پیاده‌سازی از ترکیب‌های نامعتبر جلوگیری نمی‌کند. برای مثال، زمینه‌ای که در options آن OP_NO_TLSv1_2 وجود دارد و maximum_version آن روی TLSVersion.TLSv1_2 تنظیم شده است، نمی‌تواند یک اتصال TLS 1.2 برقرار کند.

اضافه شده در نسخه‌ی 3.7.

SSLContext.minimum_version¶

مانند SSLContext.maximum_version است، با این تفاوت که پایین‌ترین نسخه پشتیبانی‌شده یا TLSVersion.MINIMUM_SUPPORTED است.

اضافه شده در نسخه‌ی 3.7.

SSLContext.num_tickets¶

تعداد بلیت‌های نشست (session tickets) TLS 1.3 برای یک زمینه PROTOCOL_TLS_SERVER را کنترل کنید. این تنظیم تأثیری بر اتصالات TLS 1.0 تا 1.2 ندارد.

اضافه شده در نسخه‌ی 3.8.

SSLContext.options¶

عدد صحیحی که مجموعه‌ی گزینه‌های SSL فعال در این زمینه را نشان می‌دهد. مقدار پیش‌فرض OP_ALL است، اما می‌توانید گزینه‌های دیگری مانند OP_NO_SSLv2 را با OR کردن آن‌ها با یکدیگر مشخص کنید.

تغییر یافته در نسخه‌ی 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: همه‌ی گزینه‌های OP_NO_SSL* و OP_NO_TLS* از پایتون 3.7 منسوخ شده‌اند. در عوض از SSLContext.minimum_version و SSLContext.maximum_version استفاده کنید.

SSLContext.post_handshake_auth¶

احراز هویت کلاینت پس از دست‌دهی (post-handshake) در TLS 1.3 را فعال کنید. احراز هویت پس از دست‌دهی به‌طور پیش‌فرض غیرفعال است و یک سرور تنها می‌تواند در حین دست‌دهی اولیه، یک گواهی کلاینت TLS را درخواست کند. هنگامی که فعال باشد، یک سرور می‌تواند در هر زمانی پس از دست‌دهی، یک گواهی کلاینت TLS را درخواست کند.

هنگامی که روی سوکت‌های سمت کلاینت فعال شود، کلاینت به سرور علامت می‌دهد که از احراز هویت پس از دست‌دهی (post-handshake authentication) پشتیبانی می‌کند.

هنگامی که در سوکت‌های سمت سرور فعال باشد، SSLContext.verify_mode نیز باید روی CERT_OPTIONAL یا CERT_REQUIRED تنظیم شود. تبادل واقعی گواهی کلاینت تا زمانی که SSLSocket.verify_client_post_handshake() فراخوانی شود و مقداری ورودی/خروجی انجام شود، به تعویق می‌افتد.

اضافه شده در نسخه‌ی 3.8.

SSLContext.protocol¶

نسخه‌ی پروتکل انتخاب‌شده هنگام ساخت زمینه. این ویژگی فقط‌خواندنی است.

SSLContext.hostname_checks_common_name¶

اینکه آیا check_hostname در نبود افزونه‌ی نام جایگزین موضوع، برای تأیید نام مشترک موضوع گواهی به‌عنوان حالت جایگزین عمل می‌کند یا خیر (پیش‌فرض: true).

اضافه شده در نسخه‌ی 3.7.

تغییر یافته در نسخه‌ی 3.10: این پرچم در OpenSSL پیش از نسخه 1.1.1l تاثیری نداشت. پایتون 3.8.9، 3.9.3 و 3.10 شامل راه‌حل‌های موقتی برای نسخه‌های پیشین هستند.

SSLContext.security_level¶

یک عدد صحیح که سطح امنیت زمینه را نشان می‌دهد. این ویژگی فقط‌خواندنی است.

اضافه شده در نسخه‌ی 3.10.

SSLContext.verify_flags¶

پرچم‌ها برای عملیات تأیید صحت گواهی. می‌توانید پرچم‌هایی مانند VERIFY_CRL_CHECK_LEAF را با OR کردن آن‌ها با یکدیگر تنظیم کنید. به‌طور پیش‌فرض، OpenSSL نه به فهرست‌های ابطال گواهی (CRLs) نیاز دارد و نه آن‌ها را تأیید صحت می‌کند.

اضافه شده در نسخه‌ی 3.4.

تغییر یافته در نسخه‌ی 3.6: SSLContext.verify_flags پرچم‌های VerifyFlags را برمی‌گرداند:

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

SSLContext.verify_mode¶

اینکه آیا باید برای تأیید گواهی‌های سایر همتایان تلاش شود و در صورت شکست تأیید، چگونه رفتار شود. این ویژگی باید یکی از CERT_NONE، CERT_OPTIONAL یا CERT_REQUIRED باشد.

تغییر یافته در نسخه‌ی 3.6: SSLContext.verify_mode یک enum از VerifyMode برمی‌گرداند:

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

SSLContext.set_psk_client_callback(callback)¶

احراز هویت TLS-PSK (کلید از پیش اشتراک‌گذاشته‌شده) را روی یک اتصال سمت کلاینت فعال می‌کند.

به‌طور کلی، احراز هویت مبتنی بر گواهی باید بر این روش ترجیح داده شود.

پارامتر callback یک شیء فراخوانی‌پذیر با امضای زیر است: def callback(hint: str | None) -> tuple[str | None, bytes]. پارامتر hint یک راهنمای هویت اختیاری است که توسط سرور ارسال می‌شود. مقدار بازگشتی یک تاپل به‌شکل (client-identity, psk) است. client-identity یک رشته اختیاری است که ممکن است سرور از آن برای انتخاب یک PSK متناظر برای کلاینت استفاده کند. این رشته باید هنگام کدگذاری با UTF-8 کمتر یا مساوی 256 هشت‌بیتی باشد. PSK یک bytes-like object است که کلید از پیش اشتراک‌گذاری‌شده را نشان می‌دهد. برای رد کردن اتصال، یک PSK با طول صفر برگردانید.

با تنظیم callback به None، هر کال‌بک موجود حذف می‌شود.

نکته

هنگام استفاده از TLS 1.3:

• پارامتر hint همیشه None است.

• client-identity باید یک رشته غیرخالی باشد.

• the PSK is only offered to the server, which may decline it and authenticate with a certificate instead. That certificate is checked according to verify_mode, so a client relying on the PSK to authenticate the server should not set it to CERT_NONE, or should check SSLSocket.session_reused, which is true if the PSK was used. A PSK handshake does not need any CA certificates to be loaded when using CERT_REQUIRED.

• a zero length PSK does not reject the connection, it only means that no PSK is offered. An exception raised by the callback has the same effect.

• the PSK is used with the SHA-256 handshake digest, so a server can only accept it with a cipher suite that uses SHA-256.

نمونه استفاده:

context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
context.check_hostname = False
context.verify_mode = ssl.CERT_NONE
context.maximum_version = ssl.TLSVersion.TLSv1_2
context.set_ciphers('PSK')

# A simple lambda:
psk = bytes.fromhex('c0ffee')
context.set_psk_client_callback(lambda hint: (None, psk))

# A table using the hint from the server:
psk_table = { 'ServerId_1': bytes.fromhex('c0ffee'),
              'ServerId_2': bytes.fromhex('facade')
}
def callback(hint):
    return 'ClientId_1', psk_table.get(hint, b'')
context.set_psk_client_callback(callback)

این متد در صورتی که HAS_PSK برابر False باشد، NotImplementedError را پرتاب خواهد کرد.

اضافه شده در نسخه‌ی 3.13.

SSLContext.set_psk_server_callback(callback, identity_hint=None)¶

احراز هویت TLS-PSK (کلید از پیش اشتراک‌گذاشته‌شده) را در یک اتصال سمت سرور فعال می‌کند.

به‌طور کلی، احراز هویت مبتنی بر گواهی باید بر این روش ترجیح داده شود.

پارامتر callback یک شیء فراخوانی‌پذیر با امضای def callback(identity: str | None) -> bytes است. پارامتر identity یک هویت اختیاری ارسال‌شده از سوی کلاینت است که می‌توان از آن برای انتخاب یک PSK متناظر استفاده کرد. مقدار بازگشتی یک bytes-like object است که کلید از پیش به اشتراک گذاشته‌شده را نشان می‌دهد. برای رد کردن اتصال، یک PSK با طول صفر برگردانید.

با تنظیم callback به None، هر کال‌بک موجود حذف می‌شود.

پارامتر identity_hint یک رشته‌ی راهنمای هویت اختیاری است که به کلاینت ارسال می‌شود. این رشته باید هنگام کدگذاری با UTF-8 کمتر یا مساوی 256 هشت‌بیتی باشد.

نکته

هنگام استفاده از TLS 1.3:

• هنگام استفاده از TLS 1.3، پارامتر identity_hint به کلاینت ارسال نمی‌شود.

• a zero length PSK, or an exception raised by the callback, only declines the client's PSK. If a certificate was loaded with load_cert_chain(), the handshake continues with certificate authentication instead of failing, so a server relying on the PSK to authenticate clients should not load one, or should check SSLSocket.session_reused, which is true if the PSK was used.

• the PSK can only be accepted with a cipher suite that uses SHA-256. When a certificate is loaded, OpenSSL's default TLS 1.3 cipher suite order selects a SHA-384 suite instead, so the PSK is declined even if it matches.

نمونه استفاده:

context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
context.maximum_version = ssl.TLSVersion.TLSv1_2
context.set_ciphers('PSK')

# A simple lambda:
psk = bytes.fromhex('c0ffee')
context.set_psk_server_callback(lambda identity: psk)

# A table using the identity of the client:
psk_table = { 'ClientId_1': bytes.fromhex('c0ffee'),
              'ClientId_2': bytes.fromhex('facade')
}
def callback(identity):
    return psk_table.get(identity, b'')
context.set_psk_server_callback(callback, 'ServerId_1')

این متد در صورتی که HAS_PSK برابر False باشد، NotImplementedError را پرتاب خواهد کرد.

اضافه شده در نسخه‌ی 3.13.

گواهی‌ها¶

گواهی‌ها به‌طور کلی بخشی از یک سیستم کلید عمومی / کلید خصوصی هستند. در این سیستم، به هر اصل (principal) (که ممکن است یک ماشین، یک شخص، یا یک سازمان باشد) یک کلید رمزنگاری دوبخشی یکتا اختصاص داده می‌شود. یک بخش از کلید عمومی است و کلید عمومی نامیده می‌شود؛ بخش دیگر مخفی نگه داشته می‌شود و کلید خصوصی نامیده می‌شود. این دو بخش با هم مرتبط هستند، به این معنا که اگر پیامی را با یکی از بخش‌ها رمزنگاری کنید، می‌توانید آن را با بخش دیگر رمزگشایی کنید، و فقط با بخش دیگر.

یک گواهی حاوی اطلاعاتی درباره دو طرف (principal) است. این گواهی حاوی نام یک موضوع و کلید عمومی آن موضوع است. همچنین حاوی اظهار طرف دوم، یعنی صادرکننده، است مبنی بر اینکه موضوع همان هویتی است که ادعا می‌کند، و اینکه این کلید واقعاً کلید عمومی موضوع است. اظهار اکسپورتکننده با کلید خصوصی اکسپورتکننده امضا شده است، که تنها صادرکننده آن را می‌داند. با این حال، هر کسی می‌تواند با یافتن کلید عمومی صادرکننده، رمزگشایی اظهار با آن کلید، و مقایسه آن با سایر اطلاعات موجود در گواهی، صحت اظهار صادرکننده را تأیید کند. گواهی همچنین حاوی اطلاعاتی درباره بازه زمانی اعتبار آن است. این موضوع به‌صورت دو فیلد با نام‌های "notBefore" و "notAfter" بیان می‌شود.

در کاربرد گواهی‌ها در پایتون، یک کلاینت یا سرور می‌تواند از یک گواهی برای اثبات هویت خود استفاده کند. همچنین می‌توان از طرف دیگر یک اتصال شبکه خواست که گواهی‌ای ارائه دهد، و آن گواهی می‌تواند تا حد رضایت کلاینت یا سروری که چنین اعتبارسنجی‌ای را لازم می‌داند، اعتبارسنجی شود. می‌توان تلاش اتصال را طوری تنظیم کرد که در صورت ناموفق بودن اعتبارسنجی، استثنایی پرتاب کند. اعتبارسنجی به‌طور خودکار توسط چارچوب OpenSSL زیرین انجام می‌شود؛ برنامه نیازی ندارد نگران سازوکار آن باشد. اما برنامه معمولاً نیاز دارد مجموعه‌هایی از گواهی‌ها را فراهم کند تا این فرایند انجام شود.

پایتون از پرونده‌ها برای نگهداری گواهی‌ها استفاده می‌کند. آن‌ها باید با قالب «PEM» باشند (به RFC 1422 مراجعه کنید)، که یک قالب کدگذاری‌شده به base-64 است و با یک خط سرآیند و یک خط پایانی احاطه شده است:

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

-----BEGIN CERTIFICATE-----
... (گواهی برای سرور شما)...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (گواهی برای CA)...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (گواهی ریشه برای صادرکننده CA)...
-----END CERTIFICATE-----

-----BEGIN RSA PRIVATE KEY-----
... (کلید خصوصی با کدگذاری base64) ...
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
... (گواهی با کدگذاری base64 PEM) ...
-----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

نکاتی درباره سوکت‌های غیرمسدود¶

سوکت‌های SSL در حالت غیرمسدودکننده (non-blocking) کمی متفاوت از سوکت‌های معمولی رفتار می‌کنند. بنابراین، هنگام کار با سوکت‌های غیرمسدودکننده، باید به چند نکته توجه داشته باشید:

• بیشتر متدهای SSLSocket در صورتی که یک عملیات ورودی/خروجی باعث مسدود شدن شود، به‌جای BlockingIOError، یا SSLWantWriteError یا SSLWantReadError را پرتاب می‌کنند. اگر یک عملیات خواندن روی سوکت زیرین لازم باشد، SSLWantReadError پرتاب می‌شود، و برای یک عملیات نوشتن روی سوکت زیرین، SSLWantWriteError پرتاب می‌شود. توجه داشته باشید که تلاش برای نوشتن در یک سوکت SSL ممکن است ابتدا به خواندن از سوکت زیرین نیاز داشته باشد، و تلاش برای خواندن از سوکت SSL ممکن است به یک نوشتن قبلی روی سوکت زیرین نیاز داشته باشد.

  تغییر یافته در نسخه‌ی 3.5: در نسخه‌های پیشین پایتون، متد SSLSocket.send() به‌جای پرتاب کردن SSLWantWriteError یا SSLWantReadError، صفر را برمی‌گرداند.

• فراخوانی select() به شما می‌گوید که سوکت در سطح سیستم‌عامل قابل خواندن (یا نوشتن) است، اما این به آن معنا نیست که داده کافی در لایه‌ی بالایی SSL وجود دارد. برای مثال، ممکن است تنها بخشی از یک فریم SSL رسیده باشد. بنابراین، باید آماده باشید تا شکست‌های SSLSocket.recv() و SSLSocket.send() را مدیریت کنید و پس از فراخوانی دیگری از select() دوباره تلاش کنید.

• در مقابل، از آن‌جا که لایه SSL چارچوب‌بندی خاص خود را دارد، ممکن است یک سوکت SSL هنوز داده‌ای برای خواندن در دسترس داشته باشد، بدون آنکه select() از آن آگاه باشد. بنابراین، ابتدا باید SSLSocket.recv() را فراخوانی کنید تا هر داده‌ای که ممکن است در دسترس باشد تخلیه شود، و سپس تنها در صورت لزوم، در یک فراخوانی select() مسدود شوید.

  (البته، ملاحظات مشابهی هنگام استفاده از سایر اولیه‌ها مانند poll() یا موارد موجود در ماژول selectors اعمال می‌شود)

• خود دست‌دهی SSL (SSL handshake) غیرمسدودکننده خواهد بود: متد SSLSocket.do_handshake() باید تا زمانی که با موفقیت بازگشت کند، دوباره فراخوانی شود. در اینجا خلاصه‌ای با استفاده از select() برای منتظر ماندن تا آماده شدن سوکت آمده است:

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

پشتیبانی از Memory BIO¶

از زمان معرفی ماژول SSL در Python 2.6، کلاس SSLSocket دو حوزه‌ی عملکردی مرتبط اما متمایز را ارائه کرده است:

• مدیریت پروتکل SSL

• ورودی/خروجی شبکه

API ورودی/خروجی شبکه دقیقاً مشابه API ارائه‌شده توسط socket.socket است که SSLSocket نیز از آن ارث‌بری می‌کند. این موضوع امکان استفاده از یک سوکت SSL به‌عنوان جایگزین مستقیم (drop-in replacement) برای یک سوکت معمولی را فراهم می‌کند و افزودن پشتیبانی SSL به یک برنامه موجود را بسیار آسان می‌سازد.

ترکیب مدیریت پروتکل SSL و ورودی/خروجی شبکه معمولاً به‌خوبی کار می‌کند، اما در برخی موارد این‌طور نیست. یک نمونه، چارچوب‌های ورودی/خروجی ناهمگام هستند که می‌خواهند از مدل متفاوتی برای تسهیم ورودی/خروجی (IO multiplexing) نسبت به مدل «select/poll روی توصیف‌گر پرونده» (مبتنی بر آمادگی) استفاده کنند؛ مدلی که توسط socket.socket و روال‌های داخلی ورودی/خروجی سوکت OpenSSL فرض می‌شود. این موضوع بیشتر برای سکوهایی مانند ویندوز مرتبط است که این مدل در آن‌ها کارآمد نیست. برای این منظور، گونه‌ای از SSLSocket با محدوده‌ای محدودتر به نام SSLObject ارائه شده است.

class ssl.SSLObject¶

یک نسخه با محدوده‌ی کاهش‌یافته از SSLSocket که نشان‌دهنده‌ی یک نمونه از پروتکل SSL است و فاقد هرگونه متد ورودی/خروجی شبکه است. این کلاس معمولاً توسط نویسندگان چارچوب‌هایی استفاده می‌شود که می‌خواهند ورودی/خروجی ناهمگام برای SSL را از طریق بافرهای حافظه پیاده‌سازی کنند.

این کلاس یک رابط را بر فراز یک شیء SSL سطح پایین، که OpenSSL آن را پیاده‌سازی کرده است، پیاده‌سازی می‌کند. این شیء وضعیت یک اتصال SSL را ثبت می‌کند، اما خود هیچ‌گونه ورودی/خروجی (IO) شبکه‌ای فراهم نمی‌کند. ورودی/خروجی باید از طریق اشیای "BIO" جداگانه انجام شود که لایه‌ی انتزاعی ورودی/خروجی OpenSSL هستند.

این کلاس سازنده‌ی عمومی ندارد. یک نمونه‌ی SSLObject باید با استفاده از متد wrap_bio() ایجاد شود. این متد نمونه‌ی SSLObject را ایجاد می‌کند و آن را به یک جفت BIO متصل می‌کند. BIO ورودی برای انتقال داده از پایتون به نمونه‌ی پروتکل SSL استفاده می‌شود، در حالی که BIO خروجی برای انتقال داده در جهت معکوس استفاده می‌شود.

متدهای زیر در دسترس هستند:

• context

• server_side

• server_hostname

• session

• session_reused

• read()

• write()

• getpeercert()

• get_verified_chain()

• get_unverified_chain()

• selected_alpn_protocol()

• selected_npn_protocol()

• cipher()

• shared_ciphers()

• compression()

• pending()

• do_handshake()

• verify_client_post_handshake()

• unwrap()

• get_channel_binding()

• version()

در مقایسه با SSLSocket، این شیء فاقد ویژگی‌های زیر است:

• هر شکلی از ورودی/خروجی شبکه؛ recv() و send() فقط از بافرهای زیربنایی MemoryBIO می‌خوانند و در آن‌ها می‌نویسند.

• هیچ سازوکاری برای do_handshake_on_connect وجود ندارد. شما باید همیشه do_handshake() را به‌صورت دستی فراخوانی کنید تا دست‌دهی آغاز شود.

• هیچ مدیریتی برای suppress_ragged_eofs وجود ندارد. تمام شرایط پایان پرونده که پروتکل را نقض می‌کنند، از طریق استثنا SSLEOFError گزارش می‌شوند.

• فراخوانی متد unwrap() چیزی برنمی‌گرداند، برخلاف یک سوکت SSL که در آن سوکت زیرین را برمی‌گرداند.

• کال‌بک server_name_callback که به SSLContext.set_servername_callback() ارسال می‌شود، به‌عنوان اولین پارامتر خود، یک نمونه SSLObject را به‌جای یک نمونه SSLSocket دریافت خواهد کرد.

چند نکته مرتبط با استفاده از SSLObject:

• تمام عملیات ورودی/خروجی روی یک SSLObject به صورت غیرمسدود است. این بدان معناست که برای مثال read() در صورتی استثنای SSLWantReadError را پرتاب می‌کند که به داده بیشتری نسبت به آنچه BIO ورودی در دسترس دارد نیاز داشته باشد.

تغییر یافته در نسخه‌ی 3.7: نمونه‌های SSLObject باید با wrap_bio() ایجاد شوند. در نسخه‌های پیشین، امکان ایجاد مستقیم نمونه‌ها وجود داشت. این کار هرگز مستند نشده بود و به‌طور رسمی پشتیبانی نمی‌شد.

یک SSLObject با استفاده از بافرهای حافظه با دنیای بیرون ارتباط برقرار می‌کند. کلاس MemoryBIO یک بافر حافظه فراهم می‌کند که می‌تواند برای این منظور استفاده شود. این کلاس یک شیء BIO حافظه‌ی OpenSSL (ورودی/خروجی پایه) را پوشش می‌دهد:

class ssl.MemoryBIO¶

یک بافر حافظه (memory buffer) که می‌توان از آن برای انتقال داده بین پایتون و یک نمونه از پروتکل SSL استفاده کرد.

pending¶

تعداد بایت‌های موجود در بافر حافظه را در حال حاضر برمی‌گرداند.

eof¶

یک بولی که نشان می‌دهد آیا BIO حافظه‌ای (memory BIO) در موقعیت پایان پرونده قرار دارد یا خیر.

read(n=-1, /)¶

حداکثر n بایت از بافر حافظه بخوانید. اگر n مشخص نشده باشد یا منفی باشد، تمام بایت‌ها برگردانده می‌شوند.

write(buf, /)¶

بایت‌های buf را در BIO حافظه‌ای (memory BIO) بنویسید. آرگومان buf باید شیء‌ای باشد که از پروتکل بافر پشتیبانی می‌کند.

مقدار بازگشتی تعداد بایت‌های نوشته‌شده است، که همیشه برابر با طول buf است.

write_eof()¶

یک نشانگر EOF را در BIO حافظه (memory BIO) می‌نویسد. پس از فراخوانی این متد، فراخوانی write() غیرمجاز است. ویژگی eof پس از خوانده شدن تمام داده‌های موجود در بافر، درست می‌شود.

نشست SSL¶

class ssl.SSLSession¶

شیء نشست که توسط session استفاده می‌شود.

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_2
>>> client_context.maximum_version = ssl.TLSVersion.TLSv1_3

TLS 1.3¶

پروتکل TLS 1.3 نسبت به نسخه‌ی قبلی TLS/SSL کمی متفاوت عمل می‌کند. برخی ویژگی‌های جدید TLS 1.3 هنوز در دسترس نیستند.

• پروتکل TLS 1.3 از مجموعه رمزهای مجزایی استفاده می‌کند. تمام مجموعه‌های رمز AES-GCM و ChaCha20 به‌طور پیش‌فرض فعال هستند. برای محدود کردن رمزهای مجاز TLS 1.3، باید متد SSLContext.set_ciphersuites() فراخوانی شود، نه SSLContext.set_ciphers() که فقط روی رمزهای موجود در نسخه‌های قدیمی‌تر TLS تأثیر می‌گذارد. متد SSLContext.get_ciphers() اطلاعاتی درباره‌ی رمزها برای هر دو نسخه‌ی TLS 1.3 و نسخه‌های پیشین برمی‌گرداند و متد SSLSocket.cipher() پس از برقراری اتصال، اطلاعاتی را درباره‌ی رمز توافق‌شده برای هر دو نسخه‌ی TLS 1.3 و نسخه‌های پیشین برمی‌گرداند.

• تیکت‌های نشست (session tickets) دیگر به‌عنوان بخشی از دست‌دهی اولیه ارسال نمی‌شوند و به‌شکل متفاوتی مدیریت می‌شوند. SSLSocket.session و SSLSession با TLS 1.3 سازگار نیستند.

• گواهی‌های سمت کلاینت نیز دیگر در حین دست‌دهی اولیه تأیید نمی‌شوند. یک سرور می‌تواند در هر زمان یک گواهی درخواست کند. کلاینت‌ها درخواست‌های گواهی را هنگامی که داده‌های کاربردی را ارسال می‌کنند یا از سرور دریافت می‌کنند، پردازش می‌کنند.

• ویژگی‌های TLS 1.3 مانند داده‌ی زودهنگام، درخواست گواهی کلاینت با تأخیر TLS و بازنشانی کلید هنوز پشتیبانی نمی‌شوند.