spatial_hasher/lib.rs
1#![deny(missing_docs)]
2//! # Spatial Hasher
3//!
4//! A Rust library for deterministic encryption and decryption using 3D spatial parameters with secure authenticated encryption.
5//!
6//! ## Overview
7//!
8//! `spatial_hasher` provides a way to encrypt and decrypt data using a deterministic algorithm based on 3D spatial parameters. It utilizes a combination of a 3D point, a rotation axis, the number of iterations, and a strength parameter to derive a cryptographic key using SHA-256 hashing. This key is then used with the **ChaCha20-Poly1305 authenticated encryption algorithm** to ensure secure encryption and decryption.
9//!
10//! ## Features
11//!
12//! - **Secure Authenticated Encryption**: Uses the ChaCha20-Poly1305 algorithm for strong encryption and integrity protection.
13//! - **Deterministic Key Derivation**: Generates a consistent key from spatial parameters, allowing for reproducible encryption and decryption.
14//! - **Customizable Parameters**: Adjust the starting point, rotation axis, iterations, and strength to modify the encryption.
15//! - **Simple API**: Easy to integrate into other Rust projects.
16//! - **Serialization Support**: Structures can be serialized and deserialized using `serde`.
17//! - **Unit Tests Included**: Verify functionality with built-in tests.
18//!
19//! ## Nomenclature
20//!
21//! - **Point3D**: Represents a point in 3D space.
22//! - **RotationAxis**: Represents a rotation axis in 3D space.
23//! - **Spha256**: The core struct that provides encryption and decryption methods.
24//!
25//! ## Architecture
26//!
27//! The `Spha256` struct is the core of this library. It uses the spatial parameters to generate a cryptographic key and perform encryption and decryption using the ChaCha20-Poly1305 algorithm.
28//! 
29//!
30//! ### **Key Derivation**
31//!
32//! The key is derived by hashing the spatial parameters using SHA-256:
33//!
34//! - Coordinates of the `Point3D` and `RotationAxis`.
35//! - The `iterations` and `strength` parameters.
36//!
37//! ### **Encryption Process**
38//!
39//! 1. **Key Generation**: Derive the key from spatial parameters.
40//! 2. **Nonce Generation**: Generate a unique nonce for each encryption.
41//! 3. **Data Encryption**: Encrypt data using ChaCha20-Poly1305 with the key and nonce.
42//!
43//! ### **Decryption Process**
44//!
45//! - Use the same key derived from the parameters.
46//! - Extract the nonce from the encrypted data.
47//! - Decrypt the data using ChaCha20-Poly1305.
48//!
49//! ## Usage
50//!
51//! ### **Creating a `Spha256` Instance**
52//!
53//! ```rust
54//! use spatial_hasher::{Point3D, RotationAxis, Spha256};
55//!
56//! let point = Point3D { x: 1.0, y: 2.0, z: 3.0 };
57//! let rotation_axis = RotationAxis { x: 0.0, y: 1.0, z: 0.0 };
58//! let iterations = 10;
59//! let strength = 0.1;
60//!
61//! let hasher = Spha256::new(point, rotation_axis, iterations, strength);
62//! ```
63//!
64//! ### **Encrypting Data**
65//!
66//! ```rust
67//! let data = b"Secret Message";
68//! let encrypted_data = hasher.encrypt(data);
69//! ```
70//!
71//! ### **Decrypting Data**
72//!
73//! ```rust
74//! let decrypted_data = hasher.decrypt(&encrypted_data).expect("Decryption failed");
75//! assert_eq!(data, &decrypted_data[..]);
76//! ```
77//!
78//! ## Modules
79//!
80//! - [`spatial_hasher`]: Contains the `Spha256` struct and related functionality.
81//!
82//! ## Structs
83//!
84//! - [`Point3D`]: Represents a point in 3D space.
85//! - [`RotationAxis`]: Represents a rotation axis in 3D space.
86//! - [`Spha256`]: Provides methods for encryption and decryption.
87//!
88//! ## Security Considerations
89//!
90//! The security of the encryption relies on the secrecy of the parameters used to derive the key. Ensure that the `Point3D`, `RotationAxis`, `iterations`, and `strength` parameters are kept confidential.
91//!
92//! ## Dependencies
93//!
94//! - `chacha20poly1305` for encryption
95//! - `serde` for serialization
96//! - `sha2` for SHA-256 hashing
97//! - `rand` for random number generation
98//!
99//! ## License
100//!
101//! This project is licensed under the MIT License.
102//!
103//! ---
104//!
105//! [spatial_hasher]: crate::spatial_hasher
106//! [Point3D]: crate::spatial_hasher::Point3D
107//! [RotationAxis]: crate::spatial_hasher::RotationAxis
108//! [Spha256]: crate::spatial_hasher::Spha256
109
110pub mod point3d;
111pub mod rotation_axis;
112pub mod spatial_hasher;
113
114pub use point3d::Point3D;
115pub use rotation_axis::RotationAxis;
116pub use spatial_hasher::Spha256;