wots 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6efca98c49499aae50fd5225762614026111f16cfc4ccee573e6ea6857e0664
-  data.tar.gz: 236faef3ed700463ea083a7cae7de8d6365663e5ad1e65c9819dab21e92fb6d3
+  metadata.gz: 44928dd35ba7e5a8294069e3f85916e3a635440d52d63304337f218503d66443
+  data.tar.gz: 1e2b102c71bb6d73c96a5aa31cee0a74b4de756179b791a68733e3233e86c396
 SHA512:
-  metadata.gz: b8eefc4c86bf05cfa7820e291bcbacf3d1fba792d91a7392f086147979468e8fe8caa62de59c7f47c00bc65145ab9d82f91cbba35215f295ddb85484dea6d477
-  data.tar.gz: 0a3a1affaa6a0d9e9298927cfd16e12a3e84aaa4a8b558f4b739002e2005a4d07f0747156c2716c12e879d5770b3c7aa06a852a47f148b9b3ebeb32f7026d27a
+  metadata.gz: c92615a1dece0f8ed08dcd809c32dd8f4c4bf2476accd34799a66f3dd277ecb6bedf3ce97c6f67132bd46a8ca09b7e542497b715f515b6d4180ab9f59426e386
+  data.tar.gz: 2a1f7a07e0860068fec8b1dc2c685efd02f8e287971d711244642979bb26a52233f338135696b86d77ef59b0eb00baf6bdb2099b23956d482d57677d0c509ce6

data/.ruby-version

@@ -1 +1 @@
-ruby-3.4.3
+ruby-4.0.0

data/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.3.0] - 2026-11-08
+
+This release contains **breaking changes**. Keys and signatures created with 0.2.0 are not compatible.
+
+### Breaking changes
+
+- `WOTSP-SHAKE_256` (`WOTS::Param::SHAKE256`) now uses **SHAKE128** with a 256-bit output, as defined in
+  RFC 8391 Sections 5.1 and 5.2. It used SHAKE256 with OpenSSL's default output length before, which is not
+  RFC 8391 and fails on OpenSSL 3.4 and later. Its outputs change.
+- `PrivateKey.from_seed(param, seed, pub_seed, addr: Address.new)` now requires `pub_seed`, and derives each
+  private key element as `PRF_keygen(seed, pub_seed || ADRS)` (NIST SP 800-208 Section 6.2), the method of the
+  XMSS reference implementation. It used `PRF(seed, toByte(i, 32))` before, so the same seed always gave the
+  same key regardless of `pub_seed` and address. The derived keys change.
+- `PrivateKey#keys`, `PublicKey#keys` and `Signature#sigs` are frozen arrays of frozen, lowercase hex strings.
+- `WOTS::Param` instances are frozen.
+- Stricter input validation, raising `ArgumentError`:
+  - `Param#f`, `#h`, `#h_msg`, `#prf` and `#prf_keygen` accept only the key and message lengths defined in
+    RFC 8391 and SP 800-208.
+  - `Param#chain` validates the seed length, and `Param#compute_checksum` rejects digits outside `[0, w - 1]`.
+  - Strings in encodings that are not ASCII compatible (e.g. UTF-16) are not accepted as hex strings.
+- `Param#chain` no longer modifies the given address.
+
+### Added
+
+- `addr:` keyword (default `WOTS::Address.new`) on `PrivateKey.from_seed`, `PrivateKey#sign`,
+  `PublicKey.from_private_key` and `PublicKey.from_signature`, so that one seed can derive several keys.
+- `PublicKey#verify(signature, pub_seed, message, addr:)`.
+- `Signature#==`, and `eql?`/`hash` consistent with `==` for `PublicKey` and `Signature`.
+- `WOTS::Core`, a scheme-independent WOTS+ engine on binary strings, driven by a hasher object
+  (`secret`, `step`, `compress`), so that other WOTS+ instantiations such as the one of SLH-DSA can be built on it.
+- `WOTS::RFC8391Hasher`, the hasher of RFC 8391.
+- `Param#keyed_digest` (binary keyed hash) and the prefix constants `Param::F`, `H`, `H_MSG`, `PRF`, `PRF_KEYGEN`.
+- Test vectors generated with the XMSS reference implementation for every parameter set, `w = 4` and `16`.
+- Runtime dependency on the `sha3` gem.
+
+### Changed
+
+- Signing, key generation and verification are about 30% faster.
+- Public keys and signatures compare equal regardless of the letter case of their hex strings.
+
+### Security
+
+- Documented how to manage one-time keys: one address per key, persist the state before releasing a
+  signature, never sign twice, and never roll back or share the state. The library does not track key use.
+- `RFC8391Hasher#inspect` redacts the seed and private key elements.
+- Releases require MFA on RubyGems (`rubygems_mfa_required`).
+- CI runs with a read-only token and actions pinned to commit SHAs.
+
+## [0.2.0] - 2026-08-11
+
+### Security
+
+- Restricted parameters to the sets and Winternitz parameters (`w = 4, 16`) defined in RFC 8391.
+- Rejected odd-length hex and raw binary input, and validated the remaining inputs.
+- Validated `Address` field ranges.
+- Redacted private key material from `PrivateKey#inspect`.
+- Documented the input format and security constraints.
+
+## [0.1.0] - 2025-09-18
+
+- Initial release.
+
+[0.3.0]: https://github.com/azuchi/wots/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/azuchi/wots/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/azuchi/wots/releases/tag/v0.1.0

data/README.md

@@ -10,7 +10,7 @@ WOTS+ is a post-quantum cryptographic signature scheme that provides security ag
 - Support for multiple hash functions:
   - `WOTSP-SHA2_256` (SHA-256)
   - `WOTSP-SHA2_512` (SHA-512)
-  - `WOTSP-SHAKE_256` (SHAKE-256)
+  - `WOTSP-SHAKE_256` (SHAKE128 with a 256-bit output, as defined in RFC 8391)
 - Support for Winternitz parameters w=4 and w=16
 - Key generation from seed
 - Digital signature generation and verification
@@ -41,24 +41,42 @@ require 'wots'
 # Use predefined parameters
 param = WOTS::Param::SHA256
 
-# Generate private key from seed
+# Generate private key from the secret seed and the public seed
 seed = "693141c7ee701d13e1a7c733e0aa8326c19961429bfb54083f2f65b30c32e20b"
-private_key = WOTS::PrivateKey.from_seed(param, seed)
+pub_seed = "46ece585b4c0bfa1186209270e22fa07c4716461b5a026c268e594fb94404f3a"
+private_key = WOTS::PrivateKey.from_seed(param, seed, pub_seed)
 
 # Generate public key
-pub_seed = "46ece585b4c0bfa1186209270e22fa07c4716461b5a026c268e594fb94404f3a"
 public_key = WOTS::PublicKey.from_private_key(private_key, pub_seed)
 
 # Sign a message
 message = "f16c96e88fb99a8287a43121962e89ed521699fa3e126c67eaaa168066354477"
 signature = private_key.sign(pub_seed, message)
 
