# `Caracola.AssertedIdentity`
[🔗](https://github.com/netkubes/caracola/blob/v0.1.0-rc.1/lib/caracola/asserted_identity.ex#L1)

Asserted identity within a trust domain (RFC 3325) and privacy (RFC
3323): the `P-Asserted-Identity`, `P-Preferred-Identity` and `Privacy`
headers.

```
defmodule MyProxy do
  use Malla.Service,
    plugins: [Caracola.AssertedIdentity],
    sip: [listen: "sip:all:5060"],
    asserted_identity: [trusted: ["10.0.0.0/8", "192.0.2.10"]]
end
```

The trust domain is the list of `:trusted` addresses (IPv4 or IPv6, with
an optional prefix length). P-Asserted-Identity headers of requests
received from any other address are removed before they are authorized
or routed (RFC 3325 §5), so `identities/1` only returns identities
asserted by trusted nodes.

A proxy that has authenticated a user asserts its identity with the
options of `assert_opts/1` (which also remove P-Preferred-Identity), and
before forwarding a request outside the trust domain uses the options of
`forward_opts/2`, which remove the asserted identity if the user asked
for it with `Privacy: id` (RFC 3325 §9.3):

```
defcb sip_route(_scheme, user, "example.com", req, call) do
  opts = Caracola.AssertedIdentity.assert_opts("<sip:" <> user <> "@example.com>")
  {:proxy, :ruri, opts ++ [:record_route]}
end
```

User agents ask for privacy with the `Privacy` header (`{:add,
"privacy", "id"}`) and an anonymous From (RFC 3323 §4.1.1).

## Configuration

Under the `:asserted_identity` key:

  * `:trusted` - addresses of the trust domain (default `[]`).

# `privacy`

```elixir
@type privacy() :: :id | :header | :session | :user | :none | :critical | String.t()
```

A privacy value of the `Privacy` header (RFC 3323, RFC 3325).

# `assert_opts`

```elixir
@spec assert_opts(String.t() | Caracola.URI.t() | [String.t() | Caracola.URI.t()]) ::
  list()
```

Proxy or request options asserting identities (a URI or a list of
them, as a SIP URI and a tel URI): they replace P-Asserted-Identity and
remove P-Preferred-Identity.

# `forward_opts`

```elixir
@spec forward_opts(Caracola.Message.t(), boolean()) :: list()
```

Proxy options to forward a request: if the destination is not trusted
and the request has `Privacy: id`, the asserted identity is removed.

# `identities`

```elixir
@spec identities(Caracola.Message.t()) :: [Caracola.URI.t()]
```

The identities asserted in a request (P-Asserted-Identity), only present
if it came from the trust domain.

# `preferred`

```elixir
@spec preferred(Caracola.Message.t()) :: [Caracola.URI.t()]
```

The identities a user agent asks to be asserted (P-Preferred-Identity).

# `privacy`

```elixir
@spec privacy(Caracola.Message.t()) :: [privacy()]
```

The privacy values of a message (RFC 3323 §4.2).

    iex> {:ok, msg} = Caracola.Message.update_header(%Caracola.Message{}, :add, "Privacy", "id; critical")
    iex> Caracola.AssertedIdentity.privacy(msg)
    [:id, :critical]

# `trusted?`

```elixir
@spec trusted?(module(), :inet.ip_address()) :: boolean()
```

Returns `true` if an address belongs to the trust domain of a service.

---

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