Skip to content

Latest commit

 

History

History
309 lines (233 loc) · 9.87 KB

demo.md

File metadata and controls

309 lines (233 loc) · 9.87 KB

🔐 zsCrypt — Demo

See every protection type in action


🧩 Type Overview

Type Protects Access Pattern Use Case
EncryptedValue<T> Value types (int, float, structs) Direct .Value get/set Game stats, counters, flags
HiddenValue<T> Reference types (string, byte[], objects) Direct .Value get/set Config objects, tokens
EphemeralValue<T> Any supported type ref callback via .Use() Passwords, API keys, secrets

All three implement ISecureValue and IDisposable for a consistent lifecycle contract. EncryptedValue<T> and HiddenValue<T> additionally implement ISecureValue<T> for direct value access.


🎮 EncryptedValue<T> — Value Type Protection

Encrypts unmanaged value types in memory. Every read decrypts; every write encrypts. Implicit operators make it feel like a native variable.

// Direct usage — the Fody weaver injects an algorithm into the base type
using EncryptedValue<int> health = new(100);
health.Value -= 25;
int hp = health;          // implicit conversion → 75
Console.WriteLine(hp);    // 75

Subclassing — Unique Algorithms Per Type

Each subclass receives its own randomly generated encryption algorithm at build time. Even two classes wrapping the same underlying type get completely different logic.

class SecureHealth : EncryptedValue<int> {
    public SecureHealth() { }
    public SecureHealth(int v) : base(v) { }
    public static implicit operator SecureHealth(int v) => new(v);
}

class SecureGold : EncryptedValue<int> {   // ← different algorithm than SecureHealth
    public SecureGold() { }
    public SecureGold(int v) : base(v) { }
    public static implicit operator SecureGold(int v) => new(v);
}
using SecureHealth health = 100;       // encrypted with algorithm A
using SecureGold   gold   = 5000;      // encrypted with algorithm B

health.Value -= 25;
gold.Value   += 250;

Console.WriteLine(health.Value);       // 75
Console.WriteLine(gold.Value);         // 5250

Demo Output

── EncryptedValue<T> ──────────────────
  Direct:  42 + 8 = 50
  Health:  100 - 25 = 75
  Gold:    5000 + 250 = 5250

👻 HiddenValue<T> — Reference Type Hiding

Stores a reference behind an encrypted GCHandle pointer. Memory scanners following pointer chains will not find the target object — the handle address is encrypted.

No subclassing needed — HiddenValue<T> delegates encryption to an internal EncryptedValue<long>.

using HiddenValue<string> secret = new("SuperSecretPassword123");
Console.WriteLine(secret.Value);       // SuperSecretPassword123

string plain = secret;                 // implicit conversion
using HiddenValue<byte[]> key = new(new byte[] { 0xCA, 0xFE });
byte[] data = key.Value;               // [202, 254]

Demo Output

── HiddenValue<T> ────────────────────
  String:  SuperSecretPassword123
  Bytes:   [202, 254]

⏱️ EphemeralValue<T> — Controlled-Lifetime Secrets

The decrypted value only exists inside a callback. Once the callback returns, the decrypted form is immediately destroyed — it never escapes into caller memory.

class SecureApiKey : EphemeralValue<string> {
    public SecureApiKey() { }
    public SecureApiKey(ref string v, bool eraseOrigin = true) : base(ref v, eraseOrigin) { }
    public static implicit operator SecureApiKey(string v) => new(ref v);
}

Origin Erasure

The ref constructor overwrites the caller's original variable after storing:

string apiKey = "sk-abc123def456ghi789";
// apiKey == "sk-abc123def456ghi789"

using SecureApiKey secure = new(ref apiKey, eraseOrigin: true);
// apiKey == "" ← characters zeroed in-place

Callback Access

The Use callbacks pass the decrypted value by ref to prevent automatic stack copies of value types from leaking unzeroed memory. Custom RefAction<T> and RefFunc<T, TResult> delegates are used instead of Action<T> / Func<T, TResult>.

// RefAction — read-only access (value passed by ref)
secure.Use((ref string decrypted) => {
    Console.WriteLine(decrypted);      // sk-abc123def456ghi789
});
// decrypted is destroyed here

// RefFunc — compute a result from the secret (value passed by ref)
int length = secure.Use((ref string d) => d.Length);
Console.WriteLine(length);            // 21

Demo Output

── EphemeralValue<T> ──────────────────
  Before:  "sk-abc123def456ghi789"
  After:   "" (zeroed)
  Callback: "sk-abc123def456ghi789"
  Length:  21 (computed inside callback)

