کتابخانه‌ی استاندارد · امنیت و رمزنگاری

اس اس ال ssl

رابط آشنای سبک OpenSSL برای اتصال امن، روی تی ال اس خود سلام.

واردسازی اس اس ال

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

این بسته رابط زمینه و اتصال به سبک OpenSSL را می‌دهد (SSL_CTX، SSL_connect، SSL_read و هم‌خانواده‌هایشان، با نام‌های سلام)، ولی زیر آن تی ال اس خود سلام کار می‌کند و به هیچ کتابخانه‌ی بیرونی نیاز ندارد. وقتی کد C نوشته‌شده با OpenSSL را منتقل می‌کنید، یا جدایی یک زمینه‌ی مشترک از اتصال‌های متعدد را می‌پسندید، به کارش ببرید. برای کد تازه تی ال اس کوتاه‌تر است و برای درخواست‌های وب اچ تی تی پی همه‌ی کار را برایتان انجام می‌دهد.

روند کار: یک زمینه بسازید، هر سوکت TCP را با پوشاندن به آن بدهید، برای کارخواه نام میزبان را تنظیم و اتصال برقرار کردن را صدا بزنید (سرور پذیرش را صدا می‌زند)، سپس خواندن و نوشتن. نکته‌هایی که باید بدانید:

  • زمینه‌ی کارخواه از همان ابتدا گواهی‌ها را با ریشه‌های سیستم می‌سنجد و کمینه‌ی نسخه‌اش TLS 1.2 است. بارگذاری مکان تایید ریشه‌های سیستم را با پرونده‌ی شما جایگزین می‌کند و تنظیم مسیرهای پیش‌فرض تایید به آن‌ها برمی‌گردد.
  • تنظیم نام میزبان لازم است: تا وقتی بررسی روشن است، بدون آن دست‌دهی رد می‌شود.
  • خاموش‌ کردن و بستن سوکت را نمی‌بندند. مثل OpenSSL، اتصال TCP که پوشانده‌اید مال شماست؛ پس از آن با تی سی پی ببندیدش.
  • تنظیم کمینه نسخه با تی ال اس۱۳ پس از دست‌دهی بررسی می‌شود: سروری که فقط 1.2 دارد وصل و سپس رد می‌شود. خواندن یک رشته برمی‌گرداند که در بایت صفر تمام می‌شود.

یک کارخواه کامل

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

ssl-fetch-page.salam
واردسازی اس اس ال
واردسازی شبکه.تی سی پی
واردسازی رشته

تابع دریافت صفحه(زمینه: اس اس ال.زمینه، میزبان: رشته، مسیر: رشته): رشته:
    سوکت := تی سی پی.شماره گیری(میزبان، ۴۴۳)
    اگر وارونه تی سی پی.اتصال معتبر(سوکت):
        برگشت "دسترسی نشد به " + میزبان
    پایان
    اتصال := اس اس ال.پوشاندن(زمینه، سوکت.توصیفگر)
    _ := اس اس ال.تنظیم نام میزبان(اتصال، میزبان)
    اگر وارونه اس اس ال.اتصال برقرار کردن(اتصال):
        پیام := اس اس ال.متن خطای اتصال(اتصال)
        اس اس ال.بستن(اتصال)
        تی سی پی.بستن(سوکت)
        برگشت "دست‌دهی ناموفق: " + پیام
    پایان
    _ := اس اس ال.نوشتن(اتصال، "GET " + مسیر + " HTTP/1.1\r\nHost: " + میزبان + "\r\nConnection: close\r\n\r\n")
    ناپایا پاسخ := ""
    تا درست:
        تکه := اس اس ال.خواندن(اتصال، ۱۶۳۸۴)
        اگر تکه.طول() برابر ۰:
            بشکن
        پایان
        پاسخ += تکه
    پایان
    اس اس ال.خاموش‌ کردن(اتصال)
    اس اس ال.بستن(اتصال)
    تی سی پی.بستن(سوکت)
    برگشت رشته.تفکیک کردن(پاسخ، "\r\n").بگیر(۰)
پایان

