sha3 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de8b62510dacd92d85961808033747000eaed0b5866ed33e1d51599a9ce03b17
-  data.tar.gz: dc36181bd1095ab54c2574fba9fde0c37fd011d256067325abadb3bbb734b1da
+  metadata.gz: 0352e31c9fba5b6e692cca78be1860cccf6a008717738ecbea414d83d195b588
+  data.tar.gz: 24f543cfcb6b2d477182912a65b54a09cce5209dcfe6c8dbeec22c3992296cec
 SHA512:
-  metadata.gz: d8f86426fd9b7ecb187eb3b75cbf0b9d574cfc6e6bda0370c25e4b9d8b1ccf33a45427b7c5a0e16b7f7e6ff0c9c5b8d2b556fa409d9890ed5c67c261c734c770
-  data.tar.gz: 8c670be3e5adadc174a164a757aec0e326b26633737c52a8c1f8e41dc3f69f9dc44be9ad077dc22e7ce6742a0313f89151d5ec7135958cde0ccc2a59173f2cea
+  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
+BasedOnStyle: Google
+
 ColumnLimit: 120
-CompactNamespaces: false
-ConstructorInitializerAllOnOneLineOrOnePerLine: true
-Cpp11BracedListStyle: true
-DerivePointerAlignment: false
-FixNamespaceComments: true
-IncludeBlocks: Regroup
-IndentCaseLabels: true
-IndentPPDirectives: None
+
 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/.rubocop.yml

@@ -10,4 +10,4 @@ Layout/LineLength:
   Max: 120
 
 Naming/VariableNumber:
-  Enabled: false
+  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/README.md

@@ -4,14 +4,13 @@
 
 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) and KMAC (Keccak Message Authentication Code) as specified in NIST SP 800-185.
+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'.
+> **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
 
@@ -20,10 +19,11 @@ This gem provides support for the standard SHA-3 fixed-length functions (224, 25
 - [Installation](#installation)
 - [Usage](#usage)
   - [SHA-3 Fixed Hash Functions](#sha-3-fixed-hash-functions)
-  - [SHAKE128/256 Functions](#shake128256-functions)
-  - [KMAC Functions](#kmac-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)
@@ -43,6 +43,7 @@ This gem provides support for the standard SHA-3 fixed-length functions (224, 25
 
 - 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
@@ -54,7 +55,7 @@ This gem provides support for the standard SHA-3 fixed-length functions (224, 25
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'sha3', '~> 2.0'
+gem 'sha3', '~> 2.2'
 ```
 
 And then execute:
@@ -100,15 +101,54 @@ Valid algorithm symbols are:
 - `: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:
+
+```ruby
+# 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])
+```
+
+```ruby
+# Example usage
+digest = SHA3::Digest::SHA3_256.new('Start here')
+
+digest << "Compute Me"
+digest.update("Me too")
+
+digest.hexdigest
+# => "bedf0dd9a15b647..."
+```
+
+### Hashing a File
+
+```ruby
+# 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.new(:shake_128)
+shake = SHA3::Digest::SHAKE_128.new
 
-# Add data to be hashed
+# Add data to hash
 shake << 'Squeeze this data...'
 
 # Squeeze 120 bytes (240 hex characters) from the hash state
@@ -123,6 +163,36 @@ 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:
@@ -130,12 +200,14 @@ KMAC (Keccak Message Authentication Code) is a message authentication code algor
 ```ruby
 require 'sha3'
 
-# Create a new KMAC instance
-# Parameters: algorithm, output_length (in bytes), key, [customization]
+# 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
+# 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
@@ -144,47 +216,23 @@ result = kmac.hexdigest
 # Or as binary
 binary_result = kmac.digest
 
-# One-shot operation
-result = SHA3::KMAC.hexdigest(:kmac_256, "message", 64, "key", "customization")
-```
-
-### Alternate Class Syntax
-
-For convenience, you can also use dedicated classes for each algorithm:
-
-```ruby
-# 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])
-```
-
-```ruby
-# Example usage
-digest = SHA3::Digest::SHA3_256.new('Start here')
-
-digest << "Compute Me"
-digest.update("Me too")
-
-digest.hexdigest
-# => "bedf0dd9a15b647..."
-```
+# Create a new KMAC instance with an arbitrary-length (XOF) operation
+kmac = SHA3::KMAC.new(:kmac_256, 0, "my secret key", "app-specific customization")
 
-### Hashing a File
+# Add data to be authenticated (update can be called multiple times)
+kmac.update("Authenticate this message")
+# or use the << operator
+kmac << "And this too"
 
-```ruby
-# Compute the hash value for a given file, and return the result as hex
-hash = SHA3::Digest::SHA3_256.file("my_file.bin").hexdigest
+# Get the result as a hex string
+result = kmac.hex_squeeze(128)
 
-# Using SHAKE function to squeeze an arbitrary number of bytes
-shake = SHA3::Digest::SHAKE_128.file("my_file.bin").hexdigest(320)
+# Or as binary
+binary_result = kmac.squeeze(128)
 
-# Calling SHA3::Digest.file(...) defaults to SHA3_256
-hash = SHA3::Digest.file("my_file.bin").hexdigest
-# => "a9801db49389339..."
+# 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
@@ -213,14 +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)
-- [X] Add support for KMAC
-- [ ] Add support for cSHAKE
+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