mirror of
https://github.com/asterisk/asterisk.git
synced 2025-09-02 11:06:31 +00:00
c5734b4ae6
Added a new option "unknown_tn_attest_level" to allow Identity
headers to be sent when a callerid TN isn't explicitly configured
in stir_shaken.conf. Since there's no TN object, a private_key_file
and public_cert_url must be configured in the attestation or profile
objects.
Since "unknown_tn_attest_level" uses the same enum as attest_level,
some of the sorcery macros had to be refactored to allow sharing
the enum and to/from string conversion functions.
Also fixed a memory leak in crypto_utils:pem_file_cb().
Resolves: #921
UserNote: You can now set the "unknown_tn_attest_level" option
in the attestation and/or profile objects in stir_shaken.conf to
enable sending Identity headers for callerid TNs not explicitly
configured.
(cherry picked from commit 90cf13acd8)
296 lines
17 KiB
XML
296 lines
17 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="unknown_tn_attest_level">
|
|
<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">
|
|
<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 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="">
|
|
<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="">
|
|
<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="">
|
|
<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="">
|
|
<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="">
|
|
<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="">
|
|
<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>
|
|
<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">
|
|
<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> |