Session Security

This document describes the security-related features of the Session class, including login attempt tracking, account lockouts, session creation limits, fingerprint validation, and inactivity handling.

Overview

The session security system protects against:

Brute-force login attempts
Session hijacking (fingerprint/IP mismatch)
Session fixation
Session creation flooding (bot protection)
Idle session abuse (inactivity timeout)

Method	Purpose	Scope
`get_security_status()`	Returns full session security status (locks, attempts, creation, inactivity).	Per IP / Fingerprint
`check_lock_status()`	Checks login attempt lock status.	Per IP / Fingerprint
`reset_attempts()`	Resets failed attempts after successful login.	Per IP / Fingerprint
`unlock_attempts()`	Manually unlocks a specific user.	Per IP / Fingerprint
`unlock_all_attempts()`	Unlocks all users globally.	Global
`security_log_attempt()`	Logs failed or suspicious attempts.	Per IP / Fingerprint
`security_check_lock()`	Blocks access if user is currently locked.	Per IP / Fingerprint
`security_track_session_creation()`	Tracks excessive session creation (anti-bot).	Per IP / Fingerprint
`generate_fingerprint()`	Generates unique fingerprint for session protection.	Per User
`regenerate_on_login()`	Prevents session fixation.	Per Session

Method Details

get_security_status()

Purpose: Returns complete security information for the current session.

Example Usage:

$status = $this->session->get_security_status();

if ($status['locked']) {
    echo "Locked for {$status['remaining']} seconds";
}

if ($status['creation_locked']) {
    echo "Too many sessions created. Wait {$status['creation_remaining']} seconds";
}

Returns:

Key	Description
locked	Whether login is locked
remaining	Remaining lock time (seconds)
attempts	Failed login attempts
max_attempts	Maximum allowed attempts
creation_locked	Whether session creation is locked
creation_remaining	Remaining creation lock time
inactivity_expired	Whether session expired due to inactivity
ip	Current user IP
fingerprint	Generated session fingerprint

check_lock_status()

Purpose: Check login attempt lock status.

Example Usage:

$status = $this->session->check_lock_status();

if ($status['locked']) {
    echo "Locked for {$status['remaining']} seconds.";
}

security_check_lock()

Purpose: Prevents execution if user is currently locked.

Example Usage:

$msg = $this->session->security_check_lock($ip, $fingerprint);

if ($msg) {
    die($msg);
}

security_log_attempt()

Purpose: Logs failed login or suspicious activity.

Example Usage:

$this->session->security_log_attempt($ip, $fingerprint, 'Invalid password');

reset_attempts()

Purpose: Clears failed attempts after successful login.

Example Usage:

$this->session->reset_attempts();

unlock_attempts()

Purpose: Unlock a specific user manually.

Example Usage:

$this->session->unlock_attempts($ip, $fingerprint);

unlock_all_attempts()

Purpose: Reset all locks globally.

Example Usage:

$count = $this->session->unlock_all_attempts();
echo "{$count} users unlocked";

Session Creation Lockout

Purpose: Prevent bots from rapidly creating sessions.

Behavior: - Tracks session creation timestamps - Locks if threshold exceeded - Uses creation_ prefix in storage

Example:

$msg = $this->session->security_track_session_creation($ip, $fingerprint);

if ($msg) {
    echo $msg;
}

Fingerprint Security

Purpose: Protect against session hijacking.

How it works: - Combines browser headers + optional IP - Uses HMAC SHA-256 hashing - Stored in session and verified on each request

Example:

$fingerprint = $this->session->generate_fingerprint();

Session Fixation Protection

Method: regenerate_on_login()

Purpose: Regenerates session ID after login.

Example:

$this->session->regenerate_on_login();

Inactivity Timeout

Purpose: Automatically destroys session after inactivity.

Behavior: - Based on sess_inactivity_timeout - Default: 30 minutes - Automatically checked on each request

Result: - Session destroyed silently - inactivity_expired becomes TRUE

Internal Methods (Advanced)

Method	Description
`_security_init()`	Initializes storage file securely
`_security_load()`	Loads JSON data with file locking
`_security_save()`	Saves data safely with locking

Storage Format (security.json)

{
  "IP_FINGERPRINT": {
    "attempts": 3,
    "timestamps": [1234567890],
    "locked_until": 1234567999
  },
  "creation_IP_FINGERPRINT": {
    "creations": [1234567890],
    "locked_until": 1234567999
  }
}

Summary

Method	Use Case
`get_security_status()`	Full monitoring/debugging
`check_lock_status()`	Before login validation
`security_log_attempt()`	On failed login
`reset_attempts()`	After successful login
`security_track_session_creation()`	Prevent bot session spam
`regenerate_on_login()`	Prevent session fixation
`unlock_attempts()`	Admin manual unlock
`unlock_all_attempts()`	System reset