Access and Multi-User Interface

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

Functions
bool	netHTTPs_AcceptClient (const NET_ADDR *addr)
	Accept or deny a connection from a remote HTTP client. [user-provided]. More...
uint8_t	netHTTPs_CheckAccount (const char *username, const char *password)
	Check if an user account exist in the user database. [user-provided]. More...
void	netHTTPs_GetUserSecret (uint8_t user_id, char *buf, uint32_t buf_len)
	Retrieve the secret word for the selected user. [user-provided]. More...
bool	netHTTPs_FileAccess (uint8_t user_id, const char *fname)
	Check if remote user is allowed to access a file on HTTP server. [user-provided]. More...
netStatus	netHTTPs_CalcHashHA1 (const char *username, const char *password, char *buf, uint32_t buf_len)
	Calculate HA1 hash value for the given credentials. [thread-safe]. More...
uint8_t	netHTTPs_GetUserId (void)
	Retrieve the user identification. [thread-safe]. More...

Description

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

To filter the access to the HTTP server based on the IP address and port of the connecting client, the optional function netHTTPs_AcceptClient is used. It is part of the template file HTTP_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 HTTP 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 HTTP server. The users which are allowed to access the HTTP 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_HTTP_Server.h). The default account is a system administrator account, which has no restrictions. All other accounts are created in a separate HTTP_Server_Multiuser.c module. To enable a list of users, you need to adapt the following functions that are included in this module:

• netHTTPs_CheckAccount - checks if the user account exists for the provided credentials.
• netHTTPs_FileAccess - check if the access to the file is allowed for a provided user.
• netHTTPs_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 HTTP_Server_Multiuser.c is not added to the project, but Authentication is enabled, the web server runs in single user authentication mode.

Function Documentation

netHTTPs_AcceptClient()

bool netHTTPs_AcceptClient

(

const NET_ADDR *

addr

)

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

Parameters

[in]

addr

structure containing IP address and port of remote HTTP client.

Returns

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

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

The argument addr points to a buffer containing the 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 HTTP_Server_Access.c. Customize it to the application's needs.

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

netHTTPs_CalcHashHA1()

netStatus netHTTPs_CalcHashHA1	(	const char *	username,
		const char *	password,
		char *	buf,
		uint32_t	buf_len
	)

Calculate HA1 hash value for the given credentials. [thread-safe].

Parameters

[in]	username	username, a null-terminated string.
[in]	password	password, a null-terminated string.
[out]	buf	buffer to store the hash value to.
[in]	buf_len	length of buffer.

Returns

status code that indicates the execution status of the function.

The function netHTTPs_CalcHashHA1 calculates the MD5 hash value HA1, which is representend as a hexadecimal string. You can call the function if Digest authentication is used. Saving a password as HA1 hash adds additional security to the application.

The argument username points to the user name, which is a null-terminated string.

The argument password points to the password, which is a null-terminated string.

The argument buf points to a buffer that will be used to store the value of HA1 hash.

The argument buf_len specifies the length of the buffer buf, which must be at least 33 bytes because the function also adds a null-termination to the HA1 hash string.

The HA1 hash is calculated as:

HA1 = MD5(username:realm:password)

The value for realm is from the Net_Config_HTTP_Server.h.

Possible netStatus return values:

• netOK: HA1 hash calculated successfully.
• netInvalidParameter: Invalid parameter provided.
• netError: Digest authentication not enabled in the configuration.

Code Example

char buf[33];
 
if (netHTTPs_LoginActive() == true) {
  netHTTPs_SetUsername ("sysadmin");
  netHTTPs_CalcHashHA1 ("sysadmin", "a$Min#77", buf, sizeof(buf));
  netHTTPs_SetPassword (buf);
}

netHTTPs_CheckAccount()

uint8_t netHTTPs_CheckAccount	(	const char *	username,
		const char *	password
	)

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

Parameters

[in]	username	pointer to username.
[in]	password	pointer to password.

Returns

status information:

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

The function netHTTPs_CheckAccount checks if an user account exist in the user database for the provided credentials. It is called from the Network Component's HTTP server to check if the user with provided credentials is allowed to access the web pages or not.

The argument username points to a null-terminated string representing the user name that was typed in from the browser.

