# `Apero.Crypto.Cipher`
[🔗](https://github.com/Lorenzo-SF/apero/blob/3.0.0/lib/apero/crypto/cipher.ex#L1)

Symmetric encryption and streaming cipher utilities.

Supports AES-256-GCM (authenticated), ChaCha20-Poly1305, and
AES-256-CTR (streaming mode for large files/streams).

All encrypted values are self-contained (IV/nonce + tag + ciphertext,
Base64-encoded) and use `:crypto.strong_rand_bytes/1` for key/IV generation.

# `decrypt`

```elixir
@spec decrypt(binary(), binary()) :: {:ok, binary()} | {:error, term()}
```

Decrypts a value encrypted with `encrypt/2`. Returns `{:ok, plaintext}` or `{:error, reason}`.

# `decrypt_chacha20`

```elixir
@spec decrypt_chacha20(binary(), binary()) :: binary() | :error
```

Decrypts ChaCha20-Poly1305 encrypted data. Returns plaintext on success, :error on failure.

# `decrypt_ctr`

```elixir
@spec decrypt_ctr(binary(), binary(), binary()) :: {:ok, binary()} | :error
```

Decrypts data encrypted with AES-256-CTR streaming.

# `encrypt`

```elixir
@spec encrypt(binary(), binary() | nil) :: {:ok, binary()}
```

Encrypts plaintext with AES-256-GCM. Returns `{:ok, ciphertext}`.

# `encrypt_chacha20`

```elixir
@spec encrypt_chacha20(binary(), binary()) :: binary()
```

Encrypts plaintext with ChaCha20-Poly1305.

# `stream_encrypt`

```elixir
@spec stream_encrypt(
  {any(), binary()},
  binary()
) :: {any(), binary(), binary()}
```

Encrypts a chunk of data in streaming mode.

# `stream_finalize`

```elixir
@spec stream_finalize(any()) :: binary()
```

Finalizes a streaming encryption. Returns the final state (discard after).

# `stream_init`

```elixir
@spec stream_init(binary()) :: {any(), binary()}
```

Starts an AES-256-CTR encryption stream. Use with `stream_encrypt/2` and `stream_finalize/1`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*