yescrypt 0.1.0

data/ext/yescrypt/yescrypt_ext.c

@@ -0,0 +1,407 @@
+/*
+ * Ruby C extension wrapper for yescrypt.
+ */
+
+#include <ruby.h>
+#include <ruby/thread.h>
+#include <ruby/encoding.h>
+#include <string.h>
+#include <stdlib.h>
+
+#include "yescrypt.h"
+#include "insecure_memzero.h"
+
+static VALUE rb_mYescrypt;
+static VALUE rb_eYescryptError;
+
+/* Cached symbol IDs */
+static ID id_n, id_r, id_p, id_t_param, id_flags, id_outlen;
+static ID id_n_log2, id_salt;
+
+#define MAX_KDF_OUTLEN 1024
+#define MAX_N_LOG2 24
+#define MAX_R 256
+#define MAX_P 256
+#define MAX_T 100
+
+/* Default parameter values (single source of truth for C side) */
+#define DEFAULT_N_LOG2_VAL 12
+#define DEFAULT_R_VAL      32
+#define DEFAULT_P_VAL      1
+#define DEFAULT_T_VAL      0
+#define DEFAULT_FLAGS_VAL  YESCRYPT_DEFAULTS
+
+static void validate_flags(int flags)
+{
+    int base = flags & 0x3; /* lowest 2 bits: WORM/RW/DEFAULTS */
+    if (base > YESCRYPT_DEFAULTS)
+        rb_raise(rb_eArgError, "invalid base flag value: %d", base);
+
+    int extra = flags & ~0x3;
+    int valid_extra = YESCRYPT_ROUNDS_6 | YESCRYPT_GATHER_8 | YESCRYPT_SIMPLE_8;
+    if (extra & ~valid_extra)
+        rb_raise(rb_eArgError, "invalid flags: 0x%x", flags);
+}
+
+/* --- GVL-free structs for kdf and hash_password --- */
+
+struct kdf_nogvl_args {
+    const yescrypt_shared_t *shared;
+    yescrypt_local_t *local;
+    const uint8_t *password;
+    size_t password_len;
+    const uint8_t *salt;
+    size_t salt_len;
+    const yescrypt_params_t *params;
+    uint8_t *buf;
+    size_t buflen;
+    int ret;
+};
+
+static void *kdf_nogvl(void *data)
+{
+    struct kdf_nogvl_args *args = data;
+    args->ret = yescrypt_kdf(
+        args->shared, args->local,
+        args->password, args->password_len,
+        args->salt, args->salt_len,
+        args->params, args->buf, args->buflen);
+    return NULL;
+}
+
+struct hash_nogvl_args {
+    const yescrypt_shared_t *shared;
+    yescrypt_local_t *local;
+    const uint8_t *password;
+    size_t password_len;
+    const uint8_t *setting;
+    uint8_t *buf;
+    size_t buflen;
+    uint8_t *result;
+};
+
+static void *hash_nogvl(void *data)
+{
+    struct hash_nogvl_args *args = data;
+    args->result = yescrypt_r(
+        args->shared, args->local,
+        args->password, args->password_len,
+        args->setting,
+        args->buf, args->buflen);
+    return NULL;
+}
+
+/* --- Cleanup helpers for rb_ensure --- */
+
+struct kdf_cleanup_ctx {
+    yescrypt_shared_t shared;
+    yescrypt_local_t local;
+};
+
+static VALUE kdf_cleanup(VALUE arg)
+{
+    struct kdf_cleanup_ctx *ctx = (struct kdf_cleanup_ctx *)arg;
+    yescrypt_free_local(&ctx->local);
+    yescrypt_free_shared(&ctx->shared);
+    return Qnil;
+}
+
+/*
+ * Yescrypt.kdf(password, salt, n:, r:, p:, flags:, t:, outlen:)
+ *
+ * Low-level KDF function. n, r, p, and flags are required.
+ * Returns raw hash bytes.
+ */
+static VALUE kdf_body(VALUE arg);
+
+struct kdf_call_ctx {
+    VALUE password;
+    VALUE salt;
+    VALUE opts;
+    struct kdf_cleanup_ctx *cleanup;
+};
+
+static VALUE rb_yescrypt_kdf(int argc, VALUE *argv, VALUE self)
+{
+    (void)self;
+    VALUE password, salt, opts;
+    rb_scan_args(argc, argv, "2:", &password, &salt, &opts);
+
+    Check_Type(password, T_STRING);
+    Check_Type(salt, T_STRING);
+
+    if (NIL_P(opts))
+        opts = rb_hash_new();
+
+    struct kdf_cleanup_ctx cleanup;
+    yescrypt_init_shared(&cleanup.shared);
+    yescrypt_init_local(&cleanup.local);
+
+    struct kdf_call_ctx ctx = { password, salt, opts, &cleanup };
+    return rb_ensure(kdf_body, (VALUE)&ctx, kdf_cleanup, (VALUE)&cleanup);
+}
+
+static VALUE kdf_body(VALUE arg)
+{
+    struct kdf_call_ctx *ctx = (struct kdf_call_ctx *)arg;
+
+    VALUE v_N = rb_hash_aref(ctx->opts, ID2SYM(id_n));
+    VALUE v_r = rb_hash_aref(ctx->opts, ID2SYM(id_r));
+    VALUE v_p = rb_hash_aref(ctx->opts, ID2SYM(id_p));
+    VALUE v_t = rb_hash_aref(ctx->opts, ID2SYM(id_t_param));
+    VALUE v_flags = rb_hash_aref(ctx->opts, ID2SYM(id_flags));
+    VALUE v_outlen = rb_hash_aref(ctx->opts, ID2SYM(id_outlen));
+
+    if (NIL_P(v_N) || NIL_P(v_r) || NIL_P(v_p) || NIL_P(v_flags))
+        rb_raise(rb_eArgError, "n, r, p, and flags are required for kdf");
+
+    uint64_t N = NUM2ULL(v_N);
+    uint32_t r = NUM2UINT(v_r);
+    uint32_t p = NUM2UINT(v_p);
+    uint32_t t = NIL_P(v_t) ? 0 : NUM2UINT(v_t);
+    int flags = NUM2INT(v_flags);
+    size_t outlen = NIL_P(v_outlen) ? 32 : NUM2SIZET(v_outlen);
+
+    /* Input validation */
+    if (N == 0 || (N & (N - 1)) != 0)
+        rb_raise(rb_eArgError, "n must be a power of 2");
+    if (N > ((uint64_t)1 << MAX_N_LOG2))
+        rb_raise(rb_eArgError, "n must not exceed 2^%d", MAX_N_LOG2);
+    if (r == 0 || r > MAX_R)
+        rb_raise(rb_eArgError, "r must be between 1 and %d", MAX_R);
+    if (p == 0 || p > MAX_P)
+        rb_raise(rb_eArgError, "p must be between 1 and %d", MAX_P);
+    if (t > MAX_T)
+        rb_raise(rb_eArgError, "t must be between 0 and %d", MAX_T);
+    if (outlen == 0 || outlen > MAX_KDF_OUTLEN)
+        rb_raise(rb_eArgError, "outlen must be between 1 and %d", MAX_KDF_OUTLEN);
+    validate_flags(flags);
+
+    yescrypt_params_t params;
+    params.flags = (yescrypt_flags_t)flags;
+    params.N = N;
+    params.r = r;
+    params.p = p;
+    params.t = t;
+    params.g = 0;
+
+    uint8_t buf[MAX_KDF_OUTLEN];
+
+    /* Pin strings so GC compaction won't move them while GVL is released */
+    VALUE pw_pinned = rb_str_new_frozen(ctx->password);
+    VALUE salt_pinned = rb_str_new_frozen(ctx->salt);
+
+    struct kdf_nogvl_args args;
+    args.shared = &ctx->cleanup->shared;
+    args.local = &ctx->cleanup->local;
+    args.password = (const uint8_t *)RSTRING_PTR(pw_pinned);
+    args.password_len = RSTRING_LEN(pw_pinned);
+    args.salt = (const uint8_t *)RSTRING_PTR(salt_pinned);
+    args.salt_len = RSTRING_LEN(salt_pinned);
+    args.params = &params;
+    args.buf = buf;
+    args.buflen = outlen;
+
+    rb_thread_call_without_gvl(kdf_nogvl, &args, RUBY_UBF_IO, NULL);
+
+    if (args.ret != 0) {
+        insecure_memzero(buf, sizeof(buf));
+        rb_raise(rb_eYescryptError, "yescrypt_kdf failed");
+    }
+
+    VALUE result = rb_str_new((const char *)buf, outlen);
+    insecure_memzero(buf, sizeof(buf));
+    RB_GC_GUARD(pw_pinned);
+    RB_GC_GUARD(salt_pinned);
+    return result;
+}
+
+/*
+ * Yescrypt.gensalt(n_log2:, r:, p:, t:, flags:, salt:)
+ *
+ * Generate a yescrypt setting/salt string.
+ * The salt: parameter is required.
+ */
+static VALUE rb_yescrypt_gensalt(int argc, VALUE *argv, VALUE self)
+{
+    (void)self;
+    VALUE opts;
+    rb_scan_args(argc, argv, "0:", &opts);
+
+    if (NIL_P(opts))
+        opts = rb_hash_new();
+
+    VALUE v_N = rb_hash_aref(opts, ID2SYM(id_n_log2));
+    VALUE v_r = rb_hash_aref(opts, ID2SYM(id_r));
+    VALUE v_p = rb_hash_aref(opts, ID2SYM(id_p));
+    VALUE v_t = rb_hash_aref(opts, ID2SYM(id_t_param));
+    VALUE v_flags = rb_hash_aref(opts, ID2SYM(id_flags));
+    VALUE v_salt = rb_hash_aref(opts, ID2SYM(id_salt));
+
+    if (NIL_P(v_salt))
+        rb_raise(rb_eArgError, "salt is required");
+
+    Check_Type(v_salt, T_STRING);
+
+    uint32_t N_log2 = NIL_P(v_N) ? DEFAULT_N_LOG2_VAL : NUM2UINT(v_N);
+    uint32_t r = NIL_P(v_r) ? DEFAULT_R_VAL : NUM2UINT(v_r);
+    uint32_t p = NIL_P(v_p) ? DEFAULT_P_VAL : NUM2UINT(v_p);
+    uint32_t t = NIL_P(v_t) ? DEFAULT_T_VAL : NUM2UINT(v_t);
+    int flags = NIL_P(v_flags) ? DEFAULT_FLAGS_VAL : NUM2INT(v_flags);
+
+    /* Input validation */
+    if (N_log2 == 0 || N_log2 > MAX_N_LOG2)
+        rb_raise(rb_eArgError, "n_log2 must be between 1 and %d", MAX_N_LOG2);
+    if (r == 0 || r > MAX_R)
+        rb_raise(rb_eArgError, "r must be between 1 and %d", MAX_R);
+    if (p == 0 || p > MAX_P)
+        rb_raise(rb_eArgError, "p must be between 1 and %d", MAX_P);
+    if (t > MAX_T)
+        rb_raise(rb_eArgError, "t must be between 0 and %d", MAX_T);
+    validate_flags(flags);
+
+    const uint8_t *salt_ptr = (const uint8_t *)RSTRING_PTR(v_salt);
+    size_t salt_len = RSTRING_LEN(v_salt);
+
+    uint8_t buf[YESCRYPT_MAX_ENCODED];
+    uint8_t *result = yescrypt_gensalt(N_log2, r, p, t,
+        (yescrypt_flags_t)flags, salt_ptr, salt_len,
+        buf, sizeof(buf));
+
+    if (!result)
+        rb_raise(rb_eYescryptError, "failed to generate salt");
+
+    VALUE str = rb_str_new_cstr((const char *)result);
+    rb_enc_associate(str, rb_usascii_encoding());
+    OBJ_FREEZE(str);
+    return str;
+}
+
+/*
+ * Yescrypt._hash_password(password, setting)
+ *
+ * Internal: Hash a password using a setting string (from gensalt).
+ * Returns the full encoded hash string (frozen).
+ */
+static VALUE hash_body(VALUE arg);
+
+struct hash_call_ctx {
+    VALUE password;
+    VALUE setting;
+    struct kdf_cleanup_ctx *cleanup;
+};
+
+static VALUE rb_yescrypt_hash(VALUE self, VALUE password, VALUE setting)
+{
+    (void)self;
+    Check_Type(password, T_STRING);
+    Check_Type(setting, T_STRING);
+
+    struct kdf_cleanup_ctx cleanup;
+    yescrypt_init_shared(&cleanup.shared);
+    yescrypt_init_local(&cleanup.local);
+
+    struct hash_call_ctx ctx = { password, setting, &cleanup };
+    return rb_ensure(hash_body, (VALUE)&ctx, kdf_cleanup, (VALUE)&cleanup);
+}
+
+static VALUE hash_body(VALUE arg)
+{
+    struct hash_call_ctx *ctx = (struct hash_call_ctx *)arg;
+
+    uint8_t buf[YESCRYPT_MAX_ENCODED];
+
+    /* Pin strings so GC compaction won't move them while GVL is released */
+    VALUE pw_pinned = rb_str_new_frozen(ctx->password);
+    VALUE setting_pinned = rb_str_new_frozen(ctx->setting);
+
+    struct hash_nogvl_args args;
+    args.shared = &ctx->cleanup->shared;
+    args.local = &ctx->cleanup->local;
+    args.password = (const uint8_t *)RSTRING_PTR(pw_pinned);
+    args.password_len = RSTRING_LEN(pw_pinned);
+    args.setting = (const uint8_t *)RSTRING_PTR(setting_pinned);
+    args.buf = buf;
+    args.buflen = sizeof(buf);
+
+    rb_thread_call_without_gvl(hash_nogvl, &args, RUBY_UBF_IO, NULL);
+
+    RB_GC_GUARD(pw_pinned);
+    RB_GC_GUARD(setting_pinned);
+
+    if (!args.result) {
+        insecure_memzero(buf, sizeof(buf));
+        rb_raise(rb_eYescryptError, "yescrypt hash failed");
+    }
+
+    VALUE str = rb_str_new_cstr((const char *)args.result);
+    insecure_memzero(buf, sizeof(buf));
+    rb_enc_associate(str, rb_usascii_encoding());
+    OBJ_FREEZE(str);
+    return str;
+}
+
+/*
+ * Yescrypt.decode_params(hash_string)
+ *
+ * Parse the parameter segment from an encoded yescrypt string.
+ * Returns a frozen Hash with :n_log2, :r, :p, :t, :flags or nil if invalid.
+ */
+static VALUE rb_yescrypt_decode_params(VALUE self, VALUE str)
+{
+    (void)self;
+    if (NIL_P(str) || TYPE(str) != T_STRING)
+        return Qnil;
+
+    const uint8_t *setting = (const uint8_t *)RSTRING_PTR(str);
+    uint32_t N_log2, r, p, t;
+    yescrypt_flags_t flags;
+
+    const uint8_t *result = yescrypt_decode_params_ext(
+        setting, &N_log2, &r, &p, &t, &flags);
+
+    if (!result)
+        return Qnil;
+
+    VALUE hash = rb_hash_new();
+    rb_hash_aset(hash, ID2SYM(id_n_log2), UINT2NUM(N_log2));
+    rb_hash_aset(hash, ID2SYM(id_r), UINT2NUM(r));
+    rb_hash_aset(hash, ID2SYM(id_p), UINT2NUM(p));
+    rb_hash_aset(hash, ID2SYM(id_t_param), UINT2NUM(t));
+    rb_hash_aset(hash, ID2SYM(id_flags), INT2NUM((int)flags));
+    OBJ_FREEZE(hash);
+    return hash;
+}
+
+void Init_yescrypt_ext(void)
+{
+    /* Cache intern IDs */
+    id_n = rb_intern("n");
+    id_r = rb_intern("r");
+    id_p = rb_intern("p");
+    id_t_param = rb_intern("t");
+    id_flags = rb_intern("flags");
+    id_outlen = rb_intern("outlen");
+    id_n_log2 = rb_intern("n_log2");
+    id_salt = rb_intern("salt");
+
+    rb_mYescrypt = rb_define_module("Yescrypt");
+    rb_eYescryptError = rb_define_class_under(rb_mYescrypt, "Error", rb_eStandardError);
+
+    rb_define_module_function(rb_mYescrypt, "kdf", rb_yescrypt_kdf, -1);
+    rb_define_module_function(rb_mYescrypt, "gensalt", rb_yescrypt_gensalt, -1);
+    rb_define_module_function(rb_mYescrypt, "decode_params", rb_yescrypt_decode_params, 1);
+    rb_define_private_method(rb_singleton_class(rb_mYescrypt), "_hash_password", rb_yescrypt_hash, 2);
+
+    /* Flavor flag constants */
+    rb_define_const(rb_mYescrypt, "WORM", INT2FIX(YESCRYPT_WORM));
+    rb_define_const(rb_mYescrypt, "RW", INT2FIX(YESCRYPT_RW));
+    rb_define_const(rb_mYescrypt, "DEFAULTS", INT2FIX(YESCRYPT_DEFAULTS));
+
+    /* Default parameter constants (single source of truth) */
+    rb_define_const(rb_mYescrypt, "DEFAULT_N_LOG2", INT2FIX(DEFAULT_N_LOG2_VAL));
+    rb_define_const(rb_mYescrypt, "DEFAULT_R", INT2FIX(DEFAULT_R_VAL));
+    rb_define_const(rb_mYescrypt, "DEFAULT_P", INT2FIX(DEFAULT_P_VAL));
+    rb_define_const(rb_mYescrypt, "DEFAULT_T", INT2FIX(DEFAULT_T_VAL));
+    rb_define_const(rb_mYescrypt, "DEFAULT_FLAGS", INT2FIX(DEFAULT_FLAGS_VAL));
+}

