Initialize README with project details and instructions

Add detailed project overview, structure, features, and usage instructions.

Author: Krishna757-Cyber

README.md

@@ -0,0 +1,209 @@
+# 🔐 Secure Authentication System using Cryptography
+
+> A C-based authentication simulator with a matching web-based frontend (HTML / CSS / JavaScript), demonstrating CIA Triad principles, XOR encryption, intrusion detection, and role-based access control.
+
+---
+
+## 📁 Project Structure
+
+```
+Secure-Authentication-System/
+│
+├── authen/
+│   ├── main.c            ← Entry point; menu system; session handling
+│   ├── functions.c       ← All function implementations
+│   ├── functions.h       ← Structs, constants, function declarations
+│   └── Makefile          ← Builds to authen / authen.exe
+│
+├── index.html            ← Web frontend (single-page app)
+├── styles.css            ← Cyberpunk terminal aesthetic
+├── script.js             ← JavaScript mirrors all C logic in-browser
+└── README.md             ← This file
+```
+
+> **Note:** `authen.exe` is the compiled binary generated by running `make windows` (MinGW on Windows) or `make` on Linux/macOS. It is **not** a source file — it is produced from `main.c + functions.c`.
+
+---
+
+## 🎯 Course Outcomes Covered
+
+| CO | Description | Implementation |
+|----|-------------|----------------|
+| CO1 | Understand cyber threats; define secure auth with flowchart & algorithm | CIA Triad in README; XOR cipher algorithm |
+| CO2 | Implement auth logic using loops, file handling, conditionals | `authenticate_user()`, `load_users()`, `save_users()` in C |
+| CO3 | Apply encryption & modular programming | `xor_encrypt()` / `xor_decrypt()` functions; separate header |
+| CO4 | Analyze attack simulation; incorporate incident response | `trigger_intrusion_alert()`, IDS lockout, security log |
+| CO5 | Integrate all cybersecurity concepts in a C application | Full system: register → login → session → admin panel |
+
+---
+
+## 🛡️ CIA Triad – Applied Principles
+
+### Confidentiality
+- Passwords are **never stored in plaintext**
+- XOR encryption with key `0x5A` applied before writing to `credentials.dat`
+- Masked password input (characters replaced with `*`)
+
+### Integrity
+- All authentication events **timestamped and logged** to `security.log`
+- Admin-only password reset — users cannot modify other accounts
+- Role-based access prevents privilege escalation
+
+### Availability
+- Account lockout after **3 consecutive failed attempts** prevents brute-force DoS
+- Admin can unlock accounts via the admin menu
+- System remains accessible to legitimate users at all times
+
+---
+
+## 🔑 Key Features
+
+| Feature | C (Terminal) | Web (Browser) |
+|---------|-------------|---------------|
+| User Registration | `register_user()` | `registerUser()` in script.js |
+| XOR Password Encryption | `xor_encrypt()` | `xorEncrypt()` — same key (0x5A) |
+| Login / Authentication | `authenticate_user()` | `authenticateUser()` |
+| Attempt Counter | `failed_attempts` field in struct | `failedAttempts` in localStorage |
+| Intrusion Detection | `trigger_intrusion_alert()` | Alert overlay with glitch animation |
+| Account Lockout | `is_locked` flag | `isLocked` flag |
+| Audit Logging | `security.log` (binary file) | localStorage JSON array |
+| Admin Panel | `admin_session_loop()` | Admin dashboard page |
+| Password Reset | `reset_password()` | `resetPassword()` modal |
+| Account Unlock | Menu option 4 | Unlock button in user table |
+| Masked Input | `mask_input()` (raw terminal) | `type="password"` + toggle |
+
+---
+
+## 🔐 XOR Encryption Algorithm
+
+```
+Encrypt:  enc[i] = plaintext[i] XOR 0x5A
+Decrypt:  plain[i] = enc[i] XOR 0x5A   (XOR is its own inverse)
+
+Example:
+  Plaintext:  'A' (ASCII 65)
+  65 XOR 90 = 27  → stored value
+  27 XOR 90 = 65  → decrypted back to 'A' ✓
+```
+
+> **Note:** XOR cipher is used here for demonstration purposes (as specified in the project requirements). In production systems, use bcrypt, Argon2, or SHA-256 with salt for password hashing.
+
+---
+
+## 🚨 Intrusion Detection System (IDS)
+
+The IDS triggers when:
+1. A user fails to log in **3 consecutive times**
+2. A locked account attempts login
+
+**Response Actions:**
+- Account is flagged `is_locked = 1` (C) / `isLocked: true` (JS)
+- Alert written to `security.log` with `IDS_ALERT` event type
+- Terminal prints a warning banner (C) / overlay modal appears (Web)
+- Only an administrator can unlock the account
+
+---
+
+## 🏃 How to Run
+
+### Web Version (No setup required)
+```bash
+# Just open in a browser:
+open index.html
+# or double-click index.html in your file manager
+```
+
+Default login credentials:
+- **Admin:** `admin` / `Admin@123`
+- **User:** `alice` / `alice123`
+
+---
+
+### C Version (Terminal)
+
+**Prerequisites:** GCC compiler
+
+#### Linux / macOS
+```bash
+cd authen/
+make
+./authen
+```
+
+#### Windows (MinGW)
+```bash
+cd authen/
+make windows
+authen.exe
+```
+
+#### Manual Compile (without make)
+```bash
+gcc -o authen main.c functions.c -Wall -std=c11
+```
+
+**First run:** The system auto-creates a default admin account (`admin` / `Admin@123`).
+
+---
+
+## 📋 Data Structures (from functions.h)
+
+```c
+typedef struct {
+    char username[32];
+    char enc_password[64];   /* XOR-encrypted, stored as raw bytes */
+    int  role;               /* 0 = USER, 1 = ADMIN               */
+    int  failed_attempts;    /* Consecutive failed logins          */
+    int  is_locked;          /* Lockout flag                       */
+} User;
+
+typedef struct {
+    char username[32];
+    int  role;
+    int  logged_in;
+} Session;
+```
+
+---
+
+## 📊 Security Event Log Format
+
+```
+[2025-01-15 10:23:41] REGISTER             | USER: alice                | User account created
+[2025-01-15 10:24:05] LOGIN_OK             | USER: alice                | User login
+[2025-01-15 10:25:12] LOGIN_FAIL           | USER: alice                | Wrong password (attempt 1/3)
+[2025-01-15 10:25:20] LOGIN_FAIL           | USER: alice                | Wrong password (attempt 2/3)
+[2025-01-15 10:25:30] IDS_ALERT            | USER: alice                | BRUTE-FORCE DETECTED – Account locked
+```
+
+---
+
+## 🗂️ Syllabus Topics Applied
+
+| Topic | Where Applied |
+|-------|--------------|
+| Threat Landscape / Threat Actors | IDS simulation of brute-force attacker |
+| Social Engineering | Password masking; account lockout awareness |
+| CIA Triad | Confidentiality (encryption), Integrity (logging), Availability (lockout) |
+| Principle of Least Privilege | Role-based access: user vs admin capabilities |
+| Symmetric Encryption | XOR cipher with shared key 0x5A |
+| Authentication Methods | Username/password; role verification |
+| Vulnerability Scanning (Simulation) | 3-attempt lockout simulates IDS/IPS |
+| Ethical Hacking (Brute-force) | Failed attempt simulation triggers alert |
+| Incident Response | Admin unlock; log review; alert generation |
+| C Programming Concepts | Structures, functions, loops, file I/O, conditionals, arrays |
+
+---
+
+## 👥 Authors
+
+- **Krishna757-Cyber** — Project Lead, C Implementation, Web Frontend
+- **Ritesh004-kira** — Password Encryption Enhancement, Login Attempts Handling
+
+---
+
+## 📌 Notes
+
+- The `.exe` file in the repository is the **compiled binary** for Windows — built from `main.c` and `functions.c` using MinGW GCC.
+- Credentials are stored in `credentials.dat` (C) and `localStorage` (Web) — both simulate the same file-handling concept.
+- This project is a **simulator** for educational purposes. Do not use XOR cipher for real-world password storage.