xcrypt 0.1.1 → 0.2.0

data/ext/libxcrypt/build-aux/m4/lt~obsolete.m4

@@ -0,0 +1,99 @@
+# lt~obsolete.m4 -- aclocal satisfying obsolete definitions.    -*-Autoconf-*-
+#
+#   Copyright (C) 2004-2005, 2007, 2009, 2011-2019, 2021-2024 Free
+#   Software Foundation, Inc.
+#   Written by Scott James Remnant, 2004.
+#
+# This file is free software; the Free Software Foundation gives
+# unlimited permission to copy and/or distribute it, with or without
+# modifications, as long as this notice is preserved.
+
+# serial 5 lt~obsolete.m4
+
+# These exist entirely to fool aclocal when bootstrapping libtool.
+#
+# In the past libtool.m4 has provided macros via AC_DEFUN (or AU_DEFUN),
+# which have later been changed to m4_define as they aren't part of the
+# exported API, or moved to Autoconf or Automake where they belong.
+#
+# The trouble is, aclocal is a bit thick.  It'll see the old AC_DEFUN
+# in /usr/share/aclocal/libtool.m4 and remember it, then when it sees us
+# using a macro with the same name in our local m4/libtool.m4 it'll
+# pull the old libtool.m4 in (it doesn't see our shiny new m4_define
+# and doesn't know about Autoconf macros at all.)
+#
+# So we provide this file, which has a silly filename so it's always
+# included after everything else.  This provides aclocal with the
+# AC_DEFUNs it wants, but when m4 processes it, it doesn't do anything
+# because those macros already exist, or will be overwritten later.
+# We use AC_DEFUN over AU_DEFUN for compatibility with aclocal-1.6.
+#
+# Anytime we withdraw an AC_DEFUN or AU_DEFUN, remember to add it here.
+# Yes, that means every name once taken will need to remain here until
+# we give up compatibility with versions before 1.7, at which point
+# we need to keep only those names which we still refer to.
+
+# This is to help aclocal find these macros, as it can't see m4_define.
+AC_DEFUN([LTOBSOLETE_VERSION], [m4_if([1])])
+
+m4_ifndef([AC_LIBTOOL_LINKER_OPTION],	[AC_DEFUN([AC_LIBTOOL_LINKER_OPTION])])
+m4_ifndef([AC_PROG_EGREP],		[AC_DEFUN([AC_PROG_EGREP])])
+m4_ifndef([_LT_AC_PROG_ECHO_BACKSLASH],	[AC_DEFUN([_LT_AC_PROG_ECHO_BACKSLASH])])
+m4_ifndef([_LT_AC_SHELL_INIT],		[AC_DEFUN([_LT_AC_SHELL_INIT])])
+m4_ifndef([_LT_AC_SYS_LIBPATH_AIX],	[AC_DEFUN([_LT_AC_SYS_LIBPATH_AIX])])
+m4_ifndef([_LT_PROG_LTMAIN],		[AC_DEFUN([_LT_PROG_LTMAIN])])
+m4_ifndef([_LT_AC_TAGVAR],		[AC_DEFUN([_LT_AC_TAGVAR])])
+m4_ifndef([AC_LTDL_ENABLE_INSTALL],	[AC_DEFUN([AC_LTDL_ENABLE_INSTALL])])
+m4_ifndef([AC_LTDL_PREOPEN],		[AC_DEFUN([AC_LTDL_PREOPEN])])
+m4_ifndef([_LT_AC_SYS_COMPILER],	[AC_DEFUN([_LT_AC_SYS_COMPILER])])
+m4_ifndef([_LT_AC_LOCK],		[AC_DEFUN([_LT_AC_LOCK])])
+m4_ifndef([AC_LIBTOOL_SYS_OLD_ARCHIVE],	[AC_DEFUN([AC_LIBTOOL_SYS_OLD_ARCHIVE])])
+m4_ifndef([_LT_AC_TRY_DLOPEN_SELF],	[AC_DEFUN([_LT_AC_TRY_DLOPEN_SELF])])
+m4_ifndef([AC_LIBTOOL_PROG_CC_C_O],	[AC_DEFUN([AC_LIBTOOL_PROG_CC_C_O])])
+m4_ifndef([AC_LIBTOOL_SYS_HARD_LINK_LOCKS], [AC_DEFUN([AC_LIBTOOL_SYS_HARD_LINK_LOCKS])])
+m4_ifndef([AC_LIBTOOL_OBJDIR],		[AC_DEFUN([AC_LIBTOOL_OBJDIR])])
+m4_ifndef([AC_LTDL_OBJDIR],		[AC_DEFUN([AC_LTDL_OBJDIR])])
+m4_ifndef([AC_LIBTOOL_PROG_LD_HARDCODE_LIBPATH], [AC_DEFUN([AC_LIBTOOL_PROG_LD_HARDCODE_LIBPATH])])
+m4_ifndef([AC_LIBTOOL_SYS_LIB_STRIP],	[AC_DEFUN([AC_LIBTOOL_SYS_LIB_STRIP])])
+m4_ifndef([AC_PATH_MAGIC],		[AC_DEFUN([AC_PATH_MAGIC])])
+m4_ifndef([AC_PROG_LD_GNU],		[AC_DEFUN([AC_PROG_LD_GNU])])
+m4_ifndef([AC_PROG_LD_RELOAD_FLAG],	[AC_DEFUN([AC_PROG_LD_RELOAD_FLAG])])
+m4_ifndef([AC_DEPLIBS_CHECK_METHOD],	[AC_DEFUN([AC_DEPLIBS_CHECK_METHOD])])
+m4_ifndef([AC_LIBTOOL_PROG_COMPILER_NO_RTTI], [AC_DEFUN([AC_LIBTOOL_PROG_COMPILER_NO_RTTI])])
+m4_ifndef([AC_LIBTOOL_SYS_GLOBAL_SYMBOL_PIPE], [AC_DEFUN([AC_LIBTOOL_SYS_GLOBAL_SYMBOL_PIPE])])
+m4_ifndef([AC_LIBTOOL_PROG_COMPILER_PIC], [AC_DEFUN([AC_LIBTOOL_PROG_COMPILER_PIC])])
+m4_ifndef([AC_LIBTOOL_PROG_LD_SHLIBS],	[AC_DEFUN([AC_LIBTOOL_PROG_LD_SHLIBS])])
+m4_ifndef([AC_LIBTOOL_POSTDEP_PREDEP],	[AC_DEFUN([AC_LIBTOOL_POSTDEP_PREDEP])])
+m4_ifndef([LT_AC_PROG_EGREP],		[AC_DEFUN([LT_AC_PROG_EGREP])])
+m4_ifndef([LT_AC_PROG_SED],		[AC_DEFUN([LT_AC_PROG_SED])])
+m4_ifndef([_LT_CC_BASENAME],		[AC_DEFUN([_LT_CC_BASENAME])])
+m4_ifndef([_LT_COMPILER_BOILERPLATE],	[AC_DEFUN([_LT_COMPILER_BOILERPLATE])])
+m4_ifndef([_LT_LINKER_BOILERPLATE],	[AC_DEFUN([_LT_LINKER_BOILERPLATE])])
+m4_ifndef([_AC_PROG_LIBTOOL],		[AC_DEFUN([_AC_PROG_LIBTOOL])])
+m4_ifndef([AC_LIBTOOL_SETUP],		[AC_DEFUN([AC_LIBTOOL_SETUP])])
+m4_ifndef([_LT_AC_CHECK_DLFCN],		[AC_DEFUN([_LT_AC_CHECK_DLFCN])])
+m4_ifndef([AC_LIBTOOL_SYS_DYNAMIC_LINKER],	[AC_DEFUN([AC_LIBTOOL_SYS_DYNAMIC_LINKER])])
+m4_ifndef([_LT_AC_TAGCONFIG],		[AC_DEFUN([_LT_AC_TAGCONFIG])])
+m4_ifndef([AC_DISABLE_FAST_INSTALL],	[AC_DEFUN([AC_DISABLE_FAST_INSTALL])])
+m4_ifndef([_LT_AC_LANG_CXX],		[AC_DEFUN([_LT_AC_LANG_CXX])])
+m4_ifndef([_LT_AC_LANG_F77],		[AC_DEFUN([_LT_AC_LANG_F77])])
+m4_ifndef([_LT_AC_LANG_GCJ],		[AC_DEFUN([_LT_AC_LANG_GCJ])])
+m4_ifndef([AC_LIBTOOL_LANG_C_CONFIG],	[AC_DEFUN([AC_LIBTOOL_LANG_C_CONFIG])])
+m4_ifndef([_LT_AC_LANG_C_CONFIG],	[AC_DEFUN([_LT_AC_LANG_C_CONFIG])])
+m4_ifndef([AC_LIBTOOL_LANG_CXX_CONFIG],	[AC_DEFUN([AC_LIBTOOL_LANG_CXX_CONFIG])])
+m4_ifndef([_LT_AC_LANG_CXX_CONFIG],	[AC_DEFUN([_LT_AC_LANG_CXX_CONFIG])])
+m4_ifndef([AC_LIBTOOL_LANG_F77_CONFIG],	[AC_DEFUN([AC_LIBTOOL_LANG_F77_CONFIG])])
+m4_ifndef([_LT_AC_LANG_F77_CONFIG],	[AC_DEFUN([_LT_AC_LANG_F77_CONFIG])])
+m4_ifndef([AC_LIBTOOL_LANG_GCJ_CONFIG],	[AC_DEFUN([AC_LIBTOOL_LANG_GCJ_CONFIG])])
+m4_ifndef([_LT_AC_LANG_GCJ_CONFIG],	[AC_DEFUN([_LT_AC_LANG_GCJ_CONFIG])])
+m4_ifndef([AC_LIBTOOL_LANG_RC_CONFIG],	[AC_DEFUN([AC_LIBTOOL_LANG_RC_CONFIG])])
+m4_ifndef([_LT_AC_LANG_RC_CONFIG],	[AC_DEFUN([_LT_AC_LANG_RC_CONFIG])])
+m4_ifndef([AC_LIBTOOL_CONFIG],		[AC_DEFUN([AC_LIBTOOL_CONFIG])])
+m4_ifndef([_LT_AC_FILE_LTDLL_C],	[AC_DEFUN([_LT_AC_FILE_LTDLL_C])])
+m4_ifndef([_LT_REQUIRED_DARWIN_CHECKS],	[AC_DEFUN([_LT_REQUIRED_DARWIN_CHECKS])])
+m4_ifndef([_LT_AC_PROG_CXXCPP],		[AC_DEFUN([_LT_AC_PROG_CXXCPP])])
+m4_ifndef([_LT_PREPARE_SED_QUOTE_VARS],	[AC_DEFUN([_LT_PREPARE_SED_QUOTE_VARS])])
+m4_ifndef([_LT_PROG_ECHO_BACKSLASH],	[AC_DEFUN([_LT_PROG_ECHO_BACKSLASH])])
+m4_ifndef([_LT_PROG_F77],		[AC_DEFUN([_LT_PROG_F77])])
+m4_ifndef([_LT_PROG_FC],		[AC_DEFUN([_LT_PROG_FC])])
+m4_ifndef([_LT_PROG_CXX],		[AC_DEFUN([_LT_PROG_CXX])])

