hmac --- هش کلیددار برای اصالت‌سنجی پیام¶

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

این ماژول الگوریتم HMAC را همان‌طور که در RFC 2104 توصیف شده است، پیاده‌سازی می‌کند. این رابط به شما اجازه می‌دهد از هر تابع هش با اندازه‌ی چکیده ثابت استفاده کنید. به‌طور خاص، نمی‌توانید از توابع خروجی توسعه‌پذیر (extendable output functions) مانند SHAKE-128 یا SHAKE-256 با HMAC استفاده کنید.

hmac.new(key, msg=None, digestmod)¶

یک شیء hmac جدید برمی‌گرداند. key یک شیء bytes یا bytearray حاوی کلید مخفی است. اگر msg وجود داشته باشد، فراخوانی متد update(msg) انجام می‌شود. digestmod نام چکیده، سازنده چکیده یا ماژولی است که شیء HMAC باید از آن استفاده کند. این می‌تواند هر نامی باشد که برای hashlib.new() مناسب است. با وجود جایگاه آرگومانی آن، این آرگومان الزامی است.

تغییر یافته در نسخه‌ی 3.4: پارامتر key می‌تواند یک شیء bytes یا bytearray باشد. پارامتر msg می‌تواند از هر نوعی باشد که hashlib از آن پشتیبانی می‌کند. پارامتر digestmod می‌تواند نام یک الگوریتم هش باشد.

تغییر یافته در نسخه‌ی 3.8: آرگومان digestmod اکنون الزامی است. آن را به‌عنوان آرگومان کلیدواژه‌ای ارسال کنید تا در صورتی که msg اولیه ندارید، از ناهماهنگی جلوگیری شود.

hmac.digest(key, msg, digest)¶

خلاصه‌ی msg را برای key محرمانه و digest داده‌شده برمی‌گرداند. این تابع معادل HMAC(key, msg, digest).digest() است، اما از یک پیاده‌سازی بهینه‌شده به زبان C یا پیاده‌سازی درون‌خطی استفاده می‌کند که برای پیام‌هایی که در حافظه جا می‌شوند سریع‌تر است. پارامترهای key، msg و digest همان معنایی را دارند که در new() آمده است.

جزئیات پیاده‌سازی CPython: پیاده‌سازی بهینه‌ی C تنها زمانی استفاده می‌شود که digest یک رشته و نام یک الگوریتم digest باشد که OpenSSL از آن پشتیبانی می‌کند.

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

class hmac.HMAC¶

یک شیء HMAC دارای متدهای زیر است:

HMAC.update(msg)¶

شیء hmac را با msg به‌روزرسانی کنید. فراخوانی‌های مکرر معادل یک فراخوانی با الحاق همه آرگومان‌ها است: m.update(a); m.update(b) معادل m.update(a + b) است.

تغییر یافته در نسخه‌ی 3.4: پارامتر msg می‌تواند از هر نوعی باشد که توسط hashlib پشتیبانی می‌شود.

HMAC.digest()¶

خلاصه‌ی بایت‌هایی که تاکنون به متد update() داده شده‌اند را برمی‌گرداند. طول این شیء بایت برابر با digest_size خلاصه‌ای خواهد بود که به سازنده داده شده است. ممکن است شامل بایت‌های غیر ASCII، از جمله بایت‌های NUL باشد.

هشدار

هنگام مقایسه‌ی خروجی digest() با یک چکیده تأمین‌شده از خارج در حین یک روال تأیید صحت، توصیه می‌شود برای کاهش آسیب‌پذیری در برابر حملات زمان‌سنجی، از تابع compare_digest() به‌جای عملگر == استفاده کنید.

HMAC.hexdigest()¶

مانند digest() با این تفاوت که چکیده به‌صورت رشته‌ای با طولی دو برابر برگردانده می‌شود که فقط شامل ارقام مبنای شانزده است. می‌توان از آن برای تبادل امن مقدار در ایمیل یا سایر محیط‌های غیردودویی استفاده کرد.

هشدار

هنگام مقایسه‌ی خروجی hexdigest() با یک خلاصه‌ی ارائه‌شده از منبع خارجی در یک روال راستی‌آزمایی، توصیه می‌شود برای کاهش آسیب‌پذیری در برابر حملات زمان‌بندی، به‌جای عملگر == از تابع compare_digest() استفاده کنید.

HMAC.copy()¶

یک کپی («clone») از شیء hmac برمی‌گرداند. می‌توان از آن برای محاسبه‌ی کارآمد چکیده‌های رشته‌هایی که یک زیررشته‌ی آغازین مشترک دارند استفاده کرد.

یک شیء هش دارای ویژگی‌های زیر است:

HMAC.digest_size¶

اندازه‌ی خلاصه‌ی HMAC حاصل بر حسب بایت.

HMAC.block_size¶

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

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

HMAC.name¶

نام کانونیکال این HMAC، همیشه با حروف کوچک، مثلاً hmac-md5.

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

این ماژول همچنین تابع کمکی زیر را فراهم می‌کند:

hmac.compare_digest(a, b)¶

a == b را برمی‌گرداند. این تابع از رویکردی استفاده می‌کند که برای جلوگیری از تحلیل زمانی، با اجتناب از رفتار اتصال کوتاه مبتنی بر محتوا طراحی شده است و آن را برای رمزنگاری مناسب می‌سازد. a و b باید هر دو از یک نوع باشند: یا str (فقط ASCII، مانند آنچه HMAC.hexdigest() برمی‌گرداند)، یا یک bytes-like object.

نکته

اگر a و b طول‌های متفاوتی داشته باشند، یا اگر خطایی رخ دهد، یک حمله زمان‌بندی (timing attack) می‌تواند به‌صورت نظری اطلاعاتی را درباره نوع و طول a و b آشکار کند—اما نه مقادیر آن‌ها.

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

تغییر یافته در نسخه‌ی 3.10: این تابع در صورت موجود بودن، به‌صورت داخلی از CRYPTO_memcmp() در OpenSSL استفاده می‌کند.