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.
تغییر یافته در نسخهی 3.10: ویژگیهای بدون مستند HMAC.digest_cons، HMAC.inner و HMAC.outer حذف شدند.
این ماژول همچنین تابع کمکی زیر را فراهم میکند:
- 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 استفاده میکند.
همچنین ملاحظه نمائید
- ماژول
hashlib ماژول پایتون که توابع هش امن را فراهم میکند.