final class \SmartAuth
{ } ::

Class: Smart Authentication - provides a safe, in-memory object, to store the authentication data and to provide a standard way to work with authentication inside the Smart.Framework / modules.
It must be re-populated on each execution. This ensure using a good practice for Auth mechanisms.
It provides the core and only STATIC methods to integrate authentication with Smart.Framework
The very important security concerns regarding the authentication protection against forgery,
the mechanism implemented in this class will offer a very good protection by using CONSTANTS,
so after a successful or failed authentication, the page needs to refresh or load another page
in order to change authentication data.
This comes as a result of more than 15 years research over web and client/server technologies ...
The best practices are to never store Authentication objects in session because session can be forged.
To avoid such bad practices this object provide just STATIC methods !!
The best way is to store just the login ID and a safe password HASH (irreversible) in session
and re-check authentication each time when the page is loaded or to use the HTTP AUTH mechanism
to avoid store in session the username / password hash. Or this can be combined with cookies, but requires
much more atention to pay by avoiding session forgery or cookie leakage.
Session must be protected against forgery by implementing advanced detection mechanisms based on
IP address and the browser signature of the client. The Smart Session provides a good layer for this purpose.

Language: PHP
Located at: lib/framework/lib_auth.php
Package: @Core:Authentication
Namespace: \
Class Name: SmartAuth
Version: v.20231018
Depends: Smart, SmartEnvironment, SmartCipherCrypto, SmartCryptoCipherBlowfishCBC
Usage: static object: Class::method() - This class provides only STATIC methods

class Methods

public static function validate_auth_username ( string $auth_user_name, bool $check_reasonable = false ) {} :: BOOL

@return: {BOOLEAN} TRUE if the username is valid or FALSE if not
@param: {STRING} $auth_user_name: The Auth User Name to be validated ; max length is 25, can contain just: a-z 0-9 .
@param: {BOOL} $check_reasonable: Check for reasonable length ; if FALSE, min length is 3 ; if TRUE, min length is 5

Validate an Auth User Name

public static function validate_auth_password ( string $auth_user_pass, bool $check_complexity = false ) {} :: BOOL

@return: {BOOLEAN} TRUE if the password is valid or FALSE if not
@param: {STRING} $auth_user_pass: The Auth Password (plain text) to be validated ; min length is 7 ; max length is 88
@param: {BOOL} $check_complexity: Check for password complexity ; if set to TRUE will allow just complex passwords

Validate an Auth Password

public static function set_login_data ( string $y_realm, string $y_method, string $y_pass, string $y_user_id, string $y_user_name, string $y_user_email = "", string $y_user_fullname = "", ARRAY/STRING $y_user_privileges_list = [0 => "none", 1 => "no-privilege"], ARRAY/STRING $y_user_restrictions_list = [0 => "none", 1 => "no-restriction"], int $y_user_quota = -1, array $y_user_metadata = [], string $y_keys = "" ) {} :: BOOL

@return: {BOOLEAN} TRUE if all data is OK, FALSE if not or try to reauthenticate under the same execution (which is not allowed ; must be just once per execution)
@param: {STRING} $y_realm: *OPTIONAL* The user Authentication Realm(s)
@param: {ENUM} $y_method: *OPTIONAL* The authentication method used, as description only: HTTP-BASIC / OTHER / ...
@param: {STRING} $y_pass: *OPTIONAL* The user login password hash (will be stored in memory as encrypted to avoid exposure)
@param: {STRING} $y_user_id: The user (login) ID ; can be the Username or Email (on backend this should be always set with the same value as Username)
@param: {STRING} $y_user_name: The user username ; Mandatory ; must be valid safe username
@param: {STRING} $y_user_email: *OPTIONAL* The user Email ; if email is used as login ID this may be redundant !
@param: {STRING} $y_user_fullname: *OPTIONAL* The user Full Name (First Name + Last Name)
@param: {ARRAY/STRING} $y_user_privileges_list: *OPTIONAL* The user Privileges List as string '<priv-a>,<priv-b>,...' or array ['priv-a','priv-b'] that list all the current user privileges ; a privilege key must have 3..28 characters and can contain only: a-z -
@param: {ARRAY/STRING} $y_user_restrictions_list: *OPTIONAL* The user Restrictions List as string '<restr-a>,<restr-b>,...' or array ['restr-a','restr-b'] that list all the current user restrictions ; a restriction key must have 3..28 characters and can contain only: a-z -
@param: {STRING} $y_user_quota: *OPTIONAL* The user (storage) Quota
@param: {ARRAY} $y_user_metadata: *OPTIONAL* The user metainfo, associative array key => value ; Ex: [ 'auth-safe' => 101 ]
@param: {STRING} $y_keys: *OPTIONAL* The user Private Key (will be stored in memory as encrypted to avoid exposure)

Set the (in-memory) Auth Login Data
It can be used just once per execution (session) as it stores the data using constants,
and the data cannot be changed after a successful or failed authentication has set.

public static function check_login ( ) {} :: BOOL

@return: {BOOLEAN} TRUE if current user is Logged-in, FALSE if not

Check the (in-memory) Auth Login Data if the current user is logged-in

public static function get_login_data ( bool $y_skip_sensitive = false ) {} :: ARRAY

@return: {ARRAY} a complete array containing all the meta-data of the current auth user

Get the (in-memory) Auth Login Data

public static function get_auth_method ( ) {} :: STRING

@return: {STRING} The user login method

