The AuthenticateClient method is used to authenticate a specific
client session, typically in response to an OnAuthenticate event
that indicates a client has requested authentication. This method is
also used internally to automatically grant the appropriate
access rights to local user and anonymous client sessions.
It is recommended that most applications specify FTP_ACCESS_DEFAULT
as the dwUserAccess value for a client session, since this allows the server
automatically grant the appropriate access based on the server
configuration options for normal and anonymous users. If the server is
going to be publicly accessible or third-party FTP clients will be
used to access the server, you should always grant the
FTP_ACCESS_LIST permission to clients. Many client applications
will not function correctly if they are unable to obtain a list of
files in the user's home directory.
If FTP_ACCESS_RESTRICTED is specified and the server
was started in multi-user mode, the client session will be effectively
locked to its home directory and cannot navigate to the server root
directory. By default, restricted client sessions are also limited to
only downloading files and requesting directory listings. If a client
session is not restricted, the client can access files outside of its
home directory. Regardless of this option, a client cannot access
files outside of the server root directory.
If FTP_ACCESS_RESTRICTED or FTP_ACCESS_ANONYMOUS is specified, the
client session will be authenticated in a restricted mode and the
access rights for the session will persist until the client
disconnects from the server. Unlike regular users, the access rights
for a restricted client cannot be changed by the server at a later
point. This restriction is designed to prevent the inadvertent
granting of rights to an untrusted client that could compromise the
security of the server.
If the lpszDirectory parameter is NULL or an empty string and
the server has been started in multi-user mode, each user is assigned
their own home directory based on their username. If the server has
not been started in multi-user mode, then the default home directory
will be the server root directory and is shared by all users. The
GetClientHomeDirectory method will return the full path to
the home directory for an authenticated client.
If the FTP_ACCESS_EXECUTE permission is granted to the client
session, it can execute external programs using the SITE EXEC command.
Because the program is executed in the context of the server process,
it is recommended that you limit access to this functionality and ensure
that the programs being executed do not introduce any security risks
to the operating system. This permission is never granted by default,
and the SITE EXEC command will return an error if the client session is
anonymous, regardless of whether this permission is granted or not.
This method is should only be used for custom authentication
schemes and is not necessary if you have used the AddVirtualUser
method to create virtual users.