Mercurial > p > roundup > code
comparison doc/upgrading.txt @ 7375:9bd7ed918121
issue2551253 - Modify password PBKDF2 method to use SHA512
Implement new PBKDF2-SHA512 more secure password hash function.
Intended to be future default once I get more feedback.
upgrading.txt:
added doc for using it now.
reference.py:
Added enabling future features to use case for interfaces.py.
admin.py:
Changed perftest password command to use the default password
function. Can be used to verify that new hash is enabled properly.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Sat, 20 May 2023 15:34:13 -0400 |
| parents | 692242b3effd |
| children | bb7752f6e1cd |
comparison
equal
deleted
inserted
replaced
| 7374:72de757edf78 | 7375:9bd7ed918121 |
|---|---|
| 207 ``sessiondb`` ``backend`` option as described above. | 207 ``sessiondb`` ``backend`` option as described above. |
| 208 | 208 |
| 209 Update ``config.ini``'s ``password_pbkdf2_default_rounds`` (required) | 209 Update ``config.ini``'s ``password_pbkdf2_default_rounds`` (required) |
| 210 --------------------------------------------------------------------- | 210 --------------------------------------------------------------------- |
| 211 | 211 |
| 212 Roundup hashes passwords using PBKDF2 with SHA1. PBKDF2 has a | 212 Roundup hashes passwords using PBKDF2 with SHA1. In this release, you |
| 213 parameter that makes hashing a password more difficult to do. | 213 can `upgrade to PBKDF2-SHA512 from current PBKDF2-SHA1`. If you |
| 214 The original 10000 value was set years ago. It has not been | 214 upgrade, you want to set the default rounds according to the |
| 215 updated for advancements in computing power. | 215 PBKDF2-SHA512 upgrading directions. Note that this algorithm is |
| 216 expected to be the default in a future version of Roundup. | |
| 217 | |
| 218 If you don't want to upgrade, we recommend that you increase the | |
| 219 default number of rounds from the original 10000. PBKDF2 has a | |
| 220 parameter that makes hashing a password more difficult to do. The | |
| 221 original 10000 value was set years ago. It has not been updated for | |
| 222 advancements in computing power. | |
| 216 | 223 |
| 217 This release of Roundup changes the value to 2000000 (2 | 224 This release of Roundup changes the value to 2000000 (2 |
| 218 million). This exceeds the current `recommended setting of | 225 million). This exceeds the current `recommended setting of |
| 219 1,300,000`_ for PBKDF2 when used with SHA1. | 226 1,300,000`_ for PBKDF2 when used with SHA1. |
| 220 | 227 |
| 221 If you were using the old 10000 value, it will be automatically | 228 .. caution:: |
| 222 upgraded to 2 million by using ``roundup-admin``'s | 229 |
| 223 ``updateconfig``. If you were not using the old 10000 default, | 230 If you were using the old 10000 value, **it will be automatically |
| 224 you should update it manually. | 231 upgraded** to 2 million by using ``roundup-admin``'s |
| 225 | 232 ``updateconfig``. If you were not using the old 10000 default, you |
| 226 After the change users will still be able to log in using the | 233 should update it manually. |
| 227 older 10000 round hashed passwords. If ``migrate_passwords`` is | 234 |
| 228 set to ``yes``, passwords will be automatically re-hashed using | 235 After the change users will still be able to log in using the older |
| 229 the new higher value when the user logs in. | 236 10000 round hashed passwords. If ``migrate_passwords`` is set to |
| 237 ``yes``, passwords will be automatically re-hashed using the new | |
| 238 higher value when the user logs in. If | |
| 239 ``password_pbkdf2_default_rounds`` is set to a lower value than was | |
| 240 used to hash a password, the password will not be rehashed so the | |
| 241 higher value will be kept. The lower value will be used only if the | |
| 242 password is changed using the web or command line. | |
| 230 | 243 |
| 231 Increasing the number of rounds will slow down re-hashing. That's the | 244 Increasing the number of rounds will slow down re-hashing. That's the |
| 232 whole point. Sadly it will also slow down logins. Usually the hash | 245 whole point. Sadly it will also slow down logins. Usually the hash |
| 233 takes under 1 second, but if you are using a slow chip (e.g. an ARM V6 | 246 takes under 1 second, but if you are using a slow chip (e.g. an ARM V6 |
| 234 at 700 bogo mips) it can take 30 seconds to compute the 2000000 | 247 at 700 bogo mips) it can take 30 seconds to compute the 2000000 |
| 238 | 251 |
| 239 You can see how long it will take by using the new ``roundup-admin`` | 252 You can see how long it will take by using the new ``roundup-admin`` |
| 240 ``perftest`` command. After you have finished migrating your database, | 253 ``perftest`` command. After you have finished migrating your database, |
| 241 run:: | 254 run:: |
| 242 | 255 |
| 243 roundup-admin -i <tracker_home> perftest password rounds=10000 | 256 roundup-admin -i <tracker_home> perftest password scheme=PBKDF2 rounds=10000 |
| 244 | 257 |
| 245 and then:: | 258 and then:: |
| 246 | 259 |
| 247 roundup-admin -i <tracker_home> perftest password rounds=2,000,000 | 260 roundup-admin -i <tracker_home> perftest password scheme=PBKDF2 rounds=2,000,000 |
| 248 | 261 |
| 249 so see the difference. Output from this command looks like:: | 262 so see the difference. Output from this command looks like:: |
| 250 | 263 |
| 251 Hash time: 0.203151849s scheme: PBKDF2 rounds: 10000 | 264 Hash time: 0.203151849s scheme: PBKDF2 rounds: 10000 |
| 252 | 265 |
| 253 If your testing reports a hash time in the 0.5 second range for 10000 | 266 If your testing reports a hash time above 0.5 seconds for 10000 |
| 254 rounds, there may be another issue. See if executing:: | 267 rounds, there may be another issue. See if executing:: |
| 255 | 268 |
| 256 python3 -c 'from hashlib import pbkdf2_hmac' | 269 python3 -c 'from hashlib import pbkdf2_hmac' |
| 257 | 270 |
| 258 produces an error. | 271 produces an error. |
| 264 | 277 |
| 265 You should find out how to make the import succeed. You may need to | 278 You should find out how to make the import succeed. You may need to |
| 266 install an OS vendor package or some other library. | 279 install an OS vendor package or some other library. |
| 267 | 280 |
| 268 .. _recommended setting of 1,300,000: https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#pbkdf2 | 281 .. _recommended setting of 1,300,000: https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#pbkdf2 |
| 282 | |
| 283 Upgrade to PBKDF2-SHA512 from current PBKDF2-SHA1 (recommended) | |
| 284 --------------------------------------------------------------- | |
| 285 | |
| 286 We recommend that you upgrade to using PBKDF2-SHA512 for hashing your | |
| 287 passwords. This is a more secure method than the old PBKDF2 (with | |
| 288 SHA1). Because the algorithm is more secure, it uses a smaller value | |
| 289 for ``password_pbkdf2_default_rounds``. Setting | |
| 290 ``password_pbkdf2_default_rounds`` to ``250000`` exceeds the current | |
| 291 `recommended setting of 210,000`_ iterations for PBKDF2 when used with | |
| 292 SHA512. | |
| 293 | |
| 294 You can see how long this takes to calculate on your hardware using | |
| 295 ``roundup-admin``'s perftest command. For example:: | |
| 296 | |
| 297 roundup-admin -i <tracker_home> perftest password scheme=PBKDF2S5 rounds=250,000 | |
| 298 | |
| 299 produces:: | |
| 300 | |
| 301 Hash time: 0.161892945 seconds, scheme: PBKDF2S5, rounds: 250000 | |
| 302 | |
| 303 Any increase in the number of rounds will cause the password to | |
| 304 automatically be rehashed to the higher value the next time the user | |
| 305 logs in via the web interface. Changing the number of rounds to a | |
| 306 **lower** value will not trigger a rehash during login unless the | |
| 307 scheme is also being changed. The lower number will be used only when | |
| 308 the password is explicitly changed using the web interface or the | |
| 309 command line (``roundup-admin`` for example). | |
| 310 | |
| 311 Change the default hashing scheme by adding the following lines to | |
| 312 |the interfaces.py file|_ in your tracker home:: | |
| 313 | |
| 314 ## Use PBDKF2S5 (PBKDF2-SHA512) for passwords. Re-hash old PBDFK2 | |
| 315 # Force password with scheme PBKDF2 (SHA1) to get re-hashed | |
| 316 Password.deprecated_schemes.insert(0, Password.known_schemes[0]) | |
| 317 # choose PBKDF2S5 as the scheme to use for rehashing. | |
| 318 Password.default_scheme = Password.experimental_schemes[0] | |
| 319 | |
| 320 You may need to create the ``interfaces.py`` file if it doesn't exist. | |
| 321 In the future, when the default hash is changed to PBKDF2S5, upgrade | |
| 322 directions will include instructions to remove these lines and | |
| 323 the file ``interfaces.py`` if it becomes empty. | |
| 324 | |
| 325 You can verify that PBKDF2S5 is used by default by running:: | |
| 326 | |
| 327 roundup-admin -i <tracker_home> perftest password rounds=250,000 | |
| 328 | |
| 329 and verify that the scheme is PBKDF2S5. | |
| 330 | |
| 331 .. _the interfaces.py file: | |
| 332 reference.html#interfaces-py-hooking-into-the-core-of-roundup | |
| 333 | |
| 334 .. |the interfaces.py file| replace:: the ``interfaces.py`` file | |
| 335 | |
| 336 .. _recommended setting of 210,000: https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#pbkdf2 | |
| 269 | 337 |
| 270 jQuery updated with updates to user.help.html (recommended) | 338 jQuery updated with updates to user.help.html (recommended) |
| 271 ----------------------------------------------------------- | 339 ----------------------------------------------------------- |
| 272 | 340 |
| 273 The devel and responsive templates shipped with an old version of | 341 The devel and responsive templates shipped with an old version of |