xcrypt 0.1.2-arm-linux → 0.2.0-arm-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21eca2c864456dc81c260c68c09042df2d5977ab4b1e0a7fbc6ecd14a6932ef8
-  data.tar.gz: 3694326527500e11e5a9b67635bf2a394b6c07a7214b56e2c5569c4be464f662
+  metadata.gz: c50664d757de26c075f277815c6436ead82be015ef4a48570985be3e7e37f401
+  data.tar.gz: 874a7514e5936865821f727029ffa910d4c432d5684097e2a941bb8700a0e7f4
 SHA512:
-  metadata.gz: 4bd2246605e4f54a9e6fbeb803676e32fb7bf7d8b17e7abe4f2278de58ad18c7864879e8dfff41941e33e18c3a80ac82a24c0edc048b684a54fdd15e5f500d82
-  data.tar.gz: 5cf3b11c7d3c5bbd9352b5d564a5d3c527e4ee00f944aa45df79fc11352461ed027f3f47e678ee486ee7b1f4854a9c5d685dfddae285b215676eb45d3014d3a8
+  metadata.gz: 1faa01f3db6b917674c5d7bc8f2347e8e72a3aed6cc1e3d77860af35f3042233031a1cb4187a245caed5c9565c63142491aae3e5e0aff2d39d5a28ec33ba490f
+  data.tar.gz: 6325efa1805094021dcf58e2972bafa17cb90711c857b0ad765e378f21e48bdf0e498f5e909cb694d04c17cbaa22d9145dc1efbdcd212e092afc9e2ebc7ba933

data/lib/xcrypt/ffi.rb

@@ -73,6 +73,7 @@ module XCrypt
     # Returns the prefix string of the library's preferred (strongest)
     # hashing method.
     attach_function :crypt_preferred_method, [], :string
+
   end
 
   private_constant :FFI

