xcrypt 0.1.2-arm-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 21eca2c864456dc81c260c68c09042df2d5977ab4b1e0a7fbc6ecd14a6932ef8
+  data.tar.gz: 3694326527500e11e5a9b67635bf2a394b6c07a7214b56e2c5569c4be464f662
+SHA512:
+  metadata.gz: 4bd2246605e4f54a9e6fbeb803676e32fb7bf7d8b17e7abe4f2278de58ad18c7864879e8dfff41941e33e18c3a80ac82a24c0edc048b684a54fdd15e5f500d82
+  data.tar.gz: 5cf3b11c7d3c5bbd9352b5d564a5d3c527e4ee00f944aa45df79fc11352461ed027f3f47e678ee486ee7b1f4854a9c5d685dfddae285b215676eb45d3014d3a8

data/lib/xcrypt/ffi.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module XCrypt
+  # Low-level FFI bindings for libxcrypt.
+  #
+  # Consumers should use the high-level {XCrypt} module methods instead of
+  # calling into this module directly.
+  #
+  # 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
+
+    # Size constants mirrored from <crypt.h>.
+    CRYPT_OUTPUT_SIZE         = 384
+    CRYPT_MAX_PASSPHRASE_SIZE = 512
+    CRYPT_GENSALT_OUTPUT_SIZE = 192
+    CRYPT_DATA_RESERVED_SIZE  = 767
+    CRYPT_DATA_INTERNAL_SIZE  = 30_720
+
+    # sizeof(struct crypt_data) == 32768 bytes, as guaranteed by the header.
+    CRYPT_DATA_SIZE = 32_768
+
+    # crypt_checksalt(3) return codes.
+    CRYPT_SALT_OK              = 0
+    CRYPT_SALT_INVALID         = 1
+    CRYPT_SALT_METHOD_DISABLED = 2
+    CRYPT_SALT_METHOD_LEGACY   = 3
+    CRYPT_SALT_TOO_CHEAP       = 4
+
+    # Load the shared library built from the libxcrypt submodule.
+    # It lives in a platform-specific subdirectory next to this file.
+    begin
+      _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. " \
+            "Build it with: rake compile"
+    end
+
+    # char *crypt_rn(const char *phrase, const char *setting,
+    #                void *data, int size)
+    #
+    # Thread-safe variant that writes to a caller-supplied buffer.  Returns
+    # NULL on error instead of a magic error string.
+    attach_function :crypt_rn, [:string, :string, :pointer, :int], :pointer
+
+    # char *crypt_gensalt_rn(const char *prefix, unsigned long count,
+    #                        const char *rbytes, int nrbytes,
+    #                        char *output, int output_size)
+    #
+    # Thread-safe salt generator that writes to a caller-supplied buffer.
+    # Pass NULL for rbytes to let the library obtain entropy from the OS.
+    attach_function :crypt_gensalt_rn,
+                    [:string, :ulong, :pointer, :int, :pointer, :int],
+                    :pointer
+
+    # int crypt_checksalt(const char *setting)
+    #
+    # Inspects a setting string and reports whether it is valid.
+    attach_function :crypt_checksalt, [:string], :int
+
+    # const char *crypt_preferred_method(void)
+    #
+    # Returns the prefix string of the library's preferred (strongest)
+    # hashing method.
+    attach_function :crypt_preferred_method, [], :string
+  end
+
+  private_constant :FFI
+end

data/lib/xcrypt/version.rb

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

data/lib/xcrypt.rb

@@ -0,0 +1,249 @@
+# 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$",
+    scrypt:        "$7$",
+    bcrypt:        "$2b$",
+    sha512:        "$6$",
+    sha256:        "$5$",
+    sha1:          "$sha1$",
+    sun_md5:       "$md5",
+    md5:           "$1$",
+    bsdi_des:      "_",
+    des:           "",
+  }.freeze
+
+  PREFIXES = ALGORITHMS.invert.freeze
+  private_constant :ALGORITHMS, :PREFIXES
+
+  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
+        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:)
+    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:)
+    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?
+    result_ptr.read_string
+  ensure
+    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)
+    secure_compare(result, hash)
+  rescue Error
+    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
+
+    output = ::FFI::MemoryPointer.new(:char, FFI::CRYPT_GENSALT_OUTPUT_SIZE)
+    result_ptr = FFI.crypt_gensalt_rn(prefix, cost, nil, 0, output, FFI::CRYPT_GENSALT_OUTPUT_SIZE)
+    raise Error, "crypt_gensalt failed: unknown prefix or unsupported algorithm" if result_ptr.null?
+
+    result_ptr.read_string
+  end
+
+  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
+
+    # avoid ability for attacker to guess length of string by timing attack
+    comparable = trusted[0, untrusted.bytesize].ljust(untrusted.bytesize, "\0".b)
+
+    result = defined?(OpenSSL.fixed_length_secure_compare) ?
+      OpenSSL.fixed_length_secure_compare(comparable, untrusted) :
+      comparable.each_byte.zip(untrusted.each_byte).reduce(0) { |acc, (a, b)| acc | (a ^ b) }.zero?
+
+    trusted.bytesize == untrusted.bytesize and result
+  end
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: xcrypt
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: arm-linux
+authors:
+- Konstantin Haase
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !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'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler-dock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '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: []
+extra_rdoc_files: []
+files:
+- lib/xcrypt.rb
+- lib/xcrypt/arm-linux/libxcrypt.so
+- lib/xcrypt/ffi.rb
+- lib/xcrypt/version.rb
+homepage: https://github.com/rkh/ruby-xcrypt
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/rkh/ruby-xcrypt
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Ruby FFI bindings for libxcrypt
+test_files: []