Skip to content

Latest commit

 

History

History
142 lines (100 loc) · 5.91 KB

CONTRIBUTING.md

File metadata and controls

142 lines (100 loc) · 5.91 KB

Contributing to zsCrypt

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.


Table of Contents


Code of Conduct

Be respectful and constructive. All contributors are expected to maintain a welcoming environment regardless of experience level, background, or perspective.


How to Contribute

  1. Fork the repository on GitHub.
  2. Create a branch from main for your change (e.g. fix/thread-safety-dispose or feat/new-op-type).
  3. Make your changes following the Coding Standards below.
  4. Verify the build and example run pass (see Development Setup).
  5. Open a Pull Request against main with a clear description of what you changed and why.

Development Setup

Prerequisites

  • .NET 8 SDK
  • Any editor that supports C# (Visual Studio, VS Code with C# extension, Rider, etc.)

Build

dotnet build

Run the Example

dotnet run --project src/zsCrypt.Example

The 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.


Project Structure

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

Coding Standards

  • 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, #region blocks, 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 declared volatile. Always double-check volatile flags inside the lock to eliminate TOCTOU races.
  • Memory Safety: Sensitive byte arrays must be zeroed via MemoryCleaner in finally blocks — 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.

Security Guidelines

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 AllocHGlobal allocation must be zeroed before FreeHGlobal is 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).


Submitting a Pull Request

  1. Keep PRs focused — one logical change per PR.
  2. Write a clear PR description:
    • What changed.
    • Why the change is needed (link to an issue if applicable).
    • How you verified correctness (dotnet build output, example run output, manual IL inspection, etc.).
  3. Ensure dotnet build produces 0 warnings and 0 errors.
  4. Ensure dotnet run --project src/zsCrypt.Example produces the expected output.
  5. For changes to cryptographic or memory-safety logic, describe your threat model reasoning in the PR body.

Reporting Bugs

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).

Requesting Features

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.