Package org.bluezoo.gumdrop.ftp.file

Class RoleBasedFTPHandler

java.lang.Object
org.bluezoo.gumdrop.ftp.file.RoleBasedFTPHandler
All Implemented Interfaces:
FTPConnectionHandler
public class RoleBasedFTPHandler extends Object implements FTPConnectionHandler
FTP connection handler with role-based access control.

This handler uses a Realm to authenticate users and check role membership for authorization decisions. Users are granted permissions based on their membership in standard FTP roles.

Role Hierarchy

  • ftp-admin - Full access to all operations
  • ftp-delete - Can delete, rename (implies ftp-write)
  • ftp-write - Can upload, create directories (implies ftp-read)
  • ftp-read - Read-only access

Configuration Example


 <realm id="ftpRealm" class="org.bluezoo.gumdrop.BasicRealm">
   <property name="href">ftp-users.xml</property>
 </realm>
 
 <service class="org.bluezoo.gumdrop.ftp.file.RoleBasedFTPService">
   <property name="realm" ref="#ftpRealm"/>
   <property name="root-directory">/var/ftp</property>
   <listener class="org.bluezoo.gumdrop.ftp.FTPListener" port="21"/>
 </service>
Author:
Chris Burdess
See Also:

  • Constructor Details

    • RoleBasedFTPHandler

      public RoleBasedFTPHandler(Realm realm, FTPFileSystem fileSystem)
      Creates a new role-based FTP handler.
      Parameters:
      realm - the realm for authentication and role checking
      fileSystem - the file system to use for file operations

  • Method Details

    • setWelcomeMessage

      public void setWelcomeMessage(String welcomeMessage)
      Sets a custom welcome message.
      Parameters:
      welcomeMessage - the welcome message to display on connection

    • setQuotaManager

      public void setQuotaManager(QuotaManager quotaManager)
      Sets the quota manager for quota enforcement.
      Parameters:
      quotaManager - the quota manager

    • getQuotaManager

      public QuotaManager getQuotaManager()
      Description copied from interface: FTPConnectionHandler
      Gets the quota manager for this handler, if quota enforcement is enabled.

      When a quota manager is provided, the FTP connection will check quotas before allowing STOR and APPE commands, and will update usage after successful uploads and deletes.

      Specified by:
      getQuotaManager in interface FTPConnectionHandler
      Returns:
      the quota manager, or null if quota enforcement is disabled
      See Also:

    • connected

      public String connected(FTPConnectionMetadata metadata)
      Description copied from interface: FTPConnectionHandler
      Notifies that a new client connection has been established.

      This is called immediately after the TCP connection is accepted and any SSL/TLS handshake is completed. It provides an opportunity to perform early connection-level filtering, logging, or initialization.

      The handler can send a custom welcome banner by returning a string, or return null to use the default welcome message.

      Specified by:
      connected in interface FTPConnectionHandler
      Parameters:
      metadata - connection metadata with client and security information
      Returns:
      custom welcome banner, or null for default

    • authenticate

      public FTPAuthenticationResult authenticate(String username, String password, String account, FTPConnectionMetadata metadata)
      Description copied from interface: FTPConnectionHandler
      Handles FTP authentication (USER/PASS/ACCT command sequence).

      This method is called to authenticate a user with the provided credentials. The implementation should validate the user against whatever authentication backend is appropriate (database, LDAP, etc.).

      Authentication considerations:

      • Anonymous FTP (user="anonymous" or "ftp")
      • Standard username/password authentication
      • Account information for systems that require it
      • Rate limiting for failed attempts
      • Account status checking (enabled, expired, etc.)
      Specified by:
      authenticate in interface FTPConnectionHandler
      Parameters:
      username - the username from USER command
      password - the password from PASS command (can be null if not provided yet)
      account - the account from ACCT command (can be null if not provided)
      metadata - complete connection context
      Returns:
      authentication result indicating success, failure, or need for more information

    • getFileSystem

      public FTPFileSystem getFileSystem(FTPConnectionMetadata metadata)
      Description copied from interface: FTPConnectionHandler
      Provides the file system implementation for this connection.

      This method is called after successful authentication to get the file system that should be used for this user's session. Different users may get different file system implementations with different access rights, root directories, etc.

      Examples:

      • Anonymous users get read-only access to public directory
      • Regular users get access to their home directory
      • Admin users get full file system access
      • Virtual users get database-backed file systems
      Specified by:
      getFileSystem in interface FTPConnectionHandler
      Parameters:
      metadata - connection context including authenticated user
      Returns:
      file system implementation for this user

    • isAuthorized

      public boolean isAuthorized(FTPOperation operation, String path, FTPConnectionMetadata metadata)
      Description copied from interface: FTPConnectionHandler
      Checks if the authenticated user is authorized to perform an operation.

      This method is called before executing any file or directory operation to verify that the user has the required permissions. The default implementation allows all operations for backward compatibility.

      Implementations can use this for:

      • Role-based access control using FTPRoles
      • Path-based access control (restrict access to certain directories)
      • Time-based restrictions (maintenance windows)
      • Quota enforcement

      Example role-based implementation: 

      
 public boolean isAuthorized(FTPOperation operation, String path,
                            FTPConnectionMetadata metadata) {
     String user = metadata.getAuthenticatedUser();
     
     // Admins can do anything
     if (realm.isUserInRole(user, FTPRoles.ADMIN)) {
         return true;
     }
     
     switch (operation) {
         case READ:
         case NAVIGATE:
             return realm.isUserInRole(user, FTPRoles.READ);
         case WRITE:
         case CREATE_DIR:
             return realm.isUserInRole(user, FTPRoles.WRITE);
         case DELETE:
         case DELETE_DIR:
         case RENAME:
             return realm.isUserInRole(user, FTPRoles.DELETE);
         default:
             return false;
     }
 }
      Specified by:
      isAuthorized in interface FTPConnectionHandler
      Parameters:
      operation - the type of operation being attempted
      path - the file or directory path (may be null for general queries)
      metadata - connection context including authenticated user
      Returns:
      true if the operation is allowed, false to deny with 550 response
      See Also:

    • transferStarting

      public void transferStarting(String path, boolean upload, long size, FTPConnectionMetadata metadata)
      Description copied from interface: FTPConnectionHandler
      Called when a data transfer (upload/download) is starting.

      This provides an opportunity to set up logging, progress tracking, virus scanning, or other transfer-related processing.

      Specified by:
      transferStarting in interface FTPConnectionHandler
      Parameters:
      path - the file path being transferred
      upload - true for upload (STOR), false for download (RETR)
      size - expected transfer size in bytes (-1 if unknown)
      metadata - connection context

    • transferProgress

      public void transferProgress(String path, boolean upload, ByteBuffer data, long totalBytesTransferred, FTPConnectionMetadata metadata)
      Description copied from interface: FTPConnectionHandler
      Called during data transfer to provide transfer progress updates.

      This method is called periodically during file transfers with chunks of data. It can be used for:

      • Progress tracking and reporting
      • Real-time virus scanning
      • Content filtering
      • Transfer rate limiting
      • Custom logging

      The handler should process the data quickly to avoid slowing down the transfer.

      Specified by:
      transferProgress in interface FTPConnectionHandler
      Parameters:
      path - the file path being transferred
      upload - true for upload, false for download
      data - the data chunk being transferred
      totalBytesTransferred - total bytes transferred so far
      metadata - connection context

    • transferCompleted

      public void transferCompleted(String path, boolean upload, long totalBytesTransferred, boolean success, FTPConnectionMetadata metadata)
      Description copied from interface: FTPConnectionHandler
      Called when a data transfer has completed.

      This provides an opportunity for cleanup, final processing, statistics recording, etc.

      Specified by:
      transferCompleted in interface FTPConnectionHandler
      Parameters:
      path - the file path that was transferred
      upload - true for upload, false for download
      totalBytesTransferred - total bytes successfully transferred
      success - true if transfer completed successfully, false if aborted/failed
      metadata - connection context

    • handleSiteCommand

      public FTPFileOperationResult handleSiteCommand(String command, FTPConnectionMetadata metadata)
      Description copied from interface: FTPConnectionHandler
      Handles SITE-specific commands.

      The SITE command allows servers to implement custom, non-standard commands. This method receives the SITE command arguments and can implement whatever custom functionality is needed.

      Examples:

      • SITE CHMOD - change file permissions
      • SITE DISK - show disk usage
      • SITE HELP - show custom help
      Specified by:
      handleSiteCommand in interface FTPConnectionHandler
      Parameters:
      command - the SITE command and arguments
      metadata - connection context
      Returns:
      operation result, or NOT_SUPPORTED if command is not recognized

    • disconnected

      public void disconnected(FTPConnectionMetadata metadata)
      Description copied from interface: FTPConnectionHandler
      Notifies that the client connection has been closed.

      This is called when the client disconnects (gracefully with QUIT or abruptly due to network issues). The handler should perform final cleanup and resource management.

      Cleanup actions might include:

      • Closing files or streams
      • Updating connection statistics
      • Logging connection summary
      • Releasing any held resources
      Specified by:
      disconnected in interface FTPConnectionHandler
      Parameters:
      metadata - final connection context with duration and statistics