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

Functions
bool	netTELNETs_AcceptClient (const NET_ADDR *addr)
	Accept or deny a connection from a remote Telnet client. [user-provided]. More...

uint8_t	netTELNETs_CheckUsername (const char *username)
	Check if an user account exist in the user database. [user-provided]. More...

bool	netTELNETs_CheckPassword (uint8_t user_id, const char *password)
	Check user account password in the user database. [user-provided]. More...

uint8_t	netTELNETs_GetUserId (void)
	Retrieve the user identification number. [thread-safe]. More...

Description

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

To filter the access to the Telnet server based on the IP address and port of the connecting client, the optional function netTELNETs_AcceptClient is used. It is part of the template file Telnet_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 Telnet 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 commands executed on the Telnet server. The users which are allowed to access the Telnet 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_Telnet_Server.h). The default account is a system administrator account, which has no restrictions. All other accounts are created in a separate Telnet_Server_Multiuser.c module.

To enable a list of users, you need to adapt the function netTELNETs_CheckUsername, which checks if the user account exists for the provided credentials, and the function netTELNETs_CheckPassword, which checks if the password fits to the user account for the provided credentials.

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

netTELNETs_GetUserId - retrieves the user identification number for the user, which is trying to execute a command.

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 Telnet_Server_Multiuser.c is not added to the project, but authentication is enabled, the Telnet server runs in single user authentication mode.

Function Documentation

◆ netTELNETs_AcceptClient()

bool netTELNETs_AcceptClient ( const NET_ADDR * addr )

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

Parameters

[in] addr structure containing IP address and port of remote Telnet client.

Returns

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

The function netTELNETs_AcceptClient checks if a connection from the remote client is allowed. This allows remote client filtering. You can selectively decide which clients are allowed to connect to the Telnet server.

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

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 Telnet_Server_Access.c. Customize it to the application's needs.

bool netTELNETs_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);
}

◆ netTELNETs_CheckPassword()

bool netTELNETs_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 netTELNETs_CheckPassword authenticates the password for a specified user ID on the server.

The argument user_id is the identification number of a user.

The argument password points to a null-terminated string representing the password that gets checked.

Note: This function is optional and only needed for multi-user authentication.

Code Example

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

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

◆ netTELNETs_CheckUsername()

uint8_t netTELNETs_CheckUsername ( const char * username )

Check if an user account exist 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 netTELNETs_CheckUsername authenticates the user name and returns the user identification number. A value of 0 is returned if the user does not exist.

The argument username points to a null-terminated string representing the user name that must be checked.

Note: This function is optional and only needed for multi-user authentication.

Code Example

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

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

◆ netTELNETs_GetUserId()

uint8_t netTELNETs_GetUserId ( void )

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

Returns: user identification number (0 = system administrator).

The function netTELNETs_GetUserId retrieves the user identification number when the Telnet console is protected with user authentication. It can be used to disable certain commands for unprivileged users.

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

Code Example

uint32_t netTELNETs_ProcessCommand (const char *cmd, char *buf, uint32_t buf_len, uint32_t *pvar) {
  uint32_t len = 0;
  ..
  if (netTELNETs_CheckCommand (cmd, "PASSW") == true) { 
    // Change the system password
    if (netTELNETs_GetUserId () == 0) && (strlen (cmd) >= 7)) {
      // Only administrator can change the password
      netTELNETs_SetPassword (&cmd[7]);
      len = sprintf (buf,"Password changed");
      return (len);
    }
  }
  ..
}