lucinda/security

Encapsulates web security operations on top of OWASP guidelines

Web Security API

• About
• Configuration
• Binding Points
• Execution
• Installation
• Unit Tests
• Examples
• Reference Guide

About

This API is a skeleton (requires binding by developers) that implements common concerns of web security (authentication, authorization, state persistence, csrf prevention) based on OWASP guidelines, offering multiple binding points where developers MUST plugin components using its prototypes in order to complete the process (eg: DB authentication)., _(*1)

, _(*2)

It does so using this series of steps:, _(*3)

• configuration: setting up an XML file where web security is configured
• binding points: binding user-defined components defined in XML/code to API prototypes
• execution: creating a Wrapper instance to authenticate & authorize then use it to get logged in user id, access token (for stateless apps) or csrf token (for form logins)

API is fully PSR-4 compliant, only requiring PHP 8.1+ interpreter and SimpleXML + OpenSSL extensions. To quickly see how it works, check:, _(*4)

• installation: describes how to install API on your computer, in light of steps above
• unit tests: API has 100% Unit Test coverage, using UnitTest API instead of PHPUnit for greater flexibility
• example: shows a deep example of API functionality based on unit test for Wrapper

All classes inside belong to Lucinda\WebSecurity namespace!, _(*5)

Configuration

To configure this API you must have a XML with following tags inside:, _(*6)

• security: (mandatory) configures the api
• users: (optional) required only if authentication is by XML (access control list)
• routes: (optional) required only if authorization is by XML (access control list)

Security

Maximal syntax of this tag is:, _(*7)

<security>
    <csrf secret="..." expiration="..."/>
    <persistence>
        <session parameter_name="..." expiration="..." is_http_only="..." is_https_only="..." ignore_ip="..." handler="..."/>
        <remember_me secret="..." parameter_name="..."  expiration="..." is_http_only="..." is_https_only="..."/>
        <synchronizer_token secret="..." expiration="..." regeneration="..."/>
        <json_web_token secret="..." expiration="..." regeneration="..."/>
    </persistence>
    <authentication>
        <form dao="..." throttler="...">
            <login page="..." target="..." parameter_username="..." parameter_password="..."  parameter_rememberMe="..." />
            <logout page="..." target="..."/>
        </form>
        <oauth2 dao="..." target="..." login="..." logout="..."/>
    </authentication>
    <authorization>
        <by_dao page_dao="..." user_dao="..." logged_in_callback="..." logged_out_callback="..."/>
        <by_route logged_in_callback="..." logged_out_callback="..."/>
    </authorization>
</security>

Where:, _(*8)

