epithet 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3695519b4c82955cf40a1d3b5109fbeaf3458085146500eea600c0fa8ce86bb0
-  data.tar.gz: f527803fc071230ae440b9e199f65ad890a0bf8778d643258b0c58b1a0f53b78
+  metadata.gz: 100d3ac2b640a77419d9d6f45228ed67251285ed6f0bf390b9249573d20db887
+  data.tar.gz: 5350064afb6799feec528888c475bcc0d8e403272f13332d00bdcd43b7bcd47c
 SHA512:
-  metadata.gz: 725d659f196c53fc6ea438607dd9319b95b5aac8b61a68c5708b62f9eed26fd76012b3addb45a9a9880952c7275bbc2e5aace3390998c082e6dedd48c76fc174
-  data.tar.gz: aa15ac11d2ae8c1454ce5d086c25fbae5aee1957747e77dfcbdf626c470ddf438df69a3580eee98ecca7131243ed175d53c5edbc245b6b8c3c96b01742cf2914
+  metadata.gz: 77e5c3acde924854471a36ede3d43e010fcf4f2bd7f4a49b75c753e7c80e4c0651355c0c33ec28a9d1c229abf14fd5da61b40c1eae2a23cbd31f8c8ef94cd9a5
+  data.tar.gz: 21a8c95376177e30642bed7aefd1b1f87ccd5f0a00d489592c154ed1ecf86cdf076df57f04f98d01ad802b4ea1c62367b5afcc0fdd165501f95fe081ac10efd9

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.1.0 - 2026-07-14
+
+- Freeze config strings upon object initialization
+- Merge custom scrypt params
+- Block58 now defaults to a generic s2i that handles any block size
+- Optimised 16-byte unrolled s2i selected via `Block58::build`
+- Recognize unprefixed decodes by payload length
+- Fix github CI warnings
+- Write notes on salt & improve examples
+
 ## 1.0.0 - 2026-07-14
 
 ### Breaking changes

data/README.md

@@ -21,12 +21,14 @@ gem install epithet
 
 ## Usage
 
