パスワード管理は一般的に、不必要に再発明されるべきではないものです。Djangoはユーザーのパスワードを管理するための安全で柔軟なツールセットを提供するよう努めています。このドキュメントでは、Djangoがパスワードを保存する方法、ストレージハッシュの設定方法、およびハッシュされたパスワードを扱ういくつかのユーティリティについて説明します。
\n\nDjangoはデフォルトでPBKDF2を利用した、柔軟なパスワード保存システムを提供します。
\nThe password attribute of a\nUser object is a string in this format:
<algorithm>$<iterations>$<salt>$<hash>\nこれらはユーザーのパスワードを保存するためのコンポーネントで、ハッシュアルゴリズム、アルゴリズムのイテレーション回数（ワークファクター）、ランダムなソルト、そして結果のパスワードハッシュをドル記号($)で区切ったものです。このアルゴリズムは、Djangoが使用できる数多くの一方向ハッシュ、またはパスワード保存アルゴリズム（下記参照）の一つです。イテレーションはハッシュに対してアルゴリズムが実行された回数を表します。ソルトは使用されたランダムシードで、ハッシュは一方向ハッシュ関数の実行結果です。
\nデフォルトでは、Djangoは NIST が推奨するパスワードストレッチングメカニズムである PBKDF2 アルゴリズムと SHA256 ハッシュを使用します。これはほとんどのユーザーに十分有効なはずです。非常に安全で、クラックするのに膨大な計算時間を必要とします。
\nただし、要件に応じて、異なるアルゴリズムを使用することも、一部のセキュリティ状況に合わせてカスタムアルゴリズムを使用することもできます。繰り返しますが、ほとんどのユーザーはこれを行う必要はありません。よくわからない場合、おそらくそうしないほうが良いです。もしそうする場合は、こちらをお読みください:
\nDjangoは PASSWORD_HASHERS 設定に基づき、使用するアルゴリズムを選択します。これは、Djangoインストールがサポートするハッシュアルゴリズムクラスのリストです。このリストの最初のエントリ（つまり、 settings.PASSWORD_HASHERS[0] ）がパスワードの保存に使用され、他の全てのエントリは、既に存在するパスワードの検証に使用できる有効性検証ハッシャです。つまり、他のアルゴリズムを使用したい場合は PASSWORD_HASHERS を修正して、使用したいアルゴリズムをリストの最初にする必要があります。
デフォルトでの PASSWORD_HASHERS
PASSWORD_HASHERS = [\n 'django.contrib.auth.hashers.PBKDF2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',\n 'django.contrib.auth.hashers.Argon2PasswordHasher',\n 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',\n 'django.contrib.auth.hashers.ScryptPasswordHasher',\n]\nこれは、Djangoは PBKDF2 を使用して全てのパスワードを保存しますが、PBKDF2SHA1、 argon2 、および bcrypt で保存されたパスワードのチェックもサポートすることを意味しています。
\n次のいくつかのセクションでは、高度なユーザーがこの設定を変更するための一般的な方法について説明します。
\nArgon2 is the winner of the 2015 Password Hashing Competition, a community\norganized open competition to select a next generation hashing algorithm. It's\ndesigned not to be easier to compute on custom hardware than it is to compute\non an ordinary CPU.
\nArgon2 is not the default for Django because it requires a third-party\nlibrary. The Password Hashing Competition panel, however, recommends immediate\nuse of Argon2 rather than the other algorithms supported by Django.
\nTo use Argon2 as your default storage algorithm, do the following:
\nInstall the argon2-cffi library. This can be done by running\npython -m pip install django[argon2], which is equivalent to\npython -m pip install argon2-cffi (along with any version requirement\nfrom Django's setup.cfg).
Modify PASSWORD_HASHERS to list Argon2PasswordHasher first.\nThat is, in your settings file, you'd put:
PASSWORD_HASHERS = [\n 'django.contrib.auth.hashers.Argon2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',\n 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',\n 'django.contrib.auth.hashers.ScryptPasswordHasher',\n]\nKeep and/or add any entries in this list if you need Django to upgrade\npasswords.
\nbcrypt with DjangoLink to this heading#Bcrypt is a popular password storage algorithm that's specifically designed\nfor long-term password storage. It's not the default used by Django since it\nrequires the use of third-party libraries, but since many people may want to\nuse it Django supports bcrypt with minimal effort.
\nTo use Bcrypt as your default storage algorithm, do the following:
\nInstall the bcrypt library. This can be done by running\npython -m pip install django[bcrypt], which is equivalent to\npython -m pip install bcrypt (along with any version requirement from\nDjango's setup.cfg).
Modify PASSWORD_HASHERS to list BCryptSHA256PasswordHasher\nfirst. That is, in your settings file, you'd put:
PASSWORD_HASHERS = [\n 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',\n 'django.contrib.auth.hashers.Argon2PasswordHasher',\n 'django.contrib.auth.hashers.ScryptPasswordHasher',\n]\nKeep and/or add any entries in this list if you need Django to upgrade\npasswords.
\nThat's it -- now your Django install will use Bcrypt as the default storage\nalgorithm.
\nscrypt with DjangoLink to this heading#scrypt is similar to PBKDF2 and bcrypt in utilizing a set number of iterations\nto slow down brute-force attacks. However, because PBKDF2 and bcrypt do not\nrequire a lot of memory, attackers with sufficient resources can launch\nlarge-scale parallel attacks in order to speed up the attacking process.\nscrypt is specifically designed to use more memory compared to other\npassword-based key derivation functions in order to limit the amount of\nparallelism an attacker can use, see RFC 7914 for more details.
\nTo use scrypt as your default storage algorithm, do the following:
\nModify PASSWORD_HASHERS to list ScryptPasswordHasher first.\nThat is, in your settings file:
PASSWORD_HASHERS = [\n 'django.contrib.auth.hashers.ScryptPasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',\n 'django.contrib.auth.hashers.Argon2PasswordHasher',\n 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',\n]\nKeep and/or add any entries in this list if you need Django to upgrade\npasswords.
\nMost password hashes include a salt along with their password hash in order to\nprotect against rainbow table attacks. The salt itself is a random value which\nincreases the size and thus the cost of the rainbow table and is currently set\nat 128 bits with the salt_entropy value in the BasePasswordHasher. As\ncomputing and storage costs decrease this value should be raised. When\nimplementing your own password hasher you are free to override this value in\norder to use a desired entropy level for your password hashes. salt_entropy\nis measured in bits.
The PBKDF2 and bcrypt algorithms use a number of iterations or rounds of\nhashing. This deliberately slows down attackers, making attacks against hashed\npasswords harder. However, as computing power increases, the number of\niterations needs to be increased. We've chosen a reasonable default (and will\nincrease it with each release of Django), but you may wish to tune it up or\ndown, depending on your security needs and available processing power. To do so,\nyou'll subclass the appropriate algorithm and override the iterations\nparameter (use the rounds parameter when subclassing a bcrypt hasher). For\nexample, to increase the number of iterations used by the default PBKDF2\nalgorithm:
Create a subclass of django.contrib.auth.hashers.PBKDF2PasswordHasher:
from django.contrib.auth.hashers import PBKDF2PasswordHasher\n\nclass MyPBKDF2PasswordHasher(PBKDF2PasswordHasher):\n """\n A subclass of PBKDF2PasswordHasher that uses 100 times more iterations.\n """\n iterations = PBKDF2PasswordHasher.iterations * 100\nSave this somewhere in your project. For example, you might put this in\na file like myproject/hashers.py.
Add your new hasher as the first entry in PASSWORD_HASHERS:
PASSWORD_HASHERS = [\n 'myproject.hashers.MyPBKDF2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',\n 'django.contrib.auth.hashers.Argon2PasswordHasher',\n 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',\n 'django.contrib.auth.hashers.ScryptPasswordHasher',\n]\nThat's it -- now your Django install will use more iterations when it\nstores passwords using PBKDF2.
\n\nArgon2 has three attributes that can be customized:
\ntime_cost controls the number of iterations within the hash.
memory_cost controls the size of memory that must be used during the\ncomputation of the hash.
parallelism controls how many CPUs the computation of the hash can be\nparallelized on.
The default values of these attributes are probably fine for you. If you\ndetermine that the password hash is too fast or too slow, you can tweak it as\nfollows:
\nChoose parallelism to be the number of threads you can\nspare computing the hash.
Choose memory_cost to be the KiB of memory you can spare.
Adjust time_cost and measure the time hashing a password takes.\nPick a time_cost that takes an acceptable time for you.\nIf time_cost set to 1 is unacceptably slow, lower memory_cost.
scryptLink to this heading#scrypt has four attributes that can be customized:
\nwork_factor controls the number of iterations within the hash.
block_size
parallelism controls how many threads will run in parallel.
maxmem limits the maximum size of memory that can be used during the\ncomputation of the hash. Defaults to 0, which means the default\nlimitation from the OpenSSL library.
We've chosen reasonable defaults, but you may wish to tune it up or down,\ndepending on your security needs and available processing power.
\n\nユーザーがログインする際、もしそのパスワードが推奨されるアルゴリズム以外で保存されていた場合、Djangoは自動で推奨されるアルゴリズムへ更新します。つまり、Djangoの古いインストールでも、ユーザーのログイン時に自動的にセキュリティが強化され、新しい（より良い）保存アルゴリズムが開発されるたびに切り替えることができるということです。
\nHowever, Django can only upgrade passwords that use algorithms mentioned in\nPASSWORD_HASHERS, so as you upgrade to new systems you should make\nsure never to remove entries from this list. If you do, users using\nunmentioned algorithms won't be able to upgrade. Hashed passwords will be\nupdated when increasing (or decreasing) the number of PBKDF2 iterations, bcrypt\nrounds, or argon2 attributes.
データベース上の全てのパスワードがデフォルトのハッシュアルゴリズムでエンコードされていない場合、デフォルト以外のアルゴリズムでエンコードされたパスワードを持つユーザーと、存在しないユーザー（デフォルトのハッシュアルゴリズムが実行されます）に対するログインリクエストにかかる時間の差に起因する、ユーザー列挙型タイミング攻撃に対して脆弱になる可能性があることに注意してください。 古いパスワードハッシュの更新 によりこれを軽減できます。
\nIf you have an existing database with an older, weak hash such as MD5 or SHA1,\nyou might want to upgrade those hashes yourself instead of waiting for the\nupgrade to happen when a user logs in (which may never happen if a user doesn't\nreturn to your site). In this case, you can use a "wrapped" password hasher.
\nFor this example, we'll migrate a collection of SHA1 hashes to use\nPBKDF2(SHA1(password)) and add the corresponding password hasher for checking\nif a user entered the correct password on login. We assume we're using the\nbuilt-in User model and that our project has an accounts app. You can\nmodify the pattern to work with any algorithm or with a custom user model.
First, we'll add the custom hasher:
\naccounts/hashers.pyfrom django.contrib.auth.hashers import (\n PBKDF2PasswordHasher, SHA1PasswordHasher,\n)\n\n\nclass PBKDF2WrappedSHA1PasswordHasher(PBKDF2PasswordHasher):\n algorithm = 'pbkdf2_wrapped_sha1'\n\n def encode_sha1_hash(self, sha1_hash, salt, iterations=None):\n return super().encode(sha1_hash, salt, iterations)\n\n def encode(self, password, salt, iterations=None):\n _, _, sha1_hash = SHA1PasswordHasher().encode(password, salt).split('$', 2)\n return self.encode_sha1_hash(sha1_hash, salt, iterations)\nThe data migration might look something like:
\naccounts/migrations/0002_migrate_sha1_passwords.pyfrom django.db import migrations\n\nfrom ..hashers import PBKDF2WrappedSHA1PasswordHasher\n\n\ndef forwards_func(apps, schema_editor):\n User = apps.get_model('auth', 'User')\n users = User.objects.filter(password__startswith='sha1$')\n hasher = PBKDF2WrappedSHA1PasswordHasher()\n for user in users:\n algorithm, salt, sha1_hash = user.password.split('$', 2)\n user.password = hasher.encode_sha1_hash(sha1_hash, salt)\n user.save(update_fields=['password'])\n\n\nclass Migration(migrations.Migration):\n\n dependencies = [\n ('accounts', '0001_initial'),\n # replace this with the latest migration in contrib.auth\n ('auth', '####_migration_name'),\n ]\n\n operations = [\n migrations.RunPython(forwards_func),\n ]\nBe aware that this migration will take on the order of several minutes for\nseveral thousand users, depending on the speed of your hardware.
\nFinally, we'll add a PASSWORD_HASHERS setting:
mysite/settings.pyPASSWORD_HASHERS = [\n 'django.contrib.auth.hashers.PBKDF2PasswordHasher',\n 'accounts.hashers.PBKDF2WrappedSHA1PasswordHasher',\n]\nInclude any other hashers that your site uses in this list.
\nThe full list of hashers included in Django is:
\n[\n 'django.contrib.auth.hashers.PBKDF2PasswordHasher',\n 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',\n 'django.contrib.auth.hashers.Argon2PasswordHasher',\n 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',\n 'django.contrib.auth.hashers.BCryptPasswordHasher',\n 'django.contrib.auth.hashers.ScryptPasswordHasher',\n 'django.contrib.auth.hashers.SHA1PasswordHasher',\n 'django.contrib.auth.hashers.MD5PasswordHasher',\n 'django.contrib.auth.hashers.UnsaltedSHA1PasswordHasher',\n 'django.contrib.auth.hashers.UnsaltedMD5PasswordHasher',\n 'django.contrib.auth.hashers.CryptPasswordHasher',\n]\nThe corresponding algorithm names are:
\npbkdf2_sha256
pbkdf2_sha1
argon2
bcrypt_sha256
bcrypt
scrypt
sha1
md5
unsalted_sha1
unsalted_md5
crypt
If you write your own password hasher that contains a work factor such as a\nnumber of iterations, you should implement a\nharden_runtime(self, password, encoded) method to bridge the runtime gap\nbetween the work factor supplied in the encoded password and the default\nwork factor of the hasher. This prevents a user enumeration timing attack due\nto difference between a login request for a user with a password encoded in an\nolder number of iterations and a nonexistent user (which runs the default\nhasher's default number of iterations).
Taking PBKDF2 as example, if encoded contains 20,000 iterations and the\nhasher's default iterations is 30,000, the method should run password\nthrough another 10,000 iterations of PBKDF2.
If your hasher doesn't have a work factor, implement the method as a no-op\n(pass).
The django.contrib.auth.hashers module provides a set of functions\nto create and validate hashed passwords. You can use them independently\nfrom the User model.
If you'd like to manually authenticate a user by comparing a plain-text\npassword to the hashed password in the database, use the convenience\nfunction check_password(). It takes two arguments: the plain-text\npassword to check, and the full value of a user's password field in the\ndatabase to check against, and returns True if they match, False\notherwise.
Creates a hashed password in the format used by this application. It takes\none mandatory argument: the password in plain-text (string or bytes).\nOptionally, you can provide a salt and a hashing algorithm to use, if you\ndon't want to use the defaults (first entry of PASSWORD_HASHERS\nsetting). See Included hashers for the algorithm name of each\nhasher. If the password argument is None, an unusable password is\nreturned (one that will never be accepted by check_password()).
Returns False if the password is a result of\nUser.set_unusable_password().
Users often choose poor passwords. To help mitigate this problem, Django\noffers pluggable password validation. You can configure multiple password\nvalidators at the same time. A few validators are included in Django, but you\ncan write your own as well.
\n各パスワードのバリデータは、ユーザーに要件の説明文を与え、指定されたパスワードの妥当性検証を行い、要件を満たしていない場合はエラーメッセージを返し、必要に応じて設定されたパスワードを受信します。バリデータは、それらの挙動を微調整するオプション設定を持つこともできます。
\nValidation is controlled by the AUTH_PASSWORD_VALIDATORS setting.\nThe default for the setting is an empty list, which means no validators are\napplied. In new projects created with the default startproject\ntemplate, a set of validators is enabled by default.
By default, validators are used in the forms to reset or change passwords and\nin the createsuperuser and changepassword management\ncommands. Validators aren't applied at the model level, for example in\nUser.objects.create_user() and create_superuser(), because we assume\nthat developers, not users, interact with Django at that level and also because\nmodel validation doesn't automatically run as part of creating models.
パスワードの妥当性検証は AUTH_PASSWORD_VALIDATORS で構成されます:
AUTH_PASSWORD_VALIDATORS = [\n {\n 'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',\n },\n {\n 'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',\n 'OPTIONS': {\n 'min_length': 9,\n }\n },\n {\n 'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',\n },\n {\n 'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',\n },\n]\n本例では組み込みの4つ全てのバリデータを有効化します。
\nUserAttributeSimilarityValidator は、パスワードとユーザの属性との類似性をチェックします。
MinimumLengthValidator, which checks whether the password meets a minimum\nlength. This validator is configured with a custom option: it now requires\nthe minimum length to be nine characters, instead of the default eight.
CommonPasswordValidator, which checks whether the password occurs in a\nlist of common passwords. By default, it compares to an included list of\n20,000 common passwords.
NumericPasswordValidator は、パスワードが全体的に数値ではないかをチェックします。
For UserAttributeSimilarityValidator and CommonPasswordValidator,\nwe're using the default settings in this example. NumericPasswordValidator\nhas no settings.
The help texts and any errors from password validators are always returned in\nthe order they are listed in AUTH_PASSWORD_VALIDATORS.
Django includes four validators:
\nValidates whether the password meets a minimum length.\nThe minimum length can be customized with the min_length parameter.
Validates whether the password is sufficiently different from certain\nattributes of the user.
\nThe user_attributes parameter should be an iterable of names of user\nattributes to compare to. If this argument is not provided, the default\nis used: 'username', 'first_name', 'last_name', 'email'.\nAttributes that don't exist are ignored.
The maximum allowed similarity of passwords can be set on a scale of 0.1\nto 1.0 with the max_similarity parameter. This is compared to the\nresult of difflib.SequenceMatcher.quick_ratio(). A value of 0.1\nrejects passwords unless they are substantially different from the\nuser_attributes, whereas a value of 1.0 rejects only passwords that are\nidentical to an attribute's value.
Validates whether the password is not a common password. This converts the\npassword to lowercase (to do a case-insensitive comparison) and checks it\nagainst a list of 20,000 common password created by Royce Williams.
\nThe password_list_path can be set to the path of a custom file of\ncommon passwords. This file should contain one lowercase password per line\nand may be plain text or gzipped.
Validates whether the password is not entirely numeric.
\nThere are a few functions in django.contrib.auth.password_validation that\nyou can call from your own forms or other code to integrate password\nvalidation. This can be useful if you use custom forms for password setting,\nor if you have API calls that allow passwords to be set, for example.
Validates a password. If all validators find the password valid, returns\nNone. If one or more validators reject the password, raises a\nValidationError with all the error messages\nfrom the validators.
The user object is optional: if it's not provided, some validators may\nnot be able to perform any validation and will accept any password.
Informs all validators that the password has been changed. This can be used\nby validators such as one that prevents password reuse. This should be\ncalled once the password has been successfully changed.
\nFor subclasses of AbstractBaseUser,\nthe password field will be marked as "dirty" when calling\nset_password() which\ntriggers a call to password_changed() after the user is saved.
Returns a list of the help texts of all validators. These explain the\npassword requirements to the user.
\nReturns an HTML string with all help texts in an <ul>. This is\nhelpful when adding password validation to forms, as you can pass the\noutput directly to the help_text parameter of a form field.
Returns a set of validator objects based on the validator_config\nparameter. By default, all functions use the validators defined in\nAUTH_PASSWORD_VALIDATORS, but by calling this function with an\nalternate set of validators and then passing the result into the\npassword_validators parameter of the other functions, your custom set\nof validators will be used instead. This is useful when you have a typical\nset of validators to use for most scenarios, but also have a special\nsituation that requires a custom set. If you always use the same set\nof validators, there is no need to use this function, as the configuration\nfrom AUTH_PASSWORD_VALIDATORS is used by default.
The structure of validator_config is identical to the\nstructure of AUTH_PASSWORD_VALIDATORS. The return value of\nthis function can be passed into the password_validators parameter\nof the functions listed above.
Note that where the password is passed to one of these functions, this should\nalways be the clear text password - not a hashed password.
\nIf Django's built-in validators are not sufficient, you can write your own\npassword validators. Validators have a fairly small interface. They must\nimplement two methods:
\nvalidate(self, password, user=None): validate a password. Return\nNone if the password is valid, or raise a\nValidationError with an error message if the\npassword is not valid. You must be able to deal with user being\nNone - if that means your validator can't run, return None for no\nerror.
get_help_text(): provide a help text to explain the requirements to\nthe user.
Any items in the OPTIONS in AUTH_PASSWORD_VALIDATORS for your\nvalidator will be passed to the constructor. All constructor arguments should\nhave a default value.
Here's a basic example of a validator, with one optional setting:
\nfrom django.core.exceptions import ValidationError\nfrom django.utils.translation import gettext as _\n\nclass MinimumLengthValidator:\n def __init__(self, min_length=8):\n self.min_length = min_length\n\n def validate(self, password, user=None):\n if len(password) < self.min_length:\n raise ValidationError(\n _("This password must contain at least %(min_length)d characters."),\n code='password_too_short',\n params={'min_length': self.min_length},\n )\n\n def get_help_text(self):\n return _(\n "Your password must contain at least %(min_length)d characters."\n % {'min_length': self.min_length}\n )\nYou can also implement password_changed(password, user=None), which will\nbe called after a successful password change. That can be used to prevent\npassword reuse, for example. However, if you decide to store a user's previous\npasswords, you should never do so in clear text.