تابع ریشه:
    زمینه := اس اس ال.زمینه جدید مشتری()
    _ := اس اس ال.تنظیم مسیرهای پیش‌فرض تایید(زمینه)
    _ := اس اس ال.تنظیم کمینه نسخه(زمینه، اس اس ال.تی ال اس۱۲)
    اس اس ال.تنظیم تایید(زمینه، اس اس ال.تایید طرف مقابل)
    سرچاپ دریافت صفحه(زمینه، "example.com"، "/")
    سرچاپ دریافت صفحه(زمینه، "expired.badssl.com"، "/")
    اس اس ال.بستن زمینه(زمینه)
پایان

این برنامه به شبکه نیاز دارد، پس این‌جا فقط بررسی می‌شود. در برابر میزبان‌های واقعی این را چاپ کرد:

HTTP/1.1 200 OK
دست‌دهی ناموفق: certificate verification failed: certificate expired

اعتماد فقط به مرجع گواهی خودتان

سرویس‌های درون یک شرکت اغلب گواهی را از یک مرجع خصوصی می‌گیرند. آن مرجع را به جای ریشه‌های سیستم با بارگذاری مکان تایید بار کنید: کارخواه آن وقت فقط سرورهایی را می‌پذیرد که گواهی‌شان را مرجع شما امضا کرده، که از وب عمومی سخت‌گیرانه‌تر است. تنظیم کمینه نسخه با تی ال اس۱۳ هر چیز قدیمی‌تر از TLS 1.3 را رد می‌کند و پس از دست‌دهی طرف مقابل تاییدشده و نتیجه تایید می‌گویند بررسی چطور پیش رفت.

ssl-private-ca.salam
واردسازی اس اس ال
واردسازی شبکه.تی سی پی

تابع ریشه:
    زمینه := اس اس ال.زمینه جدید مشتری()
    اگر وارونه اس اس ال.بارگذاری مکان تایید(زمینه، "/etc/company/ca.pem"):
        سرچاپ "مرجع گواهی شرکت خوانده نشد:"، اس اس ال.آخرین متن خطا()
        برگشت ۱
    پایان
    اس اس ال.تنظیم تایید(زمینه، اس اس ال.تایید طرف مقابل)
    _ := اس اس ال.تنظیم کمینه نسخه(زمینه، اس اس ال.تی ال اس۱۳)

    سوکت := تی سی پی.شماره گیری("billing.internal"، ۸۴۴۳)
    اتصال := اس اس ال.پوشاندن(زمینه، سوکت.توصیفگر)
    _ := اس اس ال.تنظیم نام میزبان(اتصال، "billing.internal")
    موفق := اس اس ال.اتصال برقرار کردن(اتصال)
    اگر وارونه موفق یا وارونه اس اس ال.طرف مقابل تاییدشده(اتصال):
        سرچاپ "سرور رد شد، نتیجه‌ی تایید"، اس اس ال.نتیجه تایید(اتصال)، اس اس ال.متن خطای اتصال(اتصال)
        اس اس ال.بستن(اتصال)
        تی سی پی.بستن(سوکت)
        برگشت ۱
    پایان
    _ := اس اس ال.نوشتن(اتصال، "PING\n")
    سرچاپ "پاسخ سرور:"، اس اس ال.خواندن(اتصال، ۱۰۲۴)
    اس اس ال.خاموش‌ کردن(اتصال)
    اس اس ال.بستن(اتصال)
    تی سی پی.بستن(سوکت)
    اس اس ال.بستن زمینه(زمینه)
    برگشت ۰
پایان

نتیجه تایید وقتی گواهی پذیرفته شده برابر CERT_OK یعنی صفر است. فایل مرجع را برای برنامه خواندنی نگه دارید ولی نوشتنی نه، چون هر کس بتواند آن را عوض کند می‌تواند خودش را جای سرورهای شما جا بزند.

STARTTLS: امن کردن اتصالی که باز است

پست الکترونیک، IMAP، XMPP و برخی پروتکل‌های پایگاه داده با متن ساده شروع می‌کنند و وقتی کارخواه بخواهد روی همان اتصال به TLS می‌روند. برای همین است که پوشاندن شماره‌ی سوکت می‌گیرد نه نام میزبان: با net.tcp با سرور حرف بزنید تا موافقت کند، سپس همان fd را بپوشانید و با خواندن و نوشتن همین بسته ادامه دهید.

