ssl --- پوششی TLS/SSL برای اشیای سوکت

کد منبع: Lib/ssl.py

---

این ماژول دسترسی به امکانات رمزنگاری و احراز هویت همتا در امنیت لایه انتقال (Transport Layer Security، که اغلب با نام «Secure Sockets Layer» شناخته می‌شود) را برای سوکت‌های شبکه، چه در سمت کلاینت و چه در سمت سرور، فراهم می‌کند. این ماژول از کتابخانه OpenSSL استفاده می‌کند.

این یک ماژول اختیاری است. اگر در نسخه CPython شما وجود ندارد، به مستندات توزیع‌کننده خود (یعنی کسی که پایتون را در اختیار شما قرار داده است) مراجعه کنید. اگر شما توزیع‌کننده هستید، نیازمندی‌های ماژول‌های اختیاری را ببینید.

توجه

برخی رفتارها ممکن است وابسته به پلتفرم باشند، زیرا فراخوانی‌هایی به APIهای سوکت سیستم‌عامل انجام می‌شود. نسخه نصب‌شده OpenSSL نیز ممکن است باعث تغییراتی در رفتار شود. برای مثال، TLSv1.3 همراه با نسخه 1.1.1 از OpenSSL ارائه می‌شود.

هشدار

از این ماژول بدون خواندن ملاحظات امنیتی استفاده نکنید. این کار ممکن است باعث ایجاد احساس امنیت کاذب شود، زیرا تنظیمات پیش‌فرض ماژول ssl لزوماً مناسب برنامه شما نیستند.

دسترس‌پذیری: not WASI.

این ماژول روی WebAssembly کار نمی‌کند یا در دسترس نیست. برای اطلاعات بیشتر سکوهای WebAssembly را ببینید.

این بخش، اشیاء و توابع ماژول ssl را مستند می‌کند؛ برای اطلاعات کلی‌تر درباره TLS، SSL و گواهی‌ها، خواننده به اسناد بخش «See Also» در پایین ارجاع داده می‌شود.

این ماژول یک کلاس، ssl.SSLSocket، ارائه می‌دهد که از نوع socket.socket مشتق شده است و پوششی شبیه به سوکت فراهم می‌کند که همچنین داده‌های عبوری از سوکت را با SSL رمزگذاری و رمزگشایی می‌کند. این کلاس از متدهای اضافی نیز پشتیبانی می‌کند، مانند getpeercert() که گواهی‌ی طرف دیگر اتصال را بازیابی می‌کند، cipher() که رمز مورد استفاده برای اتصال امن را بازیابی می‌کند، یا get_verified_chain() و get_unverified_chain() که زنجیره‌ی گواهی را بازیابی می‌کنند.

برای برنامه‌های کاربردی پیشرفته‌تر، کلاس ssl.SSLContext به مدیریت تنظیمات و گواهی‌ها کمک می‌کند، که سپس می‌توانند توسط سوکت‌های SSL ایجادشده از طریق متد SSLContext.wrap_socket() به ارث برده شوند.

تغییر یافته در نسخه‌ی 3.5.3: به‌روزرسانی شد تا از پیوند دادن با OpenSSL 1.1.0 پشتیبانی کند

تغییر یافته در نسخه‌ی 3.6: OpenSSL 0.9.8، 1.0.0 و 1.0.1 منسوخ شده‌اند و دیگر پشتیبانی نمی‌شوند. در آینده، ماژول ssl حداقل به OpenSSL 1.0.2 یا 1.1.0 نیاز خواهد داشت.

تغییر یافته در نسخه‌ی 3.10: PEP 644 پیاده‌سازی شده است. ماژول ssl به OpenSSL 1.1.1 یا جدیدتر نیاز دارد.

استفاده از ثابت‌ها و توابع منسوخ‌شده منجر به هشدارهای منسوخ‌شدن می‌شود.

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

ایجاد سوکت

نمونه‌های SSLSocket باید با استفاده از متد SSLContext.wrap_socket() ایجاد شوند. تابع کمکی create_default_context() زمینه‌ای جدید با تنظیمات پیش‌فرض امن برمی‌گرداند.

مثال سوکت کلاینت با زمینه پیش‌فرض و پشته دوگانه IPv4/IPv6:

import socket
import ssl

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

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

مثال سوکت کلاینت با زمینه سفارشی و IPv4:

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

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

مثال سوکت سرور در حال گوش‌دادن به localhost IPv4:

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

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

ایجاد زمینه

یک تابع کمکی به ایجاد اشیاء SSLContext برای اهداف رایج کمک می‌کند.

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

یک شیء SSLContext جدید با تنظیمات پیش‌فرض برای منظور داده‌شده برمی‌گرداند. این تنظیمات توسط ماژول ssl انتخاب می‌شوند و معمولاً نشان‌دهنده‌ی سطح امنیتی بالاتری نسبت به فراخوانی مستقیم سازنده‌ی SSLContext هستند.

cafile، capath و cadata گواهی‌های CA اختیاری قابل اعتماد برای تأیید گواهی را نشان می‌دهند، همان‌طور که در SSLContext.load_verify_locations() آمده است. اگر هر سه None باشند، این تابع می‌تواند به‌جای آن، اعتماد به گواهی‌های CA پیش‌فرض سیستم را انتخاب کند.

تنظیمات عبارت‌اند از: PROTOCOL_TLS_CLIENT یا PROTOCOL_TLS_SERVER، OP_NO_SSLv2 و OP_NO_SSLv3، همراه با مجموعه‌های رمزنگاری با رمزگذاری قوی، بدون RC4 و بدون مجموعه‌های رمزنگاریِ بدون احراز هویت. قرار دادن SERVER_AUTH به‌عنوان purpose، verify_mode را روی CERT_REQUIRED تنظیم می‌کند و یا گواهی‌های CA را بارگذاری می‌کند (هنگامی که دست‌کم یکی از cafile، capath یا cadata داده شده باشد)، یا از SSLContext.load_default_certs() برای بارگذاری گواهی‌های CA پیش‌فرض استفاده می‌کند.

هرگاه از keylog_filename پشتیبانی شود و متغیر محیطی SSLKEYLOGFILE تنظیم‌شده باشد، create_default_context() ثبت کلید (key logging) را فعال می‌کند.

تنظیمات پیش‌فرض برای این زمینه شامل VERIFY_X509_PARTIAL_CHAIN و VERIFY_X509_STRICT است. این تنظیمات باعث می‌شود پیاده‌سازی زیربنایی OpenSSL رفتاری بیشتر شبیه به یک پیاده‌سازی مطابق با RFC 5280 داشته باشد، در ازای مقدار کمی ناسازگاری با گواهی‌های قدیمی‌تر X.509.

توجه

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

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

توجه

اگر متوجه شدید که هنگام تلاش برخی کلاینت‌ها یا سرورهای قدیمی برای اتصال با یک SSLContext ایجادشده توسط این تابع، آن‌ها خطایی با مضمون «Protocol or cipher suite mismatch» دریافت می‌کنند، ممکن است فقط از SSL3.0 پشتیبانی کنند، که این تابع با استفاده از OP_NO_SSLv3 آن را غیرفعال می‌کند. SSL3.0 به‌طور گسترده‌ای کاملاً ناامن تلقی می‌شود. اگر همچنان می‌خواهید به استفاده از این تابع ادامه دهید و در عین حال اتصال‌های SSL 3.0 را مجاز بدانید، می‌توانید آن‌ها را دوباره فعال کنید، با استفاده از:

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

توجه

این زمینه به‌طور پیش‌فرض VERIFY_X509_STRICT را فعال می‌کند، که ممکن است گواهی‌های پیش از RFC 5280 یا بدشکل را، که پیاده‌سازی OpenSSL زیرین در غیر این صورت آن‌ها را می‌پذیرفت، رد کند. اگرچه غیرفعال کردن این گزینه توصیه نمی‌شود، می‌توانید این کار را با استفاده از روش زیر انجام دهید:

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

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

تغییر یافته در نسخه‌ی 3.4.4: RC4 از رشته‌ی cipher پیش‌فرض حذف شد.

تغییر یافته در نسخه‌ی 3.6: ChaCha20/Poly1305 به رشته‌ی رمزارز پیش‌فرض (default cipher string) افزوده شد.

3DES از رشته‌ی cipher پیش‌فرض حذف شد.

تغییر یافته در نسخه‌ی 3.8: پشتیبانی از گزارش‌گیری کلید (key logging) در SSLKEYLOGFILE اضافه شد.

تغییر یافته در نسخه‌ی 3.10: زمینه اکنون از پروتکل PROTOCOL_TLS_CLIENT یا PROTOCOL_TLS_SERVER به‌جای پروتکل عام PROTOCOL_TLS استفاده می‌کند.

تغییر یافته در نسخه‌ی 3.13: این زمینه اکنون از VERIFY_X509_PARTIAL_CHAIN و VERIFY_X509_STRICT در پرچم‌های تأیید پیش‌فرض خود استفاده می‌کند.

استثناها

exception ssl.SSLError

برای اعلام خطایی از پیاده‌سازی SSL زیربنایی (که در حال حاضر توسط کتابخانه‌ی OpenSSL ارائه می‌شود) پرتاب می‌شود. این نشان‌دهنده‌ی مشکلی در لایه‌ی رمزنگاری و احراز هویت سطح بالاتر است که بر اتصال شبکه‌ی زیربنایی سوار شده است. این خطا زیرنوعی از OSError است. کد خطا و پیام نمونه‌های SSLError توسط کتابخانه‌ی OpenSSL ارائه می‌شوند.

تغییر یافته در نسخه‌ی 3.3: SSLError پیش‌تر زیرنوعی از socket.error بود.

library

یک رشته‌ی یادآور (mnemonic) برای مشخص‌کردن زیرماژول OpenSSL که خطا در آن رخ داده است، مانند SSL، PEM یا X509. بازه‌ی مقادیر ممکن به نسخه‌ی OpenSSL بستگی دارد.

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

reason

یک رشته‌ی یادآور که دلیل وقوع این خطا را مشخص می‌کند، برای مثال CERTIFICATE_VERIFY_FAILED. بازه‌ی مقادیر ممکن به نسخه‌ی OpenSSL بستگی دارد.

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

exception ssl.SSLZeroReturnError

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

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

exception ssl.SSLWantReadError

زیرکلاسی از SSLError که توسط یک سوکت SSL غیرمسدود هنگام تلاش برای خواندن یا نوشتن داده پرتاب می‌شود، اما پیش از برآورده شدن درخواست، داده‌های بیشتری باید از طریق انتقال TCP زیرین دریافت شود.

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

exception ssl.SSLWantWriteError

زیرکلاسی از SSLError که توسط یک سوکت SSL غیرمسدود هنگام تلاش برای خواندن یا نوشتن داده پرتاب می‌شود، اما پیش از برآورده شدن درخواست، باید داده‌های بیشتری روی انتقال TCP زیرین ارسال شود.

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

exception ssl.SSLSyscallError

زیرکلاسی از SSLError که هنگام مواجهه با یک خطای سیستمی در تلاش برای انجام یک عملیات روی یک سوکت SSL پرتاب می‌شود. متأسفانه، راه آسانی برای بررسی شماره errno اصلی وجود ندارد.

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

exception ssl.SSLEOFError

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

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

exception ssl.SSLCertVerificationError

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

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

verify_code

یک شماره خطای عددی که خطای تأیید را نشان می‌دهد.

verify_message

رشته‌ای قابل‌خواندن برای انسان از خطای صحت‌سنجی.

exception ssl.CertificateError

نام مستعاری برای SSLCertVerificationError.

تغییر یافته در نسخه‌ی 3.7: این استثنا اکنون نام مستعاری برای SSLCertVerificationError است.

تولید تصادفی

ssl.RAND_bytes(num, /)

num بایت شبه‌تصادفی قوی از نظر رمزنگاری را برمی‌گرداند. اگر PRNG با داده کافی بذردهی نشده باشد یا روش RAND فعلی از عملیات پشتیبانی نکند، یک SSLError پرتاب می‌کند. می‌توان از RAND_status() برای بررسی وضعیت PRNG و از RAND_add() برای بذردهی PRNG استفاده کرد.

برای تقریباً همه‌ی کاربردها، os.urandom() ترجیح داده می‌شود.

برای به دست آوردن الزامات یک تولیدگر قوی از نظر رمزنگاری، مقاله‌ی ویکی‌پدیا، Cryptographically secure pseudorandom number generator (CSPRNG) را بخوانید.

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

ssl.RAND_status()

اگر تولیدگر اعداد شبه‌تصادفی SSL با میزان «کافی» تصادفی‌بودن بذرگذاری شده باشد، True را برمی‌گرداند و در غیر این صورت False را برمی‌گرداند. می‌توانید از ssl.RAND_egd() و ssl.RAND_add() برای افزایش تصادفی‌بودن تولیدگر اعداد شبه‌تصادفی استفاده کنید.

ssl.RAND_add(bytes, entropy, /)

bytes داده‌شده را در مولد اعداد شبه‌تصادفی SSL مخلوط کنید. پارامتر entropy (یک عدد اعشاری) کران پایینی برای آنتروپی موجود در رشته است (بنابراین همیشه می‌توانید از 0.0 استفاده کنید). برای اطلاعات بیشتر درباره منابع آنتروپی، RFC 1750 را ببینید.

تغییر یافته در نسخه‌ی 3.5: اکنون bytes-like object قابل‌نوشتن پذیرفته می‌شود.

مدیریت گواهی

ssl.cert_time_to_seconds(cert_time)

با دریافت رشته‌ی cert_time که نشان‌دهنده‌ی تاریخ "notBefore" یا "notAfter" از یک گواهی در قالب "%b %d %H:%M:%S %Y %Z" برای strptime (با تنظیمات locale C) است، زمان بر حسب ثانیه از مبدأ را برمی‌گرداند.

در اینجا یک مثال آمده است:

>>> import ssl
>>> import datetime as dt
>>> timestamp = ssl.cert_time_to_seconds("Jan  5 09:34:43 2018 GMT")
>>> timestamp
1515144883
>>> print(dt.datetime.fromtimestamp(timestamp, dt.UTC))
2018-01-05 09:34:43+00:00

برای تاریخ‌های «notBefore» یا «notAfter» باید از GMT استفاده شود (RFC 5280).

تغییر یافته در نسخه‌ی 3.5: زمان ورودی به‌عنوان زمانی در UTC تفسیر می‌شود، همان‌طور که با منطقه زمانی 'GMT' در رشته ورودی مشخص شده است. پیش‌تر از منطقه زمانی محلی استفاده می‌شد. یک عدد صحیح برگردانده می‌شود (در قالب ورودی کسری از ثانیه وجود ندارد).

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

با ارائه‌ی آدرس addr یک سرور محافظت‌شده با SSL، به‌صورت یک جفت (نام میزبان، شماره پورت)، گواهی سرور را دریافت می‌کند و آن را به‌صورت یک رشته‌ی کدگذاری‌شده با PEM برمی‌گرداند. اگر ssl_version مشخص شده باشد، از آن نسخه از پروتکل SSL برای تلاش جهت اتصال به سرور استفاده می‌کند. اگر ca_certs مشخص شده باشد، باید یک پرونده حاوی فهرستی از گواهی‌های ریشه باشد، با همان قالبی که برای پارامتر cafile در SSLContext.load_verify_locations() استفاده می‌شود. این فراخوانی تلاش می‌کند گواهی سرور را در برابر آن مجموعه از گواهی‌های ریشه اعتبارسنجی کند، و اگر اعتبارسنجی ناموفق باشد، شکست می‌خورد. می‌توان یک مهلت زمانی را با پارامتر timeout مشخص کرد.

تغییر یافته در نسخه‌ی 3.3: این تابع اکنون با IPv6 سازگار است.

تغییر یافته در نسخه‌ی 3.5: مقدار پیش‌فرض ssl_version برای بیشترین سازگاری با سرورهای مدرن، از PROTOCOL_SSLv3 به PROTOCOL_TLS تغییر کرده است.

تغییر یافته در نسخه‌ی 3.10: پارامتر timeout افزوده شد.

ssl.DER_cert_to_PEM_cert(der_cert_bytes)

با دریافت یک گواهی به‌صورت هیپ‌ای (blob) از بایت‌های کدگذاری‌شده با DER، نسخه‌ی رشته‌ای کدگذاری‌شده با PEM از همان گواهی را برمی‌گرداند.

ssl.PEM_cert_to_DER_cert(pem_cert_string)

با داشتن یک گواهی به‌صورت رشته‌ی ASCII PEM، دنباله‌ای از بایت‌های کدگذاری‌شده با DER برای همان گواهی بازمی‌گرداند.

ssl.get_default_verify_paths()

یک تاپل نام‌دار حاوی مسیرهای cafile و capath پیش‌فرض OpenSSL برمی‌گرداند. این مسیرها همان مسیرهایی هستند که توسط SSLContext.set_default_verify_paths() استفاده می‌شوند. مقدار بازگشتی یک named tuple از نوع DefaultVerifyPaths است:

• cafile - مسیر حل‌شده برای cafile یا None اگر پرونده وجود نداشته باشد،

• capath - مسیر حل‌شده به capath یا None اگر پوشه وجود نداشته باشد،

• openssl_cafile_env - کلید محیطی OpenSSL که به یک cafile اشاره می‌کند،

• openssl_cafile - مسیر سخت‌کدشده به یک cafile،

• openssl_capath_env - کلید محیطی OpenSSL که به یک capath اشاره می‌کند،

• openssl_capath - مسیر سخت‌کدشده به یک پوشه‌ی capath

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

ssl.enum_certificates(store_name)

گواهی‌ها را از مخزن گواهی سیستم ویندوز بازیابی می‌کند. store_name می‌تواند یکی از CA، ROOT یا MY باشد. ویندوز ممکن است مخازن گواهی بیشتری نیز ارائه دهد.

این تابع فهرستی از تاپل‌های (cert_bytes, encoding_type, trust) را برمی‌گرداند. encoding_type کدگذاری cert_bytes را مشخص می‌کند. این مقدار یا x509_asn برای داده‌های X.509 ASN.1 است یا pkcs_7_asn برای داده‌های PKCS#7 ASN.1. trust هدف گواهی را به‌صورت مجموعه‌ای از OIDS یا، اگر گواهی برای تمام اهداف قابل اعتماد باشد، دقیقاً به‌صورت True مشخص می‌کند.

مثال:

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

دسترس‌پذیری: Windows.

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

ssl.enum_crls(store_name)

بازیابی CRLها از مخزن گواهی سیستمی ویندوز (cert store). store_name می‌تواند یکی از CA، ROOT یا MY باشد. ویندوز ممکن است فروشگاه‌های گواهی دیگری نیز ارائه دهد.

این تابع فهرستی از تاپل‌های (cert_bytes, encoding_type, trust) را برمی‌گرداند. encoding_type کدگذاری cert_bytes را مشخص می‌کند. این مقدار می‌تواند x509_asn برای داده‌های X.509 ASN.1 یا pkcs_7_asn برای داده‌های PKCS#7 ASN.1 باشد.

دسترس‌پذیری: Windows.

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

ثابت‌ها

همه‌ی ثابت‌ها اکنون مجموعه‌های enum.IntEnum یا enum.IntFlag هستند.

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

ssl.CERT_NONE

مقدار ممکن برای SSLContext.verify_mode. به‌جز PROTOCOL_TLS_CLIENT، این حالت پیش‌فرض است. در سوکت‌های سمت کلاینت، تقریباً هر گواهی‌ای پذیرفته می‌شود. خطاهای اعتبارسنجی، مانند گواهی غیرقابل‌اعتماد یا منقضی‌شده، نادیده گرفته می‌شوند و باعث لغو دست‌دهی TLS/SSL نمی‌شوند.

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

بحث ملاحظات امنیتی را در زیر ببینید.

ssl.CERT_OPTIONAL

مقدار ممکن برای SSLContext.verify_mode. در حالت کلاینت، CERT_OPTIONAL همان معنای CERT_REQUIRED را دارد. توصیه می‌شود به‌جای آن از CERT_REQUIRED برای سوکت‌های سمت کلاینت استفاده کنید.

در حالت سرور، یک درخواست برای گواهی کلاینت به کلاینت ارسال می‌شود. کلاینت می‌تواند یا این درخواست را نادیده بگیرد یا برای انجام احراز هویت گواهی کلاینت TLS، یک گواهی ارسال کند. اگر کلاینت تصمیم بگیرد گواهی ارسال کند، آن گواهی اعتبارسنجی می‌شود. هر خطای اعتبارسنجی، فوراً باعث لغو دست‌دهی TLS می‌شود.

استفاده از این تنظیم نیاز دارد که یک مجموعه معتبر از گواهی‌های CA به SSLContext.load_verify_locations() ارسال شود.

ssl.CERT_REQUIRED

