Polish docs and drop OTP 22 crypto scaffolding

- README: replace the removed Java-implementation attribution with a
  pointer to the sibling `ex_fpe` library; fix radix range to 2..65535.
- AGENTS.md: rewrite the architecture/gotchas to match the `ex_fpe`-style
  algorithm (do_encdec/setup_encdec_vars/#aux record/prf/ciph), correct the
  -spec and dialyzer notes, and record the non_negative_rem/2 pitfall.
- Module docs: bump the documented radix range to 2..65535.
- rebar.config: drop the now-unused POST_OTP_22 platform_define and raise
  minimum_otp_vsn to 24.0 (crypto:crypto_one_time/5 is used unconditionally).
- CHANGELOG: note the minimum OTP bump.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: g-andrade

AGENTS.md

@@ -26,9 +26,10 @@ All checks run sequentially (`.NOTPARALLEL`). CI runs `make check-fast`,
 ## Compiler flags
 
 Always on: `warn_export_vars`, `warn_missing_spec`, `warn_unused_import`,
-`warnings_as_errors`. Every function (including internal helpers) carries a
-`-spec`. The `test` profile relaxes `warn_missing_spec` and
-`warnings_as_errors`.
+`warnings_as_errors`. `warn_missing_spec` only requires specs on **exported**
+functions, so the public API and the `validate_*` helpers are spec'd, but the
+internal round/PRF helpers (`do_encdec/7`, `do_encrypt_rounds/5`, etc.) are not.
+The `test` profile relaxes `warn_missing_spec` and `warnings_as_errors`.
 
 ## Architecture
 
@@ -41,10 +42,27 @@ There is one module, `erlffx`, with a four-function public API:
 | `decrypt/2` | Reverse `encrypt/2` |
 
 Internally: `config/3` merges params into a `raw_config()` map and validates it
-into the opaque `config()` (mandatory keys). `encrypt`/`decrypt` run the
-alternating Feistel network (`encrypt_loop`/`decrypt_loop`); each round's PRF
-`fk/4` builds the FFX `P`/`Q` blocks and runs AES-CBC-MAC (`aes_cbc_mac/2` →
-`aes_cbc/3`). Integers are carried as `maginteger()` `{Value, Magnitude}` pairs.
+into the opaque `config()` (mandatory keys). Both `encrypt/2` and `decrypt/2`
+delegate to `do_encdec/7` (a `DoEncrypt` boolean picks the direction).
+`setup_encdec_vars/6` derives the per-call parameters into an `#aux{}` record
+(`u`/`v` halves, `small_b`, `d`, the `P` block, the `Q` zero-padding) and splits
+the input integer into its `{A, B}` halves via `split_num_string_int/3`. The
+Feistel network then runs as `do_encrypt_rounds/5` (rounds `0..NumberOfRounds-1`)
+or `do_decrypt_rounds/4` (rounds counting back down to `-1`). Each round builds
+the FFX `P || Q` blocks, computes `R = prf/2` (AES-CBC-MAC: `crypto_one_time/5`
+in CBC mode, keeping the last 16 bytes), expands it to `S` with
+`compute_s_blocks/3` (`R || CIPH(R⊕1) || …` using `ciph/2`, AES-ECB), and folds
+`Y = NUM(S)` into the running half with `non_negative_rem/2` (addition when
+encrypting, subtraction when decrypting) modulo `radix^m`. The result is
+reconstructed as `FinalB + FinalA * radix^v`. Integers are plain Erlang
+integers throughout — the earlier `maginteger()` `{Value, Magnitude}` pairs are
+gone.
+
+> **`non_negative_rem/2` gotcha:** it must fold the result fully into `[0, B)`
+> via `((A rem B) + B) rem B`. A negative `A` that is an exact multiple of `B`
+> makes `A rem B` zero, so the naïve `(A rem B) + B` wrongly returns `B` — which
+> broke `decrypt/2` round-trips for the rare inputs where `B - Y` lands on an
+> exact multiple of `radix^m`.
 
 ## Conventions and gotchas
 
@@ -53,10 +71,10 @@ alternating Feistel network (`encrypt_loop`/`decrypt_loop`); each round's PRF
   26 (its `-doc` triple-quoted-string handling is broken there); `rebar3_hank`
   is dropped on OTP 29 (katana_code bug). So `make check-fast` is a partial
   no-op on those OTP releases — develop/lint on OTP 27+ (28 is the reference).
-- **Crypto API split**: `aes_cbc/3` uses `crypto:crypto_one_time/5` on OTP ≥ 23
-  and the removed `crypto:block_encrypt/4` on OTP 22, selected by the
-  `POST_OTP_22` `platform_define`. `minimum_otp_vsn` is `22.0` but only **24+**
-  is supported.
+- **Crypto**: `prf/2` and `ciph/2` call `crypto:crypto_one_time/5`
+  unconditionally (no OTP 22 `crypto:block_encrypt/4` fallback anymore). The old
+  `POST_OTP_22` `platform_define` is gone and `minimum_otp_vsn` is `24.0`, which
+  matches what is actually supported.
 - **Docs are EEP-48**, not edoc text. Public docs are `-moduledoc`/`-doc`
   triple-quoted attributes guarded by `-ifdef(E48).` (`E48` is defined on OTP
   27+). The internal helpers are simply unexported, so ex_doc omits them — no
@@ -72,10 +90,11 @@ alternating Feistel network (`encrypt_loop`/`decrypt_loop`); each round's PRF
   `dont_repeat_yourself` and `max_line_length` because the known-answer test
   vectors are intentionally repetitive and carry long literals (256-bit keys,
   digit lists). `src/` uses the default ruleset with no exceptions.
-- **dialyzer** runs with `underspecs` on. Keep specs tight: the P value is
-  `<<_:128>>`, magnitudes are `pos_integer()`, the opaque `config()` uses
-  mandatory (`:=`) keys, and the AES key/CBC data flow is typed over binaries
-  (`validate_aes_key/1` normalizes any `iodata()` key to a binary).
+- **dialyzer** runs with `underspecs` on. Keep specs tight: the opaque
+  `config()` uses mandatory (`:=`) keys, the `#aux{}` record fields are typed
+  (`u`/`v` as `pos_integer()`, `radix()`, binaries for `p`/`q_zeros`), and the
+  AES key flow is typed over binaries (`validate_aes_key/1` normalizes any
+  `iodata()` key to a binary).
 
 ## Tests
 

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ### Changed
 
 - max radix from 255 to 65535
+- minimum OTP version to 24
 - implementation to be in the spirit of
   [`ex_fpe`](https://github.com/g-andrade/ex_fpe)
 

README.md

@@ -7,13 +7,12 @@
 `erlffx` is an Erlang implementation of the mechanism described in the 2010
 paper [The FFX Mode of Operation for Format-Preserving
 Encryption](https://csrc.nist.gov/csrc/media/projects/block-cipher-techniques/documents/bcm/proposed-modes/ffx/ffx-spec.pdf)
-by Bellare, Rogaway and Spies. It is based on an existing [Java
-implementation](https://github.com/michaeltandy/java-ffx-format-preserving-encryption)
-by Michael Tandy.
+by Bellare, Rogaway and Spies. Its algorithm follows the sibling Elixir
+library [`ex_fpe`](https://github.com/g-andrade/ex_fpe).
 
 * AES-128 / AES-192 / AES-256 keys are supported (CBC mode)
 * Any positive word length is supported
-* Any radix / alphabet size between 2 and 255 is acceptable (10 by default)
+* Any radix / alphabet size between 2 and 65535 is acceptable (10 by default)
 * Optional 'tweak' values may be defined
 * The number of rounds is configurable (10 by default)
 

rebar.config

@@ -2,8 +2,7 @@
 
 %% == Erlang Compiler == %%
 
-% but only 24+ is supported
-{minimum_otp_vsn, "22.0"}.
+{minimum_otp_vsn, "24.0"}.
 
 {erl_opts, [
     debug_info,
@@ -12,9 +11,6 @@
     warn_unused_import,
     warnings_as_errors,
     %
-    % crypto API split: crypto:crypto_one_time/5 (23+) vs crypto:block_encrypt/4
-    {platform_define, "^((2[3-9])|([3-9]))", 'POST_OTP_22'},
-    %
     % EEP-48 doc attributes (OTP 27+)
     {platform_define, "^2[7-9]\\.", 'E48'},
     {platform_define, "^[3-9]", 'E48'}

src/erlffx.erl

@@ -13,7 +13,7 @@ a chosen radix, so the ciphertext keeps the format of the plaintext. See the
 
 - AES-128 / AES-192 / AES-256 keys are supported (CBC mode).
 - Any positive word length is supported.
-- Any radix / alphabet size between 2 and 255 is acceptable (10 by default).
+- Any radix / alphabet size between 2 and 65535 is acceptable (10 by default).
 - Optional 'tweak' values may be defined.
 - The number of Feistel rounds is configurable (10 by default).
 """.
@@ -120,7 +120,7 @@ Builds an opaque encryption `t:config/0`.
 
 - `AesKey` must be a 16-, 24- or 32-byte (AES-128/192/256) key.
 - `ValueLength` is the word length, in digits of the chosen radix.
-- `OptionalParams` may set the `tweak`, the `radix` (2..255, default 10) and
+- `OptionalParams` may set the `tweak`, the `radix` (2..65535, default 10) and
   the `number_of_rounds` (default 10).
 
 The same `t:config/0` must be used to `encrypt/2` and `decrypt/2` a value.