# dcrypt Common Utilities (`common`)
The `common` crate provides shared functionality, data structures, and security primitives that are used across multiple crates within the dcrypt workspace. Its main purpose is to centralize common code, especially related to security best practices, to ensure consistency and reduce redundancy.
## Core Components
1. **Security Primitives (`dcrypt_docs/common/security/README.md`)**:
This is the most critical part of the `common` crate. It defines types and traits for secure memory handling and cryptographic operations.
* **Secret Data Types**:
* `SecretBuffer<const N: usize>`: A fixed-size buffer that invokes zeroization on its owned bytes when dropped.
* `SecretVec`: (Requires `alloc` feature) A variable-length vector that wipes removed bytes and old allocations as it changes size, then zeroizes its complete allocation on drop.
* `EphemeralSecret<T: Zeroize>`: Wraps a value and invokes its `Zeroize` implementation on drop.
* `ZeroizeGuard<'a, T: Zeroize>`: A guard that invokes `zeroize` on a mutable reference when the guard goes out of
scope, useful for RAII-style cleanup.
* **Traits**:
* `SecureZeroingType`: For types that can be securely zeroed and cloned.
* `SecureOperation<T>`: Defines a pattern for operations that need to ensure sensitive data is cleared regardless of success or failure.
* `SecureCompare`: For constant-time comparison of data.
* **Memory Barriers (`barrier`)**: Utilities for inserting compiler and memory fences. Fences alone do not establish constant-time execution or secure erasure.
* **Secure Allocation (`alloc`)**: (Requires `alloc` feature) Placeholder utilities for secure memory allocation and deallocation, aiming for future integration with platform-specific mechanisms like `mlock`.
2. **Mathematical Utilities (`math_common.rs`)**:
Provides common mathematical functions frequently used in cryptographic algorithms:
* `mod_exp(base, exp, modulus)`: Modular exponentiation.
* `gcd(a, b)`: Greatest Common Divisor.
* `mod_inv(a, modulus)`: Modular multiplicative inverse using the Extended Euclidean Algorithm.
* `mod_add`, `mod_sub`, `mod_mul`: Modular arithmetic operations.
3. **Elliptic Curve Utilities (`ec_common.rs`)**:
Defines basic structures for elliptic curve cryptography:
* `Point { x, y, z }`: Represents a point on an elliptic curve, supporting affine (z=None) and projective coordinates.
* `CurveParams`: Holds parameters for a curve in short Weierstrass form (a, b, p, order, cofactor, generator).
4. **NTRU Utilities (`ntru_common.rs`)**:
Currently a placeholder for common operations related to NTRU-based cryptography.
5. **McEliece Utilities (`mceliece_common.rs`)**:
Currently a placeholder for common operations related to McEliece-based cryptography.
## Purpose and Usage
The `common` crate is a foundational library within dcrypt. Its wrappers reduce
data-remanence risk for current owned allocations, but cannot erase caller,
compiler/register, or already-freed historical copies and do not provide locked
memory.
- It promotes code reuse for essential security patterns (like zeroization and constant-time comparison).
- It provides a centralized place for low-level utilities that don't fit into the `api` or `internal` crates but are needed by multiple algorithm implementations.
- Higher-level crates like `algorithms`, `symmetric`, `kem`, and `sign` depend on `common` for these shared functionalities.
For instance, a cryptographic algorithm implementation in `dcrypt-algorithms` might use `SecretBuffer` to store its round keys, `EphemeralSecret` to manage temporary sensitive state during computation, and `barrier` functions to ensure correct execution order for side-channel resistance. Mathematical utilities might be used in RSA or Diffie-Hellman implementations.
Centralizing these elements makes their behavior easier to review; it does not
constitute a blanket security guarantee for their consumers.