Get the auth user login method from (in-memory) Auth Login Data

public static function get_auth_realm ( ) {} :: STRING

@return: {STRING} returns the current user auth realm or an empty string if not set

Get the auth realm of the current user stored in the (in-memory) Auth Login Data

public static function get_auth_id ( ) {} :: STRING

@return: {STRING} if current user is Logged-in will get the user (login) ID which is mandatory, else an empty string

Get the current user auth ID from the (in-memory) Auth Login Data

public static function get_auth_username ( ) {} :: STRING

@return: {STRING} returns the user login username or an empty string if not set

Get the current user auth username from the (in-memory) Auth Login Data

public static function get_auth_passhash ( ) {} :: STRING

@return: {STRING} The plain password if was set or empty string

Get the auth (safe) stored password hash from (in-memory)

public static function get_user_email ( ) {} :: STRING

@return: {STRING} returns the user login email or an empty string if not set

Get the current user email from the (in-memory) Auth Login Data

public static function get_user_privkey ( ) {} :: STRING

@return: {STRING} The plain private-key if was set and valid or empty string

Get the auth user (safe) stored private-key from (in-memory)

public static function get_user_fullname ( ) {} :: STRING

@return: {STRING} returns the user login full name or an empty string if not set

Get the current user Full Name (First + Last Name) from the (in-memory) Auth Login Data

public static function get_user_privileges ( ) {} :: STRING

@return: {STRING} returns user login privileges as a list-string like: '<privilege-one>,<privilege-two>,...' or an empty string if not set

Get the list of the current user privileges stored in the (in-memory) Auth Login Data

public static function get_user_restrictions ( ) {} :: STRING

@return: {STRING} returns user login restrictions as a list-string like: '<restriction-one>,<restriction-two>,...' or an empty string if not set

Get the list of the current user restrictions stored in the (in-memory) Auth Login Data

public static function test_login_privilege ( string $y_privilege_to_test, string $y_list_to_test = null ) {} :: BOOL

@return: {BOOLEAN} TRUE if the current user have the tested privilege or FALSE if does not

Test if the current user privileges contain the tested one using the (in-memory) Auth Login Data

public static function test_login_restriction ( string $y_restriction_to_test, string $y_list_to_test = null ) {} :: BOOL

@return: {BOOLEAN} TRUE if the current user have the tested restriction or FALSE if does not

Test if the current user restrictions contain the tested one using the (in-memory) Auth Login Data

public static function validate_privilege_or_restriction_key ( string $y_key_to_validate ) {} :: BOOLEAN

@return: {BOOLEAN} TRUE if the current user have the tested Privilege/Restriction or FALSE if does not

Test if a Privilege/Restriction key is valid and contain only allowed chars

public static function get_user_quota ( ) {} :: INT

@return: {INTEGER} returns the user (storage) quota

Get the current user quota stored in the (in-memory) Auth Login Data

public static function get_user_metadata ( ) {} :: ARRAY

@return: {ARRAY} returns an array with all current user metadata

Get the current user metadata stored in the (in-memory) Auth Login Data

public static function encrypt_privkey ( string $y_pkey, string $y_secret ) {} :: STRING

@return: {STRING} returns a string with the safe encrypted privacy-key or empty string if was empty
@param: {STRING} $y_pkey: The private key to be safe encrypted
@param: {STRING} $y_secret: The encryption secret

Safe Encrypt a private key using a password, using Blowfish CBC
The provided password have to be the same as the login password for the user is being used to avoid decryption of the key by other users
This is completely safe as long as the users login passwords are supposed to be stored as ireversible hashes (by default they are ... but with custom login implementations they can be or not, depending the developer's choice)

public static function decrypt_privkey ( string $y_pkey, string $y_secret ) {} :: STRING

@return: {STRING} returns a string with the privacy-key (decrypted, if any, and if valid) which was supposed to be provided as encrypted
@param: {STRING} $y_pkey: The private key to be decrypted
@param: {STRING} $y_secret: The encryption secret

Decrypt a private key using a password, using Blowfish CBC
The provided password have to be the same as the login password for the user is being used to avoid decryption of the key by other users
This is completely safe as long as the users login passwords are supposed to be stored as ireversible hashes (by default they are ... but with custom login implementations they can be or not, depending the developer's choice)

public static function safe_arr_privileges_or_restrictions ( MIXED $y_list ) {} :: ARRAY

@return: {ARRAY} returns the associative array of auth Privileges or Restrictions as [ 'key-a' => 'Key A', 'key-b' => 'Key B', ..., 'key-n' => 'Key N' ]
@param: {MIXED} $y_list: List of Privileges or Restrictions as ARRAY [ 'key-a', 'key-b', ..., 'key-n' ] or STRING '<key-a>, <key-b>, ..., <key-n>'

Build the associative Array of Auth Privileges or Restrictions

class Properties

class Constants

public const REGEX_VALID_PRIV_NAME = "/^[a-z\\-]{3,28}$/" ; ::

public const SWT_VERSION_PREFIX = "SWT" ; ::

public const SWT_VERSION_SUFFIX = "v1.2" ; ::

public const SWT_VERSION_SIGNATURE = "swt:1.2" ; ::

Sample code: PHP


<?php

// Usage example:
 SmartAuth::some_method_of_this_class(...);

// #end php code

documentation generated on: 2023-10-19 23:15:45 +0000

final class \SmartAuth { } ::

class Methods

class Properties

class Constants

Sample code: PHP

final class \SmartAuth
{ } ::