mirror of https://github.com/asterisk/asterisk
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
517 lines
19 KiB
517 lines
19 KiB
;--
|
|
|
|
There are 4 object types used by the STIR/SHAKEN process...
|
|
|
|
The "attestation" object sets the parameters for creating an Identity
|
|
header which attests to the ownership of the caller id on outgoing
|
|
INVITE requests.
|
|
|
|
One or more "tn" objects that are used to create the outgoing Identity
|
|
header. Each object's "id" is a specific caller-id telephone number
|
|
and the object contains the URL to the certificate that was used to
|
|
attest to the ownership of the caller-id, the level (A,B,C) of the
|
|
attestation you're making, and the private key the asterisk
|
|
attestation service will use to sign the Identity header. When
|
|
an outgoing INVITE request is placed, the attestation service will
|
|
look up the caller-id in the tn object list and if it's found, use
|
|
the information in the object to create the Identity header.
|
|
|
|
The "verification" object sets the parameters for verification
|
|
of the Identity header and caller id on incoming INVITE requests.
|
|
|
|
One or more "profile" objects that can be associated to channel
|
|
driver endpoints (currently only chan_pjsip). Profiles can set
|
|
whether verification, attestation, both or neither should be
|
|
performed on requests coming in to this endpoint or requests
|
|
going out from this endpoint. Additionally they can override
|
|
most of the attestation and verification options to make them
|
|
specific to an endpoint. When Asterisk loads the configs, it
|
|
creates "effective profiles" or "eprofiles" on the fly that are
|
|
the amalgamation of the attestation, verification and profile.
|
|
You can see them in the CLI with "stir_shaken show eprofiles".
|
|
|
|
NOTE: The "tn" object can be configured to source its data from a
|
|
realtime database by configuring sorcery.conf and extconfig.conf.
|
|
Both of those files have examples for "stir_tn". There is also an
|
|
Alembic script in the "config" section of contrib/ast-db-manage that
|
|
will create the table. Since there can be only one "verification"
|
|
or "attestation" object, and will probably be only a few "profile"
|
|
objects, those objects aren't realtime enabled.
|
|
|
|
--;
|
|
|
|
;--
|
|
=======================================================================
|
|
Attestation Object Description
|
|
=======================================================================
|
|
The "attestation" object sets the parameters for creating an Identity
|
|
header which attests to the ownership of the caller id on outgoing
|
|
INVITE requests.
|
|
|
|
All parameters except 'global_disable" may be overridden in a "profile"
|
|
or "tn" object.
|
|
|
|
Only one "attestation" object may exist.
|
|
|
|
Parameters:
|
|
|
|
-- global_disable -----------------------------------------------------
|
|
If set, globally disables the attestation service. No Identity headers
|
|
will be added to any outgoing INVITE requests.
|
|
|
|
Default: no
|
|
|
|
-- private_key_file ---------------------------------------------------
|
|
The path to a file containing the private key you received from the
|
|
issuing authority. The file must NOT be group or world readable or
|
|
writable so make sure the user the asterisk process is running as is
|
|
the owner.
|
|
|
|
Default: none
|
|
|
|
-- public_cert_url ----------------------------------------------------
|
|
The URL to the certificate you received from the issueing authority.
|
|
They may give you a URL to use or you may have to host the certificate
|
|
yourself and provide your own URL here.
|
|
|
|
Default: none
|
|
|
|
WARNING: Make absolutely sure the file that's made public doesn't
|
|
accidentally include the privite key as well as the certificate.
|
|
If you set "check_tn_cert_public_url" in the "attestation" section
|
|
above, the tn will not be loaded and a "DANGER" message will be output
|
|
on the asterisk console if the file does contain a private key.
|
|
|
|
-- check_tn_cert_public_url -------------------------------------------
|
|
Identity headers in outgoing requests must contain a URL that points
|
|
to the certificate used to sign the header. Setting this parameter
|
|
tells Asterisk to actually try to retrieve the certificates indicated
|
|
by "public_cert_url" parameters and fail loading that tn if the cert
|
|
can't be retrieved or if its 'Not Valid Before" -> 'Not Valid After"
|
|
date range doesn't include today. This is a network intensive process
|
|
so use with caution.
|
|
|
|
Default: no
|
|
|
|
-- attest_level -------------------------------------------------------
|
|
The level of the attestation you're making.
|
|
One of "A", "B", "C"
|
|
|
|
Default: none
|
|
|
|
-- unknown_tn_attest_level --------------------------------------------
|
|
Attestation level to use for unknown TNs.
|
|
One of "A", "B", "C"
|
|
|
|
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.
|
|
|
|
Default: none
|
|
|
|
-- send_mky -----------------------------------------------------------
|
|
If set and an outgoing call uses DTLS, an "mky" Media Key grant will
|
|
be added to the Identity header. Although RFC8224/8225 require this,
|
|
not many implementations support it so a remote verification service
|
|
may fail to verify the signature.
|
|
|
|
Default: no
|
|
|
|
-----------------------------------------------------------------------
|
|
Example "attestation" object:
|
|
--;
|
|
|
|
;[attestation]
|
|
;global_disable = no
|
|
;private_key_file = /var/lib/asterisk/keys/stir_shaken/tns/multi-tns-key.pem
|
|
;public_cert_url = https://example.com/tncerts/multi-tns-cert.pem
|
|
;attest_level = C
|
|
;unknown_tn_attest_level = C
|
|
|
|
;--
|
|
=======================================================================
|
|
TN Object Description
|
|
=======================================================================
|
|
Each "tn" object contains the parameters needed to create the Identity
|
|
header used to attest to the ownership of the caller-id on outgoing
|
|
requests. When an outgoing INVITE request is placed, the attestation
|
|
service will look up the caller-id in this list and if it's found, use
|
|
the information in the object to create the Identity header.
|
|
The private key and certificate needed to sign the Identity header are
|
|
usually provided to you by the telephone number issuing authority along
|
|
with their certificate authority certificate. You should give the CA
|
|
certificate to any recipients who expect to receive calls from you
|
|
although this has probably already been done by the issuing authority.
|
|
|
|
The "id" of this object MUST be a canonicalized telephone number which
|
|
starts with a country code. The only valid characters are the numbers
|
|
0-9, '#' and '*'.
|
|
|
|
Parameters:
|
|
|
|
-- type (required) ----------------------------------------------------
|
|
Must be set to "tn"
|
|
|
|
Default: none
|
|
|
|
-- private_key_file ---------------------------------------------------
|
|
The path to a file containing the private key you received from the
|
|
issuing authority. The file must NOT be group or world readable or
|
|
writable so make sure the user the asterisk process is running as is
|
|
the owner.
|
|
|
|
Default: private_key_file from the profile or attestation objects.
|
|
|
|
-- public_cert_url ----------------------------------------------------
|
|
The URL to the certificate you received from the issueing authority.
|
|
They may give you a URL to use or you may have to host the certificate
|
|
yourself and provide your own URL here.
|
|
|
|
Default: public_cert_url from the profile or attestation objects.
|
|
|
|
WARNING: Make absolutely sure the file that's made public doesn't
|
|
accidentally include the privite key as well as the certificate.
|
|
If you set "check_tn_cert_public_url" in the "attestation" section
|
|
above, the tn will not be loaded and a "DANGER" message will be output
|
|
on the asterisk console if the file does contain a private key.
|
|
|
|
-- attest_level -------------------------------------------------------
|
|
The level of the attestation you're making.
|
|
One of "A", "B", "C"
|
|
|
|
Default: attest_level from the profile or attestation objects.
|
|
|
|
-----------------------------------------------------------------------
|
|
Example "tn" object:
|
|
--;
|
|
|
|
;[18005551515]
|
|
;type = tn
|
|
;private_key_file = /var/lib/asterisk/keys/stir_shaken/tns/18005551515-key.pem
|
|
;public_cert_url = https://example.com/tncerts/18005551515-cert.pem
|
|
;attest_level = C
|
|
|
|
;--
|
|
=======================================================================
|
|
Verification Object Description
|
|
=======================================================================
|
|
The "verification" object sets the parameters for verification
|
|
of the Identity header on incoming INVITE requests.
|
|
|
|
All parameters except 'global_disable" may be overridden in a "profile"
|
|
object.
|
|
|
|
Only one "verification" object may exist.
|
|
|
|
Parameters:
|
|
|
|
-- global_disable -----------------------------------------------------
|
|
If set, globally disables the verification service.
|
|
|
|
Default: no
|
|
|
|
-- load_system_certs---------------------------------------------------
|
|
If set, loads the system Certificate Authority certificates
|
|
(usually located in /etc/pki/CA) into the trust store used to
|
|
validate the certificates in incoming requests. This is not
|
|
normally required as service providers will usually provide their
|
|
CA certififcate to you separately.
|
|
|
|
Default: no
|
|
|
|
-- ca_file -----------------------------------------------------------
|
|
Path to a file containing one or more CA certs in PEM format.
|
|
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.
|
|
|
|
Default: none
|
|
|
|
-- ca_path -----------------------------------------------------------
|
|
Path to a directory containing one or more hashed CA certs.
|
|
See ca_file above.
|
|
For this option, each certificate must be placed in its own
|
|
PEM file in the directory specified and hashed with the
|
|
following command:
|
|
`openssl rehash <ca_path>`
|
|
|
|
Default: none
|
|
|
|
NOTE: Both ca_file and ca_path can be specified but at least one
|
|
MUST be.
|
|
|
|
-- crl_file -----------------------------------------------------------
|
|
Path to a file containing one or more CRLs in PEM format.
|
|
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.
|
|
|
|
Default: none
|
|
|
|
-- crl_path -----------------------------------------------------------
|
|
Path to a directory containing one or more hashed CRLs.
|
|
See crl_file above.
|
|
For this option, each CRL must be placed in its own
|
|
PEM file in the directory specified and hashed with the
|
|
following command:
|
|
`openssl rehash <crl_path>`
|
|
|
|
Default: none
|
|
|
|
NOTE: Neither crl_file nor crl_path are required.
|
|
|
|
-- untrusted_cert_file ------------------------------------------------
|
|
Path to a file containing one or more untrusted certs in PEM format.
|
|
Unfortunately, sometimes the CRLs are signed by a different CA
|
|
than the certificate being verified. In this case, you'll need to
|
|
provide the certificate belonging to the issuer of the CRL. That
|
|
certificate is considered "untrusted" by OpenSSL and can't be placed
|
|
in the ca_file or ca_path. It has to be specified here.
|
|
|
|
Default: none
|
|
|
|
-- untrusted_cert_path ------------------------------------------------
|
|
Path to a directory containing one or more hashed untrusted certs used
|
|
to verify CRLs.
|
|
See untrusted_cert_file above.
|
|
For this option, each certificates must be placed in its own
|
|
PEM file in the directory specified and hashed with the
|
|
following command:
|
|
`openssl rehash <ca_path>`
|
|
|
|
Default: none
|
|
|
|
NOTE: Neither untrusted_cert_file nor untrusted_cert_path are required
|
|
unless you're verifying CRLs that aren't signed by the same CA as the
|
|
X5U certificate.
|
|
|
|
-- cert_cache_dir -----------------------------------------------------
|
|
Incoming Identity headers will have a URL pointing to the certificate
|
|
used to sign the header. To prevent us from having to retrieve the
|
|
certificate for every request, we maintain a cache of them in the
|
|
'cert_cache_dir' specified. The directory will be checked for
|
|
existence and writability at startup.
|
|
|
|
Default: <astvarlibdir>/keys/stir_shaken/cache
|
|
|
|
-- curl_timeout -------------------------------------------------------
|
|
The number of seconds we'll wait for a response when trying to retrieve
|
|
the certificate specified in the incoming Identity header's "x5u"
|
|
parameter.
|
|
|
|
Default: 2
|
|
|
|
-- max_cache_entry_age ------------------------------------------------
|
|
Maximum age in seconds a certificate in the cache can reach before
|
|
re-retrieving it.
|
|
|
|
Default: 86400 (24 hours per ATIS-1000074)
|
|
|
|
NOTE: If, when retrieving the URL specified by the "x5u" parameter,
|
|
we receive a recognized caching directive in the HTTP response AND that
|
|
directive indicates caching for MORE than the value set here, we'll use
|
|
that time for the max_cache_entry_age.
|
|
|
|
-- max_cache_size -----------------------------------------------------
|
|
Maximum number of entries the cache can hold.
|
|
Not presently implemented.
|
|
|
|
-- max_iat_age --------------------------------------------------------
|
|
The "iat" parameter in the Identity header indicates the time the
|
|
sender actually created their attestation. If that is older than the
|
|
current time by the number of seconds set here, the request will be
|
|
considered "failed".
|
|
|
|
Default: 15
|
|
|
|
-- ignore_sip_date_header ---------------------------------------------
|
|
When set to true, will cause the verification process to not consider a
|
|
missing or invalid SIP "Date" header to be a failure. This will make
|
|
the IAT the sole "truth" for Date in the verification process.
|
|
|
|
Default: no
|
|
|
|
-- max_date_header_age ------------------------------------------------
|
|
The sender MUST also send a SIP Date header in their request. If we
|
|
receive one that is older than the current time by the number of seconds
|
|
set here, the request will be considered "failed".
|
|
|
|
Default: 15
|
|
|
|
-- failure_action -----------------------------------------------------
|
|
Indicates what will happen to requests that have failed verification.
|
|
Must be one of:
|
|
- continue -
|
|
Continue processing the request. You can use the STIR_SHAKEN
|
|
dialplan function to determine whether the request passed or failed
|
|
verification and take the action you deem appropriate.
|
|
|
|
- reject_request -
|
|
Reject the request immediately using the SIP response codes
|
|
defined by RFC8224.
|
|
|
|
- continue_return_reason -
|
|
Continue processing the request but, per RFC8224, send a SIP Reason
|
|
header back to the originator in the next provisional response
|
|
indicating the issue according to RFC8224. You can use the
|
|
STIR_SHAKEN dialplan function to determine whether the request
|
|
passed or failed verification and take the action you deem
|
|
appropriate.
|
|
|
|
Default: continue
|
|
|
|
NOTE: If you select "continue" or "continue_return_reason", and,
|
|
based on the results from the STIR_SHAKEN function, you determine you
|
|
want to terminate the call, you can use the PJSIPHangup() dialplan
|
|
application to reject the call using a STIR/SHAKEN-specific SIP
|
|
response code.
|
|
|
|
-- use_rfc9410_responses ----------------------------------------------
|
|
If set, when sending Reason headers back to originators, the protocol
|
|
header parameter will be set to "STIR" rather than "SIP". This is a
|
|
new protocol defined in RFC9410 and may not be supported by all
|
|
participants.
|
|
|
|
Default: no
|
|
|
|
-- relax_x5u_port_scheme_restrictions ---------------------------------
|
|
If set, the port and scheme restrictions imposed by ATIS-1000074
|
|
section 5.3.1 that require the scheme to be "https" and the port to
|
|
be 443 or 8443 are relaxed. This will allow schemes like "http"
|
|
and ports other than the two mentioned to appear in x5u URLs received
|
|
in Identity headers.
|
|
|
|
Default: no
|
|
|
|
CAUTION: Setting this parameter could have serious security
|
|
implications and should only be use for testing.
|
|
|
|
-- relax_x5u_path_restrictions ----------------------------------------
|
|
If set, the path restrictions imposed by ATIS-1000074 section 5.3.1
|
|
that require the x5u URL to be rejected if it contains a query string,
|
|
path parameters, fragment identifier or user/password are relaxed.
|
|
|
|
Default: no
|
|
|
|
CAUTION: Setting this parameter could have serious security
|
|
implications and should only be use for testing.
|
|
|
|
-- x5u_permit/x5u_deny ------------------------------------------------
|
|
When set, the IP address of the host in a received Identity header x5u
|
|
URL is checked against the acl created by this list of permit/deny
|
|
parameters. If the check fails, the x5u URL will be considered invalid
|
|
and verification will fail. This can prevent an attacker from sending
|
|
you a request pretending to be a known originator with a mailcious
|
|
certificate URL. (Server-side request forgery (SSRF)).
|
|
See acl.conf.sample to see examples of how to specify the permit/deny
|
|
parameters.
|
|
|
|
Default: Deny all "Special-Purpose" IP addresses described in RFC 6890.
|
|
This includes the loopback addresses 127.0.0.0/8, private use networks such
|
|
as 10.0.0/8, 172.16.0.0/12 and 192.168.0.0/16, and the link local network
|
|
169.254.0.0/16 among others.
|
|
|
|
CAUTION: Setting this parameter could have serious security
|
|
implications and should only be use for testing.
|
|
|
|
-- x5u_acl ------------------------------------------------------------
|
|
Rather than providing individual permit/deny parameters, you can set
|
|
the acllist parameter to an acl list predefined in acl.conf.
|
|
|
|
Default: none
|
|
|
|
CAUTION: Setting this parameter could have serious security
|
|
implications and should only be use for testing.
|
|
|
|
-----------------------------------------------------------------------
|
|
Example "verification" object:
|
|
--;
|
|
|
|
;[verification]
|
|
;global_disable = yes
|
|
;load_system_certs = no
|
|
;ca_path = /var/lib/asterisk/keys/stir_shaken/verification_ca
|
|
;cert_cache_dir = /var/lib/asterisk/keys/stir_shaken/verification_cache
|
|
;failure_action = reject_request
|
|
;curl_timeout=5
|
|
;max_iat_age=60
|
|
;max_date_header_age=60
|
|
;max_cache_entry_age = 300
|
|
; For internal testing
|
|
;x5u_deny=0.0.0.0/0.0.0.0
|
|
;x5u_permit=127.0.0.0/8
|
|
;x5u_permit=192.168.100.0/24
|
|
;relax_x5u_port_scheme_restrictions = yes
|
|
;relax_x5u_path_restrictions = yes
|
|
|
|
;--
|
|
=======================================================================
|
|
Profile Object Description
|
|
=======================================================================
|
|
A "profile" object can be associated to channel driver endpoint
|
|
(currently only chan_pjsip) and can set verification and attestation
|
|
parameters specific to endpoints using this profile. If you have
|
|
multiple upstream providers, this is the place to set parameters
|
|
specific to them.
|
|
|
|
The "id" of this object is arbitrary and you'd specify it in the
|
|
"stir_shaken_profile" parameter of the endpoint.
|
|
|
|
Parameters:
|
|
|
|
-- type (required) ----------------------------------------------------
|
|
Must be set to "profile"
|
|
|
|
Default: none
|
|
|
|
-- endpoint_behavior--------------------------------------------------
|
|
Actions to be performed for endpoints referencing this profile.
|
|
Must be one of:
|
|
- off -
|
|
Don't do any STIR/SHAKEN processing.
|
|
- attest -
|
|
Attest on outgoing calls.
|
|
- verify
|
|
Verify incoming calls.
|
|
- on -
|
|
Attest outgoing calls and verify incoming calls.
|
|
Default: off
|
|
|
|
All of the "verification" parameters defined above can be set on a profile
|
|
with the exception of 'global_disable'.
|
|
|
|
All of the "attestation" parameters defined above can be set on a profile
|
|
with the exception of 'global_disable'.
|
|
|
|
When Asterisk loads the configs, it creates "effective profiles" or
|
|
"eprofiles" on the fly that are the amalgamation of the attestation,
|
|
verification and profile. You can see them in the CLI with
|
|
"stir_shaken show eprofiles".
|
|
|
|
-----------------------------------------------------------------------
|
|
Example "profile" object:
|
|
--;
|
|
|
|
;[myprofile]
|
|
;type = profile
|
|
;endpoint_behavior = verify
|
|
;failure_action = continue_return_reason
|
|
;x5u_acl = myacllist
|
|
|
|
;In pjsip.conf...
|
|
;[myendpoint]
|
|
;type = endpoint
|
|
;stir_shaken_profile = myprofile
|
|
|
|
;In acl.conf...
|
|
;[myacllist]
|
|
;permit=0.0.0.0/0.0.0.0
|
|
;deny=10.24.20.171
|
|
|