-# Verify signature by reconstructing public key
-recovered_pk = WOTS::PublicKey.from_signature(signature, pub_seed, message)
-valid = (recovered_pk == public_key)
+# Verify signature
+valid = public_key.verify(signature, pub_seed, message)
 puts "Signature valid: #{valid}"
 ```
 
+### Deriving several keys from one seed
+
+Private keys are derived as `sk[i] = PRF_keygen(seed, pub_seed || ADRS)`
+([NIST SP 800-208](https://doi.org/10.6028/NIST.SP.800-208) Section 6.2), so each address gives a different key.
+Pass a distinct `WOTS::Address` (e.g. a different `ots_addr`) for each key, and pass the **same** address to
+every operation on that key:
+
+```ruby
+addr = WOTS::Address.new(ots_addr: 5)
+private_key = WOTS::PrivateKey.from_seed(param, seed, pub_seed, addr: addr)
+public_key = WOTS::PublicKey.from_private_key(private_key, pub_seed, addr: addr)
+signature = private_key.sign(pub_seed, message, addr: addr)
+public_key.verify(signature, pub_seed, message, addr: addr) # => true
+```
+
+`addr` defaults to `WOTS::Address.new` (all fields zero). Never use the same `seed`, `pub_seed` and address for
+two keys: they would be the same key, and signing with both would reuse a one-time key.
+See [One-time keys](#one-time-keys-state-management-is-up-to-you) for how to manage the addresses.
+
 ### Available Parameter Sets
 
 ```ruby
@@ -68,18 +86,119 @@ param = WOTS::Param::SHA256
 # SHA-512 based (n=64 bytes, w=16)
 param = WOTS::Param::SHA512
 
