| 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.
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); // 75Each 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── 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 conversionusing HiddenValue<byte[]> key = new(new byte[] { 0xCA, 0xFE });
byte[] data = key.Value; // [202, 254]── HiddenValue<T> ────────────────────
String: SuperSecretPassword123
Bytes: [202, 254]
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);
}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-placeThe 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── EphemeralValue<T> ──────────────────
Before: "sk-abc123def456ghi789"
After: "" (zeroed)
Callback: "sk-abc123def456ghi789"
Length: 21 (computed inside callback)
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();── Compile-Time Encryption ────────────
Int: 12345
Health: 9999
ApiKey: sk-live-7f3a9b2c4d5e6f
String: Encrypted at compile time.
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();
}| 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 |
dotnet build
dotnet run --project src/zsCrypt.Example╔══════════════════════════════════════╗
║ 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.
┌─────────────────────────────────────────────────┐
│ 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 │
└─────────────────────────────────────────────────┘