Access and Multi-User Interface

Functions to filter access to the FTP server and to work with user accounts. More...

Functions
bool	netFTPs_AcceptClient (const NET_ADDR *addr)
	Accept or deny connection from remote FTP client. [user-provided]. More...
uint8_t	netFTPs_CheckUsername (const char *username)
	Check if an user account exists in the user database. [user-provided]. More...
bool	netFTPs_CheckPassword (uint8_t user_id, const char *password)
	Check user account password in the user database. [user-provided]. More...
bool	netFTPs_FileAccess (uint8_t user_id, const char *fname, uint32_t access)
	Check if remote user is allowed to access a file on FTP server. [user-provided]. More...
uint8_t	netFTPs_GetUserId (void)
	Retrieve the user identification number. [thread-safe]. More...

Description

Functions to filter access to the FTP server and to work with user accounts.

To filter the access to the FTP server based on the IP address and port of the connecting client, the optional function netFTPs_AcceptClient is used. It is part of the template file FTP_Server_Access.c. If this template file is missing in the µVision project, the function will not be available and thus connections from all remote clients will be accepted. You need to adapt the function to the application's needs by specifying the rules for allowed/blocked clients. The FTP server will use the information in this function to filter the access.

The multi-user login allows you to create different profiles for different users or groups of users. The profiles define the access rights to different files on the FTP server. The users which are allowed to access the FTP server are stored in an user database.

If you want to use multi-user authentication, you need to check the Enable User Authentication in the configuration file (Net_Config_FTP_Server.h). The default account is a system administrator account, which has no restrictions. All other accounts are created in a separate FTP_Server_Multiuser.c module. To enable a list of users, you need to adapt the following functions that are included in this module:

• netFTPs_CheckUsername - checks if the user account exists for the provided credentials.
• netFTPs_CheckPassword - checks if the password fits to the user account for the provided credentials.
• netFTPs_FileAccess - check if the access to the file is allowed for a provided user.

The following function is included in the Network Component library rl_net.h:

• netFTPs_GetUserId - retrieves the user identification number for the user, which is trying to access the file or folder.

Note

• To add the template files to your project, simply right-click on the Source group, select Add New Item to Group, then click on User Code Template and scroll in the template files list until you find the required template.
• If the FTP_Server_Multiuser.c is not added to the project, but Authentication is enabled, the FTP server runs in single user authentication mode (refer to Control Interface).

Function Documentation

netFTPs_AcceptClient()

bool netFTPs_AcceptClient

(

const NET_ADDR *

addr

)

Accept or deny connection from remote FTP client. [user-provided].

Parameters

[in]

addr

structure containing IP address and port of remote FTP client.

Returns

• true = Connection from the remote client is allowed.
• false = Connection is denied.

The function netFTPs_AcceptClient checks if a connection from the remote client is allowed or not. This enables remote client filtering. You can selectively decide which clients are allowed to connect to the FTP server and which are not.

The argument addr points to a buffer containing IP address and port of the remote machine.

Note

This function is optional. If missing, the library default function is used which accepts all remote clients.

Code Example

The following example is available in the user code template file FTP_Server_Access.c. Customize it to the application's needs.

bool netFTPs_AcceptClient (const NET_ADDR *addr) {
  if (addr->addr_type == NET_ADDR_IP4) {
    // IPv4 client
    if (addr->addr[0] == 192  &&
        addr->addr[1] == 168  &&
        addr->addr[2] == 0    &&
        addr->addr[3] == 1) {
      // Accept connection from client at 192.168.0.1
      return (true);
    }
  }
  else {
    // IPv6 client
    const uint8_t ip6_addr[NET_ADDR_IP6_LEN] = { 
                     0xfe, 0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
                     0x1c, 0x30, 0x6c, 0xff, 0xfe, 0xa2, 0x45, 0x5e };
    if (memcmp (addr->addr, ip6_addr, NET_ADDR_IP6_LEN) == 0) {
      // Accept connection from client at [fe80::1c30:6cff:fea2:455e]
      return (true);
    }
  }
  // Deny connection.
  return (false);
}

