% Interface for prompting and passing passwords into MATLAB

% Copyright 2020 The MathWorks, Inc.

classdef (Abstract) PasswordProvider < handle
    
    methods (Abstract)
        % Set whether to prompt for passwords
        % PROMPTFORPASSWORD - Flag indicating whether to prompt for passwords
        setPromptForPassword(obj, promptForPassword);
        
        % PROMPTFORPASSWORD - Flag indicating whether to prompt for passwords
        % Return whether to prompt for passwords
        promptForPassword = getPromptForPassword(obj);
        
        % USERNAME = promptForIdentity(obj, SUGGESTEDUSERNAME, REQUIRESSYSTEMUSER);
        % Prompt for username
        % SUGGESTEDUSERNAME - username to initially populate any dialog
        % option with. User should be free to change from this.
        % REQUIRESSYSTEMUSER - Flag indicating username must be a system account
        % USERNAME - Actual username entered by user
        username = promptForIdentity(obj, suggestedUserName, requiresSystemUser);
        
        % promptForCurrentPassword(obj, USERNAME, ERRORCODE, ALLOWPASSWORDCACHE);
        % Prompt for password of an existing user.
        % This does not return the actual password, since the exact
        % implementation may render it insecure to return the actual
        % password. The password should be able to be retrieved using the
        % fetchEncryptedPassword or fetchHashedPassword methods. This is
        % true for all password prompt methods.
        % USERNAME - username of current user. Users may not change this.
        % ERRORCODE - AuthenticationErrorCode identifying reason
        % why password is required. Can be empty.
        % ALLOWPASSWORDCACHE - Flag indicating if client is allowed to
        % cache passwords. Restricts what REMEMBERPASSWORD values are
        % allowed.
        promptForCurrentPassword(obj, username, errorCode, allowPasswordCache);
        
        % promptForNewPassword(obj, USERNAME, ALLOWPASSWORDCACHE, REQUIRESSYSTEMUSER);
        % Prompt for password of a new user.
        % USERNAME - username of new user. Users may not change this.
        % ALLOWPASSWORDCACHE - Flag indicating if client is allowed to
        % cache passwords. Restricts what REMEMBERPASSWORD values are
        % allowed.
        % REQUIRESSYSTEMUSER - Flag indicating username must be a system account
        promptForNewPassword(obj, username, allowPasswordCache, requiresSystemUser);
        
        % promptForChangePassword(obj, USERNAME, ERRORCODE, ALLOWPASSWORDCACHE, REQUIRESSYSTEMUSER);
        % Prompt for user to change existing password.
        % The old password can be retrieved with fetchOldHashedPassword.
        % The new password can be retrieved with
        % fetchEncryptedPassword/fetchHashedPassword.
        % CURRENTUSER - username of current user.
        % USERNAME - username of password to change. Users may not change this.
        % ERRORCODE - AuthenticationErrorCode identifying reason
        % why password is required. Can be empty.
        % ALLOWPASSWORDCACHE - Flag indicating if client is allowed to
        % cache passwords. Restricts what REMEMBERPASSWORD values are
        % allowed.
        % REQUIRESSYSTEMUSER - Flag indicating username must be a system account
        promptForChangePassword(obj, currentUser, username, errorCode, allowPasswordCache, requiresSystemUser);
        
        % USERNAME = promptForTemporaryUserSwitch(obj, 
        % OWNER, SUGGESTEDUSER, ERRORCODE, ALLOWPASSWORDCACHE);
        % Prompt user for credentials of a different user.
        % OWNER - Owning username
        % SUGGESTEDUSER - Suggested username to enter credentials for.
        % This is likely the admin user. Users can change
        % this.
        % ERRORCODE - AuthenticationErrorCode identifying reason
        % why password is required. Can be empty.
        % ALLOWPASSWORDCACHE - Flag indicating if client is allowed to
        % cache passwords. Restricts what REMEMBERPASSWORD values are
        % allowed.
        % USERNAME - Actual username entered by user
        % REQUIRESSYSTEMUSER - Flag indicating username must be a system account
        username = promptForTemporaryUserSwitch(obj, owner, suggestedUser, errorCode, allowPasswordCache, requiresSystemUser);
        
        % promptForAdminPassword(obj, ADMINUSERNAME, ERRORCODE, ALLOWPASSWORDCACHE);
        % Prompt for password of admin user.
        % ADMINUSERNAME - username of admin user. Users may not change this.
        % ERRORCODE - AuthenticationErrorCode identifying reason
        % why password is required. Can be empty.
        % ALLOWPASSWORDCACHE - Flag indicating if client is allowed to
        % cache passwords. Restricts what REMEMBERPASSWORD values are
        % allowed.
        promptForAdminPassword(obj, adminUsername, errorCode, allowPasswordCache);
        
        % Issue a warning that the current user is modifying data owned by
        % a different user
        % CURRENTUSER - username of current user.
        % OWNER - Owning username
        issueNotOwnerWarning(obj, currentUser, owner);
        
        % Fetch an existing password matching the given username and return
        % the encrypted credential using the given encryptor
        % Returns byte array:
        % encryptedBytes = encryptor.encrypt(stringEncoder.encode(password))
        % If a password is not stored for the given username, return empty.
        encryptedBytes = fetchEncryptedPassword(obj, encryptor, stringEncoder, username);
        
        % Fetch an existing password matching the given username and return
        % the hashed credential using the given hasher
        % Returns byte array:
        % hashedBytes = hasher.digest(stringEncoder.encode(password))
        % If a password is not stored for the given username, return empty.
        [hashedBytes, rememberPassword] = fetchHashedPassword(obj, hasher, stringEncoder, username);
        
        % Fetch a password matching the given username entered as the currentUser
        % for promptForChangePassword and return the hashed credential using
        % the given hasher.
        % Returns byte array:
        % hashedBytes = hasher.digest(stringEncoder.encode(password))
        % If a password is not stored for the given username, return empty.
        hashedBytes = fetchHashedChangePassword(obj, hasher, stringEncoder, username);
        
        % Clear all entries. This should be 
        % called once the required password is extracted using either
        % fetchEncryptedPassword or fetchHashedPassword.
        clear(obj);
    end
end

