xcrypt 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2b8f55233d310005b2decc0bada01ddbaaacece6d1e57e93cdeb7298851b648
-  data.tar.gz: 2d1da401f1fea6e6d87be0eb6360d8880e3797f331f0fb660bc7c8af1124a66a
+  metadata.gz: e50289aa4e577c8954a17b6ee720629448716ba51e93673ff49bce3d065e8260
+  data.tar.gz: 8df23e9c5de9299d05456f52752a6db9f6099234ed958e3f8a49dbd5ab0eff6c
 SHA512:
-  metadata.gz: 0eb73edf196306320c75324107032d804fd86f75e5e59ded5b70021a60c90dcc031933e6959ecce7f6bdb4f3b997a201d48baf189434236a41a47aa0cd910a23
-  data.tar.gz: 6d31efa37e75d163dd9c9f4ac6e16ae4fc160bdde485478aaec135ee54c67b48822530f3cc5b277822c909d20f9a5690b9c666552f74e01f3a5882c4099cf6d1
+  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.1"
+  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.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Konstantin Haase