xcrypt 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f004dd771f2475845cede2f1baf42bcbc9ec273aec345028ce8f080e1738aee
-  data.tar.gz: 26c0ebf5fe20acc933888dfcb087e68121c511e01d117a8df7eed342f78a9b1a
+  metadata.gz: e50289aa4e577c8954a17b6ee720629448716ba51e93673ff49bce3d065e8260
+  data.tar.gz: 8df23e9c5de9299d05456f52752a6db9f6099234ed958e3f8a49dbd5ab0eff6c
 SHA512:
-  metadata.gz: f5ef248f2cb841ddde2e0c427c8f7ec44818b744d30955d564fb4b4509e9006d3e58d4bfd5c9200971319f1b9ec75a913dc63b44bc72d9219c6fd05e3003156c
-  data.tar.gz: 6f1a0e554f680f0ed399d17ac607fd2f3b2a851619012a98e440970f4922f1cd03b9ea4dfadff17d459fc5e097ee2a827070b4af3bddc77b7f4a2f8b05a8628b
+  metadata.gz: 1ee8df7d64fdea9f032435f67f886d622f63fbea47dd9f5156a03c45834d446177d807ee4c4ba7ddf3282c65790e695f2a641455fd3a0abd48319d3ee58181a7
+  data.tar.gz: 7acd5509656ba24800a87dcc2d8f6e20e53faeecc8a1bb1d253d21849266c1be9b3cae44c00f9b45d821fe282e850656b1309b0c17d645d27a7b28406ca62e19

data/lib/xcrypt/version.rb

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

data/lib/xcrypt.rb

@@ -1,11 +1,36 @@
 # 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)
 module XCrypt
   require "xcrypt/version"
   require "xcrypt/ffi"
 
+  # 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,6 +50,77 @@ 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|
       if setting
@@ -37,10 +133,37 @@ module XCrypt
     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]
 
+  # 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+
+  # @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)
     setting, algorithm = nil, setting if setting.is_a? Symbol
     setting ||= generate_setting(algorithm, cost:)
@@ -52,6 +175,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,6 +194,19 @@ module XCrypt
     false
   end
 
+  # 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.
+  #
+  # @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
+  # @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
     cost ||= 0
@@ -73,6 +220,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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: xcrypt
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Konstantin Haase
@@ -37,10 +37,25 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
 description: |
   Ruby FFI bindings for libxcrypt, a modern library for one-way hashing of
   passwords.  Supports yescrypt, bcrypt, SHA-512, SHA-256, and other
   algorithms provided by the bundled libxcrypt source (ext/libxcrypt).
+email: ruby-xcrypt@rkh.im
 executables: []
 extensions:
 - Rakefile
@@ -50,40 +65,13 @@ files:
 - ext/libxcrypt/AUTHORS
 - ext/libxcrypt/COPYING.LIB
 - ext/libxcrypt/ChangeLog
-- ext/libxcrypt/INSTALL
 - ext/libxcrypt/LICENSING
 - ext/libxcrypt/Makefile.am
-- ext/libxcrypt/Makefile.in
 - ext/libxcrypt/NEWS
 - ext/libxcrypt/README
 - ext/libxcrypt/README.md
 - ext/libxcrypt/THANKS
-- ext/libxcrypt/TODO
-- ext/libxcrypt/TODO.md
-- ext/libxcrypt/aclocal.m4
 - ext/libxcrypt/autogen.sh
-- ext/libxcrypt/autom4te.cache/output.0
-- ext/libxcrypt/autom4te.cache/output.1
-- ext/libxcrypt/autom4te.cache/output.2
-- ext/libxcrypt/autom4te.cache/output.3
-- ext/libxcrypt/autom4te.cache/requests
-- ext/libxcrypt/autom4te.cache/traces.0
-- ext/libxcrypt/autom4te.cache/traces.1
-- ext/libxcrypt/autom4te.cache/traces.2
-- ext/libxcrypt/autom4te.cache/traces.3
-- ext/libxcrypt/build-aux/ci/ci-log-dependency-versions
-- ext/libxcrypt/build-aux/ci/ci-log-logfiles
-- ext/libxcrypt/build-aux/ci/clang-gcov-wrapper
-- ext/libxcrypt/build-aux/ci/configure-wrapper
-- ext/libxcrypt/build-aux/ci/summarize-coverage
-- ext/libxcrypt/build-aux/m4-autogen/compile
-- ext/libxcrypt/build-aux/m4-autogen/config.guess
-- ext/libxcrypt/build-aux/m4-autogen/config.sub
-- ext/libxcrypt/build-aux/m4-autogen/depcomp
-- ext/libxcrypt/build-aux/m4-autogen/install-sh
-- ext/libxcrypt/build-aux/m4-autogen/ltmain.sh
-- ext/libxcrypt/build-aux/m4-autogen/missing
-- ext/libxcrypt/build-aux/m4-autogen/test-driver
 - ext/libxcrypt/build-aux/m4/ax_append_compile_flags.m4
 - ext/libxcrypt/build-aux/m4/ax_append_flag.m4
 - ext/libxcrypt/build-aux/m4/ax_check_compile_flag.m4
@@ -91,11 +79,6 @@ files:
 - ext/libxcrypt/build-aux/m4/ax_gcc_func_attribute.m4
 - ext/libxcrypt/build-aux/m4/ax_require_defined.m4
 - ext/libxcrypt/build-aux/m4/ax_valgrind_check.m4
-- ext/libxcrypt/build-aux/m4/libtool.m4
-- ext/libxcrypt/build-aux/m4/ltoptions.m4
-- ext/libxcrypt/build-aux/m4/ltsugar.m4
-- ext/libxcrypt/build-aux/m4/ltversion.m4
-- ext/libxcrypt/build-aux/m4/lt~obsolete.m4
 - ext/libxcrypt/build-aux/m4/pkg_compat.m4
 - ext/libxcrypt/build-aux/m4/zw_alignment.m4
 - ext/libxcrypt/build-aux/m4/zw_automodern.m4
@@ -115,9 +98,6 @@ files:
 - ext/libxcrypt/build-aux/scripts/gen-libcrypt-map
 - ext/libxcrypt/build-aux/scripts/move-if-change
 - ext/libxcrypt/build-aux/scripts/skip-if-exec-format-error
-- ext/libxcrypt/codecov.yml
-- ext/libxcrypt/config.h.in
-- ext/libxcrypt/configure
 - ext/libxcrypt/configure.ac
 - ext/libxcrypt/doc/crypt.3
 - ext/libxcrypt/doc/crypt.5
@@ -192,9 +172,6 @@ files:
 - ext/libxcrypt/lib/util-xbzero.c
 - ext/libxcrypt/lib/util-xstrcpy.c
 - ext/libxcrypt/lib/xcrypt.h.in
-- ext/libxcrypt/libxcrypt.spec.rpkg
-- ext/libxcrypt/rpkg.conf
-- ext/libxcrypt/rpkg.macros
 - ext/libxcrypt/test/TestCommon.pm
 - ext/libxcrypt/test/alg-des.c
 - ext/libxcrypt/test/alg-gost3411-2012-hmac.c
@@ -243,6 +220,7 @@ files:
 - lib/xcrypt.rb
 - lib/xcrypt/ffi.rb
 - lib/xcrypt/version.rb
+homepage: https://github.com/rkh/ruby-xcrypt
 licenses:
 - MIT
 metadata: