You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Oct 10, 2025. It is now read-only.
This project is a powerful and secure steganography tool built with Spring Boot 3. It allows you to hide text messages or files within images using the Least Significant Bit (LSB) technique. The application provides a RESTful API for all its operations, supports robust AES-256 encryption for hidden data, and includes features like large file streaming to ensure memory efficiency.
7
+
This project is a powerful and secure steganography tool built with Spring Boot 3. It allows you to hide text messages or files within images using the Least Significant Bit (LSB) technique. The application provides a RESTful API for all its operations, supports robust AES-256 encryption for hidden data, and is optimized for production with GraalVM native image support and Java Virtual Threads.
8
8
9
9
## Table of Contents
10
10
@@ -19,82 +19,94 @@ This project is a powerful and secure steganography tool built with Spring Boot
19
19
-[Getting Started](#getting-started)
20
20
-[Prerequisites](#prerequisites)
21
21
-[Cloning the Repository](#cloning-the-repository)
22
-
-[Configuration](#configuration)
23
-
-[Running the Application (JVM)](#running-the-application-jvm)
22
+
-[Configuration](#configuration)
23
+
-[Running the Application](#running-the-application)
24
+
-[1. For Local Development (JVM)](#1-for-local-development-jvm)
25
+
-[2. For Production (Native Docker Image)](#2-for-production-native-docker-image)
24
26
-[Interacting with the API](#interacting-with-the-api)
25
-
-[Containerization with Docker (Native Image)](#containerization-with-docker-native-image)
-[Example 2: Encode a Text Message](#example-2-encode-a-text-message)
29
+
-[Example 3: Decode a Stego Image](#example-3-decode-a-stego-image)
26
30
-[Project Structure](#project-structure)
27
31
-[Contributing](#contributing)
28
32
-[License](#license)
29
33
30
34
## What is Steganography?
31
35
32
-
Steganography is the practice of concealing a message, image, or file within another message, image, or file. Unlike cryptography, which obscures the content of a message, steganography conceals the very existence of the message. This tool uses the **Least Significant Bit (LSB)** method, which subtly alters the color data of image pixels to embed information, making the changes virtually invisible to the human eye.
36
+
Steganography is the practice of concealing a messageor file within another file. Unlike cryptography, which obscures the *content* of a message, steganography conceals the very *existence* of the message. This tool uses the **Least Significant Bit (LSB)** method, which subtly alters the color data of image pixels to embed information, making the changes virtually invisible to the human eye.
33
37
34
38
## Features
35
39
36
40
-**Text & File Steganography**: Embed both plain text and binary files within images.
37
-
-**Strong Encryption**: All hidden data is encrypted with **AES-256 (CBC mode)** using a key derived from your password via **PBKDF2**.
38
-
-**RESTful API**: Easy-to-use endpoints for encoding, decoding, capacity estimation, and managing encodings.
39
-
-**GraalVM Native Image Support**: Build a lightweight, fast-starting native executable container using Spring Boot's Maven plugin and Cloud Native Buildpacks.
40
-
-**Capacity Estimation**: Before performing an expensive encoding operation, you can estimate if your data will fit in a given image.
41
-
-**Large File Streaming**: Efficiently encodes large files by streaming them, keeping memory usage low.
42
-
-**Database Integration**: Metadata for each encoding is saved to a MySQL database using Spring Data JPA.
43
-
-**Virtual Threads**: Uses Java 25 Virtual Threads with an embedded Jetty server for high-concurrency request handling.
44
-
-**Scheduled Cleanup**: A background task cleans up orphaned stego files and expired extracted files.
45
-
-**Docker Compose Support**: Includes a `compose.yml` for easy multi-container setup.
41
+
-**Strong Encryption**: All hidden data is encrypted with **AES-256 (CBC mode)**. The encryption key is derived from your password using **PBKDF2 with 65,536 iterations** and a unique salt for each encoding.
42
+
-**RESTful API**: A comprehensive API for encoding, decoding, capacity estimation, and managing encodings.
43
+
-**GraalVM Native Image Support**: Build a lightweight, fast-starting native executable container using the integrated Spring Boot Maven plugin and Cloud Native Buildpacks.
44
+
-**High-Concurrency Ready**: Utilizes **Java 25 Virtual Threads** with an embedded Jetty server to efficiently handle a large number of concurrent requests.
45
+
-**Large File Streaming**: Efficiently encodes and encrypts large files by streaming them, keeping memory usage low.
46
+
-**Capacity Estimation**: A dedicated endpoint to check if your data will fit in a given image before performing the encoding.
47
+
-**Database Integration**: Encoding metadata is saved to a MySQL database using Spring Data JPA.
48
+
-**Scheduled Cleanup**: A background task periodically cleans up orphaned stego files from storage and deletes expired extracted files.
49
+
-**Robust Error Handling**: A global exception handler provides detailed, structured error responses (`ProblemDetail`) for API clients.
50
+
-**Traceability**: A `CorrelationIdFilter` adds a unique trace ID to every request for improved logging and debugging.
46
51
47
52
## How It Works
48
53
49
-
The application embeds data by modifying the least significant bits of an image's pixel color channels (Red, Green, Blue).
50
-
51
54
### Encoding Process
52
55
53
56
1.**Input**: A user provides a cover image, the data to hide (text or a file), and a password.
54
-
2.**Encryption**: The data is encrypted using AES-256.
55
-
3.**Metadata Creation**: A JSON metadata block is created containing details like LSB depth, data type, and a password verification hash.
56
-
4.**LSB Embedding**: The metadata and encrypted data are written into the cover image's pixels.
57
+
2.**Encryption**: The data is encrypted using AES-256. A unique salt is generated for each operation.
58
+
3.**Metadata Creation**: A JSON metadata block is created containing details like LSB depth, data type, and a **SHA-256 hash** of the encryption key for password verification on decode.
59
+
4.**LSB Embedding**: The metadata and encrypted data are written into the least significant bits of the cover image's pixels.
57
60
5.**Output**: The modified image is saved as a new, lossless **PNG file**, and its metadata is persisted in the database.
58
61
59
62
### Decoding Process
60
63
61
-
1.**Input**: A user provides the stego-image and the password.
62
-
2.**Metadata Extraction**: The application reads the image's LSBs to find and extract the metadata.
63
-
3.**Password Verification**: It hashes the provided passwordand compares it to the hash stored in the metadata.
64
-
4.**Payload Extraction & Decryption**: The application reads and decrypts the hidden data.
64
+
1.**Input**: A user provides the stego-image and the password used for encoding.
65
+
2.**Metadata Extraction**: The application reads the image's LSBs to find the "magic number" (`STEG`) and extracts the metadata.
66
+
3.**Password Verification**: It derives a key from the provided password, hashes it, and compares it to the hash stored in the metadata. The process fails if they don't match.
67
+
4.**Payload Extraction & Decryption**: The application reads the hidden data from the pixels and decrypts it using the password.
65
68
5.**Output**: The original text or file is returned.
66
69
70
+
### Security Model
71
+
72
+
-**Password Derivation**: The AES key is derived from the user's password and a unique, random **16-byte salt** using **PBKDF2**. This ensures that even identical passwords produce different keys for different encodings.
73
+
-**Password Verification**: During decoding, the provided password is used to derive a key, which is then hashed (SHA-256) and compared against the hash stored in the image's metadata. This prevents incorrect password attempts without decrypting the entire payload.
74
+
-**Authenticated Encryption**: The use of **CBC mode with PKCS5Padding** and a unique **16-byte Initialization Vector (IV)** ensures that encrypted data is resistant to common cryptographic attacks.
75
+
67
76
## Technology Stack
68
77
69
78
-**Java 25** & **Spring Boot 3**
70
-
-**GraalVM**: For building a native executable.
71
-
-**Spring Web, Data JPA, Jetty**
72
-
-**MySQL**: Database for persisting encoding metadata.
73
-
-**Maven**: For project and dependency management.
74
-
-**Docker & Docker Compose**: For container orchestration.
79
+
-**GraalVM**: For building the native executable.
80
+
-**Spring Framework**: Web, Data JPA, Jetty (for Virtual Threads).
81
+
-**Database**: MySQL.
82
+
-**Build & Packaging**: Maven, Spring Boot Buildpacks.
83
+
-**Containerization**: Docker & Docker Compose.
84
+
-**Utilities**: Lombok, MapStruct.
75
85
76
86
## API Endpoints
77
87
78
88
The base path for all endpoints is `/api/v1/stego`.
The main configuration is in `src/main/resources/application.yml`. Key properties can be overridden with environment variables, which is the standard practice for containerized deployment.
|`app.storage.base-path`|`STORAGE_BASE_PATH`| Local directory where files will be stored. |`storage`|
129
+
-`app.stream.threshold-bytes`: File size (in bytes) above which streaming is used for encoding. Default: `1MB`.
130
+
-`app.cleanup.*`: Settings for the scheduled file cleanup task.
131
+
-`app.extraction.temp-ttl-ms`: Time-to-live for extracted files. Default: `5 minutes`.
132
+
133
+
## Running the Application
134
+
135
+
There are two primary ways to run the application.
108
136
109
-
For local development, you can run the application directly on your machine's JVM.
137
+
### 1. For Local Development (JVM)
138
+
139
+
This method is ideal for development and debugging, as it uses Spring Boot's hot-reload capabilities.
110
140
111
141
1.**Start the Database**:
142
+
Open a terminal and run the following command to start the MySQL database service in the background.
112
143
```bash
113
144
docker compose up -d db-mysql
114
145
```
115
146
116
147
2. **Run the Spring Boot Application**:
148
+
In a separate terminal, run the application using the Maven wrapper.
117
149
```bash
118
150
./mvnw spring-boot:run
119
151
```
120
-
The application will start on port `8080`.
121
-
122
-
## Containerization with Docker (Native Image)
152
+
The application will start on `http://localhost:8080`.
123
153
124
-
The recommended way to run the application in production is to build a native image container using the Spring Boot Maven plugin.
154
+
### 2. For Production (Native Docker Image)
125
155
126
-
This process involves two simple steps:
127
-
128
-
1. **Build the Native Docker Image:**
129
-
Run the following Maven command. This will use Cloud Native Buildpacks to compile the application into a native executable and package it into a minimal Docker image named `noobdevsam/spring-project-steganography-tool:0.0.1-SNAPSHOT`.
156
+
This is the recommended approach for production. It compiles the application into a native executable and packages it into a minimal, secure Docker container.
130
157
158
+
1. **Build the Native Docker Image**:
159
+
Run the following Maven command. This uses Cloud Native Buildpacks to compile a native executable and create a Docker image named `noobdevsam/spring-project-steganography-tool:0.0.1-SNAPSHOT`.
131
160
```bash
132
-
# This command can take several minutes to complete
161
+
# This command can take several minutes and requires Docker to be running.
Once the image is built, you can start the application and the database using Docker Compose.
138
-
165
+
2. **Run with Docker Compose**:
166
+
Once the image is built, start the application and the database using Docker Compose.
139
167
```bash
168
+
# This will use the image built in the previous step.
140
169
docker compose up
141
170
```
142
-
The application will be available on port `8080`. The `storage` directory is mounted as a volume, so your files will persist between container restarts.
171
+
The application will be available on `http://localhost:8080`.
172
+
173
+
To stop all services, press `Ctrl+C` or run `docker compose down`.
0 commit comments