مقدار ممکن برای SSLContext.verify_mode. در این حالت، ارائه گواهی از طرف دیگر اتصال سوکت الزامی است؛ اگر گواهی ارائه نشود یا اعتبارسنجی آن ناموفق باشد، یک SSLError پرتاب می‌شود. این حالت برای تأیید صحت گواهی در حالت کلاینت کافی نیست، زیرا نام‌های میزبان را تطبیق نمی‌دهد. برای تأیید اصالت یک گواهی، check_hostname نیز باید فعال باشد. PROTOCOL_TLS_CLIENT از CERT_REQUIRED استفاده می‌کند و check_hostname را به‌طور پیش‌فرض فعال می‌کند.

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

استفاده از این تنظیم نیاز دارد که یک مجموعه معتبر از گواهی‌های CA به SSLContext.load_verify_locations() ارسال شود.

class ssl.VerifyMode

مجموعه‌ی enum.IntEnum از ثابت‌های CERT_*.

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

ssl.VERIFY_DEFAULT

مقدار ممکن برای SSLContext.verify_flags. در این حالت، فهرست‌های ابطال گواهی (CRLs) بررسی نمی‌شوند. به‌طور پیش‌فرض، OpenSSL نه به CRLها نیاز دارد و نه آن‌ها را تأیید می‌کند.

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

ssl.VERIFY_CRL_CHECK_LEAF

مقدار ممکن برای SSLContext.verify_flags. در این حالت، تنها گواهی همتا بررسی می‌شود، اما هیچ‌یک از گواهی‌های CA میانی بررسی نمی‌شود. این حالت به یک فهرست لغو گواهی (CRL) معتبر نیاز دارد که توسط اکسپورتکننده گواهی همتا (CA بالادستی مستقیم آن) امضا شده باشد. اگر هیچ CRL مناسبی با SSLContext.load_verify_locations بارگذاری نشده باشد، اعتبارسنجی شکست خواهد خورد.

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

ssl.VERIFY_CRL_CHECK_CHAIN

مقدار ممکن برای SSLContext.verify_flags. در این حالت، فهرست‌های لغو گواهی (CRLs) مربوط به تمام گواهی‌های موجود در زنجیره گواهی همتا بررسی می‌شوند.

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

ssl.VERIFY_X509_STRICT

مقدار ممکن برای SSLContext.verify_flags جهت غیرفعال کردن راه‌حل‌های موقت برای گواهی‌های X.509 معیوب.

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

ssl.VERIFY_ALLOW_PROXY_CERTS

مقدار ممکن برای SSLContext.verify_flags جهت فعال‌سازی تأیید گواهی پراکسی.

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

ssl.VERIFY_X509_TRUSTED_FIRST

مقدار ممکن برای SSLContext.verify_flags. این پرچم به OpenSSL دستور می‌دهد که هنگام ساخت زنجیره‌ی اعتماد برای اعتبارسنجی یک گواهی، گواهی‌های مورد اعتماد را ترجیح دهد. این پرچم به‌طور پیش‌فرض فعال است.

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

ssl.VERIFY_X509_PARTIAL_CHAIN

مقدار ممکن برای SSLContext.verify_flags. این مقدار به OpenSSL دستور می‌دهد که CAهای میانی موجود در مخزن اعتماد (trust store) را به‌عنوان لنگرهای اعتماد (trust-anchors) بپذیرد، به همان شیوه‌ای که گواهی‌های CA ریشه‌ی خودامضا پذیرفته می‌شوند. این کار امکان اعتماد به گواهی‌های صادرشده توسط یک CA میانی را بدون نیاز به اعتماد به CA ریشه‌ی والد آن فراهم می‌کند.

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

class ssl.VerifyFlags

enum.IntFlag مجموعه‌ای از ثابت‌های VERIFY_*.

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

ssl.PROTOCOL_TLS

بالاترین نسخه‌ی پروتکل را که هر دو کلاینت و سرور از آن پشتیبانی می‌کنند، انتخاب می‌کند. با وجود نام، این گزینه می‌تواند هر دو پروتکل «SSL» و «TLS» را انتخاب کند.

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

منسوخ شده از نسخه‌ی 3.10: کلاینت‌ها و سرورهای TLS برای ارتباط امن به تنظیمات پیش‌فرض متفاوتی نیاز دارند. ثابت عام پروتکل TLS منسوخ شده است و به جای آن PROTOCOL_TLS_CLIENT و PROTOCOL_TLS_SERVER توصیه می‌شود.

ssl.PROTOCOL_TLS_CLIENT

به‌صورت خودکار بر سر بالاترین نسخه‌ی پروتکل که هم کلاینت و هم سرور پشتیبانی می‌کنند، مذاکره می‌کند و زمینه را برای اتصال‌های سمت کلاینت پیکربندی می‌کند. این پروتکل به‌طور پیش‌فرض CERT_REQUIRED و check_hostname را فعال می‌کند.

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

ssl.PROTOCOL_TLS_SERVER

به‌صورت خودکار از طریق مذاکره، بالاترین نسخه‌ی پروتکل را که هر دو کلاینت و سرور از آن پشتیبانی می‌کنند، تعیین می‌کند و زمینه را برای اتصال‌های سمت سرور پیکربندی می‌کند.

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

ssl.PROTOCOL_SSLv23

نام مستعاری برای PROTOCOL_TLS.

منسوخ شده از نسخه‌ی 3.6: به‌جای آن از PROTOCOL_TLS استفاده کنید.

ssl.PROTOCOL_SSLv3

نسخه‌ی 3 SSL را به‌عنوان پروتکل رمزنگاری کانال انتخاب می‌کند.

اگر OpenSSL با گزینه no-ssl3 کامپایل شده باشد، این پروتکل در دسترس نیست.

هشدار

نسخه‌ی 3 SSL ناامن است. استفاده از آن به‌شدت توصیه نمی‌شود.

منسوخ شده از نسخه‌ی 3.6: OpenSSL تمام پروتکل‌های خاص نسخه را منسوخ کرده است. به‌جای آن‌ها از پروتکل پیش‌فرض PROTOCOL_TLS_SERVER یا PROTOCOL_TLS_CLIENT همراه با SSLContext.minimum_version و SSLContext.maximum_version استفاده کنید.

ssl.PROTOCOL_TLSv1

TLS نسخه 1.0 را به‌عنوان پروتکل رمزنگاری کانال انتخاب می‌کند.

منسوخ شده از نسخه‌ی 3.6: OpenSSL تمام پروتکل‌های مختص نسخه را منسوخ کرده است.

ssl.PROTOCOL_TLSv1_1

نسخه‌ی TLS 1.1 را به‌عنوان پروتکل رمزنگاری کانال انتخاب می‌کند. فقط با openssl نسخه‌ی 1.0.1+ در دسترس است.

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

منسوخ شده از نسخه‌ی 3.6: OpenSSL تمام پروتکل‌های مختص نسخه را منسوخ کرده است.

ssl.PROTOCOL_TLSv1_2

نسخه 1.2 TLS را به‌عنوان پروتکل رمزنگاری کانال انتخاب می‌کند. فقط با openssl نسخه 1.0.1+ در دسترس است.

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

منسوخ شده از نسخه‌ی 3.6: OpenSSL تمام پروتکل‌های مختص نسخه را منسوخ کرده است.

ssl.OP_ALL

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

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

ssl.OP_NO_SSLv2

