base64 --- کدگذاریهای Base16، Base32، Base64 و Base85 برای داده¶
کد منبع: Lib/base64.py
این ماژول توابعی برای کدگذاری دادههای دودویی به نویسههای قابلچاپ ASCII و کدگشایی چنین کدگذاریهایی به دادههای دودویی فراهم میکند. این ماژول شامل کدگذاریهای مشخصشده در RFC 4648 (Base64، Base32 و Base16)، کدگذاری Base85 مشخصشده در PDF 2.0، و گونههای غیراستاندارد Base85 است که در جاهای دیگر استفاده میشوند.
این ماژول دو رابط ارائه میدهد. رابط مدرن از کدگذاری اشیاء شبهبایت به bytes ASCII، و کدگشایی اشیاء شبهبایت یا رشتههای حاوی ASCII به bytes پشتیبانی میکند. هر دو الفبای base-64 تعریفشده در RFC 4648 (معمولی، و امن برای URL و سامانه فایلبندی) پشتیبانی میشوند.
رابط قدیمی از کدگشایی از رشتهها پشتیبانی نمیکند، اما توابعی برای کدگذاری و کدگشایی به و از اشیای پرونده ارائه میدهد. این رابط فقط از الفبای استاندارد Base64 پشتیبانی میکند و مطابق RFC 2045 هر ۷۶ نویسه یک خط جدید اضافه میکند. توجه داشته باشید که اگر به دنبال پشتیبانی از RFC 2045 هستید، احتمالاً بهتر است در عوض به بسته email نگاه کنید.
تغییر یافته در نسخهی 3.3: توابع کدگشایی رابط مدرن اکنون رشتههای یونیکود فقط ASCII را میپذیرند.
تغییر یافته در نسخهی 3.4: اکنون تمامی توابع کدگذاری و کدگشایی این ماژول، هر شیء شبهبایت را میپذیرند. پشتیبانی از Ascii85/Base85 افزوده شد.
کدگذاریهای RFC 4648¶
کدگذاریهای RFC 4648 برای کدگذاری دادههای دودویی مناسب هستند، بهطوری که بتوان آنها را بهصورت امن از طریق ایمیل ارسال کرد، بهعنوان بخشهایی از URLها استفاده کرد، یا بهعنوان بخشی از یک درخواست HTTP POST قرار داد.
- base64.b64encode(s, altchars=None)¶
bytes-like object s را با استفاده از Base64 کدگذاری میکند و
bytesکدگذاریشده را برمیگرداند.altchars اختیاری باید یک شیء شبهبایت به طول ۲ باشد که الفبای جایگزین را برای نویسههای
+و/مشخص میکند. این به یک برنامه اجازه میدهد که برای مثال، رشتههای Base64 امن برای URL یا سیستم پرونده تولید کند. پیشفرضNoneاست، که در این صورت از الفبای استاندارد Base64 استفاده میشود.ممکن است در صورتی که طول altchars ۲ نباشد، assert کند یا یک
ValueErrorرا پرتاب کند. اگر altchars یک bytes-like object نباشد، یکTypeErrorرا پرتاب میکند.
- base64.b64decode(s, altchars=None, validate=False)¶
bytes-like object یا رشتهی ASCII کدگذاریشده با Base64 s را کدگشایی میکند و
bytesکدگشاییشده را برمیگرداند.altchars اختیاری باید یک bytes-like object یا رشتهی ASCII به طول ۲ باشد که الفبای جایگزینی را که بهجای نویسههای
+و/استفاده میشود، مشخص میکند.اگر s بهدرستی پدینگ (padding) نشده باشد، استثنای
binascii.Errorپرتاب میشود.اگر validate برابر
Falseباشد (پیشفرض)، نویسههایی که نه در الفبای عادی base-64 و نه در الفبای جایگزین وجود دارند، پیش از بررسی پرکننده (padding) دور انداخته میشوند. اگر validate برابرTrueباشد، این نویسههای غیرالفبایی در ورودی منجر به پرتاب یکbinascii.Errorمیشوند.برای اطلاعات بیشتر درباره بررسی سختگیرانه base64،
binascii.a2b_base64()را ببینیدممکن است در صورتی که طول altchars برابر ۲ نباشد، assert کند یا یک
ValueErrorرا پرتاب کند.
- base64.standard_b64encode(s)¶
bytes-like object s را با استفاده از الفبای استاندارد Base64 کدگذاری میکند و
bytesکدگذاریشده را برمیگرداند.
- base64.standard_b64decode(s)¶
bytes-like object یا رشته ASCII s را با استفاده از الفبای استاندارد Base64 کدگشایی میکند و
bytesکدگشاییشده را برمیگرداند.
- base64.urlsafe_b64encode(s)¶
bytes-like object s را با استفاده از الفبای امن برای URL و سامانه فایلبندی کدگذاری میکند، که در الفبای استاندارد Base64،
-را به جای+و_را به جای/جایگزین میکند، وbytesکدگذاریشده را برمیگرداند. نتیجه همچنان میتواند شامل=باشد.
- base64.urlsafe_b64decode(s)¶
با استفاده از الفبای امن برای URL و سامانه فایلبندی، که در الفبای استاندارد Base64 بهجای
+از-و بهجای/از_استفاده میکند، bytes-like object یا رشتهی ASCII s را کدگشایی کنید وbytesکدگشاییشده را برگردانید.
- base64.b32encode(s)¶
bytes-like object s را با استفاده از Base32 کدگذاری میکند و
bytesکدگذاریشده را برمیگرداند.
- base64.b32decode(s, casefold=False, map01=None)¶
bytes-like object یا رشته ASCII s را که با Base32 کدگذاریشده است، کدگشایی میکند و
bytesکدگشاییشده را برمیگرداند.casefold اختیاری پرچمی است که مشخص میکند آیا الفبای کوچک بهعنوان ورودی قابلقبول است یا خیر. به دلایل امنیتی، مقدار پیشفرض
Falseاست.RFC 4648 امکان نگاشت اختیاری رقم ۰ (صفر) به حرف O (اوه) و نگاشت اختیاری رقم ۱ (یک) به حرف I (آی) یا حرف L (اِل) را فراهم میکند. آرگومان اختیاری map01، هنگامی که
Noneنباشد، مشخص میکند که رقم ۱ باید به کدام حرف نگاشت شود (هنگامی که map01Noneنباشد، رقم ۰ همیشه به حرف O نگاشت میشود). بهدلایل امنیتی، مقدار پیشفرضNoneاست، تا ۰ و ۱ در ورودی مجاز نباشند.اگر s بهدرستی پد (padding) نشده باشد یا نویسههای خارج از الفبا در ورودی وجود داشته باشند، یک
binascii.Errorپرتاب میشود.
- base64.b32hexencode(s)¶
مشابه
b32encode()است، اما از الفبای مبنای شانزده توسعهیافته (Extended Hex Alphabet) استفاده میکند، همانطور که در RFC 4648 تعریف شده است.اضافه شده در نسخهی 3.10.
- base64.b32hexdecode(s, casefold=False)¶
مشابه
b32decode()است، اما از الفبای مبنای شانزده توسعهیافته (Extended Hex Alphabet) تعریفشده در RFC 4648 استفاده میکند.این نسخه اجازهی نگاشت رقم ۰ (صفر) به حرف O (اوه) و نگاشت رقم ۱ (یک) به حرف I (آی) یا حرف L (اِل) را نمیدهد؛ همهی این نویسهها در الفبای مبنای شانزده توسعهیافته (Extended Hex Alphabet) گنجانده شدهاند و قابل تعویض با یکدیگر نیستند.
اضافه شده در نسخهی 3.10.
- base64.b16encode(s)¶
شیء bytes-like object s را با استفاده از Base16 کدگذاری کنید و
bytesکدگذاریشده را برگردانید.
- base64.b16decode(s, casefold=False)¶
کدگشایی bytes-like object یا رشتهی ASCII s کدگذاریشده با Base16 و برگرداندن
bytesکدگشاییشده.casefold اختیاری پرچمی است که مشخص میکند آیا الفبای کوچک بهعنوان ورودی قابلقبول است یا خیر. به دلایل امنیتی، مقدار پیشفرض
Falseاست.اگر s بهدرستی پد (padding) نشده باشد یا نویسههای خارج از الفبا در ورودی وجود داشته باشند، یک
binascii.Errorپرتاب میشود.
کدگذاریهای Base85¶
کدگذاری Base85 خانوادهای از الگوریتمها است که ۴ بایت را با ۵ نویسهی ASCII بازنمایی میکنند. این کدگذاری در ابتدا در ابزار btoa(1) یونیکس پیادهسازی شد؛ نسخهای از آن بعداً توسط Adobe در زبان PostScript پذیرفته شد و در PDF 2.0 (ISO 32000-2) استاندارد شده است. این نسخه، در هر دو گونهی btoa و PDF خود، توسط a85encode() پیادهسازی شده است.
نسخهای جداگانه، با استفاده از مجموعه نویسه خروجی متفاوت، بهعنوان شوخی روز اول آوریل در RFC 1924 تعریف شد، اما اکنون توسط Git و سایر نرمافزارها استفاده میشود. این نسخه توسط b85encode() پیادهسازی شده است.
در نهایت، نسخه سومی، با استفاده از مجموعهی نویسهی خروجی دیگری که برای درج امن در رشتههای زبان برنامهنویسی طراحی شده است، توسط ZeroMQ تعریف شده و در اینجا توسط z85encode() پیادهسازی شده است.
توابع موجود در این ماژول در نحوهی مدیریت موارد زیر تفاوت دارند:
اینکه آیا باید نشانگرهای دربرگیرندهی
<~و~>را گنجاند و انتظار داشت.اینکه آیا ورودی به چند خط شکسته شود یا خیر.
مجموعهای از نویسههای ASCII که برای کدگذاری استفاده میشوند.
کدگذاریهای فشرده برای دنبالههایی از فاصلهها و بایتهای null.
کدگذاری بایتهای پدینگ صفر (zero-padding) اعمالشده بر ورودی.
برای اطلاعات بیشتر، به مستندات هر یک از توابع مراجعه کنید.
- base64.a85encode(b, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)¶
bytes-like object b را با استفاده از Ascii85 کدگذاری میکند و
bytesکدگذاریشده را برمیگرداند.foldspaces یک پرچم اختیاری است که بهجای ۴ فاصلهی متوالی (ASCII 0x20)، از دنبالهی کوتاه ویژهی 'y' استفاده میکند؛ همانطور که توسط 'btoa' پشتیبانی میشود. این قابلیت توسط کدگذاری استاندارد استفادهشده در PDF پشتیبانی نمیشود.
wrapcol تعیین میکند که آیا باید نویسههای خط جدید (
b'\n') به خروجی افزوده شوند یا خیر. اگر این مقدار غیرصفر باشد، طول هر خط خروجی حداکثر این تعداد نویسه خواهد بود، بدون احتساب نویسه خط جدید پایانی.pad مشخص میکند که آیا پدینگ صفر (zero-padding) اعمالشده به انتهای ورودی بهطور کامل در کدگذاری خروجی حفظ میشوند، همانطور که
btoaاین کار را انجام میدهد و خروجیای تولید میکند که دقیقاً مضربی از ۵ بایت است. این بخشی از کدگذاری استاندارد استفادهشده در PDF نیست، زیرا طول داده را حفظ نمیکند.adobe تعیین میکند که آیا دنبالهی بایتی کدگذاریشده با
<~و~>محصور شود یا خیر، همانگونه که در یک لفظی رشتهای PostScript base-85 وجود دارد. توجه داشته باشید که جریانهای ASCII85Decode در اسناد PDF باید با~>پایان یابند، اما نباید با<~آغاز شوند.اضافه شده در نسخهی 3.4.
- base64.a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \t\n\r\x0b')¶
bytes-like object یا رشتهی ASCII b را که با Ascii85 کدگذاریشده است، کدگشایی میکند و
bytesکدگشاییشده را برمیگرداند.foldspaces پرچمی است که مشخص میکند آیا دنبالهی کوتاه 'y' باید بهعنوان مخففی برای ۴ فاصلهی متوالی (ASCII 0x20) پذیرفته شود یا خیر. این قابلیت در کدگذاری استاندارد Ascii85 که در PDF و PostScript استفاده میشود، پشتیبانی نمیشود.
adobe تعیین میکند که نشانگرهای
<~و~>وجود داشته باشند. اگرچه نشانگر ابتدایی<~الزامی نیست، اما ورودی باید با~>پایان یابد، در غیر این صورت یکValueErrorپرتاب میشود.ignorechars باید یک رشتهی بایتی شامل نویسههایی باشد که باید از ورودی نادیده گرفته شوند. این رشته باید فقط شامل نویسههای فضای سفید باشد، و بهطور پیشفرض شامل تمام نویسههای فضای سفید در ASCII است.
اضافه شده در نسخهی 3.4.
- base64.b85encode(b, pad=False)¶
شیء شبهبایت (bytes-like object) b را با استفاده از base85 (که برای مثال در diffهای دودویی بهسبک git استفاده میشود) کدگذاری میکند و
bytesکدگذاریشده را برمیگرداند.ورودی با
b'\0'پر میشود تا طول آن پیش از کدگذاری مضربی از ۴ بایت باشد. اگر pad درست باشد، تمام نویسههای حاصل در خروجی نگه داشته میشوند؛ خروجی همیشه مضربی از ۵ بایت خواهد بود، و بنابراین ممکن است طول داده هنگام کدگشایی حفظ نشود.اضافه شده در نسخهی 3.4.
- base64.b85decode(b)¶
bytes-like object یا رشتهی ASCII b را که با base85 کدگذاریشده است، کدگشایی میکند و
bytesکدگشاییشده را برمیگرداند.اضافه شده در نسخهی 3.4.
- base64.z85encode(s)¶
bytes-like object s را با استفاده از Z85 (همانطور که در ZeroMQ استفاده میشود) کدگذاری کنید و
bytesکدگذاریشده را برگردانید.مشخصات ZeroMQ الزام میکند که طول دادههای کدگذاریشده با Z85 مضربی از ۵ بایت باشد. برای تولید فریمهای دادهی سازگار، باید دادههای ورودی به این تابع را تا مضربی از ۴ بایت پد کنید.
اضافه شده در نسخهی 3.13.
- base64.z85decode(s)¶
bytes-like object یا رشته ASCII s کدگذاریشده با Z85 را کدگشایی میکند و
bytesکدگشاییشده را برمیگرداند.اضافه شده در نسخهی 3.13.
رابط قدیمی¶
- base64.decode(input, output)¶
محتوای پرونده دودویی input را کدگشایی کنید و دادههای دودویی حاصل را در پرونده output بنویسید. input و output باید اشیای پرونده باشند. input تا زمانی خوانده میشود که
input.readline()یک شیء bytes خالی برگرداند.
- base64.decodebytes(s)¶
bytes-like object s را، که باید شامل یک یا چند خط دادهی کدگذاریشده به base64 باشد، کدگشایی میکند و
bytesکدگشاییشده را برمیگرداند.اضافه شده در نسخهی 3.1.
- base64.encode(input, output)¶
محتویات پرونده دودویی input را کدگذاری کنید و دادههای حاصل کدگذاریشده با base64 را در پرونده output بنویسید. input و output باید اشیای پرونده باشند. input تا زمانی خوانده میشود که
input.read()یک شیء بایت خالی برگرداند.encode()یک نویسه خط جدید (b'\n') را پس از هر ۷۶ بایت از خروجی درج میکند و همچنین اطمینان حاصل میکند که خروجی همیشه با یک خط جدید پایان مییابد، مطابق RFC 2045 (MIME).
- base64.encodebytes(s)¶
شیء شبهبایت s را، که میتواند حاوی دادههای دودویی دلخواه باشد، کدگذاری میکند و
bytesحاوی دادههای کدگذاریشده با base64 را برمیگرداند؛ بهگونهای که سطرهای جدید (b'\n') پس از هر ۷۶ بایت از خروجی درج شوند و اطمینان حاصل شود که یک خط جدید پایانی وجود دارد، مطابق RFC 2045 (MIME).اضافه شده در نسخهی 3.1.
نمونهای از استفاده از ماژول:
>>> import base64
>>> encoded = base64.b64encode(b'data to be encoded')
>>> encoded
b'ZGF0YSB0byBiZSBlbmNvZGVk'
>>> data = base64.b64decode(encoded)
>>> data
b'data to be encoded'
ملاحظات امنیتی¶
بخش ملاحظات امنیتی جدیدی به RFC 4648 (بخش ۱۲) افزوده شده است؛ توصیه میشود بخش امنیتی را برای هر کدی که در محیط عملیاتی مستقر شده است، بازبینی کنید.
همچنین ملاحظه نمائید
- ماژول
binascii ماژول پشتیبانی شامل تبدیلهای ASCII به دودویی و دودویی به ASCII.
- RFC 1521 - MIME (Multipurpose Internet Mail Extensions) بخش یکم: سازوکارهایی برای تعیین و توصیف قالب بدنههای پیام اینترنتی
بخش ۵.۲، «Base64 Content-Transfer-Encoding»، تعریف کدگذاری base64 را ارائه میدهد.
- ISO 32000-2 قالب سند قابلحمل - بخش ۲: PDF 2.0
بخش 7.4.3، «ASCII85Decode Filter»، تعریف کدگذاری Ascii85 استفادهشده در PDF و PostScript را ارائه میدهد، از جمله مجموعه نویسههای خروجی و جزئیات حفظ طول داده با استفاده از پدینگ صفر (zero-padding) و گروههای خروجی جزئی.
- ZeroMQ RFC 32/Z85
بخش «مشخصات رسمی» مجموعه نویسههای مورد استفاده در Z85 را ارائه میدهد.