+With `EPITHET_PASSPHRASE="example only"`:
+
 ```ruby
 require 'epithet'
 
 def epithet_initialize
   Epithet.configure(
-    passphrase: ENV.fetch('EPITHET_PASSPHRASE') { 'example only' },
+    passphrase: ENV.fetch('EPITHET_PASSPHRASE'),
     salt: 'v1'
   )
 end

data/SECURITY.md

@@ -2,39 +2,50 @@
 
 ## Cryptographic considerations
 
-The primary construction is `AES-256-ECB(id(8B) + HMAC-SHA256(id)[0,7])` with the result
-base58 encoded for transmission and a contextual prefix prepended. Subkeys for AES and
-HMAC are by default derived with HKDF using an internal key generator that takes IKM from
-a passphrase via scrypt, salting generated keys by prefix and purpose.
-
-This library is intended for high-performance obfuscation of integer sequences, deflection
-of casual tampering, and conversion to a compact, stable wire parameter format that is hard
-to guess and hard to predict.  Although it uses standard cryptographic primitives to do so,
-the design trade-off of the compact format means it is not intended to defeat nation-state
-security services, talented cryptographers, or even a well-resourced enterprise.
-
-The identifiers produced are intentionally deterministic i.e. replayable and reusable. For
-privacy, confidentiality, and authentication purposes they should therefore be considered
-equivalent to the plaintext integer they represent, and those concerns must still be addressed
-in the usual manner.
+The primary construction is `AES-256-ECB(id(8B) + HMAC-SHA256(id)[0,7])` with the result base58
+encoded for transmission and a contextual prefix prepended. Subkeys for AES and HMAC are by default
+derived with HKDF using an internal key generator that takes IKM from a passphrase via scrypt,
+salting generated keys by prefix and purpose.
+
+This library is intended for high-performance obfuscation of integer sequences, deflection of casual
+tampering, and conversion to a compact, stable wire parameter format that is hard to guess and hard
+to predict.  Although it uses standard cryptographic primitives to do so, the design trade-off of
+the compact format means it is not intended to defeat nation-state security services, talented
+cryptographers, or even a well-resourced enterprise.
+
+The identifiers produced are intentionally deterministic i.e. replayable and reusable. For privacy,
+confidentiality, and authentication purposes they should therefore be considered equivalent to the
+plaintext integer they represent, and those concerns must still be addressed in the usual manner.
 
 The tamper detection is necessarily probabilistic, because the MAC is truncated.
 
-Encodings are canonical, producing exactly one string per id, and Epithet will reject attempts
-to decode a value exceeding the 128-bit block.
+Encodings are canonical, producing exactly one string per id, and Epithet will reject attempts to
+decode a value exceeding the 128-bit block.
+
+If configuring alternative cipher algorithms, note that only 128-bit block ciphers that function
+without IV/nonce requirements are accepted. Streaming ciphers (e.g. chacha20) or block ciphers in
+streaming modes (e.g. aes-256-ctr) must not be used; no nonce/IV value is included in construction,
+making them trivially vulnerable to known-plaintext attacks.  These, CBC/OCB, and other IV/nonce
+modes may also be rejected by Epithet's guardrails.
 
-If configuring alternative cipher and digest algorithms, note that only 128-bit block
-ciphers that function without IV/nonce requirements are accepted. Streaming ciphers
-(e.g. chacha20) or block ciphers in streaming modes (e.g. aes-256-ctr) must not be used;
-no nonce/IV value is included in construction, making them trivially vulnerable to
-known-plaintext attacks. These, CBC/OCB, and other IV/nonce modes may also be rejected
-by Epithet's guardrails.
+If configuring alternative digest algorithms, note that any algorithm may be accepted whenever they
+it produces at least 64 bits of output. HMAC does not rest on collision resistance, so even dated
+digests are not trivially forgeable here, but algorithms other than the defaults step outside the
+supported security profile.  If you must stray, stay within the SHA-2 family.
 
-A weak, guessable, or disclosed passphrase will compromise the obfuscation and
-tamper-detection properties.
+A weak, guessable, or disclosed passphrase will compromise the obfuscation and tamper-detection
+properties.
 
 Use Epithet at your own risk.
 
+## On salt
+
+Epithet uses salt in two ways.  Firstly, as part of a scrypt operation to turn the configured
+passphrase into initial keying material.  Secondly, to supply an additional affordance to separate
+derived subkeys by some application-specific division such as purpose or rotation epoch.  Epithet
+does not store or verify passwords; both uses of salt are non-secret configuration and may safely be
+committed to source control.
+
 ## Vulnerabilities
 
 If you think you've found a vulnerability in Epithet that compromises its design or behaviour, please

data/lib/epithet/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 class Epithet
-  # `= '1.0.0'`
-  VERSION = '1.0.0'
+  # `= '1.1.0'`
+  VERSION = '1.1.0'
 end

data/lib/epithet.rb

@@ -46,7 +46,7 @@ class Epithet
   def initialize(prefix, config: Epithet.defaults)
     prefix = String(prefix)
     key_salt = [prefix.bytesize, prefix, config.salt.bytesize, config.salt].pack('Q>Z*Q>Z*')
-    @block58 = Block58.new(16, alphabet: config.alphabet)
+    @block58 = Block58.build(16, alphabet: config.alphabet)
     @prefix_s = "#{prefix}#{config.separator}"
 
     cipher_key_len = OpenSSL::Cipher.new(config.cipher).key_len
@@ -74,12 +74,13 @@ class Epithet
     @prefix_s + @block58.i2s(ct)
   end
 
-  # Decode a prefixed or raw Base58 string to an Integer.
+  # Decode a prefixed or raw Base58 string to an Integer. Raw inputs are
+  # recognised by their exact payload length.
   #
   # Returns the Integer on success, nil if authentication fails.
   # Raises ArgumentError on invalid wire format (see Block58#valid?).
   def decode(s)
-    s = s.delete_prefix(@prefix_s)
+    s = s.delete_prefix(@prefix_s) unless s.bytesize == @block58.size
     raise ArgumentError, 'unexpected format' unless @block58.valid?(s)
 
     d = @decryptor.dup
@@ -104,7 +105,10 @@ class Epithet
     # #### Examples
     #
     #     # As it might appear in an initializer
-    #     Epithet.configure(passphrase: ENV.fetch('EPITHET_PASSPHRASE'))
+    #     Epithet.configure(
+    #       passphrase: ENV.fetch('EPITHET_PASSPHRASE'),
+    #       scrypt: { salt: "#{MyApp.name}/#{MyApp.env}" }
+    #     )
     #
     #     # Retaining already-configured passphrase but updating salt,
     #     # and using a custom separator.
@@ -117,7 +121,7 @@ class Epithet
     # #### Options
     #
     # *   `:passphrase` - Install new key generator with scrypt-derived key material
-    # *   `:scrypt` - Params for scrypt; omit to use `Keygen::DEFAULT_SCRYPT_PARAMS`
+    # *   `:scrypt` - Params for scrypt, merged over `Keygen::DEFAULT_SCRYPT_PARAMS`
     # *   `:keygen` - Install an existing key generator
     # *   `:cipher` - Must be a 128-bit block cipher in ECB mode or equivalent; omit for standard `aes-256-ecb`
     # *   `:digest` - Must be >= 64 bits; omit for standard `sha256`
@@ -162,11 +166,11 @@ class Epithet
 
     def initialize(opts = {})
       opts = opts.dup
-      @separator = String(opts.delete(:separator) { '_' })
-      @salt = String(opts.delete(:salt))
-      @alphabet = String(opts.delete(:alphabet) { Block58::Alphabet })
-      @cipher = opts.delete(:cipher) || 'aes-256-ecb'
-      @digest = opts.delete(:digest) || 'sha256'
+      @separator = -String(opts.delete(:separator) { '_' })
+      @salt = -String(opts.delete(:salt))
+      @alphabet = -String(opts.delete(:alphabet) { Block58::Alphabet })
+      @cipher = -(opts.delete(:cipher) || 'aes-256-ecb')
+      @digest = -(opts.delete(:digest) || 'sha256')
 
       cipher = OpenSSL::Cipher.new(@cipher)
       raise ArgumentError, 'separator intersects alphabet' if @separator.bytes.intersect?(@alphabet.bytes)
@@ -177,8 +181,9 @@ class Epithet
       @keygen = opts.delete(:keygen) || Keygen.new(
         passphrase: opts.delete(:passphrase),
         digest: @digest,
-        scrypt: opts.delete(:scrypt) || Keygen::DEFAULT_SCRYPT_PARAMS)
+        scrypt: opts.delete(:scrypt) || {})
       raise ArgumentError, "unused option(s) #{opts.keys}" unless opts.empty?
+      freeze
     end
   end
 
@@ -204,13 +209,15 @@ class Epithet
     }.freeze
 
     # Create a new key generator from either high-entropy key material, or a supplied passphrase.
-    def initialize(ikm: nil, passphrase: nil, digest: 'sha256', scrypt: DEFAULT_SCRYPT_PARAMS)
+    # Supplied scrypt params are merged over DEFAULT_SCRYPT_PARAMS.
+    def initialize(ikm: nil, passphrase: nil, digest: 'sha256', scrypt: {})
       if (passphrase.nil? && ikm.nil?) || (!passphrase.nil? && !ikm.nil?)
         raise ArgumentError, 'keygen requires either ikm or passphrase'
       end
 
-      @ikm = ikm || OpenSSL::KDF.scrypt(passphrase, **scrypt)
-      @digest = digest
+      @ikm = (ikm ? ikm.b : OpenSSL::KDF.scrypt(passphrase, **DEFAULT_SCRYPT_PARAMS, **scrypt)).freeze
+      @digest = -String(digest)
+      freeze
     end
 
     def inspect
@@ -224,15 +231,27 @@ class Epithet
   end
 
   # Fixed-length Base58 codec for a fixed-size block.
+  #
+  # Obtain codecs via Block58::build, which selects the fastest variant for
+  # the block size, an unrolled decoder for 16-byte blocks, or the generic
+  # chunked decoder otherwise.
   class Block58
     # `= '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'`
     Alphabet = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
 
+    POW58 = Array.new(11) { 58**_1 }.freeze # :nodoc:
+
+    attr_reader :size
+
+    # Same as ::new but may select a tuned subclass for performance.
+    def self.build(block_size, ...) = (block_size == 16 ? Unrolled16 : self).new(block_size, ...)
+
     # Create a codec for a block size in bytes.
     #
     # The alphabet must be 58 distinct bytes in ascending order, so that
     # lexicographic order agrees with numeric order.
     def initialize(block_size, alphabet: Alphabet)
+      raise ArgumentError, 'invalid block size' unless Integer === block_size && block_size > 0
       @alphabet = alphabet.b.freeze
       raise ArgumentError, 'invalid alphabet length' unless @alphabet.bytesize == 58
       raise ArgumentError, 'alphabet not strictly ascending' unless @alphabet.bytes.each_cons(2).all? { _2 > _1 }
@@ -272,44 +291,78 @@ class Epithet
     # Decode a fixed-length Base58 string to an Integer.
     # Assumes the input passes `#valid?`. Wraps at 58**size on the i2s round trip.
     def s2i(str)
