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

Caller identity signing and verification with STIR/SHAKEN: the
`Identity` header (RFC 8224) with a PASSporT (RFC 8225) and the SHAKEN
extension (RFC 8588), signed with ES256.

```
defmodule MyProxy do
  use Malla.Service,
    plugins: [Caracola.StirShaken],
    sip: [listen: "sip:all:5060"],
    stir_shaken: [
      key: File.read!("priv/shaken_key.pem"),
      x5u: "https://cert.example.com/shaken.pem",
      verify: [trusted: [File.read!("priv/sti_ca.pem")], enforce: :invalid]
    ]
end
```

## Signing (authentication service)

The service signs the calls it originates or proxies, with the `:key`
(an EC P-256 private key, in PEM) whose certificate is published at the
`:x5u` URL. The application decides the attestation level (`"A"`, `"B"`
or `"C"`, RFC 8588 §4) and adds the header with `sign_opts/3`:

```
defcb sip_route(_scheme, _user, _domain, req, call) do
  {:proxy, :ruri, Caracola.StirShaken.sign_opts(call.service, req, attest: "A")}
end
```

The originating number is the one of the P-Asserted-Identity, if any,
or the From; the destination is the one of the To. `identity/4` builds
the header for other numbers.

## Verification (verification service)

`verify/2` checks the `Identity` header of a request (RFC 8224 §6.2):

  * its PASSporT is well formed and uses ES256 (438 and 437 otherwise),
  * it is fresh: its `iat` is less than `:max_age` seconds old (403
    Stale Date otherwise),
  * its originating and destination numbers are the ones of the request
    (438 otherwise),
  * the certificate of its `x5u` (or `info`) URL can be fetched, is valid
    and chains to one of the `:trusted` certificates, and the PASSporT is
    signed with its key (436 or 438 otherwise).

Certificates are cached for `:cache_time` milliseconds. They are fetched
over HTTPS by `sip_stir_shaken_fetch/2`, which services can implement to
fetch them otherwise. Without `:trusted` certificates the chain is not
checked, which is only acceptable for tests.

With `enforce: :invalid` (or `:all`), initial INVITEs are verified
before they are routed, and rejected if the verification fails (and, with
`:all`, if they have no Identity: 428). Otherwise, the application calls
`verify/2` and decides, for example, the `verstat` to pass on.

Numbers are compared in canonical form (RFC 8224 §8.3): the user part of
SIP URIs (or the number of tel URIs) without `+` nor visual separators.
Only telephone numbers are supported, and PASSporTs in compact form
(without claims) are rejected.

## Configuration

Under the `:stir_shaken` key:

  * `:key` - EC P-256 private key to sign with, in PEM.
  * `:x5u` - URL of the certificate of the key.
  * `:attest` - default attestation level (default `"C"`).
  * `:verify` - verification options:
    * `:trusted` - trusted CA certificates, in PEM (default `[]`).
    * `:max_age` - maximum age of a PASSporT, in seconds (default 60).
    * `:cache_time` - milliseconds to cache certificates (default
      3600000).
    * `:enforce` - `false` (default), `:invalid` or `:all`.

# `attest`

```elixir
@type attest() :: String.t()
```

An attestation level: `"A"` (full), `"B"` (partial) or `"C"` (gateway).

# `error`

```elixir
@type error() ::
  :no_identity
  | :invalid_identity_header
  | :unsupported_credential
  | :stale_date
  | :bad_identity_info
```

Why an Identity header failed verification.

# `verified`

```elixir
@type verified() :: %{
  attest: attest() | nil,
  orig: String.t(),
  dest: [String.t()],
  iat: integer(),
  origid: String.t() | nil,
  x5u: String.t()
}
```

The claims of a PASSporT that verified correctly.

# `canonical`

```elixir
@spec canonical(String.t() | nil) :: String.t() | nil
```

Canonical form of a telephone number (RFC 8224 §8.3): without `+` nor
visual separators. `nil` if it is not a number.

    iex> Caracola.StirShaken.canonical("+1 (555) 123-4567")
    "15551234567"
    iex> Caracola.StirShaken.canonical("alice")
    nil

# `clear_cache`

```elixir
@spec clear_cache(module()) :: :ok
```

Removes the cached certificates of a service.

# `identity`

```elixir
@spec identity(module(), String.t(), [String.t()], keyword()) :: String.t()
```

The value of an Identity header signed by the service, for an
originating number and the destination numbers.

Options:

  * `:attest` - attestation level, `"A"`, `"B"` or `"C"` (the
    `:attest` of the configuration by default).
  * `:origid` - origination identifier (a new UUID by default).
  * `:iat` - issue time, in seconds since the epoch (now by default).

# `reply`

```elixir
@spec reply(error()) :: Caracola.Reply.sipreply()
```

The reply for a verification failure (RFC 8224 §6.2.2).

    iex> Caracola.StirShaken.reply(:stale_date)
    {403, [reason_phrase: "Stale Date"]}

# `sign_opts`

```elixir
@spec sign_opts(module(), Caracola.Message.t(), keyword()) :: list()
```

Request or proxy options adding an Identity header to a request, signed
by the service. The originating number is the one of the
P-Asserted-Identity or the From of `req`, and the destination the one of
its To. Options are the ones of `identity/4`.

# `verify`

```elixir
@spec verify(module(), Caracola.Message.t()) :: {:ok, verified()} | {:error, error()}
```

Verifies the Identity header of a request. Returns the verified claims,
or the reason of the failure (see `reply/1`).

---

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