data/lib/xcrypt/ffi.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "ffi"
-require "ffi-compiler/loader"
 
 module XCrypt
   # Low-level FFI bindings for libxcrypt.
@@ -9,9 +8,9 @@ module XCrypt
   # Consumers should use the high-level {XCrypt} module methods instead of
   # calling into this module directly.
   #
-  # The shared library loaded here is compiled from the libxcrypt submodule
-  # (ext/libxcrypt) via ffi-compiler.  Run <tt>bundle exec rake compile</tt>
-  # to build it before loading this gem.
+  # The shared library loaded here is built from the libxcrypt submodule
+  # (ext/libxcrypt).  Run <tt>bundle exec rake compile</tt> to build it
+  # before loading this gem.
   module FFI
     extend ::FFI::Library
 
@@ -32,11 +31,15 @@ module XCrypt
     CRYPT_SALT_METHOD_LEGACY   = 3
     CRYPT_SALT_TOO_CHEAP       = 4
 
-    # Load the native extension compiled from the libxcrypt submodule.
-    # FFI::Compiler::Loader searches for lib<arch>-<os>/libxcrypt.{bundle,so}
-    # relative to this file's location.
+    # Load the shared library built from the libxcrypt submodule.
+    # It lives in a platform-specific subdirectory next to this file.
     begin