-      # rubocop:disable Style/NumericLiterals, Lint/AmbiguousOperatorPrecedence, Layout
-      #
-      # By unrolling coefficients, this is ~8x faster than Horner's scheme
+      # Chunking intermediate results into 64-bit integers is ~5x faster
+      # under YJIT than Horner's scheme
       #
       #   str.each_byte.inject(0) { _1 * 58 + @lut[_2] }
       #
-      # at computing the inner product when using YJIT, by chunking
-      # intermediate results into 64-bit integers.
+      # at computing the inner product.
       lut = @lut
+      size = @size
+      pow = POW58
+      acc = 0
+      pos = 0
+      while pos < size
+        n = size - pos
+        n = 10 if n > 10
+        chunk = 0
+        i = 0
+        while i < n
+          chunk = (chunk * 58) + lut.getbyte(str.getbyte(pos))
+          pos += 1
+          i += 1
+        end
+        acc = (acc * pow[n]) + chunk
+      end
+      acc
+    end
+
+    # Specialised decoder for 16-byte blocks (22 digits) with a fully unrolled inner product.
+    class Unrolled16 < Block58
+      def initialize(...)
+        super
+        raise ArgumentError, 'unrolled codec requires a 16-byte block' unless @size == 22
+      end
+
+      # Decode a fixed-length Base58 string to an Integer.
+      # Assumes the input passes `#valid?`.
+      def s2i(str)
+        # rubocop:disable Style/NumericLiterals, Lint/AmbiguousOperatorPrecedence, Layout
+        #
+        # By unrolling the chunks against literal coefficients, this is ~1.6x
+        # faster under YJIT than the generic chunked Block58#s2i, and ~8x
+        # faster than Horner's scheme.
+        lut = @lut
 
