HTTP2 Authentication

The HTTP protocol provides a method for servers to request a user name and password from a client before granting access to a page. The HTTP2 server supports this authentication mechanism, allowing developers to require valid credentials for access to some or all pages. 

Authentication functionality is supported by two user-provided callback functions. The first, HTTPNeedsAuth, determines if the requested page requires valid credentials to proceed. The second, HTTPCheckAuth, checks the user name and password against an accepted list and determines whether to grant or deny access. This split between two callback functions is necessitated by the nature of the HTTP protocol and the low-memory architecture of the HTTP2 server. In cases where different credentials or sets of credentials may be accepted for different pages, the two functions communicate with each other through a single byte stored in curHTTP.isAuthorized. 

When a request is first made, the function HTTPNeedsAuth is called to determine if that page needs password protection. This function returns a value to instruct the HTTP2 server how to proceed. The most significant bit indicates whether or not access is granted. That is, values 0x80 and higher allow access unconditionally, while values 0x79 and lower will require a user name and password at a later point. The value returned is stored as curHTTP.isAuthorized so that it can be accessed by future callback functions. 

The following example is the simplest case, in which all files require a password for access:

BYTE HTTPNeedsAuth(BYTE* cFile)
{
    return 0x00;
}

In some cases, only certain files will need to be protected. The second example requires a password for any file located in the /treasure folder:

BYTE HTTPNeedsAuth(BYTE* cFile)
{
    // Compare to "/treasure" folder.  Don't use strcmp here, because
    // cFile has additional path info such as "/treasure/gold.htm"
    if(!memcmppgm2ram((void*)cFile, (ROM void*)"treasure", 8))
        return 0x00;

    return 0x80;
}

More complex uses could require an administrative user to access the /admin folder, while any authenticated user can access the rest of the site. The third example requires a different set of user name and password combinations for the /admin folder versus the rest of the site:

#define HTTP_AUTH_ADMIN     (0x00)
#define HTTP_AUTH_OTHER     (0x01)

BYTE HTTPNeedsAuth(BYTE* cFile)
{
    // Return a specific code for admin users
    if(!memcmppgm2ram((void*)cFile, (ROM void*)"admin", 5))
        return HTTP_AUTH_ADMIN;

    return HTTP_AUTH_OTHER;
}

The HTTPCheckAuth function determines if the supplied user name and password are valid to access this resource. Again, the most significant bit indicates whether or not access is granted. The value returned is also stored as curHTTP.isAuthorized so that it can be accessed by future callback functions. 

The following example is the simplest case, in which one user/password pair is accepted for all pages:

BYTE HTTPCheckAuth(BYTE* cUser, BYTE* cPass)
{
    if(!strcmppgm2ram((char*)cUser, (ROM char*)"AliBaba") &&
       !strcmppgm2ram((char*)cPass, (ROM char*)"Open Sesame!") )
        return 0x80;

    return 0x00;
}

In some cases, you may have multiple users with various levels of access. The following example satisfies the needs used in the third example of HTTPNeedsAuth above:

BYTE HTTPCheckAuth(BYTE* cUser, BYTE* cPass)
{
    // Check for admin users first
    if(curHTTP.isAuthorized == HTTP_AUTH_ADMIN &&
       !strcmppgm2ram((char*)cUser, (ROM char*)"admin") &&
       !strcmppgm2ram((char*)cPass, (ROM char*)"s3cREt") )
        return 0x80;

    if(!strcmppgm2ram((char*)cUser, (ROM char*)"kate") &&
       !strcmppgm2ram((char*)cPass, (ROM char*)"puppies!") )
        return 0x80;

    return 0x00;
}

More complex uses are certainly feasible. Many applications may choose to store the user names and passwords in EEPROM or other non-volatile storage so that they may be updated by the end-user. Some applications may wish to return various values above 0x80 in HTTPCheckAuth so that later callback functions can determine which user logged in. The flexibility of these functions provides for many more possibilities that are not documented here but can be developed in just a few hours.