sBurger256 2.0.4

🔐 sBurger-256

A custom symmetric block cipher for .NET with a 256-bit key and substitution-permutation network.

📋 Table of Contents

• 📖 About
• ✨ Features
• 🚀 Getting Started
  • 📌 Prerequisites
  • 📦 Installation
• 💡 Usage
• 📚 API Reference
• 🧪 Running Tests
• 🏗️ Project Structure
• 🤝 Contributing
• 📄 License

📖 About

sBurger-256 is a custom symmetric encryption algorithm built as a .NET class library. It uses a 256-bit key and a substitution-permutation network to encrypt and decrypt data in blocks of up to 32 bytes.

The cipher derives internal transformation parameters from the key, then applies a sequence of XOR, bit-rotation, and bit-inversion operations to each byte of the data block.

⚠️ Note: This is an author's experimental cipher created for educational purposes. It has not been formally audited. Do not use it for protecting sensitive data in production.

✨ Features

🚀 Getting Started

📌 Prerequisites

• Using the NuGet package: .NET 8 or later
• Building this repository: .NET 10 SDK or later
• Repository language version: C# 14

📦 Installation

NuGet Package Manager

dotnet add package sBurger256

Or via the Package Manager Console in Visual Studio:

Install-Package sBurger256

Or add directly to your .csproj:

<PackageReference Include="sBurger256" Version="2.0.4" />

💡 Usage

using System.Security.Cryptography;
using System.Text;

// 1. Create a 256-bit key (e.g. from a passphrase via SHA-256).
byte[] key = SHA256.HashData(Encoding.UTF8.GetBytes("your passphrase"));

// 2. Initialize the cipher. The key constructor generates settings automatically.
using var cipher = new sBurger256.sBurger256(key);

// 3. Encrypt a 32-byte block.
byte[] data = Encoding.UTF8.GetBytes("Hello, sBurger-256 cipher test!!");  // 32 bytes
cipher.Encryption(data);
Console.WriteLine($"Ciphertext: {Convert.ToHexString(data)}");

// 4. Decrypt back.
cipher.Decryption(data);
Console.WriteLine($"Plaintext:  {Encoding.UTF8.GetString(data)}");

👉 See the full working demo in examples/sBurger256.Example/Program.cs.

📚 API Reference

🔨 Constructors

public sBurger256()

Creates a new cipher instance. Set the Key property and call GenerationSettings() before encrypting or decrypting.

public sBurger256(byte[] key)

Creates a new cipher instance with a non-zero 32-byte key and generates settings immediately.

🏷️ Properties

📏 Constants

⚙️ Methods

🔧 GenerationSettings

public void GenerationSettings()

Derives internal cipher parameters from the current key. Must be called once after setting the key and before any encryption or decryption unless using the sBurger256(byte[] key) constructor. Throws InvalidOperationException if the key has not been set, and ObjectDisposedException after disposal.

🔒 Encryption

public byte[] Encryption(byte[] data)

Encrypts the data block in place and returns the same array. Data length must be between 1 and 32 bytes. Throws ArgumentException for invalid length, InvalidOperationException if settings were not generated, and ObjectDisposedException after disposal. Also throws ArgumentNullException when data is null.

🔓 Decryption

public byte[] Decryption(byte[] data)

Decrypts the data block in place and returns the same array. Data length must be between 1 and 32 bytes. Throws ArgumentException for invalid length, InvalidOperationException if settings were not generated, and ObjectDisposedException after disposal. Also throws ArgumentNullException when data is null.

🧹 Dispose

public void Dispose()

Zeroes key material and derived settings. Prefer using var or call Dispose() when done. Encryption, decryption, key changes, and settings generation throw ObjectDisposedException after disposal.

🧪 Running Tests

dotnet test

Tests are located in tests/sBurger256.Tests/ and use xUnit. They cover key validation, roundtrip encryption/decryption, deterministic known-answer vectors, boundary conditions, and wrong-key scenarios.

🏗️ Project Structure

sBurger-256/
├── 📁 src/
│   ├── 📄 sBurger256.cs              # Library source
│   └── 📄 sBurger256.csproj
├── 📁 tests/
│   └── 📁 sBurger256.Tests/          # xUnit tests
│       ├── 📄 sBurger256Tests.cs
│       └── 📄 sBurger256.Tests.csproj
├── 📁 examples/
│   └── 📁 sBurger256.Example/        # Console demo app
│       ├── 📄 Program.cs
│       └── 📄 sBurger256.Example.csproj
├── 📄 Directory.Packages.props        # Central package management
├── 📄 sBurger256.slnx                 # Solution file
└── 📄 README.md

🤝 Contributing

Contributions are welcome! To get started:

1. 🍴 Fork the repository
2. 🌿 Create a feature branch (git checkout -b feature/my-feature)
3. ✏️ Make your changes and add tests
4. ✅ Run dotnet test to verify everything passes
5. 📬 Open a Pull Request

📄 License

This project is licensed under the MIT License.