-# SHAKE-256 based (n=32 bytes, w=16)
+# SHAKE128 based (n=32 bytes, w=16), i.e. RFC 8391 WOTSP-SHAKE_256
 param = WOTS::Param::SHAKE256
 ```
 
+`WOTS::Param::SHAKE256` is named after the RFC 8391 parameter set `WOTSP-SHAKE_256`, where `256` is the output
+length in bits. It uses **SHAKE128**, not SHAKE256 (RFC 8391 Section 5.1).
+
+## Using the WOTS+ engine from another library
+
+`WOTS::Core` is the scheme-independent WOTS+ engine behind the API above. It works on **binary strings**
+and leaves the hashing and the hash address to a *hasher* object, so the same engine can drive other WOTS+
+instantiations, such as the one in SLH-DSA (FIPS 205), implemented in another library.
+
+```ruby
+core = WOTS::Core.new(n: 16, w: 16)   # w is 4 or 16
+pk   = core.pk_gen(hasher)
+sig  = core.sign(hasher, msg)         # msg: n-byte binary string; returns len n-byte strings
+pk2  = core.pk_from_sig(hasher, sig, msg)
+```
+
+A hasher is bound to one WOTS+ key pair and responds to:
+
+| Method | Returns |
+|---|---|
+| `secret(chain_idx)` | the `n`-byte secret value of chain `chain_idx` (used by `pk_gen` and `sign` only) |
+| `step(x, chain_idx, hash_idx)` | one application of the chaining hash to the `n`-byte value `x` at position `hash_idx` of chain `chain_idx` |
+| `compress(values)` | the public key built from the `len` chain end values |
+
+`WOTS::Core` calls them in the order of FIPS 205 Algorithms 6–8: for each chain `i` in ascending order,
+`secret(i)` (when needed) and then `step(x, i, j)` for ascending `j`. It never sees an address, so the hasher
+sets the chain and hash address itself. `WOTS::RFC8391Hasher` is the hasher of RFC 8391 used by this library.
+
+A hasher keeps a mutable address, so do not share one hasher between threads; create one per operation.
+
+## Input format
+
+All key material, seeds and messages are **even-length hexadecimal strings**. Raw binary strings and
+odd-length hex strings are rejected with an `ArgumentError`; convert them with `unpack1('H*')` first.
+
+```ruby
+message = Digest::SHA256.hexdigest("some payload")   # 64 hex chars = 32 bytes
+signature = private_key.sign(pub_seed, message)
+```
+
 ## Security Considerations
 
-**⚠️ IMPORTANT: This is a cryptograFixphic library implementation. While it follows RFC 8391 specifications,
+**⚠️ IMPORTANT: This is a cryptographic library implementation. While it follows RFC 8391 specifications,
 it has not undergone formal security audits. Use at your own risk in production environments.**
 
-WOTS+ is a **one-time signature scheme**. Each private key should only be used to sign **one message**.
-Reusing a private key to sign multiple messages can leak information about the private key and compromise security.
+### One-time keys: state management is up to you
+
+WOTS+ is a **one-time signature scheme**. Each private key must be used to sign **one message, once**.
+Signatures of two different messages under the same key let an attacker forge signatures.
+
+**This library does not track whether a key has been used.** A flag inside `WOTS::PrivateKey` would not protect
+you: calling `PrivateKey.from_seed` again recreates the same key as a fresh object, and real reuse happens across
+process restarts, devices and backups, which no in-memory flag can see. The state belongs to the code that assigns
+one-time keys, typically a counter of the next address to use. Follow these rules
+(based on [NIST SP 800-208](https://doi.org/10.6028/NIST.SP.800-208) Sections 8.1 and 9.1):
+
+- **One address per key.** `seed`, `pub_seed` and `addr` determine the key: the same triple always gives the same
+  key. Give every key its own address, e.g. by incrementing `ots_addr`.
+- **Persist before you release.** Write the updated state (e.g. the next `ots_addr`) to non-volatile storage, and
+  make sure it has really reached it (e.g. `File#fsync`, a committed database transaction), *before* the signature
+  leaves your process. If the process crashes after exporting a signature but before the state is durable, the key
+  will be used again after the restart.
+- **Never sign twice, not even the same message.** Re-computing a signature over the same message is open to fault
+  injection attacks (SP 800-208, Section 8.1, footnote 9). Sign once and store the signature if you need it again.
+- **Never roll the state back or share it.** Do not restore the state from backups or VM snapshots, and do not use
+  the same `seed` on several devices or processes at once.
+
+SP 800-208 additionally requires stateful hash-based key generation and signing to run inside a validated hardware
+cryptographic module. This software library cannot meet that requirement.
+
+### Key material
+
+The seed passed to `WOTS::PrivateKey.from_seed` is secret key material and must come from a
+cryptographically secure random number generator, e.g. `SecureRandom.hex(param.n)`.
+The private key is bound to `pub_seed` and the address, using the key generation method of NIST SP 800-208
+(Section 6.2). Of the parameter sets supported here, SP 800-208 defines
+`PRF_keygen` only for `WOTSP-SHA2_256`; this library applies the same construction
+(`Hash(toByte(4, n) || KEY || M)`) to every parameter set, as the XMSS reference implementation does.
+
+Only the Winternitz parameters defined in RFC 8391 (`w = 4` and `w = 16`) are accepted. Other values
+overflow the checksum encoding, which drops the high bits of the checksum and allows an attacker to
+forge signatures without the private key.
+
+Private key material is held in Ruby `String` objects and is not zeroized; it remains in memory until
+garbage collected.
 
 ## Specifications
 
 This implementation follows [RFC 8391 - XMSS: eXtended Merkle Signature Scheme](https://datatracker.ietf.org/doc/html/rfc8391), Section 3 (WOTS+).
+Private keys are derived with the method of [NIST SP 800-208](https://doi.org/10.6028/NIST.SP.800-208) Section 6.2.
+
+### How it is tested
+
+RFC 8391 and SP 800-208 do not publish test vectors; RFC 8391 (Section 7) points to its reference implementation
+instead, and NIST ACVP has no XMSS or WOTS+ test vectors yet. `spec/fixtures/reference_vectors.json` was therefore
+generated with the WOTS+ part (`wots.c`) of the
+[XMSS reference implementation](https://github.com/XMSS/xmss-reference)
+(commit `171ccbd26f098542a67eb5d2b128281c80bd71a6`) for every parameter set, `w = 4` and `16`, and a non-zero
+address. The specs check that key generation, signing and verification reproduce those vectors.
+
+Note that this is the reference implementation of XMSS, not of a standalone WOTS+. The chaining, signing and
+verification are RFC 8391 WOTS+ itself. The private key derivation is the one XMSS uses (SP 800-208); RFC 8391
+leaves the derivation of WOTS+ private keys open (Section 3.1.7).
+
+### Not compatible with SLH-DSA
+
+The WOTS+ of SLH-DSA ([FIPS 205](https://doi.org/10.6028/NIST.FIPS.205)) is a different instantiation: its chain
+step is the tweakable hash `F(PK.seed, ADRS, M)` without bitmasks, its address layout differs (and is compressed
+for SHA2), the public key is compressed with `T_len`, and it uses `n = 16, 24, 32` with `w = 16` only.
+Keys and signatures of this library cannot be used with SLH-DSA, nor with schemes built on it. Such a WOTS+ can be
+implemented on top of `WOTS::Core` with its own hasher (see
+[Using the WOTS+ engine from another library](#using-the-wots-engine-from-another-library)).

data/lib/wots/address.rb

@@ -1,27 +1,79 @@
 module WOTS
+  # WOTS+ hash function address.
+  # Each field is packed into a fixed width big endian integer by #to_payload,
+  # so a value outside its range would silently wrap and collide with another
+  # address, breaking the domain separation the chaining function relies on.
   class Address
-    attr_accessor :layer_addr
-    attr_accessor :tree_addr
-    attr_accessor :ots_addr
-    attr_accessor :chain_addr
-    attr_accessor :hash_addr
-    attr_accessor :key_and_mask # 0: key generation, 1: bitmask generation
+    UINT32_MAX = 0xFFFFFFFF
+    UINT64_MAX = 0xFFFFFFFFFFFFFFFF
+
+    attr_reader :layer_addr
+    attr_reader :tree_addr
+    attr_reader :ots_addr
+    attr_reader :chain_addr
+    attr_reader :hash_addr
+    attr_reader :key_and_mask # 0: key generation, 1: bitmask generation
 
     def initialize(layer_addr: 0, tree_addr: 0, ots_addr: 0, chain_addr: 0, hash_addr: 0, key_and_mask: 0)
-      @layer_addr = layer_addr
-      @tree_addr = tree_addr
-      @ots_addr = ots_addr
-      @chain_addr = chain_addr
-      @hash_addr = hash_addr
-      @key_and_mask = key_and_mask
+      self.layer_addr = layer_addr
+      self.tree_addr = tree_addr
+      self.ots_addr = ots_addr
+      self.chain_addr = chain_addr
+      self.hash_addr = hash_addr
+      self.key_and_mask = key_and_mask
+    end
+
+    def layer_addr=(value)
+      @layer_addr = check_range(:layer_addr, value, UINT32_MAX)
+    end
+
+    def tree_addr=(value)
+      @tree_addr = check_range(:tree_addr, value, UINT64_MAX)
+    end
+
+    def ots_addr=(value)
+      @ots_addr = check_range(:ots_addr, value, UINT32_MAX)
+    end
+
+    def chain_addr=(value)
+      @chain_addr = check_range(:chain_addr, value, UINT32_MAX)
+    end
+
+    def hash_addr=(value)
+      @hash_addr = check_range(:hash_addr, value, UINT32_MAX)
+    end
+
+    def key_and_mask=(value)
+      @key_and_mask = check_range(:key_and_mask, value, UINT32_MAX)
     end
 
     def type
       0
     end
 
+    # Return a copy of +addr+ that can be freely mutated by the chaining function,
+    # so that the caller's address object is never modified.
+    # @param [WOTS::Address] addr
+    # @return [WOTS::Address]
+    # @raise ArgumentError If +addr+ is not a WOTS::Address.
+    def self.copy_of(addr)
+      raise ArgumentError, 'addr must be WOTS::Address.' unless addr.is_a?(Address)
+
+      addr.dup
+    end
+
     def to_payload
       [layer_addr, tree_addr, type, ots_addr, chain_addr, hash_addr, key_and_mask].pack('NQ>NNNNN')
     end
+
+    private
+
+    # @raise ArgumentError If +value+ would not survive the round trip through +pack+.
+    def check_range(name, value, max)
+      raise ArgumentError, "#{name} must be integer." unless value.is_a?(Integer)
+      raise ArgumentError, "#{name} must be between 0 and #{max}." unless value >= 0 && value <= max
+
+      value
+    end
   end
-end
+end

data/lib/wots/core.rb

@@ -0,0 +1,189 @@
+module WOTS
+  # Scheme independent WOTS+ engine working on binary strings.
+  #
+  # The WOTS+ of RFC 8391 and of FIPS 205 (SLH-DSA) share the message encoding,
+  # the checksum and the way the chains are walked; they differ only in how a
+  # chain secret is derived, how one chain step is hashed, what goes into the
+  # hash address and how the chain end values form the public key. Those parts
+  # are supplied by a +hasher+ object, so this class never sees an address.
+  #
+  # A hasher bound to one WOTS+ key pair responds to:
+  #
+  # * +secret(chain_idx)+ -> the +n+-byte secret value of chain +chain_idx+.
+  #   Only needed by #pk_gen and #sign.
+  # * +step(x, chain_idx, hash_idx)+ -> one application of the chaining hash to the
+  #   +n+-byte value +x+ at position +hash_idx+ of chain +chain_idx+
+  #   (RFC 8391 Algorithm 2 with hash address +hash_idx+, FIPS 205 Algorithm 5 line 3-4).
+  # * +compress(values)+ -> the public key built from the +len+ chain end values.
+  #   RFC 8391 returns the values as they are; FIPS 205 applies T_len.
+  #
+  # The calls are made in the order of FIPS 205 Algorithms 6-8: for each chain i
+  # (ascending), +secret(i)+ (if needed) and then +step(x, i, j)+ for ascending j.
+  #
+  # This class is the API other gems build on, so its interface is kept stable.
+  class Core
+    # The Winternitz parameters this engine supports.
+    SUPPORTED_W = [4, 16].freeze
+
+    attr_reader :n, :w, :lg_w, :len1, :len2, :len
+
+    # @param [Integer] n The byte length of messages, chain values and secrets.
+    # @param [Integer] w The Winternitz parameter, one of +SUPPORTED_W+.
+    # @raise ArgumentError
+    def initialize(n:, w:)
+      raise ArgumentError, 'n must be integer.' unless n.is_a?(Integer)
+      raise ArgumentError, 'n must be positive.' unless n.positive?
+      raise ArgumentError, 'w must be integer.' unless w.is_a?(Integer)
+      raise ArgumentError, "w must be one of #{SUPPORTED_W.join(', ')}." unless SUPPORTED_W.include?(w)
+
+      @n = n
+      @w = w
+      @lg_w = w.bit_length - 1
+      @len1 = (8 * n + lg_w - 1) / lg_w
+      # floor(log2(len1 * (w - 1)) / lg_w) + 1, computed without floating point.
+      @len2 = ((len1 * (w - 1)).bit_length - 1) / lg_w + 1
+      @len = len1 + len2
+      @csum_shift = (8 - ((len2 * lg_w) % 8)) % 8
+      @csum_bytes = (len2 * lg_w + 7) / 8
+      freeze
+    end
+
+    # Convert +data+ into +out_len+ base w digits (RFC 8391 base_w, FIPS 205 base_2b).
+    # @param [String] data Binary string.
+    # @param [Integer] out_len
+    # @return [Array<Integer>]
+    # @raise ArgumentError If +data+ is too short to produce +out_len+ digits.
+    def base_w(data, out_len)
+      raise ArgumentError, 'data must be string.' unless data.is_a?(String)
+      raise ArgumentError, 'out_len must be integer.' unless out_len.is_a?(Integer)
+      raise ArgumentError, 'out_len must be positive.' unless out_len.positive?
+
+      required = (out_len * lg_w + 7) / 8
+      raise ArgumentError, "data must be at least #{required} bytes to produce #{out_len} digits." if data.bytesize < required
+
+      digits = []
+      in_idx = 0
+      total = 0
+      bits = 0
+      mask = w - 1
+      out_len.times do
+        if bits == 0
+          total = data.getbyte(in_idx)
+          in_idx += 1
+          bits = 8
+        end
+        bits -= lg_w
+        digits << ((total >> bits) & mask)
+      end
+      digits
+    end
+
+    # Encode the checksum of the first +len1+ message digits.
+    # @param [Array<Integer>] msg_digits
+    # @return [String] Binary string of ceil(len2 * lg_w / 8) bytes.
+    # @raise ArgumentError
+    def checksum_bytes(msg_digits)
+      raise ArgumentError, 'msg_digits must be Array.' unless msg_digits.is_a?(Array)
+      raise ArgumentError, "msg_digits must have at least #{len1} digits." if msg_digits.length < len1
+
+      csum = 0
+      len1.times do |i|
+        d = msg_digits[i]
+        raise ArgumentError, "digit must be between 0 and #{w - 1}." unless d.is_a?(Integer) && d >= 0 && d < w
+
+        csum += w - 1 - d
+      end
+      csum <<= @csum_shift
+      bytes = Array.new(@csum_bytes) { |i| (csum >> (8 * (@csum_bytes - 1 - i))) & 0xFF }
+      bytes.pack('C*')
+    end
+
+    # The +len+ base w digits signed for +msg+: the message digits followed by the checksum digits.
+    # @param [String] msg Binary string of +n+ bytes.
+    # @return [Array<Integer>]
+    # @raise ArgumentError
+    def digits(msg)
+      check_value!(msg, 'msg')
+      msg_digits = base_w(msg, len1)
+      msg_digits + base_w(checksum_bytes(msg_digits), len2)
+    end
+
+    # Walk +steps+ steps of chain +chain_idx+ from position +start+.
+    # @param hasher
+    # @param [String] x Binary string of +n+ bytes, the value at position +start+.
+    # @param [Integer] chain_idx
+    # @param [Integer] start
+    # @param [Integer] steps
+    # @return [String] Binary string of +n+ bytes, the value at position +start+ + +steps+.
+    # @raise ArgumentError
+    def chain(hasher, x, chain_idx, start, steps)
+      check_value!(x, 'x')
+      raise ArgumentError, 'chain_idx must be integer.' unless chain_idx.is_a?(Integer)
+      raise ArgumentError, "chain_idx must be between 0 and #{len - 1}." unless chain_idx >= 0 && chain_idx < len
+      raise ArgumentError, 'start must be integer.' unless start.is_a?(Integer)
+      raise ArgumentError, 'steps must be integer.' unless steps.is_a?(Integer)
+      raise ArgumentError, 'start must not be negative.' if start.negative?
+      raise ArgumentError, 'steps must not be negative.' if steps.negative?
+      raise ArgumentError, 'Invalid range' if start + steps > w - 1
+
+      steps.times do |j|
+        x = hasher.step(x, chain_idx, start + j)
+      end
+      check_value!(x, 'hasher#step result') if steps.positive?
+      x
+    end
+
+    # Generate the public key (RFC 8391 WOTS_genPK, FIPS 205 Algorithm 6).
+    # @param hasher
+    # @return The result of +hasher.compress+.
+    def pk_gen(hasher)
+      values = Array.new(len) do |i|
+        chain(hasher, secret(hasher, i), i, 0, w - 1)
+      end
+      hasher.compress(values)
+    end
+
+    # Sign +msg+ (RFC 8391 WOTS_sign, FIPS 205 Algorithm 7).
+    # @param hasher
+    # @param [String] msg Binary string of +n+ bytes.
+    # @return [Array<String>] +len+ binary strings of +n+ bytes.
+    # @raise ArgumentError
+    def sign(hasher, msg)
+      ds = digits(msg)
+      Array.new(len) do |i|
+        chain(hasher, secret(hasher, i), i, 0, ds[i])
+      end
+    end
+
+    # Compute the public key from a signature (RFC 8391 WOTS_pkFromSig, FIPS 205 Algorithm 8).
+    # @param hasher
+    # @param [Array<String>] sig +len+ binary strings of +n+ bytes.
+    # @param [String] msg Binary string of +n+ bytes.
+    # @return The result of +hasher.compress+.
+    # @raise ArgumentError
+    def pk_from_sig(hasher, sig, msg)
+      raise ArgumentError, 'sig must be Array.' unless sig.is_a?(Array)
+      raise ArgumentError, "sig must have #{len} elements." unless sig.length == len
+
+      sig.each { |s| check_value!(s, 'sig element') }
+      ds = digits(msg)
+      values = Array.new(len) do |i|
+        chain(hasher, sig[i], i, ds[i], w - 1 - ds[i])
+      end
+      hasher.compress(values)
+    end
+
+    private
+
+    def secret(hasher, chain_idx)
+      sk = hasher.secret(chain_idx)
+      check_value!(sk, 'hasher#secret result')
+      sk
+    end
+
+    def check_value!(value, name)
+      raise ArgumentError, "#{name} must be string." unless value.is_a?(String)
+      raise ArgumentError, "#{name} must be #{n} bytes." unless value.bytesize == n
+    end
+  end
+end

data/lib/wots/param.rb

@@ -1,4 +1,4 @@
-require 'openssl'
+require 'sha3'
 
 module WOTS
   # WOTS+ parameters defined in rfc8391.
@@ -10,126 +10,193 @@ module WOTS
     autoload :SHA512, 'wots/param/sha512'
     autoload :SHAKE256, 'wots/param/shake256'
 
+    # The parameter sets defined in RFC 8391 and the +n+ they require.
+    # WOTSP-SHAKE_256 uses SHAKE128 with a 256-bit output (RFC 8391 Section 5.1 and 5.2).
+    SUPPORTED_NAMES = {
+      'WOTSP-SHA2_256' => 32,
+      'WOTSP-SHA2_512' => 64,
+      'WOTSP-SHAKE_256' => 32
+    }.freeze
+
+    # The Winternitz parameter is a member of the set {4, 16}.
+    # Other values break the checksum encoding and allow signature forgery.
+    SUPPORTED_W = Core::SUPPORTED_W
+
+    # Domain separation prefixes of the keyed hash functions (RFC 8391 Section 5.1,
+    # and NIST SP 800-208 Section 5 for PRF_KEYGEN).
+    F = 0
+    H = 1
+    H_MSG = 2
+    PRF = 3
+    PRF_KEYGEN = 4
+
+    # The byte lengths of KEY and M accepted by each keyed hash function, as multiples of n
+    # plus a constant: [[key_n, key_extra], [message_n, message_extra]], or nil for any length.
+    # RFC 8391 Section 3.1.1.1 (F, PRF), Section 4.1.2 (H, H_msg), NIST SP 800-208 Section 6.2
+    # (PRF_keygen, whose M is SEED || ADRS).
+    INPUT_LENGTHS = {
+      F => [[1, 0], [1, 0]],
+      H => [[1, 0], [2, 0]],
+      H_MSG => [[3, 0], nil],
+      PRF => [[1, 0], [0, 32]],
+      PRF_KEYGEN => [[1, 0], [1, 32]]
+    }.freeze
+    private_constant :INPUT_LENGTHS
+
     attr_reader :name
     attr_reader :n
     attr_reader :w
+    # @return [WOTS::Core] The WOTS+ engine for this parameter set.
+    attr_reader :core
 
     # @param [Hash] opts
+    # @option opts [String] :name the name of the parameter set; it is a member of +SUPPORTED_NAMES+.
     # @option opts [Integer] :n the message length as well as the length of a private key,
     # public key, or signature element in bytes.
     # @option opts [Integer] :w the Winternitz parameter; it is a member of the set {4, 16}.
-    # @option opts [Integer] :len the number of n-byte string elements in a WOTS+ private key, public key, and signature.
+    # @raise ArgumentError
     def initialize(opts)
       raise ArgumentError, 'name must be string.' unless opts[:name].is_a?(String)
       raise ArgumentError, 'n must be integer.' unless opts[:n].is_a?(Integer)
       raise ArgumentError, 'w must be integer.' unless opts[:w].is_a?(Integer)
 
-      @name = opts[:name]
+      expected_n = SUPPORTED_NAMES[opts[:name]]
+      raise ArgumentError, "name must be one of #{SUPPORTED_NAMES.keys.join(', ')}." if expected_n.nil?
+      raise ArgumentError, "n must be #{expected_n} for #{opts[:name]}." unless opts[:n] == expected_n
+      raise ArgumentError, "w must be one of #{SUPPORTED_W.join(', ')}." unless SUPPORTED_W.include?(opts[:w])
+
+      @name = opts[:name].dup.freeze
       @n = opts[:n]
       @w = opts[:w]
+      @core = Core.new(n: n, w: w)
+      freeze
+    end
+
+    # log2(w), i.e. the number of bits consumed by a single base w digit.
+    # @return [Integer]
+    def lg_w
+      core.lg_w
     end
 
     def len1
-      @len1 ||= (8.0 * n / Math.log2(w)).ceil
+      core.len1
     end
 
     def len2
-      @len2 ||= (Math.log2(len1 * (w - 1)) / Math.log2(w)).floor + 1
+      core.len2
     end
 
     def len
-      @len ||= len1 + len2
+      core.len
     end
 
+    # @param [String] k Hex string of +n+ bytes.
+    # @param [String] m Hex string of +n+ bytes.
+    # @return [String] Hex string.
     def f(k, m)
-      keyed_hash(0, k, m)
+      keyed_hash(F, k, m)
     end
 
+    # @param [String] k Hex string of +n+ bytes.
+    # @param [String] m Hex string of 2n bytes.
+    # @return [String] Hex string.
     def h(k, m)
-      keyed_hash(1, k, m)
+      keyed_hash(H, k, m)
     end
 
+    # @param [String] k Hex string of 3n bytes.
+    # @param [String] m Hex string.
+    # @return [String] Hex string.
     def h_msg(k, m)
-      keyed_hash(2, k, m)
+      keyed_hash(H_MSG, k, m)
     end
 
     # PRF function.
-    # @param [String] k key
-    # @param [String] m message
+    # @param [String] k key Hex string of +n+ bytes.
+    # @param [String] m message Hex string of 32 bytes.
     # @return [String] Hex string.
     def prf(k, m)
-      keyed_hash(3, k, m)
+      keyed_hash(PRF, k, m)
+    end
+
+    # PRF used for pseudorandom key generation (NIST SP 800-208 Section 5).
+    # RFC 8391 does not define it; SP 800-208 defines it with the domain separation prefix 4,
+    # which is also what the XMSS reference implementation uses for every parameter set.
+    # @param [String] k key Hex string of +n+ bytes.
+    # @param [String] m message Hex string of n + 32 bytes (SEED || ADRS).
+    # @return [String] Hex string.
+    def prf_keygen(k, m)
+      keyed_hash(PRF_KEYGEN, k, m)
+    end
+
+    # The keyed hash functions of RFC 8391 Section 5.1 on binary strings:
+    # Hash(toByte(prefix, n) || KEY || M).
+    # @param [Integer] prefix One of F, H, H_MSG, PRF and PRF_KEYGEN.
+    # @param [String] key Binary string; +n+ bytes, or 3n bytes for H_MSG.
+    # @param [String] message Binary string; n bytes for F, 2n for H, any length for H_MSG,
+    # 32 for PRF and n + 32 for PRF_KEYGEN.
+    # @return [String] Binary string of +n+ bytes.
+    # @raise ArgumentError If +prefix+ is unknown or +key+ or +message+ has the wrong length.
+    def keyed_digest(prefix, key, message)
+      lengths = INPUT_LENGTHS[prefix]
+      raise ArgumentError, 'prefix must be one of F, H, H_MSG, PRF and PRF_KEYGEN.' unless lengths
+      raise ArgumentError, 'key must be string.' unless key.is_a?(String)
+      raise ArgumentError, 'message must be string.' unless message.is_a?(String)
+
+      key_len = lengths[0][0] * n + lengths[0][1]
+      raise ArgumentError, "key must be #{key_len} bytes." unless key.bytesize == key_len
+      if lengths[1]
+        message_len = lengths[1][0] * n + lengths[1][1]
+        raise ArgumentError, "message must be #{message_len} bytes." unless message.bytesize == message_len
+      end
+
+      payload = to_byte(prefix, n) + key.b + message.b
+      case name
+      when 'WOTSP-SHA2_256'
+        Digest::SHA256.digest(payload)
+      when 'WOTSP-SHA2_512'
+        Digest::SHA512.digest(payload)
+      when 'WOTSP-SHAKE_256'
+        # RFC 8391 Section 5.1: SHAKE128(toByte(prefix, 32) || KEY || M, 256)
+        SHA3::Digest::SHAKE_128.new(payload).squeeze(n)
+      else
+        raise 'Unknown param'
+      end
     end
 
     # Convert data as base w representation.
-    # @param [String] data The data to be converted.
+    # @param [String] data The data to be converted. Hex string.
     # @param [Integer] out_len Output length.
     # @return [Array] An array of integer.
+    # @raise ArgumentError If +data+ is too short to produce +out_len+ digits.
     def base_w(data, out_len)
-      x = hex_to_bin(data)
-
-      basew = []
-      in_idx = 0
-      total = 0
-      bits = 0
-      lg_w = Math.log2(w).to_i
-
-      out_len.times do
-        if bits == 0
-          break if in_idx >= x.bytesize
-          total = x.getbyte(in_idx)
-          in_idx += 1
-          bits += 8
-        end
-
-        bits -= lg_w
-        basew << ((total >> bits) & (w - 1))
-      end
-
-      basew
+      core.base_w(hex_to_bin(data), out_len)
     end
 
     # Compute checksum for +base_w+.
     # @param [Array] base_w
-    # @return [String] Checksum binary string.
+    # @return [String] Checksum hex string.
     def compute_checksum(base_w)
-      c_sum = 0
-      len1.times do |i|
-        c_sum = (c_sum + w - 1 - base_w[i])
-      end
-      c_sum = (c_sum << (8 - ((len2 * Math.log2(w).to_i) % 8)))
-      len_2_bytes = ((len2 * Math.log2(w).to_i) / 8.0).ceil
-      to_byte(c_sum, len_2_bytes)
+      bin_to_hex(core.checksum_bytes(base_w))
     end
 
     # WOTS+ Chaining Function.
+    # The chain address is taken from +addr+; +addr+ itself is not modified.
     # @see https://datatracker.ietf.org/doc/html/rfc8391#autoid-16
-    # @param [String] x Input string.
+    # @param [String] x Input string. Hex string.
     # @param [Integer] start_idx Start index.
     # @param [Integer] steps Number of steps.
-    # @param [String] seed Seed.
+    # @param [String] seed Seed. Hex string.
     # @param [WOTS::Address] addr Address.
-    # @return [String] Result.
+    # @return [String] Hex string.
+    # @raise ArgumentError
     def chain(x, start_idx, steps, seed, addr)
-      return x if steps == 0
-      raise "Invalid range" if (start_idx + steps) > (w - 1)
-
-      result = x.dup
-
-      steps.times do |i|
-        addr.hash_addr = (start_idx + i)
+      raise ArgumentError, 'x must be hex string.' unless hex_string?(x)
+      raise ArgumentError, 'seed must be hex string.' unless hex_string?(seed)
+      raise ArgumentError, 'addr must be WOTS::Address.' unless addr.is_a?(Address)
 
-        addr.key_and_mask = 0
-        key = prf(seed, addr.to_payload)
-
-        addr.key_and_mask = 1
-        mask = prf(seed, addr.to_payload)
-
-        masked = xor_bytes(result, mask)
-        result = f(key, masked)
-      end
-
-      result
+      hasher = RFC8391Hasher.new(self, pub_seed: hex_to_bin(seed), addr: addr)
+      bin_to_hex(core.chain(hasher, hex_to_bin(x), addr.chain_addr, start_idx, steps))
     end
 
     def ==(other)
@@ -140,8 +207,14 @@ module WOTS
     # Convert +value+ to +length+ size binary string.
     # @param [Integer] value
     # @param [Integer] length
-    # @return [String]
+    # @return [String] Binary string.
+    # @raise ArgumentError If +value+ does not fit in +length+ bytes.
     def to_byte(value, length)
+      raise ArgumentError, 'value must be integer.' unless value.is_a?(Integer)
+      raise ArgumentError, 'length must be integer.' unless length.is_a?(Integer)
+      raise ArgumentError, 'value must not be negative.' if value.negative?
+      raise ArgumentError, "value does not fit in #{length} bytes." if value.bit_length > length * 8
+
       bytes = []
 
       length.times do
@@ -154,24 +227,12 @@ module WOTS
 
     private
 
-    def xor_bytes(a, b)
-      [a].pack('H*').unpack('C*').zip(
-        [b].pack('H*').unpack('C*')
-      ).map { |x, y| x ^ y }.pack("C*")
-    end
-
+    # @param [Integer] prefix Domain separation prefix.
+    # @param [String] k Hex string.
+    # @param [String] m Hex string.
+    # @return [String] Hex string.
     def keyed_hash(prefix, k, m)
-      payload = to_byte(prefix, n) + hex_to_bin(k) + hex_to_bin(m)
-      case name
-      when 'WOTSP-SHA2_256'
-        Digest::SHA256.hexdigest(payload)
-      when 'WOTSP-SHA2_512'
-        Digest::SHA512.hexdigest(payload)
-      when 'WOTSP-SHAKE_256'
-        OpenSSL::Digest.new('shake256', payload).hexdigest
-      else
-        raise 'Unknown param'
-      end
+      bin_to_hex(keyed_digest(prefix, hex_to_bin(k), hex_to_bin(m)))
     end
   end
-end
+end

data/lib/wots/private_key.rb

@@ -17,53 +17,65 @@ module WOTS
       end
 
       @param = param
-      @keys = keys
+      @keys = normalize_hex_array(keys)
     end
 
     # Generate private key using +seed+.
+    # Each element is derived as sk[i] = PRF_keygen(seed, pub_seed || ADRS) with the
+    # chain address of ADRS set to i (NIST SP 800-208 Section 6.2, Algorithm 10').
+    # Binding the key to +pub_seed+ and +addr+ gives every key pair and every OTS address
+    # its own private key, so one +seed+ can derive several keys by using a different
+    # +addr+ (e.g. +ots_addr+) for each of them.
     # @param [WOTS::Param] param
-    # @param [String] seed
+    # @param [String] seed The secret seed. Hex string of +param.n+ bytes.
+    # It must be generated with a cryptographically secure random number generator.
+    # @param [String] pub_seed The public seed. Hex string of +param.n+ bytes.
+    # @param [WOTS::Address] addr The address of this key pair. The same address must be passed
+    # to #sign, PublicKey.from_private_key and PublicKey.from_signature.
+    # @return [WOTS::PrivateKey]
     # @raise ArgumentError
-    def self.from_seed(param, seed)
+    def self.from_seed(param, seed, pub_seed, addr: Address.new)
       raise ArgumentError, "param must be WOTS::Param." unless param.is_a?(WOTS::Param)
-      raise ArgumentError, "seed must be String." unless seed.is_a?(String)
+      raise ArgumentError, "seed must be hex string." unless hex_string?(seed)
       raise ArgumentError, "seed must be #{param.n} bytes." unless hex_to_bin(seed).bytesize == param.n
-      raise ArgumentError, "len parameter too large." if param.len.bit_length > 16
+      raise ArgumentError, 'pub_seed must be hex string.' unless hex_string?(pub_seed)
+      raise ArgumentError, "pub_seed must be #{param.n} bytes." unless hex_to_bin(pub_seed).bytesize == param.n
 
-      keys = param.len.times.map do |i|
-        param.prf(seed, param.to_byte(i, 32))
-      end
+      hasher = RFC8391Hasher.new(param, pub_seed: hex_to_bin(pub_seed), addr: addr, seed: hex_to_bin(seed))
+      keys = Array.new(param.len) { |i| bin_to_hex(hasher.secret(i)) }
 
       PrivateKey.new(param, keys)
     end
 
     # Generate signature.
-    # @param [String] pub_seed The Public seed.
-    # @param [String] message The message to be signed.
+    # WOTS+ is a one-time signature scheme: this private key must be used to sign
+    # one message, once. This library does not track whether a key has been used;
+    # the caller must persist its state (e.g. the next address) to non-volatile
+    # storage before releasing the signature. See "One-time keys" in README.md.
+    # @param [String] pub_seed The Public seed. Hex string of +param.n+ bytes.
+    # @param [String] message The message to be signed. Hex string of +param.n+ bytes.
+    # @param [WOTS::Address] addr The address passed to PrivateKey.from_seed.
     # @return [WOTS::Signature]
     # @raise ArgumentError
-    def sign(pub_seed, message)
+    def sign(pub_seed, message, addr: Address.new)
       raise ArgumentError, 'pub_seed must be hex string.' unless hex_string?(pub_seed)
       raise ArgumentError, "pub_seed must be #{param.n} bytes." unless hex_to_bin(pub_seed).bytesize == param.n
-      raise ArgumentError, "message must be string." unless message.is_a?(String)
+      raise ArgumentError, "message must be hex string." unless hex_string?(message)
       raise ArgumentError, "message must be #{param.n} bytes." unless hex_to_bin(message).bytesize == param.n
 
-      addr = Address.new
-
-      # Convert message to base w
-      base_w = param.base_w(message, param.len1)
-
-      # Compute checksum
-      c_sum = param.compute_checksum(base_w)
-
-      base_w = base_w + param.base_w(c_sum, param.len2)
-
-      sigs = param.len.times.map do |i|
-        addr.chain_addr = i
-        param.chain(keys[i], 0, base_w[i], pub_seed, addr)
-      end
+      hasher = RFC8391Hasher.new(param, pub_seed: hex_to_bin(pub_seed), addr: addr,
+                                        keys: keys.map { |k| hex_to_bin(k) })
+      sigs = param.core.sign(hasher, hex_to_bin(message)).map { |s| bin_to_hex(s) }
 
       Signature.new(param, sigs)
     end
+
+    # Redacted inspect.
+    # The default implementation prints every instance variable, which would
+    # write the whole private key into logs, exception reports and REPL output.
+    # @return [String]
+    def inspect
+      "#<WOTS::PrivateKey param=#{param.name} w=#{param.w} keys=[REDACTED]>"
+    end
   end
 end

data/lib/wots/public_key.rb

@@ -16,56 +16,71 @@ module WOTS
         raise ArgumentError, "key must be #{param.n} bytes." unless hex_to_bin(key).bytesize == param.n
       end
       @param = param
-      @keys = keys
+      @keys = normalize_hex_array(keys)
     end
 
     # Generate public key from +private_key+ and +pub_seed+.
     # @param [WOTS::PrivateKey] private_key
-    # @param [String] pub_seed
-    def self.from_private_key(private_key, pub_seed)
+    # @param [String] pub_seed Hex string of +param.n+ bytes.
+    # @param [WOTS::Address] addr The address passed to PrivateKey.from_seed.
+    # @raise ArgumentError
+    def self.from_private_key(private_key, pub_seed, addr: Address.new)
       raise ArgumentError, 'private_key must be WOTS::PrivateKey.' unless private_key.is_a?(WOTS::PrivateKey)
       param = private_key.param
       raise ArgumentError, 'pub_seed must be hex string.' unless hex_string?(pub_seed)
       raise ArgumentError, "pub_seed must be #{param.n} bytes." unless hex_to_bin(pub_seed).bytesize == param.n
-      addr = WOTS::Address.new
-      keys = param.len.times.map do |i|
-        addr.chain_addr = i
-        sk = private_key.keys[i]
-        param.chain(sk, 0, param.w - 1, pub_seed, addr)
-      end
-      PublicKey.new(private_key.param, keys)
+      hasher = RFC8391Hasher.new(param, pub_seed: hex_to_bin(pub_seed), addr: addr,
+                                        keys: private_key.keys.map { |k| hex_to_bin(k) })
+      keys = param.core.pk_gen(hasher).map { |k| bin_to_hex(k) }
+      PublicKey.new(param, keys)
     end
 
     # Generate public key from +signature+.
     # @param [WOTS::Signature] signature
-    # @param [String] pub_seed
-    # @param [String] message
+    # @param [String] pub_seed Hex string of +param.n+ bytes.
+    # @param [String] message Hex string of +param.n+ bytes.
+    # @param [WOTS::Address] addr The address passed to PrivateKey.from_seed.
     # @return [WOTS::PublicKey]
     # @raise ArgumentError
-    def self.from_signature(signature, pub_seed, message)
+    def self.from_signature(signature, pub_seed, message, addr: Address.new)
+      raise ArgumentError, 'signature must be WOTS::Signature.' unless signature.is_a?(WOTS::Signature)
       param = signature.param
       raise ArgumentError, 'pub_seed must be hex string.' unless hex_string?(pub_seed)
       raise ArgumentError, "pub_seed must be #{param.n} bytes." unless hex_to_bin(pub_seed).bytesize == param.n
-      raise ArgumentError, "message must be string." unless message.is_a?(String)
+      raise ArgumentError, "message must be hex string." unless hex_string?(message)
       raise ArgumentError, "message must be #{param.n} bytes." unless hex_to_bin(message).bytesize == param.n
 
-      base_w = param.base_w(message, param.len1)
-      c_sum = param.compute_checksum(base_w)
-      base_w = base_w + param.base_w(c_sum, param.len2)
+      hasher = RFC8391Hasher.new(param, pub_seed: hex_to_bin(pub_seed), addr: addr)
+      sigs = signature.sigs.map { |s| hex_to_bin(s) }
+      keys = param.core.pk_from_sig(hasher, sigs, hex_to_bin(message)).map { |k| bin_to_hex(k) }
 
-      addr = WOTS::Address.new
+      PublicKey.new(param, keys)
+    end
 
-      keys = param.len.times.map do |i|
-        addr.chain_addr = i
-        param.chain(signature.sigs[i], base_w[i], param.w - 1 - base_w[i], pub_seed, addr)
-      end
+    # Verify +signature+ on +message+.
+    # Invalid input (wrong types or sizes) raises ArgumentError; a well-formed signature
+    # that does not verify, including one made with another parameter set, returns false.
+    # @param [WOTS::Signature] signature
+    # @param [String] pub_seed Hex string of +param.n+ bytes.
+    # @param [String] message Hex string of +param.n+ bytes.
+    # @param [WOTS::Address] addr The address passed to PrivateKey.from_seed.
+    # @return [Boolean]
+    # @raise ArgumentError
+    def verify(signature, pub_seed, message, addr: Address.new)
+      raise ArgumentError, 'signature must be WOTS::Signature.' unless signature.is_a?(WOTS::Signature)
+      return false unless signature.param == param
 
-      PublicKey.new(param, keys)
+      PublicKey.from_signature(signature, pub_seed, message, addr: addr) == self
     end
 
     def ==(other)
       return false unless other.is_a?(PublicKey)
       param == other.param && keys == other.keys
     end
+    alias eql? ==
+
+    def hash
+      [self.class, param.name, param.w, keys].hash
+    end
   end
 end

data/lib/wots/rfc8391_hasher.rb

@@ -0,0 +1,105 @@
+module WOTS
+  # WOTS::Core hasher for the WOTS+ of RFC 8391, bound to one key pair.
+  #
+  # * secret: PRF_keygen(seed, pub_seed || ADRS) (NIST SP 800-208 Section 6.2), or the
+  #   stored private key elements when the key was given explicitly.
+  # * step: RFC 8391 Algorithm 2 (chain), i.e. F(KEY, X xor BM) with KEY and BM derived by PRF.
+  # * compress: the chain end values as they are (an RFC 8391 WOTS+ public key is the array).
+  #
+  # All values are binary strings.
+  class RFC8391Hasher
+    # @param [WOTS::Param] param
+    # @param [String] pub_seed Binary string of +param.n+ bytes.
+    # @param [WOTS::Address] addr The address of the key pair. It is copied, never modified.
+    # @param [String] seed Optional secret seed (binary string of +param.n+ bytes).
+    # @param [Array<String>] keys Optional private key elements (+param.len+ binary strings).
+    # Give at most one of +seed+ and +keys+; with neither, the hasher can only verify.
+    # @raise ArgumentError
+    def initialize(param, pub_seed:, addr:, seed: nil, keys: nil)
+      raise ArgumentError, 'param must be WOTS::Param.' unless param.is_a?(WOTS::Param)
+      raise ArgumentError, 'give at most one of seed and keys.' if seed && keys
+
+      check_value!(param, pub_seed, 'pub_seed')
+      check_value!(param, seed, 'seed') if seed
+      if keys
+        raise ArgumentError, 'keys must be Array.' unless keys.is_a?(Array)
+        raise ArgumentError, "keys must have #{param.len} elements." unless keys.length == param.len
+
+        keys.each { |k| check_value!(param, k, 'key') }
+      end
+
+      @param = param
+      @pub_seed = pub_seed.b.freeze
+      @seed = seed&.b&.freeze
+      @keys = keys&.map { |k| k.b.freeze }&.freeze
+      @addr = Address.copy_of(addr)
+      @keygen_addr = Address.copy_of(addr)
+      @keygen_addr.hash_addr = 0
+      @keygen_addr.key_and_mask = 0
+    end
+
+    # @param [Integer] chain_idx
+    # @return [String]
+    def secret(chain_idx)
+      check_index!(chain_idx, @param.len, 'chain_idx')
+      return @keys[chain_idx] if @keys
+      raise ArgumentError, 'this hasher has no secret seed or private key.' unless @seed
+
+      @keygen_addr.chain_addr = chain_idx
+      @param.keyed_digest(Param::PRF_KEYGEN, @seed, @pub_seed + @keygen_addr.to_payload)
+    end
+
+    # @param [String] x
+    # @param [Integer] chain_idx
+    # @param [Integer] hash_idx
+    # @return [String]
+    def step(x, chain_idx, hash_idx)
+      check_value!(@param, x, 'x')
+      check_index!(chain_idx, @param.len, 'chain_idx')
+      check_index!(hash_idx, @param.w - 1, 'hash_idx')
+
+      @addr.chain_addr = chain_idx
+      @addr.hash_addr = hash_idx
+
+      @addr.key_and_mask = 0
+      key = @param.keyed_digest(Param::PRF, @pub_seed, @addr.to_payload)
+
+      @addr.key_and_mask = 1
+      mask = @param.keyed_digest(Param::PRF, @pub_seed, @addr.to_payload)
+
+      @param.keyed_digest(Param::F, key, xor(x, mask))
+    end
+
+    # @param [Array<String>] values
+    # @return [Array<String>]
+    def compress(values)
+      values
+    end
+
+    # Redacted inspect, so that the secret seed and private key elements never reach
+    # logs, exception reports or REPL output.
+    # @return [String]
+    def inspect
+      secret = if @keys then 'keys' elsif @seed then 'seed' else 'none' end
+      "#<WOTS::RFC8391Hasher param=#{@param.name} w=#{@param.w} secret=#{secret} [REDACTED]>"
+    end
+
+    private
+
+    def xor(a, b)
+      raise ArgumentError, 'length mismatch.' unless a.bytesize == b.bytesize
+
+      a.bytes.zip(b.bytes).map { |i, j| i ^ j }.pack('C*')
+    end
+
+    def check_index!(value, limit, name)
+      raise ArgumentError, "#{name} must be integer." unless value.is_a?(Integer)
+      raise ArgumentError, "#{name} must be between 0 and #{limit - 1}." unless value >= 0 && value < limit
+    end
+
+    def check_value!(param, value, name)
+      raise ArgumentError, "#{name} must be string." unless value.is_a?(String)
+      raise ArgumentError, "#{name} must be #{param.n} bytes." unless value.bytesize == param.n
+    end
+  end
+end

data/lib/wots/signature.rb

@@ -15,7 +15,17 @@ module WOTS
       end
 
       @param = param
-      @sigs = sigs
+      @sigs = normalize_hex_array(sigs)
+    end
+
+    def ==(other)
+      return false unless other.is_a?(Signature)
+      param == other.param && sigs == other.sigs
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, param.name, param.w, sigs].hash
     end
   end
 end

data/lib/wots/util.rb

@@ -2,31 +2,45 @@ module WOTS
   module Util
 
     # Check whether +data+ is hex string or not.
+    # An odd-length string is NOT a valid hex string, since +Array#pack+ would
+    # silently zero-pad it and make two distinct inputs collide. A string in an
+    # encoding that is not ASCII compatible (e.g. UTF-16) is not a hex string either.
     # @param [String] data
     # @return [Boolean]
     # @raise [ArgumentError]
     def hex_string?(data)
       raise ArgumentError, 'data must be string' unless data.is_a?(String)
-      data.match?(/\A[0-9a-fA-F]+\z/)
+      return false unless data.encoding.ascii_compatible?
+
+      data.length.even? && data.match?(/\A[0-9a-fA-F]+\z/)
     end
 
     # Convert hex string +data+ to binary.
-    # @param [String] data
-    # @return [String]
-    # @raise [ArgumentError]
+    # @param [String] data Hex string.
+    # @return [String] Binary string.
+    # @raise [ArgumentError] If +data+ is not a hex string.
     def hex_to_bin(data)
-      raise ArgumentError, 'data must be string' unless data.is_a?(String)
-      hex_string?(data) ? [data].pack('H*') : data
+      raise ArgumentError, 'data must be hex string' unless hex_string?(data)
+      [data].pack('H*')
+    end
+
+    # Normalize the validated hex strings in +values+ to lowercase and freeze them,
+    # so that equality does not depend on letter case and later changes to the
+    # caller's strings or array cannot affect an object that has validated them.
+    # @param [Array<String>] values Hex strings.
+    # @return [Array<String>] A frozen array of frozen lowercase hex strings.
+    def normalize_hex_array(values)
+      values.map { |v| v.downcase.freeze }.freeze
     end
 
     # Convert binary string +data+ to hex string.
-    # @param [String] data
-    # @return [String]
+    # @param [String] data Binary string.
+    # @return [String] Hex string.
     # @raise [ArgumentError]
     def bin_to_hex(data)
       raise ArgumentError, 'data must be string' unless data.is_a?(String)
-      hex_string?(data) ? data : data.unpack1('H*')
+      data.unpack1('H*')
     end
 
   end
-end
+end

data/lib/wots/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WOTS
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/wots.rb

@@ -2,8 +2,10 @@
 require 'digest'
 require_relative "wots/version"
 require_relative 'wots/util'
+require_relative 'wots/core'
 require_relative 'wots/param'
 require_relative 'wots/address'
+require_relative 'wots/rfc8391_hasher'
 require_relative 'wots/private_key'
 require_relative 'wots/public_key'
 require_relative 'wots/signature'

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: wots
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - azuchi
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sha3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
 description: A Ruby implementation of the Winternitz OTS (W-OTS+), as described in
   RFC8391.
 email:
@@ -20,18 +34,21 @@ files:
 - ".rspec"
 - ".ruby-gemset"
 - ".ruby-version"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/wots.rb
 - lib/wots/address.rb
+- lib/wots/core.rb
 - lib/wots/param.rb
 - lib/wots/param/sha256.rb
 - lib/wots/param/sha512.rb
 - lib/wots/param/shake256.rb
 - lib/wots/private_key.rb
 - lib/wots/public_key.rb
+- lib/wots/rfc8391_hasher.rb
 - lib/wots/signature.rb
 - lib/wots/util.rb
 - lib/wots/version.rb
@@ -42,7 +59,8 @@ licenses:
 metadata:
   homepage_uri: https://github.com/azuchi/wots
   source_code_uri: https://github.com/azuchi/wots
-  changelog_uri: https://github.com/azuchi/wots
+  changelog_uri: https://github.com/azuchi/wots/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib