SHA3 for Ruby

A high-performance native binding to the SHA3 (FIPS 202) cryptographic hashing algorithms, based on the XKCP - eXtended Keccak Code Package.

This 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) and KMAC (Keccak Message Authentication Code) as specified in NIST SP 800-185.

• Documentation
• Features
• Installation
• Usage
  • SHA-3 Fixed Hash Functions
  • SHAKE128/256 Functions
  • KMAC Functions
  • Alternate Class Syntax
  • Hashing a File
• Development
  • Dependencies
  • Testing
  • Supported Ruby Versions
• Contributing
• Roadmap
• License
• Credits

• API Documentation
• GitHub Repository
• Issue Tracker

• Full support for all SHA-3 variants (224, 256, 384, and 512 bits)
• Support for SHAKE128 and SHAKE256 extendable-output functions (XOFs)
• Support for KMAC (Keccak Message Authentication Code)
• Native C implementation for high performance
• Simple, Ruby-friendly API that follows Ruby's standard Digest interface
• Comprehensive test suite with official NIST test vectors
• Thread-safe implementation

Add this line to your application's Gemfile:

gem 'sha3', '~> 2.0'

And then execute:

bundle install

Or install it yourself as:

gem install sha3

require 'sha3'

# Create a new digest instance
digest = SHA3::Digest.new(:sha3_224, 'Start here')

# Add more data to be hashed
digest << "Compute Me"
digest.update("Me too")

# Get the final hash value as a hex string
digest.hexdigest
# => "d6d38021d60857..."

# Or as a binary string
digest.digest

Valid algorithm symbols are:

• :sha3_224 - SHA-3 224 bits
• :sha3_256 - SHA-3 256 bits
• :sha3_384 - SHA-3 384 bits
• :sha3_512 - SHA-3 512 bits
• :shake_128 - SHAKE128 extendable-output function
• :shake_256 - SHAKE256 extendable-output function

SHAKE128 and SHAKE256 are extendable-output functions (XOFs) that allow you to "squeeze" an arbitrary number of bytes from the hash state:

# Create a new SHAKE128 instance
shake = SHA3::Digest.new(:shake_128)

# Add data to be hashed
shake << 'Squeeze this data...'

# Squeeze 120 bytes (240 hex characters) from the hash state
result = shake.hex_squeeze(120)

# Or get binary output
binary_result = shake.squeeze(1024)

# You can call squeeze functions multiple times with arbitrary output lengths
first_part = shake.squeeze(32)       # Get 32 bytes
second_part = shake.squeeze(64)      # Get 64 bytes
third_part = shake.hex_squeeze(128)  # Get 128 bytes as hex

KMAC (Keccak Message Authentication Code) is a message authentication code algorithm based on the SHAKE extendable-output functions:

require 'sha3'

# Create a new KMAC instance
# Parameters: algorithm, output_length (in bytes), key, [customization] optional
kmac = SHA3::KMAC.new(:kmac_128, 32, "my secret key", "app-specific customization")

# Add data to be authenticated (update can be called multiple times)
kmac.update("Authenticate this message")
# or use the << operator
kmac << "And this too"

# Get the result as a hex string
result = kmac.hexdigest
# => "a8982c..."

# Or as binary
binary_result = kmac.digest

# One-shot operation (customization is optional)
# Parameters: algorithm, data, output_length (in bytes), data, key, [customization] optional
result = SHA3::KMAC.hexdigest(:kmac_256, "message", 64, "key", "customization")

For convenience, you can also use dedicated classes for each algorithm:

# Available classes
SHA3::Digest::SHA3_224.new([data])
SHA3::Digest::SHA3_256.new([data])
SHA3::Digest::SHA3_384.new([data])
SHA3::Digest::SHA3_512.new([data])
SHA3::Digest::SHAKE_128.new([data])
SHA3::Digest::SHAKE_256.new([data])

# Example usage
digest = SHA3::Digest::SHA3_256.new('Start here')

digest << "Compute Me"
digest.update("Me too")

digest.hexdigest
# => "bedf0dd9a15b647..."

# Compute the hash value for a given file, and return the result as hex
hash = SHA3::Digest::SHA3_256.file("my_file.bin").hexdigest

# Using SHAKE function to squeeze an arbitrary number of bytes
shake = SHA3::Digest::SHAKE_128.file("my_file.bin").hexdigest(320)

# Calling SHA3::Digest.file(...) defaults to SHA3_256
hash = SHA3::Digest.file("my_file.bin").hexdigest
# => "a9801db49389339..."

• C/C++ compiler and native build tools (e.g., Clang/LLVM, GCC, MinGW, etc.)
• Gems: rake, rake-compiler, rspec, yard

Run rake to build and run the (RSpec) tests.

To run the tests manually:

bundle exec rspec

The test suite includes a special sha3_vectors_spec.rb file that automatically:

1. Downloads the official SHA3 test vectors from the XKCP repository
2. Parses the test vectors
3. Runs tests against all SHA3 variants (224, 256, 384, and 512 bit)

The test vectors are downloaded only once and cached in the spec/data directory for future test runs.

• MRI Ruby 2.7 - 3.1

• Add support for SHA-3 variants (224, 256, 384, and 512 bit)
• Add support for SHAKE128 and SHAKE256 extendable-output functions (XOFs)
• Add support for KMAC
• Add support for cSHAKE

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Copyright (c) 2012 - 2025 Johanns Gregorian (https://github.com/johanns)

Released under the MIT License. See LICENSE.txt for details.

• XKCP - eXtended Keccak Code Package by the Keccak team: https://keccak.team/index.html
• All contributors to the SHA3 for Ruby project