Stir/Shaken Refactor
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.
2023-10-26 16:27:35 +00:00
|
|
|
;--
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
|
|
-- 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_path = /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
|
|
|
|
|
|
|
|
;--
|
|
|
|
=======================================================================
|
|
|
|
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_path = /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 single file containing a CA certificate or certificate chain
|
|
|
|
to be used to validate the certificates in incoming requests.
|
|
|
|
|
|
|
|
Default: none
|
|
|
|
|
|
|
|
-- ca_path -----------------------------------------------------------
|
|
|
|
Path to a directory containing one or more CA certificates to be used
|
|
|
|
to validate the certificates in incoming requests. The files in that
|
|
|
|
directory must contain only one certificate each and the directory
|
|
|
|
must be hashed using the OpenSSL 'c_rehash' utility.
|
|
|
|
|
|
|
|
Default: none
|
|
|
|
|
|
|
|
NOTE: Both ca_file and ca_path can be specified but at least one
|
|
|
|
MUST be.
|
|
|
|
|
|
|
|
-- crl_file -----------------------------------------------------------
|
|
|
|
Path to a single file containing a CA certificate revocation list
|
|
|
|
to be used to validate the certificates in incoming requests.
|
|
|
|
|
|
|
|
Default: none
|
|
|
|
|
|
|
|
-- crl_path -----------------------------------------------------------
|
|
|
|
Path to a directory containing one or more CA certificate revocation
|
|
|
|
lists to be used to validate the certificates in incoming requests.
|
|
|
|
The files in that directory must contain only one certificate each and
|
|
|
|
the directory must be hashed using the OpenSSL 'c_rehash' utility.
|
|
|
|
|
|
|
|
Default: none
|
|
|
|
|
|
|
|
NOTE: Neither crl_file nor crl_path are required.
|
|
|
|
|
|
|
|
-- 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
|
|
|
|
|
|
|
|
-- 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_behhavior--------------------------------------------------
|
|
|
|
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]
|
2022-02-28 17:19:54 +00:00
|
|
|
;permit=0.0.0.0/0.0.0.0
|
Stir/Shaken Refactor
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.
2023-10-26 16:27:35 +00:00
|
|
|
;deny=10.24.20.171
|
|
|
|
|