ssl-starttls.salam
واردسازی اس اس ال
واردسازی شبکه.تی سی پی
واردسازی رشته

تابع بگو(سوکت: تی سی پی.اتصال شبکه، خط: رشته): رشته:
    _ := تی سی پی.نوشتن(سوکت، خط + "\r\n")
    برگشت تی سی پی.خواندن(سوکت، ۴۰۹۶)
پایان

تابع ریشه:
    سوکت := تی سی پی.شماره گیری("smtp.gmail.com"، ۵۸۷)
    خوشامد := تی سی پی.خواندن(سوکت، ۴۰۹۶)
    سرچاپ "بی‌رمز:"، رشته.تفکیک کردن(خوشامد، "\r\n").بگیر(۰)
    _ := بگو(سوکت، "EHLO client.example.com")
    پاسخ := بگو(سوکت، "STARTTLS")
    اگر وارونه رشته.شروع با(پاسخ، "220"):
        سرچاپ "STARTTLS پشتیبانی نمی‌شود:"، پاسخ
        تی سی پی.بستن(سوکت)
        برگشت ۱
    پایان

    زمینه := اس اس ال.زمینه جدید مشتری()
    _ := اس اس ال.تنظیم مسیرهای پیش‌فرض تایید(زمینه)
    اس اس ال.تنظیم تایید(زمینه، اس اس ال.تایید طرف مقابل)
    اتصال := اس اس ال.پوشاندن(زمینه، سوکت.توصیفگر)
    _ := اس اس ال.تنظیم نام میزبان(اتصال، "smtp.gmail.com")
    اگر وارونه اس اس ال.اتصال برقرار کردن(اتصال):
        سرچاپ "دست‌دهی ناموفق:"، اس اس ال.متن خطای اتصال(اتصال)
        برگشت ۱
    پایان
    _ := اس اس ال.نوشتن(اتصال، "EHLO client.example.com\r\n")
    سرچاپ "رمز شده:"، رشته.تفکیک کردن(اس اس ال.خواندن(اتصال، ۴۰۹۶)، "\r\n").بگیر(۰)
    _ := اس اس ال.نوشتن(اتصال، "QUIT\r\n")
    اس اس ال.خاموش‌ کردن(اتصال)
    اس اس ال.بستن(اتصال)
    تی سی پی.بستن(سوکت)
    اس اس ال.بستن زمینه(زمینه)
    برگشت ۰
پایان

در برابر درگاه ارسال جیمیل، خوشامد سرور را بی‌رمز و سپس نخستین پاسخ رمز شده‌اش را چاپ کرد؛ شناسه‌های پایان هر خط در هر اجرا عوض می‌شوند:

بی‌رمز: 220 smtp.gmail.com ESMTP ... - gsmtp
رمز شده: 250-smtp.gmail.com at your service, [...]

یک کارخواه واقعی پست باید کد هر پاسخ را بررسی کند، نه فقط پاسخ STARTTLS را، و پس از جابه‌جایی دوباره EHLO بفرستد، همان‌طور که برنامه می‌کند، چون سرور هر چه را با متن ساده شنیده فراموش می‌کند.

وقتی چیزی شکست می‌خورد

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

گونه‌ها

زمینه Context

ساختار زمینه
زمینه‌ی TLS، مشترک میان اتصال‌ها.
نامانگلیسیگونهتوضیح
دستهhandleتهی*اشاره‌گر حالت زمینه.
ssl-Client.salam
واردسازی اس اس ال
واردسازی شبکه.تی سی پی