• security: (mandatory) holds global web security policies.
  • csrf: (mandatory) holds settings necessary to produce an anti-CSRF token (useful to sign authentication with)
    • secret: (mandatory) password to use in encrypting csrf token (use: Token\SaltGenerator)
    • expiration: (optional) seconds until token expires. If not set, token will expire in 10 minutes.
  • persistence (mandatory) holds one or more mechanisms useful to preserve logged in state across requests (at least one is mandatory!)
    • session: (optional) configures persistence of logged in state by HTTP session
      • parameter_name: (optional) name of $_SESSION parameter that will store logged in state. If not set, "uid" is assumed.
      • expiration: (optional) seconds until session expires. If not set, session will expire as server-default.
      • is_http_only: (optional) whether or not to set session cookie as HttpOnly (can be 0 or 1; 0 is default).
      • is_https_only: (optional) whether or not to set session cookie as HTTPS only (can be 0 or 1; 0 is default).
      • handler: (optional) name of class (incl. namespace or relative path) implementing SessionHandlerInterface to which session handling will be delegated to.
    • remember_me: (optional) configures persistence of logged in state by HTTP remember me cookie
      • secret: (mandatory) password to use in encrypting cookie (use: Token\SaltGenerator)
      • parameter_name: (optional) name of $_COOKIE parameter that will store logged in state. If not set, "uid" is assumed.
      • expiration: (optional) seconds until cookie expires. If not set, cookie will expire in one day.
      • is_http_only: (optional) whether or not to set cookie as HttpOnly (can be 0 or 1; 0 is default).
      • is_https_only: (optional) whether or not to set cookie as HTTPS only (can be 0 or 1; 0 is default).
    • synchronizer_token: (optional) configures persistence of logged in state by signing every request with a synchronizer token
      • secret: (mandatory) password to use in encrypting token (use: Token\SaltGenerator)
      • expiration: (optional) seconds until token expires. If not set, token will expire in 1 hour.
      • regeneration: (optional) seconds from the moment token was created until it needs to regenerate on continuous usage. If not set, token will be regenerated in 1 minute.
    • json_web_token: (optional) configures persistence of logged in state by signing every request with a json web token
      • secret: (mandatory) password to use in encrypting token (use: Token\SaltGenerator)
      • expiration: (optional) seconds until token expires. If not set, token will expire in 1 hour.
      • regeneration: (optional) seconds from the moment token was created until it needs to regenerate on continuous usage. If not set, token will be regenerated in 1 minute.
  • authentication: (mandatory) holds one or more mechanisms to authenticate (at least one is mandatory!)
    • form: (optional) configures authentication via form. If no dao attribute is set, authentication is done via XML and users tag is required!
      • dao: (optional) name of PSR-4 autoload-compliant class (incl. namespace) implementing Authentication\DAO\UserAuthenticationDAO that performs form authentication in database. 1
      • throttler: (optional) name of PSR-4 autoload-compliant class (incl. namespace) extending Authentication\Form\LoginThrottler that performs login throttling prevention
      • login: (optional) configures login
        • page: (optional) page that performs login operation (all requests to this page will pass through this filter), also one to redirect back if login is unsuccessful. If none, then "login" is implicitly used.
        • target: (optional) destination page after successful login. If none, then "index" is implicitly used.
        • parameter_username: (optional) name of $_POST parameter username will be submitted as. If none, then "username" is implicitly used.
        • parameter_password: (optional) name of $_POST parameter password will be submitted as. If none, then "password" is implicitly used.
        • parameter_rememberMe: (optional) name of $_POST parameter that activates "remember me" option (value can be 0 or 1). If none, then "remember_me" is implicitly used.
      • logout: (optional) configures logout
        • page: (optional) page that performs logout operation (all requests to this page will pass through this filter). If none, then "logout" is implicitly used.
        • target: (optional) destination page after successful or unsuccessful logout. If none, then "login" is implicitly used.
    • oauth2: (optional) configures authentication via oauth2 provider
      • dao: (mandatory) name of PSR-4 autoload-compliant class (incl. namespace) implementing Authentication\OAuth2\VendorAuthenticationDAO that saves results of authentication in database
      • target: (optional) destination page after successful login. If none, then "index" is implicitly used.
      • login: (optional) generic page where login by provider option is available. If none, then "login" is implicitly used.
      • logout: (optional) page that performs logout operation. If none, then "logout" is implicitly used.
  • authorization: (mandatory) holds a single mechanism to authorize requests (at least one is mandatory!)
    • by_dao: (optional) configures authorization by database
      • page_dao: (mandatory) name of PSR-4 autoload-compliant class (incl. namespace) extending Authorization\DAO\PageAuthorizationDAO that checks user rights in database
      • user_dao: (mandatory) name of PSR-4 autoload-compliant class (incl. namespace) extending Authorization\DAO\UserAuthorizationDAO that checks page rights in database
      • logged_in_callback: (optional) callback page for authenticated users when authorization fails. If none, then "index" is implicitly used.
      • logged_out_callback: (optional) callback page for guest users when authorization fails. If none, then "login" is implicitly used.
    • by_route: (optional) configures authorization by XML, in which case routes tag is required. 1
      • logged_in_callback: (optional) callback page for authenticated users when authorization fails. If none, then "index" is implicitly used.
      • logged_out_callback: (optional) callback page for guest users when authorization fails. If none, then "login" is implicitly used.

For examples of XMLs, check WrapperTest @ unit tests!, _(*9)

Notes: (1) If authorization is by_route, authentication is form with a dao attribute, then class referenced there must also implement Authorization\UserRoles!, _(*10)

Users

This tag is required if XML authentication (form tag is present and has no dao attribute) + authorization (by_route tag is present) are used. Syntax is:, _(*11)

<users roles="...">
    <user id="..." username="..." password="..." roles="..."/>
    ...
</security>

Where:, _(*12)

• users: (mandatory) holds list of site users, each identified by a user tag
  • roles: (mandatory) holds list of roles guests (non-logged in users) belong to, separated by commas
  • user: (mandatory) holds information about a single user
    • id: (mandatory) holds unique user identifier (eg: 1)
    • username: (optional) holds user's username (eg: john_doe). Mandatory for XML authentication!
    • password: (optional) holds user's password hashed using password_hash (eg: value of php password_hash("doe", PASSWORD_BCRYPT)). Mandatory for XML authentication!
    • roles: (optional) holds list of roles user belongs to, separated by commas (eg: USERS, ADMINISTRATORS). Mandatory for XML authentication+authorization

If no user is detected in list above, GUEST role is automatically assumed!, _(*13)

Routes

