hmac — Keyed-Hashing für Nachrichtenauthentifizierung

Quellcode: Lib/hmac.py

Dieses Modul implementiert den HMAC-Algorithmus, wie er von RFC 2104 beschrieben wird. Die Schnittstelle erlaubt die Verwendung jeder Hash-Funktion mit einer *festen* Digest-Größe. Insbesondere Funktionen mit erweiterbarem Ausgabestrom wie SHAKE-128 oder SHAKE-256 können nicht mit HMAC verwendet werden.

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

Gibt ein neues HMAC-Objekt zurück. key ist ein Byte- oder Bytearray-Objekt, das den geheimen Schlüssel enthält. Wenn msg vorhanden ist, wird der Methodenaufruf update(msg) ausgeführt. digestmod ist der Digest-Name, der Digest-Konstruktor oder das Modul, das das HMAC-Objekt verwenden soll. Es kann jeder Name sein, der für hashlib.new() geeignet ist. Trotz seiner Argumentposition ist es erforderlich.

Geändert in Version 3.4: Der Parameter key kann ein Byte- oder Bytearray-Objekt sein. Der Parameter msg kann von jedem Typ sein, der von hashlib unterstützt wird. Der Parameter digestmod kann der Name eines Hash-Algorithmus sein.

Geändert in Version 3.8: Das Argument digestmod ist jetzt erforderlich. Übergeben Sie es als Schlüsselwortargument, um umständliche Situationen zu vermeiden, wenn Sie keine anfängliche msg haben.

hmac.digest(key, msg, digest)

Gibt den Digest von msg für den gegebenen geheimen Schlüssel key und digest zurück. Die Funktion ist äquivalent zu HMAC(key, msg, digest).digest(), verwendet aber eine optimierte C- oder Inline-Implementierung, die für Nachrichten, die in den Speicher passen, schneller ist. Die Parameter key, msg und digest haben die gleiche Bedeutung wie in new().

CPython-Implementierungsdetail: Die optimierte C-Implementierung wird nur verwendet, wenn digest ein String und der Name eines Digest-Algorithmus ist, der von OpenSSL unterstützt wird.

Hinzugefügt in Version 3.7.

class hmac.HMAC

Ein HMAC-Objekt hat die folgenden Methoden

HMAC.update(msg)

Aktualisiert das HMAC-Objekt mit msg. Wiederholte Aufrufe sind äquivalent zu einem einzigen Aufruf mit der Verkettung aller Argumente: m.update(a); m.update(b) ist äquivalent zu m.update(a + b).

Geändert in Version 3.4: Der Parameter msg kann von jedem Typ sein, der von hashlib unterstützt wird.

HMAC.digest()

Gibt den Digest der bisher an die update()-Methode übergebenen Bytes zurück. Dieses Byte-Objekt hat die gleiche Länge wie die digest_size des an den Konstruktor übergebenen Digests. Es kann Nicht-ASCII-Bytes, einschließlich Null-Bytes, enthalten.

Warnung

Beim Vergleich der Ausgabe von digest() mit einem extern bereitgestellten Digest während einer Überprüfungsroutine wird empfohlen, die Funktion compare_digest() anstelle des Operators == zu verwenden, um die Anfälligkeit für Timing-Angriffe zu verringern.

HMAC.hexdigest()

Ähnlich wie digest(), nur dass der Digest als String mit doppelter Länge zurückgegeben wird, der nur hexadezimale Ziffern enthält. Dieser kann verwendet werden, um den Wert sicher in E-Mails oder anderen nicht-binären Umgebungen auszutauschen.

Warnung

Beim Vergleich der Ausgabe von hexdigest() mit einem extern bereitgestellten Digest während einer Überprüfungsroutine wird empfohlen, die Funktion compare_digest() anstelle des Operators == zu verwenden, um die Anfälligkeit für Timing-Angriffe zu verringern.

HMAC.copy()

Gibt eine Kopie ("Klon") des HMAC-Objekts zurück. Dies kann verwendet werden, um effizient die Digests von Strings zu berechnen, die einen gemeinsamen Anfangsstring haben.

Ein Hash-Objekt hat die folgenden Attribute

HMAC.digest_size

Die Größe des resultierenden HMAC-Digests in Bytes.

HMAC.block_size

Die interne Blockgröße des Hash-Algorithmus in Bytes.

Hinzugefügt in Version 3.4.

HMAC.name

Der kanonische Name dieses HMAC, immer in Kleinbuchstaben, z. B. hmac-md5.

Hinzugefügt in Version 3.4.

Geändert in Version 3.10: Die undokumentierten Attribute HMAC.digest_cons, HMAC.inner und HMAC.outer wurden entfernt.

Dieses Modul stellt auch die folgende Hilfsfunktion zur Verfügung

hmac.compare_digest(a, b)

Gibt a == b zurück. Diese Funktion verwendet einen Ansatz, der darauf ausgelegt ist, Timing-Analysen zu verhindern, indem er eine inhaltsbasierte Kurzschlussauswertung vermeidet, was ihn für die Kryptographie geeignet macht. a und b müssen beide vom gleichen Typ sein: entweder str (nur ASCII, wie z. B. von HMAC.hexdigest() zurückgegeben) oder ein bytes-ähnliches Objekt.

Hinweis

Wenn a und b unterschiedliche Längen haben oder ein Fehler auftritt, könnte ein Timing-Angriff theoretisch Informationen über die Typen und Längen von a und b preisgeben – aber nicht über ihre Werte.

Hinzugefügt in Version 3.3.

Geändert in Version 3.10: Die Funktion verwendet intern OpenSSLs CRYPTO_memcmp(), wenn verfügbar.

Siehe auch

Modul hashlib

Das Python-Modul, das sichere Hash-Funktionen bereitstellt.