-      acc0 = lut.getbyte(str.getbyte(0)) * 7427658739644928 +
-             lut.getbyte(str.getbyte(1)) * 128063081718016 +
-             lut.getbyte(str.getbyte(2)) * 2207984167552 +
-             lut.getbyte(str.getbyte(3)) * 38068692544 +
-             lut.getbyte(str.getbyte(4)) * 656356768 +
-             lut.getbyte(str.getbyte(5)) * 11316496 +
-             lut.getbyte(str.getbyte(6)) * 195112 +
-             lut.getbyte(str.getbyte(7)) * 3364 +
-             lut.getbyte(str.getbyte(8)) * 58 +
-             lut.getbyte(str.getbyte(9))
-
-      acc1 = lut.getbyte(str.getbyte(10)) * 7427658739644928 +
-             lut.getbyte(str.getbyte(11)) * 128063081718016 +
-             lut.getbyte(str.getbyte(12)) * 2207984167552 +
-             lut.getbyte(str.getbyte(13)) * 38068692544 +
-             lut.getbyte(str.getbyte(14)) * 656356768 +
-             lut.getbyte(str.getbyte(15)) * 11316496 +
-             lut.getbyte(str.getbyte(16)) * 195112 +
-             lut.getbyte(str.getbyte(17)) * 3364 +
-             lut.getbyte(str.getbyte(18)) * 58 +
-             lut.getbyte(str.getbyte(19))
-
-                               lut.getbyte(str.getbyte(21)) +
-                          58 * lut.getbyte(str.getbyte(20)) +
-                        3364 * acc1 +
-      1449225352009601191936 * acc0
-
-      # rubocop:enable Style/NumericLiterals, Lint/AmbiguousOperatorPrecedence, Layout
+        acc0 = lut.getbyte(str.getbyte(0)) * 7427658739644928 +
+               lut.getbyte(str.getbyte(1)) * 128063081718016 +
+               lut.getbyte(str.getbyte(2)) * 2207984167552 +
+               lut.getbyte(str.getbyte(3)) * 38068692544 +
+               lut.getbyte(str.getbyte(4)) * 656356768 +
+               lut.getbyte(str.getbyte(5)) * 11316496 +
+               lut.getbyte(str.getbyte(6)) * 195112 +
+               lut.getbyte(str.getbyte(7)) * 3364 +
+               lut.getbyte(str.getbyte(8)) * 58 +
+               lut.getbyte(str.getbyte(9))
+
+        acc1 = lut.getbyte(str.getbyte(10)) * 7427658739644928 +
+               lut.getbyte(str.getbyte(11)) * 128063081718016 +
+               lut.getbyte(str.getbyte(12)) * 2207984167552 +
+               lut.getbyte(str.getbyte(13)) * 38068692544 +
+               lut.getbyte(str.getbyte(14)) * 656356768 +
+               lut.getbyte(str.getbyte(15)) * 11316496 +
+               lut.getbyte(str.getbyte(16)) * 195112 +
+               lut.getbyte(str.getbyte(17)) * 3364 +
+               lut.getbyte(str.getbyte(18)) * 58 +
+               lut.getbyte(str.getbyte(19))
+
+                                 lut.getbyte(str.getbyte(21)) +
+                            58 * lut.getbyte(str.getbyte(20)) +
+                          3364 * acc1 +
+        1449225352009601191936 * acc0
+
+        # rubocop:enable Style/NumericLiterals, Lint/AmbiguousOperatorPrecedence, Layout
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: epithet
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Josh Goodall