data/lib/yescrypt/version.rb

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

data/lib/yescrypt.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "yescrypt/version"
+require "yescrypt/yescrypt_ext"
+require "securerandom"
+require "openssl"
+
+module Yescrypt
+  class << self
+    # High-level: hash a password, returning an encoded string.
+    #
+    # @param password [String] the plaintext password
+    # @param options [Hash] override defaults (n_log2:, r:, p:, t:, flags:)
+    # @return [String] encoded yescrypt hash (starts with "$y$")
+    def create(password, **options)
+      raise TypeError, "no implicit conversion of #{password.class} into String" unless password.is_a?(String)
+      opts = default_params.merge(options)
+      salt = SecureRandom.random_bytes(16)
+      setting = gensalt(
+        n_log2: opts[:n_log2],
+        r: opts[:r],
+        p: opts[:p],
+        t: opts[:t],
+        flags: opts[:flags],
+        salt: salt
+      )
+      _hash_password(password, setting)
+    end
+
+    # High-level: verify a password against an encoded hash.
+    #
+    # @param password [String] the plaintext password
+    # @param hash [String] the encoded hash from .create
+    # @return [Boolean]
+    def verify(password, hash)
+      return false unless password.is_a?(String) && hash.is_a?(String)
+      return false unless hash.start_with?("$y$")
+
+      rehash = _hash_password(password, hash)
+      begin
+        OpenSSL.fixed_length_secure_compare(rehash, hash)
+      rescue ArgumentError
+        false
+      end
+    rescue Error
+      false
+    end
+
+    # Check if hash parameters match the given configuration.
+    #
+    # @param hash [String] encoded hash string
+    # @param options [Hash] expected parameters (n_log2:, r:, p:, t:, flags:)
+    # @return [Boolean]
+    def cost_matches?(hash, **options)
+      params = decode_params(hash)
+      return false unless params
+
+      opts = default_params.merge(options)
+      params[:n_log2] == opts[:n_log2] &&
+        params[:r] == opts[:r] &&
+        params[:p] == opts[:p] &&
+        params[:t] == opts[:t] &&
+        params[:flags] == opts[:flags]
+    end
+
+    # Returns the default parameter hash, derived from constants defined in C.
+    def default_params
+      DEFAULT_PARAMS
+    end
+  end
+
+  DEFAULT_PARAMS = {
+    n_log2: DEFAULT_N_LOG2,
+    r: DEFAULT_R,
+    p: DEFAULT_P,
+    t: DEFAULT_T,
+    flags: DEFAULT_FLAGS
+  }.freeze
+end

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: yescrypt
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Suleyman Musayev
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Ruby C extension wrapping the yescrypt password hashing algorithm. yescrypt
+  is the default password hash in modern Linux distributions (glibc 2.36+). It extends
+  scrypt with pwxform for stronger time-memory tradeoff resistance. Supports YESCRYPT_WORM
+  (scrypt-compatible), YESCRYPT_RW, and YESCRYPT_DEFAULTS flavors.
+email:
+- slmusayev@gmail.com
+executables: []
+extensions:
+- ext/yescrypt/extconf.rb
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- ext/yescrypt/extconf.rb
+- ext/yescrypt/insecure_memzero.h
+- ext/yescrypt/sha256.c
+- ext/yescrypt/sha256.h
+- ext/yescrypt/yescrypt-common.c
+- ext/yescrypt/yescrypt-opt.c
+- ext/yescrypt/yescrypt.h
+- ext/yescrypt/yescrypt_ext.c
+- lib/yescrypt.rb
+- lib/yescrypt/version.rb
+homepage: https://github.com/msuliq/yescrypt
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/msuliq/yescrypt
+  source_code_uri: https://github.com/msuliq/yescrypt
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: 'yescrypt: a memory-hard password hashing function used in modern Linux.'
+test_files: []