[Bug manual/11902] New: crypt(3) man page is very unclear about glibc extensions.

["tdhutt at gmail dot com" <sourceware-bugzilla at sourceware dot org>]

crypt is: char *crypt(const char *key, const char *salt); where "key is a user's
typed password".

In the crypt man page it states:

       If salt is a character string starting with the characters "$id$" fol‐
       lowed by a string terminated by "$":

              $id$salt$encrypted

       then instead of using the DES machine,  id  identifies  the  encryption
       method  used  and  this  then  determines  how the rest of the password
       string is interpreted. The following values of id are supported:

              ID  | Method
              ─────────────────────────────────────────────────────────
              1   | MD5
              2a  | Blowfish (not in mainline glibc; added in some
                  | Linux distributions)
              5   | SHA-256 (since glibc 2.7)
              6   | SHA-512 (since glibc 2.7)

       So   $5$salt$encrypted   is   an   SHA-256   encoded    password    and
       $6$salt$encrypted is an SHA-512 encoded one.

       "salt" stands for the up to 16 characters following "$id$" in the salt.
       The encrypted part of the password string is the actual computed  pass‐
       word.  The size of this string is fixed:

       MD5     | 22 characters
       SHA-256 | 43 characters
       SHA-512 | 86 characters

       The  characters  in  "salt"  and  "encrypted"  are  drawn  from the set
       [a?zA?Z0?9./].  In the SHA implementation the entire key is significant
       (instead of only the first 8 bytes in MD5).

That's just confusing nonsense. It mostly seems to be describing the string
*returned* by crypt, not what is passed as the 'salt' parameter (how can the
encrypted string be passed *into* the function?).

I think it should read like this:

       If salt is a character string starting with the characters "$id$" fol‐
       lowed by a string terminated by "$":

              $id$salt$

       then instead of using the DES machine,  "id"  identifies  an alternative 
       encryption method to use. "salt" stands for the up to 16 characters 
       to be used as salt. The following values of id are supported:

              ID  | Method
              ─────────────────────────────────────────────────────────
              1   | MD5
              2a  | Blowfish (not in mainline glibc; added in some
                  | Linux distributions)
              5   | SHA-256 (since glibc 2.7)
              6   | SHA-512 (since glibc 2.7)

       So if the "salt" parameter is set to (for example) '$5$AaBb12$' then
       the "key" parameter would be encrypted with SHA-256.

       The return value is the string

              $id$salt$encrypted

       where "encrypted" is the actual computed  password.  The size of
       this string is fixed:

       MD5     | 22 characters
       SHA-256 | 43 characters
       SHA-512 | 86 characters

       The  characters  in  "salt"  and  "encrypted"  are  drawn  from the set
       [a?zA?Z0?9./].  In the SHA implementation the entire key is significant
       (instead of only the first 8 bytes in MD5).

I think this is much clearer and not incorrect.

-- 
           Summary: crypt(3) man page is very unclear about glibc
                    extensions.
           Product: glibc
           Version: 2.10
            Status: NEW
          Severity: normal
          Priority: P2
         Component: manual
        AssignedTo: roland at gnu dot org
        ReportedBy: tdhutt at gmail dot com
                CC: glibc-bugs at sources dot redhat dot com


http://sourceware.org/bugzilla/show_bug.cgi?id=11902

------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.