The argument password points to a null-terminated string representing the password. If the authentication type is Digest, the password is an empty string.

Note

This function is optional. For single user HTTP authentication or when the HTTP authentication is disabled, this function is not required.

Code Example

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

uint8_t netHTTPs_CheckAccount (const char *username, const char *password) {
 
  if ((strcmp (username, "guest") == 0) && (strcmp (password, "guest") == 0)) {
    // Accept guest account
    return (1);
  }
  return (0);
}

netHTTPs_FileAccess()

bool netHTTPs_FileAccess	(	uint8_t	user_id,
		const char *	fname
	)

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

Parameters

[in]	user_id	user identification number.
[in]	fname	name of a file to access.

Returns

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

The function netHTTPs_FileAccess checks if a file access is allowed for a specified user. This enables access protection of sensitive web pages. Protected web pages will not be displayed for unprivileged users. Instead, the Web server shows "Error Page 403 - Forbidden".

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

The argument fname points to a buffer containing the file name of a file, which the user is trying to access. The file name is a null-terminated string.

Note

This function is optional. If the HTTP resource access restriction is not used, this function is not required.

Code Example

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

bool netHTTPs_FileAccess (uint8_t user_id, const char *fname) {
 
  if (user_id == 1) {
    if (strcmp (fname, "system.cgi") == 0) {
      // User "guest" is not allowed to see "system.cgi"
      return (false);
    }
  }
  return (true);
}

netHTTPs_GetUserId()

uint8_t netHTTPs_GetUserId

(

void

)

Retrieve the user identification. [thread-safe].

Returns

user identification number (0 = system administrator).

The function netHTTPs_GetUserId retrieves the user identification number when the web pages are protected with user authentication. It can be used to generate a web page, whose content is based on the connected user. This function is normally called from the netCGI_Script function.

netHTTPs_GetUserId is a system function that is in the Network Component library.

Note

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

Code Example

uint16_t netCGI_Script (const char *env, char *buf, uint16_t buf_len, uint32_t *pcgi) {
  uint8_t uid;
  ..
    case 'd':
      // System password - file 'system.cgi' 
      switch (env[2]) {
        case '0':
          // Display the user name on web page. 
          uid = netHTTPs_GetUserId ();
          len = sprintf((char *)buf,(const char *)&env[4],
                        (uid == 0) ? "admin" : users[uid-1]);
          break;
        case '1':
           ..
          break;
      }
      break;
   ..
}  

netHTTPs_GetUserSecret()

void netHTTPs_GetUserSecret	(	uint8_t	user_id,
		char *	buf,
		uint32_t	buf_len
	)

Retrieve the secret word for the selected user. [user-provided].

Parameters

[in]	user_id	user identification number.
[out]	buf	buffer to store the secret word to.
[in]	buf_len	length of buffer.

Returns

none.

The function netHTTPs_GetUserSecret retrieves the user secret word from the user database for the provided user. It is called from the HTTP server of the Network Component if Digest authentication is used.

The argument user_id is the identification number of a user.

The argument buf points to a buffer that will be used to store the value of the secret word.

The argument buf_len specifies the length of the buffer buf which is 33 bytes.

The UserSecret is either a plain text password or a MD5 hash value HA1. The length of the string that is returned is used by the Network library to determine the type. The HA1 value should be 32 bytes, lowercase hexadecimal. If the length is less than 32 bytes, the Network library treats the string as plain text password.

The HA1 hash is calculated as:

HA1 = MD5(username:realm:password)

For username "guest", realm "Embedded WEB Server" and password "guest" the HA1 is:

MD5("guest:Embedded WEB Server:guest") = "bd553df9efecf3af93c88843b0f54496"

Note

This function is optional. For Basic HTTP authentication or when the HTTP authentication is disabled, this function is not required.

Code Example clear-text

void netHTTPs_GetUserSecret (uint8_t user_id, char *buf, uint32_t buf_len) {
  if (user_id == 1) {
    /* Plain text password */
    strcpy (buf, "guest");
  }
}

Code Example hash-value

void netHTTPs_GetUserSecret (uint8_t user_id, char *buf, uint32_t buf_len) {
  if (user_id == 1) {
    /* Digest HA1 hash value */
    strcpy (buf, "bd553df9efecf3af93c88843b0f54496");
  }
}