big-r81 commented on code in PR #5429:
URL: https://github.com/apache/couchdb/pull/5429#discussion_r1951509747
##########
src/docs/src/intro/security.rst:
##########
@@ -312,6 +312,59 @@ several *mandatory* fields, that CouchDB needs for
authentication:
Additionally, you may specify any custom fields that relate to the target
user.
+Password Schemes
+----------------
+
+CouchDB supports several password hashing schemes:
+
+Simple
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The original hashing scheme (``simple`` in ``password_scheme`` field) is a
+single iteration of SHA-1 over the password combined with the salt value. It is
+too weak today, unless the password has especially high entropy.
+
+PBKDF2
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The PBKDF2 hashing scheme (``pbkdf2`` in ``password_scheme`` field) is a
+multiple iteration algorithm using a member of the SHA-2 family. The number of
+iterations is configurable.
+
+Simple plus PBKDF2
+^^^^^^^^^^^^^^^^^^
+
+To aid migration a combined scheme is also available (``simple+pbkdf2`` in
+``password_scheme`` field). If you have ``simple`` credentials in your
+``_users`` database that you don't wish to delete, but are currently unable to
+authenticate with, you can convert the credential to the ``simple+pbkdf2``
+scheme without needing to know the password. CouchDB will apply the ``simple``
+scheme first and then the ``pkbdf2`` algorithm to the result.
+
+Example code to convert ``simple`` to ``simple+pbkdf2`` (Python):
+
+.. code-block:: python
+
+ import hashlib
+
+ hashlib.pbkdf2_hmac('sha256', password_sha, b'salthere', 10000).hex()
+
+The result should be stored in the ``derived_key`` field of the user doc.
+
+Example user doc:
+
+.. code-block:: javascript
+
+ {
+ "type": "user",
+ "name": "user1",
+ "password_scheme": "simple+pbkdf2",
+ "derived_key": "result from above",
+ "pbkdf2_prf": "sha256",
+ "iterations": 10000,
Review Comment:
I know thats an example, but should we use a recommended iterations count of
600000 here?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscr...@couchdb.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
