sha3 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c29bcfb557e028701b34ce0d2be3cdbec41882e45cedcb2f129e874bbb3867e5
-  data.tar.gz: 12c260b599a433def09b389d0cd39e72ebe2dae4e495979235aece99f2684e25
+  metadata.gz: 0352e31c9fba5b6e692cca78be1860cccf6a008717738ecbea414d83d195b588
+  data.tar.gz: 24f543cfcb6b2d477182912a65b54a09cce5209dcfe6c8dbeec22c3992296cec
 SHA512:
-  metadata.gz: 1be97184feef60e8340b6dd009f5c8eabcc6b2b72b050d2a3f08ef93d9c11184c7a9c1246f2cf241ef62d47fc13b96a62bab8b61002001b04942162dc9a7dd82
-  data.tar.gz: ca4d24baf5cda13fb0f071640875a16182aa234dca43b85d5d81e05ec80a9d3d1ea89b98b0f7f6a621d6395e6647472ef131c9dd2979f942556137108079ca80
+  metadata.gz: a947dc104fa08b9199ed307fd43b3bee24143561aaa9665b4c6dd6a0d20ddbf69194b4eb96b845fd0974dc68d2133d024157c754f5e2835ec6161958df343caa
+  data.tar.gz: 4dd184e53262a9ec71eaf56bf80a295e8d3b691b736333834e5ae9e416df65bbea4ca10c20cc4c22e429bb6ffc97debda126b59bd50f23d732b079c3418b2653

data/.clang-format

@@ -1,54 +1,7 @@
-BasedOnStyle: Google  # Use Google's style as a foundation
-AccessModifierOffset: -1
-AlignAfterOpenBracket: Align
-AlignConsecutiveAssignments: false
-AlignConsecutiveDeclarations: false
-AlignEscapedNewlines: Left
-AlignOperands: true
-AlignTrailingComments: true
-AllowAllParametersOfDeclarationOnNextLine: true
-AllowShortBlocksOnASingleLine: false
-AllowShortCaseLabelsOnASingleLine: false
-AllowShortFunctionsOnASingleLine: Empty
-AllowShortIfStatementsOnASingleLine: false
-AllowShortLoopsOnASingleLine: false
-AlwaysBreakAfterDefinitionReturnType: None
-AlwaysBreakAfterReturnType: None
-AlwaysBreakBeforeMultilineStrings: true
-AlwaysBreakTemplateDeclarations: Yes
-BinPackArguments: true
-BinPackParameters: true
-BreakBeforeBraces: Attach
-BreakBeforeTernaryOperators: true
-ColumnLimit: 100
-CompactNamespaces: false
-ConstructorInitializerAllOnOneLineOrOnePerLine: true
-Cpp11BracedListStyle: true
-DerivePointerAlignment: false
-FixNamespaceComments: true
-IncludeBlocks: Regroup
-IndentCaseLabels: true
-IndentPPDirectives: None
+BasedOnStyle: Google
+
+ColumnLimit: 120
+
 IndentWidth: 4
-KeepEmptyLinesAtTheStartOfBlocks: false
-Language: Cpp
-MaxEmptyLinesToKeep: 1
-NamespaceIndentation: None
-PointerAlignment: Left
-ReflowComments: true
-SortIncludes: true
-SortUsingDeclarations: true
-SpaceAfterCStyleCast: false
-SpaceAfterTemplateKeyword: true
-SpaceBeforeAssignmentOperators: true
-SpaceBeforeParens: ControlStatements
-SpaceInEmptyParentheses: false
-SpacesBeforeTrailingComments: 2
-SpacesInAngles: false
-SpacesInContainerLiterals: false
-SpacesInCStyleCastParentheses: false
-SpacesInParentheses: false
-SpacesInSquareBrackets: false
-Standard: Auto
-TabWidth: 2
+TabWidth: 4
 UseTab: Never

data/.document

@@ -1,5 +1,4 @@
 README.md
 LICENSE.txt
-lib/**/*.rb
-ext/sha3/digest.{c,h}
 doc/**/*.rb
