*: support MySQL dual passwords (RETAIN CURRENT PASSWORD / DISCARD OLD PASSWORD)

Adds MySQL 8.0-compatible dual-password support for credential rotation
without downtime:

- Parser: new RETAIN CURRENT PASSWORD and DISCARD OLD PASSWORD clauses
  on ALTER USER and SET PASSWORD; RETAIN/DISCARD/OLD registered as
  non-reserved keywords.
- Privilege cache: UserRecord.AdditionalAuthenticationString, decoded
  from mysql.user.user_attributes '$.additional_password'.
- Auth: ConnectionVerification falls back to the secondary password for
  mysql_native_password / caching_sha2_password / tidb_sm3_password when
  the primary check fails.
- Privilege: APPLICATION_PASSWORD_ADMIN dynamic privilege; required when
  RETAIN/DISCARD is applied to another user's account (self-service is
  always allowed, whether the statement uses CURRENT_USER() or names
  the caller explicitly).
- Executor: executeCreateUser rejects RETAIN/DISCARD (per MySQL);
  executeAlterUser and executeSetPwd promote the current
  authentication_string to user_attributes.additional_password on
  RETAIN, JSON_REMOVE on DISCARD, and silently drop the secondary on a
  plugin change (matching MySQL behavior).
- Error codes: ErrCurrentPasswordCannotBeRetainedPluginChange (4058),
  ErrCurrentPasswordCannotBeRetainedEmptyNew (4059) — MySQL-compatible.
- Tests: 10 unit tests in pkg/executor/test/passwordtest/dual_password_test.go
  plus integration test in tests/integrationtest/t/executor/dual_password.test.

Ref #60587

Author: takaidohigasi

pkg/errno/errcode.go

