Thank you for your interest in contributing to zsCrypt! This document describes how to get involved, what to expect from the review process, and the standards contributions must meet.
- Code of Conduct
- How to Contribute
- Development Setup
- Project Structure
- Coding Standards
- Security Guidelines
- Submitting a Pull Request
- Reporting Bugs
- Requesting Features
Be respectful and constructive. All contributors are expected to maintain a welcoming environment regardless of experience level, background, or perspective.
- Fork the repository on GitHub.
- Create a branch from
mainfor your change (e.g.fix/thread-safety-disposeorfeat/new-op-type). - Make your changes following the Coding Standards below.
- Verify the build and example run pass (see Development Setup).
- Open a Pull Request against
mainwith a clear description of what you changed and why.
- .NET 8 SDK
- Any editor that supports C# (Visual Studio, VS Code with C# extension, Rider, etc.)
dotnet builddotnet run --project src/zsCrypt.ExampleThe Fody weaver runs automatically during the build and injects unique encryption algorithms into each EncryptedValue<T> and EphemeralValue<T> subclass. You should see all demo outputs print correctly with no errors.
zsCrypt/
├── src/
│ ├── zsCrypt.Example/ # Demo application & core library source
│ │ ├── Memory/
│ │ │ └── MemoryCleaner.cs # Secure in-place memory zeroing
│ │ ├── Serialization/
│ │ │ └── SerializationProvider.cs # Byte-level serialization
│ │ ├── Types/
│ │ │ ├── EncryptedValue.cs # Encrypted value-type wrapper
│ │ │ ├── HiddenValue.cs # Encrypted GCHandle pointer wrapper
│ │ │ └── EphemeralValue.cs # Callback-scoped decryption wrapper
│ │ └── Program.cs # Demo entry point
│ └── zsCrypt.Fody/
│ └── ModuleWeaver.cs # Fody weaver — injects algorithms at build time
├── CONTRIBUTING.md
├── LICENSE.md
└── README.md
- Language: C# 12 / .NET 8. Use the latest language features where they improve clarity.
- Style: Follow the style already present in the file you are editing (4-space indentation,
#regionblocks, XML doc comments on all public and protected members). - Comments: Add inline comments that explain why, not just what. Security-sensitive paths must explain the threat they guard against.
- Thread Safety: All shared mutable state must be protected by a
lock. Flags read across threads (such as_disposed) must be declaredvolatile. Always double-check volatile flags inside the lock to eliminate TOCTOU races. - Memory Safety: Sensitive byte arrays must be zeroed via
MemoryCleanerinfinallyblocks — even on exception paths. Never store plaintext to a field or return it to caller-controlled memory without zeroing afterwards. - Dispose Pattern: Follow the established pattern in the existing classes — outer volatile check, then lock with an inner double-check before any state mutation.
- No Locks in Finalizers: Finalizers must not acquire locks (deadlock risk). They may only perform simple, exception-safe cleanup of unmanaged resources.
zsCrypt is a security-focused library. Changes must be evaluated against the following criteria:
- No plaintext leaks — decrypted data must never outlive its immediate use scope.
- No sensitive data in exceptions — exception messages must not include plaintext values or key material.
- Key material — Algorithm parameters and constants are generated fresh each build by the Fody weaver and must never be committed to source.
- Unmanaged memory — any
AllocHGlobalallocation must be zeroed beforeFreeHGlobalis called. - Thread safety — concurrent access from multiple threads must be provably safe. Introduce new locking only after considering the full lock ordering to prevent deadlocks.
If your change touches the Fody weaver (ModuleWeaver.cs), add a note in your PR explaining how the generated IL was verified (e.g., by inspecting the output with ILSpy or by running the example and confirming round-trip correctness).
- Keep PRs focused — one logical change per PR.
- Write a clear PR description:
- What changed.
- Why the change is needed (link to an issue if applicable).
- How you verified correctness (
dotnet buildoutput, example run output, manual IL inspection, etc.).
- Ensure
dotnet buildproduces 0 warnings and 0 errors. - Ensure
dotnet run --project src/zsCrypt.Exampleproduces the expected output. - For changes to cryptographic or memory-safety logic, describe your threat model reasoning in the PR body.
Open a GitHub Issue with:
- A minimal reproduction case (code snippet or steps).
- Expected vs. actual behaviour.
- .NET SDK version and OS.
- Any relevant output or stack traces (sanitise any real secret values first).
Open a GitHub Issue describing:
- The use case the feature addresses.
- How it fits the existing security model.
- Any trade-offs or risks you have considered.
Feature requests that weaken the security model or introduce managed plaintext lifetime issues will not be accepted.