Fix various inconsistencies in OU implementation

Cargo.toml

@@ -1,28 +1,35 @@
 [package]
 name = "okuchi"
 version = "0.1.0"
-edition = "2024"
+edition = "2021"
 authors = ["Nelson Dominguez <ekkolon@proton.me>"]
 description = "Okamoto-Uchiyama Cryptosystem Implementation"
 license = "MIT OR Apache-2.0"
 readme = "README.md"
 
-
 [dependencies]
-num-bigint-dig = { version = "0.8", features = ["zeroize", "prime", "rand", "u64_digit"] }
+num-bigint-dig = { version = "0.8", features = [
+    "zeroize",
+    "prime",
+    "rand",
+    "u64_digit",
+] }
 num-traits = "0.2"
+num-integer = "0.1"
 rand = "0.8"
-zeroize = { version = "1.6", features = ["derive"] }
-thiserror = "2.0"
+zeroize = { version = "1.8", features = ["derive"] }
+thiserror = "2"
+# Constant-time modular arithmetic for the decryption hot path (SECURITY-2).
+# BoxedUint provides heap-allocated variable-width integers with CT guarantees.
+crypto-bigint = { version = "0.7", features = ["alloc"] }
 
 [dev-dependencies]
-criterion = "0.7"
+criterion = "0.5"
 
 [[bench]]
 name = "okuchi"
 harness = false
 
-
 [profile.release]
 opt-level = 3
 lto = true

README.md

@@ -1,53 +1,99 @@
 # Okuchi
 
-A pure Rust implementation of the **Okamoto–Uchiyama** cryptosystem - a probabilistic public-key scheme whose security relies on the hardness of factoring and discrete logarithms modulo a composite number.
+A pure-Rust implementation of the **Okamoto-Uchiyama (OU)** cryptosystem: a
+probabilistic public-key encryption scheme with additive homomorphism, whose
+security relies on the hardness of factoring `n = p²q` and computing discrete
+logarithms modulo `p²`.
 
 **Okuchi** is a portmanteau of **Ok**amoto and **Uchi**yama.
 
+---
+
 ## ⚠️ Important Notice
 
-The project is evolving and should be treated as a **work in progress**.
-Breaking changes, redesigns, or API removals may occur without notice.
+This implementation is **experimental**, **incomplete**, and **not audited** by
+any external security professionals. It may contain defects, conceptual
+mistakes, side-channel vulnerabilities, insecure parameter choices, or other
+issues that could compromise confidentiality, integrity, or availability of
+data.
+
+The project is a **work in progress**. Breaking changes, API removals, or
+redesigns may occur without notice.
 
-This implementation is (still) **experimental**, **incomplete**, and **not audited** by any external security professionals.
-It may contain defects, conceptual mistakes, side-channel vulnerabilities, insecure parameter choices, or other issues that could compromise confidentiality, integrity, or availability of data.
+**Do not use Okuchi in production systems, high-risk environments, or anywhere
+security or correctness is critical.**
 
-**Do not use Okuchi in production systems, high-risk environments, or anywhere security or correctness is critical.**
+If you choose to use this code despite these warnings, you do so entirely at
+your own risk. No guarantees, explicit or implied, are made regarding
+correctness, security, or fitness for any purpose. The author(s) assume no
+liability for any damages or consequences resulting from use or misuse of this
+software.
 
-If you choose to use this code despite these warnings, **you do so entirely at your own risk**. No guarantees - explicit or implied - are made regarding performance, correctness, security, or fitness for any purpose.
-The author(s) **assume no liability** for any damages, losses, or consequences resulting from the use, misuse, or inability to use this software.
+---
 
 ## Goals
 
-- Provide a correct, readable and safe Rust implementation of the **OU** cryptosystem
+- Provide a correct, readable, and safe Rust implementation of the OU
+  cryptosystem
 - Serve as a reference for learning and experimentation
-- Maintain minimal dependencies and clear internal structure
+- Maintain minimal dependencies and a clear internal structure
+
+This project does **not** aim to be a hardened or production-quality
+cryptographic library.
+
+---
+
+## Features
+
+- **Probabilistic encryption**: two encryptions of the same plaintext produce
+  distinct ciphertexts
+- **Additive homomorphism**: `E(m1) * E(m2) mod n` decrypts to
+  `(m1 + m2) mod p`, without decrypting either operand
+- **Stream API**: encrypt and decrypt arbitrary-length byte sequences via
+  automatic block splitting and reassembly
+- **Validated plaintext type**: [`Plaintext`] enforces the OU plaintext bound
+  at construction and provides checked addition for safe homomorphic
+  accumulation
+- **Zeroize on drop**: secret key material (`p`, `q`, derived constants) is
+  zeroed when the key is dropped
 
-This project **does not** aim to be a hardened or production-quality cryptographic library.
+---
+
+## Security Notes
+
+- The minimum enforced key size is **512 bits** (testing only). Use **2048
+  bits or larger** for any non-trivial use.
+- The modular exponentiation `c^(p-1) mod p²` in decryption is routed through
+  `crypto-bigint` Montgomery form for constant-time guarantees. All other
+  big-integer operations (`num-bigint-dig`) are **variable-time** and may leak
+  information about secret values through timing.
+- No formal audit has been performed. Do not deploy in adversarial environments.
+
+---
 
 ## Usage
 
-As mentioned above, until the library matures and receives proper review, usage should be limited to:
+Intended use cases:
 
-- academic experiments
-- prototyping
-- security research
-- code reading and learning
+- Academic experiments
+- Prototyping
+- Security research
+- Code reading and learning
 
 **Production use is strongly discouraged.**
 
-### Example
+### Encrypt and Decrypt
 
-```rs
+```rust
 use okuchi::{KeyPair, Okuchi};
 
-let keypair = KeyPair::new(2048).expect("key generation failed");
-let pub_key = keypair.pub_key();
+let keypair  = KeyPair::new(2048).expect("key generation failed");
+let pub_key  = keypair.pub_key();
 let priv_key = keypair.priv_key();
 
 let message = "hello world 🌍";
 
-// Encrypt (stream API)
+// Encrypt arbitrary-length data via the stream API
 let packed = Okuchi::encrypt_stream(pub_key, message).unwrap();
 
 // Decrypt
@@ -56,7 +102,3 @@ let decrypted = String::from_utf8(decrypted_bytes).unwrap();
 
 assert_eq!(message, decrypted);
 ```
-
-## References
-
-- Okamoto, T., Uchiyama, S. (1998). _A New Public-Key Cryptosystem as Secure as Factoring._