aes256-java

Lightweight, zero-dependency AES-256 encryption for Java. Built with clean OOP design; encapsulation, inheritance, overloading, and overriding.
Version: v1.0.2
Status: Stable Release
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Features
   • OOP Concept Map
   • What aes256-java Is Not
   • Built With
2. Getting Started
   • Prerequisites
   • Quick Start
3. Usage
   • CLI Mode
   • Library Mode
4. Security Notes
5. Roadmap
6. Contributing
7. License
8. Third-Party Notices
9. Contact
10. Acknowledgments

(back to top)

About The Project

aes256-java is a lightweight, zero-dependency AES-256 encryption toolkit for Java. It ships as both a command-line tool for encrypting plaintext and files, and as an embeddable library you can drop into your own Java projects. The codebase is built with clean object-oriented design, demonstrating encapsulation, inheritance, method overloading, and method overriding.

Features

• PBKDF2-HMAC-SHA256 key-derivation baseline (AesGcmEngine).

• Byte-array AES-256/GCM encrypt/decrypt API (AesGcmEngine).

• Stream-based AES-256/GCM encrypt/decrypt API (AesGcmEngine).

• OOP abstraction layer with implemented wrappers (CryptoOperation, TextCipher, FileCipher).

• In-program selftest runner (SelfTest).

• Fully wired interactive CLI in Main for text/file encrypt/decrypt flows with friendly error mapping.

• Branded CLI presentation with header/banner output, action-specific screens, return-to-menu prompts, and console-aware output encoding in Main.

• AES-256 encryption and decryption for plaintext input.

• AES-256 encryption and decryption for files.

• Dual-mode usage: standalone CLI or embeddable library.

• Zero external dependencies; pure Java on top of javax.crypto.

• Clean OOP architecture suitable for learning, extending, or integrating.

OOP Concept Map

Reference notes: Local course OOP definitions used to build this concept map.
Mirror in source: Main.java header comment

Concept	Concrete Source Anchor
Encapsulation	CryptoOperation#passphrase with getPassphrase(), setPassphrase(char[]), consumePassphrase(), clearStoredPassphrase()
Inheritance	TextCipher extends CryptoOperation; FileCipher extends CryptoOperation
Method Overloading	TextCipher#encrypt(String) and TextCipher#encrypt(char[]); FileCipher#encrypt(Path), FileCipher#encrypt(File), FileCipher#encrypt(Path, Path)
Method Overriding	TextCipher#describe() and FileCipher#describe() override CryptoOperation#describe()

What aes256-java Is Not

• Not a vetted production cryptography library. See Security Notes.
• Not a key-management or secrets-storage system.
• Not a replacement for authenticated encryption libraries such as Tink or Bouncy Castle in regulated or high-assurance contexts.

Built With

• 

(back to top)

Getting Started

Status: stable (v1.0.0). The CLI entrypoints and library methods below define the supported 1.x baseline.

Prerequisites

• A Java Development Kit (JDK 17 or later recommended; any modern JDK that provides javax.crypto should work).
• Ability to run java and javac from your shell.

Verify your toolchain:

java -version
javac -version

Quick Start

1. Clone the repo.

   git clone https://github.com/zcalifornia-ph/aes256-java.git
   cd aes256-java

2. Review the project layout and entry points under the project root.
3. Compile the current baseline:

   cd aes256-java
   javac *.java

4. Start the interactive CLI:

   java Main

5. Run the in-program assertions:

   java Main --selftest

6. Review the packaged submission outputs when you need the flat-directory grader bundle:
   • aes256-java/README.md
   • aes256-java/rubric-self-check.md
   • aes256-java/Adeva_California_Rizal_PE04.zip
   • aes256-java/sha256.txt

(back to top)

Usage

The project exposes two intended usage modes. Concrete command and API signatures are being introduced incrementally as milestones land.

CLI Mode

Current available entry points:

java Main --help
java Main --selftest
java Main --selftest-large
java Main
  -> option 1 encrypts text (Base64 envelope output)
  -> option 2 decrypts text (friendly wrong-passphrase/corruption mapping)
  -> option 3 encrypts file (<input>.enc)
  -> option 4 decrypts file (strip .enc else .dec)
  -> option 5 runs the smoke test suite
  -> option 6 prints About / credits

Presentation notes:

• Help, menu, and action screens render a branded header before the active content.
• When a real console is attached, Main clears between menu/action screens; when not attached, it falls back to spacer lines and still keeps the workflow readable.
• After each action, the CLI pauses on Press Enter to return to menu... so the result stays visible before the next clear/menu repaint.

Sample interactive transcript (non-console fallback mode):

<banner>
AES-256-GCM LEARNING CLI | TEXT + FILE ENCRYPTION
==================================================
[ Menu ]

  1) Encrypt text
  2) Decrypt text
  3) Encrypt file
  4) Decrypt file
  5) Run Smoke Test
  6) About
  0) Quit

Input: 1
Plaintext: hello
warning: console is not attached; passphrase input will be visible.
Passphrase: secret
ciphertext (Base64):
<base64-envelope>

Press Enter to return to menu...

Input: 2
Ciphertext (Base64): <base64-envelope>
warning: console is not attached; passphrase input will be visible.
Passphrase: wrong
decrypt text failed: wrong passphrase or corrupted ciphertext.

Submission package note:

• The repository now includes a flat-directory submission bundle at aes256-java/Adeva_California_Rizal_PE04.zip.
• Its published checksum lives at aes256-java/sha256.txt.
• The grader-facing extracted-copy instructions live in aes256-java/README.md.
• The row-by-row rubric mapping lives in aes256-java/rubric-self-check.md.