@@ -945,6 +945,12 @@ const (
 	ErrEngineAttributeNotSupported                           = 3981
 	ErrJSONInBooleanContext                                  = 3986
 	ErrTableWithoutPrimaryKey                                = 3750
+	// Dual-password (RETAIN CURRENT PASSWORD / DISCARD OLD PASSWORD) — match MySQL 8.0.
+	ErrCurrentPasswordNotRequired                  = 3892
+	ErrDuplicatePasswordSpecifiedKeywords          = 3864
+	ErrCurrentPasswordCannotBeRetainedPluginChange = 4058
+	ErrCurrentPasswordCannotBeRetainedEmptyNew     = 4059
+	ErrCurrentPasswordCannotBeRetainedEmptyPrimary = 4060
 	// MariaDB errors.
 	ErrOnlyOneDefaultPartionAllowed         = 4030
 	ErrWrongPartitionTypeExpectedSystemTime = 4113

pkg/errno/errname.go

@@ -946,6 +946,12 @@ var MySQLErrName = map[uint16]*mysql.ErrMessage{
 	ErrDependentByCheckConstraint:                            mysql.Message("Check constraint '%s' uses column '%s', hence column cannot be dropped or renamed.", nil),
 	ErrEngineAttributeNotSupported:                           mysql.Message("Storage engine does not support ENGINE_ATTRIBUTE.", nil),
 	ErrJSONInBooleanContext:                                  mysql.Message("Evaluating a JSON value in SQL boolean context does an implicit comparison against JSON integer 0; if this is not what you want, consider converting JSON to a SQL numeric type with JSON_VALUE RETURNING", nil),
+	// Dual-password errors — match MySQL 8.0 text.
+	ErrCurrentPasswordNotRequired:                  mysql.Message("Current password needs to be specified only if it exists.", nil),
+	ErrDuplicatePasswordSpecifiedKeywords:          mysql.Message("RETAIN CURRENT PASSWORD and DISCARD OLD PASSWORD clauses are mutually exclusive in a single ALTER USER statement.", nil),
+	ErrCurrentPasswordCannotBeRetainedPluginChange: mysql.Message("Current password can not be retained for user '%-.64s'@'%-.64s' because authentication plugin is being changed.", nil),
+	ErrCurrentPasswordCannotBeRetainedEmptyNew:     mysql.Message("Current password can not be retained for user '%-.64s'@'%-.64s' because new password is empty.", nil),
+	ErrCurrentPasswordCannotBeRetainedEmptyPrimary: mysql.Message("Empty current password can not be retained as secondary password for user '%-.64s'@'%-.64s'.", nil),
 	// MariaDB errors.
 	ErrOnlyOneDefaultPartionAllowed:         mysql.Message("Only one DEFAULT partition allowed", nil),
 	ErrWrongPartitionTypeExpectedSystemTime: mysql.Message("Wrong partitioning type, expected type: `SYSTEM_TIME`", nil),

pkg/executor/simple.go

@@ -47,6 +47,7 @@ import (
 	"github.com/pingcap/tidb/pkg/parser/auth"
 	"github.com/pingcap/tidb/pkg/parser/format"
 	"github.com/pingcap/tidb/pkg/parser/mysql"
+	"github.com/pingcap/tidb/pkg/parser/terror"
 	"github.com/pingcap/tidb/pkg/planner/core"
 	"github.com/pingcap/tidb/pkg/planner/core/resolve"
 	"github.com/pingcap/tidb/pkg/plugin"
@@ -124,6 +125,8 @@ type passwordOrLockOptionsInfo struct {
 	passwordLockTime            int64
 	failedLoginAttemptsChange   bool
 	passwordLockTimeChange      bool
+	retainCurrentPassword       bool
+	discardOldPassword          bool
 }
 
 type passwordReuseInfo struct {
@@ -917,8 +920,15 @@ func (info *passwordOrLockOptionsInfo) loadOptions(plOption []*ast.PasswordOrLoc
 		case ast.PasswordReuseDefault:
 			info.passwordReuseInterval = notSpecified
 			info.passwordReuseIntervalChange = true
+		case ast.RetainCurrentPassword:
+			info.retainCurrentPassword = true
+		case ast.DiscardOldPassword:
+			info.discardOldPassword = true
 		}
 	}
+	if info.retainCurrentPassword && info.discardOldPassword {
+		return exeerrors.ErrDuplicatePasswordSpecifiedKeywords.GenWithStackByArgs()
+	}
 	return nil
 }
 
@@ -1090,6 +1100,14 @@ func (e *SimpleExec) executeCreateUser(ctx context.Context, s *ast.CreateUserStm
 	if err != nil {
 		return err
 	}
+	// MySQL rejects RETAIN CURRENT PASSWORD / DISCARD OLD PASSWORD in CREATE USER;
+	// a new user always starts with a single primary password.
+	if plOptions.retainCurrentPassword {
+		return errors.Errorf("RETAIN CURRENT PASSWORD clause is not supported in CREATE USER statement")
+	}
+	if plOptions.discardOldPassword {
+		return errors.Errorf("DISCARD OLD PASSWORD clause is not supported in CREATE USER statement")
+	}
 	passwordLocking := createUserFailedLoginJSON(plOptions)
 	if s.IsCreateRole {
 		plOptions.lockAccount = "Y"
@@ -1719,6 +1737,7 @@ func (e *SimpleExec) executeAlterUser(ctx context.Context, s *ast.AlterUserStmt)
 	hasSystemUserPriv := checker.RequestDynamicVerification(activeRoles, "SYSTEM_USER", false)
 	hasRestrictedUserPriv := checker.RequestDynamicVerification(activeRoles, "RESTRICTED_USER_ADMIN", false)
 	hasSystemSchemaPriv := checker.RequestVerification(activeRoles, mysql.SystemDB, mysql.UserTable, "", mysql.UpdatePriv)
+	hasApplicationPasswordAdminPriv := checker.RequestDynamicVerification(activeRoles, "APPLICATION_PASSWORD_ADMIN", false)
 
 	var authTokenOptions []*ast.AuthTokenOrTLSOption
 	for _, authTokenOrTLSOption := range s.AuthTokenOrTLSOptions {
@@ -1795,6 +1814,32 @@ func (e *SimpleExec) executeAlterUser(ctx context.Context, s *ast.AlterUserStmt)
 			continue
 		}
 
+		// MySQL-compatible dual password: RETAIN CURRENT PASSWORD / DISCARD OLD PASSWORD validation.
+		// https://dev.mysql.com/doc/refman/8.0/en/password-management.html#password-management-dual-password
+		if plOptions.retainCurrentPassword || plOptions.discardOldPassword {
+			// Cross-user use of either clause requires APPLICATION_PASSWORD_ADMIN.
+			if !alterCurrentUser && !hasApplicationPasswordAdminPriv {
+				return plannererrors.ErrSpecificAccessDenied.GenWithStackByArgs("APPLICATION_PASSWORD_ADMIN")
+			}
+			// Only password-based auth plugins can hold a secondary password.
+			if !isDualPasswordCapablePlugin(currentAuthPlugin) {
+				return errors.Errorf("Dual password is not supported for users authenticating with plugin '%s'", currentAuthPlugin)
+			}
+		}
+		if plOptions.retainCurrentPassword {
+			// RETAIN requires a new password to be set, with the same plugin, and the new password must be non-empty.
+			if spec.AuthOpt == nil || !(spec.AuthOpt.ByAuthString || spec.AuthOpt.ByHashString) {
+				return exeerrors.ErrCurrentPasswordCannotBeRetainedEmptyNew.GenWithStackByArgs(spec.User.Username, spec.User.Hostname)
+			}
+			if spec.AuthOpt.AuthPlugin != "" && spec.AuthOpt.AuthPlugin != currentAuthPlugin {
+				return exeerrors.ErrCurrentPasswordCannotBeRetainedPluginChange.GenWithStackByArgs(spec.User.Username, spec.User.Hostname)
+			}
+			if (spec.AuthOpt.ByAuthString && spec.AuthOpt.AuthString == "") ||
+				(spec.AuthOpt.ByHashString && spec.AuthOpt.HashString == "") {
+				return exeerrors.ErrCurrentPasswordCannotBeRetainedEmptyNew.GenWithStackByArgs(spec.User.Username, spec.User.Hostname)
+			}
+		}
+
 		type AuthTokenOptionHandler int
 		const (
 			// noNeedAuthTokenOptions means the final auth plugin is NOT tidb_auth_plugin
@@ -1965,13 +2010,35 @@ func (e *SimpleExec) executeAlterUser(ctx context.Context, s *ast.AlterUserStmt)
 		if passwordLockingStr != "" {
 			newAttributes = append(newAttributes, passwordLockingStr)
 		}
+		// MySQL-compatible dual password: if RETAIN CURRENT PASSWORD is requested,
+		// capture the current authentication_string as the secondary password before
+		// overwriting it in this UPDATE.
+		if plOptions.retainCurrentPassword {
+			attrObj, err := buildAdditionalPasswordJSON(ctx, sqlExecutor, spec.User.Username, spec.User.Hostname)
+			if err != nil {
+				return err
+			}
+			// attrObj is a full JSON object; trim the surrounding braces so it can
+			// be concatenated with the other newAttributes entries.
+			newAttributes = append(newAttributes, strings.TrimSuffix(strings.TrimPrefix(attrObj, "{"), "}"))
+		}
 		if length := len(newAttributes); length > 0 {
 			if length > 1 || passwordLockingStr == "" {
 				passwordLockingInfo.containsNoOthers = false
 			}
 			newAttributesStr := fmt.Sprintf("{%s}", strings.Join(newAttributes, ","))
 			fields = append(fields, alterField{"user_attributes=json_merge_patch(coalesce(user_attributes, '{}'), %?)", newAttributesStr})
 		}
+		// DISCARD OLD PASSWORD removes the secondary password.
+		// MySQL also silently drops the secondary when the auth plugin is changed;
+		// detect that here and do the same.
+		dropSecondary := plOptions.discardOldPassword
+		if !dropSecondary && spec.AuthOpt != nil && spec.AuthOpt.AuthPlugin != "" && spec.AuthOpt.AuthPlugin != currentAuthPlugin {
+			dropSecondary = true
+		}
+		if dropSecondary && !plOptions.retainCurrentPassword {
+			fields = append(fields, alterField{"user_attributes=json_remove(coalesce(user_attributes, '{}'), '$.additional_password')", nil})
+		}
 
 		switch authTokenOptionHandler {
 		case noNeedAuthTokenOptions:
@@ -2456,6 +2523,65 @@ func userExists(ctx context.Context, sctx sessionctx.Context, name string, host
 }
 
 // use the same internal executor to read within the same transaction, otherwise same as userExists
+// isDualPasswordCapablePlugin reports whether a user whose plugin is `plugin` is
+// eligible to hold a secondary ("additional") password. Dual passwords are only
+// meaningful for password-based plugins. LDAP / socket / token plugins are excluded,
+// matching MySQL 8.0 behavior.
+func isDualPasswordCapablePlugin(plugin string) bool {
+	switch plugin {
+	case mysql.AuthNativePassword, mysql.AuthCachingSha2Password, mysql.AuthTiDBSM3Password:
+		return true
+	}
+	return false
+}
+
+// readAuthenticationString returns the current authentication_string for the
+// given user, using the supplied system session's executor. The second return
+// value is true when a row was found, false otherwise — callers must check it
+// before treating an empty string as a legitimate empty password vs. a missing
+// user. Used when RETAIN CURRENT PASSWORD needs to capture the pre-change hash
+// as the secondary password.
+func readAuthenticationString(ctx context.Context, sqlExecutor sqlexec.SQLExecutor, name, host string) (string, bool, error) {
+	sql := new(strings.Builder)
+	sqlescape.MustFormatSQL(sql, `SELECT authentication_string FROM %n.%n WHERE User=%? AND Host=%? FOR UPDATE;`, mysql.SystemDB, mysql.UserTable, name, strings.ToLower(host))
+	rs, err := sqlExecutor.ExecuteInternal(ctx, sql.String())
+	if err != nil {
+		return "", false, err
+	}
+	defer terror.Call(rs.Close)
+	req := rs.NewChunk(nil)
+	if err := rs.Next(ctx, req); err != nil {
+		return "", false, err
+	}
+	if req.NumRows() == 0 {
+		return "", false, nil
+	}
+	return req.GetRow(0).GetString(0), true, nil
+}
+
+// buildAdditionalPasswordJSON reads the user's current authentication_string
+// and returns a JSON-object fragment `{"additional_password": "<hash>"}`
+// suitable for merging into user_attributes via JSON_MERGE_PATCH.
+// It fails when the user doesn't exist or when the current primary password is
+// empty — MySQL rejects RETAIN CURRENT PASSWORD in both situations.
+func buildAdditionalPasswordJSON(ctx context.Context, sqlExecutor sqlexec.SQLExecutor, name, host string) (string, error) {
+	oldPwd, found, err := readAuthenticationString(ctx, sqlExecutor, name, host)
+	if err != nil {
+		return "", err
+	}
+	if !found {
+		return "", exeerrors.ErrPasswordNoMatch
+	}
+	if oldPwd == "" {
+		return "", exeerrors.ErrCurrentPasswordCannotBeRetainedEmptyPrimary.GenWithStackByArgs(name, host)
+	}
+	encoded, err := json.Marshal(oldPwd)
+	if err != nil {
+		return "", err
+	}
+	return fmt.Sprintf(`{"additional_password": %s}`, encoded), nil
+}
+
 func userExistsInternal(ctx context.Context, sqlExecutor sqlexec.SQLExecutor, name string, host string) (bool, string, error) {
 	sql := new(strings.Builder)
 	sqlescape.MustFormatSQL(sql, `SELECT * FROM %n.%n WHERE User=%? AND Host=%? FOR UPDATE;`, mysql.SystemDB, mysql.UserTable, name, strings.ToLower(host))
@@ -2515,22 +2641,34 @@ func (e *SimpleExec) executeSetPwd(ctx context.Context, s *ast.SetPwdStmt) error
 
 	var u, h string
 	disableSandboxMode := false
-	if s.User == nil || s.User.CurrentUser {
-		if e.Ctx().GetSessionVars().User == nil {
+	sessUser := e.Ctx().GetSessionVars().User
+	// setPwdForSelf matches executeAlterUser's alterCurrentUser idiom: treat an
+	// explicit `FOR 'self'@'host'` that names the caller as self-service, not
+	// cross-user. MySQL 8.0 documents this — APPLICATION_PASSWORD_ADMIN is only
+	// required when the statement names a *different* account.
+	setPwdForSelf := s.User == nil || s.User.CurrentUser ||
+		(sessUser != nil && sessUser.Username == s.User.Username && sessUser.AuthHostname == s.User.Hostname)
+	if setPwdForSelf {
+		if sessUser == nil {
 			return errors.New("Session error is empty")
 		}
-		u = e.Ctx().GetSessionVars().User.AuthUsername
-		h = e.Ctx().GetSessionVars().User.AuthHostname
+		u = sessUser.AuthUsername
+		h = sessUser.AuthHostname
 	} else {
 		u = s.User.Username
 		h = s.User.Hostname
 
 		checker := privilege.GetPrivilegeManager(e.Ctx())
 		activeRoles := e.Ctx().GetSessionVars().ActiveRoles
 		if checker != nil && !checker.RequestVerification(activeRoles, "", "", "", mysql.SuperPriv) {
-			currUser := e.Ctx().GetSessionVars().User
+			currUser := sessUser
 			return exeerrors.ErrDBaccessDenied.GenWithStackByArgs(currUser.Username, currUser.Hostname, "mysql")
 		}
+		// MySQL: RETAIN CURRENT PASSWORD on another user requires APPLICATION_PASSWORD_ADMIN.
+		if s.RetainCurrentPassword && checker != nil &&
+			!checker.RequestDynamicVerification(activeRoles, "APPLICATION_PASSWORD_ADMIN", false) {
+			return plannererrors.ErrSpecificAccessDenied.GenWithStackByArgs("APPLICATION_PASSWORD_ADMIN")
+		}
 	}
 	exists, authplugin, err := userExistsInternal(ctx, sqlExecutor, u, h)
 	if err != nil {
@@ -2539,6 +2677,14 @@ func (e *SimpleExec) executeSetPwd(ctx context.Context, s *ast.SetPwdStmt) error
 	if !exists {
 		return errors.Trace(exeerrors.ErrPasswordNoMatch)
 	}
+	if s.RetainCurrentPassword {
+		if !isDualPasswordCapablePlugin(authplugin) {
+			return errors.Errorf("Dual password is not supported for users authenticating with plugin '%s'", authplugin)
+		}
+		if s.Password == "" {
+			return exeerrors.ErrCurrentPasswordCannotBeRetainedEmptyNew.GenWithStackByArgs(u, h)
+		}
+	}
 	if e.Ctx().InSandBoxMode() {
 		if !(s.User == nil || s.User.CurrentUser ||
 			e.Ctx().GetSessionVars().User.AuthUsername == u && e.Ctx().GetSessionVars().User.AuthHostname == strings.ToLower(h)) {
@@ -2599,7 +2745,17 @@ func (e *SimpleExec) executeSetPwd(ctx context.Context, s *ast.SetPwdStmt) error
 	}
 	// update mysql.user
 	sql := new(strings.Builder)
-	sqlescape.MustFormatSQL(sql, `UPDATE %n.%n SET authentication_string=%?,password_expired='N',password_last_changed=current_timestamp() WHERE User=%? AND Host=%?;`, mysql.SystemDB, mysql.UserTable, pwd, u, strings.ToLower(h))
+	if s.RetainCurrentPassword {
+		// If RETAIN CURRENT PASSWORD is specified, promote the current authentication_string
+		// to user_attributes.$.additional_password as part of this UPDATE.
+		attr, err := buildAdditionalPasswordJSON(ctx, sqlExecutor, u, h)
+		if err != nil {
+			return err
+		}
+		sqlescape.MustFormatSQL(sql, `UPDATE %n.%n SET authentication_string=%?,password_expired='N',password_last_changed=current_timestamp(),user_attributes=json_merge_patch(coalesce(user_attributes, '{}'), %?) WHERE User=%? AND Host=%?;`, mysql.SystemDB, mysql.UserTable, pwd, attr, u, strings.ToLower(h))
+	} else {
+		sqlescape.MustFormatSQL(sql, `UPDATE %n.%n SET authentication_string=%?,password_expired='N',password_last_changed=current_timestamp() WHERE User=%? AND Host=%?;`, mysql.SystemDB, mysql.UserTable, pwd, u, strings.ToLower(h))
+	}
 	_, err = sqlExecutor.ExecuteInternal(ctx, sql.String())
 	if err != nil {
 		return err

pkg/executor/test/passwordtest/BUILD.bazel

@@ -4,11 +4,12 @@ go_test(
     name = "passwordtest_test",
     timeout = "short",
     srcs = [
+        "dual_password_test.go",
         "main_test.go",
         "password_management_test.go",
     ],
     flaky = True,
-    shard_count = 9,
+    shard_count = 20,
     deps = [
         "//pkg/domain",
         "//pkg/errno",