Guido van Rossum | 8ceef41 | 2001-09-11 15:54:00 +0000 | [diff] [blame] | 1 | """HMAC (Keyed-Hashing for Message Authentication) Python module. |
| 2 | |
| 3 | Implements the HMAC algorithm as described by RFC 2104. |
| 4 | """ |
| 5 | |
Gregory P. Smith | e1ac4f1 | 2007-11-06 00:19:03 +0000 | [diff] [blame] | 6 | import warnings as _warnings |
| 7 | |
Benjamin Peterson | 629026a | 2014-05-11 16:11:44 -0700 | [diff] [blame] | 8 | from operator import _compare_digest as compare_digest |
| 9 | |
| 10 | |
Andrew M. Kuchling | 8fe2d20 | 2006-12-19 14:13:05 +0000 | [diff] [blame] | 11 | trans_5C = "".join ([chr (x ^ 0x5C) for x in xrange(256)]) |
| 12 | trans_36 = "".join ([chr (x ^ 0x36) for x in xrange(256)]) |
Tim Peters | b64bec3 | 2001-09-18 02:26:39 +0000 | [diff] [blame] | 13 | |
Andrew M. Kuchling | 1ccdff9 | 2001-11-02 21:49:20 +0000 | [diff] [blame] | 14 | # The size of the digests returned by HMAC depends on the underlying |
Andrew M. Kuchling | a7ebb33 | 2006-12-27 03:25:31 +0000 | [diff] [blame] | 15 | # hashing module used. Use digest_size from the instance of HMAC instead. |
Andrew M. Kuchling | 1ccdff9 | 2001-11-02 21:49:20 +0000 | [diff] [blame] | 16 | digest_size = None |
| 17 | |
Tim Peters | 934d31b | 2004-03-20 20:11:29 +0000 | [diff] [blame] | 18 | # A unique object passed by HMAC.copy() to the HMAC constructor, in order |
| 19 | # that the latter return very quickly. HMAC("") in contrast is quite |
| 20 | # expensive. |
| 21 | _secret_backdoor_key = [] |
| 22 | |
Guido van Rossum | 8ceef41 | 2001-09-11 15:54:00 +0000 | [diff] [blame] | 23 | class HMAC: |
Gregory P. Smith | e1ac4f1 | 2007-11-06 00:19:03 +0000 | [diff] [blame] | 24 | """RFC 2104 HMAC class. Also complies with RFC 4231. |
Guido van Rossum | 8ceef41 | 2001-09-11 15:54:00 +0000 | [diff] [blame] | 25 | |
Andrew M. Kuchling | 1ccdff9 | 2001-11-02 21:49:20 +0000 | [diff] [blame] | 26 | This supports the API for Cryptographic Hash Functions (PEP 247). |
Tim Peters | b64bec3 | 2001-09-18 02:26:39 +0000 | [diff] [blame] | 27 | """ |
Andrew M. Kuchling | a7ebb33 | 2006-12-27 03:25:31 +0000 | [diff] [blame] | 28 | blocksize = 64 # 512-bit HMAC; can be changed in subclasses. |
Guido van Rossum | 8ceef41 | 2001-09-11 15:54:00 +0000 | [diff] [blame] | 29 | |
| 30 | def __init__(self, key, msg = None, digestmod = None): |
| 31 | """Create a new HMAC object. |
| 32 | |
| 33 | key: key for the keyed hash object. |
| 34 | msg: Initial input for the hash, if provided. |
Gregory P. Smith | f21a5f7 | 2005-08-21 18:45:59 +0000 | [diff] [blame] | 35 | digestmod: A module supporting PEP 247. *OR* |
| 36 | A hashlib constructor returning a new hash object. |
| 37 | Defaults to hashlib.md5. |
Guido van Rossum | 8ceef41 | 2001-09-11 15:54:00 +0000 | [diff] [blame] | 38 | """ |
Tim Peters | 934d31b | 2004-03-20 20:11:29 +0000 | [diff] [blame] | 39 | |
| 40 | if key is _secret_backdoor_key: # cheap |
| 41 | return |
| 42 | |
Raymond Hettinger | 7fdfc2d | 2002-05-31 17:49:10 +0000 | [diff] [blame] | 43 | if digestmod is None: |
Gregory P. Smith | f21a5f7 | 2005-08-21 18:45:59 +0000 | [diff] [blame] | 44 | import hashlib |
| 45 | digestmod = hashlib.md5 |
Guido van Rossum | 8ceef41 | 2001-09-11 15:54:00 +0000 | [diff] [blame] | 46 | |
Benjamin Peterson | 4348a25 | 2008-08-19 19:07:38 +0000 | [diff] [blame] | 47 | if hasattr(digestmod, '__call__'): |
Gregory P. Smith | f21a5f7 | 2005-08-21 18:45:59 +0000 | [diff] [blame] | 48 | self.digest_cons = digestmod |
| 49 | else: |
| 50 | self.digest_cons = lambda d='': digestmod.new(d) |
| 51 | |
| 52 | self.outer = self.digest_cons() |
| 53 | self.inner = self.digest_cons() |
| 54 | self.digest_size = self.inner.digest_size |
Tim Peters | 8876848 | 2001-11-13 21:51:26 +0000 | [diff] [blame] | 55 | |
Gregory P. Smith | e1ac4f1 | 2007-11-06 00:19:03 +0000 | [diff] [blame] | 56 | if hasattr(self.inner, 'block_size'): |
| 57 | blocksize = self.inner.block_size |
| 58 | if blocksize < 16: |
| 59 | # Very low blocksize, most likely a legacy value like |
| 60 | # Lib/sha.py and Lib/md5.py have. |
| 61 | _warnings.warn('block_size of %d seems too small; using our ' |
| 62 | 'default of %d.' % (blocksize, self.blocksize), |
| 63 | RuntimeWarning, 2) |
| 64 | blocksize = self.blocksize |
| 65 | else: |
| 66 | _warnings.warn('No block_size attribute on given digest object; ' |
| 67 | 'Assuming %d.' % (self.blocksize), |
| 68 | RuntimeWarning, 2) |
| 69 | blocksize = self.blocksize |
| 70 | |
Guido van Rossum | 8ceef41 | 2001-09-11 15:54:00 +0000 | [diff] [blame] | 71 | if len(key) > blocksize: |
Gregory P. Smith | f21a5f7 | 2005-08-21 18:45:59 +0000 | [diff] [blame] | 72 | key = self.digest_cons(key).digest() |
Guido van Rossum | 8ceef41 | 2001-09-11 15:54:00 +0000 | [diff] [blame] | 73 | |
| 74 | key = key + chr(0) * (blocksize - len(key)) |
Andrew M. Kuchling | 8fe2d20 | 2006-12-19 14:13:05 +0000 | [diff] [blame] | 75 | self.outer.update(key.translate(trans_5C)) |
| 76 | self.inner.update(key.translate(trans_36)) |
Raymond Hettinger | 094662a | 2002-06-01 01:29:16 +0000 | [diff] [blame] | 77 | if msg is not None: |
Guido van Rossum | 8ceef41 | 2001-09-11 15:54:00 +0000 | [diff] [blame] | 78 | self.update(msg) |
| 79 | |
| 80 | ## def clear(self): |
| 81 | ## raise NotImplementedError, "clear() method not available in HMAC." |
| 82 | |
| 83 | def update(self, msg): |
| 84 | """Update this hashing object with the string msg. |
| 85 | """ |
| 86 | self.inner.update(msg) |
| 87 | |
| 88 | def copy(self): |
| 89 | """Return a separate copy of this hashing object. |
| 90 | |
| 91 | An update to this copy won't affect the original object. |
| 92 | """ |
Andrew M. Kuchling | a7ebb33 | 2006-12-27 03:25:31 +0000 | [diff] [blame] | 93 | other = self.__class__(_secret_backdoor_key) |
Gregory P. Smith | f21a5f7 | 2005-08-21 18:45:59 +0000 | [diff] [blame] | 94 | other.digest_cons = self.digest_cons |
Tim Peters | 934d31b | 2004-03-20 20:11:29 +0000 | [diff] [blame] | 95 | other.digest_size = self.digest_size |
Andrew M. Kuchling | 1ccdff9 | 2001-11-02 21:49:20 +0000 | [diff] [blame] | 96 | other.inner = self.inner.copy() |
| 97 | other.outer = self.outer.copy() |
| 98 | return other |
Guido van Rossum | 8ceef41 | 2001-09-11 15:54:00 +0000 | [diff] [blame] | 99 | |
Andrew M. Kuchling | 7166232 | 2006-12-27 03:31:24 +0000 | [diff] [blame] | 100 | def _current(self): |
| 101 | """Return a hash object for the current state. |
| 102 | |
| 103 | To be used only internally with digest() and hexdigest(). |
| 104 | """ |
| 105 | h = self.outer.copy() |
| 106 | h.update(self.inner.digest()) |
| 107 | return h |
| 108 | |
Guido van Rossum | 8ceef41 | 2001-09-11 15:54:00 +0000 | [diff] [blame] | 109 | def digest(self): |
| 110 | """Return the hash value of this hashing object. |
| 111 | |
| 112 | This returns a string containing 8-bit data. The object is |
| 113 | not altered in any way by this function; you can continue |
| 114 | updating the object after calling this function. |
| 115 | """ |
Andrew M. Kuchling | 7166232 | 2006-12-27 03:31:24 +0000 | [diff] [blame] | 116 | h = self._current() |
Guido van Rossum | 8ceef41 | 2001-09-11 15:54:00 +0000 | [diff] [blame] | 117 | return h.digest() |
| 118 | |
| 119 | def hexdigest(self): |
| 120 | """Like digest(), but returns a string of hexadecimal digits instead. |
| 121 | """ |
Andrew M. Kuchling | 7166232 | 2006-12-27 03:31:24 +0000 | [diff] [blame] | 122 | h = self._current() |
| 123 | return h.hexdigest() |
Guido van Rossum | 8ceef41 | 2001-09-11 15:54:00 +0000 | [diff] [blame] | 124 | |
| 125 | def new(key, msg = None, digestmod = None): |
| 126 | """Create a new hashing object and return it. |
| 127 | |
| 128 | key: The starting key for the hash. |
| 129 | msg: if available, will immediately be hashed into the object's starting |
Tim Peters | b64bec3 | 2001-09-18 02:26:39 +0000 | [diff] [blame] | 130 | state. |
Guido van Rossum | 8ceef41 | 2001-09-11 15:54:00 +0000 | [diff] [blame] | 131 | |
| 132 | You can now feed arbitrary strings into the object using its update() |
| 133 | method, and can ask for the hash value at any time by calling its digest() |
| 134 | method. |
| 135 | """ |
| 136 | return HMAC(key, msg, digestmod) |