sha3 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c29bcfb557e028701b34ce0d2be3cdbec41882e45cedcb2f129e874bbb3867e5
-  data.tar.gz: 12c260b599a433def09b389d0cd39e72ebe2dae4e495979235aece99f2684e25
+  metadata.gz: de8b62510dacd92d85961808033747000eaed0b5866ed33e1d51599a9ce03b17
+  data.tar.gz: dc36181bd1095ab54c2574fba9fde0c37fd011d256067325abadb3bbb734b1da
 SHA512:
-  metadata.gz: 1be97184feef60e8340b6dd009f5c8eabcc6b2b72b050d2a3f08ef93d9c11184c7a9c1246f2cf241ef62d47fc13b96a62bab8b61002001b04942162dc9a7dd82
-  data.tar.gz: ca4d24baf5cda13fb0f071640875a16182aa234dca43b85d5d81e05ec80a9d3d1ea89b98b0f7f6a621d6395e6647472ef131c9dd2979f942556137108079ca80
+  metadata.gz: d8f86426fd9b7ecb187eb3b75cbf0b9d574cfc6e6bda0370c25e4b9d8b1ccf33a45427b7c5a0e16b7f7e6ff0c9c5b8d2b556fa409d9890ed5c67c261c734c770
+  data.tar.gz: 8c670be3e5adadc174a164a757aec0e326b26633737c52a8c1f8e41dc3f69f9dc44be9ad077dc22e7ce6742a0313f89151d5ec7135958cde0ccc2a59173f2cea

data/.clang-format

@@ -20,7 +20,7 @@ BinPackArguments: true
 BinPackParameters: true
 BreakBeforeBraces: Attach
 BreakBeforeTernaryOperators: true
-ColumnLimit: 100
+ColumnLimit: 120
 CompactNamespaces: false
 ConstructorInitializerAllOnOneLineOrOnePerLine: true
 Cpp11BracedListStyle: true

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:
+  Enabled: false

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,13 +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) 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.
+> **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
@@ -19,6 +21,7 @@ A high-performance native binding to the SHA3 (FIPS 202) cryptographic hashing a
 - [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)
 - [Development](#development)
@@ -38,8 +41,9 @@ 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 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
@@ -119,6 +123,31 @@ second_part = shake.squeeze(64)      # Get 64 bytes
 third_part = shake.hex_squeeze(128)  # Get 128 bytes as hex
 ```
 
+### 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
+# Parameters: algorithm, output_length (in bytes), key, [customization]
+kmac = SHA3::KMAC.new(:kmac_128, 32, "my secret key", "app-specific customization")
+
+# Add data to be authenticated
+kmac.update("Authenticate this message")
+
+# Get the result as a hex string
+result = kmac.hexdigest
+# => "a8982c..."
+
+# 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:
@@ -150,6 +179,9 @@ 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 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..."
@@ -187,7 +219,8 @@ The test vectors are downloaded only once and cached in the `spec/data` director
 
 - [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
+- [X] Add support for KMAC
+- [ ] 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