phylax 0.1.0

data/ext/phylax/phylax.c

@@ -0,0 +1,1024 @@
+/*
+ * phylax — misuse-resistant cryptography for Ruby, backed by the Windows CNG
+ * primitive provider (bcrypt.dll) and DPAPI (crypt32.dll).
+ *
+ * This is a PURE C extension (no C++), so rb_raise/longjmp is the normal, safe
+ * error mechanism — none of the /EHsc unwinder hazard that the lithos C++
+ * engine had to architect around.
+ *
+ * It implements no cryptography of its own. Every primitive is a thin marshal
+ * of Ruby String bytes into a CNG / DPAPI call and back. Algorithm provider
+ * handles are opened once at load and cached for the life of the process
+ * (CNG algorithm handles are documented thread-safe); they are never closed.
+ */
+
+#include <ruby.h>
+#include <ruby/thread.h>
+#include <ruby/encoding.h>
+#include <limits.h>
+
+/* ruby.h already pulls in <windows.h>/<winnt.h>, which define NTSTATUS,
+ * STATUS_SUCCESS and NT_SUCCESS. We only need the CNG/DPAPI declarations on top
+ * of that, plus STATUS_AUTH_TAG_MISMATCH (which lives in ntstatus.h and is
+ * defined locally below to avoid the winnt.h/ntstatus.h redefinition warnings). */
+#include <windows.h>
+#include <wincrypt.h>   /* DATA_BLOB                                   */
+#include <bcrypt.h>     /* CNG primitive provider                      */
+#include <dpapi.h>      /* CryptProtectData / CryptUnprotectData       */
+
+#ifndef STATUS_SUCCESS
+#  define STATUS_SUCCESS ((NTSTATUS)0x00000000L)
+#endif
+#ifndef STATUS_AUTH_TAG_MISMATCH
+#  define STATUS_AUTH_TAG_MISMATCH ((NTSTATUS)0xC000A002L)
+#endif
+#ifndef NT_SUCCESS
+#  define NT_SUCCESS(s) (((NTSTATUS)(s)) >= 0)
+#endif
+
+/* ------------------------------------------------------------------ globals */
+
+static VALUE mPhylax;
+static VALUE eError;       /* Phylax::Error               < StandardError      */
+static VALUE eAuthError;   /* Phylax::AuthenticationError < Phylax::Error       */
+static VALUE eOSError;     /* Phylax::OSError             < Phylax::Error       */
+static VALUE cDigest;      /* Phylax::Digest                                    */
+static VALUE cHMAC;        /* Phylax::HMAC                                      */
+static VALUE cSecretBox;   /* Phylax::SecretBox                                 */
+
+/* Three SHA-2 variants, indexed 0/1/2 throughout (sha256/sha384/sha512). */
+#define N_ALG 3
+static BCRYPT_ALG_HANDLE g_hash[N_ALG];   /* plain hash providers              */
+static BCRYPT_ALG_HANDLE g_hmac[N_ALG];   /* HMAC-promoted providers           */
+static BCRYPT_ALG_HANDLE g_aes_gcm;       /* AES provider switched to GCM mode  */
+static ULONG g_dlen[N_ALG];               /* digest length (32/48/64)          */
+static ULONG g_objlen_hash[N_ALG];        /* BCRYPT_OBJECT_LENGTH, hash         */
+static ULONG g_objlen_hmac[N_ALG];        /* BCRYPT_OBJECT_LENGTH, hmac         */
+
+#define SECRETBOX_KEY_BYTES   32u
+#define SECRETBOX_NONCE_BYTES 12u
+#define SECRETBOX_TAG_BYTES   16u
+
+/* ------------------------------------------------------------- error raising */
+
+/* Build (but do not raise) a Phylax error carrying @api and @code for triage. */
+static VALUE
+make_exc(VALUE klass, const char *api, unsigned long code, const char *what)
+{
+    VALUE msg = rb_sprintf("%s: %s (0x%08lX)", api, what, code);
+    VALUE exc = rb_exc_new_str(klass, msg);
+    rb_iv_set(exc, "@api", rb_str_new_cstr(api));
+    rb_iv_set(exc, "@code", ULONG2NUM(code));
+    return exc;
+}
+
+/* Map a failing NTSTATUS to an exception. A GCM tag mismatch is an
+ * authentication failure; everything else is an OS error. Caller must have
+ * already released any native resources in this frame (longjmp follows). */
+static void
+raise_nt(const char *api, NTSTATUS st)
+{
+    if (st == STATUS_AUTH_TAG_MISMATCH) {
+        rb_exc_raise(make_exc(eAuthError, api,
+                              (unsigned long)(ULONG)st,
+                              "ciphertext failed authentication"));
+    }
+    rb_exc_raise(make_exc(eOSError, api, (unsigned long)(ULONG)st, "NTSTATUS failure"));
+}
+
+/* Map a Win32 GetLastError() to an exception. For DPAPI unprotect, integrity /
+ * credential failures are authentication errors; the rest are OS errors. */
+static void
+raise_gle(const char *api, DWORD code, int integrity_is_auth)
+{
+    if (integrity_is_auth &&
+        (code == ERROR_INVALID_DATA ||      /* 13   tamper / wrong entropy     */
+         code == ERROR_INVALID_PARAMETER || /* 87   corrupted blob             */
+         code == (DWORD)NTE_BAD_DATA ||      /* 0x80090005                      */
+         code == (DWORD)NTE_BAD_KEY)) {      /* 0x80090003                      */
+        rb_exc_raise(make_exc(eAuthError, api, code,
+                              "data could not be authenticated / decrypted"));
+    }
+    rb_exc_raise(make_exc(eOSError, api, code, "Windows API failure"));
+}
+
+/* StringValue + a guard that the byte length fits the ULONG-typed CNG params.
+ * Returns the byte length; writes the data pointer through *pp. Use only where
+ * there is NO Ruby allocation between this call and the native call that
+ * consumes the pointer (otherwise a compacting GC could move an embedded
+ * string and dangle *pp — see ulen()/RSTRING_PTR-late idiom below). */
+static ULONG
+str_bytes(VALUE *v, PUCHAR *pp)
+{
+    long n;
+    StringValue(*v);
+    n = RSTRING_LEN(*v);
+    if ((unsigned long long)n > 0xFFFFFFFFull)
+        rb_raise(rb_eArgError, "phylax: input too large (> 4 GiB)");
+    *pp = (PUCHAR)RSTRING_PTR(*v);
+    return (ULONG)n;
+}
+
+/* Coerce-and-measure without taking the data pointer. RSTRING_LEN is stable
+ * across GC (compaction never changes a string's length), so length may be
+ * read early; RSTRING_PTR must be fetched only after the last Ruby allocation,
+ * immediately before the native call. */
+static ULONG
+ulen(VALUE v)
+{
+    long n;
+    Check_Type(v, T_STRING);
+    n = RSTRING_LEN(v);
+    if ((unsigned long long)n > 0xFFFFFFFFull)
+        rb_raise(rb_eArgError, "phylax: input too large (> 4 GiB)");
+    return (ULONG)n;
+}
+
+static int
+alg_index(VALUE idx)
+{
+    int i = NUM2INT(idx);
+    if (i < 0 || i >= N_ALG)
+        rb_raise(rb_eArgError, "phylax: invalid algorithm index %d", i);
+    return i;
+}
+
+/* rb_protect body: copy a native buffer into a fresh String. Used so the
+ * native source buffer can be wiped/freed unconditionally even if the String
+ * allocation raises (NoMemoryError) — see strcopy_or_cleanup callers. */
+struct strcopy { const char *ptr; long len; };
+
+static VALUE
+strcopy_body(VALUE a)
+{
+    struct strcopy *s = (struct strcopy *)a;
+    return rb_str_new(s->ptr, s->len);
+}
+
+/* --------------------------------------------------------------- random ---- */
+
+/* Phylax.random_bytes(n) -> String (BINARY, length n) */
+static VALUE
+phylax_random_bytes(VALUE self, VALUE rn)
+{
+    long n = NUM2LONG(rn);
+    VALUE out;
+    NTSTATUS st;
+
+    if (n < 0)
+        rb_raise(rb_eArgError, "phylax: negative length");
+    if ((unsigned long long)n > 0xFFFFFFFFull)
+        rb_raise(rb_eArgError, "phylax: length too large (> 4 GiB)");
+
+    out = rb_str_new(NULL, n);
+    rb_enc_associate(out, rb_ascii8bit_encoding());
+    if (n == 0)
+        return out;
+
+    st = BCryptGenRandom(NULL, (PUCHAR)RSTRING_PTR(out), (ULONG)n,
+                         BCRYPT_USE_SYSTEM_PREFERRED_RNG);
+    if (!NT_SUCCESS(st))
+        raise_nt("BCryptGenRandom", st);   /* never returns the zeroed buffer */
+
+    return out;
+}
+
+/* --------------------------------------------------------------- hashing --- */
+
+/* Phylax.__hash(idx, data) -> raw digest String (one-shot). */
+static VALUE
+phylax_hash(VALUE self, VALUE vidx, VALUE data)
+{
+    int i = alg_index(vidx);
+    PUCHAR pin, pout;
+    ULONG nin;
+    BCRYPT_HASH_HANDLE h = NULL;
+    NTSTATUS st;
+    VALUE out;
+
+    StringValue(data);
+    nin = ulen(data);
+    out = rb_str_new(NULL, g_dlen[i]);
+    rb_enc_associate(out, rb_ascii8bit_encoding());
+    pin  = (PUCHAR)RSTRING_PTR(data);   /* pointers fetched after the last alloc */
+    pout = (PUCHAR)RSTRING_PTR(out);
+
+    st = BCryptCreateHash(g_hash[i], &h, NULL, 0, NULL, 0, 0);
+    if (NT_SUCCESS(st)) {
+        st = BCryptHashData(h, pin, nin, 0);
+        if (NT_SUCCESS(st))
+            st = BCryptFinishHash(h, pout, g_dlen[i], 0);
+    }
+    if (h) BCryptDestroyHash(h);
+    if (!NT_SUCCESS(st))
+        raise_nt("BCryptHash", st);
+
+    return out;
+}
+
+/* Phylax.__hmac(idx, key, data) -> raw MAC String (one-shot). */
+static VALUE
+phylax_hmac(VALUE self, VALUE vidx, VALUE key, VALUE data)
+{
+    int i = alg_index(vidx);
+    PUCHAR pkey, pin, pout;
+    ULONG nkey, nin;
+    BCRYPT_HASH_HANDLE h = NULL;
+    NTSTATUS st;
+    VALUE out;
+
+    StringValue(key);
+    StringValue(data);
+    nkey = ulen(key);
+    nin  = ulen(data);
+    out = rb_str_new(NULL, g_dlen[i]);
+    rb_enc_associate(out, rb_ascii8bit_encoding());
+    pkey = (PUCHAR)RSTRING_PTR(key);    /* pointers fetched after the last alloc */
+    pin  = (PUCHAR)RSTRING_PTR(data);
+    pout = (PUCHAR)RSTRING_PTR(out);
+
+    st = BCryptCreateHash(g_hmac[i], &h, NULL, 0, pkey, nkey, 0);
+    if (NT_SUCCESS(st)) {
+        st = BCryptHashData(h, pin, nin, 0);
+        if (NT_SUCCESS(st))
+            st = BCryptFinishHash(h, pout, g_dlen[i], 0);
+    }
+    if (h) BCryptDestroyHash(h);
+    if (!NT_SUCCESS(st))
+        raise_nt("BCryptHash(HMAC)", st);
+
+    return out;
+}
+
+/* ---------------------------------------------------------------- PBKDF2 --- */
+
+struct pbkdf2_job {
+    BCRYPT_ALG_HANDLE hPrf;
+    PUCHAR pw;   ULONG pwlen;
+    PUCHAR salt; ULONG saltlen;
+    ULONGLONG iters;
+    PUCHAR out;  ULONG outlen;
+    NTSTATUS st;
+};
+
+static void *
+pbkdf2_nogvl(void *p)
+{
+    struct pbkdf2_job *j = (struct pbkdf2_job *)p;
+    j->st = BCryptDeriveKeyPBKDF2(j->hPrf, j->pw, j->pwlen, j->salt, j->saltlen,
+                                  j->iters, j->out, j->outlen, 0);
+    return NULL;
+}
+
+/* Phylax.__pbkdf2(idx, password, salt, iterations, length) -> derived key.
+ * Password/salt/output are copied into private heap buffers so the GVL can be
+ * released for the (potentially long) derivation without exposing the Ruby
+ * strings to GC compaction. Secret buffers are wiped before free. */
+static VALUE
+phylax_pbkdf2(VALUE self, VALUE vidx, VALUE password, VALUE salt,
+              VALUE viters, VALUE vlen)
+{
+    int i = alg_index(vidx);
+    PUCHAR ppw, psalt;
+    ULONG npw, nsalt;
+    long len = NUM2LONG(vlen);
+    long long signed_iters = NUM2LL(viters); /* RangeError if it overflows int64 */
+    unsigned long long iters;
+    struct pbkdf2_job job;
+    VALUE out;
+
+    /* Validate in C too: __pbkdf2 is reachable directly, bypassing the Ruby
+     * guards, and a negative count would wrap (via the old NUM2ULL) into a
+     * ~2^64 iteration run that spins uninterruptibly under the released GVL. */
+    if (signed_iters < 1)
+        rb_raise(rb_eArgError, "phylax: iterations must be >= 1");
+    iters = (unsigned long long)signed_iters;
+
+    if (len < 1)
+        rb_raise(rb_eArgError, "phylax: length must be >= 1");
+    if ((unsigned long long)len > 0xFFFFFFFFull)
+        rb_raise(rb_eArgError, "phylax: length too large (> 4 GiB)");
+
+    StringValue(password);
+    StringValue(salt);
+    npw   = ulen(password);
+    nsalt = ulen(salt);
+    ppw   = (PUCHAR)RSTRING_PTR(password);  /* copied into heap below, before any */
+    psalt = (PUCHAR)RSTRING_PTR(salt);      /* further Ruby allocation            */
+
+    job.hPrf    = g_hmac[i];
+    job.pwlen   = npw;
+    job.saltlen = nsalt;
+    job.iters   = iters;
+    job.outlen  = (ULONG)len;
+    job.pw   = (PUCHAR)malloc(npw   ? npw   : 1);
+    job.salt = (PUCHAR)malloc(nsalt ? nsalt : 1);
+    job.out  = (PUCHAR)malloc((size_t)len);
+    if (!job.pw || !job.salt || !job.out) {
+        free(job.pw); free(job.salt); free(job.out);
+        rb_raise(rb_eNoMemError, "phylax: out of memory in pbkdf2");
+    }
+    memcpy(job.pw, ppw, npw);
+    memcpy(job.salt, psalt, nsalt);
+
+    /* NULL ubf: the derivation is bounded CPU work that cannot be unblocked
+     * mid-call, so it runs to completion rather than pretending to interrupt. */
+    rb_thread_call_without_gvl(pbkdf2_nogvl, &job, NULL, NULL);
+
+    SecureZeroMemory(job.pw, npw);
+    free(job.pw);
+    free(job.salt);
+
+    if (!NT_SUCCESS(job.st)) {
+        SecureZeroMemory(job.out, (size_t)len);
+        free(job.out);
+        raise_nt("BCryptDeriveKeyPBKDF2", job.st);
+    }
+
+    /* Wipe and free the derived key even if the String allocation raises (OOM). */
+    {
+        struct strcopy sc = { (const char *)job.out, len };
+        int state = 0;
+        out = rb_protect(strcopy_body, (VALUE)&sc, &state);
+        SecureZeroMemory(job.out, (size_t)len);
+        free(job.out);
+        if (state) rb_jump_tag(state);
+    }
+    rb_enc_associate(out, rb_ascii8bit_encoding());
+    return out;
+}
+
+/* -------------------------------------------------------- secure_compare --- */
+
+/* Phylax.secure_compare(a, b) -> true/false. Constant time w.r.t. content for
+ * equal-length inputs; short-circuits false on differing length (length is not
+ * secret for tag comparison — documented). */
+static VALUE
+phylax_secure_compare(VALUE self, VALUE a, VALUE b)
+{
+    long la, lb, i;
+    const volatile unsigned char *pa, *pb;
+    volatile unsigned char acc = 0;
+
+    StringValue(a);
+    StringValue(b);
+    la = RSTRING_LEN(a);
+    lb = RSTRING_LEN(b);
+    if (la != lb)
+        return Qfalse;
+
+    pa = (const volatile unsigned char *)RSTRING_PTR(a);
+    pb = (const volatile unsigned char *)RSTRING_PTR(b);
+    for (i = 0; i < la; i++)
+        acc |= (unsigned char)(pa[i] ^ pb[i]);
+
+    return acc == 0 ? Qtrue : Qfalse;
+}
+
+/* ===================================================================
+ * Streaming Digest — Phylax::Digest
+ * =================================================================== */
+
+typedef struct {
+    BCRYPT_HASH_HANDLE h;
+    int idx;
+} digest_t;
+
+static void
+digest_free(void *p)
+{
+    digest_t *d = (digest_t *)p;
+    if (d->h) BCryptDestroyHash(d->h);
+    xfree(d);
+}
+
+static size_t
+digest_memsize(const void *p)
+{
+    (void)p;
+    return sizeof(digest_t);
+}
+
+static const rb_data_type_t digest_type = {
+    "Phylax::Digest",
+    { 0, digest_free, digest_memsize, },
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static VALUE
+digest_alloc(VALUE klass)
+{
+    digest_t *d;
+    VALUE obj = TypedData_Make_Struct(klass, digest_t, &digest_type, d);
+    d->h = NULL;
+    d->idx = -1;
+    return obj;
+}
+
+static digest_t *
+digest_get(VALUE self)
+{
+    digest_t *d;
+    TypedData_Get_Struct(self, digest_t, &digest_type, d);
+    return d;
+}
+
+/* Phylax::Digest#_init(idx) — (re)create the underlying hash object. */
+static VALUE
+digest_init(VALUE self, VALUE vidx)
+{
+    digest_t *d = digest_get(self);
+    int i = alg_index(vidx);
+    NTSTATUS st;
+
+    if (d->h) { BCryptDestroyHash(d->h); d->h = NULL; }
+    st = BCryptCreateHash(g_hash[i], &d->h, NULL, 0, NULL, 0, 0);
+    if (!NT_SUCCESS(st))
+        raise_nt("BCryptCreateHash", st);
+    d->idx = i;
+    return self;
+}
+
+static VALUE
+digest_update(VALUE self, VALUE data)
+{
+    digest_t *d = digest_get(self);
+    PUCHAR pin;
+    ULONG nin;
+    NTSTATUS st;
+
+    if (!d->h) rb_raise(eError, "phylax: digest not initialized");
+    nin = str_bytes(&data, &pin);
+    st = BCryptHashData(d->h, pin, nin, 0);
+    if (!NT_SUCCESS(st))
+        raise_nt("BCryptHashData", st);
+    return self;
+}
+
+/* Non-destructive: duplicate the running state and finish the copy, leaving the
+ * original open for further #update (matches Ruby stdlib Digest semantics). */
+static VALUE
+digest_digest(VALUE self)
+{
+    digest_t *d = digest_get(self);
+    BCRYPT_HASH_HANDLE dup = NULL;
+    PUCHAR obj;
+    ULONG objlen;
+    NTSTATUS st;
+    VALUE out;
+
+    if (!d->h) rb_raise(eError, "phylax: digest not initialized");
+
+    /* Allocate the Ruby output first so the malloc below is the last resource
+     * acquired; an rb_str_new (OOM) raise then leaks nothing. */
+    out = rb_str_new(NULL, g_dlen[d->idx]);
+    rb_enc_associate(out, rb_ascii8bit_encoding());
+
+    objlen = g_objlen_hash[d->idx];
+    obj = (PUCHAR)malloc(objlen ? objlen : 1);
+    if (!obj) rb_raise(rb_eNoMemError, "phylax: out of memory");
+
+    st = BCryptDuplicateHash(d->h, &dup, obj, objlen, 0);
+    if (NT_SUCCESS(st))
+        st = BCryptFinishHash(dup, (PUCHAR)RSTRING_PTR(out), g_dlen[d->idx], 0);
+    if (dup) BCryptDestroyHash(dup);
+    free(obj);
+    if (!NT_SUCCESS(st))
+        raise_nt("BCryptDuplicateHash", st);
+
+    return out;
+}
+
+static VALUE
+digest_size(VALUE self)
+{
+    digest_t *d = digest_get(self);
+    if (d->idx < 0) rb_raise(eError, "phylax: digest not initialized");
+    return UINT2NUM(g_dlen[d->idx]);
+}
+
+/* ===================================================================
+ * Streaming HMAC — Phylax::HMAC (retains the key for #reset; wiped on free)
+ * =================================================================== */
+
+typedef struct {
+    BCRYPT_HASH_HANDLE h;
+    int idx;
+    unsigned char *key;
+    ULONG keylen;
+} hmac_t;
+
+static void
+hmac_free(void *p)
+{
+    hmac_t *m = (hmac_t *)p;
+    if (m->h) BCryptDestroyHash(m->h);
+    if (m->key) { SecureZeroMemory(m->key, m->keylen); free(m->key); }
+    xfree(m);
+}
+
+static size_t
+hmac_memsize(const void *p)
+{
+    const hmac_t *m = (const hmac_t *)p;
+    return sizeof(hmac_t) + (m->key ? m->keylen : 0);
+}
+
+static const rb_data_type_t hmac_type = {
+    "Phylax::HMAC",
+    { 0, hmac_free, hmac_memsize, },
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static VALUE
+hmac_alloc(VALUE klass)
+{
+    hmac_t *m;
+    VALUE obj = TypedData_Make_Struct(klass, hmac_t, &hmac_type, m);
+    m->h = NULL;
+    m->idx = -1;
+    m->key = NULL;
+    m->keylen = 0;
+    return obj;
+}
+
+static hmac_t *
+hmac_get(VALUE self)
+{
+    hmac_t *m;
+    TypedData_Get_Struct(self, hmac_t, &hmac_type, m);
+    return m;
+}
+
+static VALUE
+hmac_init(VALUE self, VALUE vidx, VALUE key)
+{
+    hmac_t *m = hmac_get(self);
+    int i = alg_index(vidx);
+    PUCHAR pkey;
+    ULONG nkey;
+    NTSTATUS st;
+
+    nkey = str_bytes(&key, &pkey);
+
+    if (m->h) { BCryptDestroyHash(m->h); m->h = NULL; }
+    if (m->key) { SecureZeroMemory(m->key, m->keylen); free(m->key); m->key = NULL; m->keylen = 0; }
+
+    /* Retain a private copy of the key so #reset can re-key without the caller. */
+    m->key = (unsigned char *)malloc(nkey ? nkey : 1);
+    if (!m->key) rb_raise(rb_eNoMemError, "phylax: out of memory");
+    memcpy(m->key, pkey, nkey);
+    m->keylen = nkey;
+
+    st = BCryptCreateHash(g_hmac[i], &m->h, NULL, 0, m->key, nkey, 0);
+    if (!NT_SUCCESS(st)) {
+        SecureZeroMemory(m->key, m->keylen); free(m->key); m->key = NULL; m->keylen = 0;
+        raise_nt("BCryptCreateHash(HMAC)", st);
+    }
+    m->idx = i;
+    return self;
+}
+
+static VALUE
+hmac_update(VALUE self, VALUE data)
+{
+    hmac_t *m = hmac_get(self);
+    PUCHAR pin;
+    ULONG nin;
+    NTSTATUS st;
+
+    if (!m->h) rb_raise(eError, "phylax: hmac not initialized");
+    nin = str_bytes(&data, &pin);
+    st = BCryptHashData(m->h, pin, nin, 0);
+    if (!NT_SUCCESS(st))
+        raise_nt("BCryptHashData", st);
+    return self;
+}
+
+static VALUE
+hmac_digest(VALUE self)
+{
+    hmac_t *m = hmac_get(self);
+    BCRYPT_HASH_HANDLE dup = NULL;
+    PUCHAR obj;
+    ULONG objlen;
+    NTSTATUS st;
+    VALUE out;
+
+    if (!m->h) rb_raise(eError, "phylax: hmac not initialized");
+
+    /* Allocate the Ruby output first so the malloc below is the last resource
+     * acquired; an rb_str_new (OOM) raise then leaks nothing. */
+    out = rb_str_new(NULL, g_dlen[m->idx]);
+    rb_enc_associate(out, rb_ascii8bit_encoding());
+
+    objlen = g_objlen_hmac[m->idx];
+    obj = (PUCHAR)malloc(objlen ? objlen : 1);
+    if (!obj) rb_raise(rb_eNoMemError, "phylax: out of memory");
+
+    st = BCryptDuplicateHash(m->h, &dup, obj, objlen, 0);
+    if (NT_SUCCESS(st))
+        st = BCryptFinishHash(dup, (PUCHAR)RSTRING_PTR(out), g_dlen[m->idx], 0);
+    if (dup) BCryptDestroyHash(dup);
+    free(obj);
+    if (!NT_SUCCESS(st))
+        raise_nt("BCryptDuplicateHash(HMAC)", st);
+
+    return out;
+}
+
+/* #reset — re-create the MAC object with the retained key. */
+static VALUE
+hmac_reset(VALUE self)
+{
+    hmac_t *m = hmac_get(self);
+    BCRYPT_HASH_HANDLE nh = NULL;
+    NTSTATUS st;
+
+    if (m->idx < 0) rb_raise(eError, "phylax: hmac not initialized");
+    st = BCryptCreateHash(g_hmac[m->idx], &nh, NULL, 0, m->key, m->keylen, 0);
+    if (!NT_SUCCESS(st))
+        raise_nt("BCryptCreateHash(HMAC)", st);
+    if (m->h) BCryptDestroyHash(m->h);
+    m->h = nh;
+    return self;
+}
+
+static VALUE
+hmac_size(VALUE self)
+{
+    hmac_t *m = hmac_get(self);
+    if (m->idx < 0) rb_raise(eError, "phylax: hmac not initialized");
+    return UINT2NUM(g_dlen[m->idx]);
+}
+
+/* ===================================================================
+ * SecretBox — AES-256-GCM AEAD. Phylax::SecretBox
+ * Holds only the CNG key handle; no raw key bytes are retained.
+ * =================================================================== */
+
+typedef struct {
+    BCRYPT_KEY_HANDLE key;
+} box_t;
+
+static void
+box_free(void *p)
+{
+    box_t *b = (box_t *)p;
+    if (b->key) BCryptDestroyKey(b->key);
+    xfree(b);
+}
+
+static size_t
+box_memsize(const void *p)
+{
+    (void)p;
+    return sizeof(box_t);
+}
+
+static const rb_data_type_t box_type = {
+    "Phylax::SecretBox",
+    { 0, box_free, box_memsize, },
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static VALUE
+box_alloc(VALUE klass)
+{
+    box_t *b;
+    VALUE obj = TypedData_Make_Struct(klass, box_t, &box_type, b);
+    b->key = NULL;
+    return obj;
+}
+
+static box_t *
+box_get(VALUE self)
+{
+    box_t *b;
+    TypedData_Get_Struct(self, box_t, &box_type, b);
+    return b;
+}
+
+/* Phylax::SecretBox#_init(key) — key must be exactly 32 bytes (checked in Ruby
+ * too; re-checked here so the C contract is self-standing). */
+static VALUE
+box_init(VALUE self, VALUE key)
+{
+    box_t *b = box_get(self);
+    PUCHAR pkey;
+    ULONG nkey;
+    NTSTATUS st;
+
+    nkey = str_bytes(&key, &pkey);
+    if (nkey != SECRETBOX_KEY_BYTES)
+        rb_raise(rb_eArgError, "phylax: key must be exactly %u bytes, got %lu",
+                 SECRETBOX_KEY_BYTES, (unsigned long)nkey);
+
+    if (b->key) { BCryptDestroyKey(b->key); b->key = NULL; }
+    st = BCryptGenerateSymmetricKey(g_aes_gcm, &b->key, NULL, 0, pkey, nkey, 0);
+    if (!NT_SUCCESS(st))
+        raise_nt("BCryptGenerateSymmetricKey", st);
+    return self;
+}
+
+/* Phylax::SecretBox#_seal(plaintext, aad) -> nonce(12) || ciphertext || tag(16).
+ * A fresh random nonce is generated here on every call — the caller cannot
+ * supply or reuse one. aad is nil or a String (authenticated, not encrypted). */
+static VALUE
+box_seal(VALUE self, VALUE plaintext, VALUE aad)
+{
+    box_t *b = box_get(self);
+    PUCHAR ppt, paad = NULL;
+    ULONG npt, naad = 0;
+    BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO info;
+    NTSTATUS st;
+    VALUE out;
+    PUCHAR base;
+    ULONG produced = 0;
+
+    if (!b->key) rb_raise(eError, "phylax: SecretBox is closed");
+    StringValue(plaintext);
+    npt = ulen(plaintext);
+    if (!NIL_P(aad)) { StringValue(aad); naad = ulen(aad); }
+
+    /* out = [ nonce(12) | ciphertext(npt) | tag(16) ]. Compute the total in a
+     * 64-bit unsigned type and bound it to LONG_MAX so the rb_str_new length
+     * (a 32-bit signed long on this LLP64 target) can never overflow. */
+    {
+        unsigned long long total = (unsigned long long)SECRETBOX_NONCE_BYTES +
+                                   (unsigned long long)npt +
+                                   (unsigned long long)SECRETBOX_TAG_BYTES;
+        if (total > (unsigned long long)LONG_MAX)
+            rb_raise(rb_eArgError, "phylax: plaintext too large to seal");
+    }
+    out = rb_str_new(NULL, (long)SECRETBOX_NONCE_BYTES + (long)npt + (long)SECRETBOX_TAG_BYTES);
+    rb_enc_associate(out, rb_ascii8bit_encoding());
+    /* pointers fetched after the last allocation (out) */
+    base = (PUCHAR)RSTRING_PTR(out);
+    ppt  = (PUCHAR)RSTRING_PTR(plaintext);
+    if (!NIL_P(aad)) paad = (PUCHAR)RSTRING_PTR(aad);
+
+    st = BCryptGenRandom(NULL, base, SECRETBOX_NONCE_BYTES, BCRYPT_USE_SYSTEM_PREFERRED_RNG);
+    if (!NT_SUCCESS(st))
+        raise_nt("BCryptGenRandom", st);
+
+    BCRYPT_INIT_AUTH_MODE_INFO(info);
+    info.pbNonce    = base;
+    info.cbNonce    = SECRETBOX_NONCE_BYTES;
+    info.pbAuthData = paad;
+    info.cbAuthData = naad;
+    info.pbTag      = base + SECRETBOX_NONCE_BYTES + npt;
+    info.cbTag      = SECRETBOX_TAG_BYTES;
+
+    st = BCryptEncrypt(b->key, ppt, npt, &info,
+                       NULL, 0,                                /* pbIV unused in GCM */
+                       base + SECRETBOX_NONCE_BYTES, npt, &produced, 0);
+    if (!NT_SUCCESS(st))
+        raise_nt("BCryptEncrypt", st);
+
+    return out;
+}
+
+/* Phylax::SecretBox#_open(sealed, aad) -> plaintext, or raise AuthenticationError. */
+static VALUE
+box_open(VALUE self, VALUE sealed, VALUE aad)
+{
+    box_t *b = box_get(self);
+    PUCHAR psealed, paad = NULL, pout;
+    ULONG nsealed, naad = 0, nct, produced = 0;
+    BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO info;
+    NTSTATUS st;
+    VALUE out;
+
+    if (!b->key) rb_raise(eError, "phylax: SecretBox is closed");
+    StringValue(sealed);
+    nsealed = ulen(sealed);
+    if (!NIL_P(aad)) { StringValue(aad); naad = ulen(aad); }
+
+    /* A blob shorter than nonce+tag can't be authentic — treat as tamper, not
+     * an ArgumentError, so probing truncated blobs yields no distinct signal. */
+    if (nsealed < SECRETBOX_NONCE_BYTES + SECRETBOX_TAG_BYTES)
+        rb_exc_raise(make_exc(eAuthError, "SecretBox#open", 0,
+                              "sealed message is too short to be authentic"));
+
+    nct = nsealed - SECRETBOX_NONCE_BYTES - SECRETBOX_TAG_BYTES;
+    /* Bound the plaintext length to LONG_MAX so the rb_str_new length (32-bit
+     * signed long on this LLP64 target) can never wrap negative — mirrors the
+     * guard in box_seal. */
+    if ((unsigned long long)nct > (unsigned long long)LONG_MAX)
+        rb_raise(rb_eArgError, "phylax: sealed message too large");
+    out = rb_str_new(NULL, (long)nct);
+    rb_enc_associate(out, rb_ascii8bit_encoding());
+    /* pointers fetched after the last allocation (out) */
+    psealed = (PUCHAR)RSTRING_PTR(sealed);
+    pout    = (PUCHAR)RSTRING_PTR(out);
+    if (!NIL_P(aad)) paad = (PUCHAR)RSTRING_PTR(aad);
+
+    BCRYPT_INIT_AUTH_MODE_INFO(info);
+    info.pbNonce    = psealed;
+    info.cbNonce    = SECRETBOX_NONCE_BYTES;
+    info.pbAuthData = paad;
+    info.cbAuthData = naad;
+    info.pbTag      = psealed + SECRETBOX_NONCE_BYTES + nct;
+    info.cbTag      = SECRETBOX_TAG_BYTES;
+
+    st = BCryptDecrypt(b->key, psealed + SECRETBOX_NONCE_BYTES, nct, &info,
+                       NULL, 0,
+                       pout, nct, &produced, 0);
+    if (!NT_SUCCESS(st)) {
+        /* GCM decrypts into pout BEFORE checking the tag, so on a mismatch the
+         * unauthenticated plaintext is already there. Wipe it before the raise
+         * abandons the buffer to GC — never let chosen-ciphertext output linger. */
+        SecureZeroMemory(pout, nct);
+        raise_nt("BCryptDecrypt", st);   /* tag mismatch -> AuthenticationError */
+    }
+
+    return out;
+}
+
+/* Phylax::SecretBox#close — destroy the key handle now; idempotent. */
+static VALUE
+box_close(VALUE self)
+{
+    box_t *b = box_get(self);
+    if (b->key) { BCryptDestroyKey(b->key); b->key = NULL; }
+    return Qnil;
+}
+
+/* --------------------------------------------------------------- DPAPI ----- */
+
+/* Phylax.__protect(data, machine_scope_bool, entropy_or_nil) -> blob */
+static VALUE
+phylax_protect(VALUE self, VALUE data, VALUE machine, VALUE entropy)
+{
+    DATA_BLOB in, ent, out;
+    DWORD flags = CRYPTPROTECT_UI_FORBIDDEN;
+    PUCHAR pin, pent = NULL;
+    ULONG nin, nent = 0;
+    VALUE result;
+
+    StringValue(data);
+    nin = ulen(data);
+    if (!NIL_P(entropy)) { StringValue(entropy); nent = ulen(entropy); }
+    pin = (PUCHAR)RSTRING_PTR(data);
+    if (!NIL_P(entropy)) pent = (PUCHAR)RSTRING_PTR(entropy);
+    if (RTEST(machine)) flags |= CRYPTPROTECT_LOCAL_MACHINE;
+
+    in.cbData = nin;  in.pbData = pin;
+    ent.cbData = nent; ent.pbData = pent;
+    out.cbData = 0;   out.pbData = NULL;
+
+    if (!CryptProtectData(&in, NULL, pent ? &ent : NULL, NULL, NULL, flags, &out)) {
+        raise_gle("CryptProtectData", GetLastError(), 0);
+    }
+
+    if ((unsigned long long)out.cbData > (unsigned long long)LONG_MAX) {
+        LocalFree(out.pbData);
+        rb_raise(rb_eArgError, "phylax: DPAPI blob too large");
+    }
+
+    /* LocalFree the OS blob even if the String allocation raises (OOM). */
+    {
+        struct strcopy sc = { (const char *)out.pbData, (long)out.cbData };
+        int state = 0;
+        result = rb_protect(strcopy_body, (VALUE)&sc, &state);
+        LocalFree(out.pbData);
+        if (state) rb_jump_tag(state);
+    }
+    rb_enc_associate(result, rb_ascii8bit_encoding());
+    return result;
+}
+
+/* Phylax.__unprotect(data, entropy_or_nil) -> plaintext */
+static VALUE
+phylax_unprotect(VALUE self, VALUE data, VALUE entropy)
+{
+    DATA_BLOB in, ent, out;
+    PUCHAR pin, pent = NULL;
+    ULONG nin, nent = 0;
+    VALUE result;
+
+    StringValue(data);
+    nin = ulen(data);
+    if (!NIL_P(entropy)) { StringValue(entropy); nent = ulen(entropy); }
+    pin = (PUCHAR)RSTRING_PTR(data);
+    if (!NIL_P(entropy)) pent = (PUCHAR)RSTRING_PTR(entropy);
+
+    in.cbData = nin;  in.pbData = pin;
+    ent.cbData = nent; ent.pbData = pent;
+    out.cbData = 0;   out.pbData = NULL;
+
+    if (!CryptUnprotectData(&in, NULL, pent ? &ent : NULL, NULL, NULL,
+                            CRYPTPROTECT_UI_FORBIDDEN, &out)) {
+        raise_gle("CryptUnprotectData", GetLastError(), 1);
+    }
+
+    if ((unsigned long long)out.cbData > (unsigned long long)LONG_MAX) {
+        SecureZeroMemory(out.pbData, out.cbData);
+        LocalFree(out.pbData);
+        rb_raise(rb_eArgError, "phylax: DPAPI blob too large");
+    }
+
+    /* Wipe the recovered plaintext and free the OS blob even if the String
+     * allocation raises (OOM). */
+    {
+        struct strcopy sc = { (const char *)out.pbData, (long)out.cbData };
+        int state = 0;
+        result = rb_protect(strcopy_body, (VALUE)&sc, &state);
+        SecureZeroMemory(out.pbData, out.cbData);
+        LocalFree(out.pbData);
+        if (state) rb_jump_tag(state);
+    }
+    rb_enc_associate(result, rb_ascii8bit_encoding());
+    return result;
+}
+
+/* ----------------------------------------------------------------- Init ---- */
+
+static void
+open_provider(BCRYPT_ALG_HANDLE *ph, LPCWSTR alg, ULONG flags, const char *what)
+{
+    NTSTATUS st = BCryptOpenAlgorithmProvider(ph, alg, NULL, flags);
+    if (!NT_SUCCESS(st))
+        rb_raise(rb_eLoadError, "phylax: BCryptOpenAlgorithmProvider(%s) failed: 0x%08lX",
+                 what, (unsigned long)(ULONG)st);
+}
+
+static ULONG
+provider_prop(BCRYPT_ALG_HANDLE h, LPCWSTR prop, const char *what)
+{
+    DWORD v = 0, got = 0;
+    NTSTATUS st = BCryptGetProperty(h, prop, (PUCHAR)&v, sizeof(v), &got, 0);
+    if (!NT_SUCCESS(st))
+        rb_raise(rb_eLoadError, "phylax: BCryptGetProperty(%s) failed: 0x%08lX",
+                 what, (unsigned long)(ULONG)st);
+    return v;
+}
+
+void
+Init_phylax(void)
+{
+    LPCWSTR algids[N_ALG];
+    int i;
+    NTSTATUS st;
+
+    algids[0] = BCRYPT_SHA256_ALGORITHM;
+    algids[1] = BCRYPT_SHA384_ALGORITHM;
+    algids[2] = BCRYPT_SHA512_ALGORITHM;
+
+    mPhylax = rb_define_module("Phylax");
+    eError     = rb_define_class_under(mPhylax, "Error", rb_eStandardError);
+    eAuthError = rb_define_class_under(mPhylax, "AuthenticationError", eError);
+    eOSError   = rb_define_class_under(mPhylax, "OSError", eError);
+
+    /* Open and cache provider handles for the life of the process. */
+    for (i = 0; i < N_ALG; i++) {
+        open_provider(&g_hash[i], algids[i], 0, "hash");
+        open_provider(&g_hmac[i], algids[i], BCRYPT_ALG_HANDLE_HMAC_FLAG, "hmac");
+        g_dlen[i]        = provider_prop(g_hash[i], BCRYPT_HASH_LENGTH, "HashLength");
+        g_objlen_hash[i] = provider_prop(g_hash[i], BCRYPT_OBJECT_LENGTH, "ObjectLength(hash)");
+        g_objlen_hmac[i] = provider_prop(g_hmac[i], BCRYPT_OBJECT_LENGTH, "ObjectLength(hmac)");
+    }
+
+    open_provider(&g_aes_gcm, BCRYPT_AES_ALGORITHM, 0, "aes");
+    st = BCryptSetProperty(g_aes_gcm, BCRYPT_CHAINING_MODE,
+                           (PUCHAR)BCRYPT_CHAIN_MODE_GCM,
+                           sizeof(BCRYPT_CHAIN_MODE_GCM), 0);
+    if (!NT_SUCCESS(st))
+        rb_raise(rb_eLoadError, "phylax: set GCM chaining mode failed: 0x%08lX",
+                 (unsigned long)(ULONG)st);
+
+    /* module-level primitives */
+    rb_define_singleton_method(mPhylax, "random_bytes", phylax_random_bytes, 1);
+    rb_define_singleton_method(mPhylax, "secure_compare", phylax_secure_compare, 2);
+    rb_define_singleton_method(mPhylax, "__hash", phylax_hash, 2);
+    rb_define_singleton_method(mPhylax, "__hmac", phylax_hmac, 3);
+    rb_define_singleton_method(mPhylax, "__pbkdf2", phylax_pbkdf2, 5);
+    rb_define_singleton_method(mPhylax, "__protect", phylax_protect, 3);
+    rb_define_singleton_method(mPhylax, "__unprotect", phylax_unprotect, 2);
+
+    /* Phylax::Digest */
+    cDigest = rb_define_class_under(mPhylax, "Digest", rb_cObject);
+    rb_define_alloc_func(cDigest, digest_alloc);
+    rb_define_method(cDigest, "_init", digest_init, 1);
+    rb_define_method(cDigest, "update", digest_update, 1);
+    rb_define_method(cDigest, "digest", digest_digest, 0);
+    rb_define_method(cDigest, "digest_length", digest_size, 0);
+
+    /* Phylax::HMAC */
+    cHMAC = rb_define_class_under(mPhylax, "HMAC", rb_cObject);
+    rb_define_alloc_func(cHMAC, hmac_alloc);
+    rb_define_method(cHMAC, "_init", hmac_init, 2);
+    rb_define_method(cHMAC, "update", hmac_update, 1);
+    rb_define_method(cHMAC, "digest", hmac_digest, 0);
+    rb_define_method(cHMAC, "reset", hmac_reset, 0);
+    rb_define_method(cHMAC, "digest_length", hmac_size, 0);
+
+    /* Phylax::SecretBox */
+    cSecretBox = rb_define_class_under(mPhylax, "SecretBox", rb_cObject);
+    rb_define_alloc_func(cSecretBox, box_alloc);
+    rb_define_method(cSecretBox, "_init", box_init, 1);
+    rb_define_method(cSecretBox, "_seal", box_seal, 2);
+    rb_define_method(cSecretBox, "_open", box_open, 2);
+    rb_define_method(cSecretBox, "close", box_close, 0);
+}