philiprehberger-crypt 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f934ae2dfc3f4f4dc390661a3d9d70dc78d021d4addf51bc27aa8ff8c5701f85
-  data.tar.gz: 2fb862fd3ecdab2aaed5d2a24a76f229a07d3e471f61604894445388d42a3b1c
+  metadata.gz: 9b8b7e1b7ba025acb109315c7917651f67b9645ef6abc1f7699dbe4e471020b2
+  data.tar.gz: 988b00641592540f69b355896dd6d524f7369830f93a33ad450909e4260671a2
 SHA512:
-  metadata.gz: dff085e8d30a2a6bd928291f80249a98fa075f3481866b8b7b1cd83898bac6a4671fc1903f9cd9496cf183ab2fca7a4559da5b7faea3439531470caf58fe819f
-  data.tar.gz: e15ccc8344e3324526e0d9feace9f2d780d37f7141be6d851a597ed9ef29dbdb52245883adf27cd4f78f3fec959f72a9661caff4acd3525796d1430ec13e8ef4
+  metadata.gz: 85775a37db94d000bd73b20ed1d403e6dc5b891e38600860aea6ce0087c1c45d680886b3efc5212258b4f9132a691e7d52a92d1b2e824c935a698737f3590591
+  data.tar.gz: 799433a04830123ffe629edaf5460dcad49f477e48108c66c7cbb1bbfb7c7611e78c9cf77f97cd7211de060b036d93eec7119e49cd7b1626f9af8a7aff47864e

data/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-04-09
+
+### Added
+- `hmac(data, key:, algorithm:)` for computing HMAC signatures (SHA-256/384/512)
+- `hmac_verify(data, signature:, key:, algorithm:)` for constant-time HMAC verification
+- `derive_key` now accepts an `iterations:` keyword to configure PBKDF2 work factor
+
 ## [0.2.0] - 2026-04-03
 
 ### Added

data/README.md

@@ -96,6 +96,16 @@ Philiprehberger::Crypt.random_bytes(32)
 # => 32-byte binary string
 ```
 
+### HMAC Signing
+
+```ruby
+key = Philiprehberger::Crypt.random_hex(16)
+signature = Philiprehberger::Crypt.hmac("payload", key: key)
+
+Philiprehberger::Crypt.hmac_verify("payload", signature: signature, key: key)
+# => true
+```
+
 ### Secure Comparison
 
 ```ruby
@@ -112,7 +122,9 @@ Philiprehberger::Crypt.secure_compare(token_a, token_b)
 | `.rotate_key(encrypted, old_key:, new_key:)` | Re-encrypt data with a new key |
 | `.envelope_encrypt(data, master_key:)` | Envelope encrypt with random data key |
 | `.envelope_decrypt(envelope, master_key:)` | Decrypt envelope-encrypted data |
-| `.derive_key(password, salt:)` | Derive a 32-byte key using PBKDF2-HMAC-SHA256 |
+| `.derive_key(password, salt:, iterations:)` | Derive a 32-byte key using PBKDF2-HMAC-SHA256 |
+| `.hmac(data, key:, algorithm:)` | Compute hex-encoded HMAC signature |
+| `.hmac_verify(data, signature:, key:, algorithm:)` | Constant-time HMAC verification |
 | `.random_salt` | Generate a 32-byte cryptographic random salt |
 | `.random_token` | Generate a URL-safe Base64 random token |
 | `.random_hex(n)` | Generate a hex-encoded random string (2*n characters) |

data/lib/philiprehberger/crypt/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module Crypt
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

data/lib/philiprehberger/crypt.rb

@@ -71,17 +71,47 @@ module Philiprehberger
     #
     # @param password [String] the password to derive from
     # @param salt [String] a random salt (use {.random_salt} to generate)
+    # @param iterations [Integer] number of PBKDF2 iterations (default: 100_000)
     # @return [String] a 32-byte raw key suitable for {.encrypt}/{.decrypt}
-    def self.derive_key(password, salt:)
+    # @raise [ArgumentError] if iterations is less than 1
+    def self.derive_key(password, salt:, iterations: PBKDF2_ITERATIONS)
+      raise ArgumentError, 'iterations must be >= 1' if iterations.to_i < 1
+
       OpenSSL::PKCS5.pbkdf2_hmac(
         password.to_s,
         salt,
-        PBKDF2_ITERATIONS,
+        iterations.to_i,
         KEY_LENGTH,
         OpenSSL::Digest.new('SHA256')
       )
     end
 
+    # Compute an HMAC signature for data using the given key.
+    #
+    # @param data [String] the data to sign
+    # @param key [String] the HMAC secret key
+    # @param algorithm [Symbol] hash algorithm (:sha256, :sha384, or :sha512)
+    # @return [String] hex-encoded HMAC digest
+    # @raise [ArgumentError] if algorithm is unsupported
+    def self.hmac(data, key:, algorithm: :sha256)
+      algo = HASH_ALGORITHMS[algorithm]
+      raise ArgumentError, "Unsupported algorithm: #{algorithm}. Use :sha256, :sha384, or :sha512" unless algo
+
+      OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new(algo), key.to_s, data.to_s)
+    end
+
+    # Verify an HMAC signature in constant time.
+    #
+    # @param data [String] the original data
+    # @param signature [String] the expected hex-encoded HMAC signature
+    # @param key [String] the HMAC secret key
+    # @param algorithm [Symbol] hash algorithm used to sign
+    # @return [Boolean] true if the signature matches
+    def self.hmac_verify(data, signature:, key:, algorithm: :sha256)
+      expected = hmac(data, key: key, algorithm: algorithm)
+      secure_compare(expected, signature.to_s)
+    end
+
     # Generate a cryptographically secure random salt.
     #
     # @return [String] a 32-byte random salt (raw bytes)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-crypt
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-04 00:00:00.000000000 Z
+date: 2026-04-09 00:00:00.000000000 Z
 dependencies: []
 description: A high-level encryption toolkit providing AES-256-GCM encryption and
   decryption, key rotation, envelope encryption, PBKDF2 key derivation, secure random