data/lib/xcrypt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module XCrypt
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/xcrypt/yescrypt.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module XCrypt
+  # Setting-string generation for the yescrypt and scrypt algorithms.
+  #
+  # Both algorithms share a base-64 alphabet and encoding scheme taken from
+  # libxcrypt's +alg-yescrypt-common.c+.  The public methods produce setting
+  # strings that can be passed directly to {XCrypt.crypt}.
+  #
+  # @example Generate a $y$ yescrypt setting
+  #   setting = XCrypt::Yescrypt.generate_setting(n: 16384, r: 8, p: 1)
+  #   hash = XCrypt.crypt("hunter2", setting)
+  #
+  # @example Generate a $7$ scrypt setting
+  #   setting = XCrypt::Yescrypt.generate_scrypt_setting(n: 16384, r: 32, p: 1)
+  #   hash = XCrypt.crypt("hunter2", setting)
+  module Yescrypt
+    extend self
+
+    # -------------------------------------------------------------------------
+    # Flag constants — mirrors alg-yescrypt.h
+    #
+    # These may be OR'd together to form the +flags:+ argument of
+    # {generate_setting}, except that {WORM} stands alone (do not combine
+    # with {RW}).
+    # -------------------------------------------------------------------------
+
+    # Classic scrypt with minimal extensions (t parameter support only).
+    WORM     = 0x001
+
+    # Full yescrypt mode — time-memory tradeoff resistant.
+    RW       = 0x002
+
+    # Number of inner rounds.
+    ROUNDS_3 = 0x000
+    ROUNDS_6 = 0x004
+
+    # Memory-access gather width.
+    GATHER_1 = 0x000
+    GATHER_2 = 0x008
+    GATHER_4 = 0x010
+    GATHER_8 = 0x018
+
+    # Simple mix factor.
+    SIMPLE_1 = 0x000
+    SIMPLE_2 = 0x020
+    SIMPLE_4 = 0x040
+    SIMPLE_8 = 0x060
+
+    # S-box size.
+    SBOX_6K   = 0x000
+    SBOX_12K  = 0x080
+    SBOX_24K  = 0x100
+    SBOX_48K  = 0x180
+    SBOX_96K  = 0x200
+    SBOX_192K = 0x280
+    SBOX_384K = 0x300
+    SBOX_768K = 0x380
+
+    # Recommended defaults: RW mode with 6 rounds, 4-wide gather, 2x simple
+    # mix, and a 12 KiB S-box.
+    DEFAULTS = RW | ROUNDS_6 | GATHER_4 | SIMPLE_2 | SBOX_12K
+
+    # -------------------------------------------------------------------------
+    # Public interface
+    # -------------------------------------------------------------------------
+
+    # Generates a +$y$+ yescrypt setting string from explicit parameters.
+    #
+    # Implements the encoding of libxcrypt's +yescrypt_encode_params_r+
+    # (alg-yescrypt-common.c) in pure Ruby, because that function is not
+    # exported on Linux.
+    #
+    # @param n [Integer] memory/CPU cost; must be a power of 2 greater than 1
+    # @param r [Integer] block size (default: 8)
+    # @param p [Integer] parallelism (default: 1)
+    # @param t [Integer] additional time cost (default: 0)
+    # @param flags [Integer] yescrypt mode flags; see +WORM+/+RW+/+ROUNDS_*+
+    #   etc.; defaults to {DEFAULTS}
+    # @return [String] a +$y$+ setting string
+    # @raise [ArgumentError] if +n+ is not a valid power of 2, or if +flags+
+    #   is an unsupported combination
+    def generate_setting(n:, r: 8, p: 1, t: 0, flags: DEFAULTS)
+      n_log2 = log2_of_power_of_2(n)
+
+      # Compute the "flavor" field exactly as yescrypt_encode_params_r does:
+      #   flags < RW       → flavor = flags  (WORM / pure-scrypt modes)
+      #   flags is valid RW → flavor = RW + (flags >> 2)
+      flavor =
+        if flags < RW
+          flags
+        elsif (flags & 0x3) == RW && flags <= (RW | 0x3fc)
+          RW + (flags >> 2)
+        else
+          raise ArgumentError, "invalid yescrypt flags: 0x#{flags.to_s(16)}"
+        end
+
+      # "have" bitmask indicates which optional fields follow r.
+      have = 0
+      have |= 1 if p != 1
+      have |= 2 if t != 0
+
+      setting = +"$y$"
+      setting << encode_varint(flavor, 0)
+      setting << encode_varint(n_log2, 1)
+      setting << encode_varint(r, 1)
+      if have != 0
+        setting << encode_varint(have, 1)
+        setting << encode_varint(p, 2) if p != 1
+        setting << encode_varint(t, 1) if t != 0
+      end
+      setting << "$"
+      setting << encode_bytes(SecureRandom.random_bytes(32))
+      setting
+    end
+
+    # Generates a +$7$+ scrypt setting string from explicit parameters.
+    #
+    # Encodes the setting using the same base-64 alphabet and field layout as
+    # libxcrypt's +gensalt_scrypt_rn+ (crypt-scrypt.c).
+    #
+    # @param n [Integer] memory/CPU cost; must be a power of 2 greater than 1
+    # @param r [Integer] block size (default: 32)
+    # @param p [Integer] parallelism (default: 1)
+    # @return [String] a +$7$+ setting string
+    # @raise [ArgumentError] if +n+ is not a valid power of 2
+    def generate_scrypt_setting(n:, r: 32, p: 1)
+      n_log2 = log2_of_power_of_2(n)
+
+      setting = +"$7$"
+      setting << B64[n_log2]
+      setting << encode_uint32(r, 30)
+      setting << encode_uint32(p, 30)
+      setting << encode_bytes(SecureRandom.random_bytes(32))
+      setting
+    end
+
+    private
+
+    # Base-64 alphabet shared by yescrypt and scrypt (crypt-style, not RFC 4648).
+    B64 = "./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+
+    # Returns log2(n) after validating that n is a power of 2 greater than 1.
+    def log2_of_power_of_2(n)
+      n_log2 = Integer(Math.log2(n).round)
+      raise ArgumentError, "n must be a power of 2 greater than 1 (got #{n})" unless (1 << n_log2) == n && n > 1
+      n_log2
+    end
+
+    # Variable-length base-64 encoding for yescrypt parameter fields
+    # (encode64_uint32 in alg-yescrypt-common.c, last argument = min).
+    #
+    # The first character of the output encodes both the number of subsequent
+    # characters and the most-significant bits.  The character ranges used are:
+    #   1 char : indices  0..47  (48 distinct values)
+    #   2 chars: indices 48..56  (9 × 64 = 576 additional values)
+    #   3 chars: indices 57..60  (4 × 64² = 16 384 additional values), …
+    def encode_varint(src, min)
+      raise ArgumentError, "value #{src} is below minimum #{min}" if src < min
+
+      src -= min
+      start = 0
+      endv  = 47
+      chars = 1
+      bits  = 0
+
+      loop do
+        count = (endv + 1 - start) << bits
+        break if src < count
+        raise ArgumentError, "value too large for yescrypt varint encoding" if start >= 63
+
+        start = endv + 1
+        endv  = start + (62 - endv) / 2
+        src  -= count
+        chars += 1
+        bits  += 6
+      end
+
+      result = +B64[start + (src >> bits)]
+      (chars - 1).times { bits -= 6; result << B64[(src >> bits) & 0x3f] }
+      result
+    end
+
+    # Fixed-width base-64 encoding of a 32-bit value using +srcbits+ bits,
+    # LSB first (ceil(srcbits/6) output characters).
+    # Used for scrypt's r and p fields (encode64_uint32 in crypt-scrypt.c).
+    def encode_uint32(value, srcbits)
+      out = +""
+      bits = 0
+      while bits < srcbits
+        out << B64[value & 0x3f]
+        value >>= 6
+        bits += 6
+      end
+      out
+    end
+
+    # Encodes a binary string using the fixed-width base-64 scheme, processing
+    # 3 bytes (24 bits) into 4 characters at a time (encode64 in both
+    # alg-yescrypt-common.c and crypt-scrypt.c).
+    def encode_bytes(bytes)
+      out = +""
+      i   = 0
+      while i < bytes.bytesize
+        value = 0
+        bits  = 0
+        while bits < 24 && i < bytes.bytesize
+          value |= bytes.getbyte(i) << bits
+          bits += 8
+          i    += 1
+        end
+        out << encode_uint32(value, bits)
+      end
+      out
+    end
+  end
+end

