{"id":25254601,"url":"https://github.com/tn3w/cryptolib","last_synced_at":"2025-04-05T23:27:47.464Z","repository":{"id":273219696,"uuid":"919026460","full_name":"tn3w/cryptolib","owner":"tn3w","description":"A secure high-level implementation of cryptographic primitives with post-quantum support","archived":false,"fork":false,"pushed_at":"2025-02-02T12:25:39.000Z","size":46,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-12T05:45:29.605Z","etag":null,"topics":["aes","argon2","argon2id","crypto","cryptography","dilithium","kyber","pbkdf2","post-quantum","post-quantum-cryptography","rsa","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tn3w.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-19T14:22:52.000Z","updated_at":"2025-02-02T12:25:43.000Z","dependencies_parsed_at":"2025-01-19T15:28:04.226Z","dependency_job_id":"55067475-aa98-46ac-9158-a697e7aea222","html_url":"https://github.com/tn3w/cryptolib","commit_stats":null,"previous_names":["tn3w/cryptolib"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tn3w%2Fcryptolib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tn3w%2Fcryptolib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tn3w%2Fcryptolib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tn3w%2Fcryptolib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tn3w","download_url":"https://codeload.github.com/tn3w/cryptolib/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247415785,"owners_count":20935383,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aes","argon2","argon2id","crypto","cryptography","dilithium","kyber","pbkdf2","post-quantum","post-quantum-cryptography","rsa","rust"],"created_at":"2025-02-12T05:39:10.687Z","updated_at":"2025-04-05T23:27:47.448Z","avatar_url":"https://github.com/tn3w.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CryptoLib\n\n\u003e ⚠️ **SECURITY NOTICE**\n\u003e\n\u003e While this library implements secure cryptographic primitives following OWASP recommendations and best practices, it has **NOT YET** been thoroughly tested or audited by security professionals. The implementations use secure mechanics and follow cryptographic standards, but may contain undiscovered vulnerabilities.\n\u003e\n\u003e Security researchers are encouraged to test and analyze this software. If you discover any vulnerabilities or security issues, please report them through the [GitHub Issues](https://github.com/tn3w/cryptolib/issues).\n\nA secure Rust implementation of cryptographic primitives following OWASP security recommendations and best practices. This library provides high-level implementations of AES, Argon2id, PBKDF2, RSA, and post-quantum cryptography (Kyber and Dilithium) with extensive security measures.\n\n## Why\n\nThis library provides ready-to-use, secure implementations of common cryptographic primitives that you can directly copy and paste into your projects.\n\nInstead of implementing these cryptographic primitives from scratch (which can be error-prone and risky), you can use these pre-made implementations as building blocks for your secure applications. This saves development time while ensuring proper security measures are in place.\n\n## Security Implementation Recommendations\n\nWhen choosing between the provided implementations, consider these important security recommendations:\n\n### Post-Quantum vs Traditional Cryptography\n- **Prefer Kyber over RSA** for encryption: Due to \"Store Now, Decrypt Later\" attacks, all current RSA-encrypted communications can be recorded and decrypted once quantum computers become available. Kyber provides quantum-resistant encryption that protects against future quantum computer attacks.\n- **Choose Dilithium over RSA** for digital signatures: Similar to encryption, RSA signatures are vulnerable to quantum computing attacks. Dilithium provides quantum-resistant signatures that will remain secure in the post-quantum era.\n\n### Password Hashing\n- **Use Argon2id instead of PBKDF2** for password hashing: While both implementations are provided for compatibility, Argon2id is:\n  - More secure against both GPU and ASIC attacks due to its memory-hard design\n  - Faster than PBKDF2 while providing better security\n  - The winner of the Password Hashing Competition and recommended by cryptography experts\n  - More resistant to side-channel attacks through its hybrid design\n\n## Security Features\n\nAll implementations share these security measures (when applicable):\n- Memory protection using `mlock` and `madvise(MADV_DONTDUMP)`\n- Secure memory wiping with volatile writes and memory fences\n- Constant-time operations to prevent timing attacks\n- Input validation and sanitization\n- Comprehensive error handling without information leakage\n- Protected key material in memory\n- Side-channel attack mitigations\n- Automatic cleanup using Drop trait\n\n## Implementations\n\n### Kyber Post-Quantum Key Encapsulation (KEM)\nA lattice-based post-quantum key encapsulation mechanism.\n\n**Parameters:**\n- Kyber1024 security level (NIST Level 5 - highest security)\n- Nonce size: 32 bytes (256 bits)\n- Salt length: 32 bytes (256 bits)\n- AES nonce length: 12 bytes (96 bits)\n- PBKDF2 iterations: 100,000\n\n**Security Features:**\n- Post-quantum secure against quantum computer attacks (equivalent to AES-256 security level)\n- Hybrid encryption with AES-256-GCM\n- Secure key derivation using PBKDF2\n- Protected shared secrets and key material\n- Nonce generation for each operation\n\n### Dilithium Post-Quantum Digital Signatures\nA lattice-based post-quantum digital signature scheme.\n\n**Parameters:**\n- Dilithium5 security level (NIST Level 5 - highest security)\n- Equivalent to AES-256 security level\n- Signature size: 4595 bytes\n- Public key size: 2592 bytes\n- Private key size: 4864 bytes\n- Nonce size: 32 bytes (256 bits)\n\n**Security Features:**\n- Post-quantum secure digital signatures (highest security level)\n- Protected private key material with memory locking\n- Nonce generation for each signature\n- Memory protection for sensitive data\n- Constant-time operations to prevent timing attacks\n- Automatic cleanup of sensitive data\n\n### Argon2id Password Hashing\nThe primary recommended password hashing algorithm.\n\n**Parameters (OWASP Recommended):**\n- Memory: 12 MiB (12,288 KiB)\n- Iterations: 3\n- Parallelism: 1\n- Salt length: 32 bytes (256 bits)\n- Hash length: 32 bytes (256 bits)\n\n**Security Features:**\n- Memory-hard algorithm resistant to GPU/ASIC attacks\n- Hybrid approach combining Argon2d and Argon2i\n- Protection against both timing and tradeoff attacks\n- Unique salt generation for each hash\n- Password length validation (8-1024 bytes)\n\n### AES-256-GCM Encryption\n\n**Parameters (OWASP Recommended):**\n- Key size: 256 bits\n- GCM mode for authenticated encryption\n- Nonce size: 96 bits\n- Tag size: 128 bits\n- Salt size: 256 bits\n- PBKDF2 iterations for key derivation: 100,000\n\n**Security Features:**\n- Authenticated encryption with associated data (AEAD)\n- Secure key derivation using PBKDF2-HMAC-SHA256\n- Random nonce generation for each encryption\n- Integrity verification with authentication tags\n- Secret length validation (16-1024 bytes)\n\n### PBKDF2 Password Hashing\nA legacy-compatible password hashing implementation.\n\n**Parameters (OWASP Recommended):**\n- Iterations: 600,000\n- Salt length: 32 bytes (256 bits)\n- Hash length: 32 bytes (256 bits)\n- HMAC-SHA256 as PRF\n\n**Security Features:**\n- High iteration count to increase computational cost\n- Unique salt generation for each hash\n- Password length validation (8-1024 bytes)\n- Constant-time comparison for verification\n\n### RSA Encryption and Signing\n\n**Parameters:**\n- Key size: 2048 bits (minimum)\n- Public exponent: 65537\n- Padding: OAEP with SHA-256 for encryption\n- PSS padding with SHA-256 for signatures\n\n**Security Features:**\n- Secure key generation with proper prime testing\n- OAEP padding for encryption security\n- PSS padding for signature security\n- Key zeroization after use\n- Protected key material in memory\n\n## Usage Examples\n\n### Kyber Post-Quantum Encryption\n```rust\n// Create a new instance and generate key pair\nlet mut kyber = SecureKyber::new();\nlet (private_key, public_key) = kyber.generate_keypair()?;\n\n// Create instances from exported keys\n// For encryption only (public key)\nlet encryptor = SecureKyber::from_public_key(\u0026public_key)?;\n\n// For decryption (private key)\nlet mut decryptor = SecureKyber::new();\ndecryptor.set_private_key(\u0026private_key)?;\n\n// Encrypt data using public key instance\nlet data = b\"sensitive data\";\nlet encrypted = encryptor.encrypt(data)?;\n\n// Decrypt data using private key instance\nlet decrypted = decryptor.decrypt(\u0026encrypted)?;\nassert_eq!(data, \u0026decrypted[..]);\n\n// Key encapsulation with separate instances\nlet (ciphertext, shared_secret1) = encryptor.encapsulate()?;\nlet shared_secret2 = decryptor.decapsulate(\u0026ciphertext)?;\nassert_eq!(shared_secret1, shared_secret2);\n\n// Clear sensitive data when done\ndecryptor.clear_sensitive_data();\n```\n\n### Dilithium Post-Quantum Signatures\n```rust\nlet mut dilithium = SecureDilithium::new();\n\n// Generate new key pair\nlet (private_key, public_key) = dilithium.generate_keypair()?;\n\n// Export keys for storage\n// The keys are returned as byte arrays that can be safely stored\nlet exported_private_key = private_key.clone();\nlet exported_public_key = public_key.clone();\n\n// Create a new instance with existing private key\nlet mut signer = SecureDilithium::new();\nsigner.set_private_key(\u0026exported_private_key)?;\n\n// Create a new instance with only public key for verification\nlet mut verifier = SecureDilithium::new();\nverifier.set_public_key(\u0026exported_public_key)?;\n\n// Sign data with private key instance\nlet data = b\"message to sign\";\nlet signature = signer.sign(data)?;\n\n// Verify signature with public key instance\nlet is_valid = verifier.verify_signature(data, \u0026signature)?;\nassert!(is_valid);\n\n// Clear sensitive data when done\nsigner.clear_sensitive_data();\n```\n\n### Argon2id Password Hashing\n```rust\n// Create a new hasher instance\nlet hasher = SecureArgon2id::new();\nlet password = b\"my_secure_password\";\n\n// Hash password with unique salt\nlet hash = hasher.hash_password(password)?;\n\n// Verify password against stored hash\nlet is_valid = hasher.verify_password(password, \u0026hash)?;\n```\n\n### AES-256-GCM Encryption\n```rust\n// Create a new encryptor with secret key\nlet encryptor = SecureAES::new(secret)?;\nlet data = b\"sensitive data\";\n\n// Encrypt data with random salt and nonce\nlet encrypted = encryptor.encrypt(data)?;\n\n// Decrypt data and verify integrity\nlet decrypted = encryptor.decrypt(\u0026encrypted)?;\n```\n\n### PBKDF2 Password Hashing\n```rust\n// Create a new hasher instance\nlet hasher = SecurePbkdf2::new();\nlet password = b\"my_secure_password\";\n\n// Hash password with unique salt\nlet hash = hasher.hash_password(password)?;\n\n// Verify password against stored hash\nlet is_valid = hasher.verify_password(password, \u0026hash)?;\n```\n\n### RSA Encryption and Signing\n```rust\n// Create a new instance and generate key pair\nlet mut rsa = SecureRSA::new();\nlet (private_key, public_key) = rsa.generate_keypair()?;\n\n// Encrypt data using public key\nlet data = b\"sensitive data\";\nlet encrypted = rsa.encrypt(data)?;\n\n// Decrypt data using private key\nlet decrypted = rsa.decrypt(\u0026encrypted)?;\n\n// Sign data using private key\nlet signature = rsa.sign(data)?;\n\n// Verify signature using public key\nlet is_valid = rsa.verify_signature(data, \u0026signature)?;\n```\n\n## Running Examples\n\nThe library includes several example programs demonstrating the usage of each cryptographic primitive. You can run them using cargo:\n\n```bash\n# Run AES-256-GCM encryption example\ncargo run --example aes --release\n\n# Run RSA encryption and signing example\ncargo run --example rsa --release\n\n# Run Kyber post-quantum encryption example\ncargo run --example kyber --release\n\n# Run Dilithium post-quantum signature example\ncargo run --example dilithium --release\n\n# Run PBKDF2 password hashing example\ncargo run --example pbkdf2 --release\n\n# Run Argon2id password hashing example\ncargo run --example argon2id --release\n```\n\n## Testing\n\nEach implementation includes comprehensive tests.\n\n## Dependencies\n\n- `argon2`: Password hashing\n- `ring`: Cryptographic primitives\n- `rand`: Secure random number generation\n- `rsa`: RSA implementation\n- `pbkdf2`: Key derivation\n- `constant_time_eq`: Constant-time comparison\n- `libc`: Memory protection\n- `pqcrypto-kyber`: Kyber post-quantum KEM\n- `pqcrypto-dilithium`: Dilithium post-quantum signatures\n- `pqcrypto-traits`: Common traits for post-quantum cryptography\n\n## License\n\nCopyright 2025, TN3W\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\n## Security References\n\nFor detailed understanding of the implemented algorithms and their security considerations:\n\n### Post-Quantum Cryptography\n- [NIST Post-Quantum Cryptography Standardization](https://csrc.nist.gov/projects/post-quantum-cryptography) - Official NIST documentation on post-quantum cryptography standards\n- [Kyber: Algorithm Specifications and Supporting Documentation](https://pq-crystals.org/kyber/data/kyber-specification-round3-20210804.pdf) - Detailed technical specification of the Kyber algorithm\n- [Dilithium: Algorithm Specifications and Supporting Documentation](https://pq-crystals.org/dilithium/data/dilithium-specification-round3-20210208.pdf) - Complete specification of the Dilithium signature scheme\n\n### Password Hashing\n- [Argon2: Memory-Hard Function for Password Hashing and Proof-of-Work Applications](https://password-hashing.net/argon2-specs.pdf) - Official Argon2 specification paper\n- [OWASP Password Storage Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html) - Best practices for secure password storage\n- [Password Hashing Competition](https://password-hashing.net/) - Details on why Argon2 was selected as the winner\n\n### Symmetric Encryption\n- [NIST AES Resources](https://csrc.nist.gov/projects/cryptographic-standards-and-guidelines/archived-crypto-projects/aes-development) - Comprehensive documentation on AES\n- [NIST SP 800-38D: Galois/Counter Mode](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf) - Detailed specification of GCM mode of operation\n\n### Key Derivation and RSA\n- [NIST SP 800-132: PBKDF Recommendation](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf) - Guidelines for password-based key derivation\n- [NIST SP 800-56B Rev. 2: RSA-Based Key-Establishment](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Br2.pdf) - RSA key establishment schemes\n- [RFC 8017 - PKCS #1 v2.2: RSA Cryptography Specifications](https://datatracker.ietf.org/doc/html/rfc8017) - Standard RSA implementations and padding schemes\n\n### Side-Channel Attack Prevention\n- [Constant-Time Cryptography Guidelines](https://github.com/veorq/cryptocoding) - Best practices for implementing constant-time operations\n- [Side-Channel Attacks on Post-Quantum Cryptography](https://eprint.iacr.org/2016/461.pdf) - Analysis of side-channel considerations in post-quantum algorithms\n\n### Memory Protection\n- [Linux mlock Manual](https://man7.org/linux/man-pages/man2/mlock.2.html) - Documentation for secure memory locking\n- [OWASP Cryptographic Storage Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cryptographic_Storage_Cheat_Sheet.html) - Best practices for protecting cryptographic material \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftn3w%2Fcryptolib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftn3w%2Fcryptolib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftn3w%2Fcryptolib/lists"}