blob: e878e1a8096af170eaa857068aa67ea6a6e81140 [file] [log] [blame]
Guido van Rossum8ceef412001-09-11 15:54:00 +00001"""HMAC (Keyed-Hashing for Message Authentication) Python module.
2
3Implements the HMAC algorithm as described by RFC 2104.
4"""
5
Guido van Rossuma19f80c2007-11-06 20:51:31 +00006import warnings as _warnings
7
Guido van Rossum3f429082007-07-10 13:35:52 +00008trans_5C = bytes((x ^ 0x5C) for x in range(256))
9trans_36 = bytes((x ^ 0x36) for x in range(256))
Tim Petersb64bec32001-09-18 02:26:39 +000010
Andrew M. Kuchling1ccdff92001-11-02 21:49:20 +000011# The size of the digests returned by HMAC depends on the underlying
Thomas Wouters902d6eb2007-01-09 23:18:33 +000012# hashing module used. Use digest_size from the instance of HMAC instead.
Andrew M. Kuchling1ccdff92001-11-02 21:49:20 +000013digest_size = None
14
Tim Peters934d31b2004-03-20 20:11:29 +000015
Guido van Rossum8ceef412001-09-11 15:54:00 +000016class HMAC:
Guido van Rossuma19f80c2007-11-06 20:51:31 +000017 """RFC 2104 HMAC class. Also complies with RFC 4231.
Guido van Rossum8ceef412001-09-11 15:54:00 +000018
Andrew M. Kuchling1ccdff92001-11-02 21:49:20 +000019 This supports the API for Cryptographic Hash Functions (PEP 247).
Tim Petersb64bec32001-09-18 02:26:39 +000020 """
Thomas Wouters902d6eb2007-01-09 23:18:33 +000021 blocksize = 64 # 512-bit HMAC; can be changed in subclasses.
Guido van Rossum8ceef412001-09-11 15:54:00 +000022
23 def __init__(self, key, msg = None, digestmod = None):
24 """Create a new HMAC object.
25
26 key: key for the keyed hash object.
27 msg: Initial input for the hash, if provided.
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000028 digestmod: A module supporting PEP 247. *OR*
29 A hashlib constructor returning a new hash object.
30 Defaults to hashlib.md5.
Guido van Rossum3f429082007-07-10 13:35:52 +000031
32 Note: key and msg must be bytes objects.
Guido van Rossum8ceef412001-09-11 15:54:00 +000033 """
Tim Peters934d31b2004-03-20 20:11:29 +000034
Alexandre Vassalottia351f772008-03-03 02:59:49 +000035 if not isinstance(key, bytes):
36 raise TypeError("expected bytes, but got %r" % type(key).__name__)
Guido van Rossum3f429082007-07-10 13:35:52 +000037
Raymond Hettinger7fdfc2d2002-05-31 17:49:10 +000038 if digestmod is None:
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000039 import hashlib
40 digestmod = hashlib.md5
Guido van Rossum8ceef412001-09-11 15:54:00 +000041
Guido van Rossumd59da4b2007-05-22 18:11:13 +000042 if hasattr(digestmod, '__call__'):
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000043 self.digest_cons = digestmod
44 else:
Guido van Rossum3f429082007-07-10 13:35:52 +000045 self.digest_cons = lambda d=b'': digestmod.new(d)
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000046
47 self.outer = self.digest_cons()
48 self.inner = self.digest_cons()
49 self.digest_size = self.inner.digest_size
Tim Peters88768482001-11-13 21:51:26 +000050
Guido van Rossuma19f80c2007-11-06 20:51:31 +000051 if hasattr(self.inner, 'block_size'):
52 blocksize = self.inner.block_size
53 if blocksize < 16:
Guido van Rossuma19f80c2007-11-06 20:51:31 +000054 _warnings.warn('block_size of %d seems too small; using our '
55 'default of %d.' % (blocksize, self.blocksize),
56 RuntimeWarning, 2)
57 blocksize = self.blocksize
58 else:
59 _warnings.warn('No block_size attribute on given digest object; '
60 'Assuming %d.' % (self.blocksize),
61 RuntimeWarning, 2)
62 blocksize = self.blocksize
63
Guido van Rossum8ceef412001-09-11 15:54:00 +000064 if len(key) > blocksize:
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000065 key = self.digest_cons(key).digest()
Guido van Rossum8ceef412001-09-11 15:54:00 +000066
Guido van Rossum3f429082007-07-10 13:35:52 +000067 key = key + bytes(blocksize - len(key))
Thomas Wouters902d6eb2007-01-09 23:18:33 +000068 self.outer.update(key.translate(trans_5C))
69 self.inner.update(key.translate(trans_36))
Raymond Hettinger094662a2002-06-01 01:29:16 +000070 if msg is not None:
Guido van Rossum8ceef412001-09-11 15:54:00 +000071 self.update(msg)
72
Guido van Rossum8ceef412001-09-11 15:54:00 +000073 def update(self, msg):
74 """Update this hashing object with the string msg.
75 """
Alexandre Vassalottia351f772008-03-03 02:59:49 +000076 if not isinstance(msg, bytes):
77 raise TypeError("expected bytes, but got %r" % type(msg).__name__)
Guido van Rossum8ceef412001-09-11 15:54:00 +000078 self.inner.update(msg)
79
80 def copy(self):
81 """Return a separate copy of this hashing object.
82
83 An update to this copy won't affect the original object.
84 """
Benjamin Peterson0cc74442010-08-21 02:45:15 +000085 # Call __new__ directly to avoid the expensive __init__.
86 other = self.__class__.__new__(self.__class__)
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000087 other.digest_cons = self.digest_cons
Tim Peters934d31b2004-03-20 20:11:29 +000088 other.digest_size = self.digest_size
Andrew M. Kuchling1ccdff92001-11-02 21:49:20 +000089 other.inner = self.inner.copy()
90 other.outer = self.outer.copy()
91 return other
Guido van Rossum8ceef412001-09-11 15:54:00 +000092
Thomas Wouters902d6eb2007-01-09 23:18:33 +000093 def _current(self):
94 """Return a hash object for the current state.
95
96 To be used only internally with digest() and hexdigest().
97 """
98 h = self.outer.copy()
99 h.update(self.inner.digest())
100 return h
101
Guido van Rossum8ceef412001-09-11 15:54:00 +0000102 def digest(self):
103 """Return the hash value of this hashing object.
104
105 This returns a string containing 8-bit data. The object is
106 not altered in any way by this function; you can continue
107 updating the object after calling this function.
108 """
Thomas Wouters902d6eb2007-01-09 23:18:33 +0000109 h = self._current()
Guido van Rossum8ceef412001-09-11 15:54:00 +0000110 return h.digest()
111
112 def hexdigest(self):
113 """Like digest(), but returns a string of hexadecimal digits instead.
114 """
Thomas Wouters902d6eb2007-01-09 23:18:33 +0000115 h = self._current()
116 return h.hexdigest()
Guido van Rossum8ceef412001-09-11 15:54:00 +0000117
118def new(key, msg = None, digestmod = None):
119 """Create a new hashing object and return it.
120
121 key: The starting key for the hash.
122 msg: if available, will immediately be hashed into the object's starting
Tim Petersb64bec32001-09-18 02:26:39 +0000123 state.
Guido van Rossum8ceef412001-09-11 15:54:00 +0000124
125 You can now feed arbitrary strings into the object using its update()
126 method, and can ask for the hash value at any time by calling its digest()
127 method.
128 """
129 return HMAC(key, msg, digestmod)