From 6532bac295fe0f4558369b2cc982565bcfe7981e Mon Sep 17 00:00:00 2001
From: Rob Winch <rwinch@users.noreply.github.com>
Date: Tue, 24 Oct 2017 07:18:48 -0500
Subject: [PATCH] Update Md4PasswordEncoder Javadoc

Include format and migration information.

Issue: gh-4674
---
 .../crypto/password/Md4PasswordEncoder.java   | 44 ++++++++++++++++++-
 .../password/Md4PasswordEncoderTests.java     |  6 +++
 2 files changed, 48 insertions(+), 2 deletions(-)

diff --git a/crypto/src/main/java/org/springframework/security/crypto/password/Md4PasswordEncoder.java b/crypto/src/main/java/org/springframework/security/crypto/password/Md4PasswordEncoder.java
index e19598e19f..3d8264af42 100644
--- a/crypto/src/main/java/org/springframework/security/crypto/password/Md4PasswordEncoder.java
+++ b/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
diff --git a/crypto/src/test/java/org/springframework/security/crypto/password/Md4PasswordEncoderTests.java b/crypto/src/test/java/org/springframework/security/crypto/password/Md4PasswordEncoderTests.java
index 30433cab49..726fe36dfd 100644
--- a/crypto/src/test/java/org/springframework/security/crypto/password/Md4PasswordEncoderTests.java
+++ b/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"));
+	}
 }