data/lib/xcrypt.rb

@@ -16,9 +16,19 @@
 #
 # @example Use the generic interface
 #   hash = XCrypt.crypt("hunter2", algorithm: :sha512)
+#
+# @example Generate a yescrypt setting with explicit N, r, p, t, and flags
+#   setting = XCrypt.generate_setting(:yescrypt, n: 16384, r: 8, p: 1, t: 0,
+#                                     flags: XCrypt::YESCRYPT_DEFAULTS)
+#   hash = XCrypt.crypt("hunter2", setting)
+#
+# @example Generate a scrypt ($7$) setting with explicit N, r, p
+#   setting = XCrypt.generate_setting(:scrypt, n: 16384, r: 32, p: 1)
+#   hash = XCrypt.crypt("hunter2", setting)
 module XCrypt
   require "xcrypt/version"
   require "xcrypt/ffi"
+  require "xcrypt/yescrypt"
 
   # Raised when hashing or salt generation fails.  Common causes include an
   # unsupported algorithm, a malformed setting string, or a passphrase that
@@ -122,14 +132,14 @@ module XCrypt
   #   @raise (see #yescrypt)
 
   ALGORITHMS.each_key do |algorithm|
-    define_method(algorithm) do |phrase, setting = nil, cost: nil|
+    define_method(algorithm) do |phrase, setting = nil, cost: nil, n: nil, r: nil, p: nil, t: nil, flags: nil|
       if setting
         setting_algorithm = detect_algorithm(setting)
         if setting_algorithm != algorithm
           raise ArgumentError, "setting algorithm #{setting_algorithm.inspect} does not match expected #{algorithm.inspect}"
         end
       end
-      crypt(phrase, setting, algorithm:, cost:)
+      crypt(phrase, setting, algorithm:, cost:, n:, r:, p:, t:, flags:)
     end
   end
 
@@ -161,12 +171,20 @@ module XCrypt
   #   setting; ignored when +setting+ is already a String
   # @param cost [Integer, nil] work-factor override passed to
   #   {generate_setting}; uses the library default when +nil+
+  # @param n [Integer, nil] explicit N parameter for yescrypt/scrypt; passed
+  #   to {generate_setting} when no +setting+ is provided
+  # @param r [Integer, nil] explicit r parameter; passed to {generate_setting}
+  # @param p [Integer, nil] explicit p parameter; passed to {generate_setting}
+  # @param t [Integer, nil] explicit t parameter (yescrypt only); passed to
+  #   {generate_setting}
+  # @param flags [Integer, nil] explicit yescrypt flags; passed to
+  #   {generate_setting}
   # @return [String] the hashed password
   # @raise [Error] if +crypt_rn+ returns +NULL+, indicating an invalid
   #   setting or an unsupported algorithm
-  def crypt(phrase, setting = nil, algorithm: nil, cost: nil)
+  def crypt(phrase, setting = nil, algorithm: nil, cost: nil, n: nil, r: nil, p: nil, t: nil, flags: nil)
     setting, algorithm = nil, setting if setting.is_a? Symbol
-    setting ||= generate_setting(algorithm, cost:)
+    setting ||= generate_setting(algorithm, cost:, n:, r:, p:, t:, flags:)
     data = ::FFI::MemoryPointer.new(:uint8, FFI::CRYPT_DATA_SIZE)
     result_ptr = FFI.crypt_rn(phrase, setting, data, FFI::CRYPT_DATA_SIZE)
     raise Error, "crypt failed: invalid setting or unsupported algorithm" if result_ptr.null?
