[PR #266] [MERGED] Core/SSL: AES-256-GCM encryption and decryption #275

New issue

Closed

opened 2026-05-05 03:44:38 -06:00 by gitea-mirror · 0 comments

gitea-mirror commented

2026-05-05 03:44:38 -06:00

Owner

📋 Pull Request Information

Original PR: https://github.com/ultimatepp/ultimatepp/pull/266
Author: @ismail-yilmaz
Created: 5/4/2025
Status: ✅ Merged
Merged: 5/5/2025
Merged by: @mirek-fidler

Base: master ← Head: aes256_encryption

📝 Commits (1)

79b5ad2 Core/SSL: AES-256-GCM encryption and decryption

📊 Changes

8 files changed (+697 additions, -1 deletions)

View changed files

➕ autotest/AES256/AES256.upp (+10 -0)
➕ autotest/AES256/main.cpp (+85 -0)
➕ reference/AESEncryption/AESEncryption.upp (+12 -0)
➕ reference/AESEncryption/main.cpp (+40 -0)
➕ uppsrc/Core/SSL/AES.cpp (+333 -0)
📝 uppsrc/Core/SSL/SSL.h (+37 -0)
📝 uppsrc/Core/SSL/SSL.upp (+4 -1)
➕ uppsrc/Core/SSL/src.tpp/Upp_SSL_AES256GCM_en-us.tpp (+176 -0)

📄 Description

Rationale

U++ currently lacks a modern, authenticated encryption API suitable for securely storing or transmitting sensitive data. This pull request introduces a self-contained, stream-capable Aes256Gcm class to Core/SSL package that implements AES-256 in GCM mode, providing,

Features

Confidentiality via AES-256 encryption
Integrity and authenticity via GCM authentication tag
Randomized encryption using per-message salt and IV
Password-based key derivation via PBKDF2 with configurable iteration count
Streaming support for large data encryption/decryption
Non-deterministic output to prevent ciphertext pattern leakage
Format versioning for future-proofing

This implementation aligns with modern cryptographic best practices and fills an essential gap in U++'s Core/SSL package.

Format

Encrypted data uses the following binary envelope:

[Prefix][Salt][IV][Ciphertext][Tag]

Salt and IV are randomly generated. The authentication Tag is appended at the end. The version Prefix is meant to allow future format upgrades.

Public API

class Aes256Gcm : NoCopy {
public:
    Aes256Gcm();
    ~Aes256Gcm();

    Aes256Gcm& Iteration(int n);
    Aes256Gcm& Chunksize(int sz);

    bool Encrypt(Stream& in, const String& password, Stream& out);
    bool Decrypt(Stream& in, const String& password, Stream& out);
    bool Encrypt(const String& in, const String& password, String& out);
    bool Decrypt(const String& in, const String& password, String& out);

    Gate<int64, int64> WhenProgress;
    String GetErrorDesc() const;
};

String AES256Encrypt(const String& in, const String& password, Gate<int64, int64> WhenProgress = Null);
String AES256Decrypt(const String& in, const String& password, Gate<int64, int64> WhenProgress = Null);
bool AES256Encrypt(Stream& in, const String& password, Stream& out, Gate<int64, int64> WhenProgress = Null);
bool AES256Decrypt(Stream& in, const String& password, Stream& out, Gate<int64, int64> WhenProgress = Null);

Unit Tests

Encryption/decryption roundtrip
Invalid password and tampering detection
Format validation
Non-deterministic output
Empty input behavior

Reference Examples

AESEncryption: Demonstrates the basic usage of AES-256-GCM functions.

API docs

Included.

The main context for this PR can be found here.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/ultimatepp/ultimatepp/pull/266 **Author:** [@ismail-yilmaz](https://github.com/ismail-yilmaz) **Created:** 5/4/2025 **Status:** ✅ Merged **Merged:** 5/5/2025 **Merged by:** [@mirek-fidler](https://github.com/mirek-fidler) **Base:** `master` ← **Head:** `aes256_encryption` --- ### 📝 Commits (1) - [`79b5ad2`](https://github.com/ultimatepp/ultimatepp/commit/79b5ad257609134f9b8fdc10c13911ed2e57a806) Core/SSL: AES-256-GCM encryption and decryption ### 📊 Changes **8 files changed** (+697 additions, -1 deletions) <details> <summary>View changed files</summary> ➕ `autotest/AES256/AES256.upp` (+10 -0) ➕ `autotest/AES256/main.cpp` (+85 -0) ➕ `reference/AESEncryption/AESEncryption.upp` (+12 -0) ➕ `reference/AESEncryption/main.cpp` (+40 -0) ➕ `uppsrc/Core/SSL/AES.cpp` (+333 -0) 📝 `uppsrc/Core/SSL/SSL.h` (+37 -0) 📝 `uppsrc/Core/SSL/SSL.upp` (+4 -1) ➕ `uppsrc/Core/SSL/src.tpp/Upp_SSL_AES256GCM_en-us.tpp` (+176 -0) </details> ### 📄 Description ## Rationale U++ currently lacks a modern, authenticated encryption API suitable for securely storing or transmitting sensitive data. This pull request introduces a self-contained, stream-capable `Aes256Gcm` class to `Core/SSL` package that implements AES-256 in GCM mode, providing, ## Features - Confidentiality via AES-256 encryption - Integrity and authenticity via GCM authentication tag - Randomized encryption using per-message salt and IV - Password-based key derivation via PBKDF2 with configurable iteration count - Streaming support for large data encryption/decryption - Non-deterministic output to prevent ciphertext pattern leakage - Format versioning for future-proofing This implementation aligns with modern cryptographic best practices and fills an essential gap in U++'s Core/SSL package. ## Format Encrypted data uses the following binary envelope: ``` [Prefix][Salt][IV][Ciphertext][Tag] ``` `Salt` and `IV` are randomly generated. The authentication `Tag` is appended at the end. The version `Prefix` is meant to allow future format upgrades. ## Public API ``` class Aes256Gcm : NoCopy { public: Aes256Gcm(); ~Aes256Gcm(); Aes256Gcm& Iteration(int n); Aes256Gcm& Chunksize(int sz); bool Encrypt(Stream& in, const String& password, Stream& out); bool Decrypt(Stream& in, const String& password, Stream& out); bool Encrypt(const String& in, const String& password, String& out); bool Decrypt(const String& in, const String& password, String& out); Gate<int64, int64> WhenProgress; String GetErrorDesc() const; }; String AES256Encrypt(const String& in, const String& password, Gate<int64, int64> WhenProgress = Null); String AES256Decrypt(const String& in, const String& password, Gate<int64, int64> WhenProgress = Null); bool AES256Encrypt(Stream& in, const String& password, Stream& out, Gate<int64, int64> WhenProgress = Null); bool AES256Decrypt(Stream& in, const String& password, Stream& out, Gate<int64, int64> WhenProgress = Null); ``` ## Unit Tests - Encryption/decryption roundtrip - Invalid password and tampering detection - Format validation - Non-deterministic output - Empty input behavior ## Reference Examples - `AESEncryption`: Demonstrates the basic usage of AES-256-GCM functions. ## API docs - Included. ## Related Discussions The main context for this PR can be found [here](https://github.com/ultimatepp/ultimatepp/discussions/265). --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>