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

Copy Markdown View Source

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.

Summary

Types

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

Why an Identity header failed verification.

The claims of a PASSporT that verified correctly.

Functions

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

Removes the cached certificates of a service.

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

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

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.

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

Types

attest()

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

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

error()

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

Why an Identity header failed verification.

verified()

@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.

Functions

canonical(number)

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

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

Removes the cached certificates of a service.

identity(service, orig, dest, opts \\ [])

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

@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(service, req, opts \\ [])

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

@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).