Caracola.AssertedIdentity (Caracola v0.1.0-rc.1)

Copy Markdown View Source

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 []).

Summary

Types

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

Functions

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.

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

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

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

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

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

Types

privacy()

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

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

Functions

assert_opts(identities)

@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(req, trusted_destination?)

@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(msg)

@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(msg)

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

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

privacy(msg)

@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?(service, ip)

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

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