تابع ریشه:
    ز := اس اس ال.زمینه جدید مشتری()
    اگر وارونه اس اس ال.زمینه معتبر(ز):
        سرچاپ اس اس ال.آخرین متن خطا()
        برگشت
    پایان
    _ := اس اس ال.تنظیم کمینه نسخه(ز، اس اس ال.تی ال اس۱۳)
    _ := اس اس ال.تنظیم مسیرهای پیش‌فرض تایید(ز)
    ک := تی سی پی.شماره گیری("example.com"، ۴۴۳)
    ا := اس اس ال.پوشاندن(ز، ک.توصیفگر)
    _ := اس اس ال.تنظیم نام میزبان(ا، "example.com")
    اگر وارونه اس اس ال.اتصال معتبر(ا) یا وارونه اس اس ال.اتصال برقرار کردن(ا):
        سرچاپ "دست‌دهی ناموفق:"، اس اس ال.متن خطای اتصال(ا)
        برگشت
    پایان
    سرچاپ اس اس ال.طرف مقابل تاییدشده(ا)، اس اس ال.نتیجه تایید(ا) == اس اس ال.گواهی معتبر
    ن := اس اس ال.نوشتن(ا، "GET / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n")
    اگر ن <= ۰:
        سرچاپ "کد خطا:"، اس اس ال.کد خطا(ا، ن)
    پایان
    سرچاپ اس اس ال.خواندن(ا، ۴۰۹۶).طول() > ۰
    اس اس ال.خاموش‌ کردن(ا)
    اس اس ال.بستن(ا)
    اس اس ال.بستن زمینه(ز)
    تی سی پی.بستن(ک)
پایان

اتصال Conn

ساختار اتصال
یک اتصال TLS.
نامانگلیسیگونهتوضیح
دستهhandleتهی*اشاره‌گر حالت اتصال.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Client.salam

پایاها و متغیرها

بدون تایید VERIFY_NONE

پایا بدون تایید: صحیح۳۲ = 0
حالت بررسی: بدون بررسی.
ssl-Server.salam
واردسازی اس اس ال
واردسازی شبکه.تی سی پی

تابع ریشه:
    ز := اس اس ال.زمینه جدید سرور("cert.pem"، "key.pem")
    اگر وارونه اس اس ال.زمینه معتبر(ز):
        سرچاپ اس اس ال.آخرین متن خطا()
        برگشت
    پایان
    اس اس ال.تنظیم تایید(ز، اس اس ال.بدون تایید)
    _ := اس اس ال.بارگذاری مکان تایید(ز، "clients-ca.pem")
    اس اس ال.تنظیم تایید(ز، اس اس ال.تایید طرف مقابل)
    سرچاپ اس اس ال.نوع فایل پم، اس اس ال.تی ال اس۱۲
    س := تی سی پی.پیوند(۸۴۴۳)
    تا درست:
        ک := تی سی پی.پذیرش(س)
        ا := اس اس ال.پوشاندن(ز، ک.توصیفگر)
        اگر اس اس ال.پذیرش(ا):
            درخواست := اس اس ال.خواندن(ا، ۴۰۹۶)
            _ := اس اس ال.نوشتن(ا، "HTTP/1.1 200 OK\r\nContent-Length: " + درخواست.طول() + "\r\n\r\n" + درخواست)
        پایان
        اس اس ال.بستن(ا)
    پایان
پایان

تایید طرف مقابل VERIFY_PEER

پایا تایید طرف مقابل: صحیح۳۲ = 1
حالت بررسی: گواهی طرف مقابل بررسی شود.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Server.salam

نوع فایل پم FILETYPE_PEM

پایا نوع فایل پم: صحیح۳۲ = 1
نوع پرونده‌ی PEM.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Server.salam

تی ال اس۱۲ TLS1_2

پایا تی ال اس۱۲: صحیح۳۲ = 771
شماره‌ی نسخه‌ی TLS 1.2.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Server.salam

تی ال اس۱۳ TLS1_3

پایا تی ال اس۱۳: صحیح۳۲ = 772
شماره‌ی نسخه‌ی TLS 1.3.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Client.salam

گواهی معتبر CERT_OK

پایا گواهی معتبر: صحیح۶۴ = 0
نتیجه‌ی بررسی: گواهی معتبر است.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Client.salam

تابع‌ها

پوشاندن Wrap

تابع پوشاندن(ctx: زمینه، fd: صحیح۶۴): اتصال
اتصال SSL تازه روی یک سوکت باز می‌سازد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Client.salam

اتصال معتبر ConnOk

تابع اتصال معتبر(c: اتصال): منطقی
اتصال ساخته شد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Client.salam

اتصال برقرار کردن Connect

