mirror of
https://github.com/asterisk/asterisk.git
synced 2025-09-03 03:20:57 +00:00
1ccf0ae7e8
Most of the configObjects and configOptions that are implemented with
ACO or Sorcery now have `<since>/<version>` elements added. There are
probably some that the script I used didn't catch. The version tags were
determined by the following...
* Do a git blame on the API call that created the object or option.
* From the commit hash, grab the summary line.
* Do a `git log --grep <summary>` to find the cherry-pick commits in all
branches that match.
* Do a `git patch-id` to ensure the commits are all related and didn't get
a false match on the summary.
* Do a `git tag --contains <commit>` to find the tags that contain each
commit.
* Weed out all tags not <major>.<minor>.0.
* Sort and discard any <major>.0.0 and following tags where the commit
appeared in an earlier branch.
* The result is a single tag for each branch where the API was last touched.
configObjects and configOptions elements implemented with the base
ast_config APIs were just not possible to find due to the non-deterministic
way they are accessed.
Also note that if the API call was on modified after it was added, the
version will be the one it was last modified in.
Final note: The configObject and configOption elements were introduced in
12.0.0 so options created before then may not have any XML documentation.
(cherry picked from commit a22dc33057)
336 lines
21 KiB
XML
336 lines
21 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">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>STIR/SHAKEN attestation options</synopsis>
|
|
<configOption name="global_disable" default="false">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>Globally disable verification</synopsis>
|
|
</configOption>
|
|
<configOption name="private_key_file" default="">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>File path to a certificate</synopsis>
|
|
</configOption>
|
|
<configOption name="public_cert_url" default="">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>URL to the public certificate</synopsis>
|
|
<description><para>
|
|
Must be a valid http, or https, URL.
|
|
</para></description>
|
|
</configOption>
|
|
<configOption name="attest_level">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>Attestation level</synopsis>
|
|
</configOption>
|
|
<configOption name="unknown_tn_attest_level">
|
|
<since><version>20.12.0</version><version>21.7.0</version><version>22.2.0</version></since>
|
|
<synopsis>Attestation level to use for unknown TNs</synopsis>
|
|
<description><para>
|
|
Normally if a callerid TN isn't configured in stir_shaken.conf
|
|
no Identity header will be created. If this option is set,
|
|
however, an Identity header will be sent using this
|
|
attestation level. Since there's no TN object, you must
|
|
ensure that a private_key_file and public_cert_url are
|
|
configured in the attestation or profile objects for
|
|
this to work.
|
|
</para></description>
|
|
</configOption>
|
|
<configOption name="check_tn_cert_public_url" default="false">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>On load, Retrieve all TN's certificates and validate their dates</synopsis>
|
|
</configOption>
|
|
<configOption name="send_mky" default="no">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>Send a media key (mky) grant in the attestation for DTLS calls.
|
|
(not common)</synopsis>
|
|
</configOption>
|
|
</configObject>
|
|
<configObject name="tn">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>STIR/SHAKEN TN options</synopsis>
|
|
<configOption name="type">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>Must be of type 'tn'.</synopsis>
|
|
</configOption>
|
|
<configOption name="private_key_file" default="">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>File path to a certificate</synopsis>
|
|
</configOption>
|
|
<configOption name="public_cert_url" default="">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>URL to the public certificate</synopsis>
|
|
<description><para>
|
|
Must be a valid http, or https, URL.
|
|
</para></description>
|
|
</configOption>
|
|
<configOption name="attest_level">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>Attestation level</synopsis>
|
|
</configOption>
|
|
<configOption name="check_tn_cert_public_url" default="false">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>On load, Retrieve all TN's certificates and validate their dates</synopsis>
|
|
</configOption>
|
|
<configOption name="send_mky" default="no">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>Send a media key (mky) grant in the attestation for DTLS calls.
|
|
(not common)</synopsis>
|
|
</configOption>
|
|
</configObject>
|
|
<configObject name="verification">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>STIR/SHAKEN verification options</synopsis>
|
|
<configOption name="global_disable" default="false">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>Globally disable verification</synopsis>
|
|
</configOption>
|
|
<configOption name="load_system_certs" default="">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>A boolean indicating whether trusted CA certificates should be loaded from the system</synopsis>
|
|
</configOption>
|
|
<configOption name="ca_file" default="">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>Path to a file containing one or more CA certs in PEM format</synopsis>
|
|
<description>
|
|
<para>These certs are used to verify the chain of trust for the
|
|
certificate retrieved from the X5U Identity header parameter. This
|
|
file must have the root CA certificate, the certificate of the
|
|
issuer of the X5U certificate, and any intermediate certificates
|
|
between them.</para>
|
|
<para>
|
|
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
|
|
</para>
|
|
</description>
|
|
</configOption>
|
|
<configOption name="ca_path" default="">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>Path to a directory containing one or more hashed CA certs</synopsis>
|
|
<description>
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='ca_file']/description/node())" />
|
|
<para>For this option, the individual certificates must be placed in
|
|
the directory specified and hashed using the <literal>openssl rehash</literal>
|
|
command.</para>
|
|
<para>
|
|
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
|
|
</para>
|
|
</description>
|
|
</configOption>
|
|
<configOption name="crl_file" default="">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>Path to a file containing one or more CRLs in PEM format</synopsis>
|
|
<description>
|
|
<para>If you with to check if the certificate in the X5U Identity header
|
|
parameter has been revoked, you'll need the certificate revocation
|
|
list generated by the issuer.</para>
|
|
<para>
|
|
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
|
|
</para>
|
|
</description>
|
|
</configOption>
|
|
<configOption name="crl_path" default="">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>Path to a directory containing one or more hashed CRLs</synopsis>
|
|
<description>
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='crl_file']/description/node())" />
|
|
<para>For this option, the individual CRLs must be placed in
|
|
the directory specified and hashed using the <literal>openssl rehash</literal>
|
|
command.</para>
|
|
<para>
|
|
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
|
|
</para>
|
|
</description>
|
|
</configOption>
|
|
<configOption name="untrusted_cert_file" default="">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>Path to a file containing one or more untrusted cert in PEM format used to verify CRLs</synopsis>
|
|
<description>
|
|
<para>If you with to check if the certificate in the X5U Identity header
|
|
parameter has been revoked, you'll need the certificate revocation
|
|
list generated by the issuer. Unfortunately, sometimes the CRLs are signed by a
|
|
different CA than the certificate being verified. In this case, you
|
|
may need to provide the untrusted certificate to verify the CRL.</para>
|
|
<para>
|
|
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
|
|
</para>
|
|
</description>
|
|
</configOption>
|
|
<configOption name="untrusted_cert_path" default="">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>Path to a directory containing one or more hashed untrusted certs used to verify CRLs</synopsis>
|
|
<description>
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='untrusted_cert_file']/description/node())" />
|
|
<para>For this option, the individual certificates must be placed in
|
|
the directory specified and hashed using the <literal>openssl rehash</literal>
|
|
command.</para>
|
|
<para>
|
|
See https://docs.asterisk.org/Deployment/STIR-SHAKEN/ for more information.
|
|
</para>
|
|
</description>
|
|
</configOption>
|
|
<configOption name="cert_cache_dir" default="">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>Directory to cache retrieved verification certs</synopsis>
|
|
</configOption>
|
|
<configOption name="curl_timeout" default="2">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>Maximum time to wait to CURL certificates</synopsis>
|
|
</configOption>
|
|
<configOption name="max_cache_entry_age" default="60">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>Number of seconds a cache entry may be behind current time</synopsis>
|
|
</configOption>
|
|
<configOption name="max_cache_size" default="1000">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>Maximum size to use for caching public keys</synopsis>
|
|
</configOption>
|
|
<configOption name="max_iat_age" default="15">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>Number of seconds an iat grant may be behind current time</synopsis>
|
|
</configOption>
|
|
<configOption name="max_date_header_age" default="15">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>Number of seconds a SIP Date header may be behind current time</synopsis>
|
|
</configOption>
|
|
<configOption name="failure_action" default="continue">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<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">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<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">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<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">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>Relaxes check for query parameters, user/password, etc.
|
|
in incoming Identity header x5u URLs.</synopsis>
|
|
</configOption>
|
|
<configOption name="x5u_acl" default="">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<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="">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>An IP or subnet to permit when checking
|
|
hostnames in incoming Identity header x5u URLs.</synopsis>
|
|
</configOption>
|
|
<configOption name="x5u_deny" default="">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>An IP or subnet to deny checking
|
|
hostnames in incoming Identity header x5u URLs.</synopsis>
|
|
</configOption>
|
|
</configObject>
|
|
<configObject name="profile">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>STIR/SHAKEN profile configuration options</synopsis>
|
|
<configOption name="type">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<synopsis>Must be of type 'profile'.</synopsis>
|
|
</configOption>
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='load_system_certs'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='ca_file'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='ca_path'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='crl_file'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='crl_path'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='untrusted_cert_file'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='untrusted_cert_path'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='cert_cache_dir'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='curl_timeout'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='max_iat_age'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='max_date_header_age'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='max_cache_entry_age'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='max_cache_size'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='failure_action'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='use_rfc9410_responses'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='relax_x5u_port_scheme_restrictions'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='relax_x5u_path_restrictions'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='x5u_acl'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='x5u_permit'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='verification']/configOption[@name='x5u_deny'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='attestation']/configOption[@name='check_tn_cert_public_url'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='attestation']/configOption[@name='private_key_file'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='attestation']/configOption[@name='public_cert_url'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='attestation']/configOption[@name='attest_level'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='attestation']/configOption[@name='unknown_tn_attest_level'])" />
|
|
<xi:include xpointer="xpointer(/docs/configInfo[@name='res_stir_shaken']/configFile[@name='stir_shaken.conf']/configObject[@name='attestation']/configOption[@name='send_mky'])" />
|
|
<configOption name="endpoint_behavior" default="off">
|
|
<since><version>18.22.0</version><version>20.7.0</version><version>21.2.0</version></since>
|
|
<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>
|
|
</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> |