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