mirror of
https://github.com/asterisk/asterisk.git
synced 2025-09-03 11:25:35 +00:00
d7e262226f
Why do we need a refactor?
The original stir/shaken implementation was started over 3 years ago
when little was understood about practical implementation. The
result was an implementation that wouldn't actually interoperate
with any other stir-shaken implementations.
There were also a number of stir-shaken features and RFC
requirements that were never implemented such as TNAuthList
certificate validation, sending Reason headers in SIP responses
when verification failed but we wished to continue the call, and
the ability to send Media Key(mky) grants in the Identity header
when the call involved DTLS.
Finally, there were some performance concerns around outgoing
calls and selection of the correct certificate and private key.
The configuration was keyed by an arbitrary name which meant that
for every outgoing call, we had to scan the entire list of
configured TNs to find the correct cert to use. With only a few
TNs configured, this wasn't an issue but if you have a thousand,
it could be.
What's changed?
* Configuration objects have been refactored to be clearer about
their uses and to fix issues.
* The "general" object was renamed to "verification" since it
contains parameters specific to the incoming verification
process. It also never handled ca_path and crl_path
correctly.
* A new "attestation" object was added that controls the
outgoing attestation process. It sets default certificates,
keys, etc.
* The "certificate" object was renamed to "tn" and had it's key
change to telephone number since outgoing call attestation
needs to look up certificates by telephone number.
* The "profile" object had more parameters added to it that can
override default parameters specified in the "attestation"
and "verification" objects.
* The "store" object was removed altogther as it was never
implemented.
* We now use libjwt to create outgoing Identity headers and to
parse and validate signatures on incoming Identiy headers. Our
previous custom implementation was much of the source of the
interoperability issues.
* General code cleanup and refactor.
* Moved things to better places.
* Separated some of the complex functions to smaller ones.
* Using context objects rather than passing tons of parameters
in function calls.
* Removed some complexity and unneeded encapsuation from the
config objects.
Resolves: #351
Resolves: #46
UserNote: Asterisk's stir-shaken feature has been refactored to
correct interoperability, RFC compliance, and performance issues.
See https://docs.asterisk.org/Deployment/STIR-SHAKEN for more
information.
UpgradeNote: The stir-shaken refactor is a breaking change but since
it's not working now we don't think it matters. The
stir_shaken.conf file has changed significantly which means that
existing ones WILL need to be changed. The stir_shaken.conf.sample
file in configs/samples/ has quite a bit more information. This is
also an ABI breaking change since some of the existing objects
needed to be changed or removed, and new ones added. Additionally,
if res_stir_shaken is enabled in menuselect, you'll need to either
have the development package for libjwt v1.15.3 installed or use
the --with-libjwt-bundled option with ./configure.
(cherry picked from commit 2e0d837e01)
294 lines
13 KiB
XML
294 lines
13 KiB
XML
<!DOCTYPE docs SYSTEM "appdocsxml.dtd">
|
|
<?xml-stylesheet type="text/xsl" href="appdocsxml.xslt"?>
|
|
<docs xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<configInfo name="res_stir_shaken" language="en_US">
|
|
<synopsis>STIR/SHAKEN module for Asterisk</synopsis>
|
|
<configFile name="stir_shaken.conf">
|
|
<configObject name="attestation">
|
|
<synopsis>STIR/SHAKEN attestation options</synopsis>
|
|
<configOption name="global_disable" default="false">
|
|
<synopsis>Globally disable verification</synopsis>
|
|
</configOption>
|
|
<configOption name="private_key_file" default="">
|
|
<synopsis>File path to a certificate</synopsis>
|
|
</configOption>
|
|
<configOption name="public_cert_url" default="">
|
|
<synopsis>URL to the public certificate</synopsis>
|
|
<description><para>
|
|
Must be a valid http, or https, URL.
|
|
</para></description>
|
|
</configOption>
|
|
<configOption name="attest_level">
|
|
<synopsis>Attestation level</synopsis>
|
|
</configOption>
|
|
<configOption name="check_tn_cert_public_url" default="false">
|
|
<synopsis>On load, Retrieve all TN's certificates and validate their dates</synopsis>
|
|
</configOption>
|
|
<configOption name="send_mky" default="no">
|
|
<synopsis>Send a media key (mky) grant in the attestation for DTLS calls.
|
|
(not common)</synopsis>
|
|
</configOption>
|
|
</configObject>
|
|
<configObject name="tn">
|
|
<synopsis>STIR/SHAKEN TN options</synopsis>
|
|
<configOption name="type">
|
|
<synopsis>Must be of type 'tn'.</synopsis>
|
|
</configOption>
|
|
<configOption name="private_key_file" default="">
|
|
<synopsis>File path to a certificate</synopsis>
|
|
</configOption>
|
|
<configOption name="public_cert_url" default="">
|
|
<synopsis>URL to the public certificate</synopsis>
|
|
<description><para>
|
|
Must be a valid http, or https, URL.
|
|
</para></description>
|
|
</configOption>
|
|
<configOption name="attest_level">
|
|
<synopsis>Attestation level</synopsis>
|
|
</configOption>
|
|
<configOption name="check_tn_cert_public_url" default="false">
|
|
<synopsis>On load, Retrieve all TN's certificates and validate their dates</synopsis>
|
|
</configOption>
|
|
<configOption name="send_mky" default="no">
|
|
<synopsis>Send a media key (mky) grant in the attestation for DTLS calls.
|
|
(not common)</synopsis>
|
|
</configOption>
|
|
</configObject>
|
|
<configObject name="verification">
|
|
<synopsis>STIR/SHAKEN verification options</synopsis>
|
|
<configOption name="global_disable" default="false">
|
|
<synopsis>Globally disable verification</synopsis>
|
|
</configOption>
|
|
<configOption name="load_system_certs" default="">
|
|
<synopsis>A boolean indicating whether trusted CA certificates should be loaded from the system</synopsis>
|
|
</configOption>
|
|
<configOption name="ca_file" default="">
|
|
<synopsis>Path to a file containing one or more CA certs</synopsis>
|
|
</configOption>
|
|
<configOption name="ca_path" default="">
|
|
<synopsis>Path to a directory containing one or more hashed CA certs</synopsis>
|
|
</configOption>
|
|
<configOption name="crl_file" default="">
|
|
<synopsis>Path to a file containing a CRL</synopsis>
|
|
</configOption>
|
|
<configOption name="crl_path" default="">
|
|
<synopsis>Path to a directory containing one or more hashed CRLs</synopsis>
|
|
</configOption>
|
|
<configOption name="cert_cache_dir" default="">
|
|
<synopsis>Directory to cache retrieved verification certs</synopsis>
|
|
</configOption>
|
|
<configOption name="curl_timeout" default="2">
|
|
<synopsis>Maximum time to wait to CURL certificates</synopsis>
|
|
</configOption>
|
|
<configOption name="max_cache_entry_age" default="60">
|
|
<synopsis>Number of seconds a cache entry may be behind current time</synopsis>
|
|
</configOption>
|
|
<configOption name="max_cache_size" default="1000">
|
|
<synopsis>Maximum size to use for caching public keys</synopsis>
|
|
</configOption>
|
|
<configOption name="max_iat_age" default="15">
|
|
<synopsis>Number of seconds an iat grant may be behind current time</synopsis>
|
|
</configOption>
|
|
<configOption name="max_date_header_age" default="15">
|
|
<synopsis>Number of seconds a SIP Date header may be behind current time</synopsis>
|
|
</configOption>
|
|
<configOption name="failure_action" default="continue">
|
|
<synopsis>The default failure action when not set on a profile</synopsis>
|
|
<description>
|
|
<enumlist>
|
|
<enum name="continue">
|
|
<para>If set to <literal>continue</literal>, continue and let
|
|
the dialplan decide what action to take.</para>
|
|
</enum>
|
|
<enum name="reject_request">
|
|
<para>If set to <literal>reject_request</literal>, reject the incoming
|
|
request with response codes defined in RFC8224.
|
|
</para>
|
|
</enum>
|
|
<enum name="continue_return_reason">
|
|
<para>If set to <literal>return_reason</literal>, continue to the
|
|
dialplan but add a <literal>Reason</literal> header to the sender in
|
|
the next provisional response.</para>
|
|
</enum>
|
|
</enumlist>
|
|
</description>
|
|
</configOption>
|
|
<configOption name="use_rfc9410_responses" default="no">
|
|
<synopsis>RFC9410 uses the STIR protocol on Reason headers
|
|
instead of the SIP protocol</synopsis>
|
|
</configOption>
|
|
<configOption name="relax_x5u_port_scheme_restrictions" default="no">
|
|
<synopsis>Relaxes check for "https" and port 443 or 8443
|
|
in incoming Identity header x5u URLs.</synopsis>
|
|
</configOption>
|
|
<configOption name="relax_x5u_path_restrictions" default="no">
|
|
<synopsis>Relaxes check for query parameters, user/password, etc.
|
|
in incoming Identity header x5u URLs.</synopsis>
|
|
</configOption>
|
|
<configOption name="x5u_acl" default="">
|
|
<synopsis>An existing ACL from acl.conf to use when checking
|
|
hostnames in incoming Identity header x5u URLs.</synopsis>
|
|
</configOption>
|
|
<configOption name="x5u_permit" default="">
|
|
<synopsis>An IP or subnet to permit when checking
|
|
hostnames in incoming Identity header x5u URLs.</synopsis>
|
|
</configOption>
|
|
<configOption name="x5u_deny" default="">
|
|
<synopsis>An IP or subnet to deny checking
|
|
hostnames in incoming Identity header x5u URLs.</synopsis>
|
|
</configOption>
|
|
</configObject>
|
|
<configObject name="profile">
|
|
<synopsis>STIR/SHAKEN profile configuration options</synopsis>
|
|
<configOption name="type">
|
|
<synopsis>Must be of type 'profile'.</synopsis>
|
|
</configOption>
|
|
<configOption name="load_system_certs" default="">
|
|
<synopsis>A boolean indicating whether trusted CA certificates should be loaded from the system</synopsis>
|
|
</configOption>
|
|
<configOption name="ca_file" default="">
|
|
<synopsis>Path to a file containing one or more CA certs</synopsis>
|
|
</configOption>
|
|
<configOption name="ca_path" default="">
|
|
<synopsis>Path to a directory containing one or more hashed CA certs</synopsis>
|
|
</configOption>
|
|
<configOption name="crl_file" default="">
|
|
<synopsis>Path to a file containing a CRL</synopsis>
|
|
</configOption>
|
|
<configOption name="crl_path" default="">
|
|
<synopsis>Path to a directory containing one or more hashed CRLs</synopsis>
|
|
</configOption>
|
|
<configOption name="cert_cache_dir" default="">
|
|
<synopsis>Directory to cache retrieved verification certs</synopsis>
|
|
</configOption>
|
|
<configOption name="curl_timeout" default="2">
|
|
<synopsis>Maximum time to wait to CURL certificates</synopsis>
|
|
</configOption>
|
|
<configOption name="max_iat_age" default="15">
|
|
<synopsis>Number of seconds an iat grant may be behind current time</synopsis>
|
|
</configOption>
|
|
<configOption name="max_date_header_age" default="15">
|
|
<synopsis>Number of seconds a SIP Date header may be behind current time</synopsis>
|
|
</configOption>
|
|
<configOption name="max_cache_entry_age" default="60">
|
|
<synopsis>Number of seconds a cache entry may be behind current time</synopsis>
|
|
</configOption>
|
|
<configOption name="max_cache_size" default="1000">
|
|
<synopsis>Maximum size to use for caching public keys</synopsis>
|
|
</configOption>
|
|
<configOption name="endpoint_behavior" default="off">
|
|
<synopsis>Actions performed when an endpoint references this profile</synopsis>
|
|
<description>
|
|
<enumlist>
|
|
<enum name="off">
|
|
<para>Don't do any STIR/SHAKEN processing.</para>
|
|
</enum>
|
|
<enum name="attest">
|
|
<para>Attest on outgoing calls.</para>
|
|
</enum>
|
|
<enum name="verify">
|
|
<para>Verify incoming calls.</para>
|
|
</enum>
|
|
<enum name="on">
|
|
<para>Attest outgoing calls and verify incoming calls.</para>
|
|
</enum>
|
|
</enumlist>
|
|
</description>
|
|
</configOption>
|
|
<configOption name="failure_action" default="continue">
|
|
<synopsis>What do do when a verification fails</synopsis>
|
|
<description>
|
|
<enumlist>
|
|
<enum name="continue">
|
|
<para>If set to <literal>continue</literal>, continue and let
|
|
the dialplan decide what action to take.</para>
|
|
</enum>
|
|
<enum name="reject_request">
|
|
<para>If set to <literal>reject_request</literal>, reject the incoming
|
|
request with response codes defined in RFC8224.
|
|
</para>
|
|
</enum>
|
|
<enum name="return_reason">
|
|
<para>If set to <literal>return_reason</literal>, continue to the
|
|
dialplan but add a <literal>Reason</literal> header to the sender in
|
|
the next provisional response.</para>
|
|
</enum>
|
|
</enumlist>
|
|
</description>
|
|
</configOption>
|
|
<configOption name="use_rfc9410_responses" default="no">
|
|
<synopsis>RFC9410 uses the STIR protocol on Reason headers
|
|
instead of the SIP protocol</synopsis>
|
|
</configOption>
|
|
<configOption name="relax_x5u_port_scheme_restrictions" default="no">
|
|
<synopsis>Relaxes check for "https" and port 443 or 8443
|
|
in incoming Identity header x5u URLs.</synopsis>
|
|
</configOption>
|
|
<configOption name="relax_x5u_path_restrictions" default="no">
|
|
<synopsis>Relaxes check for query parameters, user/password, etc.
|
|
in incoming Identity header x5u URLs.</synopsis>
|
|
</configOption>
|
|
<configOption name="x5u_acl" default="">
|
|
<synopsis>An existing ACL from acl.conf to use when checking
|
|
hostnames in incoming Identity header x5u URLs.</synopsis>
|
|
</configOption>
|
|
<configOption name="x5u_permit" default="">
|
|
<synopsis>An IP or subnet to permit when checking
|
|
hostnames in incoming Identity header x5u URLs.</synopsis>
|
|
</configOption>
|
|
<configOption name="x5u_deny" default="">
|
|
<synopsis>An IP or subnet to deny checking
|
|
hostnames in incoming Identity header x5u URLs.</synopsis>
|
|
</configOption>
|
|
<configOption name="check_tn_cert_public_url" default="false">
|
|
<synopsis>On load, Retrieve all TN's certificates and validate their dates</synopsis>
|
|
</configOption>
|
|
<configOption name="private_key_file" default="">
|
|
<synopsis>File path to a certificate</synopsis>
|
|
</configOption>
|
|
<configOption name="public_cert_url" default="">
|
|
<synopsis>URL to the public certificate</synopsis>
|
|
<description><para>
|
|
Must be a valid http, or https, URL.
|
|
</para></description>
|
|
</configOption>
|
|
<configOption name="attest_level">
|
|
<synopsis>Attestation level</synopsis>
|
|
</configOption>
|
|
<configOption name="send_mky" default="no">
|
|
<synopsis>Send a media key (mky) grant in the attestation for DTLS calls.
|
|
(not common)</synopsis>
|
|
</configOption>
|
|
</configObject>
|
|
</configFile>
|
|
</configInfo>
|
|
<function name="STIR_SHAKEN" language="en_US">
|
|
<synopsis>
|
|
Gets the number of STIR/SHAKEN results or a specific STIR/SHAKEN value from a result on the channel.
|
|
</synopsis>
|
|
<syntax>
|
|
<parameter name="index" required="true">
|
|
<para>The index of the STIR/SHAKEN result to get. If only 'count' is passed in, gets the number of STIR/SHAKEN results instead.</para>
|
|
</parameter>
|
|
<parameter name="value" required="false">
|
|
<para>The value to get from the STIR/SHAKEN result. Only used when an index is passed in (instead of 'count'). Allowable values:</para>
|
|
<enumlist>
|
|
<enum name = "identity" />
|
|
<enum name = "attestation" />
|
|
<enum name = "verify_result" />
|
|
</enumlist>
|
|
</parameter>
|
|
</syntax>
|
|
<description>
|
|
<para>This function will either return the number of STIR/SHAKEN identities, or return information on the specified identity.
|
|
To get the number of identities, just pass 'count' as the only parameter to the function. If you want to get information on a
|
|
specific STIR/SHAKEN identity, you can get the number of identities and then pass an index as the first parameter and one of
|
|
the values you would like to retrieve as the second parameter.
|
|
</para>
|
|
<example title="Get count and retrieve value">
|
|
same => n,NoOp(Number of STIR/SHAKEN identities: ${STIR_SHAKEN(count)})
|
|
same => n,NoOp(Identity ${STIR_SHAKEN(0, identity)} has attestation level ${STIR_SHAKEN(0, attestation)})
|
|
</example>
|
|
</description>
|
|
</function>
|
|
</docs> |