This tag is required if XML authorization (by_route tag is present) is used. Syntax is:, _(*14)

<routes roles="...">
    <route id="..." roles="..."/>
    ...
</routes>

Where:, _(*15)

• routes: (mandatory) holds list of site routes, each identified by a route tag
  • roles: (mandatory) holds list of roles all pages are assumed to belong by default to, separated by commas (eg: GUEST)
  • route: (mandatory) holds policies about a specific route
    • id: (mandatory) page relative url (eg: administration)
    • roles: (mandatory) holds list of roles page is associated to, separated by commas (eg: USERS, ADMINISTRATORS)

Binding Points

In order to remain flexible and achieve highest performance, API takes no more assumptions than those absolutely required! It offers developers instead an ability to bind to its prototypes in order to gain certain functionality., _(*16)

Declarative Binding

It offers developers an ability to bind declaratively to its prototype classes/interfaces via XML:, _(*17)

Programmatic Binding

It offers developers an ability to bind programmatically to its prototypes via Wrapper constructor:, _(*18)

Execution

Once configuration is finished, one can finally use this API to authenticate and authorize by calling Wrapper, which defines following public methods:, _(*19)

Both authentication and authorization require following objects to be set beforehand and constructor injected:, _(*20)

• Request: encapsulating request to be handled
• Authentication\OAuth2\Driver[]: encapsulating a list of OAuth2 vendors to authenticate with

If authentication/authorization reached a point where request needs to be redirected, constructor throws a SecurityPacket. It may also throw:, _(*21)

• Authentication\Form\Exception: when login form is posted with wrong parameters names
• Authentication\OAuth2\Exception: when OAuth2 provider answers with an error to authorization code or access token requests
• PersistenceDrivers\Session\HijackException: when user id in session is associated to a different IP address
• Token\EncryptionException: when token could not be decrypted
• Token\Exception: when CSRF token is invalid or missing as "csrf" POST param @ form login or "state" GET param @ oauth2 authorization code response
• ConfigurationException: when XML is misconfigured, referenced classes are not found or not fitting expected pattern

Handling SecurityPacket

Developers of non-stateless applications are supposed to handle this exception with something like:, _(*22)

try {
    // sets $xml and $request
    $object = new Lucinda\WebSecurity\Wrapper($xml, $request);
    // operate with $object to retrieve information
} catch (SecurityPacket $e) {
    header("Location: ".$e->getCallback()."?status=".$e->getStatus()."&penalty=".((integer) $e->getTimePenalty()));
    exit();
}

Developers of stateless web service applications, however, are supposed to handle this exception with something like:, _(*23)

try {
    // sets $xml and $request
    $object = new Lucinda\WebSecurity\Wrapper($xml, $request);
    // use $object to produce a response
} catch (SecurityPacket $e) {
    echo json_encode(["status"=>$e->getStatus(), "callback"=>$e->getCallback(), "penalty"=>(integer) $e->getTimePenalty(), "access_token"=>$e->getAccessToken()]);
    exit();
    // front end will handle above code and make a redirection
}

Handling other exceptions

They can be handled as following:, _(*24)

use Lucinda\WebSecurity;

try {
    // sets $xml and $request
    $object = new Wrapper($xml, $request);
    // process $object
} catch (SecurityPacket $e) {
    // handle security packet as above
} catch (Authentication\Form\Exception $e) {
    // respond with a 400 Bad Request HTTP status (it's either foul play or misconfiguration)
} catch (PersistenceDrivers\Session\HijackException $e) {
    // respond with a 400 Bad Request HTTP status (it's always foul play)
} catch (Token\EncryptionException $e) {
    // respond with a 400 Bad Request HTTP status (it's always foul play)
} catch (Token\Exception $e) {
    // respond with a 400 Bad Request HTTP status (it's either foul play or misconfiguration)
} catch (ConfigurationException $e) {
    // show stack trace and exit (it's misconfiguration)
} catch (Authentication\OAuth2\Exception $e) {
    // handle as you want (error received from OAuth2 vendor usually from user's decision not to approve your access)
}

Installation

First choose a folder, associate it to a domain then write this command in its folder using console:, _(*25)

composer require lucinda/security

Then create a configuration.xml file holding configuration settings (see configuration above) and a index.php file (see getting results above) in project root with following code:, _(*26)

$request = new Lucinda\WebSecurity\Request();
$request->setIpAddress($_SERVER["REMOTE_ADDR"]);
$request->setUri($_SERVER["REQUEST_URI"]!="/"?substr($_SERVER["REQUEST_URI"],1):"index");
$request->setMethod($_SERVER["REQUEST_METHOD"]);
$request->setParameters($_POST);
$request->setAccessToken(isset($_SERVER["HTTP_AUTHORIZATION"]) && stripos($_SERVER["HTTP_AUTHORIZATION"], "Bearer ")===0?trim(substr($_SERVER["HTTP_AUTHORIZATION"], 7)):"");

