Add HMAC-SHA-256, PBKDF2-SHA-256, and RAND_bytes to ssl/crypto

[SeanTAllen]

Prerequisite work for SCRAM-SHA-256 authentication in ponylang/postgres (Design: ponylang/postgres#83, Decision 1). Adds three cryptographic primitives to the ssl/crypto package as FFI wrappers around stable OpenSSL C APIs.

Change type: Added (new feature). PR label: changelog - added.

FFI Scoping

Pony FFI declarations are package-scoped: "An FFI signature is public to all Pony files inside the same package, so you only need to write them once." This means:

• @EVP_sha256 (declared in digest.pony) and @pony_ctx/@pony_alloc (declared in crypto.pony) are already visible to the new files. No redeclaration needed.
• _EVPMD (defined in digest.pony) is package-private and accessible from any file in ssl/crypto.
• Each new file only needs to declare its own unique FFI function (@HMAC, @PKCS5_PBKDF2_HMAC, @RAND_bytes).

Library link directives (use "lib:crypto" and the macOS LibreSSL path directives) are included in each new file following the existing convention in hash_fn.pony and digest.pony.

New Primitives

HmacSha256

One-shot HMAC computation using SHA-256 (RFC 2104). Wraps OpenSSL's HMAC() function. Returns a 32-byte message authentication code.

File: ssl/crypto/hmac_sha256.pony

use "path:/usr/local/opt/libressl/lib" if osx and x86
use "path:/opt/homebrew/opt/libressl/lib" if osx and arm
use "lib:crypto"

use @HMAC[Pointer[U8]](
  evp_md: Pointer[_EVPMD],
  key: Pointer[U8] tag, key_len: I32,
  data: Pointer[U8] tag, data_len: USize,
  md: Pointer[U8], md_len: Pointer[U32])

primitive HmacSha256
  """
  Compute HMAC using SHA-256 as the hash function, as defined in RFC 2104.

  Returns a 32-byte message authentication code.

  ```pony
  let mac = HmacSha256("secret-key", "Hello, World!")
  ```
  """
  fun tag apply(key: ByteSeq, data: ByteSeq): Array[U8] val =>
    recover
      let size: USize = 32
      let md = @pony_alloc(@pony_ctx(), size)
      @HMAC(@EVP_sha256(), key.cpointer(), key.size().i32(),
        data.cpointer(), data.size(), md, Pointer[U32])
      Array[U8].from_cpointer(md, size)
    end

Design notes:

• Non-partial, following the SHA256 primitive convention. HMAC() only fails on internal memory allocation failure, which the existing hash primitives also don't guard against.
• md_len receives a null pointer (Pointer[U32]) since we know the output is always 32 bytes.
• key_len is I32 matching the C int parameter. Keys > 2GB are not a practical concern for HMAC.
• Algorithm-specific primitive (not a general Hmac with algorithm parameter), following the existing HashFn convention. Additional HMAC variants (SHA-384, SHA-512) can be added later as separate primitives following the same pattern.
• No ifdef version guards needed. HMAC() is available in all supported OpenSSL versions (0.9.0, 1.1.x, 3.0.x). The one-shot HMAC() function is not deprecated in OpenSSL 3.0 -- only the context-based functions (HMAC_CTX_new, HMAC_Init_ex, HMAC_Update, HMAC_Final) are deprecated.

Pbkdf2Sha256

One-shot PBKDF2 key derivation using HMAC-SHA-256 as the PRF (RFC 2898). Wraps OpenSSL's PKCS5_PBKDF2_HMAC() function.

File: ssl/crypto/pbkdf2_sha256.pony

use "path:/usr/local/opt/libressl/lib" if osx and x86
use "path:/opt/homebrew/opt/libressl/lib" if osx and arm
use "lib:crypto"

use @PKCS5_PBKDF2_HMAC[I32](
  pass: Pointer[U8] tag, passlen: I32,
  salt: Pointer[U8] tag, saltlen: I32, iter: I32,
  digest: Pointer[_EVPMD],
  keylen: I32, out: Pointer[U8]) if "openssl_1.1.x" or "openssl_3.0.x"

primitive Pbkdf2Sha256
  """
  Derive a key from a password using PBKDF2 with HMAC-SHA-256 as the PRF,
  as defined in RFC 2898.

  Returns a key of the requested length, or raises an error if the derivation
  fails (e.g., zero iterations).

  Requires OpenSSL 1.1.x or 3.0.x. Not available on the legacy 0.9.0 path.

  ```pony
  let key = Pbkdf2Sha256("password", "salt", 4096, 32)?
  ```
  """
  fun tag apply(password: ByteSeq, salt: ByteSeq, iterations: U32,
    key_length: USize): Array[U8] val ?
  =>
    ifdef "openssl_1.1.x" or "openssl_3.0.x" then
      recover
        let out = @pony_alloc(@pony_ctx(), key_length)
        let rc = @PKCS5_PBKDF2_HMAC(
          password.cpointer(), password.size().i32(),
          salt.cpointer(), salt.size().i32(),
          iterations.i32(),
          @EVP_sha256(),
          key_length.i32(),
          out)
        if rc != 1 then error end
        Array[U8].from_cpointer(out, key_length)
      end
    elseif "openssl_0.9.0" then
      compile_error "Pbkdf2Sha256 requires OpenSSL 1.1.x or 3.0.x"
    else
      compile_error "You must select an SSL version to use."
    end

Design notes:

• Partial function. PKCS5_PBKDF2_HMAC() returns 0 on failure (e.g., zero iterations on OpenSSL 1.1.0+). Unlike HMAC(), this has meaningful failure modes that the caller should handle.
• iterations is U32 in the public API (semantically correct -- iteration counts are positive). Converted to .i32() for the C int parameter. Values > 2^31 would overflow, but such iteration counts are not practically useful.
• key_length is USize (consistent with other size parameters in the package). Converted to .i32() for FFI.
• Version guard with compile_error for the openssl_0.9.0 path, following the established pattern in digest.pony for shake128/shake256. PKCS5_PBKDF2_HMAC() was added in OpenSSL 1.0.0; OpenSSL 0.9.8 only provides the SHA-1-specific PKCS5_PBKDF2_HMAC_SHA1(). Since the 0.9.0 define is overloaded (used for both genuine 0.9.8 and LibreSSL, which does have the function), this guard errs on the side of safety. The 0.9.0 path is being removed per issue LibreSSL is misidentified as OpenSSL 0.9.0, disabling functionality LibreSSL supports #9.
• The @PKCS5_PBKDF2_HMAC FFI declaration has an if guard limiting it to "openssl_1.1.x" or "openssl_3.0.x" to prevent unresolved symbol errors on 0.9.0:

use @PKCS5_PBKDF2_HMAC[I32](...) if "openssl_1.1.x" or "openssl_3.0.x"

RandBytes

Cryptographically secure random byte generation. Wraps OpenSSL's RAND_bytes() function.

File: ssl/crypto/rand_bytes.pony

use "path:/usr/local/opt/libressl/lib" if osx and x86
use "path:/opt/homebrew/opt/libressl/lib" if osx and arm
use "lib:crypto"

use @RAND_bytes[I32](buf: Pointer[U8], num: I32)

primitive RandBytes
  """
  Generate cryptographically secure random bytes using OpenSSL's CSPRNG.

  Returns an array of the requested number of random bytes, or raises an
  error if the CSPRNG cannot generate secure output (e.g., insufficient
  entropy during early system startup).

  ```pony
  let nonce = RandBytes(24)?
  ```
  """
  fun tag apply(size: USize): Array[U8] val ? =>
    recover
      let buf = @pony_alloc(@pony_ctx(), size)
      let rc = @RAND_bytes(buf, size.i32())
      if rc != 1 then error end
      Array[U8].from_cpointer(buf, size)
    end

Design notes:

• Partial function. RAND_bytes() returns 0 if the CSPRNG is not properly seeded, which is a real (if rare) failure mode, especially during early system startup.
• size is USize in the public API. Converted to .i32() for the C int parameter. Generating > 2GB of random data in a single call is not a practical use case.
• No ifdef version guards needed. RAND_bytes() is available in all supported OpenSSL and LibreSSL versions.

Tests

Build and run: make test ssl=3.0.x (or make ssl=3.0.x since test is the default target).

Example-based tests (RFC test vectors)

Add to ssl/crypto/_test.pony. Follow the existing pattern: class \nodoc\ iso _TestX is UnitTest.

HMAC-SHA-256 (RFC 4231): All 7 test cases. Each verifies the computed HMAC against the expected hex digest.

Test Case	Key	Data	Expected HMAC-SHA-256
1	20 bytes of 0x0b	"Hi There"	b0344c61d8db38535ca8afceaf0bf12b881dc200c9833da726e9376c2e32cff7
2	"Jefe"	"what do ya want for nothing?"	5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843
3	20 bytes of 0xaa	50 bytes of 0xdd	773ea91e36800e46854db8ebd09181a72959098b3ef8c122d9635514ced565fe
4	25 bytes 0x01..0x19	50 bytes of 0xcd	82558a389a443c0ea4cc819899f2083a85f0faa3e578f8077a2e3ff46729665b
5	20 bytes of 0x0c	"Test With Truncation"	a3b6167473100ee06e0c796c2955552b (truncated to 128 bits)
6	131 bytes of 0xaa	"Test Using Larger Than Block-Size Key - Hash Key First"	60e431591ee0b67f0d8a26aacbf5b77f8e0bc6213728c5140546040f0ee37f54
7	131 bytes of 0xaa	"This is a test using a larger than block-size key and a larger than block-size data. The key needs to be hashed before being used by the HMAC algorithm."	9b09ffa71b942fcb27635fbcd5b0e944bfdc63644f0713938a7f51535c3a35e2

Test case 5 tests truncation: compute the full 32-byte HMAC, then verify the first 16 bytes match the expected truncated value.

PBKDF2-SHA-256 (RFC 7914 Section 11): Two test vectors.

Password	Salt	Iterations	dkLen	Expected Derived Key
"passwd"	"salt"	1	64	55ac046e56e3089fec1691c22544b605f94185216dde0465e68b9d57c20dacbc49ca9cccf179b645991664b39d77ef317c71b845b1e30bd509112041d3a19783
"Password"	"NaCl"	80000	64	4ddcd8f60b98be21830cee5ef22701f9641a4418d04c0414aeff08876b34ab56a1d425a1225833549adb841b51c9b3176a272bdebba1d078478f62b397f33c8d

These use dkLen=64, which exercises the multi-block PBKDF2 path (SHA-256 output is 32 bytes, so PBKDF2 must iterate twice to produce 64 bytes).

PBKDF2-SHA-256 (SCRAM-SHA-256 test vector): Verifies PBKDF2 produces the correct SaltedPassword for the SCRAM-SHA-256 exchange from RFC 7677. The SaltedPassword is not explicitly listed in the RFC but is derived from the RFC 7677 protocol exchange and verified by confirming the computed ClientProof and ServerSignature match the RFC values.

Password	Salt (base64)	Iterations	dkLen	Expected SaltedPassword
"pencil"	W22ZaJ0SNY7soEsUEjb6gQ==	4096	32	c4a49510323ab4f952cac1fa99441939e78ea74d6be81ddf7096e87513dc615d

The salt is passed as a raw byte array literal (the decoded bytes of W22ZaJ0SNY7soEsUEjb6gQ==), avoiding a dependency on encode/base64 in the test file.

HMAC-SHA-256 (SCRAM-SHA-256 derived values): Verifies HMAC computation of SCRAM intermediate values using the SaltedPassword from the PBKDF2 test above. These values are derived from the RFC 7677 exchange and verified against the RFC's ClientProof and ServerSignature.

• HMAC(SaltedPassword, "Client Key") = a60fc923d67e8644a92d16b96eda5ef4656b0c725c484374be25535576996e8b
• HMAC(SaltedPassword, "Server Key") = c1f3cbc1c13a9d35a14c0990eed97629ea225863e566a4314ab99f3f00e5d9d5

RandBytes: Example-based tests for basic functionality.

• RandBytes(0)? returns an empty array (size 0)
• RandBytes(32)? returns an array of size 32
• RandBytes(1)? returns an array of size 1

PonyCheck property tests

Add use "pony_check" to ssl/crypto/_test.pony. Register property tests alongside existing unit tests.

Version guards for PBKDF2 tests: All PBKDF2 test classes and their registration in the tests function must be wrapped in ifdef "openssl_1.1.x" or "openssl_3.0.x" then ... end, following the pattern used for shake128/shake256 tests on lines 153-167 of the existing _test.pony. This prevents compile_error when building with ssl=0.9.0.

HmacSha256 properties:

1. Output length is always 32 bytes. Generator: pairs of (Array[U8] val, Array[U8] val) with sizes 0-256 for key and data. Property: HmacSha256(key, data).size() == 32.

2. Deterministic. Generator: pairs of (Array[U8] val, Array[U8] val). Property: HmacSha256(key, data) == HmacSha256(key, data) (two calls with the same inputs produce identical output).

Pbkdf2Sha256 properties:

1. Output length equals requested key_length. Generator: key_length in range 1-128. Use fixed password/salt/iterations for speed. Property: Pbkdf2Sha256("p", "s", 1, key_length)?.size() == key_length.

2. Deterministic. Generator: key_length in range 1-64. Property: Pbkdf2Sha256("p", "s", 1, key_length)? == Pbkdf2Sha256("p", "s", 1, key_length)?.

RandBytes properties:

1. Output length equals requested size. Generator: size in range 0-256. Property: RandBytes(size)?.size() == size.

2. Non-constant output. Generator: size in range 16-256. Property: RandBytes(size)? != RandBytes(size)?. (For 16+ bytes, the probability of collision is negligible.)

Test case count

• 7 HMAC-SHA-256 RFC 4231 test cases (one test class, multiple assertions)
• 2 PBKDF2 RFC 7914 test cases
• 1 PBKDF2 SCRAM test case (RFC 7677)
• 2 HMAC SCRAM intermediate value tests (RFC 7677)
• 3 RandBytes basic tests
• 2 HmacSha256 PonyCheck properties
• 2 Pbkdf2Sha256 PonyCheck properties
• 2 RandBytes PonyCheck properties

Other Changes

Package docstring update

Update ssl/crypto/crypto.pony to mention the new primitives. The current docstring says "cryptographic algorithms and functions often useful in cryptographic code for their use in information security." Add the new primitives to the description.

Example

New directory: examples/hmac-pbkdf2-example/

A self-contained example demonstrating all three primitives. File named hmac-pbkdf2-example.pony (matching the existing convention where the file name matches the directory name). No corral.json (existing examples don't have one). Includes the use-statement comment explaining the import path difference:

// in your code this `use` statement would be:
// use "ssl/crypto"
use "../../ssl/crypto"

actor Main
  new create(env: Env) =>
    // HMAC-SHA-256: compute a message authentication code
    let mac = HmacSha256("secret-key", "Hello, World!")
    env.out.print("HMAC-SHA-256: " + ToHexString(mac))

    // PBKDF2-SHA-256: derive a key from a password
    ifdef "openssl_1.1.x" or "openssl_3.0.x" then
      try
        let derived = Pbkdf2Sha256("my-password", "random-salt", 4096, 32)?
        env.out.print("PBKDF2 derived key: " + ToHexString(derived))
      else
        env.err.print("PBKDF2 derivation failed")
      end
    end

    // RandBytes: generate cryptographically secure random data
    try
      let nonce = RandBytes(24)?
      env.out.print("Random nonce: " + ToHexString(nonce))
    else
      env.err.print("Random generation failed")
    end

CLAUDE.md update

Add the three new files to the Key Files table. Note the new primitives in the description of the crypto package.

Implementation Steps

1. Create ssl/crypto/hmac_sha256.pony with the HmacSha256 primitive.
2. Create ssl/crypto/pbkdf2_sha256.pony with the Pbkdf2Sha256 primitive.
3. Create ssl/crypto/rand_bytes.pony with the RandBytes primitive.
4. Add tests to ssl/crypto/_test.pony: RFC test vectors + PonyCheck property tests.
5. Create examples/hmac-pbkdf2-example/hmac-pbkdf2-example.pony.
6. Update ssl/crypto/crypto.pony package docstring.
7. Update CLAUDE.md to document new files.
8. Build and test: make test ssl=3.0.x.
9. Counterfactual testing on new test assertions.

[SeanTAllen]

implemented in #16