تابع اتصال برقرار کردن(c: اتصال): منطقی
دست‌دهی کارخواه را انجام می‌دهد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Client.salam

پذیرش Accept

تابع پذیرش(c: اتصال): منطقی
دست‌دهی سرور را انجام می‌دهد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Server.salam

خواندن Read

تابع خواندن(c: اتصال، max: صحیح): رشته
تا این قدر بایت را به شکل رشته می‌خواند؛ اگر طرف مقابل بسته باشد خالی است. متن در بایت صفر تمام می‌شود.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Client.salam

نوشتن Write

تابع نوشتن(c: اتصال، data: رشته): صحیح
داده می‌فرستد و شمار بایت‌ها، یا عدد منفی در خطا، را برمی‌گرداند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Client.salam

خاموش‌ کردن Shutdown

تابع خاموش‌ کردن(c: اتصال)
هشدار بستن را می‌فرستد و نشست TLS را تمام می‌کند؛ سوکت باز می‌ماند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Client.salam

بستن Close

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

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Client.salam

کد خطا ErrorCode

تابع کد خطا(c: اتصال، rc: صحیح): صحیح
کد خطا به سبک OpenSSL برای نتیجه‌ی یک خواندن یا نوشتن.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Client.salam

متن خطای اتصال ConnErrorString

تابع متن خطای اتصال(c: اتصال): رشته
متن خطای همین اتصال؛ برخلاف آخرین متن خطا میان نخ‌ها مشترک نیست.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Client.salam

آخرین متن خطا LastErrorString

تابع آخرین متن خطا(): رشته
متن آخرین خطا، و پاک کردن آن.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Client.salam

تنظیم نام میزبان SetHostname

تابع تنظیم نام میزبان(c: اتصال، host: رشته): منطقی
نام میزبان را برای SNI و بررسی گواهی تعیین می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Client.salam

نتیجه تایید VerifyResult

تابع نتیجه تایید(c: اتصال): صحیح۶۴
نتیجه‌ی بررسی گواهی طرف مقابل.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Client.salam

طرف مقابل تاییدشده PeerVerified

تابع طرف مقابل تاییدشده(c: اتصال): منطقی
گواهی طرف مقابل بررسی و پذیرفته شد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Client.salam

زمینه جدید مشتری NewClientContext

تابع زمینه جدید مشتری(): زمینه
زمینه‌ی کارخواه با کمینه‌ی TLS 1.2، بررسی گواهی و ریشه‌های سیستم.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Client.salam

زمینه جدید سرور NewServerContext

تابع زمینه جدید سرور(cert_file: رشته، key_file: رشته): زمینه
زمینه‌ی سرور با گواهی و کلید از پرونده.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Server.salam

زمینه معتبر CtxOk

تابع زمینه معتبر(ctx: زمینه): منطقی
زمینه ساخته شد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Client.salam

تنظیم تایید SetVerify

تابع تنظیم تایید(ctx: زمینه، mode: صحیح)
حالت بررسی گواهی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Server.salam

بارگذاری مکان تایید LoadVerifyLocationsFile

تابع بارگذاری مکان تایید(ctx: زمینه، path: رشته): منطقی
به جای ریشه‌های سیستم به گواهی‌های ریشه‌ی این پرونده‌ی PEM اعتماد می‌کند؛ اگر پرونده گواهی‌ای نداشته باشد نادرست است.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Server.salam

تنظیم مسیرهای پیش‌فرض تایید SetDefaultVerifyPaths

تابع تنظیم مسیرهای پیش‌فرض تایید(ctx: زمینه): منطقی
به ریشه‌های سیستم برمی‌گردد که پیش‌فرض زمینه‌ی تازه است.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Client.salam

تنظیم کمینه نسخه SetMinVersion

تابع تنظیم کمینه نسخه(ctx: زمینه، version: صحیح۶۴): منطقی
کمینه‌ی نسخه‌ی TLS، تی ال اس۱۲ یا تی ال اس۱۳؛ پس از پایان دست‌دهی بررسی می‌شود.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Client.salam

بستن زمینه CloseContext

تابع بستن زمینه(ctx: زمینه)
زمینه را آزاد می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ssl-Client.salam