try {
    // sets $xml and $request
    $object = new Lucinda\WebSecurity\Wrapper(simplexml_load_file("configuration.xml"), $request);
    // operate with $object to retrieve information
} catch (Lucinda\WebSecurity\SecurityPacket $e) {
    header("Location: ".$e->getCallback()."?status=".$e->getStatus()."&penalty=".((integer) $e->getTimePenalty()));
    exit();
}

Then make this file a bootstrap and start developing MVC pattern on top:, _(*27)

RewriteEngine on
RewriteRule ^(.*)$ index.php

Unit Tests

For tests and examples, check following files/folders in API sources:, _(*28)

• test.php: runs unit tests in console
• unit-tests.xml: sets up unit tests
• tests: unit tests for classes from src folder

Reference Guide

Class SecurityPacket

SecurityPacket class encapsulates an response to an authentication/authorization event that typically requires redirection and defines following methods relevant to developers:, _(*29)

Values of getStatus depend on argument enum case:, _(*30)

Usage example:, _(*31)

https://github.com/aherne/lucinda-framework/blob/master/src/Controllers/SecurityPacket.php, _(*32)

Class Request

Request encapsulates information about request necessary for authentication and authorization via following public methods:, _(*33)

Usage example:, _(*34)

https://github.com/aherne/lucinda-framework-engine/blob/master/src/RequestBinder.php, _(*35)

Interface OAuth2 Driver

Authentication\OAuth2\Driver interface encapsulates an oauth2 vendor to authenticate with and defines following methods:, _(*36)

Usage example:, _(*37)

https://github.com/aherne/lucinda-framework-engine/blob/master/src/OAuth2/AbstractSecurityDriver.php, _(*38)

Interface OAuth2 UserInformation

Authentication\OAuth2\UserInformation interface contains blueprints for retrieving information about logged in user on OAuth2 provider via following methods:, _(*39)

Usage example:, _(*40)

https://github.com/aherne/lucinda-framework-engine/blob/master/src/OAuth2/AbstractUserInformation.php, _(*41)

Interface OAuth2 VendorAuthenticationDAO

Authentication\OAuth2\VendorAuthenticationDAO interface contains blueprints for saving info about logged in user on OAuth2 provider via following methods:, _(*42)

Usage example:, _(*43)

https://github.com/aherne/lucinda-framework-configurer/blob/master/files/models/dao/UsersOAuth2Authentication.php, _(*44)

Interface UserAuthenticationDAO

Authentication\DAO\UserAuthenticationDAO interface contains blueprints for form-based database authentication via following methods:, _(*45)

Usage example:, _(*46)

https://github.com/aherne/lucinda-framework-configurer/blob/master/files/models/dao/UsersFormAuthentication1.php, _(*47)

Abstract Class LoginThrottler

Authentication\Form\LoginThrottler abstract class encapsulates form login throttling algorithm (against brute-force attacks) on a datasource (sql or nosql) via following public methods:, _(*48)

Class must be extended in order to implement following abstract protected method:, _(*49)

Usage example:, _(*50)

https://github.com/aherne/lucinda-framework-engine/blob/master/src/AbstractLoginThrottler.php https://github.com/aherne/lucinda-framework-configurer/blob/master/files/models/dao/SqlLoginThrottler.php, _(*51)

Abstract Class UserAuthorizationDAO

Authorization\DAO\UserAuthorizationDAO abstract class encapsulates database authorization where user accounts are checked in database via following public methods:, _(*52)

Class must be extended in order to implement following abstract method:, _(*53)

Usage example:, _(*54)

https://github.com/aherne/lucinda-framework-configurer/blob/master/files/models/dao/UsersAuthorization1.php, _(*55)

Abstract Class PageAuthorizationDAO

Authorization\DAO\PageAuthorizationDAO abstract class encapsulates database authorization where access control list is checked in database via following public methods:, _(*56)

Class must be extended in order to implement following abstract methods:, _(*57)

Usage example:, _(*58)

https://github.com/aherne/lucinda-framework-configurer/blob/master/files/models/dao/PagesAuthorization.php, _(*59)

Interface UserRoles

Authorization\UserRoles interface defines blueprints for any authorization where user roles are checked in database via following public methods:, _(*60)

Usage example:, _(*61)

https://github.com/aherne/lucinda-framework-configurer/blob/master/files/models/dao/UsersFormAuthentication3.php, _(*62)