Choosing an appropriate {Htpasswd}{Encoding} in configure

For legacy reasons, the default {Htpasswd}{Encoding} in Foswiki is crypt. This is likely to change in a future release of Foswiki.

The problem: apart from using a very weak hash (md5), crypt has the added limitation that only the first 8 characters of a user's password is used as input. So any user changing their password by changing some characters beyond the 8th will still be able to login using the old password.

Intended audience

This document is intended for administrators who are configuring a new installation of Foswiki, and need to decide which {Htpasswd}{Encoding} mechanism is best for them.

This only applies to installations using the default {PasswordManager} = 'HtpasswdUser' and derivatives (i.e. where Foswiki is managing a .htpasswd style password file). If your Foswiki installation does not use this password manager (Eg. your users will authenticate via some external LDAP/X.509 service instead), then this document does not apply to you.

Note that the {PasswordManager} = Foswiki::Users::ApacheHtpasswdUser is not equivalent to the default HtpasswdUser. It demonstration code and is not recommended for use.

Consider requirements

Template authentication and HTTP Basic authentication both pass the password "in the clear" For best security, use HTTPS, or use Apache Digest authentication.

• If you are using the default {LoginManager} (TemplateLogin), you are free to choose any password encoding. Here are some of the attributes:

Encoding	Hash Length	Salt	Apache	Notes
crypt	11	(2)	y	Password truncated to 8 characters.
sha1	28	no	y	SHA is less secure than Apache MD5 because of no salt
apache-md5	22	(8)	y	Apache specific algorithm
crypt-md5	22	(8)	-	simple md5 hash, understood by apache, but cannot be generated by apache
htdigest-md5	32	no	(mod_digest)	A very secure method only when used with Apache authentication. There is no salt, but the login id, realm and password are mixed together when the md5 is calculated

• Recommendations
  • apache-md5 is the strongest hashing algorithm offered by Foswiki with good compatibility. SHA1 is good but is vulnerable to dictionary attacks due to no salt..
  • Hash strength is moot however; unless you use HTTPS, passwords are passed in the clear between the browser and the server.
  • crypt encoding is not recommended because the password is silently truncated to 8 characters
• If your {LoginManager} is ApacheLogin (I.E. HTTP Basic or Digest authentication) and you want to allow new users to register via Foswiki:

  Apache Digest authentication

  Choose md5 encoding. This uses a weaker hash but has the added benefit of not passing passwords in the clear. (Note, in 1.1.4, this has been renamed to Htdigest-md5)

  HTTP Basic authentication

  Choose apache-md5 encoding for strongest passwords on the server. Passwords are passed in the clear and can be captured

• If you are using some {LoginManager} other than ApacheLogin or TemplateLogin, the {Htpasswd}{Encoding} setting probably does not apply to you.

Changing {Htpasswd}{Encoding} on an existing Foswiki installation

This requires careful planning, because the old passwords will no longer be valid under the newly selected encoding. This may be handled more gracefully in a future release of Foswiki (assuming you use TemplateLogin).

Foswiki 1.1.4 has a new optional password setting - {Htpasswd}{AutoDetect}. When this option is enabled, the default {PasswordManager} = 'HtpasswdUser' will examine the stored password hash to determine what type of encoding was used when the password was originally saved. Password checks will use the stored encoding rather than the configured encoding. However password change will write the new password using the configured encoding, permitting a graceful migration to a new stronger password configuration. Caution: Changing the configured encoding without enabling AutoDetect will probably destroy the stored passwords, especially if changing to/from the md5 / htdigest-md5 encoding.

See also

UserAuthenticationFAQ, UserAuthenticationSupplement