# `hmac` — Keyed-Hashing for Message Authentication

Вихідний код: Lib/hmac.py

Цей модуль реалізує алгоритм HMAC, як описано в RFC 2104.

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: The digestmod argument is now required. Pass it as a keyword argument to avoid awkwardness when you do not have an initial msg.

hmac.digest(key, msg, digest)

  Повернути дайджест повідомлення для заданого секретного ключа та дайджесту. Функція еквівалентна `HMAC(key, msg, digest).digest()`, але використовує оптимізовану C або вбудовану реалізацію, яка є швидшою для повідомлень, які вміщуються в пам’ять. Параметри key, msg і digest мають те саме значення, що й у `new()`.

  Деталі реалізації CPython, оптимізована реалізація C використовується лише тоді, коли digest є рядком і назвою алгоритму дайджесту, який підтримується OpenSSL.

  Нове в версії 3.7.

Об’єкт HMAC має такі методи:

HMAC.update(msg)

  Оновіть об’єкт hmac за допомогою msg. Повторні виклики еквівалентні одному виклику з конкатенацією всіх аргументів: `m.update(a); m.update(b)` еквівалентно `m.update(a + b)`.

  Змінено в версії 3.4: Параметр msg може бути будь-якого типу, який підтримується `hashlib`.

HMAC.digest()

  Повертає дайджест байтів, переданих до цього моменту методу `update()`. Цей об’єкт bytes матиме таку саму довжину, що й digest_size дайджесту, наданого конструктору. Він може містити байти, відмінні від ASCII, включаючи байти NUL.

  Попередження

  When comparing the output of `digest()` to an externally supplied digest during a verification routine, it is recommended to use the `compare_digest()` function instead of the `==` operator to reduce the vulnerability to timing attacks.

HMAC.hexdigest()

  Подібно до `digest()`, за винятком того, що дайджест повертається як рядок подвійної довжини, що містить лише шістнадцяткові цифри. Це можна використовувати для безпечного обміну значенням в електронній пошті чи в інших небінарних середовищах.

  Попередження

  When comparing the output of `hexdigest()` to an externally supplied digest during a verification routine, it is recommended to use the `compare_digest()` function instead of the `==` operator to reduce the vulnerability to timing attacks.

HMAC.copy()

  Повертає копію («клон») об’єкта hmac. Це можна використовувати для ефективного обчислення дайджестів рядків, які мають спільний початковий підрядок.

Хеш-об’єкт має такі атрибути:

HMAC.digest_size

  Розмір отриманого дайджесту HMAC у байтах.

HMAC.block_size

  Розмір внутрішнього блоку хеш-алгоритму в байтах.

  Нове в версії 3.4.

HMAC.name

  Канонічна назва цього HMAC, завжди в нижньому регістрі, напр. `hmac-md5`.

  Нове в версії 3.4.

Змінено в версії 3.10: Removed the undocumented attributes `HMAC.digest_cons`, `HMAC.inner`, and `HMAC.outer`.

Цей модуль також надає такі допоміжні функції:

hmac.compare_digest(a, b)

  Повернути `a == b`. Ця функція використовує підхід, призначений для запобігання аналізу часу шляхом уникнення короткого замикання на основі вмісту, що робить її придатною для криптографії. a і b мають бути одного типу: або `str` (тільки ASCII, як, наприклад, повертає `HMAC.hexdigest()`), або bytes-like object.

  Примітка

  Якщо a і b мають різну довжину або якщо сталася помилка, атака на синхронізацію теоретично може відкрити інформацію про типи та довжини a і b, але не їхні значення.

  Нове в версії 3.3.

  Змінено в версії 3.10: Функція внутрішньо використовує `CRYPTO_memcmp()` OpenSSL, якщо доступний.

Дивись також

Модуль `hashlib`

  Модуль Python, що забезпечує безпечні хеш-функції.