از اتصال SSLv2 جلوگیری می‌کند. این گزینه فقط همراه با PROTOCOL_TLS قابل اعمال است. این گزینه از انتخاب SSLv2 به‌عنوان نسخه‌ی پروتکل توسط همتایان جلوگیری می‌کند.

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

منسوخ شده از نسخه‌ی 3.6: SSLv2 منسوخ شده است

ssl.OP_NO_SSLv3

از یک اتصال SSLv3 جلوگیری می‌کند. این گزینه تنها در ترکیب با PROTOCOL_TLS قابل استفاده است. این گزینه از انتخاب SSLv3 به‌عنوان نسخه‌ی پروتکل توسط همتایان جلوگیری می‌کند.

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

منسوخ شده از نسخه‌ی 3.6: SSLv3 منسوخ شده است

ssl.OP_NO_TLSv1

از اتصال TLSv1 جلوگیری می‌کند. این گزینه تنها در همراهی با PROTOCOL_TLS قابل اعمال است. این گزینه از انتخاب TLSv1 به‌عنوان نسخه‌ی پروتکل توسط طرفین جلوگیری می‌کند.

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

منسوخ شده از نسخه‌ی 3.7: این گزینه از OpenSSL 1.1.0 منسوخ شده است، به‌جای آن از SSLContext.minimum_version و SSLContext.maximum_version جدید استفاده کنید.

ssl.OP_NO_TLSv1_1

از اتصال TLSv1.1 جلوگیری می‌کند. این گزینه تنها به‌همراه PROTOCOL_TLS قابل استفاده است. این گزینه مانع از انتخاب TLSv1.1 به‌عنوان نسخه‌ی پروتکل توسط همتایان می‌شود. فقط در openssl نسخه‌ی 1.0.1+ در دسترس است.

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

منسوخ شده از نسخه‌ی 3.7: این گزینه از OpenSSL 1.1.0 منسوخ شده است.

ssl.OP_NO_TLSv1_2

از اتصال TLSv1.2 جلوگیری می‌کند. این گزینه فقط در ترکیب با PROTOCOL_TLS قابل اعمال است. این گزینه از انتخاب TLSv1.2 به‌عنوان نسخه پروتکل توسط طرفین جلوگیری می‌کند. فقط با openssl نسخه 1.0.1+ در دسترس است.

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

منسوخ شده از نسخه‌ی 3.7: این گزینه از OpenSSL 1.1.0 منسوخ شده است.

ssl.OP_NO_TLSv1_3

از اتصال TLSv1.3 جلوگیری می‌کند. این گزینه فقط همراه با PROTOCOL_TLS قابل اعمال است. این گزینه مانع از انتخاب TLSv1.3 به‌عنوان نسخه‌ی پروتکل توسط همتایان می‌شود. TLS 1.3 با OpenSSL 1.1.1 یا جدیدتر در دسترس است. هنگامی که پایتون با یک نسخه‌ی قدیمی‌تر از OpenSSL کامپایل شده باشد، مقدار پیش‌فرض این پرچم 0 است.

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

منسوخ شده از نسخه‌ی 3.7: این گزینه از OpenSSL 1.1.0 منسوخ شده است. این گزینه برای سازگاری رو به عقب با OpenSSL 1.0.2 به نسخه‌های 2.7.15 و 3.6.3 اضافه شد.

ssl.OP_NO_RENEGOTIATION

هرگونه مذاکره مجدد را در TLSv1.2 و نسخه‌های پیش از آن غیرفعال کنید. پیام‌های HelloRequest را ارسال نکنید و درخواست‌های مذاکره مجدد از طریق ClientHello را نادیده بگیرید.

این گزینه تنها با OpenSSL 1.1.0h و نسخه‌های بعد از آن در دسترس است.

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

ssl.OP_CIPHER_SERVER_PREFERENCE

به‌جای اولویت کلاینت، از اولویت سرور در ترتیب رمزها استفاده کنید. این گزینه بر سوکت‌های کلاینت و سوکت‌های سرور SSLv2 تأثیری ندارد.

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

ssl.OP_SINGLE_DH_USE

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

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

ssl.OP_SINGLE_ECDH_USE

از استفاده‌ی مجدد از همان کلید ECDH برای نشست‌های SSL متفاوت جلوگیری می‌کند. این کار رازداری پیش‌رو (forward secrecy) را بهبود می‌بخشد، اما به منابع محاسباتی بیشتری نیاز دارد. این گزینه فقط به سوکت‌های سرور اعمال می‌شود.

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

ssl.OP_ENABLE_MIDDLEBOX_COMPAT

ارسال پیام‌های Change Cipher Spec (CCS) ساختگی در دست‌دهی TLS 1.3 برای اینکه اتصال TLS 1.3 بیشتر شبیه اتصال TLS 1.2 به نظر برسد.

این گزینه تنها با OpenSSL 1.1.1 و نسخه‌های بعدی در دسترس است.

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

ssl.OP_NO_COMPRESSION

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

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

class ssl.Options

enum.IntFlag مجموعه‌ای از ثابت‌های OP_*.

ssl.OP_NO_TICKET

جلوگیری از درخواست بلیت نشست (session ticket) توسط سمت کلاینت.

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

ssl.OP_IGNORE_UNEXPECTED_EOF

نادیده گرفتن خاموش شدن غیرمنتظره‌ی اتصال‌های TLS.

این گزینه فقط با OpenSSL 3.0.0 و نسخه‌های بعدی در دسترس است.

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

ssl.OP_ENABLE_KTLS

فعال‌سازی استفاده از TLS هسته (kernel TLS). برای بهره‌مندی از این قابلیت، OpenSSL باید با پشتیبانی از آن کامپایل شده باشد و مجموعه‌های رمزنگاری و افزونه‌های توافق‌شده باید توسط آن پشتیبانی شوند (فهرست موارد پشتیبانی‌شده ممکن است بسته به پلتفرم و نسخه هسته متفاوت باشد).

توجه داشته باشید که با فعال بودن TLS هسته، برخی از عملیات رمزنگاری مستقیماً توسط هسته انجام می‌شوند، نه از طریق هیچ‌یک از ارائه‌دهنده‌های OpenSSL موجود. این ممکن است نامطلوب باشد؛ برای مثال، اگر برنامه نیاز داشته باشد تمام عملیات رمزنگاری توسط ارائه‌دهنده FIPS انجام شود.

این گزینه فقط با OpenSSL 3.0.0 و نسخه‌های بعدی در دسترس است.

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

ssl.OP_LEGACY_SERVER_CONNECT

فقط اجازه‌ی مذاکره‌ی مجدد ناامن قدیمی بین OpenSSL و سرورهای وصله‌نشده را می‌دهد.

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

ssl.HAS_ALPN

اینکه کتابخانه OpenSSL پشتیبانی توکار از افزونه TLS با نام Application-Layer Protocol Negotiation، همان‌طور که در RFC 7301 توضیح داده شده است، دارد یا خیر.

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

ssl.HAS_NEVER_CHECK_COMMON_NAME

اینکه کتابخانه‌ی OpenSSL پشتیبانی توکار برای بررسی نکردن نام مشترک موضوع دارد و SSLContext.hostname_checks_common_name قابل نوشتن است.

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

ssl.HAS_ECDH

