# `Macaw.Auth.Native.Source.Ldap.Escape`
[🔗](https://github.com/dcoai/macaw_auth/blob/v0.4.1/lib/macaw/auth/native/source/ldap/escape.ex#L1)

Escaping for values placed in LDAP distinguished names and search
filters, so a username can never change a DN or widen a search. Ported
from exio's, with two fixes.

- `dn_value/1` (RFC 4514 §2.4): `, + " \ < > ; =` are escaped with a
  backslash wherever they are, `#` and space at the start and space at
  the end likewise, and NUL is `\00`. The older copies (eesidai, mdview)
  wrote `"\;"`, which in Elixir is just `";"`, so a `;` went unescaped;
  here every special is a character literal, and a property test proves
  no special survives unescaped. exio's trailing-space rule looked at the
  *escaped* text, so a value ending in a backslash and a space (`a\ `)
  kept its space bare; this decides by position in the *original* value.
- `filter_value/1` (RFC 4515 §3): `* ( ) \` and NUL become `\2a \28
  \29 \5c \00`.

The search filter itself never has a username spliced into its text:
`Macaw.Auth.Native.Source.Ldap.Filter` builds the `:eldap` term with the
username as data. `filter_value/1` is for showing that filter as text
(`Macaw.Auth.Native.Source.Ldap.diagnose/3`) and for hosts that write
their own. The `*_unescape` functions invert the escaping; the property
tests round-trip through them.

# `dn_unescape`

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

Inverts RFC 4514 value escaping: `\hh` is that byte, `\c` is `c`.
`{:ok, value}`, or `:error` for a dangling backslash or a bad hex pair.

# `dn_value`

```elixir
@spec dn_value(binary()) :: binary()
```

A value escaped for an RFC 4514 attribute value in a DN.

# `filter_unescape`

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

Inverts RFC 4515 value escaping: `\hh` is that byte. `{:ok, value}`, or
`:error` for a backslash not followed by two hex digits.

# `filter_value`

```elixir
@spec filter_value(binary()) :: binary()
```

A value escaped for an RFC 4515 assertion value in a search filter.

---

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