dcrypt Internal Utilities (internal)

The internal crate provides low-level utility functions and modules that are shared across various dcrypt crates but are not intended to be part of the public API. These utilities typically deal with implementation details crucial for security or correctness, such as constant-time operations or byte-order conversions.

Core Components

1. Constant-Time Operations (constant_time.rs):

   • Purpose: Provides functions to perform operations in a way that their execution time does not depend on the secret values being processed. This is crucial for mitigating timing side-channel attacks.
   • Key Functions:
     • ct_eq(a: AsRef<[u8]>, b: AsRef<[u8]>) -> bool: Constant-time equality comparison for byte slices, leveraging the subtle crate.
     • ct_select<T: ConditionallySelectable>(a: T, b: T, condition: bool) -> T: Constant-time conditional selection.
     • ct_assign(dst: &mut [u8], src: &[u8], condition: bool): Constant-time conditional assignment for byte slices.
     • ct_eq_choice(a, b) -> subtle::Choice: Constant-time equality returning a subtle::Choice.
     • ct_and, ct_or, ct_xor: Constant-time bitwise operations on fixed-size byte arrays.
     • ct_op: Generic constant-time conditional operation on byte arrays.
     • ct_mask(condition: bool) -> u8: Generates an all-1s or all-0s mask based on a condition.
   • Dependencies: Relies heavily on the subtle crate for its underlying constant-time primitives.

2. Endianness Utilities (endian.rs):

   • Purpose: Provides helper functions for converting between native byte order and little-endian or big-endian byte orders for u32 and u64 types.
   • Key Functions:
     • u32_from_le_bytes, u32_from_be_bytes
     • u32_to_le_bytes, u32_to_be_bytes
     • u64_from_le_bytes, u64_from_be_bytes
     • u64_to_le_bytes, u64_to_be_bytes
   • Note: These often wrap standard library or byteorder crate functionalities but provide a centralized internal API.

3. Secure Memory Zeroing (zeroing.rs):

   • Purpose: Offers utilities for securely clearing sensitive data from memory.
   • Key Functions:
     • secure_zero(data: &mut [u8]): Uses data.zeroize() from the zeroize crate.
     • secure_clone_and_zero(data: &mut [u8]) -> Vec<u8>: Clones a slice and then zeroes the original.
   • ZeroGuard<'a> Struct: An RAII guard that ensures a mutable byte slice is zeroed when the guard goes out of scope.

4. SIMD Utilities (simd module in lib.rs) (conditional on simd feature):

   • Purpose: Placeholder for SIMD (Single Instruction, Multiple Data) related utility functions, such as checking for SIMD availability.
   • is_available() -> bool: Checks for sse2 target feature as an example.

Intended Use

The internal crate is strictly for use by other dcrypt crates (e.g., algorithms, common). Its contents are considered implementation details and are subject to change without notice, as they are not governed by the public API stability promises of the dcrypt library.

By centralizing these low-level, security-critical utilities, dcrypt aims to:

• Ensure consistent application of security best practices (like constant-time operations).
• Reduce code duplication for common internal tasks.
• Make it easier to audit and verify these critical pieces of code.