اینکه کتابخانه OpenSSL از تبادل کلید دیفی-هلمن مبتنی بر منحنی بیضوی (Elliptic Curve-based Diffie-Hellman key exchange) پشتیبانی توکار دارد. این باید true باشد، مگر اینکه این قابلیت به‌صراحت توسط توزیع‌کننده غیرفعال شده باشد.

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

ssl.HAS_SNI

اینکه آیا کتابخانه‌ی OpenSSL پشتیبانی توکار از افزونه‌ی Server Name Indication دارد (همان‌طور که در RFC 6066 تعریف شده است).

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

ssl.HAS_NPN

اینکه آیا کتابخانه OpenSSL پشتیبانی توکار از Next Protocol Negotiation را دارد یا خیر، همان‌طور که در Application Layer Protocol Negotiation توضیح داده شده است. هنگامی که true باشد، می‌توانید از متد SSLContext.set_npn_protocols() برای اعلام پروتکل‌هایی که می‌خواهید پشتیبانی کنید، استفاده کنید.

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

ssl.HAS_SSLv2

این‌که آیا کتابخانه OpenSSL پشتیبانی توکار از پروتکل SSL 2.0 دارد یا خیر.

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

ssl.HAS_SSLv3

این‌که آیا کتابخانه OpenSSL پشتیبانی توکار از پروتکل SSL 3.0 دارد.

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

ssl.HAS_TLSv1

اینکه کتابخانه OpenSSL پشتیبانی توکار برای پروتکل TLS 1.0 دارد یا خیر.

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

ssl.HAS_TLSv1_1

اینکه آیا کتابخانه‌ی OpenSSL از پروتکل TLS 1.1 پشتیبانی توکار دارد یا خیر.

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

ssl.HAS_TLSv1_2

اینکه آیا کتابخانه OpenSSL از پروتکل TLS 1.2 پشتیبانی توکار دارد.

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

ssl.HAS_TLSv1_3

اینکه کتابخانه OpenSSL از پروتکل TLS 1.3 به‌صورت توکار پشتیبانی می‌کند.

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

ssl.HAS_PSK

اینکه آیا کتابخانه‌ی OpenSSL پشتیبانی توکار از TLS-PSK دارد یا خیر.

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

ssl.HAS_PHA

اینکه کتابخانه OpenSSL پشتیبانی توکار از TLS-PHA دارد یا خیر.

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

ssl.CHANNEL_BINDING_TYPES

فهرست انواع پشتیبانی‌شده‌ی اتصال کانال TLS (channel binding). رشته‌های موجود در این فهرست می‌توانند به‌عنوان آرگومان برای SSLSocket.get_channel_binding() استفاده شوند.

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

ssl.OPENSSL_VERSION

رشته‌ی نسخه‌ی کتابخانه‌ی OpenSSL بارگذاری‌شده توسط مفسر:

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

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

ssl.OPENSSL_VERSION_INFO

یک تاپل از پنج عدد صحیح که اطلاعات نسخه درباره کتابخانه OpenSSL را نشان می‌دهد:

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

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

ssl.OPENSSL_VERSION_NUMBER

شماره نسخه‌ی خام کتابخانه‌ی OpenSSL، به‌عنوان یک عدد صحیح:

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

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

ssl.ALERT_DESCRIPTION_HANDSHAKE_FAILURE

ssl.ALERT_DESCRIPTION_INTERNAL_ERROR

ALERT_DESCRIPTION_*

توضیحات هشدارها از RFC 5246 و سایر موارد. IANA TLS Alert Registry شامل این فهرست و ارجاع‌ها به RFCهایی است که معنای آن‌ها در آن‌ها تعریف شده است.

به‌عنوان مقدار بازگشتی تابع کال‌بک در SSLContext.set_servername_callback() استفاده می‌شود.

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

class ssl.AlertDescription

مجموعه‌ای از ثابت‌های ALERT_DESCRIPTION_* از کلاس enum.IntEnum.

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

Purpose.SERVER_AUTH

گزینه‌ای برای create_default_context() و SSLContext.load_default_certs(). این مقدار نشان می‌دهد که زمینه ممکن است برای احراز هویت سرورهای وب استفاده شود (بنابراین، برای ایجاد سوکت‌های سمت کلاینت استفاده خواهد شد).

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

Purpose.CLIENT_AUTH

گزینه‌ای برای create_default_context() و SSLContext.load_default_certs(). این مقدار نشان می‌دهد که ممکن است از زمینه برای احراز هویت کلاینت‌های وب استفاده شود (بنابراین، برای ایجاد سوکت‌های سمت سرور استفاده خواهد شد).

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

class ssl.SSLErrorNumber

enum.IntEnum مجموعه‌ای از ثابت‌های SSL_ERROR_*.

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

class ssl.TLSVersion

enum.IntEnum مجموعه‌ای از نسخه‌های SSL و TLS برای SSLContext.maximum_version و SSLContext.minimum_version.

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

TLSVersion.MINIMUM_SUPPORTED

TLSVersion.MAXIMUM_SUPPORTED

حداقل یا حداکثر نسخه‌ی پشتیبانی‌شده‌ی SSL یا TLS. این‌ها ثابت‌های جادویی هستند. مقدارهای آن‌ها پایین‌ترین و بالاترین نسخه‌های در دسترس TLS/SSL را نشان نمی‌دهند.

TLSVersion.SSLv3

TLSVersion.TLSv1

TLSVersion.TLSv1_1

TLSVersion.TLSv1_2

TLSVersion.TLSv1_3

SSL 3.0 تا TLS 1.3.

منسوخ شده از نسخه‌ی 3.10: همه‌ی اعضای TLSVersion به‌جز TLSVersion.TLSv1_2 و TLSVersion.TLSv1_3 منسوخ شده‌اند.

سوکت‌های SSL

class ssl.SSLSocket(socket.socket)

سوکت‌های SSL، متدهای زیر از اشیای سوکت را ارائه می‌دهند:

• accept()

• bind()

• close()

• connect()

• detach()

• fileno()

• getpeername(), getsockname()

• getsockopt(), setsockopt()

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

• listen()

• makefile()

• recv()، recv_into() (اما ارسال مقدار غیرصفر برای آرگومان flags مجاز نیست)

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

