phylax 0.1.0

data/lib/phylax/version.rb

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

data/lib/phylax.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require "phylax/version"
+require "phylax/phylax" # native extension: Phylax primitives + Digest/HMAC/SecretBox + errors
+
+# phylax — misuse-resistant cryptography for Ruby, backed by the Windows CNG
+# provider (bcrypt.dll) and DPAPI (crypt32.dll).
+#
+# It implements no cryptography itself; it is a thin, hard-to-misuse binding to
+# the operating system's own validated primitives.
+#
+#   key = Phylax::SecretBox.generate_key        # 32 secure random bytes
+#   box = Phylax::SecretBox.new(key)
+#   sealed = box.seal("attack at dawn")         # fresh nonce per call, authenticated
+#   box.open(sealed)                            # => "attack at dawn"
+#
+#   Phylax.sha256("data")                       # raw 32-byte digest
+#   Phylax.hmac_sha256(key, "msg")              # keyed MAC
+#   Phylax.pbkdf2(password: pw, salt: s, iterations: 600_000, length: 32)
+#   Phylax.random_bytes(16)
+#   Phylax.protect(secret)                      # DPAPI, bound to this user
+module Phylax
+  # The only hash algorithms the gem accepts, mapped to their C-side index.
+  HASHES = { sha256: 0, sha384: 1, sha512: 2 }.freeze
+
+  # The C bridge methods are internal plumbing; the public, validated API below
+  # wraps them. Keep them off the public surface so callers can't skip the
+  # keyword/size checks (e.g. a negative PBKDF2 iteration count).
+  private_class_method :__hash, :__hmac, :__pbkdf2, :__protect, :__unprotect
+
+  module_function
+
+  # --- one-shot hashing ----------------------------------------------------
+
+  def sha256(data) = __hash(0, data)
+  def sha384(data) = __hash(1, data)
+  def sha512(data) = __hash(2, data)
+
+  # --- one-shot HMAC -------------------------------------------------------
+
+  def hmac_sha256(key, data) = __hmac(0, key, data)
+  def hmac_sha384(key, data) = __hmac(1, key, data)
+  def hmac_sha512(key, data) = __hmac(2, key, data)
+
+  # --- PBKDF2 key derivation ----------------------------------------------
+
+  # Derive a key from a password and salt. Defaults to HMAC-SHA256.
+  #   password:   secret bytes (String)
+  #   salt:       non-secret bytes (String); must not be empty, >= 16 advised
+  #   iterations: PRF iteration count (Integer >= 1)
+  #   length:     desired key length in bytes (Integer >= 1)
+  #   hash:       :sha256 / :sha384 / :sha512
+  def pbkdf2(password:, salt:, iterations:, length:, hash: :sha256)
+    idx = HASHES.fetch(hash) { raise ArgumentError, "unknown hash #{hash.inspect}" }
+    raise ArgumentError, "iterations must be >= 1" if iterations < 1
+    raise ArgumentError, "length must be >= 1"     if length < 1
+    raise ArgumentError, "salt must not be empty"  if String(salt).empty?
+
+    __pbkdf2(idx, password, salt, iterations, length)
+  end
+
+  # --- DPAPI: protect secrets at rest -------------------------------------
+
+  # Encrypt +data+ with a key the OS derives from the current user (default)
+  # or the machine. The returned opaque blob can only be unprotected on the
+  # same machine (and, for :user scope, by the same user). An optional
+  # +entropy+ string acts as a second secret that must be supplied identically
+  # to #unprotect.
+  def protect(data, scope: :user, entropy: nil)
+    __protect(data, machine_scope!(scope), entropy)
+  end
+
+  # Reverse of #protect. Raises Phylax::AuthenticationError if the blob was
+  # tampered with, the wrong entropy was given, or it belongs to another
+  # user/machine. (DPAPI infers the scope from the blob; +scope+ is validated
+  # for symmetry but does not change the operation.)
+  def unprotect(data, scope: :user, entropy: nil)
+    machine_scope!(scope)
+    __unprotect(data, entropy)
+  end
+
+  def machine_scope!(scope)
+    case scope
+    when :user    then false
+    when :machine then true
+    else raise ArgumentError, "scope must be :user or :machine, got #{scope.inspect}"
+    end
+  end
+  private_class_method :machine_scope!
+
+  # Base class for every error phylax raises.
+  class Error < StandardError; end
+
+  # The data could not be authenticated: a SecretBox ciphertext (or its AAD)
+  # was tampered with or decrypted with the wrong key, or a DPAPI blob failed
+  # its integrity/credential check. Never trust any output when this is raised.
+  class AuthenticationError < Error; end
+
+  # A Windows API returned a failure we surface verbatim. #api names the call;
+  # #code is the NTSTATUS or Win32 error value.
+  class OSError < Error
+    def api  = @api
+    def code = @code
+  end
+
+  # Streaming message digest (SHA-256/384/512).
+  #
+  #   d = Phylax::Digest.new(:sha256)
+  #   d << "chunk one" << "chunk two"
+  #   d.hexdigest            # non-destructive; you may keep updating
+  class Digest
+    # Bytes in the final digest, keyed by algorithm symbol.
+    SIZES = { sha256: 32, sha384: 48, sha512: 64 }.freeze
+
+    attr_reader :name
+
+    def initialize(name)
+      idx = HASHES.fetch(name) { raise ArgumentError, "unknown hash #{name.inspect}" }
+      @name = name
+      _init(idx)
+    end
+
+    def <<(data)
+      update(data)
+    end
+
+    # Discard any fed data and start over.
+    def reset
+      _init(HASHES.fetch(@name))
+      self
+    end
+
+    def hexdigest
+      digest.unpack1("H*")
+    end
+
+    # Convenience: hash +data+ in one call.
+    def self.digest(name, data)
+      new(name).update(data).digest
+    end
+
+    def self.hexdigest(name, data)
+      digest(name, data).unpack1("H*")
+    end
+
+    def size
+      digest_length
+    end
+    alias length size
+
+    def inspect
+      "#<Phylax::Digest #{@name}>"
+    end
+
+    private :_init
+  end
+
+  # Streaming keyed MAC (HMAC-SHA-256/384/512).
+  #
+  #   m = Phylax::HMAC.new(:sha256, key)
+  #   m << "part one" << "part two"
+  #   m.hexdigest
+  class HMAC
+    attr_reader :name
+
+    def initialize(name, key)
+      idx = HASHES.fetch(name) { raise ArgumentError, "unknown hash #{name.inspect}" }
+      @name = name
+      _init(idx, key)
+    end
+
+    def <<(data)
+      update(data)
+    end
+
+    def hexdigest
+      digest.unpack1("H*")
+    end
+
+    def size
+      digest_length
+    end
+    alias length size
+
+    # Compute the MAC of +data+ under +key+ and compare it to +expected_tag+ in
+    # constant time. Returns true/false and never raises on mismatch — the safe
+    # way to verify a MAC.
+    def self.verify(name, key, data, expected_tag)
+      tag = new(name, key).update(data).digest
+      Phylax.secure_compare(tag, expected_tag)
+    end
+
+    def inspect
+      "#<Phylax::HMAC #{@name}>"
+    end
+
+    private :_init
+  end
+
+  # Authenticated symmetric encryption (AES-256-GCM) with a misuse-resistant
+  # API: a fresh 96-bit nonce is generated on every #seal and framed into the
+  # output, so nonce reuse is impossible by construction, and #open refuses to
+  # return anything that fails authentication.
+  class SecretBox
+    KEY_BYTES   = 32
+    NONCE_BYTES = 12
+    TAG_BYTES   = 16
+    OVERHEAD    = NONCE_BYTES + TAG_BYTES # bytes #seal adds over the plaintext
+
+    # A new random 32-byte key.
+    def self.generate_key
+      Phylax.random_bytes(KEY_BYTES)
+    end
+
+    # Derive a box's key from a password via PBKDF2-HMAC-SHA256. +salt+ is
+    # required and should be random and stored alongside the ciphertext.
+    def self.from_password(password, salt:, iterations: 600_000)
+      key = Phylax.pbkdf2(password: password, salt: salt,
+                          iterations: iterations, length: KEY_BYTES, hash: :sha256)
+      new(key)
+    end
+
+    # +key+ must be exactly 32 bytes (e.g. from .generate_key or .from_password).
+    def initialize(key)
+      key = String(key)
+      unless key.bytesize == KEY_BYTES
+        raise ArgumentError, "key must be exactly #{KEY_BYTES} bytes, got #{key.bytesize}"
+      end
+      _init(key)
+    end
+
+    # Encrypt and authenticate +plaintext+. Optional +aad+ (additional
+    # authenticated data) is authenticated but not encrypted, and must be
+    # supplied identically to #open. Returns nonce ‖ ciphertext ‖ tag.
+    def seal(plaintext, aad: nil)
+      _seal(plaintext, aad)
+    end
+
+    # Verify and decrypt a blob from #seal. Raises Phylax::AuthenticationError
+    # if the ciphertext, tag, nonce, or aad don't match (or the blob is too
+    # short to be authentic).
+    def open(sealed, aad: nil)
+      _open(sealed, aad)
+    end
+
+    def inspect
+      "#<Phylax::SecretBox>" # never expose key material
+    end
+
+    private :_init, :_seal, :_open
+  end
+end

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: phylax
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ned
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !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.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !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: vcvars
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+description: |
+  phylax (Greek "guardian") is a thin, safe-by-default binding to the Windows
+  Cryptography API: Next Generation (CNG / bcrypt.dll) and DPAPI. It does not
+  implement any cryptography of its own — it exposes the operating system's own
+  validated primitives through an ergonomic, hard-to-misuse Ruby API: a
+  cryptographically secure RNG, SHA-2 hashing and HMAC (one-shot and streaming),
+  PBKDF2 key derivation, authenticated AES-256-GCM encryption (SecretBox, with
+  nonces generated and framed automatically so reuse is impossible), a
+  constant-time comparison, and DPAPI protect/unprotect for secrets at rest.
+  Windows MSVC (mswin) Ruby only.
+executables: []
+extensions:
+- ext/phylax/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/phylax/extconf.rb
+- ext/phylax/phylax.c
+- lib/phylax.rb
+- lib/phylax/version.rb
+homepage: https://github.com/main-path/phylax
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/main-path/phylax
+  changelog_uri: https://github.com/main-path/phylax/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/main-path/phylax/issues
+  rubygems_mfa_required: 'true'
+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: 3.6.9
+specification_version: 4
+summary: Misuse-resistant cryptography for Ruby, backed by the Windows CNG provider.
+test_files: []