@@ -196,19 +214,58 @@ module XCrypt
 
   # Generates a fresh setting string suitable for passing to {crypt}.
   #
-  # Delegates to libxcrypt's +crypt_gensalt_rn+, which draws entropy from
-  # the OS to produce the random salt component.  When +algorithm+ is +nil+,
-  # the library selects its preferred (strongest) algorithm.
+  # When only +algorithm+ and optionally +cost+ are given, delegates to
+  # libxcrypt's +crypt_gensalt_rn+, which draws entropy from the OS.
+  #
+  # When +n+, +r+, +p+, +t+, or +flags+ are supplied the method generates the
+  # setting directly from those parameters instead, delegating to
+  # {XCrypt::Yescrypt}:
+  #
+  # * For +:yescrypt+ (and +:gost_yescrypt+): delegates to
+  #   {XCrypt::Yescrypt.generate_setting}, producing a +$y$+ setting.
+  #   +n+ must be a power of 2 greater than 1; +r+, +p+, +t+, and +flags+
+  #   default to 8, 1, 0, and {XCrypt::Yescrypt::DEFAULTS} respectively.
+  #
+  # * For +:scrypt+: delegates to {XCrypt::Yescrypt.generate_scrypt_setting},
+  #   producing a +$7$+ setting.  +n+ must be a power of 2 (2..2^63); +r+
+  #   and +p+ default to 32 and 1.  +t+ and +flags+ are not used for scrypt.
+  #
+  # When +algorithm+ is +nil+, the library selects its preferred algorithm.
   #
   # @param algorithm [Symbol, nil] the desired algorithm; uses the library
   #   default when +nil+
   # @param cost [Integer, nil] work-factor for the generated setting; a value
-  #   of +0+ selects the library's own default cost
+  #   of +0+ selects the library's own default cost; ignored when +n:+ is set
+  # @param n [Integer, nil] explicit N (memory/CPU cost, must be a power of 2
+  #   greater than 1); yescrypt and scrypt only
+  # @param r [Integer, nil] block size parameter; yescrypt and scrypt only
+  # @param p [Integer, nil] parallelism parameter; yescrypt and scrypt only
+  # @param t [Integer, nil] additional time cost; yescrypt only
+  # @param flags [Integer, nil] yescrypt mode flags; see {XCrypt::Yescrypt}
+  #   constants; yescrypt only; defaults to {XCrypt::Yescrypt::DEFAULTS}
   # @return [String] a setting string beginning with the algorithm prefix
-  # @raise [ArgumentError] if +algorithm+ is not a key in {ALGORITHMS}
-  # @raise [Error] if +crypt_gensalt_rn+ returns +NULL+
-  def generate_setting(algorithm = nil, cost: nil)
-    prefix = ALGORITHMS.fetch(algorithm) { raise ArgumentError, "unknown algorithm: #{algorithm.inspect}" } if algorithm
+  # @raise [ArgumentError] if +algorithm+ is not a key in {ALGORITHMS}, or if
+  #   +n+ is not a power of 2 greater than 1
+  # @raise [Error] if the underlying C call returns +NULL+
+  def generate_setting(algorithm = nil, cost: nil, n: nil, r: nil, p: nil, t: nil, flags: nil)
+    if algorithm
+      ALGORITHMS.key?(algorithm) or raise ArgumentError, "unknown algorithm: #{algorithm.inspect}"
+    end
+
+    if n || r || p || t || flags
+      case algorithm
+      when :yescrypt, :gost_yescrypt, nil
+        return Yescrypt.generate_setting(n: n || 4096, r: r || 8, p: p || 1,
+                                         t: t || 0, flags: flags || Yescrypt::DEFAULTS)
+      when :scrypt
+        return Yescrypt.generate_scrypt_setting(n: n || 16384, r: r || 32, p: p || 1)
+      else
+        raise ArgumentError,
+              "n/r/p/t/flags parameters are only supported for :yescrypt and :scrypt, got #{algorithm.inspect}"
+      end
+    end
+
+    prefix = ALGORITHMS[algorithm]
     cost ||= 0
 
     output = ::FFI::MemoryPointer.new(:char, FFI::CRYPT_GENSALT_OUTPUT_SIZE)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: xcrypt
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: arm-linux
 authors:
 - Konstantin Haase
@@ -64,6 +64,7 @@ files:
 - lib/xcrypt/arm-linux/libxcrypt.so
 - lib/xcrypt/ffi.rb
 - lib/xcrypt/version.rb
+- lib/xcrypt/yescrypt.rb
 homepage: https://github.com/rkh/ruby-xcrypt
 licenses:
 - MIT