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: #351Resolves: #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.
Put checks in place to limit how much we will actually download, as well
as a check for the data we receive at the start to ensure it begins with
what we would expect a certificate to begin with.
ASTERISK-29872
Change-Id: Ifd3c6b8bd52b8b6192a04166ccce4fc8a8000b46
During OpenSIPit, we found out that the public certificates must be of
type X.509. When reading in public keys, we use the corresponding X.509
functions now.
We also discovered that we needed a better naming scheme for the
certificates since certificates with the same name would cause issues
(overwriting certs, etc.). Now when we download a public certificate, we
get the serial number from it and use that as the name of the cached
certificate.
The configuration option public_key_url in stir_shaken.conf has also
been renamed to public_cert_url, which better describes what the option
is for.
https://wiki.asterisk.org/wiki/display/AST/OpenSIPit+2021
Change-Id: Ia00b20835f5f976e3603797f2f2fb19672d8114d
There are a lot of moving parts in this patch, but the focus of it is on
the verification of the signature using a public key located at the
public key URL provided in the JSON payload. First, we check the
database to see if we have already downloaded the key. If so, check to
see if it has expired. If it has, redownload from the URL. If we don't
have an entry in the database, just go ahead and download the public
key. The expiration is tested each time we download the file. After
that, read the public key from the file and use it to verify the
signature. All sanity checking is done when the payload is first
received, so the verification is complete once this point is reached.
The XML has also been added since a new config option was added to
general (curl_timeout). The maximum amount of time to wait for a
download can be configured through this option, with a low value by
default.
Change-Id: I3ba4c63880493bf8c7d17a9cfca1af0e934d1a1c
This commit sets up some of the initial framework for the module and
adds a way to read the private key from the specified file, which will
then be appended to the certificate object. This works fine for now, but
eventually some other structure will likely need to be used to store all
this information. Similarly, the caller_id_number is specified on the
certificate config object, but in the end we will want that information
to be tied to the certificate itself and read it from there.
A method has been added that will retrieve the private key associated
with the caller_id_number passed in. Tab completion for certificates and
stores has also been added.
Change-Id: Ic4bc1416fab5d6afe15a8e2d32f7ddd4e023295f
George Joseph
Ben Ford