+ext/sha3/*.c

data/.rdoc_options

@@ -5,6 +5,7 @@ title: SHA3
 charset: UTF-8
 encoding: UTF-8
 force_update: true
+line_numbers: true
 markup: rdoc
 op_dir: html
 visibility: :private

data/.rubocop.yml

@@ -8,3 +8,6 @@ AllCops:
 
 Layout/LineLength:
   Max: 120
+
+Naming/VariableNumber:
+  EnforcedStyle: snake_case

data/.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "(lldb) Attach",
+            "type": "cppdbg",
+            "request": "attach",
+            "program": "/Users/johannsg/.rubies/ruby-3.4.2/bin/ruby",
+            "MIMode": "lldb"
+        },
+    ]
+}

data/.vscode/settings.json

@@ -0,0 +1,9 @@
+{
+    "files.associations": {
+        "sp800-185.h": "c",
+        "cshake.h": "c",
+        "bitset": "c",
+        "sp800_185.h": "c",
+        "keccakhash.h": "c"
+    }
+}

data/.vscode/tasks.json

@@ -0,0 +1,29 @@
+{
+    "tasks": [
+        {
+            "type": "cppbuild",
+            "label": "C/C++: clang build active file",
+            "command": "/usr/bin/clang",
+            "args": [
+                "-fcolor-diagnostics",
+                "-fansi-escape-codes",
+                "-g",
+                "${file}",
+                "-o",
+                "${fileDirname}/${fileBasenameNoExtension}"
+            ],
+            "options": {
+                "cwd": "${fileDirname}"
+            },
+            "problemMatcher": [
+                "$gcc"
+            ],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            },
+            "detail": "Task generated by Debugger."
+        }
+    ],
+    "version": "2.0.0"
+}

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # SHA3 Ruby Gem Changelog
 
+## v2.2.0 (2025-03-15)
+
+### Features
+- Added support for cSHAKE
+
+## v2.1.0 (2025-03-15)
+
+### Features
+- Added support for KMAC
+
+## v2.0.0 (2025-03-15)
+
+### Features
+- Added support for SHAKE128 and SHAKE256 extendable-output functions (XOFs)
+
 ## v1.0.5 (2022-10-23)
 
 ### Security

data/Gemfile

@@ -6,6 +6,7 @@ gemspec
 
 group :development, :test do
   gem 'irb'
+  gem 'rdoc', '~> 6'
 
   gem 'rake', '~> 13'
   gem 'rake-compiler', '~> 1'

data/README.md

@@ -2,14 +2,15 @@
 
 [![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)
 
-A high-performance native binding to the SHA3 (FIPS 202) cryptographic hashing algorithm, based on the [XKCP - eXtended Keccak Code Package](https://github.com/XKCP/XKCP).
+A 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).
+
+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 to the API. Please review the changelog and ensure compatibility with your application.
-> If you need the previous behavior, lock your Gemfile to version '~> 1.0'.
+> **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
 
@@ -18,9 +19,11 @@ A high-performance native binding to the SHA3 (FIPS 202) cryptographic hashing a
 - [Installation](#installation)
 - [Usage](#usage)
   - [SHA-3 Fixed Hash Functions](#sha-3-fixed-hash-functions)
-  - [SHAKE128/256 Functions](#shake128256-functions)
   - [Alternate Class Syntax](#alternate-class-syntax)
   - [Hashing a File](#hashing-a-file)
+  - [SHAKE128/256 Functions](#shake128256-functions)
+  - [cSHAKE128/256 Functions](#cshake128256-functions)
+  - [KMAC Functions](#kmac-functions)
 - [Development](#development)
   - [Dependencies](#dependencies)
   - [Testing](#testing)
@@ -38,8 +41,10 @@ A high-performance native binding to the SHA3 (FIPS 202) cryptographic hashing a
 
 ## Features
 
-- Full support for all SHA-3 variants (224, 256, 384, and 512 bit)
+- 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
@@ -50,7 +55,7 @@ A high-performance native binding to the SHA3 (FIPS 202) cryptographic hashing a
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'sha3', '~> 2.0'
+gem 'sha3', '~> 2.2'
 ```
 
 And then execute:
@@ -96,29 +101,6 @@ Valid algorithm symbols are:
 - `:shake_128` - SHAKE128 extendable-output function
 - `:shake_256` - SHAKE256 extendable-output function
 
-### 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:
-
-```ruby
-# 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
-```
-
 ### Alternate Class Syntax
 
 For convenience, you can also use dedicated classes for each algorithm:
@@ -150,11 +132,109 @@ digest.hexdigest
 # 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:
+
+```ruby
+# 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.
+
+```ruby
+# 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:
+
+```ruby
+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
@@ -181,13 +261,16 @@ The test vectors are downloaded only once and cached in the `spec/data` director
 
 ### Supported Ruby Versions
 
-- MRI Ruby 2.7 - 3.1
+- MRI Ruby 2.7 - 3.4
 
 ## Roadmap
 
-- [X] Add support for SHA-3 variants (224, 256, 384, and 512 bit)
-- [X] Add support for SHAKE128 and SHAKE256 extendable-output functions (XOFs)
-- [ ] Add support for cSHAKE, TurboSHANKE, and KMAC
+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.
+
+- [X] 0.1.0: Add support for SHA-3 variants (224, 256, 384, and 512 bit)
+- [X] 2.0.0: Add support for SHAKE128 and SHAKE256 extendable-output functions (XOFs)
+- [X] 2.1.0: Add support for KMAC
+- [X] 2.2.0: Add support for cSHAKE
 
 ## Contributing
 

data/Rakefile

@@ -12,10 +12,11 @@ require 'rake/extensiontask'
 
 begin
   Rake::ExtensionTask.new :compile do |ext|
-    ext.name = 'sha3_digest'
+    ext.name = 'sha3_ext'
+
     ext.ext_dir = 'ext/sha3'
-    ext.tmp_dir = 'tmp'
     ext.source_pattern = '*.{c}'
+    ext.tmp_dir = 'tmp'
   end
 rescue LoadError
   task :compile do
@@ -28,6 +29,7 @@ require 'rdoc/task'
 RDoc::Task.new do |rdoc|
   rdoc.rdoc_dir = '../docs/sha3'
   rdoc.options << '--force-update'
+  rdoc.options << '-V'
 end
 
 task default: %i[compile spec]

data/doc/sha3.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module SHA3
   module Digest
     # SHA3_224 is a cryptographic hash function that produces a 224-bit (28-byte) hash value.

data/ext/sha3/config.h

@@ -1,10 +1,10 @@
 /* File generated by ToTargetConfigFile.xsl */
 
-#define XKCP_has_Sponge_Keccak
 #define XKCP_has_FIPS202
 #define XKCP_has_KeccakP1600
+#define XKCP_has_Sponge_Keccak
+#define XKCP_has_SP800_185
 
-// #define XKCP_has_SP800_185
 // #define XKCP_has_Duplex_Keccak
 // #define XKCP_has_PRG_Keccak
 // #define XKCP_has_Ketje