Library Mode

Stable baseline (v1.0.0):

// Stable public primitives in aes256-java/AesGcmEngine.java:
// - PBKDF2WithHmacSHA256 key derivation (210000 iterations, 16-byte salt, 256-bit key)
// - AES/GCM/NoPadding byte-array encrypt/decrypt with envelope:
//   salt(16) || iv(12) || ciphertext || tag(16)
// - stream encrypt/decrypt overloads for InputStream/OutputStream paths using:
//   salt(16) || streamIv(12) || record(length(4) || ciphertext || tag(16))*
// PHASE-02 OOP wrappers are implemented:
// - CryptoOperation abstract base with consume-and-clear passphrase flow
// - TextCipher: Base64 text envelope encrypt/decrypt wrappers
// - FileCipher: stream file encrypt/decrypt wrappers with .enc/.dec naming policy
AesGcmEngine engine = new AesGcmEngine();
char[] passphrase = "secret".toCharArray();
byte[] envelope = engine.encrypt(plaintext, passphrase);
byte[] recovered = engine.decrypt(envelope, "secret".toCharArray());
engine.encrypt(inputStream, encryptedOutputStream, passphrase);
engine.decrypt(encryptedInputStream, decryptedOutputStream, "secret".toCharArray());
TextCipher textCipher = new TextCipher(engine, "secret".toCharArray());
String ciphertext = textCipher.encrypt("hello");
textCipher.setPassphrase("secret".toCharArray()); // reset because passphrase is consumed per operation
String recoveredText = textCipher.decrypt(ciphertext);
String label = textCipher.banner();

// In-program assertions:
int selfTestExit = SelfTest.runDefault(System.out); // 0 when all checks pass

Compatibility note: the supported 1.x public surface is the documented Main CLI entrypoints, SelfTest runner, AesGcmEngine encrypt/decrypt overloads, and the TextCipher / FileCipher wrappers shown above.

(back to top)

Security Notes

This is an educational implementation built as a learning exercise in applied cryptography and object-oriented design. For production systems, prefer:

• Java's built-in javax.crypto primitives paired with a vetted key derivation function such as PBKDF2 or Argon2.
• Authenticated encryption modes (for example AES-GCM) from a reviewed cryptographic library.
• Proper key storage (OS keychain, KMS, HSM) rather than passwords embedded in source or configuration.

Do not use this library to protect information with real regulatory, legal, financial, or safety consequences without independent security review.

Report suspected vulnerabilities through the process in SECURITY.md. Do not open public issues for security reports.

(back to top)

Roadmap

• v0.1.0 - Core crypto engine baseline (KDF + byte-array + stream API surfaces).
• v0.1.1 - OOP abstraction hierarchy skeleton (PHASE 02 / MILESTONE 2.1).
• v0.1.2 - OOP behavior wrappers implemented (PHASE 02 / MILESTONE 2.2).
• v0.1.3 - In-program selftest integration with dual entry paths (PHASE 02 / MILESTONE 2.3).
• v0.2.0 - CLI entrypoint with selftest flags/menu routing (Main + SelfTest).
• v0.2.1 - PHASE 03 / MILESTONE 3.1 menu scaffolding (--help, About, resilient menu loop, and staged handlers).
• v0.2.2 - Full interactive encrypt/decrypt CLI wiring and friendly error mapping (PHASE 03 / MILESTONE 3.2).
• v0.3.0 - Documentation reconciliation (docs) and release metadata alignment.
• v0.3.1 - PHASE 04 / MILESTONE 4.1 docs hardening (Javadoc pass + OOP concept-map synchronization in README.md and Main.java).
• v0.3.2 - CLI presentation polish (bannered screens, clear/return flow, about credits, and console-aware output encoding).
• v0.3.3 - PE04 submission packaging (Adeva_California_Rizal_PE04.zip), checksum publication, rubric self-check, and fresh-extract validation.
• v0.4.0 - Public release cleanup, integration guidance, and API stabilization.
• v1.0.0 - First stable public release with documented API, acceptance tests, and reconciled governance docs.
• v1.0.1 - Documentation terminology cleanup across root docs, release notes, and learning guides (no runtime or API changes).
• v1.0.2 - Source Javadoc cleanup: removed internal AI-DLC terminology from class-level comments across all five Java source files (no runtime or API changes).

See the open issues for proposed features and known gaps.

(back to top)

Contributing

Contributions are welcome, especially around OOP clarity, test coverage, and documentation for learners. See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md for process, behavior, and vulnerability reporting.

1. Fork the project.
2. Create your feature branch (git checkout -b feat/your-feature).
3. Commit your changes (git commit -m 'feat: add some feature').
4. Push to your branch (git push origin feat/your-feature).
5. Open a pull request.

(back to top)

Top contributors:

License

This project is licensed under the Apache License 2.0. See LICENSE.txt for the full license text and THIRD-PARTY-NOTICES.md for third-party and adaptation notices.

(back to top)

Contact

Maintainers:

• Jayrad P. Adeva - @Shinranation - jpadeva@up.edu.ph
• Zildjian E. California - @zcalifornia-ph - zecalifornia@up.edu.ph
• Rey Marvin C. Rizal - @marverickdev - rcrizal@up.edu.ph

Project Link: https://github.com/zcalifornia-ph/aes256-java

(back to top)

Acknowledgments

• Built by Adeva, California, and Rizal.
• The Java Cryptography Architecture (JCA) and javax.crypto maintainers, whose primitives make a zero-dependency AES implementation practical.
• Open-source educators whose OOP and applied-crypto material informed the design of this project.

(back to top)