refactor(docs): improve wording, fix section

[tessus]

I've changed the wording and reorganized the text a bit.

There was also a formatting bug in the md5-crypt section.

[sirainen]

Thanks! We'll need some updates though:

This "all password schemes" isn't really true. CRYPT will support only the *-CRYPT named schemes as mentioned in the deleted text. It doesn't support all the other schemes. Looks like the *-CRYPT ones are under sub-headers of this CRYPT. Except OTP is wrongly in the same level, should fix that too.

Also it's kind of bad that some of the CRYPT schemes are duplicated here, with the second duplication having only minimal text. The long description could be either linked to or moved to include/* files so the full text is duplicated as well via include. We could do this in a separate pull request though.

[tessus]

This "all password schemes" isn't really true. CRYPT will support only the *-CRYPT named schemes as mentioned in the deleted text. It doesn't support all the other schemes.

This statement confused me even more and I ran a bunch of tests. Here are my findings:

My text "it is able to recognize all password schemes available on your system" is 100% accurate and true.

Apart from the explanations in crypt(3) and crypt(5), which already renders your statement slightly incorrect, I have added the following passwords to the passwd-file:

• yescrypt starting with $y$
• gost-yescrypt starting with $gy$
• bcrypt starting with $2b$
• scrypt starting with $7$

None of them are listed under the *-CRYPT schemes, but all of them work and are recognized by dovecot.

I am not sure where to go from here, because I have no idea whether I am still not understanding the documentation.

All I can say is that when I set

passdb passwd-file {
  default_password_scheme = crypt
  ...
  ...
}

all passwords that are supported by libc's crypt() on your operating system are supported and recognized by docvecot, thus can be used in the file specified by passwd_file_path.

P.S.: I also do not understand why a few entries are duplicated at all.

[sirainen]

Well, need to figure out some way to say it more clearly. This same page is listing all kinds of password schemes that are not supported by crypt(). For example SHA256, SSHA256, PBKDF2, maybe ARGON2, ..

I think the duplication idea is to first list the recommended schemes, and later on have a full list. Not sure if it could be done more nicely.

[tessus]

Ok, let me think about it. Maybe we need to move CRYPT to the top then. Since crypt() supports very strong password hashes.
I need to reflect on this a bit.