sha3

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

[!CAUTION] Security Notice: Do not use SHA-3 for hashing passwords. Instead, use a slow hashing function such as PBKDF2, Argon2, bcrypt, or scrypt.

[!IMPORTANT] 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 '~> 1.0'.

Table of Contents

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

Documentation

• API Documentation
• GitHub Repository
• Issue Tracker

Features

• Full support for all SHA-3 variants (224, 256, 384, and 512 bits)
• Support for SHAKE128 and SHAKE256 extendable-output functions (XOFs)
• Support for cSHAKE128 and cSHAKE256 extendable-output functions (XOFs) with domain separation and personalization
• 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

Installation

Add this line to your application's Gemfile:

gem 'sha3', '~> 2.2'

And then execute:

bundle install

Or install it yourself as:

gem install sha3

Usage

SHA-3 Fixed Hash Functions

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

Alternate Class Syntax

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..."

Hashing a File

# 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 generate an arbitrary-length hash output
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..."

SHAKE128/256 Functions

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::SHAKE_128.new

# Add data to hash
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

cSHAKE128/256 Functions

cSHAKE128 and cSHAKE256 are customizable versions of SHAKE128 and SHAKE256, allowing for domain separation and personalization through a customization string.

# Create a new cSHAKE instance with a fixed output length
cshake = SHA3::CSHAKE.new(:cshake_128, 32, name: 'my-app', customization: 'Email Signature')

# Add data to hash
cshake.update('Hello')
# Or use the << operator
cshake << 'Compute me...'

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

# Or as a binary string
cshake.digest

# Create a new cSHAKE instance for an arbitrarily-long (XOF) operation
cshake = SHA3::CSHAKE.new(:cshake_256, 0, customization: 'Signature')

# Add data to hash
cshake.update('Beep Beep')

# Squeeze 64-bytes of data from state
cshake.squeeze(64)

KMAC Functions

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 with a fixed output length
# 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

# Create a new KMAC instance with an arbitrary-length (XOF) operation
kmac = SHA3::KMAC.new(:kmac_256, 0, "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.hex_squeeze(128)

# Or as binary
binary_result = kmac.squeeze(128)

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

Development

Dependencies

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

Testing

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:

• Downloads the official SHA3 test vectors from the XKCP repository
• Parses the test vectors
• 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.

Supported Ruby Versions

• MRI Ruby 2.7 - 3.4

Roadmap

As 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.

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

Contributing

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

License

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

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

Credits

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