{"id":19965256,"url":"https://github.com/johanns/sha3","last_synced_at":"2025-04-05T05:06:57.165Z","repository":{"id":4930677,"uuid":"6087336","full_name":"johanns/sha3","owner":"johanns","description":"SHA3 for Ruby: SHA-3 (FIPS 202), SHAKE128/SHAKE256, cSHAKE128/cSHAKE256, and KMAC (NIST SP 800-185), powered by XKCP","archived":false,"fork":false,"pushed_at":"2025-03-27T20:31:08.000Z","size":4001,"stargazers_count":37,"open_issues_count":0,"forks_count":6,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-27T20:47:03.521Z","etag":null,"topics":["cshake","cshake128","cshake256","keccak","kmac","kmac128","kmac256","ruby","sha3","shake128","shake256"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"collective/collective.tabr","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johanns.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","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":"2012-10-05T07:54:21.000Z","updated_at":"2025-03-27T20:27:40.000Z","dependencies_parsed_at":"2025-03-08T02:22:03.869Z","dependency_job_id":"45ae19f7-3d60-4bf4-bb6b-d7be8e1b3869","html_url":"https://github.com/johanns/sha3","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johanns%2Fsha3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johanns%2Fsha3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johanns%2Fsha3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johanns%2Fsha3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johanns","download_url":"https://codeload.github.com/johanns/sha3/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289428,"owners_count":20914464,"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":["cshake","cshake128","cshake256","keccak","kmac","kmac128","kmac256","ruby","sha3","shake128","shake256"],"created_at":"2024-11-13T02:27:58.656Z","updated_at":"2025-04-05T05:06:57.145Z","avatar_url":"https://github.com/johanns.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SHA3 for Ruby\n\n[![Gem Version](https://badge.fury.io/rb/sha3.svg)](https://badge.fury.io/rb/sha3) [![Ruby](https://github.com/johanns/sha3/actions/workflows/main.yml/badge.svg)](https://github.com/johanns/sha3/actions/workflows/main.yml)\n\nA high-performance native binding to the SHA3 (FIPS 202) cryptographic hashing algorithms, based on the [XKCP - eXtended Keccak Code Package](https://github.com/XKCP/XKCP).\n\nThis gem provides support for the standard SHA-3 fixed-length functions (224, 256, 384, and 512 bits), as well as the SHAKE128/SHAKE256 extendable-output functions (XOFs), cSHAKE128/cSHAKE256, and KMAC (Keccak Message Authentication Code) as specified in NIST SP 800-185.\n\n\u003e [!CAUTION]\n\u003e **Security Notice**: Do not use SHA-3 for hashing passwords. Instead, use a slow hashing function such as PBKDF2, Argon2, bcrypt, or scrypt.\n\n\u003e [!IMPORTANT]\n\u003e **Breaking Changes**: SHA3 version 2.0 introduces breaking changes in the API to support new features and functionality. Please review the changelog and ensure compatibility with your application. If you need the previous behavior, lock your Gemfile to version '~\u003e 1.0'.\n\n## Table of Contents\n\n- [Documentation](#documentation)\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [SHA-3 Fixed Hash Functions](#sha-3-fixed-hash-functions)\n  - [Alternate Class Syntax](#alternate-class-syntax)\n  - [Hashing a File](#hashing-a-file)\n  - [SHAKE128/256 Functions](#shake128256-functions)\n  - [cSHAKE128/256 Functions](#cshake128256-functions)\n  - [KMAC Functions](#kmac-functions)\n- [Development](#development)\n  - [Dependencies](#dependencies)\n  - [Testing](#testing)\n  - [Supported Ruby Versions](#supported-ruby-versions)\n- [Contributing](#contributing)\n- [Roadmap](#roadmap)\n- [License](#license)\n- [Credits](#credits)\n\n## Documentation\n\n- [API Documentation](https://docs.jsg.io/sha3/html/index.html)\n- [GitHub Repository](https://github.com/johanns/sha3#readme)\n- [Issue Tracker](https://github.com/johanns/sha3/issues)\n\n## Features\n\n- Full support for all SHA-3 variants (224, 256, 384, and 512 bits)\n- Support for SHAKE128 and SHAKE256 extendable-output functions (XOFs)\n- Support for cSHAKE128 and cSHAKE256 extendable-output functions (XOFs) with domain separation and personalization\n- Support for KMAC (Keccak Message Authentication Code)\n- Native C implementation for high performance\n- Simple, Ruby-friendly API that follows Ruby's standard Digest interface\n- Comprehensive test suite with official NIST test vectors\n- Thread-safe implementation\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'sha3', '~\u003e 2.2'\n```\n\nAnd then execute:\n\n```sh\nbundle install\n```\n\nOr install it yourself as:\n\n```sh\ngem install sha3\n```\n\n## Usage\n\n### SHA-3 Fixed Hash Functions\n\n```ruby\nrequire 'sha3'\n\n# Create a new digest instance\ndigest = SHA3::Digest.new(:sha3_224, 'Start here')\n\n# Add more data to be hashed\ndigest \u003c\u003c \"Compute Me\"\ndigest.update(\"Me too\")\n\n# Get the final hash value as a hex string\ndigest.hexdigest\n# =\u003e \"d6d38021d60857...\"\n\n# Or as a binary string\ndigest.digest\n```\n\nValid algorithm symbols are:\n\n- `:sha3_224` - SHA-3 224 bits\n- `:sha3_256` - SHA-3 256 bits\n- `:sha3_384` - SHA-3 384 bits\n- `:sha3_512` - SHA-3 512 bits\n- `:shake_128` - SHAKE128 extendable-output function\n- `:shake_256` - SHAKE256 extendable-output function\n\n### Alternate Class Syntax\n\nFor convenience, you can also use dedicated classes for each algorithm:\n\n```ruby\n# Available classes\nSHA3::Digest::SHA3_224.new([data])\nSHA3::Digest::SHA3_256.new([data])\nSHA3::Digest::SHA3_384.new([data])\nSHA3::Digest::SHA3_512.new([data])\nSHA3::Digest::SHAKE_128.new([data])\nSHA3::Digest::SHAKE_256.new([data])\n```\n\n```ruby\n# Example usage\ndigest = SHA3::Digest::SHA3_256.new('Start here')\n\ndigest \u003c\u003c \"Compute Me\"\ndigest.update(\"Me too\")\n\ndigest.hexdigest\n# =\u003e \"bedf0dd9a15b647...\"\n```\n\n### Hashing a File\n\n```ruby\n# Compute the hash value for a given file, and return the result as hex\nhash = SHA3::Digest::SHA3_256.file(\"my_file.bin\").hexdigest\n\n# Using SHAKE function to generate an arbitrary-length hash output\nshake = SHA3::Digest::SHAKE_128.file(\"my_file.bin\").hexdigest(320)\n\n# Calling SHA3::Digest.file(...) defaults to SHA3_256\nhash = SHA3::Digest.file(\"my_file.bin\").hexdigest\n# =\u003e \"a9801db49389339...\"\n```\n\n### SHAKE128/256 Functions\n\nSHAKE128 and SHAKE256 are extendable-output functions (XOFs) that allow you to \"squeeze\" an arbitrary number of bytes from the hash state:\n\n```ruby\n# Create a new SHAKE128 instance\nshake = SHA3::Digest::SHAKE_128.new\n\n# Add data to hash\nshake \u003c\u003c 'Squeeze this data...'\n\n# Squeeze 120 bytes (240 hex characters) from the hash state\nresult = shake.hex_squeeze(120)\n\n# Or get binary output\nbinary_result = shake.squeeze(1024)\n\n# You can call squeeze functions multiple times with arbitrary output lengths\nfirst_part = shake.squeeze(32)       # Get 32 bytes\nsecond_part = shake.squeeze(64)      # Get 64 bytes\nthird_part = shake.hex_squeeze(128)  # Get 128 bytes as hex\n```\n\n### cSHAKE128/256 Functions\n\ncSHAKE128 and cSHAKE256 are customizable versions of SHAKE128 and SHAKE256, allowing for domain separation and personalization through a customization string.\n\n```ruby\n# Create a new cSHAKE instance with a fixed output length\ncshake = SHA3::CSHAKE.new(:cshake_128, 32, name: 'my-app', customization: 'Email Signature')\n\n# Add data to hash\ncshake.update('Hello')\n# Or use the \u003c\u003c operator\ncshake \u003c\u003c 'Compute me...'\n\n# Get the final hash value as a hex string\ncshake.hexdigest\n# =\u003e \"d6d38021d60857...\"\n\n# Or as a binary string\ncshake.digest\n\n# Create a new cSHAKE instance for an arbitrarily-long (XOF) operation\ncshake = SHA3::CSHAKE.new(:cshake_256, 0, customization: 'Signature')\n\n# Add data to hash\ncshake.update('Beep Beep')\n\n# Squeeze 64-bytes of data from state\ncshake.squeeze(64)\n```\n\n### KMAC Functions\n\nKMAC (Keccak Message Authentication Code) is a message authentication code algorithm based on the SHAKE extendable-output functions:\n\n```ruby\nrequire 'sha3'\n\n# Create a new KMAC instance with a fixed output length\n# Parameters: algorithm, output_length (in bytes), key, [customization] optional\nkmac = SHA3::KMAC.new(:kmac_128, 32, \"my secret key\", \"app-specific customization\")\n\n# Add data to be authenticated (update can be called multiple times)\nkmac.update(\"Authenticate this message\")\n# or use the \u003c\u003c operator\nkmac \u003c\u003c \"And this too\"\n\n# Get the result as a hex string\nresult = kmac.hexdigest\n# =\u003e \"a8982c...\"\n\n# Or as binary\nbinary_result = kmac.digest\n\n# Create a new KMAC instance with an arbitrary-length (XOF) operation\nkmac = SHA3::KMAC.new(:kmac_256, 0, \"my secret key\", \"app-specific customization\")\n\n# Add data to be authenticated (update can be called multiple times)\nkmac.update(\"Authenticate this message\")\n# or use the \u003c\u003c operator\nkmac \u003c\u003c \"And this too\"\n\n# Get the result as a hex string\nresult = kmac.hex_squeeze(128)\n\n# Or as binary\nbinary_result = kmac.squeeze(128)\n\n# One-shot operation (customization is optional)\n# Parameters: algorithm, data, data, output_length (in bytes),key, [customization] optional\nresult = SHA3::KMAC.hexdigest(:kmac_256, \"message\", 64, \"key\", \"customization\")\n```\n\n## Development\n\n### Dependencies\n\n- **C/C++** compiler and native build tools (e.g., Clang/LLVM, GCC, MinGW, etc.)\n- **Gems**: rake, rake-compiler, rspec, yard\n\n### Testing\n\nRun `rake` to build and run the (RSpec) tests.\n\nTo run the tests manually:\n\n```bash\nbundle exec rspec\n```\n\nThe test suite includes a special `sha3_vectors_spec.rb` file that automatically:\n1. Downloads the official SHA3 test vectors from the XKCP repository\n2. Parses the test vectors\n3. Runs tests against all SHA3 variants (224, 256, 384, and 512 bit)\n\nThe test vectors are downloaded only once and cached in the `spec/data` directory for future test runs.\n\n### Supported Ruby Versions\n\n- MRI Ruby 2.7 - 3.4\n\n## Roadmap\n\nAs of version 2.2.0 (2025), this gem is feature complete with a stable API—future updates will focus exclusively on performance improvements, security enhancements, and bug fixes.\n\n- [X] 0.1.0: Add support for SHA-3 variants (224, 256, 384, and 512 bit)\n- [X] 2.0.0: Add support for SHAKE128 and SHAKE256 extendable-output functions (XOFs)\n- [X] 2.1.0: Add support for KMAC\n- [X] 2.2.0: Add support for cSHAKE\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n\n## License\n\nCopyright (c) 2012 - 2025 Johanns Gregorian (https://github.com/johanns)\n\nReleased under the MIT License. See [LICENSE.txt](LICENSE.txt) for details.\n\n## Credits\n\n- [XKCP - eXtended Keccak Code Package](https://github.com/XKCP/XKCP) by the Keccak team: [https://keccak.team/index.html](https://keccak.team/index.html)\n- All contributors to the SHA3 for Ruby project\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohanns%2Fsha3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohanns%2Fsha3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohanns%2Fsha3/lists"}