-      ffi_lib ::FFI::Compiler::Loader.find("xcrypt")
+      _ext     = ::FFI::Platform.mac? ? "bundle" : "so"
+      _lib     = File.expand_path(
+        "../#{::FFI::Platform::ARCH}-#{::FFI::Platform::OS}/libxcrypt.#{_ext}",
+        __FILE__
+      )
+      ffi_lib _lib
     rescue LoadError
       raise LoadError,
             "XCrypt native extension not found. " \
@@ -70,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.1"
+  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

@@ -1,11 +1,46 @@
 # frozen_string_literal: true
 
+# Top-level module providing a high-level Ruby interface to libxcrypt, a
+# modern library for one-way hashing of passwords.
+#
+# All public methods are available directly on the module.
+# The most common entry points are the algorithm-specific convenience methods
+# ({yescrypt}, {bcrypt}, {sha512}, etc.) and {verify}.
+#
+# @example Hash a password with yescrypt (the strongest supported algorithm)
+#   hash = XCrypt.yescrypt("correct horse battery staple")
+#   XCrypt.verify("correct horse battery staple", hash) #=> true
+#
+# @example Hash with an explicit cost factor
+#   hash = XCrypt.bcrypt("hunter2", cost: 12)
+#
+# @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
+  # exceeds {FFI::CRYPT_MAX_PASSPHRASE_SIZE} bytes.
   Error ||= Class.new(StandardError)
 
