phylax 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e381c418f0f615ce325714db60e7859fb75be0584ed3cef79cdb39cf0a3ab5ce
+  data.tar.gz: 552fd46214a14a2faaa3038ec6f4bbd5a677367fb5e9740d894e8bf3605981bd
+SHA512:
+  metadata.gz: 4c77e2bf51d2a617e664cfc40c40fd91e79700c13d4d1a6ebc954909a24251b8dcc3cb48d84d8d9e5ead11964e3a18e60eaf48ef3ae49d92ac439e6044fe4fa3
+  data.tar.gz: 4901fb8c6cee2d011097a46f500009882475220ce30980676bd6dcbbeeb788be1fc0e948c61d9160ef6cd6971b1549e168bebeb83f44fe38295219ba5d1ec018

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## [0.1.0] - 2026-06-01
+
+Initial release.
+
+- `Phylax::SecretBox` — authenticated AES-256-GCM encryption with automatic,
+  per-message random nonces framed as `nonce ‖ ciphertext ‖ tag`; nonce reuse is
+  impossible through the public API. `seal`/`open` with optional AAD,
+  `generate_key`, and `from_password` (PBKDF2-HMAC-SHA256).
+- `Phylax.sha256/sha384/sha512` and streaming `Phylax::Digest` (non-destructive
+  `#digest` via `BCryptDuplicateHash`).
+- `Phylax.hmac_sha256/sha384/sha512`, streaming `Phylax::HMAC`, and the
+  constant-time `Phylax::HMAC.verify`.
+- `Phylax.pbkdf2` (HMAC-SHA-2 PRF; releases the GVL during derivation).
+- `Phylax.random_bytes` (system-preferred CSPRNG).
+- `Phylax.secure_compare` (constant-time for equal-length inputs).
+- `Phylax.protect` / `Phylax.unprotect` — DPAPI secrets at rest, user or machine
+  scope, optional entropy.
+- Error taxonomy: `Phylax::Error`, `Phylax::AuthenticationError`, `Phylax::OSError`.
+
+Built on the Windows CNG provider (`bcrypt.dll`) and DPAPI (`crypt32.dll`); no
+cryptography is implemented in the gem itself. Windows MSVC (mswin) Ruby only.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ned
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,155 @@
+# phylax
+
+**Misuse-resistant cryptography for Ruby, backed by the Windows CNG provider.**
+
+`phylax` (Greek *φύλαξ*, "guardian") is a thin, **safe-by-default** binding to the
+cryptography Windows already ships and validates: the **Cryptography API: Next
+Generation** (CNG / `bcrypt.dll`) and **DPAPI** (`crypt32.dll`). It implements no
+cryptography of its own — it exposes the operating system's own primitives through
+an ergonomic, hard-to-misuse API.
+
+The design goal is that the *easy* way is the *safe* way:
+
+- **Authenticated encryption that can't be nonce-reused.** `SecretBox` (AES-256-GCM)
+  generates a fresh 96-bit nonce on every `seal` and frames it into the output, so
+  the catastrophic GCM failure mode — reusing a `(key, nonce)` pair — is impossible
+  through the public API. There is no nonce parameter to get wrong.
+- **Decryption is all-or-nothing.** `open` verifies the authentication tag inside the
+  OS call and raises `Phylax::AuthenticationError` rather than ever returning
+  unauthenticated plaintext.
+- **No silent weakening.** A key that isn't exactly 32 bytes is a loud error, not a
+  silently-truncated AES-128 key. Only SHA-2 is accepted — `:md5`/`:sha1` raise.
+- **Constant-time comparison** is provided so you don't verify MACs with `==`.
+
+| What | API |
+|---|---|
+| Secure random | `Phylax.random_bytes(n)` |
+| Hashing (one-shot) | `Phylax.sha256(data)`, `.sha384`, `.sha512` |
+| Hashing (streaming) | `Phylax::Digest.new(:sha256)` |
+| HMAC (one-shot) | `Phylax.hmac_sha256(key, data)`, `.hmac_sha384`, `.hmac_sha512` |
+| HMAC (streaming) | `Phylax::HMAC.new(:sha256, key)`, `Phylax::HMAC.verify(...)` |
+| Key derivation | `Phylax.pbkdf2(password:, salt:, iterations:, length:, hash:)` |
+| Authenticated encryption | `Phylax::SecretBox` (AES-256-GCM) |
+| Constant-time compare | `Phylax.secure_compare(a, b)` |
+| Secrets at rest | `Phylax.protect(data, scope:, entropy:)` / `Phylax.unprotect` |
+
+## Requirements
+
+- **Windows** with a native **MSVC (mswin)** Ruby. Not supported on MinGW/UCRT.
+- Visual Studio 2017+ / Build Tools with the **Desktop development with C++** workload.
+
+## Install
+
+```sh
+gem install phylax
+```
+
+## Authenticated encryption — `SecretBox`
+
+```ruby
+require "phylax"
+
+key = Phylax::SecretBox.generate_key      # 32 cryptographically random bytes
+box = Phylax::SecretBox.new(key)
+
+sealed = box.seal("attack at dawn")       # => nonce ‖ ciphertext ‖ tag (binary)
+box.open(sealed)                          # => "attack at dawn"
+
+# Additional authenticated data (authenticated, not encrypted) — must match.
+sealed = box.seal(payload, aad: "v1:user-42")
+box.open(sealed, aad: "v1:user-42")       # ok
+box.open(sealed, aad: "v1:user-99")       # raises Phylax::AuthenticationError
+
+# Any tampering with the nonce, ciphertext, tag, or aad fails closed:
+box.open(sealed.tap { |s| s.setbyte(20, s.getbyte(20) ^ 1) })
+# => raises Phylax::AuthenticationError (no plaintext is returned)
+```
+
+Derive the key from a password instead (PBKDF2-HMAC-SHA256):
+
+```ruby
+salt = Phylax.random_bytes(16)            # store this alongside the ciphertext
+box  = Phylax::SecretBox.from_password("correct horse battery staple",
+                                       salt: salt, iterations: 600_000)
+```
+
+**Wire format.** `seal` returns `nonce (12 bytes) ‖ ciphertext (= plaintext length) ‖ tag (16 bytes)`,
+so the overhead is a constant `Phylax::SecretBox::OVERHEAD` (28) bytes. This is
+standard AES-256-GCM: a blob from `seal` can be decrypted by any GCM
+implementation (e.g. OpenSSL) given the same key, and vice versa.
+
+## Hashing and HMAC
+
+```ruby
+Phylax.sha256("data")                     # => 32 raw bytes (ASCII-8BIT)
+Phylax.sha256("data").unpack1("H*")       # => hex
+
+# Streaming — non-destructive #digest, so you can keep updating:
+d = Phylax::Digest.new(:sha256)
+d << "chunk one" << "chunk two"
+d.hexdigest
+
+Phylax.hmac_sha256(key, "message")        # keyed MAC, raw bytes
+
+# Verify a MAC the safe way (constant-time, never raises on mismatch):
+Phylax::HMAC.verify(:sha256, key, message, received_tag)   # => true / false
+```
+
+## Key derivation, random, and comparison
+
+```ruby
+Phylax.pbkdf2(password: pw, salt: salt, iterations: 600_000, length: 32)
+Phylax.random_bytes(16)                   # system CSPRNG (CTR_DRBG)
+Phylax.secure_compare(tag_a, tag_b)       # constant-time for equal-length inputs
+```
+
+## Secrets at rest — DPAPI
+
+`protect` encrypts data with a key the OS derives from the current user (default)
+or the machine, so the blob can only be read back on the same machine (and, for
+`:user` scope, by the same user). Great for storing a credential or a `SecretBox`
+key on disk without a master password.
+
+```ruby
+blob = Phylax.protect("api-token-value")          # bound to this Windows user
+Phylax.unprotect(blob)                             # => "api-token-value"
+
+# Optional second secret ("entropy") that must be supplied to unprotect:
+blob = Phylax.protect(secret, entropy: app_salt)
+Phylax.unprotect(blob, entropy: app_salt)
+
+# Machine scope: any account on this machine can unprotect.
+Phylax.protect(secret, scope: :machine)
+```
+
+## Errors
+
+```
+StandardError
+└─ Phylax::Error                 # base for everything phylax raises
+    ├─ Phylax::AuthenticationError  # GCM tag mismatch / tamper, or DPAPI integrity failure
+    └─ Phylax::OSError              # other Windows API failure (#api, #code)
+```
+
+`ArgumentError`/`TypeError` are raised for bad sizes or types *before* any OS call
+(e.g. a key that isn't 32 bytes, an unknown hash, a non-String input).
+
+## Security notes
+
+- **Algorithms.** AES-256-GCM (128-bit tag), SHA-256/384/512, HMAC-SHA-2,
+  PBKDF2-HMAC-SHA-2, `BCryptGenRandom` (SP 800-90A CTR_DRBG). All are the OS's
+  validated implementations; phylax only marshals bytes.
+- **Random-nonce limit.** With random 96-bit nonces, keep a single `SecretBox` key
+  under ~2³² messages (the GCM birthday bound). Rotate keys for very high volume.
+- **`secure_compare` leaks length.** It returns `false` immediately when lengths
+  differ and is constant-time only across equal-length inputs — fine for comparing
+  fixed-length MACs, which is its purpose.
+- **DPAPI tamper detection is best-effort.** Windows may return an error *or*, rarely,
+  succeed with corrupted output on a mangled blob. If you need a hard integrity
+  guarantee, wrap the data in a `SecretBox` (or add your own HMAC) first.
+- **Windows/MSVC only.** The extension links `bcrypt.lib` + `crypt32.lib` and is
+  built with `cl.exe` against a native-MSVC Ruby.
+
+## License
+
+[MIT](LICENSE.txt).

data/ext/phylax/extconf.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+#
+# extconf.rb for the phylax extension — ergonomic Ruby bindings to the Windows
+# Cryptography API: Next Generation (CNG / bcrypt.dll) plus DPAPI (crypt32.dll).
+
+require "mkmf"
+
+unless RbConfig::CONFIG["target_os"] =~ /mswin/
+  abort <<~MSG
+    phylax requires a native Windows MSVC (mswin) Ruby — it binds the Windows
+    CNG primitive provider (bcrypt.dll) and DPAPI (crypt32.dll) and is built
+    with cl.exe. Your Ruby is "#{RbConfig::CONFIG['arch']}".
+  MSG
+end
+
+# CNG primitives (BCrypt*) and DPAPI (CryptProtectData/CryptUnprotectData).
+# Pure C — no -EHsc, so rb_raise/longjmp is the normal, safe error mechanism.
+$libs = [$libs, "bcrypt.lib", "crypt32.lib"].join(" ")
+
+create_makefile("phylax/phylax")