Update Md4PasswordEncoder Javadoc

Include format and migration information.

Issue: gh-4674

crypto/src/main/java/org/springframework/security/crypto/password/Md4PasswordEncoder.java

@@ -26,11 +26,51 @@ import java.util.Base64;
 /**
  * This {@link PasswordEncoder} is provided for legacy purposes only and is not considered secure.
  *
- * Encodes passwords using MD4.
+ * Encodes passwords using MD4. The general format of the password is:
+ *
+ * <pre>
+ * s = salt == null ? "" : "{" + salt + "}"
+ * s + md4(password + s)
+ * </pre>
+ *
+ * Such that "salt" is the salt, md4 is the digest method, and password is the actual
+ * password. For example with a password of "password", and a salt of
+ * "thisissalt":
+ *
+ * <pre>
+ * String s = salt == null ? "" : "{" + salt + "}";
+ * s + md4(password + s)
+ * "{thisissalt}" + md4(password + "{thisissalt}")
+ * "{thisissalt}6cc7924dad12ade79dfb99e424f25260"
+ * </pre>
+ *
+ * If the salt does not exist, then omit "{salt}" like this:
+ *
+ * <pre>
+ * md4(password)
+ * </pre>
+ *
+ * If the salt is an empty String, then only use "{}" like this:
+ *
+ * <pre>
+ * "{}" + md4(password + "{}")
+ * </pre>
+ *
+ * The format is intended to work with the Md4PasswordEncoder that was found in the
+ * Spring Security core module. However, the passwords will need to be migrated to include
+ * any salt with the password since this API provides Salt internally vs making it the
+ * responsibility of the user. To migrate passwords from the SaltSource use the following:
+ *
+ * <pre>
+ * String salt = saltSource.getSalt(user);
+ * String s = salt == null ? null : "{" + salt + "}";
+ * String migratedPassword = s + user.getPassword();
+ * </pre>
  *
  * @author Ray Krueger
  * @author Luke Taylor
- * @since 1.0.1
+ * @author Rob winch
+ * @since 5.0
  * @deprecated Digest based password encoding is not considered secure. Instead use an
  * adaptive one way funciton like BCryptPasswordEncoder, Pbkdf2PasswordEncoder, or
  * SCryptPasswordEncoder. Even better use {@link DelegatingPasswordEncoder} which supports

crypto/src/test/java/org/springframework/security/crypto/password/Md4PasswordEncoderTests.java

@@ -66,5 +66,11 @@ public class Md4PasswordEncoderTests {
 
 		assertThat(md4.matches(rawPassword, encodedPassword)).isTrue();
 	}
+
+	@Test
+	public void javadocWhenHasSaltThenMatches() {
+		Md4PasswordEncoder encoder = new Md4PasswordEncoder();
+		assertThat(encoder.matches("password", "{thisissalt}6cc7924dad12ade79dfb99e424f25260"));
+	}
 }