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]
]
endSigning (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")}
endThe 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
iatis less than:max_ageseconds old (403 Stale Date otherwise), - its originating and destination numbers are the ones of the request (438 otherwise),
- the certificate of its
x5u(orinfo) URL can be fetched, is valid and chains to one of the:trustedcertificates, 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),:invalidor: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
@type attest() :: String.t()
An attestation level: "A" (full), "B" (partial) or "C" (gateway).
@type error() ::
:no_identity
| :invalid_identity_header
| :unsupported_credential
| :stale_date
| :bad_identity_info
Why an Identity header failed verification.
@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 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
@spec clear_cache(module()) :: :ok
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.
Options:
:attest- attestation level,"A","B"or"C"(the:attestof the configuration by default).:origid- origination identifier (a new UUID by default).:iat- issue time, in seconds since the epoch (now by default).
@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"]}
@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.
@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).