• sendfile() (اما os.sendfile فقط برای سوکت‌های متن ساده استفاده خواهد شد، در غیر این صورت 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 پشتیبانی می‌کنند. نوشتن داده با طول صفر دیگر با خطای نقض پروتکل شکست نمی‌خورد.

سوکت‌های 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() استفاده کنید.

توجه

متدهای read() و write() متدهای سطح پایینی هستند که داده‌های رمزنگاری‌نشده در سطح کاربرد را می‌خوانند و می‌نویسند و آن‌ها را به داده‌های رمزنگاری‌شده در سطح سیم رمزگشایی/رمزنگاری می‌کنند. این متدها به یک اتصال SSL فعال نیاز دارند، یعنی دست‌دهی کامل شده باشد و SSLSocket.unwrap() فراخوانی نشده باشد.

معمولاً باید به‌جای این متدها از متدهای API سوکت مانند recv() و send() استفاده کنید.

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', 'hostmaster@eff.org'),)),
 '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() عمل می‌کند.

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

SSLSocket.get_unverified_chain()

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

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

SSLSocket.cipher()

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

SSLSocket.shared_ciphers()

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

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

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

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

یک زمینه 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	خیر	خیر	بله	خیر	خیر	بله

پانویس‌ها

[1] (1,2)

SSLContext به‌طور پیش‌فرض SSLv2 را با OP_NO_SSLv2 غیرفعال می‌کند.

[2] (1,2)

SSLContext به‌طور پیش‌فرض SSLv3 را با OP_NO_SSLv3 غیرفعال می‌کند.

[3] (1,2)

پروتکل TLS 1.3 با PROTOCOL_TLS در OpenSSL >= 1.1.1 در دسترس خواهد بود. ثابت PROTOCOL اختصاصی‌ای فقط برای TLS 1.3 وجود ندارد.

همچنین ملاحظه نمائید

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

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

SSLContext.set_ciphers(ciphers, /)

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

توجه

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

مجموعه‌رمزهای TLS 1.3 را نمی‌توان با set_ciphers() غیرفعال کرد.

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 است که نشان‌دهنده‌ی زنجیره‌ی گواهی‌ای است که با نام سرور مطابقت دارد.

به دلیل مرحله‌ی اولیه‌ی مذاکره‌ی اتصال 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.

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() آمده است.

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

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

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 باید یک رشته غیرخالی باشد.

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

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، پارامتر identity_hint به کلاینت ارسال نمی‌شود.

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

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

گواهی‌های CA

اگر می‌خواهید اعتبارسنجی گواهی طرف دیگر اتصال را الزامی کنید، باید یک پرونده «گواهی‌های CA» فراهم کنید که حاوی زنجیره‌های گواهی برای هر صادرکننده‌ای باشد که مایل به اعتماد به آن هستید. باز هم، این پرونده فقط شامل این زنجیره‌ها است که به‌هم‌پیوسته شده‌اند. برای اعتبارسنجی، پایتون از اولین زنجیره‌ای استفاده می‌کند که در پرونده یافت شود و مطابقت داشته باشد. می‌توان با فراخوانی SSLContext.load_default_certs() از پرونده گواهی‌های پلتفرم استفاده کرد؛ این کار به‌صورت خودکار با create_default_context() انجام می‌شود.

کلید و گواهی‌ی ترکیبی

اغلب کلید خصوصی در همان پرونده گواهی ذخیره می‌شود؛ در این صورت، فقط باید پارامتر certfile را به SSLContext.load_cert_chain() ارسال کنید. اگر کلید خصوصی همراه گواهی ذخیره شده باشد، باید قبل از اولین گواهی در زنجیره گواهی قرار گیرد:

-----BEGIN RSA PRIVATE KEY-----
... (کلید خصوصی با کدگذاری base64) ...
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
... (گواهی با کدگذاری base64 PEM) ...
-----END CERTIFICATE-----

گواهی‌های خودامضا

اگر می‌خواهید سروری بسازید که خدمات اتصال رمزگذاری‌شده با SSL را ارائه دهد، باید برای آن خدمت یک گواهی تهیه کنید. روش‌های زیادی برای تهیه گواهی‌های مناسب وجود دارد، مانند خرید یک گواهی از یک مرجع صدور گواهی. یک روش رایج دیگر، تولید یک گواهی خودامضا است. ساده‌ترین راه برای انجام این کار، استفاده از بسته OpenSSL، با موردی مانند زیر است:

% 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
%

عیب یک گواهی خودامضا این است که خودش گواهی ریشه‌ی خود محسوب می‌شود و هیچ‌کس دیگری آن را در نهانگاه گواهی‌های ریشه‌ی شناخته‌شده (و مورد اعتماد) خود نخواهد داشت.

مثال‌ها

آزمون پشتیبانی از SSL

برای بررسی وجود پشتیبانی SSL در یک نصب پایتون، کد کاربر باید از الگوی زیر استفاده کند:

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

عملیات سمت کلاینت

این مثال یک زمینه‌ی SSL (SSL context) با تنظیمات امنیتی توصیه‌شده برای سوکت‌های کلاینت، از جمله تأیید خودکار گواهی، ایجاد می‌کند:

>>> context = ssl.create_default_context()

اگر ترجیح می‌دهید تنظیمات امنیتی را خودتان تنظیم کنید، می‌توانید یک زمینه را از پایه ایجاد کنید (اما مراقب باشید که ممکن است تنظیمات را به‌درستی انجام ندهید):

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

(این قطعه‌کد فرض می‌کند که سیستم‌عامل شما بسته‌ای از تمام گواهی‌های CA را در /etc/ssl/certs/ca-bundle.crt قرار می‌دهد؛ در غیر این صورت، با خطا مواجه می‌شوید و باید محل را تنظیم کنید)

پروتکل PROTOCOL_TLS_CLIENT زمینه را برای اعتبارسنجی گواهی و تأیید نام میزبان پیکربندی می‌کند. verify_mode به CERT_REQUIRED تنظیم شده است و check_hostname به True تنظیم شده است. همه‌ی پروتکل‌های دیگر زمینه‌های SSL را با پیش‌فرض‌های ناامن ایجاد می‌کنند.

وقتی از زمینه برای اتصال به یک سرور استفاده می‌کنید، CERT_REQUIRED و check_hostname گواهی سرور را اعتبارسنجی می‌کنند: این اعتبارسنجی تضمین می‌کند که گواهی سرور با یکی از گواهی‌های CA امضا شده باشد، صحت امضا را بررسی می‌کند و سایر ویژگی‌ها مانند اعتبار و هویت نام میزبان را تأیید می‌کند:

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

سپس می‌توانید گواهی را دریافت کنید:

>>> cert = conn.getpeercert()

بازرسی دیداری نشان می‌دهد که گواهی، سرویس موردنظر (یعنی میزبان HTTPS www.python.org) را شناسایی می‌کند:

>>> 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}

اکنون که کانال SSL برقرار شد و گواهی تأیید شد، می‌توانید ارتباط با سرور را آغاز کنید:

>>> 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'']

بحث ملاحظات امنیتی را در زیر ببینید.

عملیات سمت سرور

برای راه‌اندازی سرور، معمولاً باید یک گواهی سرور و یک کلید خصوصی داشته باشید، که هر کدام در یک پرونده قرار دارند. ابتدا یک زمینه حاوی کلید و گواهی ایجاد می‌کنید، تا کلاینت‌ها بتوانند اصالت شما را بررسی کنند. سپس یک سوکت باز می‌کنید، آن را به یک پورت پیوند می‌دهید، متد listen() را روی آن فراخوانی می‌کنید و منتظر اتصال کلاینت‌ها می‌مانید:

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)

هنگامی که یک کلاینت متصل شد، accept() را روی سوکت فراخوانی کنید تا سوکت جدید را از طرف مقابل دریافت کنید و از متد SSLContext.wrap_socket() زمینه برای ایجاد یک سوکت SSL در سمت سرور برای اتصال استفاده کنید:

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

سپس داده‌ها را از connstream می‌خوانید و تا زمانی که کار شما با کلاینت تمام نشده است (یا کار کلاینت با شما تمام نشده است)، با آن‌ها کاری انجام می‌دهید:

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], [])
  