netFTPs_CheckPassword()

bool netFTPs_CheckPassword	(	uint8_t	user_id,
		const char *	password
	)

Check user account password in the user database. [user-provided].

Parameters

[in]	user_id	user identification number.
[in]	password	pointer to password.

Returns

• true = password accepted.
• false = invalid password.

The function netFTPs_CheckPassword authenticates the password for a specified user ID.

The argument user_id is the identification number of a user.

The argument password points to the password that gets checked.

Code Example

The following example is available in the user code template file FTP_Server_Multiuser.c. Customize it to the application's needs.

bool netFTPs_CheckPassword (uint8_t user_id, const char *password) {
  if (user_id == 1) {
    if (strcmp (password, "guest") == 0) {
      // Password is correct
      return (true);
    }
  }
  return (false);
}

netFTPs_CheckUsername()

uint8_t netFTPs_CheckUsername

(

const char *

username

)

Check if an user account exists in the user database. [user-provided].

Parameters

[in]

username

pointer to username.

Returns

status information:

• User identification number.
• 0 if the user is not existing.

The function netFTPs_CheckUsername authenticates the username and returns the corresponding identification number. A value of 0 is returned if the user does not exist.

The argument username points to the user name.

Code Example

The following example is available in the user code template file FTP_Server_Multiuser.c. Customize it to the application's needs.

uint8_t netFTPs_CheckUsername (const char *username) {
  if (strcmp (username, "guest") == 0) {
    // Username is correct, return user_id
    return (1);
  }
  return (0);
}

netFTPs_FileAccess()

bool netFTPs_FileAccess	(	uint8_t	user_id,
		const char *	fname,
		uint32_t	access
	)

Check if remote user is allowed to access a file on FTP server. [user-provided].

Parameters

[in]	user_id	user identification number.
[in]	fname	full path of a file to access.
[in]	access	access mode as defined with Network Access definitions.

Returns

• true = File access is allowed.
• false = File access is denied.

The function netFTPs_FileAccess checks if file access is allowed for a specific user. This allows access protection of sensitive files. The access to protected files will be blocked for unprivileged users. The error code "550 Access is denied" will be returned to the client if access is not allowed.

The argument user_id is the user identification number as returned by netFTPs_CheckUsername. user_id identifies the user who is trying to access the specified file.

The argument fname points to a buffer containing the file name with path which should be accessed. The file name is a null-terminated string.

The argument access specifies the requested type of file access:

• NET_ACCESS_FILE_READ - File Read is allowed.
• NET_ACCESS_FILE_WRITE - File Write is allowed.
• NET_ACCESS_DIRECTORY_CREATE -Directory Create is allowed.
• NET_ACCESS_DIRECTORY_REMOVE - Directory Remove is allowed.
• NET_ACCESS_DIRECTORY_LIST - Directory List is allowed.

Note

This function is optional. If the FTP file access restriction is not used, this function is not required.

Code Example

The following example is available in the user code template file FTP_Server_Multiuser.c. Customize it to the application's needs.

bool netFTPs_FileAccess (uint8_t user_id, const char *fname, uint32_t access) {
  if (user_id == 1) {
    if ((strcmp (fname, "/log/test.txt") == 0) && (access == NET_ACCESS_FILE_WRITE)) {
      // User "guest" is not allowed to modify or delete "test.txt" in "log" folder
      return (false);
    }
  }
  return (true);
}

netFTPs_GetUserId()

uint8_t netFTPs_GetUserId

(

void

)

Retrieve the user identification number. [thread-safe].

Returns

user identification number (0 = system administrator).

The function netFTPs_GetUserId retrieves the user identification number.

Note

This function returns a value of 0 for system administrator account.

Code Example

uint32_t log_count1;
 
void netFTPs_Notify (netFTPs_Event event) {
  if ((event == netFTPs_EventLogin) && (netFTPs_GetUserId() == 1)) {
    // Count user 1 logins
    log_count1++;
  }
}