{"id":30110985,"url":"https://github.com/ericmann/xchacha20-demo","last_synced_at":"2025-08-10T05:06:14.463Z","repository":{"id":306359047,"uuid":"1025912034","full_name":"ericmann/xchacha20-demo","owner":"ericmann","description":"XChaCha20 (and Poly1305) Demo in PHP","archived":false,"fork":false,"pushed_at":"2025-07-26T02:17:59.000Z","size":19,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-09T23:50:53.312Z","etag":null,"topics":["demo","php","poly1305","xchacha20"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ericmann.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,"zenodo":null}},"created_at":"2025-07-25T02:43:31.000Z","updated_at":"2025-07-26T02:19:22.000Z","dependencies_parsed_at":"2025-07-25T07:47:37.088Z","dependency_job_id":"c54981f1-6dd8-48c1-8758-25cc01fff9cb","html_url":"https://github.com/ericmann/xchacha20-demo","commit_stats":null,"previous_names":["ericmann/xchacha20-demo"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ericmann/xchacha20-demo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericmann%2Fxchacha20-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericmann%2Fxchacha20-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericmann%2Fxchacha20-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericmann%2Fxchacha20-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ericmann","download_url":"https://codeload.github.com/ericmann/xchacha20-demo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericmann%2Fxchacha20-demo/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269677801,"owners_count":24457876,"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","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["demo","php","poly1305","xchacha20"],"created_at":"2025-08-10T05:06:13.825Z","updated_at":"2025-08-10T05:06:14.447Z","avatar_url":"https://github.com/ericmann.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# XChaCha20 Stream Cipher and Poly1305 MAC Implementation\n\nThis directory contains educational implementations of the XChaCha20 stream cipher and Poly1305 message authentication code in pure PHP, designed to demonstrate the inner workings of symmetric cryptography.\n\n## Overview\n\n**XChaCha20** is a modern stream cipher that extends ChaCha20 with a larger nonce size (192 bits vs 96 bits) for better flexibility.\n\n**Poly1305** is a fast, secure message authentication code that operates on 16-byte blocks and produces a 16-byte tag. It's commonly used with ChaCha20 in the ChaCha20-Poly1305 AEAD construction.\n\nThese implementations are for educational purposes only - for production use, always use established libraries like Libsodium.\n\n## Requirements\n\n- PHP 8.3 or higher\n- Composer\n- Libsodium extension (for the demo script and compatibility tests)\n\n## Installation\n\n1. **Clone the repository:**\n   ```bash\n   git clone https://github.com/ericmann/xchacha20-demo.git \n   cd xchacha20-demo\n   ```\n\n2. **Install dependencies:**\n   ```bash\n   composer install\n   ```\n\n## Usage\n\n### XChaCha20 Basic Usage\n\n```php\n\u003c?php\nrequire_once 'vendor/autoload.php';\n\nuse XChaChaDemo\\XChaCha20;\n\n// Generate a random key and nonce\n$key = random_bytes(32);   // 256-bit key\n$nonce = random_bytes(24); // 192-bit nonce\n\n// Create XChaCha20 instance\n$xchacha20 = new XChaCha20($key, $nonce);\n\n// Encrypt a message\n$message = \"Hello, world!\";\n$ciphertext = $xchacha20-\u003eencrypt($message);\n\n// Decrypt the message\n$decrypted = $xchacha20-\u003edecrypt($ciphertext);\necho $decrypted; // \"Hello, world!\"\n```\n\n### Poly1305 Basic Usage\n\n```php\n\u003c?php\nrequire_once 'vendor/autoload.php';\n\nuse XChaChaDemo\\Poly1305;\n\n// Generate a random key\n$key = random_bytes(32);   // 256-bit key\n\n// Create Poly1305 instance\n$poly1305 = new Poly1305($key);\n\n// Compute MAC for a message\n$message = \"Hello, world!\";\n$tag = $poly1305-\u003ecompute($message);\n\n// Verify the MAC\n$is_valid = $poly1305-\u003everify($message, $tag);\necho $is_valid ? \"MAC is valid\" : \"MAC is invalid\";\n```\n\n### Running the Demos\n\n**XChaCha20 Demo:**\n```bash\nphp xchacha_stream_demo.php\n```\n\n**Poly1305 Demo:**\n```bash\nphp poly1305_demo.php\n```\n\nThe XChaCha20 demo script:\n1. Generates a deterministic keystream using the userland implementation\n2. Generates the same keystream using Libsodium's `sodium_crypto_stream_xchacha20`\n3. Encrypts a message using the userland stream + XOR\n4. Decrypts the ciphertext using Libsodium's `sodium_crypto_stream_xchacha20_xor`\n\nThe Poly1305 demo script:\n1. Demonstrates MAC computation for various message types\n2. Shows verification of valid and tampered messages\n3. Tests with different keys and binary data\n\nThese demonstrate that the userland implementations are compatible with production libraries.\n\n## Testing\n\n### Run Tests\n\n```bash\ncomposer test\n```\n\n### Generate Code Coverage (Text)\n\n```bash\ncomposer coverage\n```\n\n*Note: Requires Xdebug or pcov to be enabled for coverage reporting.*\n\n### Generate Code Coverage (HTML)\n\n```bash\ncomposer coverage-html\n```\n\nThen open `html/index.html` in your browser.\n\n## Disclaimer \u0026 Simplifications\n\nThis code is an extraction and evolution from a series of articles on cryptography for PHP[Architect] magazine and is intended for **educational purposes only**.\n\n**DO NOT USE THIS CODE IN PRODUCTION. IT IS NOT SECURE.**\n\n### Project Goals\n\n* Illustrate the core concepts of stream cipher operation using XChaCha20 as an example.\n* Demonstrate message authentication code operation using Poly1305 as an example.\n* Demonstrate how pseudorandom keystreams are generated from a key and nonce.\n* Show how XOR operations enable encryption and decryption with the same operation.\n* Provide a tangible, albeit non-production-ready, codebase to accompany the PHP[Architect] articles.\n* Demonstrate compatibility with production libraries like Libsodium.\n\n### Features Demonstrated\n\n* **Stream Cipher Basics**: How XChaCha20 generates deterministic pseudorandom keystreams.\n* **Message Authentication**: How Poly1305 provides authenticity and integrity for messages.\n* **XOR Encryption**: Simple bitwise operations for encryption and decryption.\n* **Nonce Management**: The importance of unique nonces for security.\n* **Cross-Library Compatibility**: Verification against Libsodium's implementation.\n* **Educational Documentation**: Comprehensive comments explaining cryptographic concepts.\n\n### Key Simplifications for Educational Purposes\n\n* **No Authenticated Encryption**: The XChaCha20 implementation provides only confidentiality, not authenticity. Real-world applications require AEAD constructions like XChaCha20-Poly1305.\n* **Basic Error Handling**: Simplified validation focused on educational clarity rather than production robustness.\n* **Educational Comments**: Extensive inline documentation that would be excessive in production code.\n* **Deterministic Test Values**: Uses predictable test data for reproducible demonstrations.\n* **No Performance Optimizations**: Prioritizes readability over speed.\n\nThis project aims to make the _flow_ and _mathematical components_ of XChaCha20 and Poly1305 tangible. It is **NOT a secure implementation** and should not be used as a basis for production systems.\n\nRefer to the original PHP[Architect] magazine articles and the \"Further Reading\" sections within them for more details on secure, production-grade cryptographic protocols and implementations.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericmann%2Fxchacha20-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fericmann%2Fxchacha20-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericmann%2Fxchacha20-demo/lists"}