همچنین ملاحظه نمائید

ماژول asyncio از سوکت‌های SSL غیرمسدود پشتیبانی می‌کند و API جریان‌ها سطح بالاتری را فراهم می‌کند. این ماژول رویدادها را با استفاده از ماژول selectors پایش می‌کند و استثناهای SSLWantWriteError، SSLWantReadError و BlockingIOError را مدیریت می‌کند. همچنین دست‌دهی SSL را به‌صورت ناهمگام اجرا می‌کند.

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

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

از زمان معرفی ماژول 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

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

class ssl.SSLSession

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

id

time

timeout

ticket_lifetime_hint

has_ticket

ملاحظات امنیتی

بهترین پیش‌فرض‌ها

برای استفاده سمت کلاینت، اگر الزامات خاصی برای سیاست امنیتی خود ندارید، اکیداً توصیه می‌شود که از تابع create_default_context() برای ایجاد زمینه‌ی SSL خود استفاده کنید. این تابع گواهی‌های CA مورد اعتماد سیستم را بارگذاری می‌کند، اعتبارسنجی گواهی و بررسی نام میزبان را فعال می‌کند و تلاش می‌کند تنظیمات پروتکل و رمز نسبتاً امن را انتخاب کند.

برای مثال، به این صورت می‌توانید از کلاس smtplib.SMTP برای ایجاد یک اتصال مورد اعتماد و امن به یک سرور SMTP استفاده کنید:

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

اگر برای اتصال به یک گواهی کلاینت نیاز باشد، می‌توان آن را با SSLContext.load_cert_chain() افزود.

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

تنظیمات دستی

اعتبارسنجی گواهی‌ها

هنگام فراخوانی مستقیم سازنده‌ی SSLContext، CERT_NONE پیش‌فرض است. از آن‌جا که این حالت طرف مقابل را احراز هویت نمی‌کند، می‌تواند ناامن باشد، به‌ویژه در حالت کلاینت که در بیشتر موارد می‌خواهید از اصالت سروری که با آن در ارتباط هستید اطمینان حاصل کنید. بنابراین، در حالت کلاینت، به‌شدت توصیه می‌شود از CERT_REQUIRED استفاده کنید. با این حال، این مورد به‌تنهایی کافی نیست؛ همچنین باید بررسی کنید که گواهی‌ی سرور، که می‌توان آن را با فراخوانی SSLSocket.getpeercert() دریافت کرد، با سرویس موردنظر مطابقت دارد. در بسیاری از پروتکل‌ها و کاربردها، سرویس را می‌توان با نام میزبان شناسایی کرد. این بررسی رایج، هنگامی که SSLContext.check_hostname فعال باشد، به‌صورت خودکار انجام می‌شود.

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

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

نسخه‌های پروتکل

نسخه‌های 2 و 3 SSL ناامن تلقی می‌شوند و بنابراین استفاده از آن‌ها خطرناک است. اگر می‌خواهید حداکثر سازگاری میان کلاینت‌ها و سرورها برقرار باشد، توصیه می‌شود از PROTOCOL_TLS_CLIENT یا PROTOCOL_TLS_SERVER به‌عنوان نسخه‌ی پروتکل استفاده کنید. SSLv2 و SSLv3 به‌طور پیش‌فرض غیرفعال هستند.

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

زمینه کلاینت SSL ایجادشده در بالا، فقط اتصال‌های TLSv1.2 و TLSv1.3 (اگر توسط سیستم شما پشتیبانی شود) به یک سرور را مجاز می‌کند. PROTOCOL_TLS_CLIENT به‌طور پیش‌فرض شامل اعتبارسنجی گواهی و بررسی‌های نام میزبان می‌شود. شما باید گواهی‌ها را در زمینه بارگذاری کنید.

انتخاب رمز

اگر الزامات امنیتی پیشرفته دارید، تنظیم دقیق رمزهایی که هنگام مذاکره‌ی یک نشست SSL فعال می‌شوند از طریق متد SSLContext.set_ciphers() امکان‌پذیر است. از Python 3.2.3 به بعد، ماژول ssl برخی از رمزهای ضعیف را به‌طور پیش‌فرض غیرفعال می‌کند، اما ممکن است بخواهید انتخاب رمز را بیش‌تر محدود کنید. حتماً مستندات OpenSSL را درباره‌ی قالب فهرست رمز بخوانید. اگر می‌خواهید بررسی کنید کدام رمزها با یک فهرست رمز مشخص فعال می‌شوند، از SSLContext.get_ciphers() یا دستور openssl ciphers روی سیستم خود استفاده کنید.

چندپردازشی

اگر از این ماژول به‌عنوان بخشی از یک برنامه چندفرایندی استفاده می‌کنید (برای نمونه، با استفاده از ماژول‌های multiprocessing یا concurrent.futures)، توجه داشته باشید که مولد اعداد تصادفی درونی OpenSSL فرایندهای forkشده را به‌درستی مدیریت نمی‌کند. اگر برنامه‌ها از هر قابلیت SSL همراه با os.fork() استفاده کنند، باید وضعیت PRNG فرایند والد را تغییر دهند. هر فراخوانی موفق RAND_add() یا RAND_bytes() کافی است.

TLS 1.3

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

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

• TLS 1.3 از مجموعه‌ای مجزا از مجموعه‌های رمزنگاری (cipher suites) استفاده می‌کند. همه‌ی مجموعه‌های رمزنگاری AES-GCM و ChaCha20 به‌طور پیش‌فرض فعال هستند. متد SSLContext.set_ciphers() هنوز نمی‌تواند هیچ‌کدام از رمزهای TLS 1.3 را فعال یا غیرفعال کند، اما SSLContext.get_ciphers() آن‌ها را برمی‌گرداند.

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

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

• قابلیت‌های TLS 1.3 مانند داده‌های زودهنگام (early data)، درخواست به‌تعویق‌افتاده‌ی گواهی کلاینت TLS (deferred TLS client cert request)، پیکربندی الگوریتم امضا و تولید مجدد کلید (rekeying) هنوز پشتیبانی نمی‌شوند.

همچنین ملاحظه نمائید

کلاس socket.socket

مستندات کلاس زیربنایی socket

رمزنگاری قوی SSL/TLS: مقدمه‌ای

مقدمه‌ای از مستندات Apache HTTP Server

RFC 1422: Privacy Enhancement for Internet Electronic Mail: Part II: Certificate-Based Key Management

استیو کنت

RFC 4086: الزامات تصادفی بودن برای امنیت

Donald E. Eastlake, Jeffrey I. Schiller, Steve Crocker

RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile

دیوید کوپر و دیگران

RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2

تیم دیرکس و اریک رسکورلا.

RFC 6066: Transport Layer Security (TLS) Extensions

Donald E. Eastlake

IANA TLS: پارامترهای امنیت لایه انتقال (TLS)

IANA

RFC 7525: توصیه‌هایی برای استفاده امن از Transport Layer Security (TLS) و Datagram Transport Layer Security (DTLS)

IETF

توصیه‌های موزیلا برای TLS سمت سرور

Mozilla