hmac — Keyed-Hashing för autentisering av meddelanden

Källkod: Lib/hmac.py

Denna modul implementerar HMAC-algoritmen enligt beskrivningen i RFC 2104. Gränssnittet gör det möjligt att använda alla hashfunktioner med en fixerad digeststorlek. I synnerhet kan utdragbara utdatafunktioner som SHAKE-128 eller SHAKE-256 inte användas med HMAC.

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

Returnerar ett nytt hmac-objekt. key är ett bytes- eller bytearray-objekt som anger den hemliga nyckeln. Om msg är närvarande görs metodanropet update(msg). digestmod är digest-namnet, digest-konstruktören eller modulen för HMAC-objektet som ska användas. Det kan vara vilket namn som helst som är lämpligt för hashlib.new(). Trots argumentets position är det obligatoriskt.

Ändrad i version 3.4: Parameter key kan vara ett bytes- eller bytearray-objekt. Parametern msg kan vara av vilken typ som helst som stöds av hashlib. Parametern digestmod kan vara namnet på en hashalgoritm.

Ändrad i version 3.8: Argumentet digestmod är nu obligatoriskt. Skicka det som ett nyckelordsargument för att undvika besvärligheter när du inte har en inledande msg.

hmac.digest(key, msg, digest)

Returnerar digest av msg för given hemlighet key och digest. Funktionen är likvärdig med HMAC(key, msg, digest).digest(), men använder en optimerad C- eller inline-implementering, som är snabbare för meddelanden som ryms i minnet. Parametrarna key, msg och digest har samma betydelse som i new().

CPython-implementeringsdetalj, den optimerade C-implementeringen används endast när digest är en sträng och namnet på en digest-algoritm, som stöds av OpenSSL.

Tillagd i version 3.7.

Ett HMAC-objekt har följande metoder:

HMAC.update(msg)

Uppdatera hmac-objektet med msg. Upprepade anrop är likvärdiga med ett enda anrop med sammankoppling av alla argument: m.update(a); m.update(b) är likvärdigt med m.update(a + b).

Ändrad i version 3.4: Parametern msg kan vara av vilken typ som helst som stöds av hashlib.

HMAC.digest()

Returnerar sammanfattningen av de bytes som hittills skickats till update()-metoden. Detta bytes-objekt kommer att vara lika långt som digest_size för den digest som ges till konstruktören. Det kan innehålla icke-ASCII-bytes, inklusive NUL-bytes.

Varning

När utdata från digest() jämförs med en externt levererad digest under en verifieringsrutin, rekommenderas att funktionen compare_digest() används i stället för operatorn == för att minska sårbarheten för tidsattacker.

HMAC.hexdigest()

Som digest() förutom att digestet returneras som en dubbelt så lång sträng som endast innehåller hexadecimala siffror. Detta kan användas för att utbyta värdet på ett säkert sätt i e-post eller andra icke-binära miljöer.

Varning

När utdata från hexdigest() jämförs med en externt levererad sammanställning under en verifieringsrutin, rekommenderas det att använda funktionen compare_digest() istället för operatorn == för att minska sårbarheten för tidsattacker.

HMAC.copy()

Returnerar en kopia (”klon”) av hmac-objektet. Detta kan användas för att effektivt beräkna digests av strängar som delar en gemensam initial delsträng.

Ett hash-objekt har följande attribut:

HMAC.digest_size

Storleken på den resulterande HMAC-digesten i byte.

HMAC.block_size

Den interna blockstorleken för hashalgoritmen i bytes.

Tillagd i version 3.4.

HMAC.name

Det kanoniska namnet på denna HMAC, alltid med små bokstäver, t.ex. hmac-md5.

Tillagd i version 3.4.

Ändrad i version 3.10: Tog bort de odokumenterade attributen HMAC.digest_cons, HMAC.inner och HMAC.outer.

Denna modul innehåller också följande hjälpfunktion:

hmac.compare_digest(a, b)

Returnerar a == b. Denna funktion använder ett tillvägagångssätt som är utformat för att förhindra tidsanalys genom att undvika innehållsbaserat kortslutningsbeteende, vilket gör den lämplig för kryptografi. a och b måste båda vara av samma typ: antingen str (endast ASCII, som t.ex. returneras av HMAC.hexdigest()), eller en bytesliknande objekt.

Anteckning

Om a och b är olika långa, eller om ett fel inträffar, kan en tidsattack teoretiskt sett avslöja information om typerna och längderna på a och b - men inte deras värden.

Tillagd i version 3.3.

Ändrad i version 3.10: Funktionen använder OpenSSL:s CRYPTO_memcmp() internt när den är tillgänglig.

Se även

Modulen hashlib

Python-modul som tillhandahåller säkra hashfunktioner.