Places an ExFPE context under your supervision tree so that you can encrypt and decrypt without threading the context through every call.

A module that declares use ExFPE gets:

• a child_spec/2 / child_spec/3 builder and a start_link/3, backed by a uniquely named process holding the context in a :persistent_term;
• encrypt/2, encrypt!/2, decrypt/2, decrypt!/2 that retrieve the context transparently; plus constraints/0 and ex_fpe!/0.

You implement the child_spec/0 callback declaring your configuration, and add MyModule.child_spec() to your supervision tree.

defmodule MyApp.CardCipher do
  use ExFPE

  @impl true
  def child_spec do
    child_spec(fetch_key(), :ff3_1, _radix = 10)
  end

  defp fetch_key, do: Application.fetch_env!(:my_app, :fpe_key)
end

# in your application's supervision tree:
children = [
  MyApp.CardCipher.child_spec(),
  # ...
]

# then, anywhere:
MyApp.CardCipher.encrypt!(tweak, "34436524")

@spec constraints(t()) :: constraints()

Returns a ctx's mode-specific length constraints (min_length/max_length).

@spec decrypt(t(), tweak(), ciphertext) :: {:ok, plaintext} | {:error, term()}
when ciphertext: String.t(), plaintext: String.t()

Decrypts ciphertext back into its plaintext numerical string, using tweak.

Returns {:error, reason} if the tweak or input is invalid.

@spec decrypt!(t(), tweak(), ciphertext) :: plaintext
when ciphertext: String.t(), plaintext: String.t()

Like decrypt/3, but returns the plaintext directly and raises ExFPE.InputError on failure.

@spec encrypt(t(), tweak(), plaintext) :: {:ok, ciphertext} | {:error, term()}
when plaintext: String.t(), ciphertext: String.t()

Encrypts plaintext into a numerical string of the same length over the same alphabet, using tweak.

Returns {:error, reason} if the tweak or input is invalid.

@spec encrypt!(t(), tweak(), plaintext) :: ciphertext
when plaintext: String.t(), ciphertext: String.t()

Like encrypt/3, but returns the ciphertext directly and raises ExFPE.InputError on failure.

@spec new(key(), mode(), radix() | alphabet() | {:raw_only, radix()}) ::
  {:ok, ctx :: t()} | {:error, term()}

Creates a context for both encryption and decryption from a key, an optional mode (:ff1 by default), and either a radix, an alphabet, or {:raw_only, radix}.

A radix or alphabet encrypts strings with encrypt/3/decrypt/3; {:raw_only, radix} skips symbols entirely and works with integers through raw_encrypt/4/raw_decrypt/4.

Returns {:error, reason} if any argument is invalid.

@spec new!(key(), mode(), radix() | alphabet() | {:raw_only, radix()}) :: ctx :: t()

Like new/3, but returns the context directly and raises ExFPE.ArgumentError on failure.

@spec raw_decrypt(t(), tweak(), cipherval, length) ::
  {:ok, plainval} | {:error, term()}
when cipherval: non_neg_integer(),
     length: pos_integer(),
     plainval: non_neg_integer()

Decrypts the integer cipherval back into its plaintext value, skipping the symbol alphabet.

The alphabet-free counterpart to decrypt/3; see raw_encrypt/4 for how length and the 0 <= value < radix ** length bound work.

Returns {:error, reason} if the tweak or input is invalid.

@spec raw_decrypt!(t(), tweak(), cipherval, length) :: plainval
when cipherval: non_neg_integer(),
     length: pos_integer(),
     plainval: non_neg_integer()

Like raw_decrypt/4, but returns the plaintext value directly and raises ExFPE.InputError on failure.

@spec raw_encrypt(t(), tweak(), plainval, length) ::
  {:ok, cipherval} | {:error, term()}
when plainval: non_neg_integer(),
     length: pos_integer(),
     cipherval: non_neg_integer()

Encrypts the integer plainval directly, skipping the symbol alphabet.

This is the alphabet-free counterpart to encrypt/3: you hand it an integer and it hands an integer back, leaving the mapping between integers and whatever symbols they stand for up to you. Reach for it when your symbols aren't a single Unicode scalar each (so a custom alphabet can't accept them), when the value already lives as an integer in your system, or to avoid string encoding on a hot path.

plainval is interpreted as length digits in the context's radix, most significant first. length is significant and must be passed explicitly: FPE treats leading zeroes as real symbols, so {value: 42, length: 2} ("42") and {value: 42, length: 5} ("00042") encrypt differently and can't be told apart from the value alone. The ciphertext preserves length.

plainval must fit its declared length — that is, 0 <= plainval < radix ** length — otherwise this returns {:error, {:negative_value, plainval}} or {:error, {:value_is_larger_than_declared_length}}.

Any context supports this, including one built from an alphabet: it operates on the context's radix and ignores the alphabet. A context built with {:raw_only, radix} supports only these functions, not encrypt/3.

Returns {:error, reason} if the tweak or input is invalid.

@spec raw_encrypt!(t(), tweak(), plainval, length) :: cipherval
when plainval: non_neg_integer(),
     length: pos_integer(),
     cipherval: non_neg_integer()

Like raw_encrypt/4, but returns the ciphertext value directly and raises ExFPE.InputError on failure.