+  # Maps each supported algorithm name to its setting-string prefix.
+  #
+  # The prefix is the leading characters of any hash produced by that
+  # algorithm and is used to identify the algorithm from an existing hash.
+  #
+  # @return [Hash{Symbol => String}]
   ALGORITHMS = {
     yescrypt:      "$y$",
     gost_yescrypt: "$gy$",
@@ -25,25 +60,131 @@ module XCrypt
 
   extend self
 
+  # @!method yescrypt(phrase, setting = nil, cost: nil)
+  #   Hash +phrase+ using yescrypt, the strongest supported algorithm.
+  #   @param phrase [String] the password to hash
+  #   @param setting [String, nil] an existing hash or salt string to use as
+  #     the setting; a new setting is generated automatically when +nil+
+  #   @param cost [Integer, nil] work-factor override; uses the library
+  #     default when +nil+
+  #   @return [String] the hashed password
+  #   @raise [ArgumentError] if +setting+ belongs to a different algorithm
+  #   @raise [Error] if hashing fails
+
+  # @!method gost_yescrypt(phrase, setting = nil, cost: nil)
+  #   Hash +phrase+ using GOST R 34.11-2012 combined with yescrypt.
+  #   @param (see #yescrypt)
+  #   @return (see #yescrypt)
+  #   @raise (see #yescrypt)
+
+  # @!method scrypt(phrase, setting = nil, cost: nil)
+  #   Hash +phrase+ using scrypt.
+  #   @param (see #yescrypt)
+  #   @return (see #yescrypt)
+  #   @raise (see #yescrypt)
+
+  # @!method bcrypt(phrase, setting = nil, cost: nil)
+  #   Hash +phrase+ using bcrypt (Blowfish-based password hashing).
+  #   @param (see #yescrypt)
+  #   @return (see #yescrypt)
+  #   @raise (see #yescrypt)
+
+  # @!method sha512(phrase, setting = nil, cost: nil)
+  #   Hash +phrase+ using SHA-512 crypt.
+  #   @param (see #yescrypt)
+  #   @return (see #yescrypt)
+  #   @raise (see #yescrypt)
+
+  # @!method sha256(phrase, setting = nil, cost: nil)
+  #   Hash +phrase+ using SHA-256 crypt.
+  #   @param (see #yescrypt)
+  #   @return (see #yescrypt)
+  #   @raise (see #yescrypt)
+
+  # @!method sha1(phrase, setting = nil, cost: nil)
+  #   Hash +phrase+ using HMAC-SHA1 NetBSD crypt.
+  #   @param (see #yescrypt)
+  #   @return (see #yescrypt)
+  #   @raise (see #yescrypt)
+
+  # @!method sun_md5(phrase, setting = nil, cost: nil)
+  #   Hash +phrase+ using SunMD5 (Solaris MD5 crypt).
+  #   @param (see #yescrypt)
+  #   @return (see #yescrypt)
+  #   @raise (see #yescrypt)
+
+  # @!method md5(phrase, setting = nil, cost: nil)
+  #   Hash +phrase+ using MD5 crypt.
+  #   @param (see #yescrypt)
+  #   @return (see #yescrypt)
+  #   @raise (see #yescrypt)
+
+  # @!method bsdi_des(phrase, setting = nil, cost: nil)
+  #   Hash +phrase+ using BSDi extended DES crypt.
+  #   @param (see #yescrypt)
+  #   @return (see #yescrypt)
+  #   @raise (see #yescrypt)
+
+  # @!method des(phrase, setting = nil, cost: nil)
+  #   Hash +phrase+ using traditional DES crypt.
+  #   @param (see #yescrypt)
+  #   @return (see #yescrypt)
+  #   @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
 
+  # Returns the names of all supported algorithms.
+  #
+  # @return [Array<Symbol>] algorithm names in order from strongest to weakest
   def algorithms = ALGORITHMS.keys
 
+  # Detects which algorithm produced a given setting or hash string by
+  # matching its leading prefix against {ALGORITHMS}.
+  #
+  # @param setting [String] a setting string or an existing password hash
+  # @return [Symbol, nil] the algorithm name, or +nil+ if the prefix is
+  #   unrecognized
   def detect_algorithm(setting) = PREFIXES[setting[/\A\$\w+\$?|_/].to_s]
 
-  def crypt(phrase, setting = nil, algorithm: nil, cost: nil)
+  # Hashes +phrase+ using libxcrypt's +crypt_rn+ function.
+  #
+  # When both +setting+ and +algorithm+ are omitted, a fresh setting is
+  # generated with the library's default algorithm.  The result is always a
+  # self-describing string whose leading prefix identifies the algorithm and
+  # encodes the salt, making it safe to store directly.
+  #
+  # @param phrase [String] the password to hash
+  # @param setting [String, Symbol, nil] an existing hash or salt string, or
+  #   an algorithm +Symbol+ as shorthand for passing only +algorithm:+;
+  #   generates a fresh setting when +nil+
+  # @param algorithm [Symbol, nil] algorithm to use when generating a new
+  #   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, 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?
@@ -52,6 +193,17 @@ module XCrypt
     data&.clear
   end
 
+  # Verifies that +phrase+ matches a previously computed +hash+.
+  #
+  # Returns +false+ immediately for any hash value that would cause
+  # libxcrypt to return a magic failure token (strings beginning with +"*"+),
+  # or for empty or +nil+ input, guarding against invalid-hash oracle attacks.
+  # The final comparison is performed in constant time to prevent timing
+  # attacks.
+  #
+  # @param phrase [String] the candidate password
+  # @param hash [String, nil] the stored password hash to verify against
+  # @return [Boolean] +true+ if +phrase+ matches +hash+, +false+ otherwise
   def verify(phrase, hash)
     return false if hash.nil? || hash.empty? || hash.start_with?("*")
     result = crypt(phrase, hash)
@@ -60,8 +212,60 @@ module XCrypt
     false
   end
 
-  def generate_setting(algorithm = nil, cost: nil)
-    prefix = ALGORITHMS.fetch(algorithm) { raise ArgumentError, "unknown algorithm: #{algorithm.inspect}" } if algorithm
+  # Generates a fresh setting string suitable for passing to {crypt}.
+  #
+  # 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; 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}, 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)
@@ -73,6 +277,19 @@ module XCrypt
 
   private
 
+  # Compares two strings in constant time to prevent timing attacks.
+  #
+  # Pads or truncates +trusted+ to match +untrusted+'s byte length before
+  # comparing so that the number of loop iterations is always the same
+  # regardless of content.  A separate length check at the end ensures that a
+  # length-padded match is still rejected.
+  #
+  # Uses {OpenSSL.fixed_length_secure_compare} when available (Ruby >= 2.7
+  # with openssl >= 2.2); otherwise falls back to a pure-Ruby XOR loop.
+  #
+  # @param trusted [String] the known-good value (e.g., the output of {crypt})
+  # @param untrusted [String] the value supplied by the caller
+  # @return [Boolean] +true+ only when both strings are identical
   def secure_compare(trusted, untrusted)
     return false unless trusted.respond_to?   :to_str and trusted = trusted.to_str.b
     return false unless untrusted.respond_to? :to_str and untrusted = untrusted.to_str.b