security.py 7.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249
  1. # -*- coding: utf-8 -*-
  2. """
  3. werkzeug.security
  4. ~~~~~~~~~~~~~~~~~
  5. Security related helpers such as secure password hashing tools.
  6. :copyright: 2007 Pallets
  7. :license: BSD-3-Clause
  8. """
  9. import codecs
  10. import hashlib
  11. import hmac
  12. import os
  13. import posixpath
  14. from random import SystemRandom
  15. from struct import Struct
  16. from ._compat import izip
  17. from ._compat import PY2
  18. from ._compat import range_type
  19. from ._compat import text_type
  20. from ._compat import to_bytes
  21. from ._compat import to_native
  22. SALT_CHARS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
  23. DEFAULT_PBKDF2_ITERATIONS = 150000
  24. _pack_int = Struct(">I").pack
  25. _builtin_safe_str_cmp = getattr(hmac, "compare_digest", None)
  26. _sys_rng = SystemRandom()
  27. _os_alt_seps = list(
  28. sep for sep in [os.path.sep, os.path.altsep] if sep not in (None, "/")
  29. )
  30. def pbkdf2_hex(
  31. data, salt, iterations=DEFAULT_PBKDF2_ITERATIONS, keylen=None, hashfunc=None
  32. ):
  33. """Like :func:`pbkdf2_bin`, but returns a hex-encoded string.
  34. .. versionadded:: 0.9
  35. :param data: the data to derive.
  36. :param salt: the salt for the derivation.
  37. :param iterations: the number of iterations.
  38. :param keylen: the length of the resulting key. If not provided,
  39. the digest size will be used.
  40. :param hashfunc: the hash function to use. This can either be the
  41. string name of a known hash function, or a function
  42. from the hashlib module. Defaults to sha256.
  43. """
  44. rv = pbkdf2_bin(data, salt, iterations, keylen, hashfunc)
  45. return to_native(codecs.encode(rv, "hex_codec"))
  46. def pbkdf2_bin(
  47. data, salt, iterations=DEFAULT_PBKDF2_ITERATIONS, keylen=None, hashfunc=None
  48. ):
  49. """Returns a binary digest for the PBKDF2 hash algorithm of `data`
  50. with the given `salt`. It iterates `iterations` times and produces a
  51. key of `keylen` bytes. By default, SHA-256 is used as hash function;
  52. a different hashlib `hashfunc` can be provided.
  53. .. versionadded:: 0.9
  54. :param data: the data to derive.
  55. :param salt: the salt for the derivation.
  56. :param iterations: the number of iterations.
  57. :param keylen: the length of the resulting key. If not provided
  58. the digest size will be used.
  59. :param hashfunc: the hash function to use. This can either be the
  60. string name of a known hash function or a function
  61. from the hashlib module. Defaults to sha256.
  62. """
  63. if not hashfunc:
  64. hashfunc = "sha256"
  65. data = to_bytes(data)
  66. salt = to_bytes(salt)
  67. if callable(hashfunc):
  68. _test_hash = hashfunc()
  69. hash_name = getattr(_test_hash, "name", None)
  70. else:
  71. hash_name = hashfunc
  72. return hashlib.pbkdf2_hmac(hash_name, data, salt, iterations, keylen)
  73. def safe_str_cmp(a, b):
  74. """This function compares strings in somewhat constant time. This
  75. requires that the length of at least one string is known in advance.
  76. Returns `True` if the two strings are equal, or `False` if they are not.
  77. .. versionadded:: 0.7
  78. """
  79. if isinstance(a, text_type):
  80. a = a.encode("utf-8")
  81. if isinstance(b, text_type):
  82. b = b.encode("utf-8")
  83. if _builtin_safe_str_cmp is not None:
  84. return _builtin_safe_str_cmp(a, b)
  85. if len(a) != len(b):
  86. return False
  87. rv = 0
  88. if PY2:
  89. for x, y in izip(a, b):
  90. rv |= ord(x) ^ ord(y)
  91. else:
  92. for x, y in izip(a, b):
  93. rv |= x ^ y
  94. return rv == 0
  95. def gen_salt(length):
  96. """Generate a random string of SALT_CHARS with specified ``length``."""
  97. if length <= 0:
  98. raise ValueError("Salt length must be positive")
  99. return "".join(_sys_rng.choice(SALT_CHARS) for _ in range_type(length))
  100. def _hash_internal(method, salt, password):
  101. """Internal password hash helper. Supports plaintext without salt,
  102. unsalted and salted passwords. In case salted passwords are used
  103. hmac is used.
  104. """
  105. if method == "plain":
  106. return password, method
  107. if isinstance(password, text_type):
  108. password = password.encode("utf-8")
  109. if method.startswith("pbkdf2:"):
  110. args = method[7:].split(":")
  111. if len(args) not in (1, 2):
  112. raise ValueError("Invalid number of arguments for PBKDF2")
  113. method = args.pop(0)
  114. iterations = args and int(args[0] or 0) or DEFAULT_PBKDF2_ITERATIONS
  115. is_pbkdf2 = True
  116. actual_method = "pbkdf2:%s:%d" % (method, iterations)
  117. else:
  118. is_pbkdf2 = False
  119. actual_method = method
  120. if is_pbkdf2:
  121. if not salt:
  122. raise ValueError("Salt is required for PBKDF2")
  123. rv = pbkdf2_hex(password, salt, iterations, hashfunc=method)
  124. elif salt:
  125. if isinstance(salt, text_type):
  126. salt = salt.encode("utf-8")
  127. mac = _create_mac(salt, password, method)
  128. rv = mac.hexdigest()
  129. else:
  130. rv = hashlib.new(method, password).hexdigest()
  131. return rv, actual_method
  132. def _create_mac(key, msg, method):
  133. if callable(method):
  134. return hmac.HMAC(key, msg, method)
  135. def hashfunc(d=b""):
  136. return hashlib.new(method, d)
  137. # Python 2.7 used ``hasattr(digestmod, '__call__')``
  138. # to detect if hashfunc is callable
  139. hashfunc.__call__ = hashfunc
  140. return hmac.HMAC(key, msg, hashfunc)
  141. def generate_password_hash(password, method="pbkdf2:sha256", salt_length=8):
  142. """Hash a password with the given method and salt with a string of
  143. the given length. The format of the string returned includes the method
  144. that was used so that :func:`check_password_hash` can check the hash.
  145. The format for the hashed string looks like this::
  146. method$salt$hash
  147. This method can **not** generate unsalted passwords but it is possible
  148. to set param method='plain' in order to enforce plaintext passwords.
  149. If a salt is used, hmac is used internally to salt the password.
  150. If PBKDF2 is wanted it can be enabled by setting the method to
  151. ``pbkdf2:method:iterations`` where iterations is optional::
  152. pbkdf2:sha256:80000$salt$hash
  153. pbkdf2:sha256$salt$hash
  154. :param password: the password to hash.
  155. :param method: the hash method to use (one that hashlib supports). Can
  156. optionally be in the format ``pbkdf2:<method>[:iterations]``
  157. to enable PBKDF2.
  158. :param salt_length: the length of the salt in letters.
  159. """
  160. salt = gen_salt(salt_length) if method != "plain" else ""
  161. h, actual_method = _hash_internal(method, salt, password)
  162. return "%s$%s$%s" % (actual_method, salt, h)
  163. def check_password_hash(pwhash, password):
  164. """check a password against a given salted and hashed password value.
  165. In order to support unsalted legacy passwords this method supports
  166. plain text passwords, md5 and sha1 hashes (both salted and unsalted).
  167. Returns `True` if the password matched, `False` otherwise.
  168. :param pwhash: a hashed string like returned by
  169. :func:`generate_password_hash`.
  170. :param password: the plaintext password to compare against the hash.
  171. """
  172. if pwhash.count("$") < 2:
  173. return False
  174. method, salt, hashval = pwhash.split("$", 2)
  175. return safe_str_cmp(_hash_internal(method, salt, password)[0], hashval)
  176. def safe_join(directory, *pathnames):
  177. """Safely join zero or more untrusted path components to a base
  178. directory to avoid escaping the base directory.
  179. :param directory: The trusted base directory.
  180. :param pathnames: The untrusted path components relative to the
  181. base directory.
  182. :return: A safe path, otherwise ``None``.
  183. """
  184. parts = [directory]
  185. for filename in pathnames:
  186. if filename != "":
  187. filename = posixpath.normpath(filename)
  188. if (
  189. any(sep in filename for sep in _os_alt_seps)
  190. or os.path.isabs(filename)
  191. or filename == ".."
  192. or filename.startswith("../")
  193. ):
  194. return None
  195. parts.append(filename)
  196. return posixpath.join(*parts)