🏗️ Compile-Time Encryption

Literal values assigned to encrypted types are encrypted in the binary at build time. The plaintext never appears in the compiled assembly. The Fody weaver uses each type's own algorithm — no separate decryption mechanism required.

// Integer — "12345" does not exist as plaintext in the binary
using EncryptedValue<int> secret = new(12345);
Console.WriteLine(secret.Value);       // 12345

// Subclass — uses SecureHealth's own algorithm
using SecureHealth health = 9999;
Console.WriteLine(health.Value);       // 9999

// String — "sk-live-..." does not appear in the binary
using SecureApiKey key = "sk-live-7f3a9b2c4d5e6f";
key.Use((ref string d) => Console.WriteLine(d));    // sk-live-7f3a9b2c4d5e6f

// Direct EphemeralValue
EphemeralValue<string> msg = "Encrypted at compile time.";
msg.Use((ref string d) => Console.WriteLine(d));    // Encrypted at compile time.
msg.Dispose();

Demo Output

── Compile-Time Encryption ────────────
  Int:     12345
  Health:  9999
  ApiKey:  sk-live-7f3a9b2c4d5e6f
  String:  Encrypted at compile time.

🔗 ISecureValue Interface

All protected types share a common interface for uniform lifecycle management:

public interface ISecureValue : IDisposable {
    bool IsDisposed { get; }
}

public interface ISecureValue<T> : ISecureValue {
    T Value { get; set; }
}
Type Implements
EncryptedValue<T> ISecureValue<T>
HiddenValue<T> ISecureValue<T>
EphemeralValue<T> ISecureValue (no direct Value — callback-only)

This enables polymorphic handling:

void Cleanup(ISecureValue value) {
    if (!value.IsDisposed)
        value.Dispose();
}

🛡️ Memory Safety Guarantees

Guarantee How
Decrypted data zeroed after every read finally blocks + MemoryCleaner.Destroy
No value-type stack copies in callbacks ref delegates (RefAction<T>, RefFunc<T, TResult>)
String characters zeroed in-place Unsafe pinned pointer overwrite
Byte arrays zeroed CryptographicOperations.ZeroMemory (JIT-resistant)
Unmanaged heap zeroed Explicit byte-level zeroing after Marshal operations
No dead-store elimination [MethodImpl(NoInlining)] on all destroy methods
Thread-safe lock + volatile disposal flags with double-check pattern

🚀 Run the Demo

dotnet build
dotnet run --project src/zsCrypt.Example

Full Output

╔══════════════════════════════════════╗
║          zsCrypt Demo                ║
╚══════════════════════════════════════╝

── EncryptedValue<T> ──────────────────
  Direct:  42 + 8 = 50
  Health:  100 - 25 = 75
  Gold:    5000 + 250 = 5250

── HiddenValue<T> ────────────────────
  String:  SuperSecretPassword123
  Bytes:   [202, 254]

── EphemeralValue<T> ──────────────────
  Before:  "sk-abc123def456ghi789"
  After:   "" (zeroed)
  Callback: "sk-abc123def456ghi789"
  Length:  21 (computed inside callback)

── Compile-Time Encryption ────────────
  Int:     12345
  Health:  9999
  ApiKey:  sk-live-7f3a9b2c4d5e6f
  String:  Encrypted at compile time.

Done.

📐 Architecture At a Glance

┌─────────────────────────────────────────────────┐
│                  Your Code                       │
│                                                  │
│  SecureHealth : EncryptedValue<int>   → algo A   │
│  SecureGold   : EncryptedValue<int>   → algo B   │
│  SecureApiKey : EphemeralValue<string> → algo C   │
│  HiddenValue<string> direct           → auto     │
│                                                  │
│  ISecureValue / ISecureValue<T>                  │
│  ├─ EncryptedValue<T> ── virtual Encrypt/Decrypt │
│  ├─ HiddenValue<T> ───── delegates to above      │
│  └─ EphemeralValue<T> ── virtual Encrypt/Decrypt │
└─────────────────────────────────────────────────┘
         │ Fody weaver at build time
         ▼
┌─────────────────────────────────────────────────┐
│  Per-type: 20–50 random operations               │
│  ADD · SUB · XOR · ROL · ROR · NOT               │
│  Large constants (10000–999999) as IL operands    │
│  Grouped with Int64 locals for complex output     │
│  Fresh random parameters every build              │
└─────────────────────────────────────────────────┘