[enh] Add a complete docstring with explanations and reference

src/yunohost/user.py

@@ -444,17 +444,29 @@ def _convertSize(num, suffix=''):
 
 
 def _hash_user_password(password):
+    """
+    This function computes and return a salted hash for the password in input.
+    This implementation is inspired from [1].
+
+    The hash follows SHA-512 scheme from Linux/glibc.
+    Hence the {CRYPT} and $6$ prefixes
+    - {CRYPT} means it relies on the OS' crypt lib
+    - $6$ corresponds to SHA-512, the strongest hash available on the system
+
+    The salt is generated using random.SystemRandom(). It is the crypto-secure
+    pseudo-random number generator according to the python doc [2] (c.f. the
+    red square). It internally relies on /dev/urandom
+
+    The salt is made of 16 characters from the set [./a-zA-Z0-9]. This is the
+    max sized allowed for salts according to [3]
+
+    [1] https://www.redpill-linpro.com/techblog/2016/08/16/ldap-password-hash.html
+    [2] https://docs.python.org/2/library/random.html
+    [3] https://www.safaribooksonline.com/library/view/practical-unix-and/0596003234/ch04s03.html
+    """
+
     char_set = string.ascii_uppercase + string.ascii_lowercase + string.digits + "./"
-    # This 16 number is chosen according to this documentation stating that
-    # this is the maximum number of salt possible
-    # https://www.safaribooksonline.com/library/view/practical-unix-and/0596003234/ch04s03.html
-    #
-    # SystemRandom is the cryptographically secure random method provided by python stl
-    # You can refer to this https://docs.python.org/2/library/random.html for
-    # confirmation (read the red square), it internally uses /dev/urandom
     salt = ''.join([random.SystemRandom().choice(char_set) for x in range(16)])
 
-    # Using "$6$" means that we uses sha-512 which is the strongest hash available on the system
-    # You can refer to this for more explainations https://www.redpill-linpro.com/techblog/2016/08/16/ldap-password-hash.html
     salt = '$6$' + salt + '$'
     return '{CRYPT}' + crypt.crypt(str(password), salt)